Programmer Guide/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. A source file can also contain other types of sections. 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 the 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. E.g.

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 /*) can not be placed in a quoted string, where it is interpreted as normal text. 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 for 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 executed line by line. Special control statements can be used to change the execution order. The syntax 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 (GOSUB, 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.

jumpToMe: // just a label
callMe(read: #arg1';'#arg2): // the entry of a local subroutine
callMeWithOptions(argopt: #arg1=1 #arg2 #arg3): // local subroutine parsing arguments and options like a build-in command

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 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 all replacement rules have been applied, 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.

Local sub-routines A local sub-routine is a part of a macro which begins at a label (E.g. MySubRoutine:) and ends with an EXIT command. Sub-routines can only be called from within that macro. The return value of a sub-routine call is stored in the shell variable RESULT.

The syntax for calling a local subroutine is as follows:

GOSUB label {argumentstring}

or

GOSUBX label {argumentstring}

Where GOSUB is an in-built command which calls a sub-routine, GOSUBX is identical to GOSUB, except that it uses the caller's local variable namespace. The argumentstring is passed to the sub-routine as it would be to a macro (E.g. it is available by default in the local variable #argv).

Built-in commands Built-in commands are commands which are executed directly by the interpreter. A list of built-in commands can be found in the Command Reference.

The parsing of the argument string differs from that of other command types.

The syntax is as follows:

command {argument1 {argument2 … {options}}

Where command is the name of an in-built command (see the Command Reference). It must be the first word on the line and must not be a quoted string.

Where argumentX is the x-th argument for the command. The meaning of arguments depends on its place in the command line. There are two formats for arguments:

normal arguments - strings containing no white spaces and are not enclosed in quotes. They are separated from other arguments by a white space or a quote. quoted arguments - strings enclosed in quotes containing any possible character Where options are strings which are not enclosed in quotes and start with an slash ('/'). An option can be used as switch (/optionname) or to specify a value (/optionname=optionvalue). Only the first letter of optionname is used to identify the option. In some cases (depending on the command) the optionname is case sensitive. Both types of option formats must not contain white spaces. The meaning of an option depends only on the optionname and not on the placement of the option. This means that options can be specified anywhere on in a command string, but may not be specified in quoted strings.

Program Flow Control GOTO:

GOTO target {alternatetarget}

GOTO

Continue execution at specified label (build-in command)

target

Name of the label where the execution should continue

alternatetarget

Name of the label where the execution should continue if label target do not exist.

Notes:

If the label target do not exist and no alternate target is specified or it is also not found, the execution of the macro ends. IF:

IF condition command

IFNOT condition command

IF

Execute command if condition is true (build-in command)

IFNOT

Execute command if condition is false (build-in command)

condition

Condition to be evaluated and tested. A detailed description can be found in the command reference

command

Conditional command. Can be any type of command except an inline-command (see commanline string replacement described below)

block IF:

IF condition THEN

command block

{ELSE IF condition THEN

command block

}

{ELSE

command block

}

END

A block if is a construct which consists of an IF-THEN clause (mandatory), one or more ELSE-IF-THEN clauses (optinal), one ELSE clause (optional) and is closed with an END statement (mandatory). The command block of the first clause where the condition is true is excuted. If no condition is true and an ELSE clause exists, the command block of the ELSE clause is executed.

Notes:

For the conditions in block ifs the same syntax as for the normal IF is used. If no END statement can be found for a block if, the macro can not be loaded. DO loop:

A loop begins with the DO WHILE or DO UNTIL statement and is closed with an END statement. The command block is executed while (DO WHILE) or until (DO UNTIL) the condition specified in the DO statement is true.

DO WHILE condition

command block

END

DO UNTIL condition

command block

END

In a loop the special control commands can be used:

BREAK -> leave the loop and continue with the first command after the loop CONTINUE -> skip the rest of the command block and continue with the DO statement © 2009 The Austrian Academy of Sciences Acoustics Research Institute