| iMatix home page
| << | < | > | >>
GSLgen GSLgen
Version 2.0

Script Commands

Output File Manipulation

.output

  .output <filename>

closes the current output file, if one is open, and opens a new one.

Examples:

  .output "myfile.c"
  .output FILENAME

where FILENAME is an identifier whose value is the desired file name.

.append

  .append <filename>

closes the current output file, if one is open, and opens a previously existing one and prepares to extend it.

See the description of the output command for examples.

.close

  .close

closes the current output file, if one is open.

.literal

  .literal (from <filename> | <expr> || << <terminator>)

Copies text directly to the output file, without substition. The text can come from another file, a GSL expression, or from lines in the script, ending with a line beginning with the specified terminator.

Examples:

  .literal from "file.txt"
  .literal "whatever you want"
  .literal << .endliteral
  Lines are now copied without substitution of
  things like $(abc).
  .endliteral

Control Structures

.for

  .for [[<extended-scope>] .] <name> [as <alias>] [where <expr>] [by <expr>]
  .for  [<extended-scope>] .         [as <alias>] [where <expr>] [by <expr>]

opens a scope and introduces a loop. The following block of code is processed once for each item specified. If no scope if specified, the most recently opened scope is assumed. The items processed are those children of the XML item corresponding to this scope. If the first form is used only children with the specified name are processed; if the second form is used, all children are processed.

The alias allows you to give the new scope a name other than the specified item name; use this when you nest scopes which would otherwise have the same name or to supply a scope name when using the second form.

The where clause allows you to specify a condition which must be satisfied for the code to be processed; the expression is evaluated before any processing occurs.

The by clause allows you to sort the items according to the result of evaluating the expression for each item. If no by clause is specified the items are processed from the oldest to the youngest, the same order in which they are described in the XML file.

The expressions in the where and by clauses are evaluated within the new scope. This means that they can access attributes of the iterating item.

During the evaluation of the `by' and `where' expressions, as well as during the processing of the code, the function `item (name)' returns the number of the child (1, 2, ...) of the current item. This number is associated with the XML item itself and is not affected by a `by' or `where' clause.

Within the loop, but not within `by' and `where' expressions, the function `index (name)' returns the index of the current iteration. This is associated with the loop, so that it always takes consecutive values.

.endfor

  .endfor

terminates a .for loop, closing the scope.

Examples:

  .for RECORD.FIELD by NAME
  $(FIELD.NAME)
  .endfor

outputs the names of the fields of the current record, sorted in alphabetical order.

  .for FIELD where item () = 2
  something
  .endfor

processes only the second item named FIELD.

.if

  .if <expr>

starts conditional processing of the following block of code if the result of evaluating the expression is non-zero.

.elsif

  .elsif <expr>

may follow an `if' construct. Any number of `elsif' constructs may be used.

.else

  .else

may follow an `if' or `elsif' construct. The following block of code is processed if the logical value of all the expressions is FALSE.

.endif

  .endif

terminates a conditional processing construct.

Examples:

  .if NAME = "JAMES"
  something
  .elsif NAME = "JAIME"
  something else
  .else
  everything else
  .endif

.while

  .while <expr>

introduces a loop. The following block of code is processed repeatedly as long as the expression evaluates to a logical value of TRUE, that is not equal to zero. Expression evaluation takes place before the code is processed, so that the code will never be processed if the expression evaluates to FALSE the first time.

.endwhile

  .endwhile

terminates a `while' loop.

Examples:

  .define I = 0
  .while I < 5
  loop iteration number $(I)
  .endwhile

.next

  .next

inside a `for' or `while' loop causes immediate iteration, skipping execution of any code between the `next' command and the `endfor' or `endwhile' statement.

.last

  .last

