Chapter 1 - Introduction

This document defines and describes the syntax and semantics of the Somusar/Tefigel[tm] language. Each chapter defines purpose and usage of a set of Somusar/Tefigel[tm] constructs, and describes them concisely.

1.1 - Syntax Notation

In the syntax convention used in this document literal words and characters are indicated by text in bold fixed-font type, as in process. Non-terminal symbols are indicated by text between < and > in italic type, as in <this-is-a-symbol> (when defined) or as in <this-is-a-symbol> (when referred to).

Chapter 2 - File Sections

2.1 - Purpose

An input file for Tefigel may contain one or more <file-section>'s of three types: text, Tefigel code, and comment blocks. File sections allow to improve readability of Tefigel files and can be freely defined within each Tefigel file in no particular order. By default the content of a Tefigel file whose name ends in ".tfg" is assumed to start with a <tefigel-section>. The content of a Tefigel file whose name does not end in ".tfg" is assumed to start with a <text-section>.

2.2 - Usage

Define a <text-section>:

   text
   <text-section>
   endtext

   tefigel
   <tefigel-section>
   endtefigel

   <comment-marker>\
   <comment-section>
   <comment-marker>/

2.3 - Description

A <file-section> consists of zero or more <logical-line>'s.

The content of a <text-section> is subject to textual substitution of <variable>'s and in-line function calls via <subprogram-reference>'s. Lines starting with the current <command-marker> are treated as <command>'s. Lines starting with the current <comment-marker> are treated as <comment-line>'s.

The content of a <tefigel-section> is processed as a sequence of <command>'s or subroutine and function calls via <subprogram-reference>'s. Lines starting with any current <instruction-marker>, possibly preceded by blanks and/or tabs, are processed as the corresponding <instruction>. In particular, lines starting with the current <comment-marker>, possibly preceded by blanks and/or tabs, are treated as <comment-line>'s.

The content of a <comment-section>, including its opening and closing delimiters, is treated as a sequence of <comment-line>'s.

Both <text-section>'s and <tefigel-section>'s may contain any number of <comment-section>'s.

Chapter 3 - Commands and Instructions

3.1 - Purpose

An input file for Tefigel consists of a sequence of <logical-line>'s. Commands and instructions steer the file generation process performed by Tefigel on its input(s) to generate its output(s).

3.2 - Usage

   <command-marker> <instruction> <instruction-parameters>
   <command-marker> <subprogram-reference>
   <command-marker> <subprogram-reference>(<parameter-list>)
   <instruction-marker> <instruction-parameters>

3.3 - Description

A <logical-line> consists of one or more physical lines of text; if the last character of a physical line matches the current linebreak <special-function> then the logical line continues on the next physical line.

A Tefigel <command> is a logical text line beginning with one of the following:

• A Tefigel <instruction-marker>;

• The current general <command-marker>, possibly followed by white spaces, then followed by a Tefigel <instruction>;

• The current general <command-marker>, possibly followed by white spaces, then followed by a <subprogram-reference>, possibly followed by a <parameter-list>.

Depending on the <instruction>, a list of <instruction-parameters> may follow the Tefigel keyword.

Chapter 4 - Markers

4.1 - Purpose

Define a first-column marker for Tefigel commands or instructions.

4.2 - Usage

Define a new command or instruction marker:

   mark CMD <new-marker>
   mark <instruction> <new-marker>

   mark CMD
   mark <instruction>

4.3 - Description

The initial value for the CMD (command) marker is the at-sign @.

The initial value for the call (subroutine call) marker is the dollar-sign $.

The initial value for the rem (remark) marker is the sharp-sign #.

The <instruction>'s that can be specified as parameters for mark are the following:

   rem
   call
   set
   globset
   unset
   link
   unlink
   trap
   untrap
   add
   sub
   mul
   div
   trunc
   neg
   eval
   and
   or
   not

Chapter 5 - Comments

5.1 - Purpose

Add textual descriptions to Tefigel scripts.

5.2 - Usage

   rem comment text
   <comment-marker> comment text

5.3 - Description

