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

Using GSLgen

Command-line Syntax

To run GSLgen, use the following syntax

  gslgen -<option> ... -<attr>[:<value>] ... filename ...

If the filename has no extension, GSLgen tries to find an XML file with that name, or with the extension `.xml' (recognised by the <?xml... tag on the first line). If it finds no XML file it tries to find a file with that name or the extension `.gsl', which it interprets as a GSL file.

Options currently recognised by GSLgen are:

q, quiet
Suppresses copyright and other messages from GSLgen.

Command-line attributes are loaded with an XML file and are available to a script. This allows paramaters to be passed from the command line to the script. The attribute script can be set to the name of a GSL file to be interpreted.

If GSLgen found an XML file, it loads it, then looks for an attribute named script of the top-level item. This name is used to find a GSL script to interpret. If GSLgen found a GSL file, it begins interpreting it without loading an XML file.

Getting Started

How do I use GSLgen?

  • If you have an XML file entitled test.xml, the simplest way to invoke GSLgen is
  gslgen test
  • In this case the script must be defined as an attribute of the top-level item defined in test.xml. If this is not the case, or if you wish to use a different script, use the form
  gslgen -script:xxxxxxx.gsl test.xml

A Hello World Example

Try a `hello world' test:

Create a file called `hello.gsl':

  echo "hello world"

Run this using `gslgen hello'. This shows a trivial GSL script running without any XML data. The script does some work, and ends. Let's look at how we process an XML data file.

Create a file called `hello.xml':

  <WORLD NAME="World">
      <HELLO NAME="Hello" />

Change `hello.gsl' (we now use a dot in the first column):

  .for world
  .  for hello
  .    echo "$(name) $(world.name)"
  .  endfor

Then, run GSLgen:

  gslgen -script:hello.gsl hello.xml

A More Complex Example

This is a script which generates a simple DOS batch file to install programs by copying them into various directories. It's something you might want to generate for specific projects:

  .- install.gsl   Generates install script from install.xml
  .output "install.bat"
  @echo off
  rem generated by gslgen from install.xml, $(script)
  .for file
  .  if    type = "binary"
  echo $(name) -- \\usr\\bin
  copy $(name) \\usr\\bin >nul
  .  elsif type = "script"
  echo $(name) -- \\usr\\lib
  copy $(name) \\usr\\lib >nul
  .  elsif type = "doc"
  echo $(name) -- \\usr\\doc
  copy $(name) \\usr\\doc >nul
  .  endif
  copy $(name) install >nul

The input is an XML file like this:

  <?xml version="1.0"?>
  <INSTALL script="install.gsl">
  <FILE name="gslgen.exe"  type="binary" />
  <FILE name="gslgen.htm"  type="doc"    />
  <FILE name="install.gsl" type="script" />
  <FILE name="hello.gsl"   type="script" />

We run GSLgen to process the XML file:

  gslgen install

This is the result:

  @echo off
  rem generated by gslgen from install.xml, install.gsl
  echo gslgen.exe -- \usr\bin
  copy gslgen.exe \usr\bin >nul
  copy gslgen.exe install >nul
  echo gslgen.htm -- \usr\doc
  copy gslgen.htm \usr\doc >nul
  copy gslgen.htm install >nul
  echo install.gsl -- \usr\lib
  copy install.gsl \usr\lib >nul
  copy install.gsl install >nul
  echo hello.gsl -- \usr\lib
  copy hello.gsl \usr\lib >nul
  copy hello.gsl install >nul

What's Going On?

The scripts hello.gsl and install.gsl contain lines with a point (`.') in the first column. These are called script lines and contain instructions to be interpreted. The script install.gsl also contains lines which do not begin with a point. These are called template lines and contain text to be output when the line is interpreted. They may also contain substitution symbols which look like the text `$(name)'. Notice that each occurrence of the backslash character is repeated in the script, but not in the output file. This is because GSLgen, like many programs, uses the backslash to introduce a special character, and two backslashes are required to output one backslash.

The `for' instruction requires some explanation; it is the way to iterate through XML data. This is somewhat redundant in the case of `hello.gsl' since there is only one instance of the XML items `WORLD' and `HELLO'. The `for' instruction makes available the attributes of the XML item of the same name. Thus the attributes `name' and `type' of the items named `FILE' in `install.xml' can be used in the lines between the `for' and corresponding `endfor'. Notice that in the first example, the items `WORLD' and `HELLO' both contain an attribute `NAME' which the script accesses independently by specifying `$(world.name)' or `$(name)'. It could also use `$(hello.name)' in the second case; if the attribute name appears alone then GSLgen searches for an attribute with that name in all open XML items beginning with the most recently opened.

Another Complex Example

Try this command:

  gslgen -script:xmlfile.gsl spfper.dbm

This generates a C function, spfper.c, which handles a data table (in this case a list of persons) as an XML file, with functions to read, save, and update data in this table. This is a good example of a complex GSL script, and one that is used in real life to handle data objects in iMatix Studio.

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