The grg program takes one argument, the name of the GRG file
to use. This can be given with or without the .grg extension. If the
.grg extension is not given with the filename and a filename without
the extension is found then this will be used, else the .grg extension
will be automatically appended and a filename must exist with this extension.
The default output file name will be the basename of the GRG file
with .tex as the replacement extension. For example, if the
GRG file to be used is test.grg then the program would be
called as grg test (or grg test.grg) and the output file produced
by the program, according to the directions given in the test.grg file
would be test.tex.
The default output filename and extension can be easily changed from within the GRG file. The output filename can also be changed at certain points during generation of the output so that multiple files can be created from one input database file.
The .gpp and .pt extensions (which .grg replaces) are
deprecated. It is no longer automatically appended when not specified.
These older extensions should not be used.
There is only one option that can be given to the grg program, and this
is -d[1234]. All variants enable debug mode. When the -d option is
used the program will display the GRG file subsequent to preprocessing
and will also dump the contents of user defined macros, equates, environment
variables, as well as the definitions assigned to system variables, and the
text bodies. The -d1 variant dumps DFA state tables (from pattern
matching definitions). The -d2 variant does the same as -d1 but
also dumps the actual processing of pattern definitions. The -d3 variant
does the same as -d but also dumps the memory allocations during
pre-preocessing and output processing. The -d4 variant dumps details of
the loading and field references of any .dbf file.
The GRG file is processed in two stages (see section Structure and section Processing Sequence for more details). The first stage reads all the predefined macro definitions and expands any user defined macros. The entire file is broken down into its component parts and stored internally. The output file is then generated in the second stage by writing the stored text bodies at the appropriate places. The record text body is written for each record in the master database file (subject to sort and filter definitions), and the page text bodies are written at the start of each page. The header text body is written at the start before anything else and the footer text body is written at the end after everything else. References to database fields, interpolation of user text bodies, and processing of equates are all done at this stage.
The GRG file can have as its first line a #! sequence followed by the
path of the grg program and can then be made self-executable exactly
like a shell script. Note however that only a line starting with # as the
first line in the GRG file is interpreted this way and that # does
not start a comment line in any other place in the file (as it would in a
shell script). Command line options and arguments can be included after the
path so a line like #!/usr/local/bin/grg -d is acceptable. This is one
situation where it is common to not have the .grg extension as part
of the filename.
The above allows the GRG file to act as a filter in a pipe by defining the database input file to be standard input and redefining the output file to be standard output.
The grg program will accept any number of additional command line
arguments where each is a predefined macro and its arguments (these are
discussed in more detail in section Predefined Macros). These are processed twice. Once before
parsing the GRG file and once afterwards. This is so that the arguments
can affect the parsing of the GRG file but also so that their value can
overwrite any value in the GRG file since parsing the file would normally
rewrite their value. The processing order is described in more detail in
section Processing Sequence.
A predefined macro argument can include quotes and escaped quotes. These must
be given differently in a command line argument to prevent shell escape.
The format for a nested quote is \" and for a nested escaped quote
is \\\". For example, grg fubar.grg "%%equate eq_init 1>>_eq_trace", is a command line which
starts up tracing while processing equates in fubar.grg. Note that it
is safest when using command line predefined macros to always include a
terminating macro to avoid any possible continuation errors (when the actual
file is processed). So it is better to do:
grg fubar.grg "%%equate eq_init 1>>_eq_trace" "%%end"
Go to the first, previous, next, last section, table of contents.