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. The section header defines the visibility, type and the name of the source code contained in the source section.

Section header

The section header is defined within square brackets as follows. 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}]

E.g.:

[LOCAL:MACRO MacroExample1]

[MACRO MacroExample2 #args]

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.

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 scripting language. User-defined types can also be used (e.g. to store data) and accessed via the SECTIONFILE macro or directly with the file item functions.

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.

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 (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.

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.

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.