ack/util/LLgen/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\-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
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.