Programmer Guide/Source code

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 built-in types MACRO, CLASS and SPU, whilst visibility and ssargs are optional. The header name must be unique in the source file. The type is used by S_TOOLS-STx to select the namespace and the loader which is used to load the source code. The name is used to access the source code

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.