contrib/byacc/yacc.1

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