inside a `for' or `while' loop causes the loop to terminate iteration immediately. Control passes to the line following the `endfor' or `endwhile' statement.

Symbol Definition

.define

  .[define] <identifier> [<operator>]= [ <expr> ]

defines or undefines an XML attribute or item value. Note that the word `define' is itself optional; any GSL line which does not begin with a reserved GSL word is an implied `define'. There are several different forms, described below:

If the scope is omitted from the identifier specification, GSLgen searches open scopes for one in which an attribute of the specified name exists. If none is found, it uses the first open scope, which effectively makes the identifier a global variable.

If the name is omitted from an identifier, the value of the XML item is modified, rather than that of an attribute.

If neither scope nor name is specified, GSLgen defines the value of the XML item associated with the most recently open scope. This removes any existing value and appends the new value after any children.

If the expression is left empty then the symbol becomes undefined. If the expression ends with a default operator `?' but no default expression then an undefined expression causes the symbol to becume undefined rather than producing a runtime error.

If a multiplicative, additive or default operator is specified then the value assigned to the symbol is the result of that operator and the supplied expression to the former value of the operator.

Examples:

  .define x = 1

assigns the value 1 to the identifier x in the most recently opened open scope where x is already defined, or in the global scope if x is undefined.

  .define ->child. = "Value"

assigns the string `Value' to the value of the first XML item child which is a child of the XML item corresponding to the most recently opened scope.

  .x *= 2

multiplies the value of the identifier x by 2.

  .x ?= y ? z ?

does nothing if x is already defined; otherwise assigns it the value of y, or if y is undefined then the value of z, or if z is undefined, x remains undefined.

XML Manipulation

.new

  .new <name> [to <extended-scope> | before <before-scope> | after <after-scope>] [as <alias>]

creates a new XML item. This allows you to build new items in the data tree. The new item has the specified name and is a child of the XML item corresponding to th specified scope, or the most recently opened scope if none is specified. If a `before-scope' or `after-scope' is specified, then then it must be the name of an open scope corresponding to a child of <scope>, and the new item is inserted just before <before-scope> or just after <after-scope>; otherwise the new item is inserted after any existing children. The construct creates a new scope with the name specified by the alias or the item name if there is no alias. The following block of code is processed exactly once within this new scope. It would typically done some attributes of the new XML item. These values can then be retrieved during a future iteration of a `for' construct through the new item.

.endnew

  .endnew

terminates a `new' construct.

Examples:

  .new RECORD.FIELD
  .    define FIELD.NAME = "NEW FIELD"
  .endnew
  .for RECORD.FIELD as OLDFIELD where NAME = "OLD FIELD"
  .    new RECORD.FIELD before OLDFIELD
  .        define FIELD.NAME = "NEW FIELD"
  .    endnew
  .endfor

.delete

  .delete <extended-scope>

deletes the XML item (and any descendents) corresponding to the specified scope. Once the item has been deleted, any attempt to reference it produces an error.

The function `delete (name)' allows you to determine whether the XML item associated with a scope has been deleted.

Examples:

  .for RECORD.FIELD where TYPE = "COMMENT"
  .    delete FIELD
  .endfor

.copy

  .copy [<from-scope>] [ to <parent-scope> | after <after-scope> | before <before-scope> ] [as <name>]

makes a copy the XML item associated with <from-scope> (or the most recently opened scope if not specified) at the point specified by either the new parent (`to') or new sibling (`after' or `before'), or as a child of the XML item of the most recently opened scope if no parent of sibling is specified. The `as' clause allows you to the new item to have a different name from the old item.

Examples:

  .for DATABASE.TABLE
  .    for RECORD.FIELD
  .        copy FIELD to TABLE
  .    endfor
  .endfor

.move

  .move [<from-scope>] [ to <parent-scope> | after <after-ident> | before <before-ident> ] [as <name>]

re-attaches an XML item at the point specified by a `to', `after' or `before' clause, renaming it to the name specified in the `as' clause, if specified.

GSLgen detects any attempt to make an XML item its own descendent.