The <comment-marker> is the most recent <new-marker> specified for instruction rem. Its initial value is the sharp-sign #.

All <comment-line>'s in input are ignored by Tefigel.

Chapter 6 - Special Characters

6.1 - Purpose

Associate a special text-processing function with a single character.

6.2 - Usage

Define a new special character for a given special function:

   <special-function> <new-special-character>

   <special-function>

6.3 - Description

The <special-function> can be one of the following:

• argdelim [Initial value: comma (',')]
  Separator of parameters for Tefigel subroutine or function call's.

• callkey [Initial value: tilde ('~')]
  In-line function call marker: on output, the in-line function call is replaced by the string (if any) returned by the called function.

• dash [Initial value: none]
  String concatenation operator, also used to create name-value associations, which can be used for traditional data structures such as records and arrays.

• escape [Initial value: none]
  Escape character within lists of parameters in function or subroutine calls.

• linebreak [Initial value: none]
  Logical line concatenation operator, used to split long input logical lines into two or more input physical lines.

Chapter 7 - Variables

7.1 - Purpose

Define placeholders for character strings that can also be used as traditional program variables.

7.2 - Usage

Set a variable in the global name space:

   globset <variable>=<value>
   globset <associative-variable>=<value>

   set <variable>=<value>
   set <associative-variable>=<value>

   unset <variable>
   unset <associative-variable>

   text text text text text text text text
   text text text <variable> text text text
   text text text text text text text text

7.3 - Description

A <variable> is defined as an identifier represented by a sequence of letters, digits and underscore ('_'). The first character of the identifier must be either a letter or an underscore. Tefigel is case-sensitive with respect to variable identifiers.

A <value> can be any string and requires no delimiters: every character after the assignment operator = up to the end of the logical command line is considered part of the <value> to be stored in the <variable>, including blanks and tabs, which are treated exactly as all other characters. A <value> may contain other variables as well as in-line function calls, so that <variable> is assigned the string of characters resulting from replacing the other variables with their contents, and the in-line function calls with their return values.

An <associative-variable> is defined as the concatenation of two or more identifiers by means of the current dash special character. The identifiers may refer to previously set variables - in which case their current value is used to construct the corresponding part of the identifier of the <associative-variable> - or not refer to any variable - in which case they will literally be used to construct the corresponding part of the identifier of the <associative-variable>.

Depending on its current value, a variable may be used for arithmetic or boolean computation, as explained later in this guide.

Chapter 8 - Arithmetic Computation

8.1 - Purpose

Perform basic arithmetic operations.

8.2 - Usage

Add, subtract, multiply, divide two numbers:

   <arithmetic-instruction> <numerical-variable> <numerical-value>

   neg <numerical-variable>

   trunc <numerical-variable>

8.3 - Description

The <arithmetic-instruction> must be one of the following:

   add
   sub
   mul
   div

Arithmetic computation is always performed by Tefigel in floating-point in decimal base representation.

Chapter 9 - Boolean Computation

9.1 - Purpose

Perform simple boolean (logical) computation.

9.2 - Usage

Evaluate a plain boolean comparison storing the result into a variable:

   eval <target-variable> <boolean-comparison>

   <boolean-instruction> <target-variable> <boolean-comparison>

   not <boolean-variable>

9.3 - Description

The <boolean-instruction> must be either and or or.

A <target-variable> is defined as the identifier of a <variable> whose value will be set to 1 or 0 depending on the boolean result - true or false, respectively - yielded by the boolean comparison or operation.

A <boolean-variable> is defined as the identifier of a <variable> whose current value is a string representing a number, the boolean value of which will be considered false if the number equals 0, true if the number equals 1, or invalid otherwise.

A <boolean-comparison> is defined as follows:

   <comparison-variable><comparison-operator><comparison-value>
   <comparison-variable>

   <comparison-variable>#0

Chapter 10 - Control Flow

10.1 - Purpose

Specify the order in which the processing of input lines must be performed by Tefigel.

10.2 - Usage

