MC
API

Subsystem
list

Top
level

The SYMtable Class

A symbol table provides a mapping between names (or "symbols") and values.

Defined in: "SymbolTable.inc".

Types

SYMmergeDupes - how to handle merge conflicts

Methods

`void`	`Add`	`(string sName, anytype aValue)`
`void`	`Set`	`(string sName, anytype aValue)`
`void`	`AddOrSet`	`(string sName, anytype aValue)`
`void`	`Delete`	`(string sName)`
`boolean`	`GetBoolean`	`(string sName)`
`integer`	`GetInteger`	`(string sName)`
`list of anytype`	`GetList`	`(string sName)`
`real`	`GetReal`	`(string sName)`
`string`	`GetString`	`(string sName)`
`string`	`Source`	`(string sName)`
`boolean`	`Exists`	`(string sName)`
`void`	`Clear`	`(inout SYMtable st)`
`void`	`ReadFile`	`(SYMtable st, string sFileName)`
`void`	`MergeFrom`	`(SYMtable stMergeFrom, optional SYMmergeType eMerge, optional string sSource)`
`void`	`Print`	`()`

The SYMmergeDupes Type

This data type enumerates three different ways of handling conflicts when symbol tables are being merged with MergeFrom .

Declaration

type SYMmergeDupes is enum { /* values (see below) */ };

Values

`eSYM_MERGE_KEEP`	When this option is enabled, all symbol values are preserved in the "merged into" symbol table, and only those symbols which are unique to the "merged from" symbol table are added.
`eSYM_MERGE_OVERWRITE`	When this option is enabled, all symbol values are copied in from the "merged from" symbol table. If a given symbol already existed in the "merged into" symbol table, its value (and type) are overwritten.
`eSYM_MERGE_ERROR_IF_DUPES`	When this option is enabled, an exception will be raised if a given symbol exists in both the "merged from" and "merged into" symbol tables.

Add

Adds a new symbol to the symbol table. If the symbol already exists in the symbol table, an exception is raised.
See also Delete, Set, AddOrSet.

Declaration

void Add (string sName, anytype aValue)

Inputs

sName: The name of the symbol.
aValue: The value of the symbol.

Outputs

None.

Exceptions

X_SYM_ALREADY_EXISTS: The symbol was already defined in the symbol table.

AddOrSet

Sets the value of a symbol in the symbol table, creating the symbol if necessary.
See also Set, Add.

Declaration

void AddOrSet (string sName, anytype aValue)

Inputs

sName: The name of the symbol.
aValue: The value of the symbol.

Outputs

None.

Delete

Delete a symbol and its value from the symbol table.
See also Add, Set, Clear.

Declaration

void Delete (string sName)

Inputs

sName: The name of the symbol.

Outputs

None.

Exceptions

X_SYM_NOT_FOUND: The symbol was not found.

Clear

Removes all of the symbols from the symbol table.

Declaration

void Clear ()

Inputs

None.

Outputs

None.

Exists

Tells whether the given symbol exists in the symbol table.

Declaration

boolean Exists (string sName)

Inputs

sName: The name of the symbol.

Outputs

Returns: TRUE if the symbol exists in the symbol table; FALSE if it does not.

GetBoolean

Returns the boolean value of a symbol.

Declaration

boolean GetBoolean (string sName)

Inputs

sName: The name of the symbol.

Outputs

Returns: The value of the symbol.

Exceptions

X_SYM_NOT_FOUND: The symbol was not found.
X_SYM_TYPE_CONFLICT: The value of the symbol is not a boolean.

GetInteger

Returns the integer value of a symbol.

Declaration

integer GetInteger (string sName)

Inputs

sName: The name of the symbol.

Outputs

Returns: The value of the symbol.

Exceptions

X_SYM_NOT_FOUND: The symbol was not found.
X_SYM_TYPE_CONFLICT: The value of the symbol is not an integer.

GetList

Returns the list value of a symbol.

Note that this routine, unlike the other Get* routines, is not type-safe. You are responsible for making sure that the list contains elements of the proper type.

Declaration

list of anytype GetList (string sName)

Inputs

sName: The name of the symbol.

Outputs

Returns: The value of the symbol.

Exceptions

X_SYM_NOT_FOUND: The symbol was not found.
X_SYM_TYPE_CONFLICT: The value of the symbol is not a list.

GetReal

Returns the real value of a symbol.

Declaration

real GetReal (string sName)

Inputs

sName: The name of the symbol.

Outputs

Returns: The value of the symbol.

Exceptions

