Source code

From STX Wiki
Jump to navigationJump to search

Source code

The source code is the text which is loaded, interpreted and executed by the BScript application. Examples of scripts can be found in the directory scripts\examples in the S_TOOLS-STx installation directory. A source file is a text file containing source code. By convention, source files end with the extension sts. 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

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.

READ-style argument parsing.

[MACRO macroname {READ:} argname1{=defaultvalue1} {seperator1} {argname2={defaultvalue2} {seperator2} ...}]
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 the r

Argument Parsing Argument parsing can be done in the section header, or in the section code. Section header argument parsing comes in two forms: the 'read' and the 'arg' forms.

'ARG' Argument Parsing Syntax:

[MACRO macroname ARG: name1{=value1}...}]

This form used the ARG family of commands, and stores each argument in the i-th argument variable.


'READ' Argument Parsing Syntax:

[MACRO name { { READ: } name1{=value1}{'sep1]...}]

The arguments are parsed as strings, using the READ family of commands.

'ARGOPT' Argument Parsing Syntax:

[MACRO name { { ARGOPT: } name1{=value1}...}]

This form used the ARG family of commands with the option /O. It ignores all options, and stores each argument in the i-th argument variable.

Argument Parsing Examples Example:

[Macro test]mac1 'one' /t 'two' 'three'mac2 'one' /t 'two' 'three'mac3 'one' /t 'two' 'three'exit[Macro mac1 read:#arg1 #arg2 #arg3]con log '$#mac #arg1=$#arg1 #arg2=$#arg2 #arg3=$#arg3'exit[Macro mac2 arg:#arg1 #arg2 #arg3]con log '$#mac #arg1=$#arg1 #arg2=$#arg2 #arg3=$#arg3'exit[Macro mac3 argopt:#arg1 #arg2 #arg3]con log '$#mac #arg1=$#arg1 #arg2=$#arg2 #arg3=$#arg3'exitWhen calling the macro 'test', the following will be output:

  1. arg1=one/ttwothree #arg2= #arg3=
  1. arg1=one #arg2=/t #arg3=two
  1. arg1=one #arg2=two #arg3=

For more examples, see the macro argument_parsing_example in the example script file argument_parsing_example.sts.

Statements Each macro statement contains one command and/or a label. The statements are executed line by line. Special control statements can be used to change the execution order.

The syntax is as follows:

{label:}{commandstring}

Labels 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. It must be unique within the enclosing macro.

The label definition can also define whether parameters passed by the caller are processed or not (see Argument Parsing). E.g.:

dosomething(read: #arg1=defaultValue';'#arg2): // parameters are parsed into #arg1 and #arg2exitSee label_argument_example.sts for a working example.

Command strings 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 like can be used to change this order.

Command string pre-processing Before a command string is parsed and the command is executed, three pre-processing steps are applied.

Variable replacement 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 name. The tag character $ may occur anywhere in the string. The variable name must be delimited by a non-name character. Multiple variable replacements are currently not implemented (e.g. replace $$name by the value of the variable referenced by the variable name). Note that you can escape the dollar character using the character ` (acute accent).

Inline command: If a string with the format $(text) is detected, the command line part text is separated and treated as a command line. The command must be a call to a macro, a local subroutine or member function of a class or the built-in command VAR (in any valid format). At the end of the execution of the inline command, the string $(text) is replaced by the value of the variable RESULT (if a call was executed) or the result of the VAR command. Inline commands can be nested.

An alternative specification of an inline command is given by the format $(name := text). The processing of the command text and the replacement is performed as described above but the value of RESULT is also assigned to the variable name. The name is used unchanged; no variable replacement is applied.

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] or name[!attrid{,subid{,..}}] is replaced by the value of the attribute addressed by that attribute. 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.

Command extraction and translation After all replacement rules have been applied, the resulting command line is a string with the format: firstword rest, where firstword is a non-quoted string separated from rest by blanks. In the next step, the command is translated if the command line has one of the following formats:


command line -> translated to -> executed command

variablename := argumentstring

VAR variablename argumentstring

itemname argumentstring

SET itemname argumentstring

marconame argumentstring

MACRO macroname argumentstring

classname argumentstring

MACRO classname argumentstring

command argumentstring

command argumentstring


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

Navigation menu

Personal tools