* data/glr.c (b4_syncline): Fix (swap) the definition of
[bison.git] / doc / bison.1
0 / 369 (  0%)
CommitLineData
1.TH BISON 1 local
2.SH NAME
3bison \- GNU Project parser generator (yacc replacement)
4.SH SYNOPSIS
5.B bison
6[
7.BI \-b " file-prefix"
8] [
9.BI \-\-file-prefix= file-prefix
10] [
11.B \-d
12] [
13.BI \-\-defines= defines-file
14] [
15.B \-g
16] [
17.BI \-\-graph= graph-file
18] [
19.B \-k
20] [
21.B \-\-token-table
22] [
23.B \-l
24] [
25.B \-\-no-lines
26] [
27.B \-n
28] [
29.B \-\-no-parser
30] [
31.BI \-o " outfile"
32] [
33.BI \-\-output-file= outfile
34] [
35.BI \-p " prefix"
36] [
37.BI \-\-name-prefix= prefix
38] [
39.B \-t
40] [
41.B \-\-debug
42] [
43.B \-v
44] [
45.B \-\-verbose
46] [
47.B \-V
48] [
49.B \-\-version
50] [
51.B \-y
52] [
53.B \-\-yacc
54] [
55.B \-h
56] [
57.B \-\-help
58] [
59.B \-\-fixed-output-files
60]
61file
62.br
63.B yacc
64[
65.I "similar options and operands"
66]
67.SH DESCRIPTION
68.I Bison
69is a parser generator in the style of
70.IR yacc (1).
71It should be upwardly compatible with input files designed
72for
73.IR yacc .
74.PP
75Input files should follow the
76.I yacc
77convention of ending in
78.BR .y .
79Unlike
80.IR yacc ,
81the generated files do not have fixed names, but instead use the prefix
82of the input file.
83Moreover, if you need to put
84.I C++
85code in the input file, you can end his name by a C++-like extension
86(.ypp or .y++), then bison will follow your extension to name the
87output file (.cpp or .c++).
88For instance, a grammar description file named
89.B parse.yxx
90would produce the generated parser in a file named
91.BR parse.tab.cxx ,
92instead of
93.IR yacc 's
94.B y.tab.c
95or old
96.I Bison
97version's
98.BR parse.tab.c .
99.PP
100This description of the options that can be given to
101.I bison
102is adapted from the node
103.B Invocation
104in the
105.B bison.texinfo
106manual, which should be taken as authoritative.
107.PP
108.I Bison
109supports both traditional single-letter options and mnemonic long
110option names. Long option names are indicated with
111.B \-\-
112instead of
113.BR \- .
114Abbreviations for option names are allowed as long as they
115are unique. When a long option takes an argument, like
116.BR \-\-file-prefix ,
117connect the option name and the argument with
118.BR = .
119.SS OPTIONS
120.TP
121.BI \-b " file-prefix"
122.br
123.ns
124.TP
125.BI \-\-file-prefix= file-prefix
126Specify a prefix to use for all
127.I bison
128output file names. The names are
129chosen as if the input file were named
130\fIfile-prefix\fP\fB.c\fP.
131.TP
132.B \-d
133.br
134.ns
135Write an extra output file containing macro definitions for the token
136type names defined in the grammar and the semantic value type
137.BR YYSTYPE ,
138as well as a few
139.B extern
140variable declarations.
141.sp
142If the parser output file is named
143.IB name .c
144then this file
145is named
146\fIname\fP\fB.h\fP.
147.sp
148This output file is essential if you wish to put the definition of
149.B yylex
150in a separate source file, because
151.B yylex
152needs to be able to refer to token type codes and the variable
153.BR yylval .
154.TP
155.BI \-\-defines= defines-file
156The behavior of
157.B \-\-defines
158is the same than
159.B \-d
160option.
161The only difference is that it has an optional argument which is
162the name of the output filename.
163.TP
164.BI \-g
165.br
166.ns
167Output a VCG definition of the LALR(1) grammar automaton computed by
168Bison. If the grammar file is
169.BR foo.y
170, the VCG output file will be
171.BR foo.vcg .
172.TP
173.BI \-\-graph= graph-file
174The behavior of
175.BI \-\-graph
176is the same than
177.BI \-g
178option. The only difference is that it has an optional argument which
179is the name of the output graph filename.
180.TP
181.B \-k
182.br
183.ns
184.TP
185.B \-\-token-table
186This switch causes the
187.IB name .tab.c
188output to include a list of
189token names in order by their token numbers; this is defined in the array
190.IR yytname .
191Also generated
192are #defines for
193.IR YYNTOKENS ,
194.IR YYNNTS ,
195.IR YYNRULES ,
196and
197.IR YYNSTATES .
198.TP
199.B \-l
200.br
201.ns
202.TP
203.B \-\-no-lines
204Don't put any
205.B #line
206preprocessor commands in the parser file.
207Ordinarily
208.I bison
209puts them in the parser file so that the C compiler
210and debuggers will associate errors with your source file, the
211grammar file. This option causes them to associate errors with the
212parser file, treating it an independent source file in its own right.
213.TP
214.B \-n
215.br
216.ns
217.TP
218.B \-\-no-parser
219Do not generate the parser code into the output; generate only
220declarations. The generated
221.IB name .tab.c
222file will have only
223constant declarations. In addition, a
224.IB name .act
225file is
226generated containing a switch statement body containing all the
227translated actions.
228.TP
229.BI \-o " outfile"
230.br
231.ns
232.TP
233.BI \-\-output-file= outfile
234Specify the name
235.I outfile
236for the parser file.
237.sp
238The other output files' names are constructed from
239.I outfile
240as described under the
241.B \-v
242and
243.B \-d
244switches.
245.TP
246.BI \-p " prefix"
247.br
248.ns
249.TP
250.BI \-\-name-prefix= prefix
251Rename the external symbols used in the parser so that they start with
252.I prefix
253instead of
254.BR yy .
255The precise list of symbols renamed is
256.BR yyparse ,
257.BR yylex ,
258.BR yyerror ,
259.BR yylval ,
260.BR yychar ,
261and
262.BR yydebug .
263.sp
264For example, if you use
265.BR "\-p c" ,
266the names become
267.BR cparse ,
268.BR clex ,
269and so on.
270.TP
271.B \-t
272.br
273.ns
274.TP
275.B \-\-debug
276In the parser file, define the macro
277.B YYDEBUG
278to 1 if it is not already defined,
279so that the debugging facilities are compiled.
280.TP
281.B \-v
282.br
283.ns
284.TP
285.B \-\-verbose
286Write an extra output file containing verbose descriptions of the
287parser states and what is done for each type of look-ahead token in
288that state.
289.sp
290This file also describes all the conflicts, both those resolved by
291operator precedence and the unresolved ones.
292.sp
293The file's name is made by removing
294.B .tab.c
295or
296.B .c
297from the parser output file name, and adding
298.B .output
299instead.
300.sp
301Therefore, if the input file is
302.BR foo.y ,
303then the parser file is called
304.B foo.tab.c
305by default. As a consequence, the verbose
306output file is called
307.BR foo.output .
308.TP
309.B \-V
310.br
311.ns
312.TP
313.B \-\-version
314Print the version number of
315.I bison
316and exit.
317.TP
318.B \-h
319.br
320.ns
321.TP
322.B \-\-help
323Print a summary of the options to
324.I bison
325and exit.
326.TP
327.B \-y
328.br
329.ns
330.TP
331.B \-\-yacc
332.br
333.ns
334.TP
335.B \-\-fixed-output-files
336Equivalent to
337.BR "\-o y.tab.c" ;
338the parser output file is called
339.BR y.tab.c ,
340and the other outputs are called
341.B y.output
342and
343.BR y.tab.h .
344The purpose of this switch is to imitate
345.IR yacc 's
346output file name conventions.
347Thus, the following shell script can substitute for
348.I yacc
349and is often installed as
350.IR yacc :
351.sp
352.RS
353.ft B
354bison \-y "$@"
355.ft R
356.sp
357.RE
358.SH SEE ALSO
359.IR yacc (1)
360.br
361The
362.IR "Bison Reference Manual" ,
363included as the file
364.B bison.texinfo
365in the
366.I bison
367source distribution.
368.SH DIAGNOSTICS
369Self explanatory.