X_SYM_NOT_FOUND: The symbol was not found.
X_SYM_TYPE_CONFLICT: The value of the symbol is not a real.

GetString

Returns the string value of a symbol.

Declaration

string GetString (string sName)

Inputs

sName: The name of the symbol.

Outputs

Returns: The value of the symbol.

Exceptions

X_SYM_NOT_FOUND: The symbol was not found.
X_SYM_TYPE_CONFLICT: The value of the symbol is not a string.

Source

Determine which filename a symbol originated in.

Declaration

string Source (string sName)

Inputs

sName: The name of the symbol.

Outputs

Returns: If the symbol was loaded in from a file, then the name of that file is returned. If the symbol was created by other means (e.g. Add), then whatever value was assigned at that time (possibly NULL) is returned.

Exceptions

X_SYM_NOT_FOUND: The symbol was not found.

Print

Prints to the results file all of the symbols in the symbol table, along with their values.

Declaration

void Print ( )

Inputs

None.

Outputs

None.

ReadFile

Reads a symbol file and assigns symbols according to the contents of the file. See also Symbol File Syntax.

If a symbol exists in the symbol table prior to calling ReadFile and the symbol file contains an assignment of that symbol, the symbol's value is changed to the value specified in the file.
If a symbol is assigned more than once in a file, an exception is raised.

Declaration

integer ReadFile (string sFileName)

Inputs

sFileName: The name of the file.

Outputs

None.

Exceptions

X_SYM_ALREADY_EXISTS: A symbol was defined twice in the file.
X_SYM_FILE_ERROR: A syntax error was found in the file.

MergeFrom

Merges the contents of one symbol table into another.

Declaration

void MergeFrom (SYMtable uMergeFrom,
    optional SYMmergeDupes eMerge,
    optional string sSource)

Inputs

uMergeFrom: A symbol table.
eMerge: An optional value of type SYMmergeDupes. This setting controls what happens when the same symbol is defined in both symbol tables. By default, this will raise an exception, but it is possible to specify instead that values from one symbol table or the other are to be used.
sSource: An optional string indicating the source of a given symbol. If this parameter is present and set to "X", any symbol copied from uMergeFrom will be flagged as having come from "X". If this parameter is omitted, any copied symbol's "source" attribute (usually a filename) will be preserved.

Outputs

None.

Exceptions

X_SYM_ALREADY_EXISTS: A symbol was defined in both symbol files and eMerge was set (or defaulted) to eSYM_MERGE_ERROR_IF_DUPES. In this event, the uMergeInto symbol table is unmodified.

Example of Symbol File


// This is an example of a symbol file.

VideoFormat = "NTSC";

Film = FALSE;

ClipCount = 10;  // number of clips to put in sequence
 
BinList = { "Bin1", "Bin2", "Bin3" };

Symbol File Syntax

A symbol file (also known as a Parameter File) contains zero or more assignment statements, with a syntax very similar to 4Test.

Each assignment statement consists of a symbol (variable) name, an equals sign, a value, and a semicolon.

The "//" syntax for comments is supported. However, the "/* ... */" syntax is not.

Whitespace is not significant, except within a quoted string.

Symbol names are composed of alphanumeric characters and/or '_' (underscore), and must not begin with a digit.

Strings may be delimited with either single or double quotes; the beginning and ending delimiters must match.

Numbers may optionally include a leading '-' and/or a decimal point. Currently only decimal numbers are allowed.

Lists consist of an open curly brace '{', zero or more values separated by commas, and a close curly brace '}'.

You can logically include one symbol file in another by using the keyword "use", followed by a string containing a file name, followed by a semicolon.

If a symbol is assigned more than once in a file, an exception is raised when the file is read. See SYMreadFile.

BNF Grammar

symbol_file := [statement ";"]...
statement   := assignment | "use" string
assignment  := symbol_name "=" value
value       := string | number | boolean | list
boolean     := "TRUE" | "FALSE" | "true" | "false"
string      := '"' character... '"' | "'" character... "'"
number      := digit... ["." digit...] | "." digit...
list        := "{" [ value ["," value]... ] "}"

Set

Changes the value of a symbol in the symbol table. If the symbol does not exist in the symbol table, an exception is raised.
See also Add, AddOrSet.

Declaration

void Set (string sName, anytype aValue)

Inputs

sName: The name of the symbol.
aValue: The new value of the symbol.

Outputs

None.

Exceptions

X_SYM_NOT_FOUND: The symbol was not found in the symbol table.

This page is maintained by (REMOVED).

Last updated 9 September 1998.