Terminate processing:

   exit <exit-code>

   if <boolean-comparison>
   <input-block>
   else
   <alternative-input-block>
   endif

   case <case-variable>
   when <case-evaluator>
   <input-block>
   when <case-evaluator>
   <input-block>
   otherwise
   <alternative-input-block>
   endcase

   while <boolean-comparison>
   <input-block>
   endwhile

   for <loop-variable>=<for-each-list>
   <input-block>
   endfor

   loop <loop-variable>=<range-definition>
   <input-block>
   endloop

   jump <target-label>
   <input-block>
   label <target-label>

   jumpcond <target-label> <boolean-comparison>
   <input-block>
   label <target-label>

10.3 - Description

An <exit-code> is an integer number to be returned to the operating system process that started Tefigel.

An <input-block>, or an <alternative-input-block>, is a sequence of logical input lines, that may contain none, one, or more Tefigel command lines.

A <case-evaluator> is defined as follows:

   <comparison-operator><comparison-value>

When performing a conditional transfer of control, on processing the jumpcond instruction, if the <boolean-comparison> yields true, file generation control is transferred to the input line immediately following the label instruction, so that the <input-block> is not processed. Both forward and backward conditional transfer of control are allowed.

Chapter 11 - Subroutines and Functions

11.1 - Purpose

Divide a complex file generation process in a set of simpler functional modules that insulate repetitive or specific tasks and are easier to write, test, and manage.

11.2 - Usage

Transfer control to a subroutine (a file) in the same variable name space:

   process <file-reference>

   process_if_readable <file-reference>

   [call] <subprogram-reference>
   [call] <subprogram-reference>(<parameter-list>)

   <call-key><subprogram-reference>(<parameter-list>)

   interface(<new-variable-list>)

   shift

   retvalue=<value>

   quit

   codefile

11.3 - Description

A <file-reference> can be either a valid file pathname - absolute or relative - or a <variable> containing a string corresponding to a valid pathname. Relative file pathnames of functions or subroutines are first sought for with respect to the working directory of Tefigel, then using the current <library-path-specifier>, described later in the guide. Tefigel will first attempt to access the file with the given name; in case of failure it will try to access the file adding the extension ".tfg". In other words, extension ".tfg" is optional and may be omitted in <file-reference>'s.

A <subprogram-reference> can be either a <file-reference> or a <built-in-function>. The call instruction may be omitted.

A <parameter-list> is a sequence of strings or <variable>'s, separated by the character currently associated with <special-function> argdelim.

The <call-key> is the character currently associated with <special-function> callkey.

A <new-variable-list> is a sequence of <variable>'s, separated by the character currently associated with <special-function> argdelim.

The <parameter-list> may be omitted, in which case it is also possible to omit the left and right parentheses. Arguments supplied as parameters to a function or subroutine are made available in the new name space of the called function or subroutine as "register" variables identified as REG_0, REG_1, REG_2, etc., according to their sequential position in the <parameter-list>. Unspecified registers are guaranteed to be initialized to the empty string. The number of arguments is available in variable REG_COUNT. The complete list of arguments is also available in variable REG_ALL.

Instruction shift transfers the contents of each REG_n into REG_n - 1, decrements REG_COUNT, and updates REG_ALL accordingly.

Instruction interface automatically initializes each variable in the <new-variable-list> to the value of the register in the corresponding order position. A <new-variable-list> in the form "..." specifies that the function or subroutine has a variable number of parameters, hence no automatic initialization is performed.

Beyond positional association, no restriction is imposed, and no check is performed, by Tefigel on the function or subroutine signature, so that it is possible to supply a variable number of arguments to functions and subroutines. Currently, Tefigel supports up to 32 parameters.

Functions may set their return value by means of instruction retvalue.

Returning from a function or subroutine is automatically performed when the end of the file containing the function or subroutine is reached. Alternatively, instruction quit can be used to explicitly return from the function or subroutine.

A <code-file> is a file where each line is interpreted as a <command>.

Chapter 12 - Built-in Functions

12.1 - Purpose

Perform frequently needed routine tasks.

12.2 - Usage

