| blob | e824fe8e9ae281dc0b7f8c69858f55905bd31551 |
1 .\" $NetBSD: yacc.1,v 1.6 2015/01/03 23:22:52 christos Exp $
2 .\"
3 .\" Id: yacc.1,v 1.24 2014/10/06 00:03:48 tom Exp
4 .\"
5 .\" .TH YACC 1 "July\ 15,\ 1990"
6 .\" .UC 6
7 .de ES
8 .ne 8
9 .nf
10 .sp
11 .in +4
12 ..
13 .de XE
14 .in -4
15 .fi
16 ..
17 .\" Escape single quotes in literal strings from groff's Unicode transform.
18 .ie \n(.g .ds AQ \(aq
19 .el .ds AQ '
20 .ie \n(.g .ds `` \(lq
21 .el .ds `` ``
22 .ie \n(.g .ds '' \(rq
23 .el .ds '' ''
24 .\" Bulleted paragraph
25 .de bP
26 .IP \(bu 4
27 ..
28 .TH YACC 1 "October 5, 2014" "Berkeley Yacc" "User Commands"
29 .SH NAME
30 Yacc \- an LALR(1) parser generator
31 .SH SYNOPSIS
32 .B yacc [ -BdgilLPrtvVy ] [ \-b
33 .I file_prefix
34 .B ] [ \-o
35 .I output_file
36 .B ] [ \-p
37 .I symbol_prefix
38 .B ]
39 .I filename
40 .SH DESCRIPTION
41 .B Yacc
42 reads the grammar specification in the file
43 .I filename
44 and generates an LALR(1) parser for it.
45 The parsers consist of a set of LALR(1) parsing tables and a driver routine
46 written in the C programming language.
47 .B Yacc
48 normally writes the parse tables and the driver routine to the file
49 .IR y.tab.c.
50 .PP
51 The following options are available:
52 .TP 5
53 \fB\-b \fP\fIfile_prefix\fR
54 The
55 .B \-b
56 option changes the prefix prepended to the output file names to
57 the string denoted by
58 .IR file_prefix.
59 The default prefix is the character
60 .IR y.
61 .TP
62 .B \-B
63 create a backtracking parser (compile-type configuration for \fBbtyacc\fP).
64 .TP
65 .B \-d
66 The \fB-d\fR option causes the header file
67 .BR y.tab.h
68 to be written.
69 It contains #define's for the token identifiers.
70 .TP
71 .B \-g
72 The
73 .B \-g
74 option causes a graphical description of the generated LALR(1) parser to
75 be written to the file
76 .BR y.dot
77 in graphviz format, ready to be processed by dot(1).
78 .TP
79 .B \-i
80 The \fB-i\fR option causes a supplementary header file
81 .BR y.tab.i
82 to be written.
83 It contains extern declarations
84 and supplementary #define's as needed to map the conventional \fIyacc\fP
85 \fByy\fP-prefixed names to whatever the \fB-p\fP option may specify.
86 The code file, e.g., \fBy.tab.c\fP is modified to #include this file
87 as well as the \fBy.tab.h\fP file, enforcing consistent usage of the
88 symbols defined in those files.
89 .IP
90 The supplementary header file makes it simpler to separate compilation
91 of lex- and yacc-files.
92 .TP
93 .B \-l
94 If the
95 .B \-l
96 option is not specified,
97 .B yacc
98 will insert \fI#line\fP directives in the generated code.
99 The \fI#line\fP directives let the C compiler relate errors in the
100 generated code to the user's original code.
101 If the \fB-l\fR option is specified,
102 .B yacc
103 will not insert the \fI#line\fP directives.
104 \&\fI#line\fP directives specified by the user will be retained.
105 .TP
106 .B \-L
107 enable position processing, e.g., \*(``%locations\*('' (compile-type 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 .IR symbol_prefix.
121 The default prefix is the string
122 .BR 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 .IR y.code.c,
135 and the tables file is named
136 .IR 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 .IR 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 with \fB%lex-param\fP and \fB%parse-param\fP
346 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.