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