contrib/byacc/yacc.1

   1 .\" $Id: yacc.1,v 1.18 2012/01/15 18:12:28 tom Exp $
   2 .\"
   3 .\" .TH YACC 1 "July\ 15,\ 1990"
   4 .\" .UC 6
   5 .de ES
   6 .ne 8
   7 .nf
   8 .sp
   9 .in +4
  10 ..
  11 .de EE
  12 .in -4
  13 .fi
  14 ..
  15 .\" Bulleted paragraph
  16 .de bP
  17 .IP \(bu 4
  18 ..
  19 .TH YACC 1 "September 7, 2011" "Berkeley Yacc" "User Commands"
  20 .SH NAME
  21 Yacc \- an LALR(1) parser generator
  22 .SH SYNOPSIS
  23 .B yacc [ -dgilrtv ] [ \-b
  24 .I file_prefix
  25 .B ] [ \-p
  26 .I symbol_prefix
  27 .B ]
  28 .I filename
  29 .SH DESCRIPTION
  30 .B Yacc
  31 reads the grammar specification in the file
  32 .I filename
  33 and generates an LALR(1) parser for it.
  34 The parsers consist of a set of LALR(1) parsing tables and a driver routine
  35 written in the C programming language.
  36 .B Yacc
  37 normally writes the parse tables and the driver routine to the file
  38 .IR y.tab.c.
  39 .PP
  40 The following options are available:
  41 .TP 5
  42 \fB\-b \fP\fIfile_prefix\fR
  43 The
  44 .B \-b
  45 option changes the prefix prepended to the output file names to
  46 the string denoted by
  47 .IR file_prefix.
  48 The default prefix is the character
  49 .IR y.
  50 .TP
  51 .B \-d
  52 The \fB-d\fR option causes the header file
  53 .BR y.tab.h
  54 to be written.
  55 It contains #define's for the token identifiers.
  56 .TP
  57 .B \-g
  58 The
  59 .B \-g
  60 option causes a graphical description of the generated LALR(1) parser to
  61 be written to the file
  62 .BR y.dot
  63 in graphviz format, ready to be processed by dot(1).
  64 .TP
  65 .B \-i
  66 The \fB-i\fR option causes a supplementary header file
  67 .BR y.tab.i
  68 to be written.
  69 It contains extern declarations
  70 and supplementary #define's as needed to map the conventional \fIyacc\fP
  71 \fByy\fP-prefixed names to whatever the \fB-p\fP option may specify.
  72 The code file, e.g., \fBy.tab.c\fP is modified to #include this file
  73 as well as the \fBy.tab.h\fP file, enforcing consistent usage of the
  74 symbols defined in those files.
  75 .IP
  76 The supplementary header file makes it simpler to separate compilation
  77 of lex- and yacc-files.
  78 .TP
  79 .B \-l
  80 If the
  81 .B \-l
  82 option is not specified,
  83 .B yacc
  84 will insert \fI#line\fP directives in the generated code.
  85 The \fI#line\fP directives let the C compiler relate errors in the
  86 generated code to the user's original code.
  87 If the \fB-l\fR option is specified,
  88 .B yacc
  89 will not insert the \fI#line\fP directives.
  90 \&\fI#line\fP directives specified by the user will be retained.
  91 .TP
  92 \fB\-o \fP\fIoutput_file\fR
  93 specify the filename for the parser file.
  94 If this option is not given, the output filename is
  95 the file prefix concatenated with the file suffix, e.g., \fBy.tab.c\fP.
  96 This overrides the \fB-p\fP option.
  97 .TP
  98 \fB\-p \fP\fIsymbol_prefix\fR
  99 The
 100 .B \-p
 101 option changes the prefix prepended to yacc-generated symbols to
 102 the string denoted by
 103 .IR symbol_prefix.
 104 The default prefix is the string
 105 .BR yy.
 106 .TP
 107 .B \-P
 108 create a reentrant parser, e.g., "%pure-parser".
 109 .TP
 110 .B \-r
 111 The
 112 .B \-r
 113 option causes
 114 .B yacc
 115 to produce separate files for code and tables.  The code file
 116 is named
 117 .IR y.code.c,
 118 and the tables file is named
 119 .IR y.tab.c.
 120 The prefix "\fIy.\fP" can be overridden using the \fB\-b\fP option.
 121 .TP
 122 .B \-s
 123 suppress "\fB#define\fP" statements generated for string literals in
 124 a "\fB%token\fP" statement, to more closely match original \fByacc\fP behavior.
 125 .IP
 126 Normally when \fByacc\fP sees a line such as
 127 .ES
 128 %token OP_ADD "ADD"
 129 .EE
 130 .IP
 131 it notices that the quoted "ADD" is a valid C identifier,
 132 and generates a #define not only for OP_ADD,
 133 but for ADD as well,
 134 e.g.,
 135 .ES
 136 #define OP_ADD 257
 137 .br
 138 #define ADD 258
 139 .EE
 140 .IP
 141 The original \fByacc\fP does not generate the second "\fB#define\fP".
 142 The \fB\-s\fP option suppresses this "\fB#define\fP".
 143 .IP
 144 POSIX (IEEE 1003.1 2004) documents only names and numbers for "\fB%token\fP",
 145 though original \fByacc\fP and bison also accept string literals.
 146 .TP
 147 .B \-t
 148 The
 149 .B \-t
 150 option changes the preprocessor directives generated by
 151 .B yacc
 152 so that debugging statements will be incorporated in the compiled code.
 153 .TP
 154 .B \-v
 155 The
 156 .B \-v
 157 option causes a human-readable description of the generated parser to
 158 be written to the file
 159 .IR y.output.
 160 .TP
 161 .B \-V
 162 print the version number to the standard output.
 163 .TP
 164 .B \-y
 165 \fByacc\fP ignores this option,
 166 which bison supports for ostensible POSIX compatibility.
 167 .SH EXTENSIONS
 168 .B yacc
 169 provides some extensions for compatibility with bison and other implementations
 170 of yacc:
 171 .TP
 172 \fB %expect\fP \fInumber\fP
 173 tell \fByacc\fP the expected number of shift/reduce conflicts.
 174 That makes it only report the number if it differs.
 175 .TP
 176 \fB %expect-rr\fP \fInumber\fP
 177 tell \fByacc\fP the expected number of reduce/reduce conflicts.
 178 That makes it only report the number if it differs.
 179 This is (unlike bison) allowable in LALR parsers.
 180 .TP
 181 \fB %lex-param\fP { \fIargument-declaration\fP }
 182 By default, the lexer accepts no parameters, e.g., \fByylex()\fP.
 183 Use this directive to add parameter declarations for your customized lexer.
 184 .TP
 185 \fB %parse-param\fP { \fIargument-declaration\fP }
 186 By default, the parser accepts no parameters, e.g., \fByyparse()\fP.
 187 Use this directive to add parameter declarations for your customized parser.
 188 .TP
 189 \fB %pure-parser\fP
 190 Most variables (other than \fByydebug\fP and \fByynerrs\fP) are
 191 allocated on the stack within \fByyparse\fP, making the parser reasonably
 192 reentrant.
 193 .SH PORTABILITY
 194 According to Robert Corbett,
 195 .ES
 196     Berkeley Yacc is an LALR(1) parser generator.  Berkeley Yacc has been made
 197 as compatible as possible with AT&T Yacc.  Berkeley Yacc can accept any input
 198 specification that conforms to the AT&T Yacc documentation.  Specifications
 199 that take advantage of undocumented features of AT&T Yacc will probably be
 200 rejected.
 201 .EE
 202 .PP
 203 The rationale in
 204 .ES
 205 http://pubs.opengroup.org/onlinepubs/9699919799/utilities/yacc.html
 206 .EE
 207 .PP
 208 documents some features of AT&T yacc which are no longer required for POSIX
 209 compliance.
 210 .PP
 211 That said, you may be interested in reusing grammary files with some
 212 other implementation which is not strictly compatible with AT&T yacc.
 213 For instance, there is bison.
 214 Here are a few differences:
 215 .bP
 216 \fBYacc\fP accepts an equals mark preceding the left curly brace
 217 of an action (as in the original grammar file \fBftp.y\fP):
 218 .ES
 219         |       STAT CRLF
 220                 = {
 221                         statcmd();
 222                 }
 223 .EE
 224 .bP
 225 \fBYacc\fP and bison emit code in different order, and in particular bison
 226 makes forward reference to common functions such as yylex, yyparse and
 227 yyerror without providing prototypes.
 228 .bP
 229 Bison's support for "%expect" is broken in more than one release.
 230 For best results using bison, delete that directive.
 231 .bP
 232 Bison has no equivalent for some of \fByacc\fP's commmand-line options,
 233 relying on directives embedded in the grammar file.
 234 .bP
 235 Bison's "\fB\-y\fP" option does not affect bison's lack of support for
 236 features of AT&T yacc which were deemed obsolescent.
 237 .
 238 .SH DIAGNOSTICS
 239 If there are rules that are never reduced, the number of such rules is
 240 reported on standard error.
 241 If there are any LALR(1) conflicts, the number of conflicts is reported
 242 on standard error.