yacc.1

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