build/byacc/yacc.1

   1 .\" $Id: yacc.1,v 1.12 2011/09/08 00:40:44 tom Exp $
   2 .\"
   3 .\" .TH YACC 1 "July\ 15,\ 1990"
   4 .\" .UC 6
   5 .TH YACC 1 "September 7, 2011" "Berkeley Yacc" "User Commands"
   6 .SH NAME
   7 Yacc \- an LALR(1) parser generator
   8 .SH SYNOPSIS
   9 .B yacc [ -dgilrtv ] [ \-b
  10 .I file_prefix
  11 .B ] [ \-p
  12 .I symbol_prefix
  13 .B ]
  14 .I filename
  15 .SH DESCRIPTION
  16 .B Yacc
  17 reads the grammar specification in the file
  18 .I filename
  19 and generates an LALR(1) parser for it.
  20 The parsers consist of a set of LALR(1) parsing tables and a driver routine
  21 written in the C programming language.
  22 .B Yacc
  23 normally writes the parse tables and the driver routine to the file
  24 .IR y.tab.c.
  25 .PP
  26 The following options are available:
  27 .TP
  28 \fB\-b \fP\fIfile_prefix\fR
  29 The
  30 .B \-b
  31 option changes the prefix prepended to the output file names to
  32 the string denoted by
  33 .IR file_prefix.
  34 The default prefix is the character
  35 .IR y.
  36 .TP
  37 .B \-d
  38 The \fB-d\fR option causes the header file
  39 .BR y.tab.h
  40 to be written.
  41 It contains #define's for the token identifiers.
  42 .TP
  43 .B \-g
  44 The
  45 .B \-g
  46 option causes a graphical description of the generated LALR(1) parser to
  47 be written to the file
  48 .BR y.dot
  49 in graphviz format, ready to be processed by dot(1).
  50 .TP
  51 .B \-i
  52 The \fB-i\fR option causes a supplementary header file
  53 .BR y.tab.i
  54 to be written.
  55 It contains extern declarations
  56 and supplementary #define's as needed to map the conventional \fIyacc\fP
  57 \fByy\fP-prefixed names to whatever the \fB-p\fP option may specify.
  58 The code file, e.g., \fBy.tab.c\fP is modified to #include this file
  59 as well as the \fBy.tab.h\fP file, enforcing consistent usage of the
  60 symbols defined in those files.
  61 .IP
  62 The supplementary header file makes it simpler to separate compilation
  63 of lex- and yacc-files.
  64 .TP
  65 .B \-l
  66 If the
  67 .B \-l
  68 option is not specified,
  69 .B yacc
  70 will insert \fI#line\fP directives in the generated code.
  71 The \fI#line\fP directives let the C compiler relate errors in the
  72 generated code to the user's original code.
  73 If the \fB-l\fR option is specified,
  74 .B yacc
  75 will not insert the \fI#line\fP directives.
  76 \&\fI#line\fP directives specified by the user will be retained.
  77 .TP
  78 \fB\-o \fP\fIoutput_file\fR
  79 specify the filename for the parser file.
  80 If this option is not given, the output filename is
  81 the file prefix concatenated with the file suffix, e.g., \fBy.tab.c\fP.
  82 This overrides the \fB-p\fP option.
  83 .TP
  84 \fB\-p \fP\fIsymbol_prefix\fR
  85 The
  86 .B \-p
  87 option changes the prefix prepended to yacc-generated symbols to
  88 the string denoted by
  89 .IR symbol_prefix.
  90 The default prefix is the string
  91 .BR yy.
  92 .TP
  93 .B \-P
  94 create a reentrant parser, e.g., "%pure-parser".
  95 .TP
  96 .B \-r
  97 The
  98 .B \-r
  99 option causes
 100 .B yacc
 101 to produce separate files for code and tables.  The code file
 102 is named
 103 .IR y.code.c,
 104 and the tables file is named
 105 .IR y.tab.c.
 106 The prefix "\fIy.\fP" can be overridden using the \fB\-b\fP option.
 107 .TP
 108 .B \-t
 109 The
 110 .B \-t
 111 option changes the preprocessor directives generated by
 112 .B yacc
 113 so that debugging statements will be incorporated in the compiled code.
 114 .TP
 115 .B \-v
 116 The
 117 .B \-v
 118 option causes a human-readable description of the generated parser to
 119 be written to the file
 120 .IR y.output.
 121 .TP
 122 .B \-V
 123 print the version number to the standard output.
 124 .SH EXTENSIONS
 125 .B yacc
 126 provides some extensions for compatibility with bison and other implementations
 127 of yacc:
 128 .TP
 129 \fB %expect\fP \fInumber\fP
 130 tell \fByacc\fP the expected number of shift/reduce conflicts.
 131 That makes it only report the number if it differs.
 132 .TP
 133 \fB %expect-rr\fP \fInumber\fP
 134 tell \fByacc\fP the expected number of reduce/reduce conflicts.
 135 That makes it only report the number if it differs.
 136 This is (unlike bison) allowable in LALR parsers.
 137 .TP
 138 \fB %lex-param\fP { \fIargument-declaration\fP }
 139 By default, the lexer accepts no parameters, e.g., \fByylex()\fP.
 140 Use this directive to add parameter declarations for your customized lexer.
 141 .TP
 142 \fB %parse-param\fP { \fIargument-declaration\fP }
 143 By default, the parser accepts no parameters, e.g., \fByyparse()\fP.
 144 Use this directive to add parameter declarations for your customized parser.
 145 .TP
 146 \fB %pure-parser\fP
 147 Most variables (other than \fByydebug\fP and \fByynerrs\fP) are
 148 allocated on the stack within \fByyparse\fP, making the parser reasonably
 149 reentrant.
 150 .
 151 .SH DIAGNOSTICS
 152 If there are rules that are never reduced, the number of such rules is
 153 reported on standard error.
 154 If there are any LALR(1) conflicts, the number of conflicts is reported
 155 on standard error.