Built-in functions are used in the same way as user-defined functions are used:

   [call] <built-in-function>(<parameter-list>)
   <call-key><built-in-function>(<parameter-list>)

12.3 - Description

A <built-in-function> is one of the subroutines and functions listed below.

Built-in functions have a higher precedence in comparison with file functions or subroutines, so that it is not possible to override a built-in function with a file function or subroutine carrying the same name.

By default built-in functions carry the lower-case names listed below, unless <control-variable> CMD_CASE is switched to upper-case mode, in which case their names are also switched to upper-case.

12.3.1 - File Handling

• cur_input
  Return name of current input file.

• cur_input(n)
  Return name of Tefigel input file at nesting level n. Nesting level starts at 0, thus CUR_INPUT(0) is equivalent to cur_input.

• cur_input_line
  Return current line number of current input file.

• cur_input_line(n)
  Return current line number of Tefigel input file at nesting level n. Nesting level starts at 0, thus CUR_INPUT_LINE(0) is equivalent to cur_input_line.

• cur_output
  Return name of current output file.

• cur_output_line
  Return current line number of current output file.

• file_readable(filename)
  Return 1 if filename can be opened for reading, 0 otherwise.

12.3.2 - Tag File Processing

• tag_file_process(filename,subroutine dir,case sensitive)
  Process tag file filename (typically, an XML or HTML file) applying corresponding user-defined Tefigel scripts from directory subroutine dir. The optional case sensitive flag, which defaults to 1, can be set to 0 for case-insensitive tag identifiers, such as HTML tags. Additional information on this subject is provided in a later chapter.

12.3.3 - CSV File Processing

• csv_file_process(filename,subroutine,separator)
  Process comma-separated value (CSV) file filename through subroutine using character separator as value delimiter. Additional information on this subject is provided in a later chapter.

12.3.4 - Output Formatting

• format(to_format,width,hdr,trl,h_line,t_line,filler)
  Format to_format, which can be a string or a file name, producing output lines of width characters, using filler as "background" character, according to the following scheme:

   A heading line, as specified by h_line
   hdr Text line #1, width characters long trl
   hdr Text line #2, width characters long trl
   hdr ................................... trl
   A trailing line, as specified by t_line

• tabs(string,t1,t2,t3,...)
  Return edited copy of input string, replacing tabs with blanks aligned to the positions specified by numerical parameters t1, t2, t3, etc. Default alignment values for t1, t2, t3, etc., are 8, 16, 24, etc.

12.3.5 - Variable Formatting

• fmt_float(printf_fmt,variable)
  Return string value of variable formatted as per double floating-point printf_fmt. Refer to the technical literature for valid printf_fmt strings.

12.3.6 - String Handling

• chr(number)
  Return the character (ASCII or ISO 8859-1) corresponding to the given number, which can be specified as a decimal, octal or hexadecimal number.

• length(string)
  Return length of string.

• make_id(<base-identifier>,<id-pattern>)
  Return an identifier built by applying the <id-pattern> to the given <base-identifier>, as explained in further detail below.

• replace(string,old string,new string)
  Return a string with all occurrences of old string replaced with corresponding occurrences of new string.

• substr(string,offset,n)
  Return substring of n characters starting from position offset (zero-based) of the given string.

• to_lower(STRING)
  Return STRING converted to lower case as in string.

• to_UPPER(string)
  Return string converted to upper case as in STRING.

• to_Upper(string)
  Return string with the first letter converted to upper case as in String.

• value(string)
  Return final value of string, which can be an arbitrarily complex sequence of dash-concatenated variables. This function is used to expand complex name-value associations, also referred to as <associative-variable>'s, such as plain or multi-dimensional arrays, or nested records.

12.3.7 - Data Group Handling

• group(separator,data field 1,data field 2,...)
  Return a data group (a dynamic record) with the specified data fields separated by the specified single-character separator.

• ungroup(data group,separator,variable 1,variable 2,...)
  Assigns the data fields from the specified data group to the specified variables using the specified single-character separator.

12.3.8 - List Processing

• new_list(list id)
  Create a new empty list identified by list id.

