util/LLgen/LLgen.1

   1 .\" $Id: LLgen.1,v 2.14 1999/04/23 14:15:43 ceriel Exp $
   2 .TH LLGEN 1 "$Revision: 2.14 $"
   3 .ad
   4 .SH NAME
   5 LLgen, an extended LL(1) parser generator
   6 .SH SYNOPSIS
   7 LLgen [ \-vxwans ] [ \-j[\fInum\fP] ] [ \-l\fInum\fP ] [ \-h\fInum\fP ] file ...
   8 .SH DESCRIPTION
   9 \fILLgen\fP
  10 converts a context-free grammar into a set of
  11 functions which form a recursive descent parser with no backtrack.
  12 The grammar may be ambiguous;
  13 ambiguities can be broken by user specifications.
  14 .PP
  15 \fILLgen\fP
  16 reads each
  17 \fIfile\fP
  18 in sequence.
  19 Together, these files must constitute a context-free grammar.
  20 For each file,
  21 \fILLgen\fP
  22 generates an output file, which must be compiled by the
  23 C-compiler.
  24 In addition, it generates the files
  25 \fILpars.c\fP
  26 and
  27 \fILpars.h.\fP
  28 \fILpars.h\fP
  29 contains the
  30 \fIdefine\fP
  31 statements that associate the
  32 \fILLgen\fP-assigned `token-codes' with user declared `token-names'.
  33 This allows other source files, for instance the source file
  34 containing the lexical analyzer,
  35 to access the token-codes by
  36 using the token-names.
  37 \fILpars.c\fP
  38 contains the error recovery routines and tables. It must also
  39 be compiled by the C-compiler. When the generated parser uses non-correcting
  40 error recovery (
  41 \fB\-n\fP
  42 option)
  43 \fILLgen\fP
  44 also generates a file
  45 \fILncor.c\fP
  46 that contains the non-correcting recovery mechanism.
  47 .PP
  48 \fILLgen\fP
  49 will only update those output files that differ from their previous
  50 version.
  51 This allows
  52 \fILLgen\fP
  53 to be used with
  54 \fImake\fP
  55 (1) convieniently.
  56 .PP
  57 To obtain a working program, the user must also supply a
  58 lexical analyzer, as well as
  59 \fImain\fP
  60 and
  61 \fILLmessage\fP,
  62 an error reporting routine;
  63 \fILex\fP
  64 (1) is a useful program for creating lexical analysers usable
  65 by
  66 \fILLgen\fP.
  67 .PP
  68 \fILLgen\fP accepts the following flags:
  69 .IP \fB\-v\fP
  70 create a file called
  71 \fILL.output\fP,
  72 which contains a description of the conflicts that
  73 were not resolved.
  74 If the flag is given more than once,
  75 \fILLgen\fP
  76 will be more "verbose".
  77 If it is given three times, a complete description of the
  78 grammar will be supplied.
  79 .IP \fB\-x\fP
  80 the sets that are computed are extended with the nonterminal
  81 symbols and these extended sets are also included in the
  82 \fILL.output\fP
  83 file.
  84 .IP \fB\-w\fP
  85 no warnings are given.
  86 .IP \fB\-a\fP
  87 Produce ANSI C function headers and prototypes.
  88 .IP \fB\-n\fP
  89 Produce a parser with non-correcting error recovery.
  90 .IP \fB\-s\fP
  91 Simulate the calling of all defined subparsers in all semantic actions. When
  92 using non-correcting error recovery, subparsers that are called in semantic
  93 actions may cause problems; this flag provides a `brute-force' solution.
  94 .IP \fB\-j\fP[\fInum\fP]
  95 when this flag is given, \fILLgen\fP will generate dense switches,
  96 so that the compiler can generate a jump table for it. This will only be
  97 done for switches that have density between
  98 \fIlow_percentage\fP and \fIhigh_percentage\fP, as explained below.
  99 Usually, compilers generate a jumptable when the density of the switch
 100 is above a certain threshold. When jump tables are to be used more often,
 101 \fIhigh_percentage\fP must be set to this threshold, and \fIlow_percentage\fP
 102 must be set to a minimum threshold. There is a time-space trade-off here.
 103 .I num
 104 is the minimum number of cases in a switch for the \fB\-j\fP option to be
 105 effective. The default value (if
 106 .I num
 107 is not given) is 8.
 108 .IP \fB\-l\fP\fInum\fP
 109 The \fIlow_percentage\fP, as described above. Default value is 10.
 110 .IP \fB\-h\fP\fInum\fP
 111 The \fIhigh_percentage\fP, as described above. Default value is 30.
 112 .SH FILES
 113 LL.output                 verbose output file
 114 .br
 115 Lpars.c                   the error recovery routines
 116 .br
 117 Lncor.c                   non-correcting error recovery mechanism
 118 .br
 119 Lpars.h                   defines for token names
 120 .SH "SEE ALSO"
 121 \fIlex\fP(1)
 122 .br
 123 \fImake\fP(1)
 124 .br
 125 \fILLgen, an Extended LL(1) Parser Generator\fP
 126 by C.J.H. Jacobs.
 127 .br
 128 \fITop-down Non-Correcting Error Recovery in LLgen\fP
 129 by A.W van Deudekom and P.J. Kooiman
 130 .SH DIAGNOSTICS
 131 Are intended to be self-explanatory. They are reported
 132 on standard error. A more detailed report is found in the
 133 \fILL.output\fP
 134 file.
 135 .SH AUTHOR
 136 Ceriel J. H. Jacobs
 137 .br
 138 The non-correcting error recovery mechanism is written by
 139 A.W van Deudekom and P.J. Kooiman.