Note that moving an XML does not invalidate any scope associated with it. If the moved XML item is associated with a future iteration of a `for' loop, the iteration will still take place even if the item is no longer a child of the extended scope from the `for' instruction.

Examples:

  .for TABLE.RECORD
  .    for RECORD.FIELD
  .        move FIELD to RECORD
  .    endfor
  .endfor

.sort

  .sort [[<extended-scope>] .] [<name>] [as <alias>] by <expr>

Sorts the specified XML items. A scope is created with each item in turn and is used to evaluate the expression. The result is then used to sort the items. The `as' clause allows you to give the created scope a different name. After execution, the specified XML items are in order and after any other children of the same parent.

.load

  .load <filename> [ to <parent-scope> | after <after-ident> | before <before-ident> ] [as <name>]

Loads the contents of an XML file at the place specified by a `to', `after' or `before' clause, renaming the items to the name specified in the `as' clause, if specified.

Note that `load' is deprecated. Use `xml' instead.

.xml

  .xml [ to <parent-scope> | after <after-ident> | before <before-ident> ] [as <name>] (from <filename> | <expr> || << <terminator>)

imports XML data into the the specified point. The data can come from a file, an expression, or from lines in the script, ending with a line beginning with the specified terminator. Note that in this form, GSLgen uses the lines literally, without substitution.

Examples:

  .xml from "data.xml"
  .xml to RECORD '<field name="date"/><field name="time"/>'
  .xml after SISTER << .endxml
  <text>
  All this text is used literally even though it contains stuff
  that looks like a substitution, eg $(abc).
  </text>
  .endxml

.save

  .save <extended-scope> as <filename>

creates an XML file representing the XML item corresponding to the specified scope. This recursively includes all child items.

Script Manipulation

.include

  .include <filename>

includes another script file. Deprecated - see `gsl'

.gsl

  .gsl from <filename>
  .gsl <expr>

interprets the contents of the specified file or expression as GSL, just as though it were part of the script.

Examples:

  .gsl "header.gsl"
  .gsl GSL.TEXT

.template

  .template (0 | 1)

Turns template mode on or off.

.endtemplate

Terminates the block introduced by a `template' instruction.

Macros and Functions

Macros and functions are pieces of GSL which can be invoked with parameters. The only difference between a macro and as function is that macros are interpreted in template mode and functions in script mode.

.macro

  .macro <name> [(<param> [, <param>] ...)]

introduces a macro definition with the specified name.

.endmacro

  .endmacro

terminates a macro definition.

.function

.function <name> [([<param>] [, <param>] ...)]

introduces a function definition with the specified name.

.endfunction

  .endfunction

terminates a function definition.

.invoke

  .[invoke] <name> [([<expr>] [, [<expr>]])] ...)]

causes a previously defined macro or function to be processed. Note that the keyword `invoke' is optional, so that a function can be invoked by simply giving its name and a (possibly empty) parameter list.

This creates a special scope with the name of the macro or function, and attributes corresponding to the parameters value of the parameters. This scope does not count in numeric scope specifications and cannot have children. It can be used to define local variables, but must in this case be specified by name.

The number of expressions (or empty expressions) must match exactly the number of parameters in the definition. An empty expression or an expression whose value is undefined causes the corresponding parameter to be undefined during processing of the macro code.

Examples:

  .macro echotwice (text)
  .    echo text
  .    echo text
  .endmacro
  ...
  .echotwice ("Hello")
  .function recursive (N)
      recursive.localvar = N - 1
      recursive (localvar)
  .endfunction
  .function assign (dest, source)
      .$(dest) = source
  .endfunction

Miscellaneous

.echo

  .echo <expr>

outputs the given expression to the standard output.

.abort

  .abort <expr>

outputs the given expression to the standard output and halts GSLgen operation.


| << | < | > | >>
| The Generator Script Language | Introduction | Installing GSLgen | Using GSLgen | The General Schema Language (GSL) | Script Commands
iMatix
Copyright © 1996-2000 iMatix