• new_list(list id,item1,item2,...)
  Create a new list identified by list id containing the specified items.

• delete_list(list id)
  Delete the list identified by list id.

• add_item(list id,item)
  Add item at the end of the list identified by list id.

• list_item_count(list id)
  Return number of items contained in the list identified by list id.

• list_contents(list id,prefix,suffix,separator)
  Return a string containing the items of the list separated by separator. If separator is omitted, it defaults to comma.
  The optional prefix and suffix allow to specify a leading and a trailing string for each item of the list.

• list_process(list id,processor)
  Apply processor (a user-defined Tefigel script) to each item contained in the list identified by list id. The processor is called with three arguments:
  1. the position (zero-based) of the current item in the list;
  2. the total number of items in the list;
  3. the current item.
  

12.3.9 - Word List Processing

• word(string,n,separator list)
  Return n-th word (zero-based) from string, using separator list as the set of separator characters. The separator list may be omitted, in which case its content defaults to blank and tab.

• word_count(string,separator list)
  Return number of words from string, using separator list as the set of separator characters. The separator list may be omitted, in which case its content defaults to blank and tab.

• word_list_process(string,processor,separator list)
  Apply processor (a user-defined Tefigel script) to each word contained in string, using separator list as the set of separator characters. The separator list may be omitted, in which case its content defaults to blank and tab. The processor is called with three arguments:
  1. the position (zero-based) of the current word in the string;
  2. the total number of words in string;
  3. the current word.
  

12.3.10 - Record Processing

• field(string,n,separator)
  Return n-th field (zero-based) from string, using separator as the field separator.

• field_count(string,separator)
  Return number of fields from string, using separator as the field separator.

12.3.11 - Date and Time

• date
  Return current system date, formatted as in "Tue Jan 14 2003".

• time
  Return current system time, formatted as in "23:17:51.255".

12.3.12 - Environment

• cur_platform
  Return name of current execution platform, one of "Linux", "Mac_OS_X", or "Windows".

• get_env(variable)
  Return value of the specified environment variable.

12.3.13 - Miscellaneous

• hook(which)
  Return name of <hook-subroutine> currently associated with the <hook-event> specified by which. Hook events are listed later in this guide.

• switch(which)
  Return current value of Tefigel internal switch specified by which. Internal switches are listed later in this guide.

12.3.14 - Additional Details on make_id

A <base-identifier> is the identifier of a variable, defined as a string of letters, decimal digits and underscores ('_'), as in this_is_a_Valid_BASE_id. An <id-pattern> is one of the strings listed below, providing a mnemonic identifier pattern specifying the desired format for the conversion of a given <base-identifier>. The following list shows the identifier resulting by applying an <id-pattern> to this_is_a_Valid_BASE_id.

• "abcdef": thisisavalidbaseid

• "abcDef": thisIsAValidBaseId

• "abcDEF": thisISAVALIDBASEID

• "Abcdef": Thisisavalidbaseid

• "AbcDef": ThisIsAValidBaseId

• "AbcDEF": ThisISAVALIDBASEID

• "ABCdef": THISisavalidbaseid

• "ABCDef": THISIsAValidBaseId

• "ABCDEF": THISISAVALIDBASEID

• "abc_def": this_is_a_valid_base_id

• "abc_Def": this_Is_A_Valid_Base_Id

• "abc_DEF": this_IS_A_VALID_BASE_ID

• "Abc_def": This_is_a_valid_base_id

• "Abc_Def": This_Is_A_Valid_Base_Id

• "Abc_DEF": This_IS_A_VALID_BASE_ID

• "ABC_def": THIS_is_a_valid_base_id

• "ABC_Def": THIS_Is_A_Valid_Base_Id

• "ABC_DEF": THIS_IS_A_VALID_BASE_ID

Chapter 13 - Input and Output

13.1 - Purpose

Manage input files, that provide text and commands for Tefigel, and output files, where the result of Tefigel's processing is stored.

13.2 - Usage

