Names, Namespaces, Keywords and Options

From STX Wiki
Jump to navigation Jump to search

In STx 'names' are identification strings. They are used for the following:

  • macro and spu source code definitions
  • labels within macros
  • items
  • item inputs and outputs
  • variables
  • table fields
  • table data

Syntax

Unless specified otherwise, names can contain the following characters:

  • 'a' .. 'z' (letters)
  • '0' .. '9' (digits)
  • '#', '@', '&' and '_' (symbols).

The first character must be a letter or a symbol (not a digit). Names are generally not case sensitive ('AName' is equal to 'aname'). One notable exception are segment names.

Variable Names

Variables may not contain the symbol '_'. The symbols ('#', '@' and '&') are used as first character to address a particular namespace. In some commands, two names are concatenated to form an identifier. E.g.

spuitem.output graphitem.CURSOR instanceitem.variable class::memberfunction

Segment Names

Audio segment names may not contain the following characters:

+-*/%:'$_

Audio segments are case sensitive and should not contain blank spaces.

Table Field Names

The data type name used in tables differs from other names:

  • a name need not to be unique inside a table (row).
  • a name can be split into parts with the character '.' (dot)
  • names may be case-sensitive searched and compared (e.g. segments; this depends, however, on the way the macro has been programmed) wildcards ('*' and '?') can be used in search and compare functions
  • the rules used are those used for windows file names rather than an STx specification. However, the following characters should not be used because of their special meaning in STx: quotes (), square brackets ([ ]), and the dollar symbol ($)
  • if extended ASCII characters (e.g. from the German character set: ö, ä, ß, ...) or parsing symbols (blanks, tabs) are used, the name must be surrounded by quotes, if accessed in command lines (e.g. '$#table[$#index,NAMEFIELD]' where NAMEFIELD contains extended characters).

Namespaces

A namespace (or environment) defines the context within which a name must be unique and from which the entity identified by the name can be accessed. The table below lists the different namespaces.

namespace for ... context visible from macros / classes
macro and class source code whole application All
SPU source code whole application All
shell items a shell inside the owning shell
arguments (inputs), outputs and local functions of an SPU source SPU source code inside the owning shell; arguments/inputs are specified on spu item instantiation; outputs can be used to connect an spu item
input and outputs of items (e.g. graphs) the owning item inside the owning shell; inputs/ outputs can be used to connect the item
macro labels and class member functions macro/class source code labels can only be used inside the source code; member functions can be accessed from inside the shell (public) or the instance (protected / private)
global variables whole application all
shell variables a shell inside the owning shell
local variables macro or class inside the macro or member function
instance variables instance inside the class / instance; inside the shell if instance name is known

Keywords

Most shell commands use keywords to select a (sub-) function or pass special arguments (e.g. colors). All keywords can be abbreviated to the shortest unique form (e.g. the color WHITE can be abbreviated to W, but the shortest form for GREEN is GRE because GR can also mean GRAY). All keywords (except those used for options) are case insensitive.

Options

A command may be parsed options in the format /O or /O=value. An option begins with the character '/'. Options may be case sensitive, e.g. /O does not necessarily have the same effect as /o.

In this documentation, if an option is documented using mixed case, where one letter is capitalised, the capitalised letter is the option (e.g. /centRe should be written as /R when coding).

If you need to specify a forward slash in a command, which should not be parsed as an option, you can do so after specifying the option '/-'. E.g.:

#a := quote /the first word and the last word are /missing

#a := quote /- /neither the first nor the last word is /missing

In contrast to other keywords, some option names and values are case sensitive.