Programmer Guide/Source code

Source code

The source code is the text which is interpreted and executed by the BScript application. Examples of S_TOOLS-STx scripts can be found in the directory Examples in the S_TOOLS-STx installation directory.

source file

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.

source section

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.

A source file can also contain other types of sections. If an unknown section type is detected by the loader, the section is ignored. User defined sections can be used to store setup data or any other types of data and can be accessed with the macro SECTIONFILE or with a shell file item.

section header

The section header defines the visibility, type and the name of the source code contained in the source section.

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 (e.g. to call a macro, to create an spu item, to create a instance item of a class, to derive a class, ...). Source sections of type MACRO and CLASS are loaded into the same namespace. A separate namespace is used for SPU items.

section header syntax

The section header is defined within square brackets as follows:

[ { visiblity: } sstype ssname { ssargs } ]

E.g.

[LOCAL:MACRO MacroExample1]

or

[MACRO MacroExample2 #args]

The parameters sstype and ssname are mandatory for the built-in types MACRO, CLASS and SPU, whilst visibility and ssargs are optional.

visibility

There are currently four supported visibility values:

GLOBAL - the section code is visible everywhere.

LOCAL - the section code is visible only for code inside the same source file.

MAIN - defines the section code as the main application macro. This must be called from APPMAIN (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 defined in the S_TOOLS-STx scripting language. User-defined types can also be used (e.g. to store data) and accessed via the SECTIONFILE macro. See Macros, Classes and SPUs for an explanation of macro types.

ssname

The name identifying this source code section. This is used to access the source code later on. The name must be unique in the namespace where the source code is loaded.

ssargs

The meaning of this part of the header depends on the type of the source section. See MACRO, CLASS and SPU for details.

If a class or an spu is defined with local visibility, instances of the class/spu can only be created by macros/classes defined in the same source file.=====source code=====

The source code within a section may consist of statements (at least one is mandatory), empty lines (are ignored) and comments.

During loading (when you run a script, it is first loaded), the source code is parsed, the statements are precompiled and all empty lines and comments are ignored.

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:

A line comment starts with the tag '//' and ends at the end of the same line. E.g.

// this is a line comment

block comment:

A block comment is opened with the tag '/*' and closed with the tag '*/'. A block comment can be spanned over more than one line. E.g.

/* this comment

spans a couple

of lines */

Note that a comment open tag ('//' or '/*') can not be placed in a quoted string. In quoted strings comment tags are interpreted as normal text.

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 and/or commands. In SPUs, the statements are used to define and connect the circuit elements.