Programmer Guide/Source code

The source code is the text which is loaded by the STx source code loader and which is 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 library packages and applications) or sts (for scripts to be loaded and executed via BScript). Examples of scripts can be found in the directory scripts\examples in the STx installation directory. 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 starts a new section, defining the scope, type and the name of the source code contained in the body of the respective section. The section header must be enclosed within square brackets, and the opening bracket must be the first character in the line. There must not be any text behind the closing bracket except, optionally, a comment.

[{scope:}sstype ssname {ssargs}]

scope

The scope of a section defines from where the source code object can be accessed, instantiated or called. Source headers without an explitic scope are GLOBAL. The following scope 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 respective section (which must be defining a macro) as the main macro of an STx application. A main macro must be called by the system macro AppMain. This keyword is applicable to 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, meaning that the macro implements the startup code of a command interpreter instance (shell) and can only be used in the shell. This keyword is applicable to 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 have a defined meaning in the STx scripting language. Other, user-defined, types may also be used (e.g. to store data). Such user-defined sections will be ignored by STx. They may be 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, as defined by the section type, sstype. 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 scope and ssargs are optional, and depend on sstype. All keywords, names and other parts of the header are not case-sensitive.

Examples

[LOCAL:MACRO MacroExample1]
   // This macro called "MacroExample1" will be visible only locally
   …

[MACRO MacroExample2 #args]
   // This macro called "MacroExample2" will be globally visible
   …

[SPU DSPCircuit1 #in1 #in2 OUT #out1]
   …

Section body

The section body consists of statements (actually, there must be at least one statement per section), of empty lines (which are ignored) and of comments (which are also ignored). The section body ends with the next section header or with the end of the file.

comments

A comment is part of the source code that is there for documentation purposes. It is ignored by the loader. A comment can be placed wherever a whitespace character is allowed. The standard C++ comment tags "//" and "/* … */" can be used in 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 an end of a line.

In a quoted string, the comment tags are interpreted as normal text and not as tag, which is probably the expected behaviour. It is also possible to escape one character of a comment tag (like: `//) to avoid its interpretation.

statements

A statement is that 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 section headers liated below. The possible formats differ only in how arguments are processed or parsed 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]

Arguments are stored in the variables #ARGV and #QARGV, without further processing or parsing. The user program is free further to process these data, e.g. by using the READVAR and/or the ARG command.

important variables: #ARGV, #QARGV

[MACRO macroname {READ:} argname1{=defaultvalue1} {separator1} …]

READ-style argument parsing: The arguments are parsed as strings, internally using the READVAR command before the first macro statement is executed. The programmer can select arbitrary separators by supplying the separatorn arguments. 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, its value is the empty string. If no separator is spezified between two arguments, all whitespace characters are considered separators.

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

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

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=elementY.outZ. The whole assignment must not contain a whitespace, because whitespaces are used for seperation. This is the only case where an element can be used before it is defined!

Escape and Continuation Character

In some cases tag or parsing characters should be used as normal characters (e.g. arguments for commands or a part of a string). In this case the escape character ` (back-quote) can be used to suppress the interpretation of the following character.

The escape character has a special meaning if it is the last character on a line. In this case it is interpreted as continuation character and the next line is concatenated to the current. This feature can be used to concatenate two or more lines. Concatenation applies to statements but also to section headers.

Preprocessing

The STx preprocessor may be used for conditionally skipping or including parts of an STx source file depending on which preprocessor constants have been defined (and which haven't). In the directory script\examples, you will find a script called preprocessor.sts showing several ways of using the preprocessor.

Every preprocessor command must start either with the character ! (exclamation mark), or with the character ] (closed square bracket). Although not strictly enforced (the preprocessor only issues a warning otherwise), either character should be placed in the very first column of the respective line.

For defining and undefining a preprocessor constant, there are the preprocessor commands define and undef:

! define CONSTANT1
! define CONSTANT2
! undef CONSTANT1

• Like the most other keywords and names used in STx, preprocessor statements and constants are case-insensitive, meaning that CONSTANT1, constant1, and CoNsTaNt1 are the same constant.
• Note that (for the time being), the only property of preprocessor constants is their being defined or being undefined. It is currently not possible (since it would currently make no sense) to assign a value to a constant.

The conditional ifdef, elif, else, and endif preprocessor statements cause the macro interpreter conditionally to skip part of the macro source code. See for yourself:

! ifdef CONSTANT
writelog 'This statement will be executed if CONSTANT is defined'
! else
writelog 'This statement will be executed unless CONSTANT is defined'
! endif

With the if command, there is also support for complex conditions:

! if defined(CONS1) || defined(CONS2) && defined(CONS3)	
writelog 'This statement will be executed if either CONS1 or both of CONS2 and CONS3 are defined' 
! elif defined CONS4 && ! defined CONS5	
writelog 'This statement will be executed if the preceding statement is not, and if CONS4 is defined and CONS5 is not 
! else	
writelog 'This statement will be executed if neither of the preceding statements were' 
! endif

• You may, but need not enclose the argument of the defined function (i.e. the name of a constant) in brackets.
• You may build up complex expressions with the && (and), || (or), and the ! (not) operator.

Unlike in other conditional expressions used in STx (e.g. the IF command) which are evaluated strictly from left to right, you can group expressions with brackets. If you do not use brackets, && will take precedence over ||, as it normally does (and contrary to what STx normally does due to historical reasons).

! if (defined(CONS1) || defined CONS2) && (defined(CONS3) ||defined(CONS4))

There are a few additional preprocessor statements you may find useful:

!include filepath

With the include statement, you may textually merge some other files into the current macro (just like with the "#include" preprocessor statement in C, or with COBOL copy books). Note that it is (for obvious reasons) not possible for a file to include itself, or to include a file that includes a file that, in turn, includes a file including the first file. If you try to, macro interpretation will abort with an error message. If the file name supplied to the include statement is not an absolute path, the preprocessor will first look for the respective relative path in the current directory and, on failure, will look for it in directory where the including file is situated. Note that, for the time being, file inclusion may not be nested for more than forty-two levels.

!showdef or !showdef constant

Without arguments, this command will print a list of all preprocessor constants currently defined. With an argument supplied, the command will show if the argument is a preprocessor constant that is currently defined.

!warn msg

This statement causes the script loader to display a user-defined warning message. Execution of the script is not impaired by issuing a warning.

!error msg

This statement causes the STx script loader to issue a user-defined error message and to cancel loading the source file.

Other Source File Sections

The standard sections of a source file (macro, class, spu) contain the code which is loaded and interpreted by STx.

[Libraries]
library1
library2
...

Notes

• The source file may also contain other sections that can be used for many purposes. e.g.:
  • initialize data tables
  • define the standard (default) values of a setup dialog
  • define a dialog template
  • ...
• The sections of a source file should only be loaded. Do not save dynamic data (like current settings) in a source file. If a section is written to a source file (e.g. via the macro SectionFile), the content is not destroyed, but the text formatting can be changed.