Change the source of input text and commands: the same instructions used to divide a complex file generation task into a set of more manageable, smaller tasks - namely process, process_if_readable, and call, described in the previous chapter - can also be used to perform this function, as Tefigel allows text and commands to be freely intermixed in any text file.

Attach, without any processing, the contents of a file to the current output file:

   attach <file-reference>

   output <file-reference>

   append <file-reference>

   echo text

   msg text

13.3 - Description

The distinction between file processing and subroutine or function calling in Tefigel is purely theoretical; in practice, calling a subroutine or a function implies the processing of the file that implements the called subroutine or function.

Chapter 14 - Packages and Libraries

14.1 - Purpose

Divide logically related subroutines and functions into packages, hierarchically grouped in collections called libraries.

14.2 - Usage

Define a logical root, called library path, for a set of function and subroutine packages, to be used as the starting point within the file-system when searching for files, functions, or subroutines, to be processed or called.

   library <library-path-specifier>

   library

14.3 - Description

A <library-path-specifier> can be either a valid directory pathname - absolute or relative - or a <variable> containing a string corresponding to a valid directory pathname.

File pathnames supplied as parameters to call and process instructions are first used literally by Tefigel to attempt completion of the relevant instruction; should this attempt fail, then the current library path - if previously defined by means of a library instruction - is used as a prefix to attempt the requested calling or processing of the supplied file pathname.

Tefigel allows to define only one library path at a time, to ensure that called or processed files can be uniquely identified.

Chapter 15 - Tag File Processing

15.1 - Purpose

Associate Tefigel processors (subroutines) with tag file contents and process a tag file (typically, XML or HTML files).

15.2 - Usage

Process a tag file applying corresponding user-defined Tefigel scripts from a given directory:

   [call] tag_file_process(<tag-file>,<subroutine-dir>,<case-sensitive>)

15.3 - Description

The built-in subroutine tag_file_process parses the specified <tag-file> and processes its contents through user-defined Tefigel scripts contained in directory <subroutine-dir>. Both <tag-file> and <subroutine-dir> are specified as <file-reference>'s. The optional <case-sensitive> flag, which defaults to 1, can be set to 0 for case-insensitive tag identifiers, such as HTML tags.

When processing <tag-file>, Tefigel calls subroutines from <subroutine-dir> according to the scheme described below. Only available subroutines are called: it is not required to supply all subroutines described below. Missing subroutines will result in Tefigel silently ignoring them.

1. On entering and exiting the processing of the tag file, Tefigel calls subroutines tag_tree.in and tag_tree.out respectively;

2. On entering and exiting the processing of each tag node, Tefigel calls subroutines tag_node.in and tag_node.out respectively;

3. On entering and exiting the processing of a tag node (element) identified by tagId, Tefigel calls subroutines tagId.in and tagId.out respectively;

4. Input text within one element tagId is processed through subroutines tag_node.tval and tagId.tval;

5. XML CDATA sections are processed through subroutine tag_cdata;

6. Comment tags are processed through subroutine tag_comment.

Chapter 16 - CSV File Processing

16.1 - Purpose

Process a comma-separated value (CSV) file (typically, a file containing row-column data or metadata) through a Tefigel processor (subroutine).

16.2 - Usage

Process a CSV file through a user-defined CSV subroutine (a Tefigel script):

   [call] csv_file_process(<CSV-file>,<CSV-subroutine>,<value-separator>)

16.3 - Description

The built-in subroutine csv_file_process reads the <CSV-file> and processes each line of its contents through the user-defined Tefigel script <CSV-subroutine>. Both <CSV-file> and <CSV-subroutine> are specified as <file-reference>'s. Parameter <value-separator> specifies the character separating each value in each line of <CSV-file>.

When processing <CSV-file>, Tefigel calls for each input line the specified <CSV-subroutine> passing the input line as a <parameter-list>, so that each value from the input line appears as a distinct input argument to the <CSV-subroutine>. Tefigel automatically sets the <special-function> argdelim to <value-separator>.

Chapter 17 - Filters

17.1 - Purpose

Associate Tefigel processors (subroutines) with text lines matching regular expressions.

