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. 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 one of 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 the the member function can be called. The following scopes are defined:

• public: The function is visible everywhere. It can be called from macros and 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.

[CLASS name {parent}]

CLASS

The mandatory keyword to define a class sectionclass

The class nameparent

The name of the parent classClass Functions

Classes can be used in two ways:

• First a class can be called like a macro. In this case the execution begins with the first statement. This feature can be used to implement static functions. Static functions are class functions which can be called directly without creating an instance. The static functions must be defined before the first member function. If a class does not implement any static functions, the first statement in the sourcecode must the an EXIT command, to avoid execution of member functions on instantiation.

[class simple cobj]
// no static functions
exit

• Classes can be used as objects. In this case, first an instance of the class must be created (a shell instance-item) and than the member functions of the instance can be called. The member functions are defined in the class sourcecode with special label names.

// instantiate the CDlgMap class
#dmap := cobj new cdlgmap
if '$#dmap[?]' != 'instance' em -1 ; Failed to create instance of CDlgMap

or alternatively

// You can also instantiate the CDlgMap class as follows,
// if the class calls the cobj constructor itself 
// (e.g. the class exits using the following command:
// exit 1 set $(CObj new CDlgMap $#argv)
#dmap := cdlgmap
if '$#dmap[?]' != 'instance' em -1 ; Failed to create instance of CDlgMap

Member function labels

Class member functions can be defined as public, protected or private.

public_<name>:

Defines the public member function <name> which can be called from every interface.protected_<name>:

Defines the protected member function <name> which can be called by member functions of the class and its derived classes.private_<name>:

Defines the private member function <name> which can only be called by member functions of the class itself.The keywords public_, protected_ or private_ are mandatory when defining a member function. The name must be formatted according to the label name rules and must be unique. All public and protected member functions are virtual, with the consequence that they can be overridden in derived classes.Member function parameters

The way that parameters passed to a member function are parsed, depends on how the function is defined.

The basic function with no specified parameter will store the passed parameters in the variable #argv.

The parameters can, however, also be specified in the function definition, and automatically parsed accordingly.

E.g.:

public_simple:
        // arguments are automatically stored as a string in #argv
        // arguments can also be parsed using the ARG command.
exit
public_advancedread(read: #arg1=10';'#arg2=text';'#arg3):
        // arguments parsed using semi-colon as separator.
        // arguments stored in #arg1, #arg2 and #arg3
        // default values specified for #arg1 and #arg2
        // arguments are all available in #argv and also accessible using the <code>ARG</code> command.
exit
public_advancedarg(arg: #arg1 #arg2 #arg3):
        // arguments are parsed using ARG
exit

Member function source

A member function begins with the first statement following the member function label and ends with an EXIT statement. The member function source code has the same syntax as a macro with the following exceptions:

• When a member is called, execution starts directly at the member function label. Therefore, each member function must implement its own argument parsing (like a subroutine).
• On entry to a member function the variables #ARGV (argument string), #THIS (name of the instance item) and #MAC (name of macro/class) are defined.
• From inside a member function, the instance environment of the instance used in the call command can be accessed directly.

Class Function Call

If a class name is used in a macro call, the class code is executed like a macro. This feature can be used to implement 'static functions' of a class. If you do not want static functions, your class source code must start with an EXIT statement.

static functions:

classname {argumentstring}

classname

Name of a class.

argumentstring

Argumentstring to passed to the class. The same processing as for macro calls is applied.Member functions of a class can only be called for an instance of a class. Therefore it is necessary to create a shell instance-item before the instance member functions can be used.

member functions:

instancename functionname argumentstring

instancename classname::functionname argumentstring

instancename

Name of a shell instance-item.functionname

Name of a member function of the class or of a parentclass of the class.classname

Name of a parentclass of the class.

argumentstring

Argumentstring to passed to the member function. The same processing as for macro calls is applied.Notes:

The return value of all types of class functions is stored in the variable RESULT.

Class - A simple example

 ///////////////////////////////////////////////////////////////////////////////
//
//  File:           simple_class.sts
//  Description:    Example class implementation and instantiation.
//  Author:         Jonnie White
//  History:        2006-02-23  created
//
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
//  Class:          simple 
//  Description:    Display basic class functionality (instantiation, output, 
//                  destruction).
[class simple cobj]

// no static functions

exit

// member functions

public_construct:
    // assign parameters to member variable &text
    &text := 'simple class'
    readvar #argv &text
    exit 1 int 0 // note that the construct MUST return 0
    
public_destruct:
    // do nothing
    exit

public_print:
    // print parameter as text in a dialog box or
    // print the contents of the member variable &text
    #text := '$&text'
    readvar #argv #text
    um $#text
exit

///////////////////////////////////////////////////////////////////////////////
// macro to test the class
[macro main]

// instantiate 
#t := cobj new simple
if '$#t[?]' != 'instance' em -1 ; Failed to instatiate the class
// call print function
$#t print
// destroy the class
$#t destroy

exit

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