Source code

Source code

The source code is the text which is loaded by the STx source code loader into a global environment and interpreted and executed by an instance of the STx command interpreter (called shell). A source file is a text file containing source code. By convention, source files end with the extension stx (for libraries packages and application) or sts (for scripts to be loaded and executed via BScript). Examples of scripts can be found in the directory scripts\examples in the S_TOOLS-STx installation directory. S_TOOLS-STx source files use a section file format, where each section starts with a section header. Each source section delineates a section of source code. The code runs from the header to the next header, or to the end of the file.

Section header

The section header defines the visibility, type and the name of the source code contained in the source section. The section header must be enclosed within square brackets, where the opening bracket must be the first character in the line and there must not be any text behind the closing bracket expect comments.

[{visiblity:}sstype ssname {ssargs}]

visibility

The visibilty of a section defines from where the source code object can be accessed, instantiated or called. The following visibility keywords are currently supported.

GLOBAL

The section code is visible everywhere. This is the default.

LOCAL

The section code is visible only for code inside the same source file. A local macro can only be called, and a local CLASS or SPU can only be instantiated from macros defined in the same source file.

MAIN

Defines the section code as the main macro of an STx application. A main macro must be called by the system macro AppMain. This keyword is defined for macro and class sections only, and should only be used for the main function of an STx application but not for scripts.

SHELL

Defines the section code as a shell startup code. This means, the macro implements the startup code of a command interpreter instance (shell) and can only be used in the shell. This keyword is defined for macro and class sections only.

MSGHANDLER

Defines a message handler macro, which can only be called from the system macros GetMessage or DispatchMsg.

sstype

Defines the type of source code in the section. The types macro, class and SPU are meaningful for the STx scripting language. Other types can also be used (e.g. to store data) and accessed via the SectionFile macro or directly with the file item functions. The section script processing application uses the special types libraries and scripts. If an unknown section type is detected by the loader, the section is ignored.

ssname

The name identifying this source code section. This is used to access the source code later on (e.g. to call a macro, to create an spu item, to create a instance item of a class, to derive a class, ...). . The name must be unique in the namespace where the source code is loaded, which is selected by the section type. Source sections of type macro and class are loaded into the same namespace. A separate namespace is used for SPU items.

ssargs

The meaning of this part of the header depends on the type of the source section.

The parameters sstype and ssname are mandatory for the types macro, class and SPU, whilst visibility and ssargs are optional and depending on sstype. All keywords, names and other parts of the header are not case-sensitive.

Examples:

[LOCAL:MACRO MacroExample1]
[MACRO MacroExample2 #args]
[SPU DSPCircuit1 #in1 #in2 OUT #out1]

Section body

The section body consists of statements (at least one is mandatory), empty lines (are ignored) and comments. The section body ends at the next section header or the end of the file.

comments

A comment is part of the source code which is used for documentation purposes and is ignored by the loader. A comment can be placed anywhere, where a whitespace character is allowed. The standard C++ comment tags can be used in S_TOOLS-STx source code.

line comment

starts with the tag // and ends at the end of the same line.

block comment

is opened with the tag /* and closed with the tag */. A block comment can be spanned over more than one line. If the begin and end tag of a block comment is on the same line, the comment is treated like a whitespace character, otherwise like a end of line.

Note that a comment open tag (// or /*) in a quoted string is interpreted as normal text and not as tag. Its also possible to escape one character of a comment tag (like: `//) to avoid its interpretation.

statements

A statement is the part of a line which remains after removing comments, and leading and trailing white space. In macros and classes, statements are label definitions, definitions of local functions or member functions and/or commands. In SPUs, the statements are used to define and connect the circuit elements.

Definition of Macros

Header

A macro is defined by one of the following section headers. The possible formats differ only in the type of argument parsing supplied before the first macro statement is executed. The optional visibility tag is omitted in this description, because it described in detail in the chapter section header.

[MACRO macroname]

No argument parsing. The argument parsing must be implemented in the macro body using the READVARand/or the ARG command.

important variables: #ARGV, #QARGV

[MACRO macroname {READ:} argname1{=defaultvalue1} {seperator1} ...]

READ-style argument parsing. The arguments are parsed as strings, using the READVAR command befor the first statement is executed. The programmer can select arbitrary argument seperators. If an argument value is specified in the call, it is assigned to the argument, otherwise the default value defined in the header is assigned to the argument. A default value must not contain whitespace characters. If more arguments are passed in a macro call than defined in the header, the last argument contains all remaining arguments. If no default value is assigned to an argument, the default value is the empty string. If no seperator is spezified between two arguments, all whitespace characters are used as seperator.

important variables: #ARGV, #ARGC

[MACRO macroname ARG: argname1{=defaultvalue1} ...]
[MACRO macroname ARGS: argname1{=defaultvalue1} ...]

ARG-style argument parsing. This form uses the ARG command, and stores each argument in the i-th argument variable. The parsing rulses are the same as for build-in commands without options.

[MACRO macroname ARGOPT: argname1{=defaultvalue1} ...]

ARGOPT-style argument parsing. This form uses the ARG command, and stores each argument in the i-th argument variable. The parsing rulses are the same as for build-in commands with options. The ARG command ca be used to access/check options and option values.

important variables: #QARGV, #QARGC

For some examples of macros using different argument parsing styles, see the scirpt script\examples\macro argument_parsing_example.sts.

Statements

Each macro statement contains one command and/or a label. The command consists of the commandstring and the optional targetstring. The statements are processed line by line. Special control statements can be used to change the processing order. The syntax of a statement is as follows:

{label:}{{targetstring :=} commandstring}

label

A label defines a target which can be used to change the program flow. A label is a string without whitespace and must start with a letter or the underline character (_). It must be unique within the enclosing macro. If a label is used to define a local subroutine/function that can be called using the (GOSUB command, its definition can also define whether parameters passed by the caller are processed or not. The argument parsing is defined in brackets with the same syntax and rules as for the macro header.

Examples:

jumpToMe:
callMe(read: #arg1';'#arg2):
callMeWithOptions(argopt: #arg1=1 #arg2 #arg3):

Note: To get a more readable source code, labels and commands should be placed on separated lines.

commandstring

A command string is the command to be executed. It can be a built-in command, a local subroutine call, a macro call, a member function call or a program flow control command. Normally commands are executed in the order of appearance. Program flow control commands can be used to change this order. Before a command string is parsed and the command is executed, three pre-processing steps are applied.

Variable replacement

A part with the format $name is replaced by the value of the variable name or removed if no value is assigned to this variable. The tag character $ may occur anywhere in the string. The variable name must be delimited by a non-name character. Multiple or recursive variable replacement is currently not implemented (e.g. it is not possible to replace $$name by the value of the variable referenced by the variable name).

Inline command

If a part with the format $(text) is detected, the command line part text is separated and treated as a command. The format of the inline command text is: {targetstring :=} commandstring. At the end of the execution of the inline command, the string $(text) is replaced by the result of the inline command. Inline commands can be nested.

Shell item replacement

• Any part of a command string with the format name[?] is replaced by the type of the shell item name. The name must be delimited by a non-name character. This format is often used to select functions according to the type of an item.
• Any part of the command string with the format name[] is replaced by the number of attributes of the item name. This syntax element is mainly used to retrieve the number of entries stored in a table item.
• Any part of the command string with the format name[!attrid{,subid,...}] is replaced by the value of the addressed attribute of the shell item name. Data and status values or the configuration settings of items can be retrieved using this syntax. Item attributes are replaced after the processing of variables and inline commands in order to provide the possibility of using variables for addressing and identifying an item or attribute.

After applying all replacement rules, the resulting command line is a string with the format: cmd or cmd args, where cmd is a non-quoted string separated from args by whitespaces. The string cmd must be an executable command and args contains the arguments and options for the command.

targetstring

If this optional part is specified, it is used as target for the result of the commandstring. The same replacement rules as described above are applied, but the resulting string is used as name/id of a target and not as executable command. This means the result of the command defined by the commandstring is assigned to the target defined by the targetstring. The assignment format can not be used with the most control commands (like IF, FOR, GOTO), because they do not have a result value.

Definition of Classes

S_TOOLS-STx classes are actually macros with built-in functionality for instantiation, destruction and message handling. The implementation of classes and object oriented programming is based on the class source code (described here) and the instance items, which implements the runtime instance of a class.

Header

A class is defined by the following section header.

[{visiblity:}CLASS classname {parentclass}]

visibility

The visibilty defines from where the class can be instantiated or called.

classname

The name of the class.

parentclass

The name of the parent class. If not specified, the class has no parent class. It is recommened that classes are directly or indirectly derived from CObj. If CObj is not used as base class, some standard functionalities (like message handling, serialisation, ..) are not available to the class.

Statements

In STx a class is a macro with some special features. Therefore the statements are defined and processed in the same way as for macro. The only (but big) difference is, that the class source code contains the definitions of the member functions. The member functions define the behaviour of the instances of a class. Member functions are defined as follows.

scope_functionname:

scope

The scope defines from where a member function can be called. The following scopes are defined:

• public: The function can be called from macros and from instances of all other classes.
• proteced: The function can be called from instances of same class and from instances of classes derived from this class.
• private: The function can only be called from instances of the same class.

functionname

This is the name of member function which must be specified in the call.

Notes:

• All public and protected' member functions are virtual. This means they can be overridden in derived classes.
• The definition of a member function looks like a label in a macro, but can not be used as label. It defines the entry of a member function but not a target for GOTO or GOSUB commands.
• It is possible to include the defintion of the argument parsing in the definition of a member function as described for local subroutines of [[#Definition_of_macros|macros].
• Like local subroutines, a member function must be terminated with an EXIT.
• A class can be used like a macro. This means if the name of a class is specified as command it is called like a macro. This feature can be used to implement static functions.

Definition of SPUs

A signal processing unit (SPU) defines a circuit consisting of elements and connections that can be used to perform a signal processing task. Like a class, the SPU source code defines the prototype of a circuit. The corresponding runtime instance is the SPU item.

Header

[SPU name {arg1 ...} OUT {out1 ...}]

name</name>: The name (class) of the SPU. This name is used to refer to this circuit in other SPU sources and for the instantiation of SPU items.

arg1, ...

The argument list. Each argument is separated from the previous one by a whitespace. The arguments provide the SPU with parameters. Parameters can be either numeric constants or strings (e.g. the name of a soundfile or a data file, the name of a wave-item, the id of a shell-item output, the output name of a value- or spu-item etc.). A list of arguments is optional (i.e. an SPUnit does not necessarily have to act on input data; e.g. signal/data sources like a noise generator)

out1, ...

The outputs list declares the names of all the outputs of the SPU. Each name is separated from the next by a whitespace. The type of data assigned to each output is defined in the output assignments where they are connected to element outputs.

Notes:

• The names of arguments, outputs and elements must be unique within the SPU source code (i.e. you cannot use an argument name for an output name).
• Either the argument list or the output list can be empty, but not both.

Statements

The statements of the SPU source code can be grouped into four categories.

default argument assignments

argX = valueX

This statement assigns the default value valueX to the argument argX. This value is used if no value is given for this argument on instantiation. The default value must be a numeric constant or a string (e.g. 5 or 'a string'). Assigning default values is optional. An argument without a default value, however, must be passed. Default values are used in reverse order. If two arguments are passed, where four have been defined, the third and fourth arguments are assigned their default values. The default values must be assigned before the argument is used (e.g. in a function statement).

STx 4.0

The default values can be assigned in the header using the syntax argX=valueX. The whole assignment must not contain a whitespace, because whitespaces are used for argument seperation.

definition statement

elementX = typeX

A definition statement defines the name elementX and the type (class) typeX of a element of an SPU. This element is local to this SPU (i.e. is not visible outside of the SPU). Any signal processing atom or SPU can be used for typeY. All SPU used in the source code must be loaded before instantiating an SPU item. Once an element is defined it can be used in the function statements and output assignments.

function statement

elementX arguments

The function statements interconnect and 'execute' the elements. The arguments passed to the element are processed within the element and returned to the element's outputs. The element's arguments can be numerical constants, strings, the outputs from other elements, or the SPU's input arguments. They must be passed in the same sequence as defined in the element type's declaration. The function statements implement the interconnection between the SPU elements. Elements must be defined before they can be used. Parsing rules for element arguments:

• $argX is replaced by the value of argX (where argX is a name from the argument list)
• arguments passed to an element are separated by blank spaces
• arguments enclosed in quotes can themselves contain spaces

STx 4.0

It is now possible to use input assignments in the function statements, instead of the ordered list of input values.

elementX inY=argument

Both function statement formats can be used inside a SPUnit source section, but the new should be prefered. If the assignment format is used, it is not necessary to specify the inputs in the right order.

output assignment

outX = elementY.outZ

The output assignments determine which element outputs are made available at the SPU outputs (to be connected to shell items or used in other SPU's using this SPU as an element). Every SPU output must have one output statement. An element output, however, can be assigned to more than one SPUnit output. Elements must be defined before they can be connected to outputs.

STx 4.0

The outputs can be assigned in the header using the syntax outX=elementX.outZ. The whole assignment must not contain a whitespace, because whitespaces are used for argument seperation. This is the only case where an element can be used before it is defined!