17.2 - Usage

Activate a filter for a given regular expression:

   filter <file-reference> <regular-expression>

   filter <file-reference>

17.3 - Description

When an input line processed by Tefigel matches the <regular-expression> associated with a filter, a call to the subroutine specified by means of <file-reference> is automatically issued by Tefigel, providing as argument the whole text line via REG_0.

Chapter 18 - Links and Traps

18.1 - Purpose

Associate Tefigel processors (subroutines) with input character strings resembling identifiers.

18.2 - Usage

Associate a parametrical function call with a character string:

   link <link>=<subprogram-reference>

   trap <trap>=<subprogram-reference>

   unlink <link>
   untrap <trap>

   text text text text text text text text
   text text text <link> text text text
   text text text text text text text text
   text text text <link>(par1, par2, ...) text text text
   text text text text text text text text

   text text text text text text text text
   text text <trap> text text text
   text text text text text text text text
   <trap>
   text text text text text text text text

18.3 - Description

A <link> is a <variable> associated with a <file-reference>. On encountering a <link> in its input, Tefigel calls the associated <file-reference> providing the given arguments, if any, and replaces in output the <link> call with the string returned by the called function, if any.

A <trap> is a <variable> associated with a <file-reference>. On encountering a <trap> in its input, Tefigel calls the associated <file-reference> without arguments, and replaces in output the <link> call with the string returned by the called function, if any.

Chapter 19 - Name Spaces

19.1 - Purpose

Create nested scopes of variables, to enable saving and restoring of values stored in variables.

19.2 - Usage

Save contents of all non-global variables:

   push

   pop

19.3 - Description

All variables defined using a set instruction are kept in name spaces which are saved and restored either explicitly on issuing of push and pop instructions, or implicitly on call's to function and subroutines.

All variables defined using a globset are kept in a global name space which is unaffected by instructions push, pop and call.

Instruction process does not affect name spaces.

Chapter 20 - Miscellaneous

20.1 - Purpose

Perform miscellaneous instructions to control Tefigel operating mode and state or to access the underlying operating system.

20.2 - Usage

Execute an operating system shell command:

   system <command-string>

   version

   reset

   dump

   switch <control-variable>=<control-value>

   hook <hook-event>=<hook-subroutine>

   hook <hook-event>=

20.3 - Description

A <command-string> can be any command for the command interpreter (shell) of the underlying operating system.

Instruction reset resets all Tefigel variables and filters, and sets special characters, markers, control switches and event hooks to their default start-up state.

Instruction dump prints all available information about Tefigel status, including variables and name spaces, special characters, markers, filters, control switches, event hooks, and library path.

Switch <control-variable>'s may be set to the <control-value>'s described in the following list:

• AUTO_NEWLINE
  0: do not automatically print a CR-LF sequence after each output line;
  1: [default] print a CR-LF sequence after each output line.

• CMD_CASE
  0: Tefigel <instruction>'s are in upper case;
  1: [default] Tefigel <instruction>'s are in lower case.

• ON_MISSING_FILE
  0: silently ignore attempts to process or call non-existent files;
  1: print a warning message when attempting to process or call non-existent files;
  2: [default] print a fatal error message and terminate processing on attempts to process or call non-existent files.

• STRICT_CMDMARK
  0: consider input lines starting with an instruction as command lines, even if a command marker has been defined;
  1: [default] when a command marker is set, treat all input lines not starting with the current command marker as text lines.

• TRACE
  0: [default] do not print tracing messages about Tefigel processing;
  1: trace begin and end of file processing instruction execution;
  2: same as 1, moreover trace execution of all instructions;
  3: same as 2, moreover trace processing of all input lines, including text lines.

Chapter 21 - Further Reading

Additional information on the different aspects of the Somusar/Software Production Technique[tm] can be found in the other volumes of the Somusar/SoProTech[tm] Booklet Series, listed below.

Vol. I - somusar/SoProTech: An Introduction

An introduction to the Somusar/Software Production Technique[tm], a new, fast, and efficient technology to make high-quality multifacet software.