ack/util/LLgen/doc/LLgen.1

.\" $Id$
.TH LLGEN 1 "$Revision$"
.ad
.SH NAME
LLgen, an extended LL(1) parser generator
.SH SYNOPSIS
LLgen [ \-vxwans ] [ \-j[\fInum\fP] ] [ \-l\fInum\fP ] [ \-h\fInum\fP ] file ...
.SH DESCRIPTION
\fILLgen\fP
converts a context-free grammar into a set of
functions which form a recursive descent parser with no backtrack.
The grammar may be ambiguous;
ambiguities can be broken by user specifications.
.PP
\fILLgen\fP
reads each
\fIfile\fP
in sequence.
Together, these files must constitute a context-free grammar.
For each file,
\fILLgen\fP
generates an output file, which must be compiled by the
C-compiler.
In addition, it generates the files
\fILpars.c\fP
and
\fILpars.h.\fP
\fILpars.h\fP
contains the
\fIdefine\fP
statements that associate the
\fILLgen\fP-assigned `token-codes' with user declared `token-names'.
This allows other source files, for instance the source file
containing the lexical analyzer,
to access the token-codes by
using the token-names.
\fILpars.c\fP
contains the error recovery routines and tables. It must also
be compiled by the C-compiler. When the generated parser uses non-correcting
error recovery (
\fB\-n\fP 
option) 
\fILLgen\fP
also generates a file 
\fILncor.c\fP
that contains the non-correcting recovery mechanism.
.PP
\fILLgen\fP
will only update those output files that differ from their previous
version.
This allows
\fILLgen\fP
to be used with
\fImake\fP
(1) convieniently.
.PP
To obtain a working program, the user must also supply a
lexical analyzer, as well as
\fImain\fP
and
\fILLmessage\fP,
an error reporting routine;
\fILex\fP
(1) is a useful program for creating lexical analysers usable
by
\fILLgen\fP.
.PP
\fILLgen\fP accepts the following flags:
.IP \fB\-v\fP
create a file called
\fILL.output\fP,
which contains a description of the conflicts that
were not resolved.
If the flag is given more than once,
\fILLgen\fP
will be more "verbose".
If it is given three times, a complete description of the
grammar will be supplied.
.IP \fB\-o\fP
Specifies the location of the output files. If not set, they
are placed in the current directory.
.IP \fB\-x\fP
the sets that are computed are extended with the nonterminal
symbols and these extended sets are also included in the
\fILL.output\fP
file.
.IP \fB\-w\fP
no warnings are given.
.IP \fB\-a\fP
Produce ANSI C function headers and prototypes.
.IP \fB\-n\fP
Produce a parser with non-correcting error recovery.
.IP \fB\-s\fP
Simulate the calling of all defined subparsers in all semantic actions. When 
using non-correcting error recovery, subparsers that are called in semantic
actions may cause problems; this flag provides a `brute-force' solution. 
.IP \fB\-j\fP[\fInum\fP]
when this flag is given, \fILLgen\fP will generate dense switches,
so that the compiler can generate a jump table for it. This will only be
done for switches that have density between
\fIlow_percentage\fP and \fIhigh_percentage\fP, as explained below.
Usually, compilers generate a jumptable when the density of the switch
is above a certain threshold. When jump tables are to be used more often,
\fIhigh_percentage\fP must be set to this threshold, and \fIlow_percentage\fP
must be set to a minimum threshold. There is a time-space trade-off here.
.I num
is the minimum number of cases in a switch for the \fB\-j\fP option to be
effective. The default value (if
.I num
is not given) is 8.
.IP \fB\-l\fP\fInum\fP
The \fIlow_percentage\fP, as described above. Default value is 10.
.IP \fB\-h\fP\fInum\fP
The \fIhigh_percentage\fP, as described above. Default value is 30.
.SH FILES
LL.output                 verbose output file
.br
Lpars.c                   the error recovery routines
.br
Lncor.c                   non-correcting error recovery mechanism
.br
Lpars.h                   defines for token names
.SH "SEE ALSO"
\fIlex\fP(1)
.br
\fImake\fP(1)
.br
\fILLgen, an Extended LL(1) Parser Generator\fP
by C.J.H. Jacobs.
.br
\fITop-down Non-Correcting Error Recovery in LLgen\fP
by A.W van Deudekom and P.J. Kooiman
.SH DIAGNOSTICS
Are intended to be self-explanatory. They are reported
on standard error. A more detailed report is found in the
\fILL.output\fP
file.
.SH AUTHOR
Ceriel J. H. Jacobs
.br
The non-correcting error recovery mechanism is written by
A.W van Deudekom and P.J. Kooiman.