yacc.1

   1 .\" $Id: yacc.1,v 1.28 2019/06/16 17:03:33 tom Exp $
   2 .\"
   3 .\" .TH YACC 1 "July\ 15,\ 1990"
   4 .\" .UC 6
   5 .ds N Yacc
   6 .ds n yacc
   7 .de Ex
   8 .RS +7
   9 .PP
  10 .nf
  11 .ft CW
  12 ..
  13 .de Ee
  14 .fi
  15 .ft R
  16 .RE
  17 ..
  18 .\" Escape single quotes in literal strings from groff's Unicode transform.
  19 .ie \n(.g .ds AQ \(aq
  20 .el       .ds AQ '
  21 .ie \n(.g .ds `` \(lq
  22 .el       .ds `` ``
  23 .ie \n(.g .ds '' \(rq
  24 .el       .ds '' ''
  25 .\" Bulleted paragraph
  26 .de bP
  27 .ie n  .IP \(bu 4
  28 .el    .IP \(bu 2
  29 ..
  30 .TH YACC 1 "June 16, 2019" "Berkeley Yacc" "User Commands"
  31 .SH NAME
  32 \*N \- an LALR(1) parser generator
  33 .SH SYNOPSIS
  34 .B \*n [ -BdgilLPrtvVy ] [ \-b
  35 .I file_prefix
  36 .B ] [ \-D
  37 .I defines_file
  38 .B ] [ \-o
  39 .I output_file
  40 .B ] [ \-p
  41 .I symbol_prefix
  42 .B ]
  43 .I filename
  44 .SH DESCRIPTION
  45 .B \*N
  46 reads the grammar specification in the file
  47 .I filename
  48 and generates an LALR(1) parser for it.
  49 The parsers consist of a set of LALR(1) parsing tables and a driver routine
  50 written in the C programming language.
  51 .B \*N
  52 normally writes the parse tables and the driver routine to the file
  53 .I y.tab.c.
  54 .PP
  55 The following options are available:
  56 .TP 5
  57 \fB\-b \fP\fIfile_prefix\fR
  58 The
  59 .B \-b
  60 option changes the prefix prepended to the output file names to
  61 the string denoted by
  62 .I file_prefix.
  63 The default prefix is the character
  64 .I y.
  65 .TP
  66 .B \-B
  67 create a backtracking parser (compile-time configuration for \fBbtyacc\fP).
  68 .TP
  69 .B \-d
  70 causes the header file
  71 .B y.tab.h
  72 to be written.
  73 It contains #define's for the token identifiers.
  74 .TP
  75 \fB\-D \fP\fIdefines_file\fR
  76 causes #define's for the token identifiers
  77 to be written to the given \fIdefines_file\fP rather
  78 than the \fBy.tab.h\fP file used by the \fB\-d\fP option.
  79 .TP
  80 .B \-g
  81 The
  82 .B \-g
  83 option causes a graphical description of the generated LALR(1) parser to
  84 be written to the file
  85 .B y.dot
  86 in graphviz format, ready to be processed by dot(1).
  87 .TP
  88 .B \-i
  89 The \fB-i\fR option causes a supplementary header file
  90 .B y.tab.i
  91 to be written.
  92 It contains extern declarations
  93 and supplementary #define's as needed to map the conventional \fIyacc\fP
  94 \fByy\fP-prefixed names to whatever the \fB-p\fP option may specify.
  95 The code file, e.g., \fBy.tab.c\fP is modified to #include this file
  96 as well as the \fBy.tab.h\fP file, enforcing consistent usage of the
  97 symbols defined in those files.
  98 .IP
  99 The supplementary header file makes it simpler to separate compilation
 100 of lex- and yacc-files.
 101 .TP
 102 .B \-l
 103 If the
 104 .B \-l
 105 option is not specified,
 106 .B \*n
 107 will insert \fI#line\fP directives in the generated code.
 108 The \fI#line\fP directives let the C compiler relate errors in the
 109 generated code to the user's original code.
 110 If the \fB-l\fR option is specified,
 111 .B \*n
 112 will not insert the \fI#line\fP directives.
 113 \&\fI#line\fP directives specified by the user will be retained.
 114 .TP
 115 .B \-L
 116 enable position processing,
 117 e.g., \*(``%locations\*('' (compile-time configuration for \fBbtyacc\fP).
 118 .TP
 119 \fB\-o \fP\fIoutput_file\fR
 120 specify the filename for the parser file.
 121 If this option is not given, the output filename is
 122 the file prefix concatenated with the file suffix, e.g., \fBy.tab.c\fP.
 123 This overrides the \fB-b\fP option.
 124 .TP
 125 \fB\-p \fP\fIsymbol_prefix\fR
 126 The
 127 .B \-p
 128 option changes the prefix prepended to yacc-generated symbols to
 129 the string denoted by
 130 .I symbol_prefix.
 131 The default prefix is the string
 132 .B yy.
 133 .TP
 134 .B \-P
 135 create a reentrant parser, e.g., \*(``%pure-parser\*(''.
 136 .TP
 137 .B \-r
 138 The
 139 .B \-r
 140 option causes
 141 .B \*n
 142 to produce separate files for code and tables.
 143 The code file is named
 144 .I y.code.c,
 145 and the tables file is named
 146 .I y.tab.c.
 147 The prefix \*(``\fIy.\fP\*('' can be overridden using the \fB\-b\fP option.
 148 .TP
 149 .B \-s
 150 suppress \*(``\fB#define\fP\*('' statements generated for string literals in
 151 a \*(``\fB%token\fP\*('' statement,
 152 to more closely match original \fByacc\fP behavior.
 153 .IP
 154 Normally when \fByacc\fP sees a line such as
 155 .Ex
 156 %token OP_ADD "ADD"
 157 .Ee
 158 .IP
 159 it notices that the quoted \*(``ADD\*('' is a valid C identifier,
 160 and generates a #define not only for OP_ADD,
 161 but for ADD as well,
 162 e.g.,
 163 .Ex
 164 #define OP_ADD 257
 165 .br
 166 #define ADD 258
 167 .Ee
 168 .IP
 169 The original \fByacc\fP does not generate the second \*(``\fB#define\fP\*(''.
 170 The \fB\-s\fP option suppresses this \*(``\fB#define\fP\*(''.
 171 .IP
 172 POSIX (IEEE 1003.1 2004) documents only names and numbers
 173 for \*(``\fB%token\fP\*('',
 174 though original \fByacc\fP and bison also accept string literals.
 175 .TP
 176 .B \-t
 177 The
 178 .B \-t
 179 option changes the preprocessor directives generated by
 180 .B \*n
 181 so that debugging statements will be incorporated in the compiled code.
 182 .TP
 183 .B \-v
 184 The
 185 .B \-v
 186 option causes a human-readable description of the generated parser to
 187 be written to the file
 188 .I y.output.
 189 .TP
 190 .B \-V
 191 print the version number to the standard output.
 192 .TP
 193 .B \-y
 194 \fByacc\fP ignores this option,
 195 which bison supports for ostensible POSIX compatibility.
 196 .PP
 197 The \fIfilename\fP parameter is not optional.
 198 However, \fByacc\fP accepts a single \*(``\-\*('' to read the grammar
 199 from the standard input.
 200 A double \*(``\-\-\*('' marker denotes the end of options.
 201 A single \fIfilename\fP parameter is expected after a \*(``\-\-\*('' marker.
 202 .SH EXTENSIONS
 203 .B \*N
 204 provides some extensions for
 205 compatibility with bison and other implementations of yacc.
 206 The \fB%destructor\fP and \fB%locations\fP features are available
 207 only if \fByacc\fP has been configured and compiled to support the
 208 back-tracking (\fBbtyacc\fP) functionality.
 209 The remaining features are always available:
 210 .TP
 211 \fB %destructor\fP { \fIcode\fP } \fIsymbol+\fP
 212 defines code that is invoked when a symbol is automatically
 213 discarded during error recovery.
 214 This code can be used to
 215 reclaim dynamically allocated memory associated with the corresponding
 216 semantic value for cases where user actions cannot manage the memory
 217 explicitly.
 218 .IP
 219 On encountering a parse error, the generated parser
 220 discards symbols on the stack and input tokens until it reaches a state
 221 that will allow parsing to continue.
 222 This error recovery approach results in a memory leak
 223 if the \fBYYSTYPE\fP value is, or contains,
 224 pointers to dynamically allocated memory.
 225 .IP
 226 The bracketed \fIcode\fP is invoked whenever the parser discards one of
 227 the symbols.
 228 Within \fIcode\fP, \*(``\fB$$\fP\*('' or
 229 \*(``\fB$<tag>$\fP\*('' designates the semantic value associated with the
 230 discarded symbol, and  \*(``\fB@$\fP\*('' designates its location (see
 231 \fB%locations\fP directive).
 232 .IP
 233 A per-symbol destructor is defined by listing a grammar symbol
 234 in \fIsymbol+\fP.  A per-type destructor is defined  by listing
 235 a semantic type tag (e.g., \*(``<some_tag>\*('') in \fIsymbol+\fP; in this
 236 case, the parser will invoke \fIcode\fP whenever it discards any grammar
 237 symbol that has that semantic type tag, unless that symbol has its own
 238 per-symbol destructor.
 239 .IP
 240 Two categories of default destructor are supported that are
 241 invoked when discarding any grammar symbol that has no per-symbol and no
 242 per-type destructor:
 243 .RS
 244 .bP
 245 the code for \*(``\fB<*>\fP\*('' is used
 246 for grammar symbols that have an explicitly declared semantic type tag
 247 (via \*(``\fB%type\fP\*('');
 248 .bP
 249 the code for \*(``\fB<>\fP\*('' is used
 250 for grammar symbols that have no declared semantic type tag.
 251 .RE
 252 .TP
 253 \fB %expect\fP \fInumber\fP
 254 tells \fByacc\fP the expected number of shift/reduce conflicts.
 255 That makes it only report the number if it differs.
 256 .TP
 257 \fB %expect-rr\fP \fInumber\fP
 258 tell \fByacc\fP the expected number of reduce/reduce conflicts.
 259 That makes it only report the number if it differs.
 260 This is (unlike bison) allowable in LALR parsers.
 261 .TP
 262 \fB %locations\fP
 263 tells \fByacc\fP to enable  management of position information associated
 264 with each token, provided by the lexer in the global variable \fByylloc\fP,
 265 similar to management of semantic value information provided in \fByylval\fP.
 266 .IP
 267 As for semantic values, locations can be referenced within actions using
 268 \fB@$\fP to refer to the location of the left hand side symbol, and \fB@N\fP
 269 (\fBN\fP an integer) to refer to the location of one of the right hand side
 270 symbols.
 271 Also as for semantic values, when a rule is matched, a default
 272 action is used the compute the location represented by \fB@$\fP as the
 273 beginning of the first symbol and the end of the last symbol in the right
 274 hand side of the rule.
 275 This default computation can be overridden by
 276 explicit assignment to \fB@$\fP in a rule action.
 277 .IP
 278 The type of \fByylloc\fP is \fBYYLTYPE\fP, which is defined by default as:
 279 .Ex
 280 typedef struct YYLTYPE {
 281     int first_line;
 282     int first_column;
 283     int last_line;
 284     int last_column;
 285 } YYLTYPE;
 286 .Ee
 287 .IP
 288 \fBYYLTYPE\fP can be redefined by the user
 289 (\fBYYLTYPE_IS_DEFINED\fP must be defined, to inhibit the default)
 290 in the declarations section of the specification file.
 291 As in bison, the macro \fBYYLLOC_DEFAULT\fP is invoked
 292 each time a rule is matched to calculate a position for the left hand side of
 293 the rule, before the associated action is executed; this macro can be
 294 redefined by the user.
 295 .IP
 296 This directive adds a \fBYYLTYPE\fP parameter to \fByyerror()\fP.
 297 If the \fB%pure-parser\fP directive is present,
 298 a \fBYYLTYPE\fP parameter is added to \fByylex()\fP calls.
 299 .TP
 300 \fB %lex-param\fP { \fIargument-declaration\fP }
 301 By default, the lexer accepts no parameters, e.g., \fByylex()\fP.
 302 Use this directive to add parameter declarations for your customized lexer.
 303 .TP
 304 \fB %parse-param\fP { \fIargument-declaration\fP }
 305 By default, the parser accepts no parameters, e.g., \fByyparse()\fP.
 306 Use this directive to add parameter declarations for your customized parser.
 307 .TP
 308 \fB %pure-parser\fP
 309 Most variables (other than \fByydebug\fP and \fByynerrs\fP) are
 310 allocated on the stack within \fByyparse\fP, making the parser reasonably
 311 reentrant.
 312 .TP
 313 \fB %token-table\fP
 314 Make the parser's names for tokens available in the \fByytname\fP array.
 315 However,
 316 .B \*n
 317 does not predefine \*(``$end\*('', \*(``$error\*(''
 318 or \*(``$undefined\*('' in this array.
 319 .SH PORTABILITY
 320 According to Robert Corbett,
 321 .Ex
 322 Berkeley Yacc is an LALR(1) parser generator.  Berkeley Yacc
 323 has been made as compatible as possible with AT&T Yacc.
 324 Berkeley Yacc can accept any input specification that
 325 conforms to the AT&T Yacc documentation.  Specifications
 326 that take advantage of undocumented features of AT&T Yacc
 327 will probably be rejected.
 328 .Ee
 329 .PP
 330 The rationale in
 331 .Ex
 332 http://pubs.opengroup.org/onlinepubs/9699919799/utilities/yacc.html
 333 .Ee
 334 .PP
 335 documents some features of AT&T yacc which are no longer required for POSIX
 336 compliance.
 337 .PP
 338 That said, you may be interested in reusing grammar files with some
 339 other implementation which is not strictly compatible with AT&T yacc.
 340 For instance, there is bison.
 341 Here are a few differences:
 342 .bP
 343 \fBYacc\fP accepts an equals mark preceding the left curly brace
 344 of an action (as in the original grammar file \fBftp.y\fP):
 345 .Ex
 346     |   STAT CRLF
 347         = {
 348                 statcmd();
 349         }
 350 .Ee
 351 .bP
 352 \fBYacc\fP and bison emit code in different order, and in particular bison
 353 makes forward reference to common functions such as yylex, yyparse and
 354 yyerror without providing prototypes.
 355 .bP
 356 Bison's support for \*(``%expect\*('' is broken in more than one release.
 357 For best results using bison, delete that directive.
 358 .bP
 359 Bison has no equivalent for some of \fByacc\fP's commmand-line options,
 360 relying on directives embedded in the grammar file.
 361 .bP
 362 Bison's \*(``\fB\-y\fP\*('' option does not affect bison's lack of support for
 363 features of AT&T yacc which were deemed obsolescent.
 364 .bP
 365 \fBYacc\fP accepts multiple parameters
 366 with \fB%lex-param\fP and \fB%parse-param\fP in two forms
 367 .Ex
 368 {type1 name1} {type2 name2} ...
 369 {type1 name1,  type2 name2 ...}
 370 .Ee
 371 .IP
 372 Bison accepts the latter (though undocumented), but depending on the
 373 release may generate bad code.
 374 .bP
 375 Like bison, \fByacc\fP will add parameters specified via \fB%parse-param\fP
 376 to \fByyparse\fP, \fByyerror\fP and (if configured for back-tracking)
 377 to the destructor declared using \fB%destructor\fP.
 378 Bison puts the additional parameters \fIfirst\fP for
 379 \fByyparse\fP and \fByyerror\fP but \fIlast\fP for destructors.
 380 \fBYacc\fP matches this behavior.
 381 .
 382 .SH DIAGNOSTICS
 383 If there are rules that are never reduced, the number of such rules is
 384 reported on standard error.
 385 If there are any LALR(1) conflicts, the number of conflicts is reported
 386 on standard error.