]> git.saurik.com Git - bison.git/blame - doc/bison.texinfo
doc: please Emacs.
[bison.git] / doc / bison.texinfo
CommitLineData
bfa74976
RS
1\input texinfo @c -*-texinfo-*-
2@comment %**start of header
3@setfilename bison.info
df1af54c
JT
4@include version.texi
5@settitle Bison @value{VERSION}
bfa74976
RS
6@setchapternewpage odd
7
5378c3e7 8@finalout
5378c3e7 9
13863333 10@c SMALL BOOK version
bfa74976 11@c This edition has been formatted so that you can format and print it in
13863333 12@c the smallbook format.
bfa74976
RS
13@c @smallbook
14
91d2c560
PE
15@c Set following if you want to document %default-prec and %no-default-prec.
16@c This feature is experimental and may change in future Bison versions.
17@c @set defaultprec
18
8c5b881d 19@ifnotinfo
bfa74976
RS
20@syncodeindex fn cp
21@syncodeindex vr cp
22@syncodeindex tp cp
8c5b881d 23@end ifnotinfo
bfa74976
RS
24@ifinfo
25@synindex fn cp
26@synindex vr cp
27@synindex tp cp
28@end ifinfo
29@comment %**end of header
30
fae437e8 31@copying
bd773d73 32
35430378
JD
33This manual (@value{UPDATED}) is for GNU Bison (version
34@value{VERSION}), the GNU parser generator.
fae437e8 35
ea0a7676
JD
36Copyright @copyright{} 1988-1993, 1995, 1998-2011 Free Software
37Foundation, Inc.
fae437e8
AD
38
39@quotation
40Permission is granted to copy, distribute and/or modify this document
35430378 41under the terms of the GNU Free Documentation License,
241ac701 42Version 1.3 or any later version published by the Free Software
c827f760 43Foundation; with no Invariant Sections, with the Front-Cover texts
35430378 44being ``A GNU Manual,'' and with the Back-Cover Texts as in
c827f760 45(a) below. A copy of the license is included in the section entitled
35430378 46``GNU Free Documentation License.''
c827f760 47
389c8cfd 48(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
35430378
JD
49modify this GNU manual. Buying copies from the FSF
50supports it in developing GNU and promoting software
389c8cfd 51freedom.''
fae437e8
AD
52@end quotation
53@end copying
54
e62f1a89 55@dircategory Software development
fae437e8 56@direntry
35430378 57* bison: (bison). GNU parser generator (Yacc replacement).
fae437e8 58@end direntry
bfa74976 59
bfa74976
RS
60@titlepage
61@title Bison
c827f760 62@subtitle The Yacc-compatible Parser Generator
df1af54c 63@subtitle @value{UPDATED}, Bison Version @value{VERSION}
bfa74976
RS
64
65@author by Charles Donnelly and Richard Stallman
66
67@page
68@vskip 0pt plus 1filll
fae437e8 69@insertcopying
bfa74976
RS
70@sp 2
71Published by the Free Software Foundation @*
0fb669f9
PE
7251 Franklin Street, Fifth Floor @*
73Boston, MA 02110-1301 USA @*
9ecbd125 74Printed copies are available from the Free Software Foundation.@*
35430378 75ISBN 1-882114-44-2
bfa74976
RS
76@sp 2
77Cover art by Etienne Suvasa.
78@end titlepage
d5796688
JT
79
80@contents
bfa74976 81
342b8b6e
AD
82@ifnottex
83@node Top
84@top Bison
fae437e8 85@insertcopying
342b8b6e 86@end ifnottex
bfa74976
RS
87
88@menu
13863333
AD
89* Introduction::
90* Conditions::
35430378 91* Copying:: The GNU General Public License says
f56274a8 92 how you can copy and share Bison.
bfa74976
RS
93
94Tutorial sections:
f56274a8
DJ
95* Concepts:: Basic concepts for understanding Bison.
96* Examples:: Three simple explained examples of using Bison.
bfa74976
RS
97
98Reference sections:
f56274a8
DJ
99* Grammar File:: Writing Bison declarations and rules.
100* Interface:: C-language interface to the parser function @code{yyparse}.
101* Algorithm:: How the Bison parser works at run-time.
102* Error Recovery:: Writing rules for error recovery.
bfa74976 103* Context Dependency:: What to do if your language syntax is too
f56274a8
DJ
104 messy for Bison to handle straightforwardly.
105* Debugging:: Understanding or debugging Bison parsers.
9913d6e4 106* Invocation:: How to run Bison (to produce the parser implementation).
f56274a8
DJ
107* Other Languages:: Creating C++ and Java parsers.
108* FAQ:: Frequently Asked Questions
109* Table of Symbols:: All the keywords of the Bison language are explained.
110* Glossary:: Basic concepts are explained.
111* Copying This Manual:: License for copying this manual.
112* Index:: Cross-references to the text.
bfa74976 113
93dd49ab
PE
114@detailmenu
115 --- The Detailed Node Listing ---
bfa74976
RS
116
117The Concepts of Bison
118
f56274a8
DJ
119* Language and Grammar:: Languages and context-free grammars,
120 as mathematical ideas.
121* Grammar in Bison:: How we represent grammars for Bison's sake.
122* Semantic Values:: Each token or syntactic grouping can have
123 a semantic value (the value of an integer,
124 the name of an identifier, etc.).
125* Semantic Actions:: Each rule can have an action containing C code.
126* GLR Parsers:: Writing parsers for general context-free languages.
127* Locations Overview:: Tracking Locations.
128* Bison Parser:: What are Bison's input and output,
129 how is the output used?
130* Stages:: Stages in writing and running Bison grammars.
131* Grammar Layout:: Overall structure of a Bison grammar file.
bfa74976 132
35430378 133Writing GLR Parsers
fa7e68c3 134
35430378
JD
135* Simple GLR Parsers:: Using GLR parsers on unambiguous grammars.
136* Merging GLR Parses:: Using GLR parsers to resolve ambiguities.
f56274a8 137* GLR Semantic Actions:: Deferred semantic actions have special concerns.
35430378 138* Compiler Requirements:: GLR parsers require a modern C compiler.
fa7e68c3 139
bfa74976
RS
140Examples
141
f56274a8
DJ
142* RPN Calc:: Reverse polish notation calculator;
143 a first example with no operator precedence.
144* Infix Calc:: Infix (algebraic) notation calculator.
145 Operator precedence is introduced.
bfa74976 146* Simple Error Recovery:: Continuing after syntax errors.
342b8b6e 147* Location Tracking Calc:: Demonstrating the use of @@@var{n} and @@$.
f56274a8
DJ
148* Multi-function Calc:: Calculator with memory and trig functions.
149 It uses multiple data-types for semantic values.
150* Exercises:: Ideas for improving the multi-function calculator.
bfa74976
RS
151
152Reverse Polish Notation Calculator
153
f56274a8
DJ
154* Rpcalc Declarations:: Prologue (declarations) for rpcalc.
155* Rpcalc Rules:: Grammar Rules for rpcalc, with explanation.
156* Rpcalc Lexer:: The lexical analyzer.
157* Rpcalc Main:: The controlling function.
158* Rpcalc Error:: The error reporting function.
159* Rpcalc Generate:: Running Bison on the grammar file.
160* Rpcalc Compile:: Run the C compiler on the output code.
bfa74976
RS
161
162Grammar Rules for @code{rpcalc}
163
13863333
AD
164* Rpcalc Input::
165* Rpcalc Line::
166* Rpcalc Expr::
bfa74976 167
342b8b6e
AD
168Location Tracking Calculator: @code{ltcalc}
169
f56274a8
DJ
170* Ltcalc Declarations:: Bison and C declarations for ltcalc.
171* Ltcalc Rules:: Grammar rules for ltcalc, with explanations.
172* Ltcalc Lexer:: The lexical analyzer.
342b8b6e 173
bfa74976
RS
174Multi-Function Calculator: @code{mfcalc}
175
f56274a8
DJ
176* Mfcalc Declarations:: Bison declarations for multi-function calculator.
177* Mfcalc Rules:: Grammar rules for the calculator.
178* Mfcalc Symbol Table:: Symbol table management subroutines.
bfa74976
RS
179
180Bison Grammar Files
181
182* Grammar Outline:: Overall layout of the grammar file.
183* Symbols:: Terminal and nonterminal symbols.
184* Rules:: How to write grammar rules.
185* Recursion:: Writing recursive rules.
186* Semantics:: Semantic values and actions.
93dd49ab 187* Locations:: Locations and actions.
bfa74976
RS
188* Declarations:: All kinds of Bison declarations are described here.
189* Multiple Parsers:: Putting more than one Bison parser in one program.
190
191Outline of a Bison Grammar
192
f56274a8 193* Prologue:: Syntax and usage of the prologue.
2cbe6b7f 194* Prologue Alternatives:: Syntax and usage of alternatives to the prologue.
f56274a8
DJ
195* Bison Declarations:: Syntax and usage of the Bison declarations section.
196* Grammar Rules:: Syntax and usage of the grammar rules section.
197* Epilogue:: Syntax and usage of the epilogue.
bfa74976
RS
198
199Defining Language Semantics
200
201* Value Type:: Specifying one data type for all semantic values.
202* Multiple Types:: Specifying several alternative data types.
203* Actions:: An action is the semantic definition of a grammar rule.
204* Action Types:: Specifying data types for actions to operate on.
205* Mid-Rule Actions:: Most actions go at the end of a rule.
206 This says when, why and how to use the exceptional
207 action in the middle of a rule.
1f68dca5 208* Named References:: Using named references in actions.
bfa74976 209
93dd49ab
PE
210Tracking Locations
211
212* Location Type:: Specifying a data type for locations.
213* Actions and Locations:: Using locations in actions.
214* Location Default Action:: Defining a general way to compute locations.
215
bfa74976
RS
216Bison Declarations
217
b50d2359 218* Require Decl:: Requiring a Bison version.
bfa74976
RS
219* Token Decl:: Declaring terminal symbols.
220* Precedence Decl:: Declaring terminals with precedence and associativity.
221* Union Decl:: Declaring the set of all semantic value types.
222* Type Decl:: Declaring the choice of type for a nonterminal symbol.
18d192f0 223* Initial Action Decl:: Code run before parsing starts.
72f889cc 224* Destructor Decl:: Declaring how symbols are freed.
d6328241 225* Expect Decl:: Suppressing warnings about parsing conflicts.
bfa74976
RS
226* Start Decl:: Specifying the start symbol.
227* Pure Decl:: Requesting a reentrant parser.
9987d1b3 228* Push Decl:: Requesting a push parser.
bfa74976 229* Decl Summary:: Table of all Bison declarations.
2f4518a1 230* %define Summary:: Defining variables to adjust Bison's behavior.
8e6f2266 231* %code Summary:: Inserting code into the parser source.
bfa74976
RS
232
233Parser C-Language Interface
234
f56274a8
DJ
235* Parser Function:: How to call @code{yyparse} and what it returns.
236* Push Parser Function:: How to call @code{yypush_parse} and what it returns.
237* Pull Parser Function:: How to call @code{yypull_parse} and what it returns.
238* Parser Create Function:: How to call @code{yypstate_new} and what it returns.
239* Parser Delete Function:: How to call @code{yypstate_delete} and what it returns.
240* Lexical:: You must supply a function @code{yylex}
241 which reads tokens.
242* Error Reporting:: You must supply a function @code{yyerror}.
243* Action Features:: Special features for use in actions.
244* Internationalization:: How to let the parser speak in the user's
245 native language.
bfa74976
RS
246
247The Lexical Analyzer Function @code{yylex}
248
249* Calling Convention:: How @code{yyparse} calls @code{yylex}.
f56274a8
DJ
250* Token Values:: How @code{yylex} must return the semantic value
251 of the token it has read.
252* Token Locations:: How @code{yylex} must return the text location
253 (line number, etc.) of the token, if the
254 actions want that.
255* Pure Calling:: How the calling convention differs in a pure parser
256 (@pxref{Pure Decl, ,A Pure (Reentrant) Parser}).
bfa74976 257
13863333 258The Bison Parser Algorithm
bfa74976 259
742e4900 260* Lookahead:: Parser looks one token ahead when deciding what to do.
bfa74976
RS
261* Shift/Reduce:: Conflicts: when either shifting or reduction is valid.
262* Precedence:: Operator precedence works by resolving conflicts.
263* Contextual Precedence:: When an operator's precedence depends on context.
264* Parser States:: The parser is a finite-state-machine with stack.
265* Reduce/Reduce:: When two rules are applicable in the same situation.
f56274a8 266* Mystery Conflicts:: Reduce/reduce conflicts that look unjustified.
676385e2 267* Generalized LR Parsing:: Parsing arbitrary context-free grammars.
1a059451 268* Memory Management:: What happens when memory is exhausted. How to avoid it.
bfa74976
RS
269
270Operator Precedence
271
272* Why Precedence:: An example showing why precedence is needed.
273* Using Precedence:: How to specify precedence in Bison grammars.
274* Precedence Examples:: How these features are used in the previous example.
275* How Precedence:: How they work.
276
277Handling Context Dependencies
278
279* Semantic Tokens:: Token parsing can depend on the semantic context.
280* Lexical Tie-ins:: Token parsing can depend on the syntactic context.
281* Tie-in Recovery:: Lexical tie-ins have implications for how
282 error recovery rules must be written.
283
93dd49ab 284Debugging Your Parser
ec3bc396
AD
285
286* Understanding:: Understanding the structure of your parser.
287* Tracing:: Tracing the execution of your parser.
288
bfa74976
RS
289Invoking Bison
290
13863333 291* Bison Options:: All the options described in detail,
c827f760 292 in alphabetical order by short options.
bfa74976 293* Option Cross Key:: Alphabetical list of long options.
93dd49ab 294* Yacc Library:: Yacc-compatible @code{yylex} and @code{main}.
f2b5126e 295
8405b70c 296Parsers Written In Other Languages
12545799
AD
297
298* C++ Parsers:: The interface to generate C++ parser classes
8405b70c 299* Java Parsers:: The interface to generate Java parser classes
12545799
AD
300
301C++ Parsers
302
303* C++ Bison Interface:: Asking for C++ parser generation
304* C++ Semantic Values:: %union vs. C++
305* C++ Location Values:: The position and location classes
306* C++ Parser Interface:: Instantiating and running the parser
307* C++ Scanner Interface:: Exchanges between yylex and parse
8405b70c 308* A Complete C++ Example:: Demonstrating their use
12545799
AD
309
310A Complete C++ Example
311
312* Calc++ --- C++ Calculator:: The specifications
313* Calc++ Parsing Driver:: An active parsing context
314* Calc++ Parser:: A parser class
315* Calc++ Scanner:: A pure C++ Flex scanner
316* Calc++ Top Level:: Conducting the band
317
8405b70c
PB
318Java Parsers
319
f56274a8
DJ
320* Java Bison Interface:: Asking for Java parser generation
321* Java Semantic Values:: %type and %token vs. Java
322* Java Location Values:: The position and location classes
323* Java Parser Interface:: Instantiating and running the parser
324* Java Scanner Interface:: Specifying the scanner for the parser
325* Java Action Features:: Special features for use in actions
326* Java Differences:: Differences between C/C++ and Java Grammars
327* Java Declarations Summary:: List of Bison declarations used with Java
8405b70c 328
d1a1114f
AD
329Frequently Asked Questions
330
f56274a8
DJ
331* Memory Exhausted:: Breaking the Stack Limits
332* How Can I Reset the Parser:: @code{yyparse} Keeps some State
333* Strings are Destroyed:: @code{yylval} Loses Track of Strings
334* Implementing Gotos/Loops:: Control Flow in the Calculator
335* Multiple start-symbols:: Factoring closely related grammars
35430378 336* Secure? Conform?:: Is Bison POSIX safe?
f56274a8
DJ
337* I can't build Bison:: Troubleshooting
338* Where can I find help?:: Troubleshouting
339* Bug Reports:: Troublereporting
340* More Languages:: Parsers in C++, Java, and so on
341* Beta Testing:: Experimenting development versions
342* Mailing Lists:: Meeting other Bison users
d1a1114f 343
f2b5126e
PB
344Copying This Manual
345
f56274a8 346* Copying This Manual:: License for copying this manual.
f2b5126e 347
342b8b6e 348@end detailmenu
bfa74976
RS
349@end menu
350
342b8b6e 351@node Introduction
bfa74976
RS
352@unnumbered Introduction
353@cindex introduction
354
6077da58 355@dfn{Bison} is a general-purpose parser generator that converts an
d89e48b3
JD
356annotated context-free grammar into a deterministic LR or generalized
357LR (GLR) parser employing LALR(1) parser tables. As an experimental
358feature, Bison can also generate IELR(1) or canonical LR(1) parser
359tables. Once you are proficient with Bison, you can use it to develop
360a wide range of language parsers, from those used in simple desk
361calculators to complex programming languages.
362
363Bison is upward compatible with Yacc: all properly-written Yacc
364grammars ought to work with Bison with no change. Anyone familiar
365with Yacc should be able to use Bison with little trouble. You need
366to be fluent in C or C++ programming in order to use Bison or to
367understand this manual. Java is also supported as an experimental
368feature.
369
370We begin with tutorial chapters that explain the basic concepts of
371using Bison and show three explained examples, each building on the
372last. If you don't know Bison or Yacc, start by reading these
373chapters. Reference chapters follow, which describe specific aspects
374of Bison in detail.
bfa74976 375
840341d6
JD
376Bison was written originally by Robert Corbett. Richard Stallman made
377it Yacc-compatible. Wilfred Hansen of Carnegie Mellon University
378added multi-character string literals and other features. Since then,
379Bison has grown more robust and evolved many other new features thanks
380to the hard work of a long list of volunteers. For details, see the
381@file{THANKS} and @file{ChangeLog} files included in the Bison
382distribution.
931c7513 383
df1af54c 384This edition corresponds to version @value{VERSION} of Bison.
bfa74976 385
342b8b6e 386@node Conditions
bfa74976
RS
387@unnumbered Conditions for Using Bison
388
193d7c70
PE
389The distribution terms for Bison-generated parsers permit using the
390parsers in nonfree programs. Before Bison version 2.2, these extra
35430378 391permissions applied only when Bison was generating LALR(1)
193d7c70 392parsers in C@. And before Bison version 1.24, Bison-generated
262aa8dd 393parsers could be used only in programs that were free software.
a31239f1 394
35430378 395The other GNU programming tools, such as the GNU C
c827f760 396compiler, have never
9ecbd125 397had such a requirement. They could always be used for nonfree
a31239f1
RS
398software. The reason Bison was different was not due to a special
399policy decision; it resulted from applying the usual General Public
400License to all of the Bison source code.
401
9913d6e4
JD
402The main output of the Bison utility---the Bison parser implementation
403file---contains a verbatim copy of a sizable piece of Bison, which is
404the code for the parser's implementation. (The actions from your
405grammar are inserted into this implementation at one point, but most
406of the rest of the implementation is not changed.) When we applied
407the GPL terms to the skeleton code for the parser's implementation,
a31239f1
RS
408the effect was to restrict the use of Bison output to free software.
409
410We didn't change the terms because of sympathy for people who want to
411make software proprietary. @strong{Software should be free.} But we
412concluded that limiting Bison's use to free software was doing little to
413encourage people to make other software free. So we decided to make the
414practical conditions for using Bison match the practical conditions for
35430378 415using the other GNU tools.
bfa74976 416
193d7c70
PE
417This exception applies when Bison is generating code for a parser.
418You can tell whether the exception applies to a Bison output file by
419inspecting the file for text beginning with ``As a special
420exception@dots{}''. The text spells out the exact terms of the
421exception.
262aa8dd 422
f16b0819
PE
423@node Copying
424@unnumbered GNU GENERAL PUBLIC LICENSE
425@include gpl-3.0.texi
bfa74976 426
342b8b6e 427@node Concepts
bfa74976
RS
428@chapter The Concepts of Bison
429
430This chapter introduces many of the basic concepts without which the
431details of Bison will not make sense. If you do not already know how to
432use Bison or Yacc, we suggest you start by reading this chapter carefully.
433
434@menu
f56274a8
DJ
435* Language and Grammar:: Languages and context-free grammars,
436 as mathematical ideas.
437* Grammar in Bison:: How we represent grammars for Bison's sake.
438* Semantic Values:: Each token or syntactic grouping can have
439 a semantic value (the value of an integer,
440 the name of an identifier, etc.).
441* Semantic Actions:: Each rule can have an action containing C code.
442* GLR Parsers:: Writing parsers for general context-free languages.
443* Locations Overview:: Tracking Locations.
444* Bison Parser:: What are Bison's input and output,
445 how is the output used?
446* Stages:: Stages in writing and running Bison grammars.
447* Grammar Layout:: Overall structure of a Bison grammar file.
bfa74976
RS
448@end menu
449
342b8b6e 450@node Language and Grammar
bfa74976
RS
451@section Languages and Context-Free Grammars
452
bfa74976
RS
453@cindex context-free grammar
454@cindex grammar, context-free
455In order for Bison to parse a language, it must be described by a
456@dfn{context-free grammar}. This means that you specify one or more
457@dfn{syntactic groupings} and give rules for constructing them from their
458parts. For example, in the C language, one kind of grouping is called an
459`expression'. One rule for making an expression might be, ``An expression
460can be made of a minus sign and another expression''. Another would be,
461``An expression can be an integer''. As you can see, rules are often
462recursive, but there must be at least one rule which leads out of the
463recursion.
464
35430378 465@cindex BNF
bfa74976
RS
466@cindex Backus-Naur form
467The most common formal system for presenting such rules for humans to read
35430378 468is @dfn{Backus-Naur Form} or ``BNF'', which was developed in
c827f760 469order to specify the language Algol 60. Any grammar expressed in
35430378
JD
470BNF is a context-free grammar. The input to Bison is
471essentially machine-readable BNF.
bfa74976 472
35430378
JD
473@cindex LALR(1) grammars
474@cindex IELR(1) grammars
475@cindex LR(1) grammars
34a6c2d1
JD
476There are various important subclasses of context-free grammars.
477Although it can handle almost all context-free grammars, Bison is
35430378 478optimized for what are called LR(1) grammars.
34a6c2d1
JD
479In brief, in these grammars, it must be possible to tell how to parse
480any portion of an input string with just a single token of lookahead.
481For historical reasons, Bison by default is limited by the additional
35430378 482restrictions of LALR(1), which is hard to explain simply.
c827f760
PE
483@xref{Mystery Conflicts, ,Mysterious Reduce/Reduce Conflicts}, for
484more information on this.
3b1977ea 485As an experimental feature, you can escape these additional restrictions by
35430378 486requesting IELR(1) or canonical LR(1) parser tables.
2f4518a1 487@xref{%define Summary,,lr.type}, to learn how.
bfa74976 488
35430378
JD
489@cindex GLR parsing
490@cindex generalized LR (GLR) parsing
676385e2 491@cindex ambiguous grammars
9d9b8b70 492@cindex nondeterministic parsing
9501dc6e 493
35430378 494Parsers for LR(1) grammars are @dfn{deterministic}, meaning
9501dc6e
AD
495roughly that the next grammar rule to apply at any point in the input is
496uniquely determined by the preceding input and a fixed, finite portion
742e4900 497(called a @dfn{lookahead}) of the remaining input. A context-free
9501dc6e 498grammar can be @dfn{ambiguous}, meaning that there are multiple ways to
e4f85c39 499apply the grammar rules to get the same inputs. Even unambiguous
9d9b8b70 500grammars can be @dfn{nondeterministic}, meaning that no fixed
742e4900 501lookahead always suffices to determine the next grammar rule to apply.
9501dc6e 502With the proper declarations, Bison is also able to parse these more
35430378
JD
503general context-free grammars, using a technique known as GLR
504parsing (for Generalized LR). Bison's GLR parsers
9501dc6e
AD
505are able to handle any context-free grammar for which the number of
506possible parses of any given string is finite.
676385e2 507
bfa74976
RS
508@cindex symbols (abstract)
509@cindex token
510@cindex syntactic grouping
511@cindex grouping, syntactic
9501dc6e
AD
512In the formal grammatical rules for a language, each kind of syntactic
513unit or grouping is named by a @dfn{symbol}. Those which are built by
514grouping smaller constructs according to grammatical rules are called
bfa74976
RS
515@dfn{nonterminal symbols}; those which can't be subdivided are called
516@dfn{terminal symbols} or @dfn{token types}. We call a piece of input
517corresponding to a single terminal symbol a @dfn{token}, and a piece
e0c471a9 518corresponding to a single nonterminal symbol a @dfn{grouping}.
bfa74976
RS
519
520We can use the C language as an example of what symbols, terminal and
9501dc6e
AD
521nonterminal, mean. The tokens of C are identifiers, constants (numeric
522and string), and the various keywords, arithmetic operators and
523punctuation marks. So the terminal symbols of a grammar for C include
524`identifier', `number', `string', plus one symbol for each keyword,
525operator or punctuation mark: `if', `return', `const', `static', `int',
526`char', `plus-sign', `open-brace', `close-brace', `comma' and many more.
527(These tokens can be subdivided into characters, but that is a matter of
bfa74976
RS
528lexicography, not grammar.)
529
530Here is a simple C function subdivided into tokens:
531
9edcd895
AD
532@ifinfo
533@example
534int /* @r{keyword `int'} */
14d4662b 535square (int x) /* @r{identifier, open-paren, keyword `int',}
9edcd895
AD
536 @r{identifier, close-paren} */
537@{ /* @r{open-brace} */
aa08666d
AD
538 return x * x; /* @r{keyword `return', identifier, asterisk,}
539 @r{identifier, semicolon} */
9edcd895
AD
540@} /* @r{close-brace} */
541@end example
542@end ifinfo
543@ifnotinfo
bfa74976
RS
544@example
545int /* @r{keyword `int'} */
14d4662b 546square (int x) /* @r{identifier, open-paren, keyword `int', identifier, close-paren} */
bfa74976 547@{ /* @r{open-brace} */
9edcd895 548 return x * x; /* @r{keyword `return', identifier, asterisk, identifier, semicolon} */
bfa74976
RS
549@} /* @r{close-brace} */
550@end example
9edcd895 551@end ifnotinfo
bfa74976
RS
552
553The syntactic groupings of C include the expression, the statement, the
554declaration, and the function definition. These are represented in the
555grammar of C by nonterminal symbols `expression', `statement',
556`declaration' and `function definition'. The full grammar uses dozens of
557additional language constructs, each with its own nonterminal symbol, in
558order to express the meanings of these four. The example above is a
559function definition; it contains one declaration, and one statement. In
560the statement, each @samp{x} is an expression and so is @samp{x * x}.
561
562Each nonterminal symbol must have grammatical rules showing how it is made
563out of simpler constructs. For example, one kind of C statement is the
564@code{return} statement; this would be described with a grammar rule which
565reads informally as follows:
566
567@quotation
568A `statement' can be made of a `return' keyword, an `expression' and a
569`semicolon'.
570@end quotation
571
572@noindent
573There would be many other rules for `statement', one for each kind of
574statement in C.
575
576@cindex start symbol
577One nonterminal symbol must be distinguished as the special one which
578defines a complete utterance in the language. It is called the @dfn{start
579symbol}. In a compiler, this means a complete input program. In the C
580language, the nonterminal symbol `sequence of definitions and declarations'
581plays this role.
582
583For example, @samp{1 + 2} is a valid C expression---a valid part of a C
584program---but it is not valid as an @emph{entire} C program. In the
585context-free grammar of C, this follows from the fact that `expression' is
586not the start symbol.
587
588The Bison parser reads a sequence of tokens as its input, and groups the
589tokens using the grammar rules. If the input is valid, the end result is
590that the entire token sequence reduces to a single grouping whose symbol is
591the grammar's start symbol. If we use a grammar for C, the entire input
592must be a `sequence of definitions and declarations'. If not, the parser
593reports a syntax error.
594
342b8b6e 595@node Grammar in Bison
bfa74976
RS
596@section From Formal Rules to Bison Input
597@cindex Bison grammar
598@cindex grammar, Bison
599@cindex formal grammar
600
601A formal grammar is a mathematical construct. To define the language
602for Bison, you must write a file expressing the grammar in Bison syntax:
603a @dfn{Bison grammar} file. @xref{Grammar File, ,Bison Grammar Files}.
604
605A nonterminal symbol in the formal grammar is represented in Bison input
c827f760 606as an identifier, like an identifier in C@. By convention, it should be
bfa74976
RS
607in lower case, such as @code{expr}, @code{stmt} or @code{declaration}.
608
609The Bison representation for a terminal symbol is also called a @dfn{token
610type}. Token types as well can be represented as C-like identifiers. By
611convention, these identifiers should be upper case to distinguish them from
612nonterminals: for example, @code{INTEGER}, @code{IDENTIFIER}, @code{IF} or
613@code{RETURN}. A terminal symbol that stands for a particular keyword in
614the language should be named after that keyword converted to upper case.
615The terminal symbol @code{error} is reserved for error recovery.
931c7513 616@xref{Symbols}.
bfa74976
RS
617
618A terminal symbol can also be represented as a character literal, just like
619a C character constant. You should do this whenever a token is just a
620single character (parenthesis, plus-sign, etc.): use that same character in
621a literal as the terminal symbol for that token.
622
931c7513
RS
623A third way to represent a terminal symbol is with a C string constant
624containing several characters. @xref{Symbols}, for more information.
625
bfa74976
RS
626The grammar rules also have an expression in Bison syntax. For example,
627here is the Bison rule for a C @code{return} statement. The semicolon in
628quotes is a literal character token, representing part of the C syntax for
629the statement; the naked semicolon, and the colon, are Bison punctuation
630used in every rule.
631
632@example
633stmt: RETURN expr ';'
634 ;
635@end example
636
637@noindent
638@xref{Rules, ,Syntax of Grammar Rules}.
639
342b8b6e 640@node Semantic Values
bfa74976
RS
641@section Semantic Values
642@cindex semantic value
643@cindex value, semantic
644
645A formal grammar selects tokens only by their classifications: for example,
646if a rule mentions the terminal symbol `integer constant', it means that
647@emph{any} integer constant is grammatically valid in that position. The
648precise value of the constant is irrelevant to how to parse the input: if
649@samp{x+4} is grammatical then @samp{x+1} or @samp{x+3989} is equally
e0c471a9 650grammatical.
bfa74976
RS
651
652But the precise value is very important for what the input means once it is
653parsed. A compiler is useless if it fails to distinguish between 4, 1 and
6543989 as constants in the program! Therefore, each token in a Bison grammar
c827f760
PE
655has both a token type and a @dfn{semantic value}. @xref{Semantics,
656,Defining Language Semantics},
bfa74976
RS
657for details.
658
659The token type is a terminal symbol defined in the grammar, such as
660@code{INTEGER}, @code{IDENTIFIER} or @code{','}. It tells everything
661you need to know to decide where the token may validly appear and how to
662group it with other tokens. The grammar rules know nothing about tokens
e0c471a9 663except their types.
bfa74976
RS
664
665The semantic value has all the rest of the information about the
666meaning of the token, such as the value of an integer, or the name of an
667identifier. (A token such as @code{','} which is just punctuation doesn't
668need to have any semantic value.)
669
670For example, an input token might be classified as token type
671@code{INTEGER} and have the semantic value 4. Another input token might
672have the same token type @code{INTEGER} but value 3989. When a grammar
673rule says that @code{INTEGER} is allowed, either of these tokens is
674acceptable because each is an @code{INTEGER}. When the parser accepts the
675token, it keeps track of the token's semantic value.
676
677Each grouping can also have a semantic value as well as its nonterminal
678symbol. For example, in a calculator, an expression typically has a
679semantic value that is a number. In a compiler for a programming
680language, an expression typically has a semantic value that is a tree
681structure describing the meaning of the expression.
682
342b8b6e 683@node Semantic Actions
bfa74976
RS
684@section Semantic Actions
685@cindex semantic actions
686@cindex actions, semantic
687
688In order to be useful, a program must do more than parse input; it must
689also produce some output based on the input. In a Bison grammar, a grammar
690rule can have an @dfn{action} made up of C statements. Each time the
691parser recognizes a match for that rule, the action is executed.
692@xref{Actions}.
13863333 693
bfa74976
RS
694Most of the time, the purpose of an action is to compute the semantic value
695of the whole construct from the semantic values of its parts. For example,
696suppose we have a rule which says an expression can be the sum of two
697expressions. When the parser recognizes such a sum, each of the
698subexpressions has a semantic value which describes how it was built up.
699The action for this rule should create a similar sort of value for the
700newly recognized larger expression.
701
702For example, here is a rule that says an expression can be the sum of
703two subexpressions:
704
705@example
706expr: expr '+' expr @{ $$ = $1 + $3; @}
707 ;
708@end example
709
710@noindent
711The action says how to produce the semantic value of the sum expression
712from the values of the two subexpressions.
713
676385e2 714@node GLR Parsers
35430378
JD
715@section Writing GLR Parsers
716@cindex GLR parsing
717@cindex generalized LR (GLR) parsing
676385e2
PH
718@findex %glr-parser
719@cindex conflicts
720@cindex shift/reduce conflicts
fa7e68c3 721@cindex reduce/reduce conflicts
676385e2 722
34a6c2d1 723In some grammars, Bison's deterministic
35430378 724LR(1) parsing algorithm cannot decide whether to apply a
9501dc6e
AD
725certain grammar rule at a given point. That is, it may not be able to
726decide (on the basis of the input read so far) which of two possible
727reductions (applications of a grammar rule) applies, or whether to apply
728a reduction or read more of the input and apply a reduction later in the
729input. These are known respectively as @dfn{reduce/reduce} conflicts
730(@pxref{Reduce/Reduce}), and @dfn{shift/reduce} conflicts
731(@pxref{Shift/Reduce}).
732
35430378 733To use a grammar that is not easily modified to be LR(1), a
9501dc6e 734more general parsing algorithm is sometimes necessary. If you include
676385e2 735@code{%glr-parser} among the Bison declarations in your file
35430378
JD
736(@pxref{Grammar Outline}), the result is a Generalized LR
737(GLR) parser. These parsers handle Bison grammars that
9501dc6e 738contain no unresolved conflicts (i.e., after applying precedence
34a6c2d1 739declarations) identically to deterministic parsers. However, when
9501dc6e 740faced with unresolved shift/reduce and reduce/reduce conflicts,
35430378 741GLR parsers use the simple expedient of doing both,
9501dc6e
AD
742effectively cloning the parser to follow both possibilities. Each of
743the resulting parsers can again split, so that at any given time, there
744can be any number of possible parses being explored. The parsers
676385e2
PH
745proceed in lockstep; that is, all of them consume (shift) a given input
746symbol before any of them proceed to the next. Each of the cloned
747parsers eventually meets one of two possible fates: either it runs into
748a parsing error, in which case it simply vanishes, or it merges with
749another parser, because the two of them have reduced the input to an
750identical set of symbols.
751
752During the time that there are multiple parsers, semantic actions are
753recorded, but not performed. When a parser disappears, its recorded
754semantic actions disappear as well, and are never performed. When a
755reduction makes two parsers identical, causing them to merge, Bison
756records both sets of semantic actions. Whenever the last two parsers
757merge, reverting to the single-parser case, Bison resolves all the
758outstanding actions either by precedences given to the grammar rules
759involved, or by performing both actions, and then calling a designated
760user-defined function on the resulting values to produce an arbitrary
761merged result.
762
fa7e68c3 763@menu
35430378
JD
764* Simple GLR Parsers:: Using GLR parsers on unambiguous grammars.
765* Merging GLR Parses:: Using GLR parsers to resolve ambiguities.
f56274a8 766* GLR Semantic Actions:: Deferred semantic actions have special concerns.
35430378 767* Compiler Requirements:: GLR parsers require a modern C compiler.
fa7e68c3
PE
768@end menu
769
770@node Simple GLR Parsers
35430378
JD
771@subsection Using GLR on Unambiguous Grammars
772@cindex GLR parsing, unambiguous grammars
773@cindex generalized LR (GLR) parsing, unambiguous grammars
fa7e68c3
PE
774@findex %glr-parser
775@findex %expect-rr
776@cindex conflicts
777@cindex reduce/reduce conflicts
778@cindex shift/reduce conflicts
779
35430378
JD
780In the simplest cases, you can use the GLR algorithm
781to parse grammars that are unambiguous but fail to be LR(1).
34a6c2d1 782Such grammars typically require more than one symbol of lookahead.
fa7e68c3
PE
783
784Consider a problem that
785arises in the declaration of enumerated and subrange types in the
786programming language Pascal. Here are some examples:
787
788@example
789type subrange = lo .. hi;
790type enum = (a, b, c);
791@end example
792
793@noindent
794The original language standard allows only numeric
795literals and constant identifiers for the subrange bounds (@samp{lo}
35430378 796and @samp{hi}), but Extended Pascal (ISO/IEC
fa7e68c3
PE
79710206) and many other
798Pascal implementations allow arbitrary expressions there. This gives
799rise to the following situation, containing a superfluous pair of
800parentheses:
801
802@example
803type subrange = (a) .. b;
804@end example
805
806@noindent
807Compare this to the following declaration of an enumerated
808type with only one value:
809
810@example
811type enum = (a);
812@end example
813
814@noindent
815(These declarations are contrived, but they are syntactically
816valid, and more-complicated cases can come up in practical programs.)
817
818These two declarations look identical until the @samp{..} token.
35430378 819With normal LR(1) one-token lookahead it is not
fa7e68c3
PE
820possible to decide between the two forms when the identifier
821@samp{a} is parsed. It is, however, desirable
822for a parser to decide this, since in the latter case
823@samp{a} must become a new identifier to represent the enumeration
824value, while in the former case @samp{a} must be evaluated with its
825current meaning, which may be a constant or even a function call.
826
827You could parse @samp{(a)} as an ``unspecified identifier in parentheses'',
828to be resolved later, but this typically requires substantial
829contortions in both semantic actions and large parts of the
830grammar, where the parentheses are nested in the recursive rules for
831expressions.
832
833You might think of using the lexer to distinguish between the two
834forms by returning different tokens for currently defined and
835undefined identifiers. But if these declarations occur in a local
836scope, and @samp{a} is defined in an outer scope, then both forms
837are possible---either locally redefining @samp{a}, or using the
838value of @samp{a} from the outer scope. So this approach cannot
839work.
840
e757bb10 841A simple solution to this problem is to declare the parser to
35430378
JD
842use the GLR algorithm.
843When the GLR parser reaches the critical state, it
fa7e68c3
PE
844merely splits into two branches and pursues both syntax rules
845simultaneously. Sooner or later, one of them runs into a parsing
846error. If there is a @samp{..} token before the next
847@samp{;}, the rule for enumerated types fails since it cannot
848accept @samp{..} anywhere; otherwise, the subrange type rule
849fails since it requires a @samp{..} token. So one of the branches
850fails silently, and the other one continues normally, performing
851all the intermediate actions that were postponed during the split.
852
853If the input is syntactically incorrect, both branches fail and the parser
854reports a syntax error as usual.
855
856The effect of all this is that the parser seems to ``guess'' the
857correct branch to take, or in other words, it seems to use more
35430378
JD
858lookahead than the underlying LR(1) algorithm actually allows
859for. In this example, LR(2) would suffice, but also some cases
860that are not LR(@math{k}) for any @math{k} can be handled this way.
fa7e68c3 861
35430378 862In general, a GLR parser can take quadratic or cubic worst-case time,
fa7e68c3
PE
863and the current Bison parser even takes exponential time and space
864for some grammars. In practice, this rarely happens, and for many
865grammars it is possible to prove that it cannot happen.
866The present example contains only one conflict between two
867rules, and the type-declaration context containing the conflict
868cannot be nested. So the number of
869branches that can exist at any time is limited by the constant 2,
870and the parsing time is still linear.
871
872Here is a Bison grammar corresponding to the example above. It
873parses a vastly simplified form of Pascal type declarations.
874
875@example
876%token TYPE DOTDOT ID
877
878@group
879%left '+' '-'
880%left '*' '/'
881@end group
882
883%%
884
885@group
886type_decl : TYPE ID '=' type ';'
887 ;
888@end group
889
890@group
891type : '(' id_list ')'
892 | expr DOTDOT expr
893 ;
894@end group
895
896@group
897id_list : ID
898 | id_list ',' ID
899 ;
900@end group
901
902@group
903expr : '(' expr ')'
904 | expr '+' expr
905 | expr '-' expr
906 | expr '*' expr
907 | expr '/' expr
908 | ID
909 ;
910@end group
911@end example
912
35430378 913When used as a normal LR(1) grammar, Bison correctly complains
fa7e68c3
PE
914about one reduce/reduce conflict. In the conflicting situation the
915parser chooses one of the alternatives, arbitrarily the one
916declared first. Therefore the following correct input is not
917recognized:
918
919@example
920type t = (a) .. b;
921@end example
922
35430378 923The parser can be turned into a GLR parser, while also telling Bison
9913d6e4
JD
924to be silent about the one known reduce/reduce conflict, by adding
925these two declarations to the Bison grammar file (before the first
fa7e68c3
PE
926@samp{%%}):
927
928@example
929%glr-parser
930%expect-rr 1
931@end example
932
933@noindent
934No change in the grammar itself is required. Now the
935parser recognizes all valid declarations, according to the
936limited syntax above, transparently. In fact, the user does not even
937notice when the parser splits.
938
35430378 939So here we have a case where we can use the benefits of GLR,
f8e1c9e5
AD
940almost without disadvantages. Even in simple cases like this, however,
941there are at least two potential problems to beware. First, always
35430378
JD
942analyze the conflicts reported by Bison to make sure that GLR
943splitting is only done where it is intended. A GLR parser
f8e1c9e5 944splitting inadvertently may cause problems less obvious than an
35430378 945LR parser statically choosing the wrong alternative in a
f8e1c9e5
AD
946conflict. Second, consider interactions with the lexer (@pxref{Semantic
947Tokens}) with great care. Since a split parser consumes tokens without
948performing any actions during the split, the lexer cannot obtain
949information via parser actions. Some cases of lexer interactions can be
35430378 950eliminated by using GLR to shift the complications from the
f8e1c9e5
AD
951lexer to the parser. You must check the remaining cases for
952correctness.
953
954In our example, it would be safe for the lexer to return tokens based on
955their current meanings in some symbol table, because no new symbols are
956defined in the middle of a type declaration. Though it is possible for
957a parser to define the enumeration constants as they are parsed, before
958the type declaration is completed, it actually makes no difference since
959they cannot be used within the same enumerated type declaration.
fa7e68c3
PE
960
961@node Merging GLR Parses
35430378
JD
962@subsection Using GLR to Resolve Ambiguities
963@cindex GLR parsing, ambiguous grammars
964@cindex generalized LR (GLR) parsing, ambiguous grammars
fa7e68c3
PE
965@findex %dprec
966@findex %merge
967@cindex conflicts
968@cindex reduce/reduce conflicts
969
2a8d363a 970Let's consider an example, vastly simplified from a C++ grammar.
676385e2
PH
971
972@example
973%@{
38a92d50
PE
974 #include <stdio.h>
975 #define YYSTYPE char const *
976 int yylex (void);
977 void yyerror (char const *);
676385e2
PH
978%@}
979
980%token TYPENAME ID
981
982%right '='
983%left '+'
984
985%glr-parser
986
987%%
988
fae437e8 989prog :
676385e2
PH
990 | prog stmt @{ printf ("\n"); @}
991 ;
992
993stmt : expr ';' %dprec 1
994 | decl %dprec 2
995 ;
996
2a8d363a 997expr : ID @{ printf ("%s ", $$); @}
fae437e8 998 | TYPENAME '(' expr ')'
2a8d363a
AD
999 @{ printf ("%s <cast> ", $1); @}
1000 | expr '+' expr @{ printf ("+ "); @}
1001 | expr '=' expr @{ printf ("= "); @}
676385e2
PH
1002 ;
1003
fae437e8 1004decl : TYPENAME declarator ';'
2a8d363a 1005 @{ printf ("%s <declare> ", $1); @}
676385e2 1006 | TYPENAME declarator '=' expr ';'
2a8d363a 1007 @{ printf ("%s <init-declare> ", $1); @}
676385e2
PH
1008 ;
1009
2a8d363a 1010declarator : ID @{ printf ("\"%s\" ", $1); @}
676385e2
PH
1011 | '(' declarator ')'
1012 ;
1013@end example
1014
1015@noindent
1016This models a problematic part of the C++ grammar---the ambiguity between
1017certain declarations and statements. For example,
1018
1019@example
1020T (x) = y+z;
1021@end example
1022
1023@noindent
1024parses as either an @code{expr} or a @code{stmt}
c827f760
PE
1025(assuming that @samp{T} is recognized as a @code{TYPENAME} and
1026@samp{x} as an @code{ID}).
676385e2 1027Bison detects this as a reduce/reduce conflict between the rules
fae437e8 1028@code{expr : ID} and @code{declarator : ID}, which it cannot resolve at the
e757bb10 1029time it encounters @code{x} in the example above. Since this is a
35430378 1030GLR parser, it therefore splits the problem into two parses, one for
fa7e68c3
PE
1031each choice of resolving the reduce/reduce conflict.
1032Unlike the example from the previous section (@pxref{Simple GLR Parsers}),
1033however, neither of these parses ``dies,'' because the grammar as it stands is
e757bb10
AD
1034ambiguous. One of the parsers eventually reduces @code{stmt : expr ';'} and
1035the other reduces @code{stmt : decl}, after which both parsers are in an
1036identical state: they've seen @samp{prog stmt} and have the same unprocessed
1037input remaining. We say that these parses have @dfn{merged.}
fa7e68c3 1038
35430378 1039At this point, the GLR parser requires a specification in the
fa7e68c3
PE
1040grammar of how to choose between the competing parses.
1041In the example above, the two @code{%dprec}
e757bb10 1042declarations specify that Bison is to give precedence
fa7e68c3 1043to the parse that interprets the example as a
676385e2
PH
1044@code{decl}, which implies that @code{x} is a declarator.
1045The parser therefore prints
1046
1047@example
fae437e8 1048"x" y z + T <init-declare>
676385e2
PH
1049@end example
1050
fa7e68c3
PE
1051The @code{%dprec} declarations only come into play when more than one
1052parse survives. Consider a different input string for this parser:
676385e2
PH
1053
1054@example
1055T (x) + y;
1056@end example
1057
1058@noindent
35430378 1059This is another example of using GLR to parse an unambiguous
fa7e68c3 1060construct, as shown in the previous section (@pxref{Simple GLR Parsers}).
676385e2
PH
1061Here, there is no ambiguity (this cannot be parsed as a declaration).
1062However, at the time the Bison parser encounters @code{x}, it does not
1063have enough information to resolve the reduce/reduce conflict (again,
1064between @code{x} as an @code{expr} or a @code{declarator}). In this
fa7e68c3 1065case, no precedence declaration is used. Again, the parser splits
676385e2
PH
1066into two, one assuming that @code{x} is an @code{expr}, and the other
1067assuming @code{x} is a @code{declarator}. The second of these parsers
1068then vanishes when it sees @code{+}, and the parser prints
1069
1070@example
fae437e8 1071x T <cast> y +
676385e2
PH
1072@end example
1073
1074Suppose that instead of resolving the ambiguity, you wanted to see all
fa7e68c3 1075the possibilities. For this purpose, you must merge the semantic
676385e2
PH
1076actions of the two possible parsers, rather than choosing one over the
1077other. To do so, you could change the declaration of @code{stmt} as
1078follows:
1079
1080@example
1081stmt : expr ';' %merge <stmtMerge>
1082 | decl %merge <stmtMerge>
1083 ;
1084@end example
1085
1086@noindent
676385e2
PH
1087and define the @code{stmtMerge} function as:
1088
1089@example
38a92d50
PE
1090static YYSTYPE
1091stmtMerge (YYSTYPE x0, YYSTYPE x1)
676385e2
PH
1092@{
1093 printf ("<OR> ");
1094 return "";
1095@}
1096@end example
1097
1098@noindent
1099with an accompanying forward declaration
1100in the C declarations at the beginning of the file:
1101
1102@example
1103%@{
38a92d50 1104 #define YYSTYPE char const *
676385e2
PH
1105 static YYSTYPE stmtMerge (YYSTYPE x0, YYSTYPE x1);
1106%@}
1107@end example
1108
1109@noindent
fa7e68c3
PE
1110With these declarations, the resulting parser parses the first example
1111as both an @code{expr} and a @code{decl}, and prints
676385e2
PH
1112
1113@example
fae437e8 1114"x" y z + T <init-declare> x T <cast> y z + = <OR>
676385e2
PH
1115@end example
1116
fa7e68c3 1117Bison requires that all of the
e757bb10 1118productions that participate in any particular merge have identical
fa7e68c3
PE
1119@samp{%merge} clauses. Otherwise, the ambiguity would be unresolvable,
1120and the parser will report an error during any parse that results in
1121the offending merge.
9501dc6e 1122
32c29292
JD
1123@node GLR Semantic Actions
1124@subsection GLR Semantic Actions
1125
1126@cindex deferred semantic actions
1127By definition, a deferred semantic action is not performed at the same time as
1128the associated reduction.
1129This raises caveats for several Bison features you might use in a semantic
35430378 1130action in a GLR parser.
32c29292
JD
1131
1132@vindex yychar
35430378 1133@cindex GLR parsers and @code{yychar}
32c29292 1134@vindex yylval
35430378 1135@cindex GLR parsers and @code{yylval}
32c29292 1136@vindex yylloc
35430378 1137@cindex GLR parsers and @code{yylloc}
32c29292 1138In any semantic action, you can examine @code{yychar} to determine the type of
742e4900 1139the lookahead token present at the time of the associated reduction.
32c29292
JD
1140After checking that @code{yychar} is not set to @code{YYEMPTY} or @code{YYEOF},
1141you can then examine @code{yylval} and @code{yylloc} to determine the
742e4900 1142lookahead token's semantic value and location, if any.
32c29292
JD
1143In a nondeferred semantic action, you can also modify any of these variables to
1144influence syntax analysis.
742e4900 1145@xref{Lookahead, ,Lookahead Tokens}.
32c29292
JD
1146
1147@findex yyclearin
35430378 1148@cindex GLR parsers and @code{yyclearin}
32c29292
JD
1149In a deferred semantic action, it's too late to influence syntax analysis.
1150In this case, @code{yychar}, @code{yylval}, and @code{yylloc} are set to
1151shallow copies of the values they had at the time of the associated reduction.
1152For this reason alone, modifying them is dangerous.
1153Moreover, the result of modifying them is undefined and subject to change with
1154future versions of Bison.
1155For example, if a semantic action might be deferred, you should never write it
1156to invoke @code{yyclearin} (@pxref{Action Features}) or to attempt to free
1157memory referenced by @code{yylval}.
1158
1159@findex YYERROR
35430378 1160@cindex GLR parsers and @code{YYERROR}
32c29292 1161Another Bison feature requiring special consideration is @code{YYERROR}
8710fc41 1162(@pxref{Action Features}), which you can invoke in a semantic action to
32c29292 1163initiate error recovery.
35430378 1164During deterministic GLR operation, the effect of @code{YYERROR} is
34a6c2d1 1165the same as its effect in a deterministic parser.
32c29292
JD
1166In a deferred semantic action, its effect is undefined.
1167@c The effect is probably a syntax error at the split point.
1168
8710fc41 1169Also, see @ref{Location Default Action, ,Default Action for Locations}, which
35430378 1170describes a special usage of @code{YYLLOC_DEFAULT} in GLR parsers.
8710fc41 1171
fa7e68c3 1172@node Compiler Requirements
35430378 1173@subsection Considerations when Compiling GLR Parsers
fa7e68c3 1174@cindex @code{inline}
35430378 1175@cindex GLR parsers and @code{inline}
fa7e68c3 1176
35430378 1177The GLR parsers require a compiler for ISO C89 or
38a92d50
PE
1178later. In addition, they use the @code{inline} keyword, which is not
1179C89, but is C99 and is a common extension in pre-C99 compilers. It is
1180up to the user of these parsers to handle
9501dc6e
AD
1181portability issues. For instance, if using Autoconf and the Autoconf
1182macro @code{AC_C_INLINE}, a mere
1183
1184@example
1185%@{
38a92d50 1186 #include <config.h>
9501dc6e
AD
1187%@}
1188@end example
1189
1190@noindent
1191will suffice. Otherwise, we suggest
1192
1193@example
1194%@{
38a92d50
PE
1195 #if __STDC_VERSION__ < 199901 && ! defined __GNUC__ && ! defined inline
1196 #define inline
1197 #endif
9501dc6e
AD
1198%@}
1199@end example
676385e2 1200
342b8b6e 1201@node Locations Overview
847bf1f5
AD
1202@section Locations
1203@cindex location
95923bd6
AD
1204@cindex textual location
1205@cindex location, textual
847bf1f5
AD
1206
1207Many applications, like interpreters or compilers, have to produce verbose
72d2299c 1208and useful error messages. To achieve this, one must be able to keep track of
95923bd6 1209the @dfn{textual location}, or @dfn{location}, of each syntactic construct.
847bf1f5
AD
1210Bison provides a mechanism for handling these locations.
1211
72d2299c 1212Each token has a semantic value. In a similar fashion, each token has an
847bf1f5 1213associated location, but the type of locations is the same for all tokens and
72d2299c 1214groupings. Moreover, the output parser is equipped with a default data
847bf1f5
AD
1215structure for storing locations (@pxref{Locations}, for more details).
1216
1217Like semantic values, locations can be reached in actions using a dedicated
72d2299c 1218set of constructs. In the example above, the location of the whole grouping
847bf1f5
AD
1219is @code{@@$}, while the locations of the subexpressions are @code{@@1} and
1220@code{@@3}.
1221
1222When a rule is matched, a default action is used to compute the semantic value
72d2299c
PE
1223of its left hand side (@pxref{Actions}). In the same way, another default
1224action is used for locations. However, the action for locations is general
847bf1f5 1225enough for most cases, meaning there is usually no need to describe for each
72d2299c 1226rule how @code{@@$} should be formed. When building a new location for a given
847bf1f5
AD
1227grouping, the default behavior of the output parser is to take the beginning
1228of the first symbol, and the end of the last symbol.
1229
342b8b6e 1230@node Bison Parser
9913d6e4 1231@section Bison Output: the Parser Implementation File
bfa74976
RS
1232@cindex Bison parser
1233@cindex Bison utility
1234@cindex lexical analyzer, purpose
1235@cindex parser
1236
9913d6e4
JD
1237When you run Bison, you give it a Bison grammar file as input. The
1238most important output is a C source file that implements a parser for
1239the language described by the grammar. This parser is called a
1240@dfn{Bison parser}, and this file is called a @dfn{Bison parser
1241implementation file}. Keep in mind that the Bison utility and the
1242Bison parser are two distinct programs: the Bison utility is a program
1243whose output is the Bison parser implementation file that becomes part
1244of your program.
bfa74976
RS
1245
1246The job of the Bison parser is to group tokens into groupings according to
1247the grammar rules---for example, to build identifiers and operators into
1248expressions. As it does this, it runs the actions for the grammar rules it
1249uses.
1250
704a47c4
AD
1251The tokens come from a function called the @dfn{lexical analyzer} that
1252you must supply in some fashion (such as by writing it in C). The Bison
1253parser calls the lexical analyzer each time it wants a new token. It
1254doesn't know what is ``inside'' the tokens (though their semantic values
1255may reflect this). Typically the lexical analyzer makes the tokens by
1256parsing characters of text, but Bison does not depend on this.
1257@xref{Lexical, ,The Lexical Analyzer Function @code{yylex}}.
bfa74976 1258
9913d6e4
JD
1259The Bison parser implementation file is C code which defines a
1260function named @code{yyparse} which implements that grammar. This
1261function does not make a complete C program: you must supply some
1262additional functions. One is the lexical analyzer. Another is an
1263error-reporting function which the parser calls to report an error.
1264In addition, a complete C program must start with a function called
1265@code{main}; you have to provide this, and arrange for it to call
1266@code{yyparse} or the parser will never run. @xref{Interface, ,Parser
1267C-Language Interface}.
bfa74976 1268
f7ab6a50 1269Aside from the token type names and the symbols in the actions you
9913d6e4
JD
1270write, all symbols defined in the Bison parser implementation file
1271itself begin with @samp{yy} or @samp{YY}. This includes interface
1272functions such as the lexical analyzer function @code{yylex}, the
1273error reporting function @code{yyerror} and the parser function
1274@code{yyparse} itself. This also includes numerous identifiers used
1275for internal purposes. Therefore, you should avoid using C
1276identifiers starting with @samp{yy} or @samp{YY} in the Bison grammar
1277file except for the ones defined in this manual. Also, you should
1278avoid using the C identifiers @samp{malloc} and @samp{free} for
1279anything other than their usual meanings.
1280
1281In some cases the Bison parser implementation file includes system
1282headers, and in those cases your code should respect the identifiers
1283reserved by those headers. On some non-GNU hosts, @code{<alloca.h>},
1284@code{<malloc.h>}, @code{<stddef.h>}, and @code{<stdlib.h>} are
1285included as needed to declare memory allocators and related types.
1286@code{<libintl.h>} is included if message translation is in use
1287(@pxref{Internationalization}). Other system headers may be included
1288if you define @code{YYDEBUG} to a nonzero value (@pxref{Tracing,
1289,Tracing Your Parser}).
7093d0f5 1290
342b8b6e 1291@node Stages
bfa74976
RS
1292@section Stages in Using Bison
1293@cindex stages in using Bison
1294@cindex using Bison
1295
1296The actual language-design process using Bison, from grammar specification
1297to a working compiler or interpreter, has these parts:
1298
1299@enumerate
1300@item
1301Formally specify the grammar in a form recognized by Bison
704a47c4
AD
1302(@pxref{Grammar File, ,Bison Grammar Files}). For each grammatical rule
1303in the language, describe the action that is to be taken when an
1304instance of that rule is recognized. The action is described by a
1305sequence of C statements.
bfa74976
RS
1306
1307@item
704a47c4
AD
1308Write a lexical analyzer to process input and pass tokens to the parser.
1309The lexical analyzer may be written by hand in C (@pxref{Lexical, ,The
1310Lexical Analyzer Function @code{yylex}}). It could also be produced
1311using Lex, but the use of Lex is not discussed in this manual.
bfa74976
RS
1312
1313@item
1314Write a controlling function that calls the Bison-produced parser.
1315
1316@item
1317Write error-reporting routines.
1318@end enumerate
1319
1320To turn this source code as written into a runnable program, you
1321must follow these steps:
1322
1323@enumerate
1324@item
1325Run Bison on the grammar to produce the parser.
1326
1327@item
1328Compile the code output by Bison, as well as any other source files.
1329
1330@item
1331Link the object files to produce the finished product.
1332@end enumerate
1333
342b8b6e 1334@node Grammar Layout
bfa74976
RS
1335@section The Overall Layout of a Bison Grammar
1336@cindex grammar file
1337@cindex file format
1338@cindex format of grammar file
1339@cindex layout of Bison grammar
1340
1341The input file for the Bison utility is a @dfn{Bison grammar file}. The
1342general form of a Bison grammar file is as follows:
1343
1344@example
1345%@{
08e49d20 1346@var{Prologue}
bfa74976
RS
1347%@}
1348
1349@var{Bison declarations}
1350
1351%%
1352@var{Grammar rules}
1353%%
08e49d20 1354@var{Epilogue}
bfa74976
RS
1355@end example
1356
1357@noindent
1358The @samp{%%}, @samp{%@{} and @samp{%@}} are punctuation that appears
1359in every Bison grammar file to separate the sections.
1360
72d2299c 1361The prologue may define types and variables used in the actions. You can
342b8b6e 1362also use preprocessor commands to define macros used there, and use
bfa74976 1363@code{#include} to include header files that do any of these things.
38a92d50
PE
1364You need to declare the lexical analyzer @code{yylex} and the error
1365printer @code{yyerror} here, along with any other global identifiers
1366used by the actions in the grammar rules.
bfa74976
RS
1367
1368The Bison declarations declare the names of the terminal and nonterminal
1369symbols, and may also describe operator precedence and the data types of
1370semantic values of various symbols.
1371
1372The grammar rules define how to construct each nonterminal symbol from its
1373parts.
1374
38a92d50
PE
1375The epilogue can contain any code you want to use. Often the
1376definitions of functions declared in the prologue go here. In a
1377simple program, all the rest of the program can go here.
bfa74976 1378
342b8b6e 1379@node Examples
bfa74976
RS
1380@chapter Examples
1381@cindex simple examples
1382@cindex examples, simple
1383
1384Now we show and explain three sample programs written using Bison: a
1385reverse polish notation calculator, an algebraic (infix) notation
1386calculator, and a multi-function calculator. All three have been tested
1387under BSD Unix 4.3; each produces a usable, though limited, interactive
1388desk-top calculator.
1389
1390These examples are simple, but Bison grammars for real programming
aa08666d
AD
1391languages are written the same way. You can copy these examples into a
1392source file to try them.
bfa74976
RS
1393
1394@menu
f56274a8
DJ
1395* RPN Calc:: Reverse polish notation calculator;
1396 a first example with no operator precedence.
1397* Infix Calc:: Infix (algebraic) notation calculator.
1398 Operator precedence is introduced.
bfa74976 1399* Simple Error Recovery:: Continuing after syntax errors.
342b8b6e 1400* Location Tracking Calc:: Demonstrating the use of @@@var{n} and @@$.
f56274a8
DJ
1401* Multi-function Calc:: Calculator with memory and trig functions.
1402 It uses multiple data-types for semantic values.
1403* Exercises:: Ideas for improving the multi-function calculator.
bfa74976
RS
1404@end menu
1405
342b8b6e 1406@node RPN Calc
bfa74976
RS
1407@section Reverse Polish Notation Calculator
1408@cindex reverse polish notation
1409@cindex polish notation calculator
1410@cindex @code{rpcalc}
1411@cindex calculator, simple
1412
1413The first example is that of a simple double-precision @dfn{reverse polish
1414notation} calculator (a calculator using postfix operators). This example
1415provides a good starting point, since operator precedence is not an issue.
1416The second example will illustrate how operator precedence is handled.
1417
1418The source code for this calculator is named @file{rpcalc.y}. The
9913d6e4 1419@samp{.y} extension is a convention used for Bison grammar files.
bfa74976
RS
1420
1421@menu
f56274a8
DJ
1422* Rpcalc Declarations:: Prologue (declarations) for rpcalc.
1423* Rpcalc Rules:: Grammar Rules for rpcalc, with explanation.
1424* Rpcalc Lexer:: The lexical analyzer.
1425* Rpcalc Main:: The controlling function.
1426* Rpcalc Error:: The error reporting function.
1427* Rpcalc Generate:: Running Bison on the grammar file.
1428* Rpcalc Compile:: Run the C compiler on the output code.
bfa74976
RS
1429@end menu
1430
f56274a8 1431@node Rpcalc Declarations
bfa74976
RS
1432@subsection Declarations for @code{rpcalc}
1433
1434Here are the C and Bison declarations for the reverse polish notation
1435calculator. As in C, comments are placed between @samp{/*@dots{}*/}.
1436
1437@example
72d2299c 1438/* Reverse polish notation calculator. */
bfa74976
RS
1439
1440%@{
38a92d50
PE
1441 #define YYSTYPE double
1442 #include <math.h>
1443 int yylex (void);
1444 void yyerror (char const *);
bfa74976
RS
1445%@}
1446
1447%token NUM
1448
72d2299c 1449%% /* Grammar rules and actions follow. */
bfa74976
RS
1450@end example
1451
75f5aaea 1452The declarations section (@pxref{Prologue, , The prologue}) contains two
38a92d50 1453preprocessor directives and two forward declarations.
bfa74976
RS
1454
1455The @code{#define} directive defines the macro @code{YYSTYPE}, thus
1964ad8c
AD
1456specifying the C data type for semantic values of both tokens and
1457groupings (@pxref{Value Type, ,Data Types of Semantic Values}). The
1458Bison parser will use whatever type @code{YYSTYPE} is defined as; if you
1459don't define it, @code{int} is the default. Because we specify
1460@code{double}, each token and each expression has an associated value,
1461which is a floating point number.
bfa74976
RS
1462
1463The @code{#include} directive is used to declare the exponentiation
1464function @code{pow}.
1465
38a92d50
PE
1466The forward declarations for @code{yylex} and @code{yyerror} are
1467needed because the C language requires that functions be declared
1468before they are used. These functions will be defined in the
1469epilogue, but the parser calls them so they must be declared in the
1470prologue.
1471
704a47c4
AD
1472The second section, Bison declarations, provides information to Bison
1473about the token types (@pxref{Bison Declarations, ,The Bison
1474Declarations Section}). Each terminal symbol that is not a
1475single-character literal must be declared here. (Single-character
bfa74976
RS
1476literals normally don't need to be declared.) In this example, all the
1477arithmetic operators are designated by single-character literals, so the
1478only terminal symbol that needs to be declared is @code{NUM}, the token
1479type for numeric constants.
1480
342b8b6e 1481@node Rpcalc Rules
bfa74976
RS
1482@subsection Grammar Rules for @code{rpcalc}
1483
1484Here are the grammar rules for the reverse polish notation calculator.
1485
1486@example
1487input: /* empty */
1488 | input line
1489;
1490
1491line: '\n'
18b519c0 1492 | exp '\n' @{ printf ("\t%.10g\n", $1); @}
bfa74976
RS
1493;
1494
18b519c0
AD
1495exp: NUM @{ $$ = $1; @}
1496 | exp exp '+' @{ $$ = $1 + $2; @}
1497 | exp exp '-' @{ $$ = $1 - $2; @}
1498 | exp exp '*' @{ $$ = $1 * $2; @}
1499 | exp exp '/' @{ $$ = $1 / $2; @}
1500 /* Exponentiation */
1501 | exp exp '^' @{ $$ = pow ($1, $2); @}
1502 /* Unary minus */
1503 | exp 'n' @{ $$ = -$1; @}
bfa74976
RS
1504;
1505%%
1506@end example
1507
1508The groupings of the rpcalc ``language'' defined here are the expression
1509(given the name @code{exp}), the line of input (@code{line}), and the
1510complete input transcript (@code{input}). Each of these nonterminal
8c5b881d 1511symbols has several alternate rules, joined by the vertical bar @samp{|}
bfa74976
RS
1512which is read as ``or''. The following sections explain what these rules
1513mean.
1514
1515The semantics of the language is determined by the actions taken when a
1516grouping is recognized. The actions are the C code that appears inside
1517braces. @xref{Actions}.
1518
1519You must specify these actions in C, but Bison provides the means for
1520passing semantic values between the rules. In each action, the
1521pseudo-variable @code{$$} stands for the semantic value for the grouping
1522that the rule is going to construct. Assigning a value to @code{$$} is the
1523main job of most actions. The semantic values of the components of the
1524rule are referred to as @code{$1}, @code{$2}, and so on.
1525
1526@menu
13863333
AD
1527* Rpcalc Input::
1528* Rpcalc Line::
1529* Rpcalc Expr::
bfa74976
RS
1530@end menu
1531
342b8b6e 1532@node Rpcalc Input
bfa74976
RS
1533@subsubsection Explanation of @code{input}
1534
1535Consider the definition of @code{input}:
1536
1537@example
1538input: /* empty */
1539 | input line
1540;
1541@end example
1542
1543This definition reads as follows: ``A complete input is either an empty
1544string, or a complete input followed by an input line''. Notice that
1545``complete input'' is defined in terms of itself. This definition is said
1546to be @dfn{left recursive} since @code{input} appears always as the
1547leftmost symbol in the sequence. @xref{Recursion, ,Recursive Rules}.
1548
1549The first alternative is empty because there are no symbols between the
1550colon and the first @samp{|}; this means that @code{input} can match an
1551empty string of input (no tokens). We write the rules this way because it
1552is legitimate to type @kbd{Ctrl-d} right after you start the calculator.
1553It's conventional to put an empty alternative first and write the comment
1554@samp{/* empty */} in it.
1555
1556The second alternate rule (@code{input line}) handles all nontrivial input.
1557It means, ``After reading any number of lines, read one more line if
1558possible.'' The left recursion makes this rule into a loop. Since the
1559first alternative matches empty input, the loop can be executed zero or
1560more times.
1561
1562The parser function @code{yyparse} continues to process input until a
1563grammatical error is seen or the lexical analyzer says there are no more
72d2299c 1564input tokens; we will arrange for the latter to happen at end-of-input.
bfa74976 1565
342b8b6e 1566@node Rpcalc Line
bfa74976
RS
1567@subsubsection Explanation of @code{line}
1568
1569Now consider the definition of @code{line}:
1570
1571@example
1572line: '\n'
1573 | exp '\n' @{ printf ("\t%.10g\n", $1); @}
1574;
1575@end example
1576
1577The first alternative is a token which is a newline character; this means
1578that rpcalc accepts a blank line (and ignores it, since there is no
1579action). The second alternative is an expression followed by a newline.
1580This is the alternative that makes rpcalc useful. The semantic value of
1581the @code{exp} grouping is the value of @code{$1} because the @code{exp} in
1582question is the first symbol in the alternative. The action prints this
1583value, which is the result of the computation the user asked for.
1584
1585This action is unusual because it does not assign a value to @code{$$}. As
1586a consequence, the semantic value associated with the @code{line} is
1587uninitialized (its value will be unpredictable). This would be a bug if
1588that value were ever used, but we don't use it: once rpcalc has printed the
1589value of the user's input line, that value is no longer needed.
1590
342b8b6e 1591@node Rpcalc Expr
bfa74976
RS
1592@subsubsection Explanation of @code{expr}
1593
1594The @code{exp} grouping has several rules, one for each kind of expression.
1595The first rule handles the simplest expressions: those that are just numbers.
1596The second handles an addition-expression, which looks like two expressions
1597followed by a plus-sign. The third handles subtraction, and so on.
1598
1599@example
1600exp: NUM
1601 | exp exp '+' @{ $$ = $1 + $2; @}
1602 | exp exp '-' @{ $$ = $1 - $2; @}
1603 @dots{}
1604 ;
1605@end example
1606
1607We have used @samp{|} to join all the rules for @code{exp}, but we could
1608equally well have written them separately:
1609
1610@example
1611exp: NUM ;
1612exp: exp exp '+' @{ $$ = $1 + $2; @} ;
1613exp: exp exp '-' @{ $$ = $1 - $2; @} ;
1614 @dots{}
1615@end example
1616
1617Most of the rules have actions that compute the value of the expression in
1618terms of the value of its parts. For example, in the rule for addition,
1619@code{$1} refers to the first component @code{exp} and @code{$2} refers to
1620the second one. The third component, @code{'+'}, has no meaningful
1621associated semantic value, but if it had one you could refer to it as
1622@code{$3}. When @code{yyparse} recognizes a sum expression using this
1623rule, the sum of the two subexpressions' values is produced as the value of
1624the entire expression. @xref{Actions}.
1625
1626You don't have to give an action for every rule. When a rule has no
1627action, Bison by default copies the value of @code{$1} into @code{$$}.
1628This is what happens in the first rule (the one that uses @code{NUM}).
1629
1630The formatting shown here is the recommended convention, but Bison does
72d2299c 1631not require it. You can add or change white space as much as you wish.
bfa74976
RS
1632For example, this:
1633
1634@example
99a9344e 1635exp : NUM | exp exp '+' @{$$ = $1 + $2; @} | @dots{} ;
bfa74976
RS
1636@end example
1637
1638@noindent
1639means the same thing as this:
1640
1641@example
1642exp: NUM
1643 | exp exp '+' @{ $$ = $1 + $2; @}
1644 | @dots{}
99a9344e 1645;
bfa74976
RS
1646@end example
1647
1648@noindent
1649The latter, however, is much more readable.
1650
342b8b6e 1651@node Rpcalc Lexer
bfa74976
RS
1652@subsection The @code{rpcalc} Lexical Analyzer
1653@cindex writing a lexical analyzer
1654@cindex lexical analyzer, writing
1655
704a47c4
AD
1656The lexical analyzer's job is low-level parsing: converting characters
1657or sequences of characters into tokens. The Bison parser gets its
1658tokens by calling the lexical analyzer. @xref{Lexical, ,The Lexical
1659Analyzer Function @code{yylex}}.
bfa74976 1660
35430378 1661Only a simple lexical analyzer is needed for the RPN
c827f760 1662calculator. This
bfa74976
RS
1663lexical analyzer skips blanks and tabs, then reads in numbers as
1664@code{double} and returns them as @code{NUM} tokens. Any other character
1665that isn't part of a number is a separate token. Note that the token-code
1666for such a single-character token is the character itself.
1667
1668The return value of the lexical analyzer function is a numeric code which
1669represents a token type. The same text used in Bison rules to stand for
1670this token type is also a C expression for the numeric code for the type.
1671This works in two ways. If the token type is a character literal, then its
e966383b 1672numeric code is that of the character; you can use the same
bfa74976
RS
1673character literal in the lexical analyzer to express the number. If the
1674token type is an identifier, that identifier is defined by Bison as a C
1675macro whose definition is the appropriate number. In this example,
1676therefore, @code{NUM} becomes a macro for @code{yylex} to use.
1677
1964ad8c
AD
1678The semantic value of the token (if it has one) is stored into the
1679global variable @code{yylval}, which is where the Bison parser will look
1680for it. (The C data type of @code{yylval} is @code{YYSTYPE}, which was
f56274a8 1681defined at the beginning of the grammar; @pxref{Rpcalc Declarations,
1964ad8c 1682,Declarations for @code{rpcalc}}.)
bfa74976 1683
72d2299c
PE
1684A token type code of zero is returned if the end-of-input is encountered.
1685(Bison recognizes any nonpositive value as indicating end-of-input.)
bfa74976
RS
1686
1687Here is the code for the lexical analyzer:
1688
1689@example
1690@group
72d2299c 1691/* The lexical analyzer returns a double floating point
e966383b 1692 number on the stack and the token NUM, or the numeric code
72d2299c
PE
1693 of the character read if not a number. It skips all blanks
1694 and tabs, and returns 0 for end-of-input. */
bfa74976
RS
1695
1696#include <ctype.h>
1697@end group
1698
1699@group
13863333
AD
1700int
1701yylex (void)
bfa74976
RS
1702@{
1703 int c;
1704
72d2299c 1705 /* Skip white space. */
13863333 1706 while ((c = getchar ()) == ' ' || c == '\t')
bfa74976
RS
1707 ;
1708@end group
1709@group
72d2299c 1710 /* Process numbers. */
13863333 1711 if (c == '.' || isdigit (c))
bfa74976
RS
1712 @{
1713 ungetc (c, stdin);
1714 scanf ("%lf", &yylval);
1715 return NUM;
1716 @}
1717@end group
1718@group
72d2299c 1719 /* Return end-of-input. */
13863333 1720 if (c == EOF)
bfa74976 1721 return 0;
72d2299c 1722 /* Return a single char. */
13863333 1723 return c;
bfa74976
RS
1724@}
1725@end group
1726@end example
1727
342b8b6e 1728@node Rpcalc Main
bfa74976
RS
1729@subsection The Controlling Function
1730@cindex controlling function
1731@cindex main function in simple example
1732
1733In keeping with the spirit of this example, the controlling function is
1734kept to the bare minimum. The only requirement is that it call
1735@code{yyparse} to start the process of parsing.
1736
1737@example
1738@group
13863333
AD
1739int
1740main (void)
bfa74976 1741@{
13863333 1742 return yyparse ();
bfa74976
RS
1743@}
1744@end group
1745@end example
1746
342b8b6e 1747@node Rpcalc Error
bfa74976
RS
1748@subsection The Error Reporting Routine
1749@cindex error reporting routine
1750
1751When @code{yyparse} detects a syntax error, it calls the error reporting
13863333 1752function @code{yyerror} to print an error message (usually but not
6e649e65 1753always @code{"syntax error"}). It is up to the programmer to supply
13863333
AD
1754@code{yyerror} (@pxref{Interface, ,Parser C-Language Interface}), so
1755here is the definition we will use:
bfa74976
RS
1756
1757@example
1758@group
1759#include <stdio.h>
1760
38a92d50 1761/* Called by yyparse on error. */
13863333 1762void
38a92d50 1763yyerror (char const *s)
bfa74976 1764@{
4e03e201 1765 fprintf (stderr, "%s\n", s);
bfa74976
RS
1766@}
1767@end group
1768@end example
1769
1770After @code{yyerror} returns, the Bison parser may recover from the error
1771and continue parsing if the grammar contains a suitable error rule
1772(@pxref{Error Recovery}). Otherwise, @code{yyparse} returns nonzero. We
1773have not written any error rules in this example, so any invalid input will
1774cause the calculator program to exit. This is not clean behavior for a
9ecbd125 1775real calculator, but it is adequate for the first example.
bfa74976 1776
f56274a8 1777@node Rpcalc Generate
bfa74976
RS
1778@subsection Running Bison to Make the Parser
1779@cindex running Bison (introduction)
1780
ceed8467
AD
1781Before running Bison to produce a parser, we need to decide how to
1782arrange all the source code in one or more source files. For such a
9913d6e4
JD
1783simple example, the easiest thing is to put everything in one file,
1784the grammar file. The definitions of @code{yylex}, @code{yyerror} and
1785@code{main} go at the end, in the epilogue of the grammar file
75f5aaea 1786(@pxref{Grammar Layout, ,The Overall Layout of a Bison Grammar}).
bfa74976
RS
1787
1788For a large project, you would probably have several source files, and use
1789@code{make} to arrange to recompile them.
1790
9913d6e4
JD
1791With all the source in the grammar file, you use the following command
1792to convert it into a parser implementation file:
bfa74976
RS
1793
1794@example
fa4d969f 1795bison @var{file}.y
bfa74976
RS
1796@end example
1797
1798@noindent
9913d6e4
JD
1799In this example, the grammar file is called @file{rpcalc.y} (for
1800``Reverse Polish @sc{calc}ulator''). Bison produces a parser
1801implementation file named @file{@var{file}.tab.c}, removing the
1802@samp{.y} from the grammar file name. The parser implementation file
1803contains the source code for @code{yyparse}. The additional functions
1804in the grammar file (@code{yylex}, @code{yyerror} and @code{main}) are
1805copied verbatim to the parser implementation file.
bfa74976 1806
342b8b6e 1807@node Rpcalc Compile
9913d6e4 1808@subsection Compiling the Parser Implementation File
bfa74976
RS
1809@cindex compiling the parser
1810
9913d6e4 1811Here is how to compile and run the parser implementation file:
bfa74976
RS
1812
1813@example
1814@group
1815# @r{List files in current directory.}
9edcd895 1816$ @kbd{ls}
bfa74976
RS
1817rpcalc.tab.c rpcalc.y
1818@end group
1819
1820@group
1821# @r{Compile the Bison parser.}
1822# @r{@samp{-lm} tells compiler to search math library for @code{pow}.}
b56471a6 1823$ @kbd{cc -lm -o rpcalc rpcalc.tab.c}
bfa74976
RS
1824@end group
1825
1826@group
1827# @r{List files again.}
9edcd895 1828$ @kbd{ls}
bfa74976
RS
1829rpcalc rpcalc.tab.c rpcalc.y
1830@end group
1831@end example
1832
1833The file @file{rpcalc} now contains the executable code. Here is an
1834example session using @code{rpcalc}.
1835
1836@example
9edcd895
AD
1837$ @kbd{rpcalc}
1838@kbd{4 9 +}
bfa74976 183913
9edcd895 1840@kbd{3 7 + 3 4 5 *+-}
bfa74976 1841-13
9edcd895 1842@kbd{3 7 + 3 4 5 * + - n} @r{Note the unary minus, @samp{n}}
bfa74976 184313
9edcd895 1844@kbd{5 6 / 4 n +}
bfa74976 1845-3.166666667
9edcd895 1846@kbd{3 4 ^} @r{Exponentiation}
bfa74976 184781
9edcd895
AD
1848@kbd{^D} @r{End-of-file indicator}
1849$
bfa74976
RS
1850@end example
1851
342b8b6e 1852@node Infix Calc
bfa74976
RS
1853@section Infix Notation Calculator: @code{calc}
1854@cindex infix notation calculator
1855@cindex @code{calc}
1856@cindex calculator, infix notation
1857
1858We now modify rpcalc to handle infix operators instead of postfix. Infix
1859notation involves the concept of operator precedence and the need for
1860parentheses nested to arbitrary depth. Here is the Bison code for
1861@file{calc.y}, an infix desk-top calculator.
1862
1863@example
38a92d50 1864/* Infix notation calculator. */
bfa74976
RS
1865
1866%@{
38a92d50
PE
1867 #define YYSTYPE double
1868 #include <math.h>
1869 #include <stdio.h>
1870 int yylex (void);
1871 void yyerror (char const *);
bfa74976
RS
1872%@}
1873
38a92d50 1874/* Bison declarations. */
bfa74976
RS
1875%token NUM
1876%left '-' '+'
1877%left '*' '/'
1878%left NEG /* negation--unary minus */
38a92d50 1879%right '^' /* exponentiation */
bfa74976 1880
38a92d50
PE
1881%% /* The grammar follows. */
1882input: /* empty */
bfa74976
RS
1883 | input line
1884;
1885
1886line: '\n'
1887 | exp '\n' @{ printf ("\t%.10g\n", $1); @}
1888;
1889
1890exp: NUM @{ $$ = $1; @}
1891 | exp '+' exp @{ $$ = $1 + $3; @}
1892 | exp '-' exp @{ $$ = $1 - $3; @}
1893 | exp '*' exp @{ $$ = $1 * $3; @}
1894 | exp '/' exp @{ $$ = $1 / $3; @}
1895 | '-' exp %prec NEG @{ $$ = -$2; @}
1896 | exp '^' exp @{ $$ = pow ($1, $3); @}
1897 | '(' exp ')' @{ $$ = $2; @}
1898;
1899%%
1900@end example
1901
1902@noindent
ceed8467
AD
1903The functions @code{yylex}, @code{yyerror} and @code{main} can be the
1904same as before.
bfa74976
RS
1905
1906There are two important new features shown in this code.
1907
1908In the second section (Bison declarations), @code{%left} declares token
1909types and says they are left-associative operators. The declarations
1910@code{%left} and @code{%right} (right associativity) take the place of
1911@code{%token} which is used to declare a token type name without
1912associativity. (These tokens are single-character literals, which
1913ordinarily don't need to be declared. We declare them here to specify
1914the associativity.)
1915
1916Operator precedence is determined by the line ordering of the
1917declarations; the higher the line number of the declaration (lower on
1918the page or screen), the higher the precedence. Hence, exponentiation
1919has the highest precedence, unary minus (@code{NEG}) is next, followed
704a47c4
AD
1920by @samp{*} and @samp{/}, and so on. @xref{Precedence, ,Operator
1921Precedence}.
bfa74976 1922
704a47c4
AD
1923The other important new feature is the @code{%prec} in the grammar
1924section for the unary minus operator. The @code{%prec} simply instructs
1925Bison that the rule @samp{| '-' exp} has the same precedence as
1926@code{NEG}---in this case the next-to-highest. @xref{Contextual
1927Precedence, ,Context-Dependent Precedence}.
bfa74976
RS
1928
1929Here is a sample run of @file{calc.y}:
1930
1931@need 500
1932@example
9edcd895
AD
1933$ @kbd{calc}
1934@kbd{4 + 4.5 - (34/(8*3+-3))}
bfa74976 19356.880952381
9edcd895 1936@kbd{-56 + 2}
bfa74976 1937-54
9edcd895 1938@kbd{3 ^ 2}
bfa74976
RS
19399
1940@end example
1941
342b8b6e 1942@node Simple Error Recovery
bfa74976
RS
1943@section Simple Error Recovery
1944@cindex error recovery, simple
1945
1946Up to this point, this manual has not addressed the issue of @dfn{error
1947recovery}---how to continue parsing after the parser detects a syntax
ceed8467
AD
1948error. All we have handled is error reporting with @code{yyerror}.
1949Recall that by default @code{yyparse} returns after calling
1950@code{yyerror}. This means that an erroneous input line causes the
1951calculator program to exit. Now we show how to rectify this deficiency.
bfa74976
RS
1952
1953The Bison language itself includes the reserved word @code{error}, which
1954may be included in the grammar rules. In the example below it has
1955been added to one of the alternatives for @code{line}:
1956
1957@example
1958@group
1959line: '\n'
1960 | exp '\n' @{ printf ("\t%.10g\n", $1); @}
1961 | error '\n' @{ yyerrok; @}
1962;
1963@end group
1964@end example
1965
ceed8467 1966This addition to the grammar allows for simple error recovery in the
6e649e65 1967event of a syntax error. If an expression that cannot be evaluated is
ceed8467
AD
1968read, the error will be recognized by the third rule for @code{line},
1969and parsing will continue. (The @code{yyerror} function is still called
1970upon to print its message as well.) The action executes the statement
1971@code{yyerrok}, a macro defined automatically by Bison; its meaning is
1972that error recovery is complete (@pxref{Error Recovery}). Note the
1973difference between @code{yyerrok} and @code{yyerror}; neither one is a
e0c471a9 1974misprint.
bfa74976
RS
1975
1976This form of error recovery deals with syntax errors. There are other
1977kinds of errors; for example, division by zero, which raises an exception
1978signal that is normally fatal. A real calculator program must handle this
1979signal and use @code{longjmp} to return to @code{main} and resume parsing
1980input lines; it would also have to discard the rest of the current line of
1981input. We won't discuss this issue further because it is not specific to
1982Bison programs.
1983
342b8b6e
AD
1984@node Location Tracking Calc
1985@section Location Tracking Calculator: @code{ltcalc}
1986@cindex location tracking calculator
1987@cindex @code{ltcalc}
1988@cindex calculator, location tracking
1989
9edcd895
AD
1990This example extends the infix notation calculator with location
1991tracking. This feature will be used to improve the error messages. For
1992the sake of clarity, this example is a simple integer calculator, since
1993most of the work needed to use locations will be done in the lexical
72d2299c 1994analyzer.
342b8b6e
AD
1995
1996@menu
f56274a8
DJ
1997* Ltcalc Declarations:: Bison and C declarations for ltcalc.
1998* Ltcalc Rules:: Grammar rules for ltcalc, with explanations.
1999* Ltcalc Lexer:: The lexical analyzer.
342b8b6e
AD
2000@end menu
2001
f56274a8 2002@node Ltcalc Declarations
342b8b6e
AD
2003@subsection Declarations for @code{ltcalc}
2004
9edcd895
AD
2005The C and Bison declarations for the location tracking calculator are
2006the same as the declarations for the infix notation calculator.
342b8b6e
AD
2007
2008@example
2009/* Location tracking calculator. */
2010
2011%@{
38a92d50
PE
2012 #define YYSTYPE int
2013 #include <math.h>
2014 int yylex (void);
2015 void yyerror (char const *);
342b8b6e
AD
2016%@}
2017
2018/* Bison declarations. */
2019%token NUM
2020
2021%left '-' '+'
2022%left '*' '/'
2023%left NEG
2024%right '^'
2025
38a92d50 2026%% /* The grammar follows. */
342b8b6e
AD
2027@end example
2028
9edcd895
AD
2029@noindent
2030Note there are no declarations specific to locations. Defining a data
2031type for storing locations is not needed: we will use the type provided
2032by default (@pxref{Location Type, ,Data Types of Locations}), which is a
2033four member structure with the following integer fields:
2034@code{first_line}, @code{first_column}, @code{last_line} and
cd48d21d
AD
2035@code{last_column}. By conventions, and in accordance with the GNU
2036Coding Standards and common practice, the line and column count both
2037start at 1.
342b8b6e
AD
2038
2039@node Ltcalc Rules
2040@subsection Grammar Rules for @code{ltcalc}
2041
9edcd895
AD
2042Whether handling locations or not has no effect on the syntax of your
2043language. Therefore, grammar rules for this example will be very close
2044to those of the previous example: we will only modify them to benefit
2045from the new information.
342b8b6e 2046
9edcd895
AD
2047Here, we will use locations to report divisions by zero, and locate the
2048wrong expressions or subexpressions.
342b8b6e
AD
2049
2050@example
2051@group
2052input : /* empty */
2053 | input line
2054;
2055@end group
2056
2057@group
2058line : '\n'
2059 | exp '\n' @{ printf ("%d\n", $1); @}
2060;
2061@end group
2062
2063@group
2064exp : NUM @{ $$ = $1; @}
2065 | exp '+' exp @{ $$ = $1 + $3; @}
2066 | exp '-' exp @{ $$ = $1 - $3; @}
2067 | exp '*' exp @{ $$ = $1 * $3; @}
2068@end group
342b8b6e 2069@group
9edcd895 2070 | exp '/' exp
342b8b6e
AD
2071 @{
2072 if ($3)
2073 $$ = $1 / $3;
2074 else
2075 @{
2076 $$ = 1;
9edcd895
AD
2077 fprintf (stderr, "%d.%d-%d.%d: division by zero",
2078 @@3.first_line, @@3.first_column,
2079 @@3.last_line, @@3.last_column);
342b8b6e
AD
2080 @}
2081 @}
2082@end group
2083@group
178e123e 2084 | '-' exp %prec NEG @{ $$ = -$2; @}
342b8b6e
AD
2085 | exp '^' exp @{ $$ = pow ($1, $3); @}
2086 | '(' exp ')' @{ $$ = $2; @}
2087@end group
2088@end example
2089
2090This code shows how to reach locations inside of semantic actions, by
2091using the pseudo-variables @code{@@@var{n}} for rule components, and the
2092pseudo-variable @code{@@$} for groupings.
2093
9edcd895
AD
2094We don't need to assign a value to @code{@@$}: the output parser does it
2095automatically. By default, before executing the C code of each action,
2096@code{@@$} is set to range from the beginning of @code{@@1} to the end
2097of @code{@@@var{n}}, for a rule with @var{n} components. This behavior
2098can be redefined (@pxref{Location Default Action, , Default Action for
2099Locations}), and for very specific rules, @code{@@$} can be computed by
2100hand.
342b8b6e
AD
2101
2102@node Ltcalc Lexer
2103@subsection The @code{ltcalc} Lexical Analyzer.
2104
9edcd895 2105Until now, we relied on Bison's defaults to enable location
72d2299c 2106tracking. The next step is to rewrite the lexical analyzer, and make it
9edcd895
AD
2107able to feed the parser with the token locations, as it already does for
2108semantic values.
342b8b6e 2109
9edcd895
AD
2110To this end, we must take into account every single character of the
2111input text, to avoid the computed locations of being fuzzy or wrong:
342b8b6e
AD
2112
2113@example
2114@group
2115int
2116yylex (void)
2117@{
2118 int c;
18b519c0 2119@end group
342b8b6e 2120
18b519c0 2121@group
72d2299c 2122 /* Skip white space. */
342b8b6e
AD
2123 while ((c = getchar ()) == ' ' || c == '\t')
2124 ++yylloc.last_column;
18b519c0 2125@end group
342b8b6e 2126
18b519c0 2127@group
72d2299c 2128 /* Step. */
342b8b6e
AD
2129 yylloc.first_line = yylloc.last_line;
2130 yylloc.first_column = yylloc.last_column;
2131@end group
2132
2133@group
72d2299c 2134 /* Process numbers. */
342b8b6e
AD
2135 if (isdigit (c))
2136 @{
2137 yylval = c - '0';
2138 ++yylloc.last_column;
2139 while (isdigit (c = getchar ()))
2140 @{
2141 ++yylloc.last_column;
2142 yylval = yylval * 10 + c - '0';
2143 @}
2144 ungetc (c, stdin);
2145 return NUM;
2146 @}
2147@end group
2148
72d2299c 2149 /* Return end-of-input. */
342b8b6e
AD
2150 if (c == EOF)
2151 return 0;
2152
72d2299c 2153 /* Return a single char, and update location. */
342b8b6e
AD
2154 if (c == '\n')
2155 @{
2156 ++yylloc.last_line;
2157 yylloc.last_column = 0;
2158 @}
2159 else
2160 ++yylloc.last_column;
2161 return c;
2162@}
2163@end example
2164
9edcd895
AD
2165Basically, the lexical analyzer performs the same processing as before:
2166it skips blanks and tabs, and reads numbers or single-character tokens.
2167In addition, it updates @code{yylloc}, the global variable (of type
2168@code{YYLTYPE}) containing the token's location.
342b8b6e 2169
9edcd895 2170Now, each time this function returns a token, the parser has its number
72d2299c 2171as well as its semantic value, and its location in the text. The last
9edcd895
AD
2172needed change is to initialize @code{yylloc}, for example in the
2173controlling function:
342b8b6e
AD
2174
2175@example
9edcd895 2176@group
342b8b6e
AD
2177int
2178main (void)
2179@{
2180 yylloc.first_line = yylloc.last_line = 1;
2181 yylloc.first_column = yylloc.last_column = 0;
2182 return yyparse ();
2183@}
9edcd895 2184@end group
342b8b6e
AD
2185@end example
2186
9edcd895
AD
2187Remember that computing locations is not a matter of syntax. Every
2188character must be associated to a location update, whether it is in
2189valid input, in comments, in literal strings, and so on.
342b8b6e
AD
2190
2191@node Multi-function Calc
bfa74976
RS
2192@section Multi-Function Calculator: @code{mfcalc}
2193@cindex multi-function calculator
2194@cindex @code{mfcalc}
2195@cindex calculator, multi-function
2196
2197Now that the basics of Bison have been discussed, it is time to move on to
2198a more advanced problem. The above calculators provided only five
2199functions, @samp{+}, @samp{-}, @samp{*}, @samp{/} and @samp{^}. It would
2200be nice to have a calculator that provides other mathematical functions such
2201as @code{sin}, @code{cos}, etc.
2202
2203It is easy to add new operators to the infix calculator as long as they are
2204only single-character literals. The lexical analyzer @code{yylex} passes
9d9b8b70 2205back all nonnumeric characters as tokens, so new grammar rules suffice for
bfa74976
RS
2206adding a new operator. But we want something more flexible: built-in
2207functions whose syntax has this form:
2208
2209@example
2210@var{function_name} (@var{argument})
2211@end example
2212
2213@noindent
2214At the same time, we will add memory to the calculator, by allowing you
2215to create named variables, store values in them, and use them later.
2216Here is a sample session with the multi-function calculator:
2217
2218@example
9edcd895
AD
2219$ @kbd{mfcalc}
2220@kbd{pi = 3.141592653589}
bfa74976 22213.1415926536
9edcd895 2222@kbd{sin(pi)}
bfa74976 22230.0000000000
9edcd895 2224@kbd{alpha = beta1 = 2.3}
bfa74976 22252.3000000000
9edcd895 2226@kbd{alpha}
bfa74976 22272.3000000000
9edcd895 2228@kbd{ln(alpha)}
bfa74976 22290.8329091229
9edcd895 2230@kbd{exp(ln(beta1))}
bfa74976 22312.3000000000
9edcd895 2232$
bfa74976
RS
2233@end example
2234
2235Note that multiple assignment and nested function calls are permitted.
2236
2237@menu
f56274a8
DJ
2238* Mfcalc Declarations:: Bison declarations for multi-function calculator.
2239* Mfcalc Rules:: Grammar rules for the calculator.
2240* Mfcalc Symbol Table:: Symbol table management subroutines.
bfa74976
RS
2241@end menu
2242
f56274a8 2243@node Mfcalc Declarations
bfa74976
RS
2244@subsection Declarations for @code{mfcalc}
2245
2246Here are the C and Bison declarations for the multi-function calculator.
2247
2248@smallexample
18b519c0 2249@group
bfa74976 2250%@{
38a92d50
PE
2251 #include <math.h> /* For math functions, cos(), sin(), etc. */
2252 #include "calc.h" /* Contains definition of `symrec'. */
2253 int yylex (void);
2254 void yyerror (char const *);
bfa74976 2255%@}
18b519c0
AD
2256@end group
2257@group
bfa74976 2258%union @{
38a92d50
PE
2259 double val; /* For returning numbers. */
2260 symrec *tptr; /* For returning symbol-table pointers. */
bfa74976 2261@}
18b519c0 2262@end group
38a92d50
PE
2263%token <val> NUM /* Simple double precision number. */
2264%token <tptr> VAR FNCT /* Variable and Function. */
bfa74976
RS
2265%type <val> exp
2266
18b519c0 2267@group
bfa74976
RS
2268%right '='
2269%left '-' '+'
2270%left '*' '/'
38a92d50
PE
2271%left NEG /* negation--unary minus */
2272%right '^' /* exponentiation */
18b519c0 2273@end group
38a92d50 2274%% /* The grammar follows. */
bfa74976
RS
2275@end smallexample
2276
2277The above grammar introduces only two new features of the Bison language.
2278These features allow semantic values to have various data types
2279(@pxref{Multiple Types, ,More Than One Value Type}).
2280
2281The @code{%union} declaration specifies the entire list of possible types;
2282this is instead of defining @code{YYSTYPE}. The allowable types are now
2283double-floats (for @code{exp} and @code{NUM}) and pointers to entries in
2284the symbol table. @xref{Union Decl, ,The Collection of Value Types}.
2285
2286Since values can now have various types, it is necessary to associate a
2287type with each grammar symbol whose semantic value is used. These symbols
2288are @code{NUM}, @code{VAR}, @code{FNCT}, and @code{exp}. Their
2289declarations are augmented with information about their data type (placed
2290between angle brackets).
2291
704a47c4
AD
2292The Bison construct @code{%type} is used for declaring nonterminal
2293symbols, just as @code{%token} is used for declaring token types. We
2294have not used @code{%type} before because nonterminal symbols are
2295normally declared implicitly by the rules that define them. But
2296@code{exp} must be declared explicitly so we can specify its value type.
2297@xref{Type Decl, ,Nonterminal Symbols}.
bfa74976 2298
342b8b6e 2299@node Mfcalc Rules
bfa74976
RS
2300@subsection Grammar Rules for @code{mfcalc}
2301
2302Here are the grammar rules for the multi-function calculator.
2303Most of them are copied directly from @code{calc}; three rules,
2304those which mention @code{VAR} or @code{FNCT}, are new.
2305
2306@smallexample
18b519c0 2307@group
bfa74976
RS
2308input: /* empty */
2309 | input line
2310;
18b519c0 2311@end group
bfa74976 2312
18b519c0 2313@group
bfa74976
RS
2314line:
2315 '\n'
2316 | exp '\n' @{ printf ("\t%.10g\n", $1); @}
2317 | error '\n' @{ yyerrok; @}
2318;
18b519c0 2319@end group
bfa74976 2320
18b519c0 2321@group
bfa74976
RS
2322exp: NUM @{ $$ = $1; @}
2323 | VAR @{ $$ = $1->value.var; @}
2324 | VAR '=' exp @{ $$ = $3; $1->value.var = $3; @}
2325 | FNCT '(' exp ')' @{ $$ = (*($1->value.fnctptr))($3); @}
2326 | exp '+' exp @{ $$ = $1 + $3; @}
2327 | exp '-' exp @{ $$ = $1 - $3; @}
2328 | exp '*' exp @{ $$ = $1 * $3; @}
2329 | exp '/' exp @{ $$ = $1 / $3; @}
2330 | '-' exp %prec NEG @{ $$ = -$2; @}
2331 | exp '^' exp @{ $$ = pow ($1, $3); @}
2332 | '(' exp ')' @{ $$ = $2; @}
2333;
18b519c0 2334@end group
38a92d50 2335/* End of grammar. */
bfa74976
RS
2336%%
2337@end smallexample
2338
f56274a8 2339@node Mfcalc Symbol Table
bfa74976
RS
2340@subsection The @code{mfcalc} Symbol Table
2341@cindex symbol table example
2342
2343The multi-function calculator requires a symbol table to keep track of the
2344names and meanings of variables and functions. This doesn't affect the
2345grammar rules (except for the actions) or the Bison declarations, but it
2346requires some additional C functions for support.
2347
2348The symbol table itself consists of a linked list of records. Its
2349definition, which is kept in the header @file{calc.h}, is as follows. It
2350provides for either functions or variables to be placed in the table.
2351
2352@smallexample
2353@group
38a92d50 2354/* Function type. */
32dfccf8 2355typedef double (*func_t) (double);
72f889cc 2356@end group
32dfccf8 2357
72f889cc 2358@group
38a92d50 2359/* Data type for links in the chain of symbols. */
bfa74976
RS
2360struct symrec
2361@{
38a92d50 2362 char *name; /* name of symbol */
bfa74976 2363 int type; /* type of symbol: either VAR or FNCT */
32dfccf8
AD
2364 union
2365 @{
38a92d50
PE
2366 double var; /* value of a VAR */
2367 func_t fnctptr; /* value of a FNCT */
bfa74976 2368 @} value;
38a92d50 2369 struct symrec *next; /* link field */
bfa74976
RS
2370@};
2371@end group
2372
2373@group
2374typedef struct symrec symrec;
2375
38a92d50 2376/* The symbol table: a chain of `struct symrec'. */
bfa74976
RS
2377extern symrec *sym_table;
2378
a730d142 2379symrec *putsym (char const *, int);
38a92d50 2380symrec *getsym (char const *);
bfa74976
RS
2381@end group
2382@end smallexample
2383
2384The new version of @code{main} includes a call to @code{init_table}, a
2385function that initializes the symbol table. Here it is, and
2386@code{init_table} as well:
2387
2388@smallexample
bfa74976
RS
2389#include <stdio.h>
2390
18b519c0 2391@group
38a92d50 2392/* Called by yyparse on error. */
13863333 2393void
38a92d50 2394yyerror (char const *s)
bfa74976
RS
2395@{
2396 printf ("%s\n", s);
2397@}
18b519c0 2398@end group
bfa74976 2399
18b519c0 2400@group
bfa74976
RS
2401struct init
2402@{
38a92d50
PE
2403 char const *fname;
2404 double (*fnct) (double);
bfa74976
RS
2405@};
2406@end group
2407
2408@group
38a92d50 2409struct init const arith_fncts[] =
13863333 2410@{
32dfccf8
AD
2411 "sin", sin,
2412 "cos", cos,
13863333 2413 "atan", atan,
32dfccf8
AD
2414 "ln", log,
2415 "exp", exp,
13863333
AD
2416 "sqrt", sqrt,
2417 0, 0
2418@};
18b519c0 2419@end group
bfa74976 2420
18b519c0 2421@group
bfa74976 2422/* The symbol table: a chain of `struct symrec'. */
38a92d50 2423symrec *sym_table;
bfa74976
RS
2424@end group
2425
2426@group
72d2299c 2427/* Put arithmetic functions in table. */
13863333
AD
2428void
2429init_table (void)
bfa74976
RS
2430@{
2431 int i;
2432 symrec *ptr;
2433 for (i = 0; arith_fncts[i].fname != 0; i++)
2434 @{
2435 ptr = putsym (arith_fncts[i].fname, FNCT);
2436 ptr->value.fnctptr = arith_fncts[i].fnct;
2437 @}
2438@}
2439@end group
38a92d50
PE
2440
2441@group
2442int
2443main (void)
2444@{
2445 init_table ();
2446 return yyparse ();
2447@}
2448@end group
bfa74976
RS
2449@end smallexample
2450
2451By simply editing the initialization list and adding the necessary include
2452files, you can add additional functions to the calculator.
2453
2454Two important functions allow look-up and installation of symbols in the
2455symbol table. The function @code{putsym} is passed a name and the type
2456(@code{VAR} or @code{FNCT}) of the object to be installed. The object is
2457linked to the front of the list, and a pointer to the object is returned.
2458The function @code{getsym} is passed the name of the symbol to look up. If
2459found, a pointer to that symbol is returned; otherwise zero is returned.
2460
2461@smallexample
2462symrec *
38a92d50 2463putsym (char const *sym_name, int sym_type)
bfa74976
RS
2464@{
2465 symrec *ptr;
2466 ptr = (symrec *) malloc (sizeof (symrec));
2467 ptr->name = (char *) malloc (strlen (sym_name) + 1);
2468 strcpy (ptr->name,sym_name);
2469 ptr->type = sym_type;
72d2299c 2470 ptr->value.var = 0; /* Set value to 0 even if fctn. */
bfa74976
RS
2471 ptr->next = (struct symrec *)sym_table;
2472 sym_table = ptr;
2473 return ptr;
2474@}
2475
2476symrec *
38a92d50 2477getsym (char const *sym_name)
bfa74976
RS
2478@{
2479 symrec *ptr;
2480 for (ptr = sym_table; ptr != (symrec *) 0;
2481 ptr = (symrec *)ptr->next)
2482 if (strcmp (ptr->name,sym_name) == 0)
2483 return ptr;
2484 return 0;
2485@}
2486@end smallexample
2487
2488The function @code{yylex} must now recognize variables, numeric values, and
2489the single-character arithmetic operators. Strings of alphanumeric
9d9b8b70 2490characters with a leading letter are recognized as either variables or
bfa74976
RS
2491functions depending on what the symbol table says about them.
2492
2493The string is passed to @code{getsym} for look up in the symbol table. If
2494the name appears in the table, a pointer to its location and its type
2495(@code{VAR} or @code{FNCT}) is returned to @code{yyparse}. If it is not
2496already in the table, then it is installed as a @code{VAR} using
2497@code{putsym}. Again, a pointer and its type (which must be @code{VAR}) is
e0c471a9 2498returned to @code{yyparse}.
bfa74976
RS
2499
2500No change is needed in the handling of numeric values and arithmetic
2501operators in @code{yylex}.
2502
2503@smallexample
2504@group
2505#include <ctype.h>
18b519c0 2506@end group
13863333 2507
18b519c0 2508@group
13863333
AD
2509int
2510yylex (void)
bfa74976
RS
2511@{
2512 int c;
2513
72d2299c 2514 /* Ignore white space, get first nonwhite character. */
bfa74976
RS
2515 while ((c = getchar ()) == ' ' || c == '\t');
2516
2517 if (c == EOF)
2518 return 0;
2519@end group
2520
2521@group
2522 /* Char starts a number => parse the number. */
2523 if (c == '.' || isdigit (c))
2524 @{
2525 ungetc (c, stdin);
2526 scanf ("%lf", &yylval.val);
2527 return NUM;
2528 @}
2529@end group
2530
2531@group
2532 /* Char starts an identifier => read the name. */
2533 if (isalpha (c))
2534 @{
2535 symrec *s;
2536 static char *symbuf = 0;
2537 static int length = 0;
2538 int i;
2539@end group
2540
2541@group
2542 /* Initially make the buffer long enough
2543 for a 40-character symbol name. */
2544 if (length == 0)
2545 length = 40, symbuf = (char *)malloc (length + 1);
2546
2547 i = 0;
2548 do
2549@end group
2550@group
2551 @{
2552 /* If buffer is full, make it bigger. */
2553 if (i == length)
2554 @{
2555 length *= 2;
18b519c0 2556 symbuf = (char *) realloc (symbuf, length + 1);
bfa74976
RS
2557 @}
2558 /* Add this character to the buffer. */
2559 symbuf[i++] = c;
2560 /* Get another character. */
2561 c = getchar ();
2562 @}
2563@end group
2564@group
72d2299c 2565 while (isalnum (c));
bfa74976
RS
2566
2567 ungetc (c, stdin);
2568 symbuf[i] = '\0';
2569@end group
2570
2571@group
2572 s = getsym (symbuf);
2573 if (s == 0)
2574 s = putsym (symbuf, VAR);
2575 yylval.tptr = s;
2576 return s->type;
2577 @}
2578
2579 /* Any other character is a token by itself. */
2580 return c;
2581@}
2582@end group
2583@end smallexample
2584
72d2299c 2585This program is both powerful and flexible. You may easily add new
704a47c4
AD
2586functions, and it is a simple job to modify this code to install
2587predefined variables such as @code{pi} or @code{e} as well.
bfa74976 2588
342b8b6e 2589@node Exercises
bfa74976
RS
2590@section Exercises
2591@cindex exercises
2592
2593@enumerate
2594@item
2595Add some new functions from @file{math.h} to the initialization list.
2596
2597@item
2598Add another array that contains constants and their values. Then
2599modify @code{init_table} to add these constants to the symbol table.
2600It will be easiest to give the constants type @code{VAR}.
2601
2602@item
2603Make the program report an error if the user refers to an
2604uninitialized variable in any way except to store a value in it.
2605@end enumerate
2606
342b8b6e 2607@node Grammar File
bfa74976
RS
2608@chapter Bison Grammar Files
2609
2610Bison takes as input a context-free grammar specification and produces a
2611C-language function that recognizes correct instances of the grammar.
2612
9913d6e4 2613The Bison grammar file conventionally has a name ending in @samp{.y}.
234a3be3 2614@xref{Invocation, ,Invoking Bison}.
bfa74976
RS
2615
2616@menu
2617* Grammar Outline:: Overall layout of the grammar file.
2618* Symbols:: Terminal and nonterminal symbols.
2619* Rules:: How to write grammar rules.
2620* Recursion:: Writing recursive rules.
2621* Semantics:: Semantic values and actions.
847bf1f5 2622* Locations:: Locations and actions.
bfa74976
RS
2623* Declarations:: All kinds of Bison declarations are described here.
2624* Multiple Parsers:: Putting more than one Bison parser in one program.
2625@end menu
2626
342b8b6e 2627@node Grammar Outline
bfa74976
RS
2628@section Outline of a Bison Grammar
2629
2630A Bison grammar file has four main sections, shown here with the
2631appropriate delimiters:
2632
2633@example
2634%@{
38a92d50 2635 @var{Prologue}
bfa74976
RS
2636%@}
2637
2638@var{Bison declarations}
2639
2640%%
2641@var{Grammar rules}
2642%%
2643
75f5aaea 2644@var{Epilogue}
bfa74976
RS
2645@end example
2646
2647Comments enclosed in @samp{/* @dots{} */} may appear in any of the sections.
35430378 2648As a GNU extension, @samp{//} introduces a comment that
2bfc2e2a 2649continues until end of line.
bfa74976
RS
2650
2651@menu
f56274a8 2652* Prologue:: Syntax and usage of the prologue.
2cbe6b7f 2653* Prologue Alternatives:: Syntax and usage of alternatives to the prologue.
f56274a8
DJ
2654* Bison Declarations:: Syntax and usage of the Bison declarations section.
2655* Grammar Rules:: Syntax and usage of the grammar rules section.
2656* Epilogue:: Syntax and usage of the epilogue.
bfa74976
RS
2657@end menu
2658
38a92d50 2659@node Prologue
75f5aaea
MA
2660@subsection The prologue
2661@cindex declarations section
2662@cindex Prologue
2663@cindex declarations
bfa74976 2664
f8e1c9e5
AD
2665The @var{Prologue} section contains macro definitions and declarations
2666of functions and variables that are used in the actions in the grammar
9913d6e4
JD
2667rules. These are copied to the beginning of the parser implementation
2668file so that they precede the definition of @code{yyparse}. You can
2669use @samp{#include} to get the declarations from a header file. If
2670you don't need any C declarations, you may omit the @samp{%@{} and
f8e1c9e5 2671@samp{%@}} delimiters that bracket this section.
bfa74976 2672
9c437126 2673The @var{Prologue} section is terminated by the first occurrence
287c78f6
PE
2674of @samp{%@}} that is outside a comment, a string literal, or a
2675character constant.
2676
c732d2c6
AD
2677You may have more than one @var{Prologue} section, intermixed with the
2678@var{Bison declarations}. This allows you to have C and Bison
2679declarations that refer to each other. For example, the @code{%union}
2680declaration may use types defined in a header file, and you may wish to
2681prototype functions that take arguments of type @code{YYSTYPE}. This
2682can be done with two @var{Prologue} blocks, one before and one after the
2683@code{%union} declaration.
2684
2685@smallexample
2686%@{
aef3da86 2687 #define _GNU_SOURCE
38a92d50
PE
2688 #include <stdio.h>
2689 #include "ptypes.h"
c732d2c6
AD
2690%@}
2691
2692%union @{
779e7ceb 2693 long int n;
c732d2c6
AD
2694 tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */
2695@}
2696
2697%@{
38a92d50
PE
2698 static void print_token_value (FILE *, int, YYSTYPE);
2699 #define YYPRINT(F, N, L) print_token_value (F, N, L)
c732d2c6
AD
2700%@}
2701
2702@dots{}
2703@end smallexample
2704
aef3da86
PE
2705When in doubt, it is usually safer to put prologue code before all
2706Bison declarations, rather than after. For example, any definitions
2707of feature test macros like @code{_GNU_SOURCE} or
2708@code{_POSIX_C_SOURCE} should appear before all Bison declarations, as
2709feature test macros can affect the behavior of Bison-generated
2710@code{#include} directives.
2711
2cbe6b7f
JD
2712@node Prologue Alternatives
2713@subsection Prologue Alternatives
2714@cindex Prologue Alternatives
2715
136a0f76 2716@findex %code
16dc6a9e
JD
2717@findex %code requires
2718@findex %code provides
2719@findex %code top
85894313 2720
2cbe6b7f 2721The functionality of @var{Prologue} sections can often be subtle and
9913d6e4
JD
2722inflexible. As an alternative, Bison provides a @code{%code}
2723directive with an explicit qualifier field, which identifies the
2724purpose of the code and thus the location(s) where Bison should
2725generate it. For C/C++, the qualifier can be omitted for the default
2726location, or it can be one of @code{requires}, @code{provides},
8e6f2266 2727@code{top}. @xref{%code Summary}.
2cbe6b7f
JD
2728
2729Look again at the example of the previous section:
2730
2731@smallexample
2732%@{
2733 #define _GNU_SOURCE
2734 #include <stdio.h>
2735 #include "ptypes.h"
2736%@}
2737
2738%union @{
2739 long int n;
2740 tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */
2741@}
2742
2743%@{
2744 static void print_token_value (FILE *, int, YYSTYPE);
2745 #define YYPRINT(F, N, L) print_token_value (F, N, L)
2746%@}
2747
2748@dots{}
2749@end smallexample
2750
2751@noindent
9913d6e4
JD
2752Notice that there are two @var{Prologue} sections here, but there's a
2753subtle distinction between their functionality. For example, if you
2754decide to override Bison's default definition for @code{YYLTYPE}, in
2755which @var{Prologue} section should you write your new definition?
2756You should write it in the first since Bison will insert that code
2757into the parser implementation file @emph{before} the default
2758@code{YYLTYPE} definition. In which @var{Prologue} section should you
2759prototype an internal function, @code{trace_token}, that accepts
2760@code{YYLTYPE} and @code{yytokentype} as arguments? You should
2761prototype it in the second since Bison will insert that code
2cbe6b7f
JD
2762@emph{after} the @code{YYLTYPE} and @code{yytokentype} definitions.
2763
2764This distinction in functionality between the two @var{Prologue} sections is
2765established by the appearance of the @code{%union} between them.
a501eca9 2766This behavior raises a few questions.
2cbe6b7f
JD
2767First, why should the position of a @code{%union} affect definitions related to
2768@code{YYLTYPE} and @code{yytokentype}?
2769Second, what if there is no @code{%union}?
2770In that case, the second kind of @var{Prologue} section is not available.
2771This behavior is not intuitive.
2772
8e0a5e9e 2773To avoid this subtle @code{%union} dependency, rewrite the example using a
16dc6a9e 2774@code{%code top} and an unqualified @code{%code}.
2cbe6b7f
JD
2775Let's go ahead and add the new @code{YYLTYPE} definition and the
2776@code{trace_token} prototype at the same time:
2777
2778@smallexample
16dc6a9e 2779%code top @{
2cbe6b7f
JD
2780 #define _GNU_SOURCE
2781 #include <stdio.h>
8e0a5e9e
JD
2782
2783 /* WARNING: The following code really belongs
16dc6a9e 2784 * in a `%code requires'; see below. */
8e0a5e9e 2785
2cbe6b7f
JD
2786 #include "ptypes.h"
2787 #define YYLTYPE YYLTYPE
2788 typedef struct YYLTYPE
2789 @{
2790 int first_line;
2791 int first_column;
2792 int last_line;
2793 int last_column;
2794 char *filename;
2795 @} YYLTYPE;
2796@}
2797
2798%union @{
2799 long int n;
2800 tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */
2801@}
2802
2803%code @{
2804 static void print_token_value (FILE *, int, YYSTYPE);
2805 #define YYPRINT(F, N, L) print_token_value (F, N, L)
2806 static void trace_token (enum yytokentype token, YYLTYPE loc);
2807@}
2808
2809@dots{}
2810@end smallexample
2811
2812@noindent
16dc6a9e
JD
2813In this way, @code{%code top} and the unqualified @code{%code} achieve the same
2814functionality as the two kinds of @var{Prologue} sections, but it's always
8e0a5e9e 2815explicit which kind you intend.
2cbe6b7f
JD
2816Moreover, both kinds are always available even in the absence of @code{%union}.
2817
9913d6e4
JD
2818The @code{%code top} block above logically contains two parts. The
2819first two lines before the warning need to appear near the top of the
2820parser implementation file. The first line after the warning is
2821required by @code{YYSTYPE} and thus also needs to appear in the parser
2822implementation file. However, if you've instructed Bison to generate
2823a parser header file (@pxref{Decl Summary, ,%defines}), you probably
2824want that line to appear before the @code{YYSTYPE} definition in that
2825header file as well. The @code{YYLTYPE} definition should also appear
2826in the parser header file to override the default @code{YYLTYPE}
2827definition there.
2cbe6b7f 2828
16dc6a9e 2829In other words, in the @code{%code top} block above, all but the first two
8e0a5e9e
JD
2830lines are dependency code required by the @code{YYSTYPE} and @code{YYLTYPE}
2831definitions.
16dc6a9e 2832Thus, they belong in one or more @code{%code requires}:
9bc0dd67
JD
2833
2834@smallexample
16dc6a9e 2835%code top @{
2cbe6b7f
JD
2836 #define _GNU_SOURCE
2837 #include <stdio.h>
2838@}
2839
16dc6a9e 2840%code requires @{
9bc0dd67
JD
2841 #include "ptypes.h"
2842@}
2843%union @{
2844 long int n;
2845 tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */
2846@}
2847
16dc6a9e 2848%code requires @{
2cbe6b7f
JD
2849 #define YYLTYPE YYLTYPE
2850 typedef struct YYLTYPE
2851 @{
2852 int first_line;
2853 int first_column;
2854 int last_line;
2855 int last_column;
2856 char *filename;
2857 @} YYLTYPE;
2858@}
2859
136a0f76 2860%code @{
2cbe6b7f
JD
2861 static void print_token_value (FILE *, int, YYSTYPE);
2862 #define YYPRINT(F, N, L) print_token_value (F, N, L)
2863 static void trace_token (enum yytokentype token, YYLTYPE loc);
2864@}
2865
2866@dots{}
2867@end smallexample
2868
2869@noindent
9913d6e4
JD
2870Now Bison will insert @code{#include "ptypes.h"} and the new
2871@code{YYLTYPE} definition before the Bison-generated @code{YYSTYPE}
2872and @code{YYLTYPE} definitions in both the parser implementation file
2873and the parser header file. (By the same reasoning, @code{%code
2874requires} would also be the appropriate place to write your own
2875definition for @code{YYSTYPE}.)
2876
2877When you are writing dependency code for @code{YYSTYPE} and
2878@code{YYLTYPE}, you should prefer @code{%code requires} over
2879@code{%code top} regardless of whether you instruct Bison to generate
2880a parser header file. When you are writing code that you need Bison
2881to insert only into the parser implementation file and that has no
2882special need to appear at the top of that file, you should prefer the
2883unqualified @code{%code} over @code{%code top}. These practices will
2884make the purpose of each block of your code explicit to Bison and to
2885other developers reading your grammar file. Following these
2886practices, we expect the unqualified @code{%code} and @code{%code
2887requires} to be the most important of the four @var{Prologue}
16dc6a9e 2888alternatives.
a501eca9 2889
9913d6e4
JD
2890At some point while developing your parser, you might decide to
2891provide @code{trace_token} to modules that are external to your
2892parser. Thus, you might wish for Bison to insert the prototype into
2893both the parser header file and the parser implementation file. Since
2894this function is not a dependency required by @code{YYSTYPE} or
8e0a5e9e 2895@code{YYLTYPE}, it doesn't make sense to move its prototype to a
9913d6e4
JD
2896@code{%code requires}. More importantly, since it depends upon
2897@code{YYLTYPE} and @code{yytokentype}, @code{%code requires} is not
2898sufficient. Instead, move its prototype from the unqualified
2899@code{%code} to a @code{%code provides}:
2cbe6b7f
JD
2900
2901@smallexample
16dc6a9e 2902%code top @{
2cbe6b7f 2903 #define _GNU_SOURCE
136a0f76 2904 #include <stdio.h>
2cbe6b7f 2905@}
136a0f76 2906
16dc6a9e 2907%code requires @{
2cbe6b7f
JD
2908 #include "ptypes.h"
2909@}
2910%union @{
2911 long int n;
2912 tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */
2913@}
2914
16dc6a9e 2915%code requires @{
2cbe6b7f
JD
2916 #define YYLTYPE YYLTYPE
2917 typedef struct YYLTYPE
2918 @{
2919 int first_line;
2920 int first_column;
2921 int last_line;
2922 int last_column;
2923 char *filename;
2924 @} YYLTYPE;
2925@}
2926
16dc6a9e 2927%code provides @{
2cbe6b7f
JD
2928 void trace_token (enum yytokentype token, YYLTYPE loc);
2929@}
2930
2931%code @{
9bc0dd67
JD
2932 static void print_token_value (FILE *, int, YYSTYPE);
2933 #define YYPRINT(F, N, L) print_token_value (F, N, L)
34f98f46 2934@}
9bc0dd67
JD
2935
2936@dots{}
2937@end smallexample
2938
2cbe6b7f 2939@noindent
9913d6e4
JD
2940Bison will insert the @code{trace_token} prototype into both the
2941parser header file and the parser implementation file after the
2942definitions for @code{yytokentype}, @code{YYLTYPE}, and
2943@code{YYSTYPE}.
2944
2945The above examples are careful to write directives in an order that
2946reflects the layout of the generated parser implementation and header
2947files: @code{%code top}, @code{%code requires}, @code{%code provides},
2948and then @code{%code}. While your grammar files may generally be
2949easier to read if you also follow this order, Bison does not require
2950it. Instead, Bison lets you choose an organization that makes sense
2951to you.
2cbe6b7f 2952
a501eca9 2953You may declare any of these directives multiple times in the grammar file.
2cbe6b7f
JD
2954In that case, Bison concatenates the contained code in declaration order.
2955This is the only way in which the position of one of these directives within
2956the grammar file affects its functionality.
2957
2958The result of the previous two properties is greater flexibility in how you may
2959organize your grammar file.
2960For example, you may organize semantic-type-related directives by semantic
2961type:
2962
2963@smallexample
16dc6a9e 2964%code requires @{ #include "type1.h" @}
2cbe6b7f
JD
2965%union @{ type1 field1; @}
2966%destructor @{ type1_free ($$); @} <field1>
2967%printer @{ type1_print ($$); @} <field1>
2968
16dc6a9e 2969%code requires @{ #include "type2.h" @}
2cbe6b7f
JD
2970%union @{ type2 field2; @}
2971%destructor @{ type2_free ($$); @} <field2>
2972%printer @{ type2_print ($$); @} <field2>
2973@end smallexample
2974
2975@noindent
2976You could even place each of the above directive groups in the rules section of
2977the grammar file next to the set of rules that uses the associated semantic
2978type.
61fee93e
JD
2979(In the rules section, you must terminate each of those directives with a
2980semicolon.)
2cbe6b7f
JD
2981And you don't have to worry that some directive (like a @code{%union}) in the
2982definitions section is going to adversely affect their functionality in some
2983counter-intuitive manner just because it comes first.
2984Such an organization is not possible using @var{Prologue} sections.
2985
a501eca9 2986This section has been concerned with explaining the advantages of the four
8e0a5e9e 2987@var{Prologue} alternatives over the original Yacc @var{Prologue}.
a501eca9
JD
2988However, in most cases when using these directives, you shouldn't need to
2989think about all the low-level ordering issues discussed here.
2990Instead, you should simply use these directives to label each block of your
2991code according to its purpose and let Bison handle the ordering.
2992@code{%code} is the most generic label.
16dc6a9e
JD
2993Move code to @code{%code requires}, @code{%code provides}, or @code{%code top}
2994as needed.
a501eca9 2995
342b8b6e 2996@node Bison Declarations
bfa74976
RS
2997@subsection The Bison Declarations Section
2998@cindex Bison declarations (introduction)
2999@cindex declarations, Bison (introduction)
3000
3001The @var{Bison declarations} section contains declarations that define
3002terminal and nonterminal symbols, specify precedence, and so on.
3003In some simple grammars you may not need any declarations.
3004@xref{Declarations, ,Bison Declarations}.
3005
342b8b6e 3006@node Grammar Rules
bfa74976
RS
3007@subsection The Grammar Rules Section
3008@cindex grammar rules section
3009@cindex rules section for grammar
3010
3011The @dfn{grammar rules} section contains one or more Bison grammar
3012rules, and nothing else. @xref{Rules, ,Syntax of Grammar Rules}.
3013
3014There must always be at least one grammar rule, and the first
3015@samp{%%} (which precedes the grammar rules) may never be omitted even
3016if it is the first thing in the file.
3017
38a92d50 3018@node Epilogue
75f5aaea 3019@subsection The epilogue
bfa74976 3020@cindex additional C code section
75f5aaea 3021@cindex epilogue
bfa74976
RS
3022@cindex C code, section for additional
3023
9913d6e4
JD
3024The @var{Epilogue} is copied verbatim to the end of the parser
3025implementation file, just as the @var{Prologue} is copied to the
3026beginning. This is the most convenient place to put anything that you
3027want to have in the parser implementation file but which need not come
3028before the definition of @code{yyparse}. For example, the definitions
3029of @code{yylex} and @code{yyerror} often go here. Because C requires
3030functions to be declared before being used, you often need to declare
3031functions like @code{yylex} and @code{yyerror} in the Prologue, even
3032if you define them in the Epilogue. @xref{Interface, ,Parser
3033C-Language Interface}.
bfa74976
RS
3034
3035If the last section is empty, you may omit the @samp{%%} that separates it
3036from the grammar rules.
3037
f8e1c9e5
AD
3038The Bison parser itself contains many macros and identifiers whose names
3039start with @samp{yy} or @samp{YY}, so it is a good idea to avoid using
3040any such names (except those documented in this manual) in the epilogue
3041of the grammar file.
bfa74976 3042
342b8b6e 3043@node Symbols
bfa74976
RS
3044@section Symbols, Terminal and Nonterminal
3045@cindex nonterminal symbol
3046@cindex terminal symbol
3047@cindex token type
3048@cindex symbol
3049
3050@dfn{Symbols} in Bison grammars represent the grammatical classifications
3051of the language.
3052
3053A @dfn{terminal symbol} (also known as a @dfn{token type}) represents a
3054class of syntactically equivalent tokens. You use the symbol in grammar
3055rules to mean that a token in that class is allowed. The symbol is
3056represented in the Bison parser by a numeric code, and the @code{yylex}
f8e1c9e5
AD
3057function returns a token type code to indicate what kind of token has
3058been read. You don't need to know what the code value is; you can use
3059the symbol to stand for it.
bfa74976 3060
f8e1c9e5
AD
3061A @dfn{nonterminal symbol} stands for a class of syntactically
3062equivalent groupings. The symbol name is used in writing grammar rules.
3063By convention, it should be all lower case.
bfa74976 3064
eb8c66bb
JD
3065Symbol names can contain letters, underscores, periods, and non-initial
3066digits and dashes. Dashes in symbol names are a GNU extension, incompatible
3067with POSIX Yacc. Periods and dashes make symbol names less convenient to
3068use with named references, which require brackets around such names
3069(@pxref{Named References}). Terminal symbols that contain periods or dashes
3070make little sense: since they are not valid symbols (in most programming
3071languages) they are not exported as token names.
bfa74976 3072
931c7513 3073There are three ways of writing terminal symbols in the grammar:
bfa74976
RS
3074
3075@itemize @bullet
3076@item
3077A @dfn{named token type} is written with an identifier, like an
c827f760 3078identifier in C@. By convention, it should be all upper case. Each
bfa74976
RS
3079such name must be defined with a Bison declaration such as
3080@code{%token}. @xref{Token Decl, ,Token Type Names}.
3081
3082@item
3083@cindex character token
3084@cindex literal token
3085@cindex single-character literal
931c7513
RS
3086A @dfn{character token type} (or @dfn{literal character token}) is
3087written in the grammar using the same syntax used in C for character
3088constants; for example, @code{'+'} is a character token type. A
3089character token type doesn't need to be declared unless you need to
3090specify its semantic value data type (@pxref{Value Type, ,Data Types of
3091Semantic Values}), associativity, or precedence (@pxref{Precedence,
3092,Operator Precedence}).
bfa74976
RS
3093
3094By convention, a character token type is used only to represent a
3095token that consists of that particular character. Thus, the token
3096type @code{'+'} is used to represent the character @samp{+} as a
3097token. Nothing enforces this convention, but if you depart from it,
3098your program will confuse other readers.
3099
3100All the usual escape sequences used in character literals in C can be
3101used in Bison as well, but you must not use the null character as a
72d2299c
PE
3102character literal because its numeric code, zero, signifies
3103end-of-input (@pxref{Calling Convention, ,Calling Convention
2bfc2e2a
PE
3104for @code{yylex}}). Also, unlike standard C, trigraphs have no
3105special meaning in Bison character literals, nor is backslash-newline
3106allowed.
931c7513
RS
3107
3108@item
3109@cindex string token
3110@cindex literal string token
9ecbd125 3111@cindex multicharacter literal
931c7513
RS
3112A @dfn{literal string token} is written like a C string constant; for
3113example, @code{"<="} is a literal string token. A literal string token
3114doesn't need to be declared unless you need to specify its semantic
14ded682 3115value data type (@pxref{Value Type}), associativity, or precedence
931c7513
RS
3116(@pxref{Precedence}).
3117
3118You can associate the literal string token with a symbolic name as an
3119alias, using the @code{%token} declaration (@pxref{Token Decl, ,Token
3120Declarations}). If you don't do that, the lexical analyzer has to
3121retrieve the token number for the literal string token from the
3122@code{yytname} table (@pxref{Calling Convention}).
3123
c827f760 3124@strong{Warning}: literal string tokens do not work in Yacc.
931c7513
RS
3125
3126By convention, a literal string token is used only to represent a token
3127that consists of that particular string. Thus, you should use the token
3128type @code{"<="} to represent the string @samp{<=} as a token. Bison
9ecbd125 3129does not enforce this convention, but if you depart from it, people who
931c7513
RS
3130read your program will be confused.
3131
3132All the escape sequences used in string literals in C can be used in
92ac3705
PE
3133Bison as well, except that you must not use a null character within a
3134string literal. Also, unlike Standard C, trigraphs have no special
2bfc2e2a
PE
3135meaning in Bison string literals, nor is backslash-newline allowed. A
3136literal string token must contain two or more characters; for a token
3137containing just one character, use a character token (see above).
bfa74976
RS
3138@end itemize
3139
3140How you choose to write a terminal symbol has no effect on its
3141grammatical meaning. That depends only on where it appears in rules and
3142on when the parser function returns that symbol.
3143
72d2299c
PE
3144The value returned by @code{yylex} is always one of the terminal
3145symbols, except that a zero or negative value signifies end-of-input.
3146Whichever way you write the token type in the grammar rules, you write
3147it the same way in the definition of @code{yylex}. The numeric code
3148for a character token type is simply the positive numeric code of the
3149character, so @code{yylex} can use the identical value to generate the
3150requisite code, though you may need to convert it to @code{unsigned
3151char} to avoid sign-extension on hosts where @code{char} is signed.
9913d6e4
JD
3152Each named token type becomes a C macro in the parser implementation
3153file, so @code{yylex} can use the name to stand for the code. (This
3154is why periods don't make sense in terminal symbols.) @xref{Calling
3155Convention, ,Calling Convention for @code{yylex}}.
bfa74976
RS
3156
3157If @code{yylex} is defined in a separate file, you need to arrange for the
3158token-type macro definitions to be available there. Use the @samp{-d}
3159option when you run Bison, so that it will write these macro definitions
3160into a separate header file @file{@var{name}.tab.h} which you can include
3161in the other source files that need it. @xref{Invocation, ,Invoking Bison}.
3162
72d2299c 3163If you want to write a grammar that is portable to any Standard C
9d9b8b70 3164host, you must use only nonnull character tokens taken from the basic
c827f760 3165execution character set of Standard C@. This set consists of the ten
72d2299c
PE
3166digits, the 52 lower- and upper-case English letters, and the
3167characters in the following C-language string:
3168
3169@example
3170"\a\b\t\n\v\f\r !\"#%&'()*+,-./:;<=>?[\\]^_@{|@}~"
3171@end example
3172
f8e1c9e5
AD
3173The @code{yylex} function and Bison must use a consistent character set
3174and encoding for character tokens. For example, if you run Bison in an
35430378 3175ASCII environment, but then compile and run the resulting
f8e1c9e5 3176program in an environment that uses an incompatible character set like
35430378
JD
3177EBCDIC, the resulting program may not work because the tables
3178generated by Bison will assume ASCII numeric values for
f8e1c9e5
AD
3179character tokens. It is standard practice for software distributions to
3180contain C source files that were generated by Bison in an
35430378
JD
3181ASCII environment, so installers on platforms that are
3182incompatible with ASCII must rebuild those files before
f8e1c9e5 3183compiling them.
e966383b 3184
bfa74976
RS
3185The symbol @code{error} is a terminal symbol reserved for error recovery
3186(@pxref{Error Recovery}); you shouldn't use it for any other purpose.
23c5a174
AD
3187In particular, @code{yylex} should never return this value. The default
3188value of the error token is 256, unless you explicitly assigned 256 to
3189one of your tokens with a @code{%token} declaration.
bfa74976 3190
342b8b6e 3191@node Rules
bfa74976
RS
3192@section Syntax of Grammar Rules
3193@cindex rule syntax
3194@cindex grammar rule syntax
3195@cindex syntax of grammar rules
3196
3197A Bison grammar rule has the following general form:
3198
3199@example
e425e872 3200@group
bfa74976
RS
3201@var{result}: @var{components}@dots{}
3202 ;
e425e872 3203@end group
bfa74976
RS
3204@end example
3205
3206@noindent
9ecbd125 3207where @var{result} is the nonterminal symbol that this rule describes,
bfa74976 3208and @var{components} are various terminal and nonterminal symbols that
13863333 3209are put together by this rule (@pxref{Symbols}).
bfa74976
RS
3210
3211For example,
3212
3213@example
3214@group
3215exp: exp '+' exp
3216 ;
3217@end group
3218@end example
3219
3220@noindent
3221says that two groupings of type @code{exp}, with a @samp{+} token in between,
3222can be combined into a larger grouping of type @code{exp}.
3223
72d2299c
PE
3224White space in rules is significant only to separate symbols. You can add
3225extra white space as you wish.
bfa74976
RS
3226
3227Scattered among the components can be @var{actions} that determine
3228the semantics of the rule. An action looks like this:
3229
3230@example
3231@{@var{C statements}@}
3232@end example
3233
3234@noindent
287c78f6
PE
3235@cindex braced code
3236This is an example of @dfn{braced code}, that is, C code surrounded by
3237braces, much like a compound statement in C@. Braced code can contain
3238any sequence of C tokens, so long as its braces are balanced. Bison
3239does not check the braced code for correctness directly; it merely
9913d6e4
JD
3240copies the code to the parser implementation file, where the C
3241compiler can check it.
287c78f6
PE
3242
3243Within braced code, the balanced-brace count is not affected by braces
3244within comments, string literals, or character constants, but it is
3245affected by the C digraphs @samp{<%} and @samp{%>} that represent
3246braces. At the top level braced code must be terminated by @samp{@}}
3247and not by a digraph. Bison does not look for trigraphs, so if braced
3248code uses trigraphs you should ensure that they do not affect the
3249nesting of braces or the boundaries of comments, string literals, or
3250character constants.
3251
bfa74976
RS
3252Usually there is only one action and it follows the components.
3253@xref{Actions}.
3254
3255@findex |
3256Multiple rules for the same @var{result} can be written separately or can
3257be joined with the vertical-bar character @samp{|} as follows:
3258
bfa74976
RS
3259@example
3260@group
3261@var{result}: @var{rule1-components}@dots{}
3262 | @var{rule2-components}@dots{}
3263 @dots{}
3264 ;
3265@end group
3266@end example
bfa74976
RS
3267
3268@noindent
3269They are still considered distinct rules even when joined in this way.
3270
3271If @var{components} in a rule is empty, it means that @var{result} can
3272match the empty string. For example, here is how to define a
3273comma-separated sequence of zero or more @code{exp} groupings:
3274
3275@example
3276@group
3277expseq: /* empty */
3278 | expseq1
3279 ;
3280@end group
3281
3282@group
3283expseq1: exp
3284 | expseq1 ',' exp
3285 ;
3286@end group
3287@end example
3288
3289@noindent
3290It is customary to write a comment @samp{/* empty */} in each rule
3291with no components.
3292
342b8b6e 3293@node Recursion
bfa74976
RS
3294@section Recursive Rules
3295@cindex recursive rule
3296
f8e1c9e5
AD
3297A rule is called @dfn{recursive} when its @var{result} nonterminal
3298appears also on its right hand side. Nearly all Bison grammars need to
3299use recursion, because that is the only way to define a sequence of any
3300number of a particular thing. Consider this recursive definition of a
9ecbd125 3301comma-separated sequence of one or more expressions:
bfa74976
RS
3302
3303@example
3304@group
3305expseq1: exp
3306 | expseq1 ',' exp
3307 ;
3308@end group
3309@end example
3310
3311@cindex left recursion
3312@cindex right recursion
3313@noindent
3314Since the recursive use of @code{expseq1} is the leftmost symbol in the
3315right hand side, we call this @dfn{left recursion}. By contrast, here
3316the same construct is defined using @dfn{right recursion}:
3317
3318@example
3319@group
3320expseq1: exp
3321 | exp ',' expseq1
3322 ;
3323@end group
3324@end example
3325
3326@noindent
ec3bc396
AD
3327Any kind of sequence can be defined using either left recursion or right
3328recursion, but you should always use left recursion, because it can
3329parse a sequence of any number of elements with bounded stack space.
3330Right recursion uses up space on the Bison stack in proportion to the
3331number of elements in the sequence, because all the elements must be
3332shifted onto the stack before the rule can be applied even once.
3333@xref{Algorithm, ,The Bison Parser Algorithm}, for further explanation
3334of this.
bfa74976
RS
3335
3336@cindex mutual recursion
3337@dfn{Indirect} or @dfn{mutual} recursion occurs when the result of the
3338rule does not appear directly on its right hand side, but does appear
3339in rules for other nonterminals which do appear on its right hand
13863333 3340side.
bfa74976
RS
3341
3342For example:
3343
3344@example
3345@group
3346expr: primary
3347 | primary '+' primary
3348 ;
3349@end group
3350
3351@group
3352primary: constant
3353 | '(' expr ')'
3354 ;
3355@end group
3356@end example
3357
3358@noindent
3359defines two mutually-recursive nonterminals, since each refers to the
3360other.
3361
342b8b6e 3362@node Semantics
bfa74976
RS
3363@section Defining Language Semantics
3364@cindex defining language semantics
13863333 3365@cindex language semantics, defining
bfa74976
RS
3366
3367The grammar rules for a language determine only the syntax. The semantics
3368are determined by the semantic values associated with various tokens and
3369groupings, and by the actions taken when various groupings are recognized.
3370
3371For example, the calculator calculates properly because the value
3372associated with each expression is the proper number; it adds properly
3373because the action for the grouping @w{@samp{@var{x} + @var{y}}} is to add
3374the numbers associated with @var{x} and @var{y}.
3375
3376@menu
3377* Value Type:: Specifying one data type for all semantic values.
3378* Multiple Types:: Specifying several alternative data types.
3379* Actions:: An action is the semantic definition of a grammar rule.
3380* Action Types:: Specifying data types for actions to operate on.
3381* Mid-Rule Actions:: Most actions go at the end of a rule.
3382 This says when, why and how to use the exceptional
3383 action in the middle of a rule.
1f68dca5 3384* Named References:: Using named references in actions.
bfa74976
RS
3385@end menu
3386
342b8b6e 3387@node Value Type
bfa74976
RS
3388@subsection Data Types of Semantic Values
3389@cindex semantic value type
3390@cindex value type, semantic
3391@cindex data types of semantic values
3392@cindex default data type
3393
3394In a simple program it may be sufficient to use the same data type for
3395the semantic values of all language constructs. This was true in the
35430378 3396RPN and infix calculator examples (@pxref{RPN Calc, ,Reverse Polish
1964ad8c 3397Notation Calculator}).
bfa74976 3398
ddc8ede1
PE
3399Bison normally uses the type @code{int} for semantic values if your
3400program uses the same data type for all language constructs. To
bfa74976
RS
3401specify some other type, define @code{YYSTYPE} as a macro, like this:
3402
3403@example
3404#define YYSTYPE double
3405@end example
3406
3407@noindent
50cce58e
PE
3408@code{YYSTYPE}'s replacement list should be a type name
3409that does not contain parentheses or square brackets.
342b8b6e 3410This macro definition must go in the prologue of the grammar file
75f5aaea 3411(@pxref{Grammar Outline, ,Outline of a Bison Grammar}).
bfa74976 3412
342b8b6e 3413@node Multiple Types
bfa74976
RS
3414@subsection More Than One Value Type
3415
3416In most programs, you will need different data types for different kinds
3417of tokens and groupings. For example, a numeric constant may need type
f8e1c9e5
AD
3418@code{int} or @code{long int}, while a string constant needs type
3419@code{char *}, and an identifier might need a pointer to an entry in the
3420symbol table.
bfa74976
RS
3421
3422To use more than one data type for semantic values in one parser, Bison
3423requires you to do two things:
3424
3425@itemize @bullet
3426@item
ddc8ede1 3427Specify the entire collection of possible data types, either by using the
704a47c4 3428@code{%union} Bison declaration (@pxref{Union Decl, ,The Collection of
ddc8ede1
PE
3429Value Types}), or by using a @code{typedef} or a @code{#define} to
3430define @code{YYSTYPE} to be a union type whose member names are
3431the type tags.
bfa74976
RS
3432
3433@item
14ded682
AD
3434Choose one of those types for each symbol (terminal or nonterminal) for
3435which semantic values are used. This is done for tokens with the
3436@code{%token} Bison declaration (@pxref{Token Decl, ,Token Type Names})
3437and for groupings with the @code{%type} Bison declaration (@pxref{Type
3438Decl, ,Nonterminal Symbols}).
bfa74976
RS
3439@end itemize
3440
342b8b6e 3441@node Actions
bfa74976
RS
3442@subsection Actions
3443@cindex action
3444@vindex $$
3445@vindex $@var{n}
1f68dca5
AR
3446@vindex $@var{name}
3447@vindex $[@var{name}]
bfa74976
RS
3448
3449An action accompanies a syntactic rule and contains C code to be executed
3450each time an instance of that rule is recognized. The task of most actions
3451is to compute a semantic value for the grouping built by the rule from the
3452semantic values associated with tokens or smaller groupings.
3453
287c78f6
PE
3454An action consists of braced code containing C statements, and can be
3455placed at any position in the rule;
704a47c4
AD
3456it is executed at that position. Most rules have just one action at the
3457end of the rule, following all the components. Actions in the middle of
3458a rule are tricky and used only for special purposes (@pxref{Mid-Rule
3459Actions, ,Actions in Mid-Rule}).
bfa74976 3460
9913d6e4
JD
3461The C code in an action can refer to the semantic values of the
3462components matched by the rule with the construct @code{$@var{n}},
3463which stands for the value of the @var{n}th component. The semantic
3464value for the grouping being constructed is @code{$$}. In addition,
3465the semantic values of symbols can be accessed with the named
3466references construct @code{$@var{name}} or @code{$[@var{name}]}.
3467Bison translates both of these constructs into expressions of the
3468appropriate type when it copies the actions into the parser
3469implementation file. @code{$$} (or @code{$@var{name}}, when it stands
3470for the current grouping) is translated to a modifiable lvalue, so it
3471can be assigned to.
bfa74976
RS
3472
3473Here is a typical example:
3474
3475@example
3476@group
3477exp: @dots{}
3478 | exp '+' exp
3479 @{ $$ = $1 + $3; @}
3480@end group
3481@end example
3482
1f68dca5
AR
3483Or, in terms of named references:
3484
3485@example
3486@group
3487exp[result]: @dots{}
3488 | exp[left] '+' exp[right]
3489 @{ $result = $left + $right; @}
3490@end group
3491@end example
3492
bfa74976
RS
3493@noindent
3494This rule constructs an @code{exp} from two smaller @code{exp} groupings
3495connected by a plus-sign token. In the action, @code{$1} and @code{$3}
1f68dca5 3496(@code{$left} and @code{$right})
bfa74976
RS
3497refer to the semantic values of the two component @code{exp} groupings,
3498which are the first and third symbols on the right hand side of the rule.
1f68dca5
AR
3499The sum is stored into @code{$$} (@code{$result}) so that it becomes the
3500semantic value of
bfa74976
RS
3501the addition-expression just recognized by the rule. If there were a
3502useful semantic value associated with the @samp{+} token, it could be
e0c471a9 3503referred to as @code{$2}.
bfa74976 3504
1f68dca5
AR
3505@xref{Named References,,Using Named References}, for more information
3506about using the named references construct.
3507
3ded9a63
AD
3508Note that the vertical-bar character @samp{|} is really a rule
3509separator, and actions are attached to a single rule. This is a
3510difference with tools like Flex, for which @samp{|} stands for either
3511``or'', or ``the same action as that of the next rule''. In the
3512following example, the action is triggered only when @samp{b} is found:
3513
3514@example
3515@group
3516a-or-b: 'a'|'b' @{ a_or_b_found = 1; @};
3517@end group
3518@end example
3519
bfa74976
RS
3520@cindex default action
3521If you don't specify an action for a rule, Bison supplies a default:
72f889cc
AD
3522@w{@code{$$ = $1}.} Thus, the value of the first symbol in the rule
3523becomes the value of the whole rule. Of course, the default action is
3524valid only if the two data types match. There is no meaningful default
3525action for an empty rule; every empty rule must have an explicit action
3526unless the rule's value does not matter.
bfa74976
RS
3527
3528@code{$@var{n}} with @var{n} zero or negative is allowed for reference
3529to tokens and groupings on the stack @emph{before} those that match the
3530current rule. This is a very risky practice, and to use it reliably
3531you must be certain of the context in which the rule is applied. Here
3532is a case in which you can use this reliably:
3533
3534@example
3535@group
3536foo: expr bar '+' expr @{ @dots{} @}
3537 | expr bar '-' expr @{ @dots{} @}
3538 ;
3539@end group
3540
3541@group
3542bar: /* empty */
3543 @{ previous_expr = $0; @}
3544 ;
3545@end group
3546@end example
3547
3548As long as @code{bar} is used only in the fashion shown here, @code{$0}
3549always refers to the @code{expr} which precedes @code{bar} in the
3550definition of @code{foo}.
3551
32c29292 3552@vindex yylval
742e4900 3553It is also possible to access the semantic value of the lookahead token, if
32c29292
JD
3554any, from a semantic action.
3555This semantic value is stored in @code{yylval}.
3556@xref{Action Features, ,Special Features for Use in Actions}.
3557
342b8b6e 3558@node Action Types
bfa74976
RS
3559@subsection Data Types of Values in Actions
3560@cindex action data types
3561@cindex data types in actions
3562
3563If you have chosen a single data type for semantic values, the @code{$$}
3564and @code{$@var{n}} constructs always have that data type.
3565
3566If you have used @code{%union} to specify a variety of data types, then you
3567must declare a choice among these types for each terminal or nonterminal
3568symbol that can have a semantic value. Then each time you use @code{$$} or
3569@code{$@var{n}}, its data type is determined by which symbol it refers to
e0c471a9 3570in the rule. In this example,
bfa74976
RS
3571
3572@example
3573@group
3574exp: @dots{}
3575 | exp '+' exp
3576 @{ $$ = $1 + $3; @}
3577@end group
3578@end example
3579
3580@noindent
3581@code{$1} and @code{$3} refer to instances of @code{exp}, so they all
3582have the data type declared for the nonterminal symbol @code{exp}. If
3583@code{$2} were used, it would have the data type declared for the
e0c471a9 3584terminal symbol @code{'+'}, whatever that might be.
bfa74976
RS
3585
3586Alternatively, you can specify the data type when you refer to the value,
3587by inserting @samp{<@var{type}>} after the @samp{$} at the beginning of the
3588reference. For example, if you have defined types as shown here:
3589
3590@example
3591@group
3592%union @{
3593 int itype;
3594 double dtype;
3595@}
3596@end group
3597@end example
3598
3599@noindent
3600then you can write @code{$<itype>1} to refer to the first subunit of the
3601rule as an integer, or @code{$<dtype>1} to refer to it as a double.
3602
342b8b6e 3603@node Mid-Rule Actions
bfa74976
RS
3604@subsection Actions in Mid-Rule
3605@cindex actions in mid-rule
3606@cindex mid-rule actions
3607
3608Occasionally it is useful to put an action in the middle of a rule.
3609These actions are written just like usual end-of-rule actions, but they
3610are executed before the parser even recognizes the following components.
3611
3612A mid-rule action may refer to the components preceding it using
3613@code{$@var{n}}, but it may not refer to subsequent components because
3614it is run before they are parsed.
3615
3616The mid-rule action itself counts as one of the components of the rule.
3617This makes a difference when there is another action later in the same rule
3618(and usually there is another at the end): you have to count the actions
3619along with the symbols when working out which number @var{n} to use in
3620@code{$@var{n}}.
3621
3622The mid-rule action can also have a semantic value. The action can set
3623its value with an assignment to @code{$$}, and actions later in the rule
3624can refer to the value using @code{$@var{n}}. Since there is no symbol
3625to name the action, there is no way to declare a data type for the value
fdc6758b
MA
3626in advance, so you must use the @samp{$<@dots{}>@var{n}} construct to
3627specify a data type each time you refer to this value.
bfa74976
RS
3628
3629There is no way to set the value of the entire rule with a mid-rule
3630action, because assignments to @code{$$} do not have that effect. The
3631only way to set the value for the entire rule is with an ordinary action
3632at the end of the rule.
3633
3634Here is an example from a hypothetical compiler, handling a @code{let}
3635statement that looks like @samp{let (@var{variable}) @var{statement}} and
3636serves to create a variable named @var{variable} temporarily for the
3637duration of @var{statement}. To parse this construct, we must put
3638@var{variable} into the symbol table while @var{statement} is parsed, then
3639remove it afterward. Here is how it is done:
3640
3641@example
3642@group
3643stmt: LET '(' var ')'
3644 @{ $<context>$ = push_context ();
3645 declare_variable ($3); @}
3646 stmt @{ $$ = $6;
3647 pop_context ($<context>5); @}
3648@end group
3649@end example
3650
3651@noindent
3652As soon as @samp{let (@var{variable})} has been recognized, the first
3653action is run. It saves a copy of the current semantic context (the
3654list of accessible variables) as its semantic value, using alternative
3655@code{context} in the data-type union. Then it calls
3656@code{declare_variable} to add the new variable to that list. Once the
3657first action is finished, the embedded statement @code{stmt} can be
3658parsed. Note that the mid-rule action is component number 5, so the
3659@samp{stmt} is component number 6.
3660
3661After the embedded statement is parsed, its semantic value becomes the
3662value of the entire @code{let}-statement. Then the semantic value from the
3663earlier action is used to restore the prior list of variables. This
3664removes the temporary @code{let}-variable from the list so that it won't
3665appear to exist while the rest of the program is parsed.
3666
841a7737
JD
3667@findex %destructor
3668@cindex discarded symbols, mid-rule actions
3669@cindex error recovery, mid-rule actions
3670In the above example, if the parser initiates error recovery (@pxref{Error
3671Recovery}) while parsing the tokens in the embedded statement @code{stmt},
3672it might discard the previous semantic context @code{$<context>5} without
3673restoring it.
3674Thus, @code{$<context>5} needs a destructor (@pxref{Destructor Decl, , Freeing
3675Discarded Symbols}).
ec5479ce
JD
3676However, Bison currently provides no means to declare a destructor specific to
3677a particular mid-rule action's semantic value.
841a7737
JD
3678
3679One solution is to bury the mid-rule action inside a nonterminal symbol and to
3680declare a destructor for that symbol:
3681
3682@example
3683@group
3684%type <context> let
3685%destructor @{ pop_context ($$); @} let
3686
3687%%
3688
3689stmt: let stmt
3690 @{ $$ = $2;
3691 pop_context ($1); @}
3692 ;
3693
3694let: LET '(' var ')'
3695 @{ $$ = push_context ();
3696 declare_variable ($3); @}
3697 ;
3698
3699@end group
3700@end example
3701
3702@noindent
3703Note that the action is now at the end of its rule.
3704Any mid-rule action can be converted to an end-of-rule action in this way, and
3705this is what Bison actually does to implement mid-rule actions.
3706
bfa74976
RS
3707Taking action before a rule is completely recognized often leads to
3708conflicts since the parser must commit to a parse in order to execute the
3709action. For example, the following two rules, without mid-rule actions,
3710can coexist in a working parser because the parser can shift the open-brace
3711token and look at what follows before deciding whether there is a
3712declaration or not:
3713
3714@example
3715@group
3716compound: '@{' declarations statements '@}'
3717 | '@{' statements '@}'
3718 ;
3719@end group
3720@end example
3721
3722@noindent
3723But when we add a mid-rule action as follows, the rules become nonfunctional:
3724
3725@example
3726@group
3727compound: @{ prepare_for_local_variables (); @}
3728 '@{' declarations statements '@}'
3729@end group
3730@group
3731 | '@{' statements '@}'
3732 ;
3733@end group
3734@end example
3735
3736@noindent
3737Now the parser is forced to decide whether to run the mid-rule action
3738when it has read no farther than the open-brace. In other words, it
3739must commit to using one rule or the other, without sufficient
3740information to do it correctly. (The open-brace token is what is called
742e4900
JD
3741the @dfn{lookahead} token at this time, since the parser is still
3742deciding what to do about it. @xref{Lookahead, ,Lookahead Tokens}.)
bfa74976
RS
3743
3744You might think that you could correct the problem by putting identical
3745actions into the two rules, like this:
3746
3747@example
3748@group
3749compound: @{ prepare_for_local_variables (); @}
3750 '@{' declarations statements '@}'
3751 | @{ prepare_for_local_variables (); @}
3752 '@{' statements '@}'
3753 ;
3754@end group
3755@end example
3756
3757@noindent
3758But this does not help, because Bison does not realize that the two actions
3759are identical. (Bison never tries to understand the C code in an action.)
3760
3761If the grammar is such that a declaration can be distinguished from a
3762statement by the first token (which is true in C), then one solution which
3763does work is to put the action after the open-brace, like this:
3764
3765@example
3766@group
3767compound: '@{' @{ prepare_for_local_variables (); @}
3768 declarations statements '@}'
3769 | '@{' statements '@}'
3770 ;
3771@end group
3772@end example
3773
3774@noindent
3775Now the first token of the following declaration or statement,
3776which would in any case tell Bison which rule to use, can still do so.
3777
3778Another solution is to bury the action inside a nonterminal symbol which
3779serves as a subroutine:
3780
3781@example
3782@group
3783subroutine: /* empty */
3784 @{ prepare_for_local_variables (); @}
3785 ;
3786
3787@end group
3788
3789@group
3790compound: subroutine
3791 '@{' declarations statements '@}'
3792 | subroutine
3793 '@{' statements '@}'
3794 ;
3795@end group
3796@end example
3797
3798@noindent
3799Now Bison can execute the action in the rule for @code{subroutine} without
841a7737 3800deciding which rule for @code{compound} it will eventually use.
bfa74976 3801
1f68dca5
AR
3802@node Named References
3803@subsection Using Named References
3804@cindex named references
3805
3806While every semantic value can be accessed with positional references
3807@code{$@var{n}} and @code{$$}, it's often much more convenient to refer to
3808them by name. First of all, original symbol names may be used as named
3809references. For example:
3810
3811@example
3812@group
3813invocation: op '(' args ')'
3814 @{ $invocation = new_invocation ($op, $args, @@invocation); @}
3815@end group
3816@end example
3817
3818@noindent
3819The positional @code{$$}, @code{@@$}, @code{$n}, and @code{@@n} can be
3820mixed with @code{$name} and @code{@@name} arbitrarily. For example:
3821
3822@example
3823@group
3824invocation: op '(' args ')'
3825 @{ $$ = new_invocation ($op, $args, @@$); @}
3826@end group
3827@end example
3828
3829@noindent
3830However, sometimes regular symbol names are not sufficient due to
3831ambiguities:
3832
3833@example
3834@group
3835exp: exp '/' exp
3836 @{ $exp = $exp / $exp; @} // $exp is ambiguous.
3837
3838exp: exp '/' exp
3839 @{ $$ = $1 / $exp; @} // One usage is ambiguous.
3840
3841exp: exp '/' exp
3842 @{ $$ = $1 / $3; @} // No error.
3843@end group
3844@end example
3845
3846@noindent
3847When ambiguity occurs, explicitly declared names may be used for values and
3848locations. Explicit names are declared as a bracketed name after a symbol
3849appearance in rule definitions. For example:
3850@example
3851@group
3852exp[result]: exp[left] '/' exp[right]
3853 @{ $result = $left / $right; @}
3854@end group
3855@end example
3856
3857@noindent
3858Explicit names may be declared for RHS and for LHS symbols as well. In order
3859to access a semantic value generated by a mid-rule action, an explicit name
3860may also be declared by putting a bracketed name after the closing brace of
3861the mid-rule action code:
3862@example
3863@group
3864exp[res]: exp[x] '+' @{$left = $x;@}[left] exp[right]
3865 @{ $res = $left + $right; @}
3866@end group
3867@end example
3868
3869@noindent
3870
3871In references, in order to specify names containing dots and dashes, an explicit
3872bracketed syntax @code{$[name]} and @code{@@[name]} must be used:
3873@example
3874@group
3875if-stmt: IF '(' expr ')' THEN then.stmt ';'
3876 @{ $[if-stmt] = new_if_stmt ($expr, $[then.stmt]); @}
3877@end group
3878@end example
3879
3880It often happens that named references are followed by a dot, dash or other
3881C punctuation marks and operators. By default, Bison will read
3882@code{$name.suffix} as a reference to symbol value @code{$name} followed by
3883@samp{.suffix}, i.e., an access to the @samp{suffix} field of the semantic
3884value. In order to force Bison to recognize @code{name.suffix} in its entirety
3885as the name of a semantic value, bracketed syntax @code{$[name.suffix]}
3886must be used.
3887
3888
342b8b6e 3889@node Locations
847bf1f5
AD
3890@section Tracking Locations
3891@cindex location
95923bd6
AD
3892@cindex textual location
3893@cindex location, textual
847bf1f5
AD
3894
3895Though grammar rules and semantic actions are enough to write a fully
72d2299c 3896functional parser, it can be useful to process some additional information,
3e259915
MA
3897especially symbol locations.
3898
704a47c4
AD
3899The way locations are handled is defined by providing a data type, and
3900actions to take when rules are matched.
847bf1f5
AD
3901
3902@menu
3903* Location Type:: Specifying a data type for locations.
3904* Actions and Locations:: Using locations in actions.
3905* Location Default Action:: Defining a general way to compute locations.
3906@end menu
3907
342b8b6e 3908@node Location Type
847bf1f5
AD
3909@subsection Data Type of Locations
3910@cindex data type of locations
3911@cindex default location type
3912
3913Defining a data type for locations is much simpler than for semantic values,
3914since all tokens and groupings always use the same type.
3915
50cce58e
PE
3916You can specify the type of locations by defining a macro called
3917@code{YYLTYPE}, just as you can specify the semantic value type by
ddc8ede1 3918defining a @code{YYSTYPE} macro (@pxref{Value Type}).
847bf1f5
AD
3919When @code{YYLTYPE} is not defined, Bison uses a default structure type with
3920four members:
3921
3922@example
6273355b 3923typedef struct YYLTYPE
847bf1f5
AD
3924@{
3925 int first_line;
3926 int first_column;
3927 int last_line;
3928 int last_column;
6273355b 3929@} YYLTYPE;
847bf1f5
AD
3930@end example
3931
8fbbeba2
AD
3932When @code{YYLTYPE} is not defined, at the beginning of the parsing, Bison
3933initializes all these fields to 1 for @code{yylloc}. To initialize
3934@code{yylloc} with a custom location type (or to chose a different
3935initialization), use the @code{%initial-action} directive. @xref{Initial
3936Action Decl, , Performing Actions before Parsing}.
cd48d21d 3937
342b8b6e 3938@node Actions and Locations
847bf1f5
AD
3939@subsection Actions and Locations
3940@cindex location actions
3941@cindex actions, location
3942@vindex @@$
3943@vindex @@@var{n}
1f68dca5
AR
3944@vindex @@@var{name}
3945@vindex @@[@var{name}]
847bf1f5
AD
3946
3947Actions are not only useful for defining language semantics, but also for
3948describing the behavior of the output parser with locations.
3949
3950The most obvious way for building locations of syntactic groupings is very
72d2299c 3951similar to the way semantic values are computed. In a given rule, several
847bf1f5
AD
3952constructs can be used to access the locations of the elements being matched.
3953The location of the @var{n}th component of the right hand side is
3954@code{@@@var{n}}, while the location of the left hand side grouping is
3955@code{@@$}.
3956
1f68dca5
AR
3957In addition, the named references construct @code{@@@var{name}} and
3958@code{@@[@var{name}]} may also be used to address the symbol locations.
3959@xref{Named References,,Using Named References}, for more information
3960about using the named references construct.
3961
3e259915 3962Here is a basic example using the default data type for locations:
847bf1f5
AD
3963
3964@example
3965@group
3966exp: @dots{}
3e259915 3967 | exp '/' exp
847bf1f5 3968 @{
3e259915
MA
3969 @@$.first_column = @@1.first_column;
3970 @@$.first_line = @@1.first_line;
847bf1f5
AD
3971 @@$.last_column = @@3.last_column;
3972 @@$.last_line = @@3.last_line;
3e259915
MA
3973 if ($3)
3974 $$ = $1 / $3;
3975 else
3976 @{
3977 $$ = 1;
4e03e201
AD
3978 fprintf (stderr,
3979 "Division by zero, l%d,c%d-l%d,c%d",
3980 @@3.first_line, @@3.first_column,
3981 @@3.last_line, @@3.last_column);
3e259915 3982 @}
847bf1f5
AD
3983 @}
3984@end group
3985@end example
3986
3e259915 3987As for semantic values, there is a default action for locations that is
72d2299c 3988run each time a rule is matched. It sets the beginning of @code{@@$} to the
3e259915 3989beginning of the first symbol, and the end of @code{@@$} to the end of the
79282c6c 3990last symbol.
3e259915 3991
72d2299c 3992With this default action, the location tracking can be fully automatic. The
3e259915
MA
3993example above simply rewrites this way:
3994
3995@example
3996@group
3997exp: @dots{}
3998 | exp '/' exp
3999 @{
4000 if ($3)
4001 $$ = $1 / $3;
4002 else
4003 @{
4004 $$ = 1;
4e03e201
AD
4005 fprintf (stderr,
4006 "Division by zero, l%d,c%d-l%d,c%d",
4007 @@3.first_line, @@3.first_column,
4008 @@3.last_line, @@3.last_column);
3e259915
MA
4009 @}
4010 @}
4011@end group
4012@end example
847bf1f5 4013
32c29292 4014@vindex yylloc
742e4900 4015It is also possible to access the location of the lookahead token, if any,
32c29292
JD
4016from a semantic action.
4017This location is stored in @code{yylloc}.
4018@xref{Action Features, ,Special Features for Use in Actions}.
4019
342b8b6e 4020@node Location Default Action
847bf1f5
AD
4021@subsection Default Action for Locations
4022@vindex YYLLOC_DEFAULT
35430378 4023@cindex GLR parsers and @code{YYLLOC_DEFAULT}
847bf1f5 4024
72d2299c 4025Actually, actions are not the best place to compute locations. Since
704a47c4
AD
4026locations are much more general than semantic values, there is room in
4027the output parser to redefine the default action to take for each
72d2299c 4028rule. The @code{YYLLOC_DEFAULT} macro is invoked each time a rule is
96b93a3d
PE
4029matched, before the associated action is run. It is also invoked
4030while processing a syntax error, to compute the error's location.
35430378 4031Before reporting an unresolvable syntactic ambiguity, a GLR
8710fc41
JD
4032parser invokes @code{YYLLOC_DEFAULT} recursively to compute the location
4033of that ambiguity.
847bf1f5 4034
3e259915 4035Most of the time, this macro is general enough to suppress location
79282c6c 4036dedicated code from semantic actions.
847bf1f5 4037
72d2299c 4038The @code{YYLLOC_DEFAULT} macro takes three parameters. The first one is
96b93a3d 4039the location of the grouping (the result of the computation). When a
766de5eb 4040rule is matched, the second parameter identifies locations of
96b93a3d 4041all right hand side elements of the rule being matched, and the third
8710fc41 4042parameter is the size of the rule's right hand side.
35430378 4043When a GLR parser reports an ambiguity, which of multiple candidate
8710fc41
JD
4044right hand sides it passes to @code{YYLLOC_DEFAULT} is undefined.
4045When processing a syntax error, the second parameter identifies locations
4046of the symbols that were discarded during error processing, and the third
96b93a3d 4047parameter is the number of discarded symbols.
847bf1f5 4048
766de5eb 4049By default, @code{YYLLOC_DEFAULT} is defined this way:
847bf1f5 4050
766de5eb 4051@smallexample
847bf1f5 4052@group
766de5eb
PE
4053# define YYLLOC_DEFAULT(Current, Rhs, N) \
4054 do \
4055 if (N) \
4056 @{ \
4057 (Current).first_line = YYRHSLOC(Rhs, 1).first_line; \
4058 (Current).first_column = YYRHSLOC(Rhs, 1).first_column; \
4059 (Current).last_line = YYRHSLOC(Rhs, N).last_line; \
4060 (Current).last_column = YYRHSLOC(Rhs, N).last_column; \
4061 @} \
4062 else \
4063 @{ \
4064 (Current).first_line = (Current).last_line = \
4065 YYRHSLOC(Rhs, 0).last_line; \
4066 (Current).first_column = (Current).last_column = \
4067 YYRHSLOC(Rhs, 0).last_column; \
4068 @} \
4069 while (0)
847bf1f5 4070@end group
766de5eb 4071@end smallexample
676385e2 4072
766de5eb
PE
4073where @code{YYRHSLOC (rhs, k)} is the location of the @var{k}th symbol
4074in @var{rhs} when @var{k} is positive, and the location of the symbol
f28ac696 4075just before the reduction when @var{k} and @var{n} are both zero.
676385e2 4076
3e259915 4077When defining @code{YYLLOC_DEFAULT}, you should consider that:
847bf1f5 4078
3e259915 4079@itemize @bullet
79282c6c 4080@item
72d2299c 4081All arguments are free of side-effects. However, only the first one (the
3e259915 4082result) should be modified by @code{YYLLOC_DEFAULT}.
847bf1f5 4083
3e259915 4084@item
766de5eb
PE
4085For consistency with semantic actions, valid indexes within the
4086right hand side range from 1 to @var{n}. When @var{n} is zero, only 0 is a
4087valid index, and it refers to the symbol just before the reduction.
4088During error processing @var{n} is always positive.
0ae99356
PE
4089
4090@item
4091Your macro should parenthesize its arguments, if need be, since the
4092actual arguments may not be surrounded by parentheses. Also, your
4093macro should expand to something that can be used as a single
4094statement when it is followed by a semicolon.
3e259915 4095@end itemize
847bf1f5 4096
342b8b6e 4097@node Declarations
bfa74976
RS
4098@section Bison Declarations
4099@cindex declarations, Bison
4100@cindex Bison declarations
4101
4102The @dfn{Bison declarations} section of a Bison grammar defines the symbols
4103used in formulating the grammar and the data types of semantic values.
4104@xref{Symbols}.
4105
4106All token type names (but not single-character literal tokens such as
4107@code{'+'} and @code{'*'}) must be declared. Nonterminal symbols must be
4108declared if you need to specify which data type to use for the semantic
4109value (@pxref{Multiple Types, ,More Than One Value Type}).
4110
9913d6e4
JD
4111The first rule in the grammar file also specifies the start symbol, by
4112default. If you want some other symbol to be the start symbol, you
4113must declare it explicitly (@pxref{Language and Grammar, ,Languages
4114and Context-Free Grammars}).
bfa74976
RS
4115
4116@menu
b50d2359 4117* Require Decl:: Requiring a Bison version.
bfa74976
RS
4118* Token Decl:: Declaring terminal symbols.
4119* Precedence Decl:: Declaring terminals with precedence and associativity.
4120* Union Decl:: Declaring the set of all semantic value types.
4121* Type Decl:: Declaring the choice of type for a nonterminal symbol.
18d192f0 4122* Initial Action Decl:: Code run before parsing starts.
72f889cc 4123* Destructor Decl:: Declaring how symbols are freed.
d6328241 4124* Expect Decl:: Suppressing warnings about parsing conflicts.
bfa74976
RS
4125* Start Decl:: Specifying the start symbol.
4126* Pure Decl:: Requesting a reentrant parser.
9987d1b3 4127* Push Decl:: Requesting a push parser.
bfa74976 4128* Decl Summary:: Table of all Bison declarations.
2f4518a1 4129* %define Summary:: Defining variables to adjust Bison's behavior.
8e6f2266 4130* %code Summary:: Inserting code into the parser source.
bfa74976
RS
4131@end menu
4132
b50d2359
AD
4133@node Require Decl
4134@subsection Require a Version of Bison
4135@cindex version requirement
4136@cindex requiring a version of Bison
4137@findex %require
4138
4139You may require the minimum version of Bison to process the grammar. If
9b8a5ce0
AD
4140the requirement is not met, @command{bison} exits with an error (exit
4141status 63).
b50d2359
AD
4142
4143@example
4144%require "@var{version}"
4145@end example
4146
342b8b6e 4147@node Token Decl
bfa74976
RS
4148@subsection Token Type Names
4149@cindex declaring token type names
4150@cindex token type names, declaring
931c7513 4151@cindex declaring literal string tokens
bfa74976
RS
4152@findex %token
4153
4154The basic way to declare a token type name (terminal symbol) is as follows:
4155
4156@example
4157%token @var{name}
4158@end example
4159
4160Bison will convert this into a @code{#define} directive in
4161the parser, so that the function @code{yylex} (if it is in this file)
4162can use the name @var{name} to stand for this token type's code.
4163
14ded682
AD
4164Alternatively, you can use @code{%left}, @code{%right}, or
4165@code{%nonassoc} instead of @code{%token}, if you wish to specify
4166associativity and precedence. @xref{Precedence Decl, ,Operator
4167Precedence}.
bfa74976
RS
4168
4169You can explicitly specify the numeric code for a token type by appending
b1cc23c4 4170a nonnegative decimal or hexadecimal integer value in the field immediately
1452af69 4171following the token name:
bfa74976
RS
4172
4173@example
4174%token NUM 300
1452af69 4175%token XNUM 0x12d // a GNU extension
bfa74976
RS
4176@end example
4177
4178@noindent
4179It is generally best, however, to let Bison choose the numeric codes for
4180all token types. Bison will automatically select codes that don't conflict
e966383b 4181with each other or with normal characters.
bfa74976
RS
4182
4183In the event that the stack type is a union, you must augment the
4184@code{%token} or other token declaration to include the data type
704a47c4
AD
4185alternative delimited by angle-brackets (@pxref{Multiple Types, ,More
4186Than One Value Type}).
bfa74976
RS
4187
4188For example:
4189
4190@example
4191@group
4192%union @{ /* define stack type */
4193 double val;
4194 symrec *tptr;
4195@}
4196%token <val> NUM /* define token NUM and its type */
4197@end group
4198@end example
4199
931c7513
RS
4200You can associate a literal string token with a token type name by
4201writing the literal string at the end of a @code{%token}
4202declaration which declares the name. For example:
4203
4204@example
4205%token arrow "=>"
4206@end example
4207
4208@noindent
4209For example, a grammar for the C language might specify these names with
4210equivalent literal string tokens:
4211
4212@example
4213%token <operator> OR "||"
4214%token <operator> LE 134 "<="
4215%left OR "<="
4216@end example
4217
4218@noindent
4219Once you equate the literal string and the token name, you can use them
4220interchangeably in further declarations or the grammar rules. The
4221@code{yylex} function can use the token name or the literal string to
4222obtain the token type code number (@pxref{Calling Convention}).
b1cc23c4
JD
4223Syntax error messages passed to @code{yyerror} from the parser will reference
4224the literal string instead of the token name.
4225
4226The token numbered as 0 corresponds to end of file; the following line
4227allows for nicer error messages referring to ``end of file'' instead
4228of ``$end'':
4229
4230@example
4231%token END 0 "end of file"
4232@end example
931c7513 4233
342b8b6e 4234@node Precedence Decl
bfa74976
RS
4235@subsection Operator Precedence
4236@cindex precedence declarations
4237@cindex declaring operator precedence
4238@cindex operator precedence, declaring
4239
4240Use the @code{%left}, @code{%right} or @code{%nonassoc} declaration to
4241declare a token and specify its precedence and associativity, all at
4242once. These are called @dfn{precedence declarations}.
704a47c4
AD
4243@xref{Precedence, ,Operator Precedence}, for general information on
4244operator precedence.
bfa74976 4245
ab7f29f8 4246The syntax of a precedence declaration is nearly the same as that of
bfa74976
RS
4247@code{%token}: either
4248
4249@example
4250%left @var{symbols}@dots{}
4251@end example
4252
4253@noindent
4254or
4255
4256@example
4257%left <@var{type}> @var{symbols}@dots{}
4258@end example
4259
4260And indeed any of these declarations serves the purposes of @code{%token}.
4261But in addition, they specify the associativity and relative precedence for
4262all the @var{symbols}:
4263
4264@itemize @bullet
4265@item
4266The associativity of an operator @var{op} determines how repeated uses
4267of the operator nest: whether @samp{@var{x} @var{op} @var{y} @var{op}
4268@var{z}} is parsed by grouping @var{x} with @var{y} first or by
4269grouping @var{y} with @var{z} first. @code{%left} specifies
4270left-associativity (grouping @var{x} with @var{y} first) and
4271@code{%right} specifies right-associativity (grouping @var{y} with
4272@var{z} first). @code{%nonassoc} specifies no associativity, which
4273means that @samp{@var{x} @var{op} @var{y} @var{op} @var{z}} is
4274considered a syntax error.
4275
4276@item
4277The precedence of an operator determines how it nests with other operators.
4278All the tokens declared in a single precedence declaration have equal
4279precedence and nest together according to their associativity.
4280When two tokens declared in different precedence declarations associate,
4281the one declared later has the higher precedence and is grouped first.
4282@end itemize
4283
ab7f29f8
JD
4284For backward compatibility, there is a confusing difference between the
4285argument lists of @code{%token} and precedence declarations.
4286Only a @code{%token} can associate a literal string with a token type name.
4287A precedence declaration always interprets a literal string as a reference to a
4288separate token.
4289For example:
4290
4291@example
4292%left OR "<=" // Does not declare an alias.
4293%left OR 134 "<=" 135 // Declares 134 for OR and 135 for "<=".
4294@end example
4295
342b8b6e 4296@node Union Decl
bfa74976
RS
4297@subsection The Collection of Value Types
4298@cindex declaring value types
4299@cindex value types, declaring
4300@findex %union
4301
287c78f6
PE
4302The @code{%union} declaration specifies the entire collection of
4303possible data types for semantic values. The keyword @code{%union} is
4304followed by braced code containing the same thing that goes inside a
4305@code{union} in C@.
bfa74976
RS
4306
4307For example:
4308
4309@example
4310@group
4311%union @{
4312 double val;
4313 symrec *tptr;
4314@}
4315@end group
4316@end example
4317
4318@noindent
4319This says that the two alternative types are @code{double} and @code{symrec
4320*}. They are given names @code{val} and @code{tptr}; these names are used
4321in the @code{%token} and @code{%type} declarations to pick one of the types
4322for a terminal or nonterminal symbol (@pxref{Type Decl, ,Nonterminal Symbols}).
4323
35430378 4324As an extension to POSIX, a tag is allowed after the
6273355b
PE
4325@code{union}. For example:
4326
4327@example
4328@group
4329%union value @{
4330 double val;
4331 symrec *tptr;
4332@}
4333@end group
4334@end example
4335
d6ca7905 4336@noindent
6273355b
PE
4337specifies the union tag @code{value}, so the corresponding C type is
4338@code{union value}. If you do not specify a tag, it defaults to
4339@code{YYSTYPE}.
4340
35430378 4341As another extension to POSIX, you may specify multiple
d6ca7905
PE
4342@code{%union} declarations; their contents are concatenated. However,
4343only the first @code{%union} declaration can specify a tag.
4344
6273355b 4345Note that, unlike making a @code{union} declaration in C, you need not write
bfa74976
RS
4346a semicolon after the closing brace.
4347
ddc8ede1
PE
4348Instead of @code{%union}, you can define and use your own union type
4349@code{YYSTYPE} if your grammar contains at least one
4350@samp{<@var{type}>} tag. For example, you can put the following into
4351a header file @file{parser.h}:
4352
4353@example
4354@group
4355union YYSTYPE @{
4356 double val;
4357 symrec *tptr;
4358@};
4359typedef union YYSTYPE YYSTYPE;
4360@end group
4361@end example
4362
4363@noindent
4364and then your grammar can use the following
4365instead of @code{%union}:
4366
4367@example
4368@group
4369%@{
4370#include "parser.h"
4371%@}
4372%type <val> expr
4373%token <tptr> ID
4374@end group
4375@end example
4376
342b8b6e 4377@node Type Decl
bfa74976
RS
4378@subsection Nonterminal Symbols
4379@cindex declaring value types, nonterminals
4380@cindex value types, nonterminals, declaring
4381@findex %type
4382
4383@noindent
4384When you use @code{%union} to specify multiple value types, you must
4385declare the value type of each nonterminal symbol for which values are
4386used. This is done with a @code{%type} declaration, like this:
4387
4388@example
4389%type <@var{type}> @var{nonterminal}@dots{}
4390@end example
4391
4392@noindent
704a47c4
AD
4393Here @var{nonterminal} is the name of a nonterminal symbol, and
4394@var{type} is the name given in the @code{%union} to the alternative
4395that you want (@pxref{Union Decl, ,The Collection of Value Types}). You
4396can give any number of nonterminal symbols in the same @code{%type}
4397declaration, if they have the same value type. Use spaces to separate
4398the symbol names.
bfa74976 4399
931c7513
RS
4400You can also declare the value type of a terminal symbol. To do this,
4401use the same @code{<@var{type}>} construction in a declaration for the
4402terminal symbol. All kinds of token declarations allow
4403@code{<@var{type}>}.
4404
18d192f0
AD
4405@node Initial Action Decl
4406@subsection Performing Actions before Parsing
4407@findex %initial-action
4408
4409Sometimes your parser needs to perform some initializations before
4410parsing. The @code{%initial-action} directive allows for such arbitrary
4411code.
4412
4413@deffn {Directive} %initial-action @{ @var{code} @}
4414@findex %initial-action
287c78f6 4415Declare that the braced @var{code} must be invoked before parsing each time
451364ed 4416@code{yyparse} is called. The @var{code} may use @code{$$} and
742e4900 4417@code{@@$} --- initial value and location of the lookahead --- and the
451364ed 4418@code{%parse-param}.
18d192f0
AD
4419@end deffn
4420
451364ed
AD
4421For instance, if your locations use a file name, you may use
4422
4423@example
48b16bbc 4424%parse-param @{ char const *file_name @};
451364ed
AD
4425%initial-action
4426@{
4626a15d 4427 @@$.initialize (file_name);
451364ed
AD
4428@};
4429@end example
4430
18d192f0 4431
72f889cc
AD
4432@node Destructor Decl
4433@subsection Freeing Discarded Symbols
4434@cindex freeing discarded symbols
4435@findex %destructor
12e35840 4436@findex <*>
3ebecc24 4437@findex <>
a85284cf
AD
4438During error recovery (@pxref{Error Recovery}), symbols already pushed
4439on the stack and tokens coming from the rest of the file are discarded
4440until the parser falls on its feet. If the parser runs out of memory,
9d9b8b70 4441or if it returns via @code{YYABORT} or @code{YYACCEPT}, all the
a85284cf
AD
4442symbols on the stack must be discarded. Even if the parser succeeds, it
4443must discard the start symbol.
258b75ca
PE
4444
4445When discarded symbols convey heap based information, this memory is
4446lost. While this behavior can be tolerable for batch parsers, such as
4b367315
AD
4447in traditional compilers, it is unacceptable for programs like shells or
4448protocol implementations that may parse and execute indefinitely.
258b75ca 4449
a85284cf
AD
4450The @code{%destructor} directive defines code that is called when a
4451symbol is automatically discarded.
72f889cc
AD
4452
4453@deffn {Directive} %destructor @{ @var{code} @} @var{symbols}
4454@findex %destructor
287c78f6
PE
4455Invoke the braced @var{code} whenever the parser discards one of the
4456@var{symbols}.
4b367315 4457Within @var{code}, @code{$$} designates the semantic value associated
ec5479ce
JD
4458with the discarded symbol, and @code{@@$} designates its location.
4459The additional parser parameters are also available (@pxref{Parser Function, ,
4460The Parser Function @code{yyparse}}).
ec5479ce 4461
b2a0b7ca
JD
4462When a symbol is listed among @var{symbols}, its @code{%destructor} is called a
4463per-symbol @code{%destructor}.
4464You may also define a per-type @code{%destructor} by listing a semantic type
12e35840 4465tag among @var{symbols}.
b2a0b7ca 4466In that case, the parser will invoke this @var{code} whenever it discards any
12e35840 4467grammar symbol that has that semantic type tag unless that symbol has its own
b2a0b7ca
JD
4468per-symbol @code{%destructor}.
4469
12e35840 4470Finally, you can define two different kinds of default @code{%destructor}s.
85894313
JD
4471(These default forms are experimental.
4472More user feedback will help to determine whether they should become permanent
4473features.)
3ebecc24 4474You can place each of @code{<*>} and @code{<>} in the @var{symbols} list of
12e35840
JD
4475exactly one @code{%destructor} declaration in your grammar file.
4476The parser will invoke the @var{code} associated with one of these whenever it
4477discards any user-defined grammar symbol that has no per-symbol and no per-type
4478@code{%destructor}.
4479The parser uses the @var{code} for @code{<*>} in the case of such a grammar
4480symbol for which you have formally declared a semantic type tag (@code{%type}
4481counts as such a declaration, but @code{$<tag>$} does not).
3ebecc24 4482The parser uses the @var{code} for @code{<>} in the case of such a grammar
12e35840 4483symbol that has no declared semantic type tag.
72f889cc
AD
4484@end deffn
4485
b2a0b7ca 4486@noindent
12e35840 4487For example:
72f889cc
AD
4488
4489@smallexample
ec5479ce
JD
4490%union @{ char *string; @}
4491%token <string> STRING1
4492%token <string> STRING2
4493%type <string> string1
4494%type <string> string2
b2a0b7ca
JD
4495%union @{ char character; @}
4496%token <character> CHR
4497%type <character> chr
12e35840
JD
4498%token TAGLESS
4499
b2a0b7ca 4500%destructor @{ @} <character>
12e35840
JD
4501%destructor @{ free ($$); @} <*>
4502%destructor @{ free ($$); printf ("%d", @@$.first_line); @} STRING1 string1
3ebecc24 4503%destructor @{ printf ("Discarding tagless symbol.\n"); @} <>
72f889cc
AD
4504@end smallexample
4505
4506@noindent
b2a0b7ca
JD
4507guarantees that, when the parser discards any user-defined symbol that has a
4508semantic type tag other than @code{<character>}, it passes its semantic value
12e35840 4509to @code{free} by default.
ec5479ce
JD
4510However, when the parser discards a @code{STRING1} or a @code{string1}, it also
4511prints its line number to @code{stdout}.
4512It performs only the second @code{%destructor} in this case, so it invokes
4513@code{free} only once.
12e35840
JD
4514Finally, the parser merely prints a message whenever it discards any symbol,
4515such as @code{TAGLESS}, that has no semantic type tag.
4516
4517A Bison-generated parser invokes the default @code{%destructor}s only for
4518user-defined as opposed to Bison-defined symbols.
4519For example, the parser will not invoke either kind of default
4520@code{%destructor} for the special Bison-defined symbols @code{$accept},
4521@code{$undefined}, or @code{$end} (@pxref{Table of Symbols, ,Bison Symbols}),
4522none of which you can reference in your grammar.
4523It also will not invoke either for the @code{error} token (@pxref{Table of
4524Symbols, ,error}), which is always defined by Bison regardless of whether you
4525reference it in your grammar.
4526However, it may invoke one of them for the end token (token 0) if you
4527redefine it from @code{$end} to, for example, @code{END}:
3508ce36
JD
4528
4529@smallexample
4530%token END 0
4531@end smallexample
4532
12e35840
JD
4533@cindex actions in mid-rule
4534@cindex mid-rule actions
4535Finally, Bison will never invoke a @code{%destructor} for an unreferenced
4536mid-rule semantic value (@pxref{Mid-Rule Actions,,Actions in Mid-Rule}).
4537That is, Bison does not consider a mid-rule to have a semantic value if you do
4538not reference @code{$$} in the mid-rule's action or @code{$@var{n}} (where
4539@var{n} is the RHS symbol position of the mid-rule) in any later action in that
4540rule.
4541However, if you do reference either, the Bison-generated parser will invoke the
3ebecc24 4542@code{<>} @code{%destructor} whenever it discards the mid-rule symbol.
12e35840 4543
3508ce36
JD
4544@ignore
4545@noindent
4546In the future, it may be possible to redefine the @code{error} token as a
4547nonterminal that captures the discarded symbols.
4548In that case, the parser will invoke the default destructor for it as well.
4549@end ignore
4550
e757bb10
AD
4551@sp 1
4552
4553@cindex discarded symbols
4554@dfn{Discarded symbols} are the following:
4555
4556@itemize
4557@item
4558stacked symbols popped during the first phase of error recovery,
4559@item
4560incoming terminals during the second phase of error recovery,
4561@item
742e4900 4562the current lookahead and the entire stack (except the current
9d9b8b70 4563right-hand side symbols) when the parser returns immediately, and
258b75ca
PE
4564@item
4565the start symbol, when the parser succeeds.
e757bb10
AD
4566@end itemize
4567
9d9b8b70
PE
4568The parser can @dfn{return immediately} because of an explicit call to
4569@code{YYABORT} or @code{YYACCEPT}, or failed error recovery, or memory
4570exhaustion.
4571
29553547 4572Right-hand side symbols of a rule that explicitly triggers a syntax
9d9b8b70
PE
4573error via @code{YYERROR} are not discarded automatically. As a rule
4574of thumb, destructors are invoked only when user actions cannot manage
a85284cf 4575the memory.
e757bb10 4576
342b8b6e 4577@node Expect Decl
bfa74976
RS
4578@subsection Suppressing Conflict Warnings
4579@cindex suppressing conflict warnings
4580@cindex preventing warnings about conflicts
4581@cindex warnings, preventing
4582@cindex conflicts, suppressing warnings of
4583@findex %expect
d6328241 4584@findex %expect-rr
bfa74976
RS
4585
4586Bison normally warns if there are any conflicts in the grammar
7da99ede
AD
4587(@pxref{Shift/Reduce, ,Shift/Reduce Conflicts}), but most real grammars
4588have harmless shift/reduce conflicts which are resolved in a predictable
4589way and would be difficult to eliminate. It is desirable to suppress
4590the warning about these conflicts unless the number of conflicts
4591changes. You can do this with the @code{%expect} declaration.
bfa74976
RS
4592
4593The declaration looks like this:
4594
4595@example
4596%expect @var{n}
4597@end example
4598
035aa4a0
PE
4599Here @var{n} is a decimal integer. The declaration says there should
4600be @var{n} shift/reduce conflicts and no reduce/reduce conflicts.
4601Bison reports an error if the number of shift/reduce conflicts differs
4602from @var{n}, or if there are any reduce/reduce conflicts.
bfa74976 4603
34a6c2d1 4604For deterministic parsers, reduce/reduce conflicts are more
035aa4a0 4605serious, and should be eliminated entirely. Bison will always report
35430378 4606reduce/reduce conflicts for these parsers. With GLR
035aa4a0 4607parsers, however, both kinds of conflicts are routine; otherwise,
35430378 4608there would be no need to use GLR parsing. Therefore, it is
035aa4a0 4609also possible to specify an expected number of reduce/reduce conflicts
35430378 4610in GLR parsers, using the declaration:
d6328241
PH
4611
4612@example
4613%expect-rr @var{n}
4614@end example
4615
bfa74976
RS
4616In general, using @code{%expect} involves these steps:
4617
4618@itemize @bullet
4619@item
4620Compile your grammar without @code{%expect}. Use the @samp{-v} option
4621to get a verbose list of where the conflicts occur. Bison will also
4622print the number of conflicts.
4623
4624@item
4625Check each of the conflicts to make sure that Bison's default
4626resolution is what you really want. If not, rewrite the grammar and
4627go back to the beginning.
4628
4629@item
4630Add an @code{%expect} declaration, copying the number @var{n} from the
35430378 4631number which Bison printed. With GLR parsers, add an
035aa4a0 4632@code{%expect-rr} declaration as well.
bfa74976
RS
4633@end itemize
4634
cf22447c
JD
4635Now Bison will report an error if you introduce an unexpected conflict,
4636but will keep silent otherwise.
bfa74976 4637
342b8b6e 4638@node Start Decl
bfa74976
RS
4639@subsection The Start-Symbol
4640@cindex declaring the start symbol
4641@cindex start symbol, declaring
4642@cindex default start symbol
4643@findex %start
4644
4645Bison assumes by default that the start symbol for the grammar is the first
4646nonterminal specified in the grammar specification section. The programmer
4647may override this restriction with the @code{%start} declaration as follows:
4648
4649@example
4650%start @var{symbol}
4651@end example
4652
342b8b6e 4653@node Pure Decl
bfa74976
RS
4654@subsection A Pure (Reentrant) Parser
4655@cindex reentrant parser
4656@cindex pure parser
d9df47b6 4657@findex %define api.pure
bfa74976
RS
4658
4659A @dfn{reentrant} program is one which does not alter in the course of
4660execution; in other words, it consists entirely of @dfn{pure} (read-only)
4661code. Reentrancy is important whenever asynchronous execution is possible;
9d9b8b70
PE
4662for example, a nonreentrant program may not be safe to call from a signal
4663handler. In systems with multiple threads of control, a nonreentrant
bfa74976
RS
4664program must be called only within interlocks.
4665
70811b85 4666Normally, Bison generates a parser which is not reentrant. This is
c827f760
PE
4667suitable for most uses, and it permits compatibility with Yacc. (The
4668standard Yacc interfaces are inherently nonreentrant, because they use
70811b85
RS
4669statically allocated variables for communication with @code{yylex},
4670including @code{yylval} and @code{yylloc}.)
bfa74976 4671
70811b85 4672Alternatively, you can generate a pure, reentrant parser. The Bison
d9df47b6 4673declaration @code{%define api.pure} says that you want the parser to be
70811b85 4674reentrant. It looks like this:
bfa74976
RS
4675
4676@example
d9df47b6 4677%define api.pure
bfa74976
RS
4678@end example
4679
70811b85
RS
4680The result is that the communication variables @code{yylval} and
4681@code{yylloc} become local variables in @code{yyparse}, and a different
4682calling convention is used for the lexical analyzer function
4683@code{yylex}. @xref{Pure Calling, ,Calling Conventions for Pure
f4101aa6
AD
4684Parsers}, for the details of this. The variable @code{yynerrs}
4685becomes local in @code{yyparse} in pull mode but it becomes a member
9987d1b3 4686of yypstate in push mode. (@pxref{Error Reporting, ,The Error
70811b85
RS
4687Reporting Function @code{yyerror}}). The convention for calling
4688@code{yyparse} itself is unchanged.
4689
4690Whether the parser is pure has nothing to do with the grammar rules.
4691You can generate either a pure parser or a nonreentrant parser from any
4692valid grammar.
bfa74976 4693
9987d1b3
JD
4694@node Push Decl
4695@subsection A Push Parser
4696@cindex push parser
4697@cindex push parser
812775a0 4698@findex %define api.push-pull
9987d1b3 4699
59da312b
JD
4700(The current push parsing interface is experimental and may evolve.
4701More user feedback will help to stabilize it.)
4702
f4101aa6
AD
4703A pull parser is called once and it takes control until all its input
4704is completely parsed. A push parser, on the other hand, is called
9987d1b3
JD
4705each time a new token is made available.
4706
f4101aa6 4707A push parser is typically useful when the parser is part of a
9987d1b3 4708main event loop in the client's application. This is typically
f4101aa6
AD
4709a requirement of a GUI, when the main event loop needs to be triggered
4710within a certain time period.
9987d1b3 4711
d782395d
JD
4712Normally, Bison generates a pull parser.
4713The following Bison declaration says that you want the parser to be a push
2f4518a1 4714parser (@pxref{%define Summary,,api.push-pull}):
9987d1b3
JD
4715
4716@example
f37495f6 4717%define api.push-pull push
9987d1b3
JD
4718@end example
4719
4720In almost all cases, you want to ensure that your push parser is also
4721a pure parser (@pxref{Pure Decl, ,A Pure (Reentrant) Parser}). The only
f4101aa6 4722time you should create an impure push parser is to have backwards
9987d1b3
JD
4723compatibility with the impure Yacc pull mode interface. Unless you know
4724what you are doing, your declarations should look like this:
4725
4726@example
d9df47b6 4727%define api.pure
f37495f6 4728%define api.push-pull push
9987d1b3
JD
4729@end example
4730
f4101aa6
AD
4731There is a major notable functional difference between the pure push parser
4732and the impure push parser. It is acceptable for a pure push parser to have
9987d1b3
JD
4733many parser instances, of the same type of parser, in memory at the same time.
4734An impure push parser should only use one parser at a time.
4735
4736When a push parser is selected, Bison will generate some new symbols in
f4101aa6
AD
4737the generated parser. @code{yypstate} is a structure that the generated
4738parser uses to store the parser's state. @code{yypstate_new} is the
9987d1b3
JD
4739function that will create a new parser instance. @code{yypstate_delete}
4740will free the resources associated with the corresponding parser instance.
f4101aa6 4741Finally, @code{yypush_parse} is the function that should be called whenever a
9987d1b3
JD
4742token is available to provide the parser. A trivial example
4743of using a pure push parser would look like this:
4744
4745@example
4746int status;
4747yypstate *ps = yypstate_new ();
4748do @{
4749 status = yypush_parse (ps, yylex (), NULL);
4750@} while (status == YYPUSH_MORE);
4751yypstate_delete (ps);
4752@end example
4753
4754If the user decided to use an impure push parser, a few things about
f4101aa6 4755the generated parser will change. The @code{yychar} variable becomes
9987d1b3
JD
4756a global variable instead of a variable in the @code{yypush_parse} function.
4757For this reason, the signature of the @code{yypush_parse} function is
f4101aa6 4758changed to remove the token as a parameter. A nonreentrant push parser
9987d1b3
JD
4759example would thus look like this:
4760
4761@example
4762extern int yychar;
4763int status;
4764yypstate *ps = yypstate_new ();
4765do @{
4766 yychar = yylex ();
4767 status = yypush_parse (ps);
4768@} while (status == YYPUSH_MORE);
4769yypstate_delete (ps);
4770@end example
4771
f4101aa6 4772That's it. Notice the next token is put into the global variable @code{yychar}
9987d1b3
JD
4773for use by the next invocation of the @code{yypush_parse} function.
4774
f4101aa6 4775Bison also supports both the push parser interface along with the pull parser
9987d1b3 4776interface in the same generated parser. In order to get this functionality,
f37495f6
JD
4777you should replace the @code{%define api.push-pull push} declaration with the
4778@code{%define api.push-pull both} declaration. Doing this will create all of
c373bf8b 4779the symbols mentioned earlier along with the two extra symbols, @code{yyparse}
f4101aa6
AD
4780and @code{yypull_parse}. @code{yyparse} can be used exactly as it normally
4781would be used. However, the user should note that it is implemented in the
d782395d
JD
4782generated parser by calling @code{yypull_parse}.
4783This makes the @code{yyparse} function that is generated with the
f37495f6 4784@code{%define api.push-pull both} declaration slower than the normal
d782395d
JD
4785@code{yyparse} function. If the user
4786calls the @code{yypull_parse} function it will parse the rest of the input
f4101aa6
AD
4787stream. It is possible to @code{yypush_parse} tokens to select a subgrammar
4788and then @code{yypull_parse} the rest of the input stream. If you would like
4789to switch back and forth between between parsing styles, you would have to
4790write your own @code{yypull_parse} function that knows when to quit looking
4791for input. An example of using the @code{yypull_parse} function would look
9987d1b3
JD
4792like this:
4793
4794@example
4795yypstate *ps = yypstate_new ();
4796yypull_parse (ps); /* Will call the lexer */
4797yypstate_delete (ps);
4798@end example
4799
d9df47b6 4800Adding the @code{%define api.pure} declaration does exactly the same thing to
f37495f6
JD
4801the generated parser with @code{%define api.push-pull both} as it did for
4802@code{%define api.push-pull push}.
9987d1b3 4803
342b8b6e 4804@node Decl Summary
bfa74976
RS
4805@subsection Bison Declaration Summary
4806@cindex Bison declaration summary
4807@cindex declaration summary
4808@cindex summary, Bison declaration
4809
d8988b2f 4810Here is a summary of the declarations used to define a grammar:
bfa74976 4811
18b519c0 4812@deffn {Directive} %union
bfa74976
RS
4813Declare the collection of data types that semantic values may have
4814(@pxref{Union Decl, ,The Collection of Value Types}).
18b519c0 4815@end deffn
bfa74976 4816
18b519c0 4817@deffn {Directive} %token
bfa74976
RS
4818Declare a terminal symbol (token type name) with no precedence
4819or associativity specified (@pxref{Token Decl, ,Token Type Names}).
18b519c0 4820@end deffn
bfa74976 4821
18b519c0 4822@deffn {Directive} %right
bfa74976
RS
4823Declare a terminal symbol (token type name) that is right-associative
4824(@pxref{Precedence Decl, ,Operator Precedence}).
18b519c0 4825@end deffn
bfa74976 4826
18b519c0 4827@deffn {Directive} %left
bfa74976
RS
4828Declare a terminal symbol (token type name) that is left-associative
4829(@pxref{Precedence Decl, ,Operator Precedence}).
18b519c0 4830@end deffn
bfa74976 4831
18b519c0 4832@deffn {Directive} %nonassoc
bfa74976 4833Declare a terminal symbol (token type name) that is nonassociative
bfa74976 4834(@pxref{Precedence Decl, ,Operator Precedence}).
39a06c25
PE
4835Using it in a way that would be associative is a syntax error.
4836@end deffn
4837
91d2c560 4838@ifset defaultprec
39a06c25 4839@deffn {Directive} %default-prec
22fccf95 4840Assign a precedence to rules lacking an explicit @code{%prec} modifier
39a06c25
PE
4841(@pxref{Contextual Precedence, ,Context-Dependent Precedence}).
4842@end deffn
91d2c560 4843@end ifset
bfa74976 4844
18b519c0 4845@deffn {Directive} %type
bfa74976
RS
4846Declare the type of semantic values for a nonterminal symbol
4847(@pxref{Type Decl, ,Nonterminal Symbols}).
18b519c0 4848@end deffn
bfa74976 4849
18b519c0 4850@deffn {Directive} %start
89cab50d
AD
4851Specify the grammar's start symbol (@pxref{Start Decl, ,The
4852Start-Symbol}).
18b519c0 4853@end deffn
bfa74976 4854
18b519c0 4855@deffn {Directive} %expect
bfa74976
RS
4856Declare the expected number of shift-reduce conflicts
4857(@pxref{Expect Decl, ,Suppressing Conflict Warnings}).
18b519c0
AD
4858@end deffn
4859
bfa74976 4860
d8988b2f
AD
4861@sp 1
4862@noindent
4863In order to change the behavior of @command{bison}, use the following
4864directives:
4865
148d66d8 4866@deffn {Directive} %code @{@var{code}@}
8e6f2266 4867@deffnx {Directive} %code @var{qualifier} @{@var{code}@}
148d66d8 4868@findex %code
8e6f2266
JD
4869Insert @var{code} verbatim into the output parser source at the
4870default location or at the location specified by @var{qualifier}.
4871@xref{%code Summary}.
148d66d8
JD
4872@end deffn
4873
18b519c0 4874@deffn {Directive} %debug
9913d6e4
JD
4875In the parser implementation file, define the macro @code{YYDEBUG} to
48761 if it is not already defined, so that the debugging facilities are
4877compiled. @xref{Tracing, ,Tracing Your Parser}.
bd5df716 4878@end deffn
d8988b2f 4879
2f4518a1
JD
4880@deffn {Directive} %define @var{variable}
4881@deffnx {Directive} %define @var{variable} @var{value}
4882@deffnx {Directive} %define @var{variable} "@var{value}"
4883Define a variable to adjust Bison's behavior. @xref{%define Summary}.
4884@end deffn
4885
4886@deffn {Directive} %defines
4887Write a parser header file containing macro definitions for the token
4888type names defined in the grammar as well as a few other declarations.
4889If the parser implementation file is named @file{@var{name}.c} then
4890the parser header file is named @file{@var{name}.h}.
4891
4892For C parsers, the parser header file declares @code{YYSTYPE} unless
4893@code{YYSTYPE} is already defined as a macro or you have used a
4894@code{<@var{type}>} tag without using @code{%union}. Therefore, if
4895you are using a @code{%union} (@pxref{Multiple Types, ,More Than One
4896Value Type}) with components that require other definitions, or if you
4897have defined a @code{YYSTYPE} macro or type definition (@pxref{Value
4898Type, ,Data Types of Semantic Values}), you need to arrange for these
4899definitions to be propagated to all modules, e.g., by putting them in
4900a prerequisite header that is included both by your parser and by any
4901other module that needs @code{YYSTYPE}.
4902
4903Unless your parser is pure, the parser header file declares
4904@code{yylval} as an external variable. @xref{Pure Decl, ,A Pure
4905(Reentrant) Parser}.
4906
4907If you have also used locations, the parser header file declares
4908@code{YYLTYPE} and @code{yylloc} using a protocol similar to that of
4909the @code{YYSTYPE} macro and @code{yylval}. @xref{Locations,
4910,Tracking Locations}.
4911
4912This parser header file is normally essential if you wish to put the
4913definition of @code{yylex} in a separate source file, because
4914@code{yylex} typically needs to be able to refer to the
4915above-mentioned declarations and to the token type codes. @xref{Token
4916Values, ,Semantic Values of Tokens}.
4917
4918@findex %code requires
4919@findex %code provides
4920If you have declared @code{%code requires} or @code{%code provides}, the output
4921header also contains their code.
4922@xref{%code Summary}.
4923@end deffn
4924
4925@deffn {Directive} %defines @var{defines-file}
4926Same as above, but save in the file @var{defines-file}.
4927@end deffn
4928
4929@deffn {Directive} %destructor
4930Specify how the parser should reclaim the memory associated to
4931discarded symbols. @xref{Destructor Decl, , Freeing Discarded Symbols}.
4932@end deffn
4933
4934@deffn {Directive} %file-prefix "@var{prefix}"
4935Specify a prefix to use for all Bison output file names. The names
4936are chosen as if the grammar file were named @file{@var{prefix}.y}.
4937@end deffn
4938
4939@deffn {Directive} %language "@var{language}"
4940Specify the programming language for the generated parser. Currently
4941supported languages include C, C++, and Java.
4942@var{language} is case-insensitive.
4943
4944This directive is experimental and its effect may be modified in future
4945releases.
4946@end deffn
4947
4948@deffn {Directive} %locations
4949Generate the code processing the locations (@pxref{Action Features,
4950,Special Features for Use in Actions}). This mode is enabled as soon as
4951the grammar uses the special @samp{@@@var{n}} tokens, but if your
4952grammar does not use it, using @samp{%locations} allows for more
4953accurate syntax error messages.
4954@end deffn
4955
4956@deffn {Directive} %name-prefix "@var{prefix}"
4957Rename the external symbols used in the parser so that they start with
4958@var{prefix} instead of @samp{yy}. The precise list of symbols renamed
4959in C parsers
4960is @code{yyparse}, @code{yylex}, @code{yyerror}, @code{yynerrs},
4961@code{yylval}, @code{yychar}, @code{yydebug}, and
4962(if locations are used) @code{yylloc}. If you use a push parser,
4963@code{yypush_parse}, @code{yypull_parse}, @code{yypstate},
4964@code{yypstate_new} and @code{yypstate_delete} will
4965also be renamed. For example, if you use @samp{%name-prefix "c_"}, the
4966names become @code{c_parse}, @code{c_lex}, and so on.
4967For C++ parsers, see the @code{%define namespace} documentation in this
4968section.
4969@xref{Multiple Parsers, ,Multiple Parsers in the Same Program}.
4970@end deffn
4971
4972@ifset defaultprec
4973@deffn {Directive} %no-default-prec
4974Do not assign a precedence to rules lacking an explicit @code{%prec}
4975modifier (@pxref{Contextual Precedence, ,Context-Dependent
4976Precedence}).
4977@end deffn
4978@end ifset
4979
4980@deffn {Directive} %no-lines
4981Don't generate any @code{#line} preprocessor commands in the parser
4982implementation file. Ordinarily Bison writes these commands in the
4983parser implementation file so that the C compiler and debuggers will
4984associate errors and object code with your source file (the grammar
4985file). This directive causes them to associate errors with the parser
4986implementation file, treating it as an independent source file in its
4987own right.
4988@end deffn
4989
4990@deffn {Directive} %output "@var{file}"
4991Specify @var{file} for the parser implementation file.
4992@end deffn
4993
4994@deffn {Directive} %pure-parser
4995Deprecated version of @code{%define api.pure} (@pxref{%define
4996Summary,,api.pure}), for which Bison is more careful to warn about
4997unreasonable usage.
4998@end deffn
4999
5000@deffn {Directive} %require "@var{version}"
5001Require version @var{version} or higher of Bison. @xref{Require Decl, ,
5002Require a Version of Bison}.
5003@end deffn
5004
5005@deffn {Directive} %skeleton "@var{file}"
5006Specify the skeleton to use.
5007
5008@c You probably don't need this option unless you are developing Bison.
5009@c You should use @code{%language} if you want to specify the skeleton for a
5010@c different language, because it is clearer and because it will always choose the
5011@c correct skeleton for non-deterministic or push parsers.
5012
5013If @var{file} does not contain a @code{/}, @var{file} is the name of a skeleton
5014file in the Bison installation directory.
5015If it does, @var{file} is an absolute file name or a file name relative to the
5016directory of the grammar file.
5017This is similar to how most shells resolve commands.
5018@end deffn
5019
5020@deffn {Directive} %token-table
5021Generate an array of token names in the parser implementation file.
5022The name of the array is @code{yytname}; @code{yytname[@var{i}]} is
5023the name of the token whose internal Bison token code number is
5024@var{i}. The first three elements of @code{yytname} correspond to the
5025predefined tokens @code{"$end"}, @code{"error"}, and
5026@code{"$undefined"}; after these come the symbols defined in the
5027grammar file.
5028
5029The name in the table includes all the characters needed to represent
5030the token in Bison. For single-character literals and literal
5031strings, this includes the surrounding quoting characters and any
5032escape sequences. For example, the Bison single-character literal
5033@code{'+'} corresponds to a three-character name, represented in C as
5034@code{"'+'"}; and the Bison two-character literal string @code{"\\/"}
5035corresponds to a five-character name, represented in C as
5036@code{"\"\\\\/\""}.
5037
5038When you specify @code{%token-table}, Bison also generates macro
5039definitions for macros @code{YYNTOKENS}, @code{YYNNTS}, and
5040@code{YYNRULES}, and @code{YYNSTATES}:
5041
5042@table @code
5043@item YYNTOKENS
5044The highest token number, plus one.
5045@item YYNNTS
5046The number of nonterminal symbols.
5047@item YYNRULES
5048The number of grammar rules,
5049@item YYNSTATES
5050The number of parser states (@pxref{Parser States}).
5051@end table
5052@end deffn
5053
5054@deffn {Directive} %verbose
5055Write an extra output file containing verbose descriptions of the
5056parser states and what is done for each type of lookahead token in
5057that state. @xref{Understanding, , Understanding Your Parser}, for more
5058information.
5059@end deffn
5060
5061@deffn {Directive} %yacc
5062Pretend the option @option{--yacc} was given, i.e., imitate Yacc,
5063including its naming conventions. @xref{Bison Options}, for more.
5064@end deffn
5065
5066
5067@node %define Summary
5068@subsection %define Summary
406dec82
JD
5069
5070There are many features of Bison's behavior that can be controlled by
5071assigning the feature a single value. For historical reasons, some
5072such features are assigned values by dedicated directives, such as
5073@code{%start}, which assigns the start symbol. However, newer such
5074features are associated with variables, which are assigned by the
5075@code{%define} directive:
5076
c1d19e10 5077@deffn {Directive} %define @var{variable}
f37495f6 5078@deffnx {Directive} %define @var{variable} @var{value}
c1d19e10 5079@deffnx {Directive} %define @var{variable} "@var{value}"
406dec82 5080Define @var{variable} to @var{value}.
9611cfa2 5081
406dec82
JD
5082@var{value} must be placed in quotation marks if it contains any
5083character other than a letter, underscore, period, or non-initial dash
5084or digit. Omitting @code{"@var{value}"} entirely is always equivalent
5085to specifying @code{""}.
9611cfa2 5086
406dec82
JD
5087It is an error if a @var{variable} is defined by @code{%define}
5088multiple times, but see @ref{Bison Options,,-D
5089@var{name}[=@var{value}]}.
5090@end deffn
f37495f6 5091
406dec82
JD
5092The rest of this section summarizes variables and values that
5093@code{%define} accepts.
9611cfa2 5094
406dec82
JD
5095Some @var{variable}s take Boolean values. In this case, Bison will
5096complain if the variable definition does not meet one of the following
5097four conditions:
9611cfa2
JD
5098
5099@enumerate
f37495f6 5100@item @code{@var{value}} is @code{true}
9611cfa2 5101
f37495f6
JD
5102@item @code{@var{value}} is omitted (or @code{""} is specified).
5103This is equivalent to @code{true}.
9611cfa2 5104
f37495f6 5105@item @code{@var{value}} is @code{false}.
9611cfa2
JD
5106
5107@item @var{variable} is never defined.
628be6c9 5108In this case, Bison selects a default value.
9611cfa2 5109@end enumerate
148d66d8 5110
628be6c9
JD
5111What @var{variable}s are accepted, as well as their meanings and default
5112values, depend on the selected target language and/or the parser
5113skeleton (@pxref{Decl Summary,,%language}, @pxref{Decl
5114Summary,,%skeleton}).
5115Unaccepted @var{variable}s produce an error.
793fbca5
JD
5116Some of the accepted @var{variable}s are:
5117
5118@itemize @bullet
d9df47b6
JD
5119@item api.pure
5120@findex %define api.pure
5121
5122@itemize @bullet
5123@item Language(s): C
5124
5125@item Purpose: Request a pure (reentrant) parser program.
5126@xref{Pure Decl, ,A Pure (Reentrant) Parser}.
5127
5128@item Accepted Values: Boolean
5129
f37495f6 5130@item Default Value: @code{false}
d9df47b6
JD
5131@end itemize
5132
812775a0
JD
5133@item api.push-pull
5134@findex %define api.push-pull
793fbca5
JD
5135
5136@itemize @bullet
34a6c2d1 5137@item Language(s): C (deterministic parsers only)
793fbca5 5138
3b1977ea 5139@item Purpose: Request a pull parser, a push parser, or both.
d782395d 5140@xref{Push Decl, ,A Push Parser}.
59da312b
JD
5141(The current push parsing interface is experimental and may evolve.
5142More user feedback will help to stabilize it.)
793fbca5 5143
f37495f6 5144@item Accepted Values: @code{pull}, @code{push}, @code{both}
793fbca5 5145
f37495f6 5146@item Default Value: @code{pull}
793fbca5
JD
5147@end itemize
5148
232be91a
AD
5149@c ================================================== lr.default-reductions
5150
1d0f55cc 5151@item lr.default-reductions
620b5727 5152@cindex default reductions
1d0f55cc 5153@findex %define lr.default-reductions
34a6c2d1
JD
5154@cindex delayed syntax errors
5155@cindex syntax errors delayed
35430378 5156@cindex LAC
4c38b19e 5157@findex %nonassoc
34a6c2d1
JD
5158
5159@itemize @bullet
5160@item Language(s): all
5161
4c38b19e 5162@item Purpose: Specify the kind of states that are permitted to
620b5727 5163contain default reductions.
4c38b19e
JD
5164That is, in such a state, Bison selects the reduction with the largest
5165lookahead set to be the default parser action and then removes that
620b5727 5166lookahead set.
4c38b19e
JD
5167(The ability to specify where default reductions should be used is
5168experimental.
34a6c2d1
JD
5169More user feedback will help to stabilize it.)
5170
5171@item Accepted Values:
5172@itemize
f37495f6 5173@item @code{all}.
2f4518a1
JD
5174This is the traditional Bison behavior. The main advantage is a
5175significant decrease in the size of the parser tables. The
5176disadvantage is that, when the generated parser encounters a
4c38b19e
JD
5177syntactically unacceptable token, the parser might then perform
5178unnecessary default reductions before it can detect the syntax error.
2f4518a1
JD
5179Such delayed syntax error detection is usually inherent in LALR and
5180IELR parser tables anyway due to LR state merging (@pxref{%define
5181Summary,,lr.type}). Furthermore, the use of @code{%nonassoc} can
5182contribute to delayed syntax error detection even in the case of
5183canonical LR. As an experimental feature, delayed syntax error
5184detection can be overcome in all cases by enabling LAC (@pxref{%define
5185Summary,,parse.lac}, for details, including a discussion of the
5186effects of delayed syntax error detection).
34a6c2d1 5187
f37495f6 5188@item @code{consistent}.
34a6c2d1
JD
5189@cindex consistent states
5190A consistent state is a state that has only one possible action.
5191If that action is a reduction, then the parser does not need to request
5192a lookahead token from the scanner before performing that action.
4c38b19e
JD
5193However, the parser recognizes the ability to ignore the lookahead token
5194in this way only when such a reduction is encoded as a default
5195reduction.
5196Thus, if default reductions are permitted only in consistent states,
35430378 5197then a canonical LR parser that does not employ
4c38b19e
JD
5198@code{%nonassoc} detects a syntax error as soon as it @emph{needs} the
5199syntactically unacceptable token from the scanner.
34a6c2d1 5200
f37495f6 5201@item @code{accepting}.
34a6c2d1 5202@cindex accepting state
4c38b19e
JD
5203In the accepting state, the default reduction is actually the accept
5204action.
35430378 5205In this case, a canonical LR parser that does not employ
4c38b19e
JD
5206@code{%nonassoc} detects a syntax error as soon as it @emph{reaches} the
5207syntactically unacceptable token in the input.
5208That is, it does not perform any extra reductions.
34a6c2d1
JD
5209@end itemize
5210
5211@item Default Value:
5212@itemize
f37495f6
JD
5213@item @code{accepting} if @code{lr.type} is @code{canonical-lr}.
5214@item @code{all} otherwise.
34a6c2d1
JD
5215@end itemize
5216@end itemize
5217
232be91a
AD
5218@c ============================================ lr.keep-unreachable-states
5219
812775a0
JD
5220@item lr.keep-unreachable-states
5221@findex %define lr.keep-unreachable-states
31984206
JD
5222
5223@itemize @bullet
5224@item Language(s): all
5225
3b1977ea
JD
5226@item Purpose: Request that Bison allow unreachable parser states to
5227remain in the parser tables.
31984206
JD
5228Bison considers a state to be unreachable if there exists no sequence of
5229transitions from the start state to that state.
5230A state can become unreachable during conflict resolution if Bison disables a
5231shift action leading to it from a predecessor state.
5232Keeping unreachable states is sometimes useful for analysis purposes, but they
5233are useless in the generated parser.
5234
5235@item Accepted Values: Boolean
5236
f37495f6 5237@item Default Value: @code{false}
31984206
JD
5238
5239@item Caveats:
5240
5241@itemize @bullet
cff03fb2
JD
5242
5243@item Unreachable states may contain conflicts and may use rules not used in
5244any other state.
31984206
JD
5245Thus, keeping unreachable states may induce warnings that are irrelevant to
5246your parser's behavior, and it may eliminate warnings that are relevant.
5247Of course, the change in warnings may actually be relevant to a parser table
5248analysis that wants to keep unreachable states, so this behavior will likely
5249remain in future Bison releases.
5250
5251@item While Bison is able to remove unreachable states, it is not guaranteed to
5252remove other kinds of useless states.
5253Specifically, when Bison disables reduce actions during conflict resolution,
5254some goto actions may become useless, and thus some additional states may
5255become useless.
5256If Bison were to compute which goto actions were useless and then disable those
5257actions, it could identify such states as unreachable and then remove those
5258states.
5259However, Bison does not compute which goto actions are useless.
5260@end itemize
5261@end itemize
5262
232be91a
AD
5263@c ================================================== lr.type
5264
34a6c2d1
JD
5265@item lr.type
5266@findex %define lr.type
35430378
JD
5267@cindex LALR
5268@cindex IELR
5269@cindex LR
34a6c2d1
JD
5270
5271@itemize @bullet
5272@item Language(s): all
5273
3b1977ea 5274@item Purpose: Specify the type of parser tables within the
35430378 5275LR(1) family.
34a6c2d1
JD
5276(This feature is experimental.
5277More user feedback will help to stabilize it.)
5278
5279@item Accepted Values:
5280@itemize
f37495f6 5281@item @code{lalr}.
35430378
JD
5282While Bison generates LALR parser tables by default for
5283historical reasons, IELR or canonical LR is almost
34a6c2d1 5284always preferable for deterministic parsers.
35430378 5285The trouble is that LALR parser tables can suffer from
620b5727 5286mysterious conflicts and thus may not accept the full set of sentences
35430378 5287that IELR and canonical LR accept.
34a6c2d1 5288@xref{Mystery Conflicts}, for details.
35430378 5289However, there are at least two scenarios where LALR may be
34a6c2d1
JD
5290worthwhile:
5291@itemize
35430378
JD
5292@cindex GLR with LALR
5293@item When employing GLR parsers (@pxref{GLR Parsers}), if you
34a6c2d1
JD
5294do not resolve any conflicts statically (for example, with @code{%left}
5295or @code{%prec}), then the parser explores all potential parses of any
5296given input.
35430378 5297In this case, the use of LALR parser tables is guaranteed not
620b5727 5298to alter the language accepted by the parser.
35430378 5299LALR parser tables are the smallest parser tables Bison can
34a6c2d1 5300currently generate, so they may be preferable.
3b1977ea 5301Nevertheless, once you begin to resolve conflicts statically,
35430378
JD
5302GLR begins to behave more like a deterministic parser, and so
5303IELR and canonical LR can be helpful to avoid
5304LALR's mysterious behavior.
34a6c2d1
JD
5305
5306@item Occasionally during development, an especially malformed grammar
35430378
JD
5307with a major recurring flaw may severely impede the IELR or
5308canonical LR parser table generation algorithm.
5309LALR can be a quick way to generate parser tables in order to
34a6c2d1 5310investigate such problems while ignoring the more subtle differences
35430378 5311from IELR and canonical LR.
34a6c2d1
JD
5312@end itemize
5313
f37495f6 5314@item @code{ielr}.
35430378
JD
5315IELR is a minimal LR algorithm.
5316That is, given any grammar (LR or non-LR),
5317IELR and canonical LR always accept exactly the same
34a6c2d1 5318set of sentences.
35430378
JD
5319However, as for LALR, the number of parser states is often an
5320order of magnitude less for IELR than for canonical
5321LR.
5322More importantly, because canonical LR's extra parser states
5323may contain duplicate conflicts in the case of non-LR
5324grammars, the number of conflicts for IELR is often an order
34a6c2d1
JD
5325of magnitude less as well.
5326This can significantly reduce the complexity of developing of a grammar.
5327
f37495f6 5328@item @code{canonical-lr}.
34a6c2d1
JD
5329@cindex delayed syntax errors
5330@cindex syntax errors delayed
35430378 5331@cindex LAC
4c38b19e 5332@findex %nonassoc
2f4518a1
JD
5333While inefficient, canonical LR parser tables can be an interesting
5334means to explore a grammar because they have a property that IELR and
5335LALR tables do not. That is, if @code{%nonassoc} is not used and
5336default reductions are left disabled (@pxref{%define
5337Summary,,lr.default-reductions}), then, for every left context of
5338every canonical LR state, the set of tokens accepted by that state is
5339guaranteed to be the exact set of tokens that is syntactically
5340acceptable in that left context. It might then seem that an advantage
5341of canonical LR parsers in production is that, under the above
5342constraints, they are guaranteed to detect a syntax error as soon as
5343possible without performing any unnecessary reductions. However, IELR
5344parsers using LAC (@pxref{%define Summary,,parse.lac}) are also able
5345to achieve this behavior without sacrificing @code{%nonassoc} or
5346default reductions.
34a6c2d1
JD
5347@end itemize
5348
f37495f6 5349@item Default Value: @code{lalr}
34a6c2d1
JD
5350@end itemize
5351
793fbca5
JD
5352@item namespace
5353@findex %define namespace
5354
5355@itemize
5356@item Languages(s): C++
5357
3b1977ea 5358@item Purpose: Specify the namespace for the parser class.
793fbca5
JD
5359For example, if you specify:
5360
5361@smallexample
5362%define namespace "foo::bar"
5363@end smallexample
5364
5365Bison uses @code{foo::bar} verbatim in references such as:
5366
5367@smallexample
5368foo::bar::parser::semantic_type
5369@end smallexample
5370
5371However, to open a namespace, Bison removes any leading @code{::} and then
5372splits on any remaining occurrences:
5373
5374@smallexample
5375namespace foo @{ namespace bar @{
5376 class position;
5377 class location;
5378@} @}
5379@end smallexample
5380
5381@item Accepted Values: Any absolute or relative C++ namespace reference without
5382a trailing @code{"::"}.
5383For example, @code{"foo"} or @code{"::foo::bar"}.
5384
5385@item Default Value: The value specified by @code{%name-prefix}, which defaults
5386to @code{yy}.
5387This usage of @code{%name-prefix} is for backward compatibility and can be
5388confusing since @code{%name-prefix} also specifies the textual prefix for the
5389lexical analyzer function.
5390Thus, if you specify @code{%name-prefix}, it is best to also specify
5391@code{%define namespace} so that @code{%name-prefix} @emph{only} affects the
5392lexical analyzer function.
5393For example, if you specify:
5394
5395@smallexample
5396%define namespace "foo"
5397%name-prefix "bar::"
5398@end smallexample
5399
5400The parser namespace is @code{foo} and @code{yylex} is referenced as
5401@code{bar::lex}.
5402@end itemize
4c38b19e
JD
5403
5404@c ================================================== parse.lac
5405@item parse.lac
5406@findex %define parse.lac
35430378 5407@cindex LAC
4c38b19e
JD
5408@cindex lookahead correction
5409
5410@itemize
5411@item Languages(s): C
5412
35430378 5413@item Purpose: Enable LAC (lookahead correction) to improve
4c38b19e
JD
5414syntax error handling.
5415
35430378 5416Canonical LR, IELR, and LALR can suffer
4c38b19e
JD
5417from a couple of problems upon encountering a syntax error. First, the
5418parser might perform additional parser stack reductions before
5419discovering the syntax error. Such reductions perform user semantic
5420actions that are unexpected because they are based on an invalid token,
5421and they cause error recovery to begin in a different syntactic context
5422than the one in which the invalid token was encountered. Second, when
5423verbose error messages are enabled (with @code{%error-verbose} or
5424@code{#define YYERROR_VERBOSE}), the expected token list in the syntax
5425error message can both contain invalid tokens and omit valid tokens.
5426
5427The culprits for the above problems are @code{%nonassoc}, default
5428reductions in inconsistent states, and parser state merging. Thus,
35430378
JD
5429IELR and LALR suffer the most. Canonical
5430LR can suffer only if @code{%nonassoc} is used or if default
4c38b19e
JD
5431reductions are enabled for inconsistent states.
5432
35430378
JD
5433LAC is a new mechanism within the parsing algorithm that
5434completely solves these problems for canonical LR,
5435IELR, and LALR without sacrificing @code{%nonassoc},
4c38b19e
JD
5436default reductions, or state mering. Conceptually, the mechanism is
5437straight-forward. Whenever the parser fetches a new token from the
5438scanner so that it can determine the next parser action, it immediately
5439suspends normal parsing and performs an exploratory parse using a
5440temporary copy of the normal parser state stack. During this
5441exploratory parse, the parser does not perform user semantic actions.
5442If the exploratory parse reaches a shift action, normal parsing then
5443resumes on the normal parser stacks. If the exploratory parse reaches
5444an error instead, the parser reports a syntax error. If verbose syntax
5445error messages are enabled, the parser must then discover the list of
5446expected tokens, so it performs a separate exploratory parse for each
5447token in the grammar.
5448
2f4518a1
JD
5449There is one subtlety about the use of LAC. That is, when in a
5450consistent parser state with a default reduction, the parser will not
5451attempt to fetch a token from the scanner because no lookahead is
5452needed to determine the next parser action. Thus, whether default
5453reductions are enabled in consistent states (@pxref{%define
4c38b19e
JD
5454Summary,,lr.default-reductions}) affects how soon the parser detects a
5455syntax error: when it @emph{reaches} an erroneous token or when it
2f4518a1
JD
5456eventually @emph{needs} that token as a lookahead. The latter
5457behavior is probably more intuitive, so Bison currently provides no
5458way to achieve the former behavior while default reductions are fully
5459enabled.
4c38b19e 5460
35430378 5461Thus, when LAC is in use, for some fixed decision of whether
4c38b19e 5462to enable default reductions in consistent states, canonical
35430378 5463LR and IELR behave exactly the same for both
4c38b19e 5464syntactically acceptable and syntactically unacceptable input. While
35430378
JD
5465LALR still does not support the full language-recognition
5466power of canonical LR and IELR, LAC at
5467least enables LALR's syntax error handling to correctly
5468reflect LALR's language-recognition power.
4c38b19e 5469
35430378 5470Because LAC requires many parse actions to be performed twice,
4c38b19e
JD
5471it can have a performance penalty. However, not all parse actions must
5472be performed twice. Specifically, during a series of default reductions
5473in consistent states and shift actions, the parser never has to initiate
5474an exploratory parse. Moreover, the most time-consuming tasks in a
5475parse are often the file I/O, the lexical analysis performed by the
5476scanner, and the user's semantic actions, but none of these are
5477performed during the exploratory parse. Finally, the base of the
5478temporary stack used during an exploratory parse is a pointer into the
5479normal parser state stack so that the stack is never physically copied.
35430378 5480In our experience, the performance penalty of LAC has proven
4c38b19e
JD
5481insignificant for practical grammars.
5482
5483@item Accepted Values: @code{none}, @code{full}
5484
5485@item Default Value: @code{none}
5486@end itemize
793fbca5
JD
5487@end itemize
5488
d8988b2f 5489
8e6f2266
JD
5490@node %code Summary
5491@subsection %code Summary
8e6f2266 5492@findex %code
8e6f2266 5493@cindex Prologue
406dec82
JD
5494
5495The @code{%code} directive inserts code verbatim into the output
5496parser source at any of a predefined set of locations. It thus serves
5497as a flexible and user-friendly alternative to the traditional Yacc
5498prologue, @code{%@{@var{code}%@}}. This section summarizes the
5499functionality of @code{%code} for the various target languages
5500supported by Bison. For a detailed discussion of how to use
5501@code{%code} in place of @code{%@{@var{code}%@}} for C/C++ and why it
5502is advantageous to do so, @pxref{Prologue Alternatives}.
5503
5504@deffn {Directive} %code @{@var{code}@}
5505This is the unqualified form of the @code{%code} directive. It
5506inserts @var{code} verbatim at a language-dependent default location
5507in the parser implementation.
5508
8e6f2266 5509For C/C++, the default location is the parser implementation file
406dec82
JD
5510after the usual contents of the parser header file. Thus, the
5511unqualified form replaces @code{%@{@var{code}%@}} for most purposes.
8e6f2266
JD
5512
5513For Java, the default location is inside the parser class.
5514@end deffn
5515
5516@deffn {Directive} %code @var{qualifier} @{@var{code}@}
5517This is the qualified form of the @code{%code} directive.
406dec82
JD
5518@var{qualifier} identifies the purpose of @var{code} and thus the
5519location(s) where Bison should insert it. That is, if you need to
5520specify location-sensitive @var{code} that does not belong at the
5521default location selected by the unqualified @code{%code} form, use
5522this form instead.
5523@end deffn
5524
5525For any particular qualifier or for the unqualified form, if there are
5526multiple occurrences of the @code{%code} directive, Bison concatenates
5527the specified code in the order in which it appears in the grammar
5528file.
8e6f2266 5529
406dec82
JD
5530Not all qualifiers are accepted for all target languages. Unaccepted
5531qualifiers produce an error. Some of the accepted qualifiers are:
8e6f2266
JD
5532
5533@itemize @bullet
5534@item requires
5535@findex %code requires
5536
5537@itemize @bullet
5538@item Language(s): C, C++
5539
5540@item Purpose: This is the best place to write dependency code required for
5541@code{YYSTYPE} and @code{YYLTYPE}.
5542In other words, it's the best place to define types referenced in @code{%union}
5543directives, and it's the best place to override Bison's default @code{YYSTYPE}
5544and @code{YYLTYPE} definitions.
5545
5546@item Location(s): The parser header file and the parser implementation file
5547before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE}
5548definitions.
5549@end itemize
5550
5551@item provides
5552@findex %code provides
5553
5554@itemize @bullet
5555@item Language(s): C, C++
5556
5557@item Purpose: This is the best place to write additional definitions and
5558declarations that should be provided to other modules.
5559
5560@item Location(s): The parser header file and the parser implementation
5561file after the Bison-generated @code{YYSTYPE}, @code{YYLTYPE}, and
5562token definitions.
5563@end itemize
5564
5565@item top
5566@findex %code top
5567
5568@itemize @bullet
5569@item Language(s): C, C++
5570
5571@item Purpose: The unqualified @code{%code} or @code{%code requires}
5572should usually be more appropriate than @code{%code top}. However,
5573occasionally it is necessary to insert code much nearer the top of the
5574parser implementation file. For example:
5575
5576@smallexample
5577%code top @{
5578 #define _GNU_SOURCE
5579 #include <stdio.h>
5580@}
5581@end smallexample
5582
5583@item Location(s): Near the top of the parser implementation file.
5584@end itemize
5585
5586@item imports
5587@findex %code imports
5588
5589@itemize @bullet
5590@item Language(s): Java
5591
5592@item Purpose: This is the best place to write Java import directives.
5593
5594@item Location(s): The parser Java file after any Java package directive and
5595before any class definitions.
5596@end itemize
5597@end itemize
5598
406dec82
JD
5599Though we say the insertion locations are language-dependent, they are
5600technically skeleton-dependent. Writers of non-standard skeletons
5601however should choose their locations consistently with the behavior
5602of the standard Bison skeletons.
8e6f2266 5603
d8988b2f 5604
342b8b6e 5605@node Multiple Parsers
bfa74976
RS
5606@section Multiple Parsers in the Same Program
5607
5608Most programs that use Bison parse only one language and therefore contain
5609only one Bison parser. But what if you want to parse more than one
5610language with the same program? Then you need to avoid a name conflict
5611between different definitions of @code{yyparse}, @code{yylval}, and so on.
5612
5613The easy way to do this is to use the option @samp{-p @var{prefix}}
704a47c4
AD
5614(@pxref{Invocation, ,Invoking Bison}). This renames the interface
5615functions and variables of the Bison parser to start with @var{prefix}
5616instead of @samp{yy}. You can use this to give each parser distinct
5617names that do not conflict.
bfa74976
RS
5618
5619The precise list of symbols renamed is @code{yyparse}, @code{yylex},
2a8d363a 5620@code{yyerror}, @code{yynerrs}, @code{yylval}, @code{yylloc},
f4101aa6
AD
5621@code{yychar} and @code{yydebug}. If you use a push parser,
5622@code{yypush_parse}, @code{yypull_parse}, @code{yypstate},
9987d1b3 5623@code{yypstate_new} and @code{yypstate_delete} will also be renamed.
f4101aa6 5624For example, if you use @samp{-p c}, the names become @code{cparse},
9987d1b3 5625@code{clex}, and so on.
bfa74976
RS
5626
5627@strong{All the other variables and macros associated with Bison are not
5628renamed.} These others are not global; there is no conflict if the same
5629name is used in different parsers. For example, @code{YYSTYPE} is not
5630renamed, but defining this in different ways in different parsers causes
5631no trouble (@pxref{Value Type, ,Data Types of Semantic Values}).
5632
9913d6e4
JD
5633The @samp{-p} option works by adding macro definitions to the
5634beginning of the parser implementation file, defining @code{yyparse}
5635as @code{@var{prefix}parse}, and so on. This effectively substitutes
5636one name for the other in the entire parser implementation file.
bfa74976 5637
342b8b6e 5638@node Interface
bfa74976
RS
5639@chapter Parser C-Language Interface
5640@cindex C-language interface
5641@cindex interface
5642
5643The Bison parser is actually a C function named @code{yyparse}. Here we
5644describe the interface conventions of @code{yyparse} and the other
5645functions that it needs to use.
5646
5647Keep in mind that the parser uses many C identifiers starting with
5648@samp{yy} and @samp{YY} for internal purposes. If you use such an
75f5aaea
MA
5649identifier (aside from those in this manual) in an action or in epilogue
5650in the grammar file, you are likely to run into trouble.
bfa74976
RS
5651
5652@menu
f56274a8
DJ
5653* Parser Function:: How to call @code{yyparse} and what it returns.
5654* Push Parser Function:: How to call @code{yypush_parse} and what it returns.
5655* Pull Parser Function:: How to call @code{yypull_parse} and what it returns.
5656* Parser Create Function:: How to call @code{yypstate_new} and what it returns.
5657* Parser Delete Function:: How to call @code{yypstate_delete} and what it returns.
5658* Lexical:: You must supply a function @code{yylex}
5659 which reads tokens.
5660* Error Reporting:: You must supply a function @code{yyerror}.
5661* Action Features:: Special features for use in actions.
5662* Internationalization:: How to let the parser speak in the user's
5663 native language.
bfa74976
RS
5664@end menu
5665
342b8b6e 5666@node Parser Function
bfa74976
RS
5667@section The Parser Function @code{yyparse}
5668@findex yyparse
5669
5670You call the function @code{yyparse} to cause parsing to occur. This
5671function reads tokens, executes actions, and ultimately returns when it
5672encounters end-of-input or an unrecoverable syntax error. You can also
14ded682
AD
5673write an action which directs @code{yyparse} to return immediately
5674without reading further.
bfa74976 5675
2a8d363a
AD
5676
5677@deftypefun int yyparse (void)
bfa74976
RS
5678The value returned by @code{yyparse} is 0 if parsing was successful (return
5679is due to end-of-input).
5680
b47dbebe
PE
5681The value is 1 if parsing failed because of invalid input, i.e., input
5682that contains a syntax error or that causes @code{YYABORT} to be
5683invoked.
5684
5685The value is 2 if parsing failed due to memory exhaustion.
2a8d363a 5686@end deftypefun
bfa74976
RS
5687
5688In an action, you can cause immediate return from @code{yyparse} by using
5689these macros:
5690
2a8d363a 5691@defmac YYACCEPT
bfa74976
RS
5692@findex YYACCEPT
5693Return immediately with value 0 (to report success).
2a8d363a 5694@end defmac
bfa74976 5695
2a8d363a 5696@defmac YYABORT
bfa74976
RS
5697@findex YYABORT
5698Return immediately with value 1 (to report failure).
2a8d363a
AD
5699@end defmac
5700
5701If you use a reentrant parser, you can optionally pass additional
5702parameter information to it in a reentrant way. To do so, use the
5703declaration @code{%parse-param}:
5704
feeb0eda 5705@deffn {Directive} %parse-param @{@var{argument-declaration}@}
2a8d363a 5706@findex %parse-param
287c78f6
PE
5707Declare that an argument declared by the braced-code
5708@var{argument-declaration} is an additional @code{yyparse} argument.
94175978 5709The @var{argument-declaration} is used when declaring
feeb0eda
PE
5710functions or prototypes. The last identifier in
5711@var{argument-declaration} must be the argument name.
2a8d363a
AD
5712@end deffn
5713
5714Here's an example. Write this in the parser:
5715
5716@example
feeb0eda
PE
5717%parse-param @{int *nastiness@}
5718%parse-param @{int *randomness@}
2a8d363a
AD
5719@end example
5720
5721@noindent
5722Then call the parser like this:
5723
5724@example
5725@{
5726 int nastiness, randomness;
5727 @dots{} /* @r{Store proper data in @code{nastiness} and @code{randomness}.} */
5728 value = yyparse (&nastiness, &randomness);
5729 @dots{}
5730@}
5731@end example
5732
5733@noindent
5734In the grammar actions, use expressions like this to refer to the data:
5735
5736@example
5737exp: @dots{} @{ @dots{}; *randomness += 1; @dots{} @}
5738@end example
5739
9987d1b3
JD
5740@node Push Parser Function
5741@section The Push Parser Function @code{yypush_parse}
5742@findex yypush_parse
5743
59da312b
JD
5744(The current push parsing interface is experimental and may evolve.
5745More user feedback will help to stabilize it.)
5746
f4101aa6 5747You call the function @code{yypush_parse} to parse a single token. This
f37495f6
JD
5748function is available if either the @code{%define api.push-pull push} or
5749@code{%define api.push-pull both} declaration is used.
9987d1b3
JD
5750@xref{Push Decl, ,A Push Parser}.
5751
5752@deftypefun int yypush_parse (yypstate *yyps)
f4101aa6 5753The value returned by @code{yypush_parse} is the same as for yyparse with the
9987d1b3
JD
5754following exception. @code{yypush_parse} will return YYPUSH_MORE if more input
5755is required to finish parsing the grammar.
5756@end deftypefun
5757
5758@node Pull Parser Function
5759@section The Pull Parser Function @code{yypull_parse}
5760@findex yypull_parse
5761
59da312b
JD
5762(The current push parsing interface is experimental and may evolve.
5763More user feedback will help to stabilize it.)
5764
f4101aa6 5765You call the function @code{yypull_parse} to parse the rest of the input
f37495f6 5766stream. This function is available if the @code{%define api.push-pull both}
f4101aa6 5767declaration is used.
9987d1b3
JD
5768@xref{Push Decl, ,A Push Parser}.
5769
5770@deftypefun int yypull_parse (yypstate *yyps)
5771The value returned by @code{yypull_parse} is the same as for @code{yyparse}.
5772@end deftypefun
5773
5774@node Parser Create Function
5775@section The Parser Create Function @code{yystate_new}
5776@findex yypstate_new
5777
59da312b
JD
5778(The current push parsing interface is experimental and may evolve.
5779More user feedback will help to stabilize it.)
5780
f4101aa6 5781You call the function @code{yypstate_new} to create a new parser instance.
f37495f6
JD
5782This function is available if either the @code{%define api.push-pull push} or
5783@code{%define api.push-pull both} declaration is used.
9987d1b3
JD
5784@xref{Push Decl, ,A Push Parser}.
5785
5786@deftypefun yypstate *yypstate_new (void)
c781580d 5787The function will return a valid parser instance if there was memory available
333e670c
JD
5788or 0 if no memory was available.
5789In impure mode, it will also return 0 if a parser instance is currently
5790allocated.
9987d1b3
JD
5791@end deftypefun
5792
5793@node Parser Delete Function
5794@section The Parser Delete Function @code{yystate_delete}
5795@findex yypstate_delete
5796
59da312b
JD
5797(The current push parsing interface is experimental and may evolve.
5798More user feedback will help to stabilize it.)
5799
9987d1b3 5800You call the function @code{yypstate_delete} to delete a parser instance.
f37495f6
JD
5801function is available if either the @code{%define api.push-pull push} or
5802@code{%define api.push-pull both} declaration is used.
9987d1b3
JD
5803@xref{Push Decl, ,A Push Parser}.
5804
5805@deftypefun void yypstate_delete (yypstate *yyps)
5806This function will reclaim the memory associated with a parser instance.
5807After this call, you should no longer attempt to use the parser instance.
5808@end deftypefun
bfa74976 5809
342b8b6e 5810@node Lexical
bfa74976
RS
5811@section The Lexical Analyzer Function @code{yylex}
5812@findex yylex
5813@cindex lexical analyzer
5814
5815The @dfn{lexical analyzer} function, @code{yylex}, recognizes tokens from
5816the input stream and returns them to the parser. Bison does not create
5817this function automatically; you must write it so that @code{yyparse} can
5818call it. The function is sometimes referred to as a lexical scanner.
5819
9913d6e4
JD
5820In simple programs, @code{yylex} is often defined at the end of the
5821Bison grammar file. If @code{yylex} is defined in a separate source
5822file, you need to arrange for the token-type macro definitions to be
5823available there. To do this, use the @samp{-d} option when you run
5824Bison, so that it will write these macro definitions into the separate
5825parser header file, @file{@var{name}.tab.h}, which you can include in
5826the other source files that need it. @xref{Invocation, ,Invoking
5827Bison}.
bfa74976
RS
5828
5829@menu
5830* Calling Convention:: How @code{yyparse} calls @code{yylex}.
f56274a8
DJ
5831* Token Values:: How @code{yylex} must return the semantic value
5832 of the token it has read.
5833* Token Locations:: How @code{yylex} must return the text location
5834 (line number, etc.) of the token, if the
5835 actions want that.
5836* Pure Calling:: How the calling convention differs in a pure parser
5837 (@pxref{Pure Decl, ,A Pure (Reentrant) Parser}).
bfa74976
RS
5838@end menu
5839
342b8b6e 5840@node Calling Convention
bfa74976
RS
5841@subsection Calling Convention for @code{yylex}
5842
72d2299c
PE
5843The value that @code{yylex} returns must be the positive numeric code
5844for the type of token it has just found; a zero or negative value
5845signifies end-of-input.
bfa74976
RS
5846
5847When a token is referred to in the grammar rules by a name, that name
9913d6e4
JD
5848in the parser implementation file becomes a C macro whose definition
5849is the proper numeric code for that token type. So @code{yylex} can
5850use the name to indicate that type. @xref{Symbols}.
bfa74976
RS
5851
5852When a token is referred to in the grammar rules by a character literal,
5853the numeric code for that character is also the code for the token type.
72d2299c
PE
5854So @code{yylex} can simply return that character code, possibly converted
5855to @code{unsigned char} to avoid sign-extension. The null character
5856must not be used this way, because its code is zero and that
bfa74976
RS
5857signifies end-of-input.
5858
5859Here is an example showing these things:
5860
5861@example
13863333
AD
5862int
5863yylex (void)
bfa74976
RS
5864@{
5865 @dots{}
72d2299c 5866 if (c == EOF) /* Detect end-of-input. */
bfa74976
RS
5867 return 0;
5868 @dots{}
5869 if (c == '+' || c == '-')
72d2299c 5870 return c; /* Assume token type for `+' is '+'. */
bfa74976 5871 @dots{}
72d2299c 5872 return INT; /* Return the type of the token. */
bfa74976
RS
5873 @dots{}
5874@}
5875@end example
5876
5877@noindent
5878This interface has been designed so that the output from the @code{lex}
5879utility can be used without change as the definition of @code{yylex}.
5880
931c7513
RS
5881If the grammar uses literal string tokens, there are two ways that
5882@code{yylex} can determine the token type codes for them:
5883
5884@itemize @bullet
5885@item
5886If the grammar defines symbolic token names as aliases for the
5887literal string tokens, @code{yylex} can use these symbolic names like
5888all others. In this case, the use of the literal string tokens in
5889the grammar file has no effect on @code{yylex}.
5890
5891@item
9ecbd125 5892@code{yylex} can find the multicharacter token in the @code{yytname}
931c7513 5893table. The index of the token in the table is the token type's code.
9ecbd125 5894The name of a multicharacter token is recorded in @code{yytname} with a
931c7513 5895double-quote, the token's characters, and another double-quote. The
9e0876fb
PE
5896token's characters are escaped as necessary to be suitable as input
5897to Bison.
931c7513 5898
9e0876fb
PE
5899Here's code for looking up a multicharacter token in @code{yytname},
5900assuming that the characters of the token are stored in
5901@code{token_buffer}, and assuming that the token does not contain any
5902characters like @samp{"} that require escaping.
931c7513
RS
5903
5904@smallexample
5905for (i = 0; i < YYNTOKENS; i++)
5906 @{
5907 if (yytname[i] != 0
5908 && yytname[i][0] == '"'
68449b3a
PE
5909 && ! strncmp (yytname[i] + 1, token_buffer,
5910 strlen (token_buffer))
931c7513
RS
5911 && yytname[i][strlen (token_buffer) + 1] == '"'
5912 && yytname[i][strlen (token_buffer) + 2] == 0)
5913 break;
5914 @}
5915@end smallexample
5916
5917The @code{yytname} table is generated only if you use the
8c9a50be 5918@code{%token-table} declaration. @xref{Decl Summary}.
931c7513
RS
5919@end itemize
5920
342b8b6e 5921@node Token Values
bfa74976
RS
5922@subsection Semantic Values of Tokens
5923
5924@vindex yylval
9d9b8b70 5925In an ordinary (nonreentrant) parser, the semantic value of the token must
bfa74976
RS
5926be stored into the global variable @code{yylval}. When you are using
5927just one data type for semantic values, @code{yylval} has that type.
5928Thus, if the type is @code{int} (the default), you might write this in
5929@code{yylex}:
5930
5931@example
5932@group
5933 @dots{}
72d2299c
PE
5934 yylval = value; /* Put value onto Bison stack. */
5935 return INT; /* Return the type of the token. */
bfa74976
RS
5936 @dots{}
5937@end group
5938@end example
5939
5940When you are using multiple data types, @code{yylval}'s type is a union
704a47c4
AD
5941made from the @code{%union} declaration (@pxref{Union Decl, ,The
5942Collection of Value Types}). So when you store a token's value, you
5943must use the proper member of the union. If the @code{%union}
5944declaration looks like this:
bfa74976
RS
5945
5946@example
5947@group
5948%union @{
5949 int intval;
5950 double val;
5951 symrec *tptr;
5952@}
5953@end group
5954@end example
5955
5956@noindent
5957then the code in @code{yylex} might look like this:
5958
5959@example
5960@group
5961 @dots{}
72d2299c
PE
5962 yylval.intval = value; /* Put value onto Bison stack. */
5963 return INT; /* Return the type of the token. */
bfa74976
RS
5964 @dots{}
5965@end group
5966@end example
5967
95923bd6
AD
5968@node Token Locations
5969@subsection Textual Locations of Tokens
bfa74976
RS
5970
5971@vindex yylloc
847bf1f5 5972If you are using the @samp{@@@var{n}}-feature (@pxref{Locations, ,
f8e1c9e5
AD
5973Tracking Locations}) in actions to keep track of the textual locations
5974of tokens and groupings, then you must provide this information in
5975@code{yylex}. The function @code{yyparse} expects to find the textual
5976location of a token just parsed in the global variable @code{yylloc}.
5977So @code{yylex} must store the proper data in that variable.
847bf1f5
AD
5978
5979By default, the value of @code{yylloc} is a structure and you need only
89cab50d
AD
5980initialize the members that are going to be used by the actions. The
5981four members are called @code{first_line}, @code{first_column},
5982@code{last_line} and @code{last_column}. Note that the use of this
5983feature makes the parser noticeably slower.
bfa74976
RS
5984
5985@tindex YYLTYPE
5986The data type of @code{yylloc} has the name @code{YYLTYPE}.
5987
342b8b6e 5988@node Pure Calling
c656404a 5989@subsection Calling Conventions for Pure Parsers
bfa74976 5990
d9df47b6 5991When you use the Bison declaration @code{%define api.pure} to request a
e425e872
RS
5992pure, reentrant parser, the global communication variables @code{yylval}
5993and @code{yylloc} cannot be used. (@xref{Pure Decl, ,A Pure (Reentrant)
5994Parser}.) In such parsers the two global variables are replaced by
5995pointers passed as arguments to @code{yylex}. You must declare them as
5996shown here, and pass the information back by storing it through those
5997pointers.
bfa74976
RS
5998
5999@example
13863333
AD
6000int
6001yylex (YYSTYPE *lvalp, YYLTYPE *llocp)
bfa74976
RS
6002@{
6003 @dots{}
6004 *lvalp = value; /* Put value onto Bison stack. */
6005 return INT; /* Return the type of the token. */
6006 @dots{}
6007@}
6008@end example
6009
6010If the grammar file does not use the @samp{@@} constructs to refer to
95923bd6 6011textual locations, then the type @code{YYLTYPE} will not be defined. In
bfa74976
RS
6012this case, omit the second argument; @code{yylex} will be called with
6013only one argument.
6014
e425e872 6015
2a8d363a
AD
6016If you wish to pass the additional parameter data to @code{yylex}, use
6017@code{%lex-param} just like @code{%parse-param} (@pxref{Parser
6018Function}).
e425e872 6019
feeb0eda 6020@deffn {Directive} lex-param @{@var{argument-declaration}@}
2a8d363a 6021@findex %lex-param
287c78f6
PE
6022Declare that the braced-code @var{argument-declaration} is an
6023additional @code{yylex} argument declaration.
2a8d363a 6024@end deffn
e425e872 6025
2a8d363a 6026For instance:
e425e872
RS
6027
6028@example
feeb0eda
PE
6029%parse-param @{int *nastiness@}
6030%lex-param @{int *nastiness@}
6031%parse-param @{int *randomness@}
e425e872
RS
6032@end example
6033
6034@noindent
2a8d363a 6035results in the following signature:
e425e872
RS
6036
6037@example
2a8d363a
AD
6038int yylex (int *nastiness);
6039int yyparse (int *nastiness, int *randomness);
e425e872
RS
6040@end example
6041
d9df47b6 6042If @code{%define api.pure} is added:
c656404a
RS
6043
6044@example
2a8d363a
AD
6045int yylex (YYSTYPE *lvalp, int *nastiness);
6046int yyparse (int *nastiness, int *randomness);
c656404a
RS
6047@end example
6048
2a8d363a 6049@noindent
d9df47b6 6050and finally, if both @code{%define api.pure} and @code{%locations} are used:
c656404a 6051
2a8d363a
AD
6052@example
6053int yylex (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness);
6054int yyparse (int *nastiness, int *randomness);
6055@end example
931c7513 6056
342b8b6e 6057@node Error Reporting
bfa74976
RS
6058@section The Error Reporting Function @code{yyerror}
6059@cindex error reporting function
6060@findex yyerror
6061@cindex parse error
6062@cindex syntax error
6063
6e649e65 6064The Bison parser detects a @dfn{syntax error} or @dfn{parse error}
9ecbd125 6065whenever it reads a token which cannot satisfy any syntax rule. An
bfa74976 6066action in the grammar can also explicitly proclaim an error, using the
ceed8467
AD
6067macro @code{YYERROR} (@pxref{Action Features, ,Special Features for Use
6068in Actions}).
bfa74976
RS
6069
6070The Bison parser expects to report the error by calling an error
6071reporting function named @code{yyerror}, which you must supply. It is
6072called by @code{yyparse} whenever a syntax error is found, and it
6e649e65
PE
6073receives one argument. For a syntax error, the string is normally
6074@w{@code{"syntax error"}}.
bfa74976 6075
2a8d363a
AD
6076@findex %error-verbose
6077If you invoke the directive @code{%error-verbose} in the Bison
6078declarations section (@pxref{Bison Declarations, ,The Bison Declarations
6079Section}), then Bison provides a more verbose and specific error message
6e649e65 6080string instead of just plain @w{@code{"syntax error"}}.
bfa74976 6081
1a059451
PE
6082The parser can detect one other kind of error: memory exhaustion. This
6083can happen when the input contains constructions that are very deeply
bfa74976 6084nested. It isn't likely you will encounter this, since the Bison
1a059451
PE
6085parser normally extends its stack automatically up to a very large limit. But
6086if memory is exhausted, @code{yyparse} calls @code{yyerror} in the usual
6087fashion, except that the argument string is @w{@code{"memory exhausted"}}.
6088
6089In some cases diagnostics like @w{@code{"syntax error"}} are
6090translated automatically from English to some other language before
6091they are passed to @code{yyerror}. @xref{Internationalization}.
bfa74976
RS
6092
6093The following definition suffices in simple programs:
6094
6095@example
6096@group
13863333 6097void
38a92d50 6098yyerror (char const *s)
bfa74976
RS
6099@{
6100@end group
6101@group
6102 fprintf (stderr, "%s\n", s);
6103@}
6104@end group
6105@end example
6106
6107After @code{yyerror} returns to @code{yyparse}, the latter will attempt
6108error recovery if you have written suitable error recovery grammar rules
6109(@pxref{Error Recovery}). If recovery is impossible, @code{yyparse} will
6110immediately return 1.
6111
93724f13 6112Obviously, in location tracking pure parsers, @code{yyerror} should have
fa7e68c3 6113an access to the current location.
35430378 6114This is indeed the case for the GLR
2a8d363a 6115parsers, but not for the Yacc parser, for historical reasons. I.e., if
d9df47b6 6116@samp{%locations %define api.pure} is passed then the prototypes for
2a8d363a
AD
6117@code{yyerror} are:
6118
6119@example
38a92d50
PE
6120void yyerror (char const *msg); /* Yacc parsers. */
6121void yyerror (YYLTYPE *locp, char const *msg); /* GLR parsers. */
2a8d363a
AD
6122@end example
6123
feeb0eda 6124If @samp{%parse-param @{int *nastiness@}} is used, then:
2a8d363a
AD
6125
6126@example
b317297e
PE
6127void yyerror (int *nastiness, char const *msg); /* Yacc parsers. */
6128void yyerror (int *nastiness, char const *msg); /* GLR parsers. */
2a8d363a
AD
6129@end example
6130
35430378 6131Finally, GLR and Yacc parsers share the same @code{yyerror} calling
2a8d363a
AD
6132convention for absolutely pure parsers, i.e., when the calling
6133convention of @code{yylex} @emph{and} the calling convention of
d9df47b6
JD
6134@code{%define api.pure} are pure.
6135I.e.:
2a8d363a
AD
6136
6137@example
6138/* Location tracking. */
6139%locations
6140/* Pure yylex. */
d9df47b6 6141%define api.pure
feeb0eda 6142%lex-param @{int *nastiness@}
2a8d363a 6143/* Pure yyparse. */
feeb0eda
PE
6144%parse-param @{int *nastiness@}
6145%parse-param @{int *randomness@}
2a8d363a
AD
6146@end example
6147
6148@noindent
6149results in the following signatures for all the parser kinds:
6150
6151@example
6152int yylex (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness);
6153int yyparse (int *nastiness, int *randomness);
93724f13
AD
6154void yyerror (YYLTYPE *locp,
6155 int *nastiness, int *randomness,
38a92d50 6156 char const *msg);
2a8d363a
AD
6157@end example
6158
1c0c3e95 6159@noindent
38a92d50
PE
6160The prototypes are only indications of how the code produced by Bison
6161uses @code{yyerror}. Bison-generated code always ignores the returned
6162value, so @code{yyerror} can return any type, including @code{void}.
6163Also, @code{yyerror} can be a variadic function; that is why the
6164message is always passed last.
6165
6166Traditionally @code{yyerror} returns an @code{int} that is always
6167ignored, but this is purely for historical reasons, and @code{void} is
6168preferable since it more accurately describes the return type for
6169@code{yyerror}.
93724f13 6170
bfa74976
RS
6171@vindex yynerrs
6172The variable @code{yynerrs} contains the number of syntax errors
8a2800e7 6173reported so far. Normally this variable is global; but if you
704a47c4
AD
6174request a pure parser (@pxref{Pure Decl, ,A Pure (Reentrant) Parser})
6175then it is a local variable which only the actions can access.
bfa74976 6176
342b8b6e 6177@node Action Features
bfa74976
RS
6178@section Special Features for Use in Actions
6179@cindex summary, action features
6180@cindex action features summary
6181
6182Here is a table of Bison constructs, variables and macros that
6183are useful in actions.
6184
18b519c0 6185@deffn {Variable} $$
bfa74976
RS
6186Acts like a variable that contains the semantic value for the
6187grouping made by the current rule. @xref{Actions}.
18b519c0 6188@end deffn
bfa74976 6189
18b519c0 6190@deffn {Variable} $@var{n}
bfa74976
RS
6191Acts like a variable that contains the semantic value for the
6192@var{n}th component of the current rule. @xref{Actions}.
18b519c0 6193@end deffn
bfa74976 6194
18b519c0 6195@deffn {Variable} $<@var{typealt}>$
bfa74976 6196Like @code{$$} but specifies alternative @var{typealt} in the union
704a47c4
AD
6197specified by the @code{%union} declaration. @xref{Action Types, ,Data
6198Types of Values in Actions}.
18b519c0 6199@end deffn
bfa74976 6200
18b519c0 6201@deffn {Variable} $<@var{typealt}>@var{n}
bfa74976 6202Like @code{$@var{n}} but specifies alternative @var{typealt} in the
13863333 6203union specified by the @code{%union} declaration.
e0c471a9 6204@xref{Action Types, ,Data Types of Values in Actions}.
18b519c0 6205@end deffn
bfa74976 6206
18b519c0 6207@deffn {Macro} YYABORT;
bfa74976
RS
6208Return immediately from @code{yyparse}, indicating failure.
6209@xref{Parser Function, ,The Parser Function @code{yyparse}}.
18b519c0 6210@end deffn
bfa74976 6211
18b519c0 6212@deffn {Macro} YYACCEPT;
bfa74976
RS
6213Return immediately from @code{yyparse}, indicating success.
6214@xref{Parser Function, ,The Parser Function @code{yyparse}}.
18b519c0 6215@end deffn
bfa74976 6216
18b519c0 6217@deffn {Macro} YYBACKUP (@var{token}, @var{value});
bfa74976
RS
6218@findex YYBACKUP
6219Unshift a token. This macro is allowed only for rules that reduce
742e4900 6220a single value, and only when there is no lookahead token.
35430378 6221It is also disallowed in GLR parsers.
742e4900 6222It installs a lookahead token with token type @var{token} and
bfa74976
RS
6223semantic value @var{value}; then it discards the value that was
6224going to be reduced by this rule.
6225
6226If the macro is used when it is not valid, such as when there is
742e4900 6227a lookahead token already, then it reports a syntax error with
bfa74976
RS
6228a message @samp{cannot back up} and performs ordinary error
6229recovery.
6230
6231In either case, the rest of the action is not executed.
18b519c0 6232@end deffn
bfa74976 6233
18b519c0 6234@deffn {Macro} YYEMPTY
bfa74976 6235@vindex YYEMPTY
742e4900 6236Value stored in @code{yychar} when there is no lookahead token.
18b519c0 6237@end deffn
bfa74976 6238
32c29292
JD
6239@deffn {Macro} YYEOF
6240@vindex YYEOF
742e4900 6241Value stored in @code{yychar} when the lookahead is the end of the input
32c29292
JD
6242stream.
6243@end deffn
6244
18b519c0 6245@deffn {Macro} YYERROR;
bfa74976
RS
6246@findex YYERROR
6247Cause an immediate syntax error. This statement initiates error
6248recovery just as if the parser itself had detected an error; however, it
6249does not call @code{yyerror}, and does not print any message. If you
6250want to print an error message, call @code{yyerror} explicitly before
6251the @samp{YYERROR;} statement. @xref{Error Recovery}.
18b519c0 6252@end deffn
bfa74976 6253
18b519c0 6254@deffn {Macro} YYRECOVERING
02103984
PE
6255@findex YYRECOVERING
6256The expression @code{YYRECOVERING ()} yields 1 when the parser
6257is recovering from a syntax error, and 0 otherwise.
bfa74976 6258@xref{Error Recovery}.
18b519c0 6259@end deffn
bfa74976 6260
18b519c0 6261@deffn {Variable} yychar
742e4900
JD
6262Variable containing either the lookahead token, or @code{YYEOF} when the
6263lookahead is the end of the input stream, or @code{YYEMPTY} when no lookahead
32c29292
JD
6264has been performed so the next token is not yet known.
6265Do not modify @code{yychar} in a deferred semantic action (@pxref{GLR Semantic
6266Actions}).
742e4900 6267@xref{Lookahead, ,Lookahead Tokens}.
18b519c0 6268@end deffn
bfa74976 6269
18b519c0 6270@deffn {Macro} yyclearin;
742e4900 6271Discard the current lookahead token. This is useful primarily in
32c29292
JD
6272error rules.
6273Do not invoke @code{yyclearin} in a deferred semantic action (@pxref{GLR
6274Semantic Actions}).
6275@xref{Error Recovery}.
18b519c0 6276@end deffn
bfa74976 6277
18b519c0 6278@deffn {Macro} yyerrok;
bfa74976 6279Resume generating error messages immediately for subsequent syntax
13863333 6280errors. This is useful primarily in error rules.
bfa74976 6281@xref{Error Recovery}.
18b519c0 6282@end deffn
bfa74976 6283
32c29292 6284@deffn {Variable} yylloc
742e4900 6285Variable containing the lookahead token location when @code{yychar} is not set
32c29292
JD
6286to @code{YYEMPTY} or @code{YYEOF}.
6287Do not modify @code{yylloc} in a deferred semantic action (@pxref{GLR Semantic
6288Actions}).
6289@xref{Actions and Locations, ,Actions and Locations}.
6290@end deffn
6291
6292@deffn {Variable} yylval
742e4900 6293Variable containing the lookahead token semantic value when @code{yychar} is
32c29292
JD
6294not set to @code{YYEMPTY} or @code{YYEOF}.
6295Do not modify @code{yylval} in a deferred semantic action (@pxref{GLR Semantic
6296Actions}).
6297@xref{Actions, ,Actions}.
6298@end deffn
6299
18b519c0 6300@deffn {Value} @@$
847bf1f5 6301@findex @@$
95923bd6 6302Acts like a structure variable containing information on the textual location
847bf1f5
AD
6303of the grouping made by the current rule. @xref{Locations, ,
6304Tracking Locations}.
bfa74976 6305
847bf1f5
AD
6306@c Check if those paragraphs are still useful or not.
6307
6308@c @example
6309@c struct @{
6310@c int first_line, last_line;
6311@c int first_column, last_column;
6312@c @};
6313@c @end example
6314
6315@c Thus, to get the starting line number of the third component, you would
6316@c use @samp{@@3.first_line}.
bfa74976 6317
847bf1f5
AD
6318@c In order for the members of this structure to contain valid information,
6319@c you must make @code{yylex} supply this information about each token.
6320@c If you need only certain members, then @code{yylex} need only fill in
6321@c those members.
bfa74976 6322
847bf1f5 6323@c The use of this feature makes the parser noticeably slower.
18b519c0 6324@end deffn
847bf1f5 6325
18b519c0 6326@deffn {Value} @@@var{n}
847bf1f5 6327@findex @@@var{n}
95923bd6 6328Acts like a structure variable containing information on the textual location
847bf1f5
AD
6329of the @var{n}th component of the current rule. @xref{Locations, ,
6330Tracking Locations}.
18b519c0 6331@end deffn
bfa74976 6332
f7ab6a50
PE
6333@node Internationalization
6334@section Parser Internationalization
6335@cindex internationalization
6336@cindex i18n
6337@cindex NLS
6338@cindex gettext
6339@cindex bison-po
6340
6341A Bison-generated parser can print diagnostics, including error and
6342tracing messages. By default, they appear in English. However, Bison
f8e1c9e5
AD
6343also supports outputting diagnostics in the user's native language. To
6344make this work, the user should set the usual environment variables.
6345@xref{Users, , The User's View, gettext, GNU @code{gettext} utilities}.
6346For example, the shell command @samp{export LC_ALL=fr_CA.UTF-8} might
35430378 6347set the user's locale to French Canadian using the UTF-8
f7ab6a50
PE
6348encoding. The exact set of available locales depends on the user's
6349installation.
6350
6351The maintainer of a package that uses a Bison-generated parser enables
6352the internationalization of the parser's output through the following
35430378
JD
6353steps. Here we assume a package that uses GNU Autoconf and
6354GNU Automake.
f7ab6a50
PE
6355
6356@enumerate
6357@item
30757c8c 6358@cindex bison-i18n.m4
35430378 6359Into the directory containing the GNU Autoconf macros used
f7ab6a50
PE
6360by the package---often called @file{m4}---copy the
6361@file{bison-i18n.m4} file installed by Bison under
6362@samp{share/aclocal/bison-i18n.m4} in Bison's installation directory.
6363For example:
6364
6365@example
6366cp /usr/local/share/aclocal/bison-i18n.m4 m4/bison-i18n.m4
6367@end example
6368
6369@item
30757c8c
PE
6370@findex BISON_I18N
6371@vindex BISON_LOCALEDIR
6372@vindex YYENABLE_NLS
f7ab6a50
PE
6373In the top-level @file{configure.ac}, after the @code{AM_GNU_GETTEXT}
6374invocation, add an invocation of @code{BISON_I18N}. This macro is
6375defined in the file @file{bison-i18n.m4} that you copied earlier. It
6376causes @samp{configure} to find the value of the
30757c8c
PE
6377@code{BISON_LOCALEDIR} variable, and it defines the source-language
6378symbol @code{YYENABLE_NLS} to enable translations in the
6379Bison-generated parser.
f7ab6a50
PE
6380
6381@item
6382In the @code{main} function of your program, designate the directory
6383containing Bison's runtime message catalog, through a call to
6384@samp{bindtextdomain} with domain name @samp{bison-runtime}.
6385For example:
6386
6387@example
6388bindtextdomain ("bison-runtime", BISON_LOCALEDIR);
6389@end example
6390
6391Typically this appears after any other call @code{bindtextdomain
6392(PACKAGE, LOCALEDIR)} that your package already has. Here we rely on
6393@samp{BISON_LOCALEDIR} to be defined as a string through the
6394@file{Makefile}.
6395
6396@item
6397In the @file{Makefile.am} that controls the compilation of the @code{main}
6398function, make @samp{BISON_LOCALEDIR} available as a C preprocessor macro,
6399either in @samp{DEFS} or in @samp{AM_CPPFLAGS}. For example:
6400
6401@example
6402DEFS = @@DEFS@@ -DBISON_LOCALEDIR='"$(BISON_LOCALEDIR)"'
6403@end example
6404
6405or:
6406
6407@example
6408AM_CPPFLAGS = -DBISON_LOCALEDIR='"$(BISON_LOCALEDIR)"'
6409@end example
6410
6411@item
6412Finally, invoke the command @command{autoreconf} to generate the build
6413infrastructure.
6414@end enumerate
6415
bfa74976 6416
342b8b6e 6417@node Algorithm
13863333
AD
6418@chapter The Bison Parser Algorithm
6419@cindex Bison parser algorithm
bfa74976
RS
6420@cindex algorithm of parser
6421@cindex shifting
6422@cindex reduction
6423@cindex parser stack
6424@cindex stack, parser
6425
6426As Bison reads tokens, it pushes them onto a stack along with their
6427semantic values. The stack is called the @dfn{parser stack}. Pushing a
6428token is traditionally called @dfn{shifting}.
6429
6430For example, suppose the infix calculator has read @samp{1 + 5 *}, with a
6431@samp{3} to come. The stack will have four elements, one for each token
6432that was shifted.
6433
6434But the stack does not always have an element for each token read. When
6435the last @var{n} tokens and groupings shifted match the components of a
6436grammar rule, they can be combined according to that rule. This is called
6437@dfn{reduction}. Those tokens and groupings are replaced on the stack by a
6438single grouping whose symbol is the result (left hand side) of that rule.
6439Running the rule's action is part of the process of reduction, because this
6440is what computes the semantic value of the resulting grouping.
6441
6442For example, if the infix calculator's parser stack contains this:
6443
6444@example
64451 + 5 * 3
6446@end example
6447
6448@noindent
6449and the next input token is a newline character, then the last three
6450elements can be reduced to 15 via the rule:
6451
6452@example
6453expr: expr '*' expr;
6454@end example
6455
6456@noindent
6457Then the stack contains just these three elements:
6458
6459@example
64601 + 15
6461@end example
6462
6463@noindent
6464At this point, another reduction can be made, resulting in the single value
646516. Then the newline token can be shifted.
6466
6467The parser tries, by shifts and reductions, to reduce the entire input down
6468to a single grouping whose symbol is the grammar's start-symbol
6469(@pxref{Language and Grammar, ,Languages and Context-Free Grammars}).
6470
6471This kind of parser is known in the literature as a bottom-up parser.
6472
6473@menu
742e4900 6474* Lookahead:: Parser looks one token ahead when deciding what to do.
bfa74976
RS
6475* Shift/Reduce:: Conflicts: when either shifting or reduction is valid.
6476* Precedence:: Operator precedence works by resolving conflicts.
6477* Contextual Precedence:: When an operator's precedence depends on context.
6478* Parser States:: The parser is a finite-state-machine with stack.
6479* Reduce/Reduce:: When two rules are applicable in the same situation.
f56274a8 6480* Mystery Conflicts:: Reduce/reduce conflicts that look unjustified.
676385e2 6481* Generalized LR Parsing:: Parsing arbitrary context-free grammars.
1a059451 6482* Memory Management:: What happens when memory is exhausted. How to avoid it.
bfa74976
RS
6483@end menu
6484
742e4900
JD
6485@node Lookahead
6486@section Lookahead Tokens
6487@cindex lookahead token
bfa74976
RS
6488
6489The Bison parser does @emph{not} always reduce immediately as soon as the
6490last @var{n} tokens and groupings match a rule. This is because such a
6491simple strategy is inadequate to handle most languages. Instead, when a
6492reduction is possible, the parser sometimes ``looks ahead'' at the next
6493token in order to decide what to do.
6494
6495When a token is read, it is not immediately shifted; first it becomes the
742e4900 6496@dfn{lookahead token}, which is not on the stack. Now the parser can
bfa74976 6497perform one or more reductions of tokens and groupings on the stack, while
742e4900
JD
6498the lookahead token remains off to the side. When no more reductions
6499should take place, the lookahead token is shifted onto the stack. This
bfa74976 6500does not mean that all possible reductions have been done; depending on the
742e4900 6501token type of the lookahead token, some rules may choose to delay their
bfa74976
RS
6502application.
6503
742e4900 6504Here is a simple case where lookahead is needed. These three rules define
bfa74976
RS
6505expressions which contain binary addition operators and postfix unary
6506factorial operators (@samp{!}), and allow parentheses for grouping.
6507
6508@example
6509@group
6510expr: term '+' expr
6511 | term
6512 ;
6513@end group
6514
6515@group
6516term: '(' expr ')'
6517 | term '!'
6518 | NUMBER
6519 ;
6520@end group
6521@end example
6522
6523Suppose that the tokens @w{@samp{1 + 2}} have been read and shifted; what
6524should be done? If the following token is @samp{)}, then the first three
6525tokens must be reduced to form an @code{expr}. This is the only valid
6526course, because shifting the @samp{)} would produce a sequence of symbols
6527@w{@code{term ')'}}, and no rule allows this.
6528
6529If the following token is @samp{!}, then it must be shifted immediately so
6530that @w{@samp{2 !}} can be reduced to make a @code{term}. If instead the
6531parser were to reduce before shifting, @w{@samp{1 + 2}} would become an
6532@code{expr}. It would then be impossible to shift the @samp{!} because
6533doing so would produce on the stack the sequence of symbols @code{expr
6534'!'}. No rule allows that sequence.
6535
6536@vindex yychar
32c29292
JD
6537@vindex yylval
6538@vindex yylloc
742e4900 6539The lookahead token is stored in the variable @code{yychar}.
32c29292
JD
6540Its semantic value and location, if any, are stored in the variables
6541@code{yylval} and @code{yylloc}.
bfa74976
RS
6542@xref{Action Features, ,Special Features for Use in Actions}.
6543
342b8b6e 6544@node Shift/Reduce
bfa74976
RS
6545@section Shift/Reduce Conflicts
6546@cindex conflicts
6547@cindex shift/reduce conflicts
6548@cindex dangling @code{else}
6549@cindex @code{else}, dangling
6550
6551Suppose we are parsing a language which has if-then and if-then-else
6552statements, with a pair of rules like this:
6553
6554@example
6555@group
6556if_stmt:
6557 IF expr THEN stmt
6558 | IF expr THEN stmt ELSE stmt
6559 ;
6560@end group
6561@end example
6562
6563@noindent
6564Here we assume that @code{IF}, @code{THEN} and @code{ELSE} are
6565terminal symbols for specific keyword tokens.
6566
742e4900 6567When the @code{ELSE} token is read and becomes the lookahead token, the
bfa74976
RS
6568contents of the stack (assuming the input is valid) are just right for
6569reduction by the first rule. But it is also legitimate to shift the
6570@code{ELSE}, because that would lead to eventual reduction by the second
6571rule.
6572
6573This situation, where either a shift or a reduction would be valid, is
6574called a @dfn{shift/reduce conflict}. Bison is designed to resolve
6575these conflicts by choosing to shift, unless otherwise directed by
6576operator precedence declarations. To see the reason for this, let's
6577contrast it with the other alternative.
6578
6579Since the parser prefers to shift the @code{ELSE}, the result is to attach
6580the else-clause to the innermost if-statement, making these two inputs
6581equivalent:
6582
6583@example
6584if x then if y then win (); else lose;
6585
6586if x then do; if y then win (); else lose; end;
6587@end example
6588
6589But if the parser chose to reduce when possible rather than shift, the
6590result would be to attach the else-clause to the outermost if-statement,
6591making these two inputs equivalent:
6592
6593@example
6594if x then if y then win (); else lose;
6595
6596if x then do; if y then win (); end; else lose;
6597@end example
6598
6599The conflict exists because the grammar as written is ambiguous: either
6600parsing of the simple nested if-statement is legitimate. The established
6601convention is that these ambiguities are resolved by attaching the
6602else-clause to the innermost if-statement; this is what Bison accomplishes
6603by choosing to shift rather than reduce. (It would ideally be cleaner to
6604write an unambiguous grammar, but that is very hard to do in this case.)
6605This particular ambiguity was first encountered in the specifications of
6606Algol 60 and is called the ``dangling @code{else}'' ambiguity.
6607
6608To avoid warnings from Bison about predictable, legitimate shift/reduce
cf22447c
JD
6609conflicts, use the @code{%expect @var{n}} declaration.
6610There will be no warning as long as the number of shift/reduce conflicts
6611is exactly @var{n}, and Bison will report an error if there is a
6612different number.
bfa74976
RS
6613@xref{Expect Decl, ,Suppressing Conflict Warnings}.
6614
6615The definition of @code{if_stmt} above is solely to blame for the
6616conflict, but the conflict does not actually appear without additional
9913d6e4
JD
6617rules. Here is a complete Bison grammar file that actually manifests
6618the conflict:
bfa74976
RS
6619
6620@example
6621@group
6622%token IF THEN ELSE variable
6623%%
6624@end group
6625@group
6626stmt: expr
6627 | if_stmt
6628 ;
6629@end group
6630
6631@group
6632if_stmt:
6633 IF expr THEN stmt
6634 | IF expr THEN stmt ELSE stmt
6635 ;
6636@end group
6637
6638expr: variable
6639 ;
6640@end example
6641
342b8b6e 6642@node Precedence
bfa74976
RS
6643@section Operator Precedence
6644@cindex operator precedence
6645@cindex precedence of operators
6646
6647Another situation where shift/reduce conflicts appear is in arithmetic
6648expressions. Here shifting is not always the preferred resolution; the
6649Bison declarations for operator precedence allow you to specify when to
6650shift and when to reduce.
6651
6652@menu
6653* Why Precedence:: An example showing why precedence is needed.
6654* Using Precedence:: How to specify precedence in Bison grammars.
6655* Precedence Examples:: How these features are used in the previous example.
6656* How Precedence:: How they work.
6657@end menu
6658
342b8b6e 6659@node Why Precedence
bfa74976
RS
6660@subsection When Precedence is Needed
6661
6662Consider the following ambiguous grammar fragment (ambiguous because the
6663input @w{@samp{1 - 2 * 3}} can be parsed in two different ways):
6664
6665@example
6666@group
6667expr: expr '-' expr
6668 | expr '*' expr
6669 | expr '<' expr
6670 | '(' expr ')'
6671 @dots{}
6672 ;
6673@end group
6674@end example
6675
6676@noindent
6677Suppose the parser has seen the tokens @samp{1}, @samp{-} and @samp{2};
14ded682
AD
6678should it reduce them via the rule for the subtraction operator? It
6679depends on the next token. Of course, if the next token is @samp{)}, we
6680must reduce; shifting is invalid because no single rule can reduce the
6681token sequence @w{@samp{- 2 )}} or anything starting with that. But if
6682the next token is @samp{*} or @samp{<}, we have a choice: either
6683shifting or reduction would allow the parse to complete, but with
6684different results.
6685
6686To decide which one Bison should do, we must consider the results. If
6687the next operator token @var{op} is shifted, then it must be reduced
6688first in order to permit another opportunity to reduce the difference.
6689The result is (in effect) @w{@samp{1 - (2 @var{op} 3)}}. On the other
6690hand, if the subtraction is reduced before shifting @var{op}, the result
6691is @w{@samp{(1 - 2) @var{op} 3}}. Clearly, then, the choice of shift or
6692reduce should depend on the relative precedence of the operators
6693@samp{-} and @var{op}: @samp{*} should be shifted first, but not
6694@samp{<}.
bfa74976
RS
6695
6696@cindex associativity
6697What about input such as @w{@samp{1 - 2 - 5}}; should this be
14ded682
AD
6698@w{@samp{(1 - 2) - 5}} or should it be @w{@samp{1 - (2 - 5)}}? For most
6699operators we prefer the former, which is called @dfn{left association}.
6700The latter alternative, @dfn{right association}, is desirable for
6701assignment operators. The choice of left or right association is a
6702matter of whether the parser chooses to shift or reduce when the stack
742e4900 6703contains @w{@samp{1 - 2}} and the lookahead token is @samp{-}: shifting
14ded682 6704makes right-associativity.
bfa74976 6705
342b8b6e 6706@node Using Precedence
bfa74976
RS
6707@subsection Specifying Operator Precedence
6708@findex %left
6709@findex %right
6710@findex %nonassoc
6711
6712Bison allows you to specify these choices with the operator precedence
6713declarations @code{%left} and @code{%right}. Each such declaration
6714contains a list of tokens, which are operators whose precedence and
6715associativity is being declared. The @code{%left} declaration makes all
6716those operators left-associative and the @code{%right} declaration makes
6717them right-associative. A third alternative is @code{%nonassoc}, which
6718declares that it is a syntax error to find the same operator twice ``in a
6719row''.
6720
6721The relative precedence of different operators is controlled by the
6722order in which they are declared. The first @code{%left} or
6723@code{%right} declaration in the file declares the operators whose
6724precedence is lowest, the next such declaration declares the operators
6725whose precedence is a little higher, and so on.
6726
342b8b6e 6727@node Precedence Examples
bfa74976
RS
6728@subsection Precedence Examples
6729
6730In our example, we would want the following declarations:
6731
6732@example
6733%left '<'
6734%left '-'
6735%left '*'
6736@end example
6737
6738In a more complete example, which supports other operators as well, we
6739would declare them in groups of equal precedence. For example, @code{'+'} is
6740declared with @code{'-'}:
6741
6742@example
6743%left '<' '>' '=' NE LE GE
6744%left '+' '-'
6745%left '*' '/'
6746@end example
6747
6748@noindent
6749(Here @code{NE} and so on stand for the operators for ``not equal''
6750and so on. We assume that these tokens are more than one character long
6751and therefore are represented by names, not character literals.)
6752
342b8b6e 6753@node How Precedence
bfa74976
RS
6754@subsection How Precedence Works
6755
6756The first effect of the precedence declarations is to assign precedence
6757levels to the terminal symbols declared. The second effect is to assign
704a47c4
AD
6758precedence levels to certain rules: each rule gets its precedence from
6759the last terminal symbol mentioned in the components. (You can also
6760specify explicitly the precedence of a rule. @xref{Contextual
6761Precedence, ,Context-Dependent Precedence}.)
6762
6763Finally, the resolution of conflicts works by comparing the precedence
742e4900 6764of the rule being considered with that of the lookahead token. If the
704a47c4
AD
6765token's precedence is higher, the choice is to shift. If the rule's
6766precedence is higher, the choice is to reduce. If they have equal
6767precedence, the choice is made based on the associativity of that
6768precedence level. The verbose output file made by @samp{-v}
6769(@pxref{Invocation, ,Invoking Bison}) says how each conflict was
6770resolved.
bfa74976
RS
6771
6772Not all rules and not all tokens have precedence. If either the rule or
742e4900 6773the lookahead token has no precedence, then the default is to shift.
bfa74976 6774
342b8b6e 6775@node Contextual Precedence
bfa74976
RS
6776@section Context-Dependent Precedence
6777@cindex context-dependent precedence
6778@cindex unary operator precedence
6779@cindex precedence, context-dependent
6780@cindex precedence, unary operator
6781@findex %prec
6782
6783Often the precedence of an operator depends on the context. This sounds
6784outlandish at first, but it is really very common. For example, a minus
6785sign typically has a very high precedence as a unary operator, and a
6786somewhat lower precedence (lower than multiplication) as a binary operator.
6787
6788The Bison precedence declarations, @code{%left}, @code{%right} and
6789@code{%nonassoc}, can only be used once for a given token; so a token has
6790only one precedence declared in this way. For context-dependent
6791precedence, you need to use an additional mechanism: the @code{%prec}
e0c471a9 6792modifier for rules.
bfa74976
RS
6793
6794The @code{%prec} modifier declares the precedence of a particular rule by
6795specifying a terminal symbol whose precedence should be used for that rule.
6796It's not necessary for that symbol to appear otherwise in the rule. The
6797modifier's syntax is:
6798
6799@example
6800%prec @var{terminal-symbol}
6801@end example
6802
6803@noindent
6804and it is written after the components of the rule. Its effect is to
6805assign the rule the precedence of @var{terminal-symbol}, overriding
6806the precedence that would be deduced for it in the ordinary way. The
6807altered rule precedence then affects how conflicts involving that rule
6808are resolved (@pxref{Precedence, ,Operator Precedence}).
6809
6810Here is how @code{%prec} solves the problem of unary minus. First, declare
6811a precedence for a fictitious terminal symbol named @code{UMINUS}. There
6812are no tokens of this type, but the symbol serves to stand for its
6813precedence:
6814
6815@example
6816@dots{}
6817%left '+' '-'
6818%left '*'
6819%left UMINUS
6820@end example
6821
6822Now the precedence of @code{UMINUS} can be used in specific rules:
6823
6824@example
6825@group
6826exp: @dots{}
6827 | exp '-' exp
6828 @dots{}
6829 | '-' exp %prec UMINUS
6830@end group
6831@end example
6832
91d2c560 6833@ifset defaultprec
39a06c25
PE
6834If you forget to append @code{%prec UMINUS} to the rule for unary
6835minus, Bison silently assumes that minus has its usual precedence.
6836This kind of problem can be tricky to debug, since one typically
6837discovers the mistake only by testing the code.
6838
22fccf95 6839The @code{%no-default-prec;} declaration makes it easier to discover
39a06c25
PE
6840this kind of problem systematically. It causes rules that lack a
6841@code{%prec} modifier to have no precedence, even if the last terminal
6842symbol mentioned in their components has a declared precedence.
6843
22fccf95 6844If @code{%no-default-prec;} is in effect, you must specify @code{%prec}
39a06c25
PE
6845for all rules that participate in precedence conflict resolution.
6846Then you will see any shift/reduce conflict until you tell Bison how
6847to resolve it, either by changing your grammar or by adding an
6848explicit precedence. This will probably add declarations to the
6849grammar, but it helps to protect against incorrect rule precedences.
6850
22fccf95
PE
6851The effect of @code{%no-default-prec;} can be reversed by giving
6852@code{%default-prec;}, which is the default.
91d2c560 6853@end ifset
39a06c25 6854
342b8b6e 6855@node Parser States
bfa74976
RS
6856@section Parser States
6857@cindex finite-state machine
6858@cindex parser state
6859@cindex state (of parser)
6860
6861The function @code{yyparse} is implemented using a finite-state machine.
6862The values pushed on the parser stack are not simply token type codes; they
6863represent the entire sequence of terminal and nonterminal symbols at or
6864near the top of the stack. The current state collects all the information
6865about previous input which is relevant to deciding what to do next.
6866
742e4900
JD
6867Each time a lookahead token is read, the current parser state together
6868with the type of lookahead token are looked up in a table. This table
6869entry can say, ``Shift the lookahead token.'' In this case, it also
bfa74976
RS
6870specifies the new parser state, which is pushed onto the top of the
6871parser stack. Or it can say, ``Reduce using rule number @var{n}.''
6872This means that a certain number of tokens or groupings are taken off
6873the top of the stack, and replaced by one grouping. In other words,
6874that number of states are popped from the stack, and one new state is
6875pushed.
6876
742e4900 6877There is one other alternative: the table can say that the lookahead token
bfa74976
RS
6878is erroneous in the current state. This causes error processing to begin
6879(@pxref{Error Recovery}).
6880
342b8b6e 6881@node Reduce/Reduce
bfa74976
RS
6882@section Reduce/Reduce Conflicts
6883@cindex reduce/reduce conflict
6884@cindex conflicts, reduce/reduce
6885
6886A reduce/reduce conflict occurs if there are two or more rules that apply
6887to the same sequence of input. This usually indicates a serious error
6888in the grammar.
6889
6890For example, here is an erroneous attempt to define a sequence
6891of zero or more @code{word} groupings.
6892
6893@example
6894sequence: /* empty */
6895 @{ printf ("empty sequence\n"); @}
6896 | maybeword
6897 | sequence word
6898 @{ printf ("added word %s\n", $2); @}
6899 ;
6900
6901maybeword: /* empty */
6902 @{ printf ("empty maybeword\n"); @}
6903 | word
6904 @{ printf ("single word %s\n", $1); @}
6905 ;
6906@end example
6907
6908@noindent
6909The error is an ambiguity: there is more than one way to parse a single
6910@code{word} into a @code{sequence}. It could be reduced to a
6911@code{maybeword} and then into a @code{sequence} via the second rule.
6912Alternatively, nothing-at-all could be reduced into a @code{sequence}
6913via the first rule, and this could be combined with the @code{word}
6914using the third rule for @code{sequence}.
6915
6916There is also more than one way to reduce nothing-at-all into a
6917@code{sequence}. This can be done directly via the first rule,
6918or indirectly via @code{maybeword} and then the second rule.
6919
6920You might think that this is a distinction without a difference, because it
6921does not change whether any particular input is valid or not. But it does
6922affect which actions are run. One parsing order runs the second rule's
6923action; the other runs the first rule's action and the third rule's action.
6924In this example, the output of the program changes.
6925
6926Bison resolves a reduce/reduce conflict by choosing to use the rule that
6927appears first in the grammar, but it is very risky to rely on this. Every
6928reduce/reduce conflict must be studied and usually eliminated. Here is the
6929proper way to define @code{sequence}:
6930
6931@example
6932sequence: /* empty */
6933 @{ printf ("empty sequence\n"); @}
6934 | sequence word
6935 @{ printf ("added word %s\n", $2); @}
6936 ;
6937@end example
6938
6939Here is another common error that yields a reduce/reduce conflict:
6940
6941@example
6942sequence: /* empty */
6943 | sequence words
6944 | sequence redirects
6945 ;
6946
6947words: /* empty */
6948 | words word
6949 ;
6950
6951redirects:/* empty */
6952 | redirects redirect
6953 ;
6954@end example
6955
6956@noindent
6957The intention here is to define a sequence which can contain either
6958@code{word} or @code{redirect} groupings. The individual definitions of
6959@code{sequence}, @code{words} and @code{redirects} are error-free, but the
6960three together make a subtle ambiguity: even an empty input can be parsed
6961in infinitely many ways!
6962
6963Consider: nothing-at-all could be a @code{words}. Or it could be two
6964@code{words} in a row, or three, or any number. It could equally well be a
6965@code{redirects}, or two, or any number. Or it could be a @code{words}
6966followed by three @code{redirects} and another @code{words}. And so on.
6967
6968Here are two ways to correct these rules. First, to make it a single level
6969of sequence:
6970
6971@example
6972sequence: /* empty */
6973 | sequence word
6974 | sequence redirect
6975 ;
6976@end example
6977
6978Second, to prevent either a @code{words} or a @code{redirects}
6979from being empty:
6980
6981@example
6982sequence: /* empty */
6983 | sequence words
6984 | sequence redirects
6985 ;
6986
6987words: word
6988 | words word
6989 ;
6990
6991redirects:redirect
6992 | redirects redirect
6993 ;
6994@end example
6995
342b8b6e 6996@node Mystery Conflicts
bfa74976
RS
6997@section Mysterious Reduce/Reduce Conflicts
6998
6999Sometimes reduce/reduce conflicts can occur that don't look warranted.
7000Here is an example:
7001
7002@example
7003@group
7004%token ID
7005
7006%%
7007def: param_spec return_spec ','
7008 ;
7009param_spec:
7010 type
7011 | name_list ':' type
7012 ;
7013@end group
7014@group
7015return_spec:
7016 type
7017 | name ':' type
7018 ;
7019@end group
7020@group
7021type: ID
7022 ;
7023@end group
7024@group
7025name: ID
7026 ;
7027name_list:
7028 name
7029 | name ',' name_list
7030 ;
7031@end group
7032@end example
7033
7034It would seem that this grammar can be parsed with only a single token
742e4900 7035of lookahead: when a @code{param_spec} is being read, an @code{ID} is
bfa74976 7036a @code{name} if a comma or colon follows, or a @code{type} if another
35430378 7037@code{ID} follows. In other words, this grammar is LR(1).
bfa74976 7038
35430378
JD
7039@cindex LR(1)
7040@cindex LALR(1)
34a6c2d1 7041However, for historical reasons, Bison cannot by default handle all
35430378 7042LR(1) grammars.
34a6c2d1
JD
7043In this grammar, two contexts, that after an @code{ID} at the beginning
7044of a @code{param_spec} and likewise at the beginning of a
7045@code{return_spec}, are similar enough that Bison assumes they are the
7046same.
7047They appear similar because the same set of rules would be
bfa74976
RS
7048active---the rule for reducing to a @code{name} and that for reducing to
7049a @code{type}. Bison is unable to determine at that stage of processing
742e4900 7050that the rules would require different lookahead tokens in the two
bfa74976
RS
7051contexts, so it makes a single parser state for them both. Combining
7052the two contexts causes a conflict later. In parser terminology, this
35430378 7053occurrence means that the grammar is not LALR(1).
bfa74976 7054
34a6c2d1 7055For many practical grammars (specifically those that fall into the
2f4518a1
JD
7056non-LR(1) class), the limitations of LALR(1) result in difficulties
7057beyond just mysterious reduce/reduce conflicts. The best way to fix
7058all these problems is to select a different parser table generation
7059algorithm. Either IELR(1) or canonical LR(1) would suffice, but the
7060former is more efficient and easier to debug during development.
7061@xref{%define Summary,,lr.type}, for details. (Bison's IELR(1) and
7062canonical LR(1) implementations are experimental. More user feedback
7063will help to stabilize them.)
34a6c2d1 7064
35430378 7065If you instead wish to work around LALR(1)'s limitations, you
34a6c2d1
JD
7066can often fix a mysterious conflict by identifying the two parser states
7067that are being confused, and adding something to make them look
7068distinct. In the above example, adding one rule to
bfa74976
RS
7069@code{return_spec} as follows makes the problem go away:
7070
7071@example
7072@group
7073%token BOGUS
7074@dots{}
7075%%
7076@dots{}
7077return_spec:
7078 type
7079 | name ':' type
7080 /* This rule is never used. */
7081 | ID BOGUS
7082 ;
7083@end group
7084@end example
7085
7086This corrects the problem because it introduces the possibility of an
7087additional active rule in the context after the @code{ID} at the beginning of
7088@code{return_spec}. This rule is not active in the corresponding context
7089in a @code{param_spec}, so the two contexts receive distinct parser states.
7090As long as the token @code{BOGUS} is never generated by @code{yylex},
7091the added rule cannot alter the way actual input is parsed.
7092
7093In this particular example, there is another way to solve the problem:
7094rewrite the rule for @code{return_spec} to use @code{ID} directly
7095instead of via @code{name}. This also causes the two confusing
7096contexts to have different sets of active rules, because the one for
7097@code{return_spec} activates the altered rule for @code{return_spec}
7098rather than the one for @code{name}.
7099
7100@example
7101param_spec:
7102 type
7103 | name_list ':' type
7104 ;
7105return_spec:
7106 type
7107 | ID ':' type
7108 ;
7109@end example
7110
35430378 7111For a more detailed exposition of LALR(1) parsers and parser
e054b190
PE
7112generators, please see:
7113Frank DeRemer and Thomas Pennello, Efficient Computation of
35430378 7114LALR(1) Look-Ahead Sets, @cite{ACM Transactions on
e054b190
PE
7115Programming Languages and Systems}, Vol.@: 4, No.@: 4 (October 1982),
7116pp.@: 615--649 @uref{http://doi.acm.org/10.1145/69622.357187}.
7117
fae437e8 7118@node Generalized LR Parsing
35430378
JD
7119@section Generalized LR (GLR) Parsing
7120@cindex GLR parsing
7121@cindex generalized LR (GLR) parsing
676385e2 7122@cindex ambiguous grammars
9d9b8b70 7123@cindex nondeterministic parsing
676385e2 7124
fae437e8
AD
7125Bison produces @emph{deterministic} parsers that choose uniquely
7126when to reduce and which reduction to apply
742e4900 7127based on a summary of the preceding input and on one extra token of lookahead.
676385e2
PH
7128As a result, normal Bison handles a proper subset of the family of
7129context-free languages.
fae437e8 7130Ambiguous grammars, since they have strings with more than one possible
676385e2
PH
7131sequence of reductions cannot have deterministic parsers in this sense.
7132The same is true of languages that require more than one symbol of
742e4900 7133lookahead, since the parser lacks the information necessary to make a
676385e2 7134decision at the point it must be made in a shift-reduce parser.
fae437e8 7135Finally, as previously mentioned (@pxref{Mystery Conflicts}),
34a6c2d1 7136there are languages where Bison's default choice of how to
676385e2
PH
7137summarize the input seen so far loses necessary information.
7138
7139When you use the @samp{%glr-parser} declaration in your grammar file,
7140Bison generates a parser that uses a different algorithm, called
35430378 7141Generalized LR (or GLR). A Bison GLR
c827f760 7142parser uses the same basic
676385e2
PH
7143algorithm for parsing as an ordinary Bison parser, but behaves
7144differently in cases where there is a shift-reduce conflict that has not
fae437e8 7145been resolved by precedence rules (@pxref{Precedence}) or a
35430378 7146reduce-reduce conflict. When a GLR parser encounters such a
c827f760 7147situation, it
fae437e8 7148effectively @emph{splits} into a several parsers, one for each possible
676385e2
PH
7149shift or reduction. These parsers then proceed as usual, consuming
7150tokens in lock-step. Some of the stacks may encounter other conflicts
fae437e8 7151and split further, with the result that instead of a sequence of states,
35430378 7152a Bison GLR parsing stack is what is in effect a tree of states.
676385e2
PH
7153
7154In effect, each stack represents a guess as to what the proper parse
7155is. Additional input may indicate that a guess was wrong, in which case
7156the appropriate stack silently disappears. Otherwise, the semantics
fae437e8 7157actions generated in each stack are saved, rather than being executed
676385e2 7158immediately. When a stack disappears, its saved semantic actions never
fae437e8 7159get executed. When a reduction causes two stacks to become equivalent,
676385e2
PH
7160their sets of semantic actions are both saved with the state that
7161results from the reduction. We say that two stacks are equivalent
fae437e8 7162when they both represent the same sequence of states,
676385e2
PH
7163and each pair of corresponding states represents a
7164grammar symbol that produces the same segment of the input token
7165stream.
7166
7167Whenever the parser makes a transition from having multiple
34a6c2d1 7168states to having one, it reverts to the normal deterministic parsing
676385e2
PH
7169algorithm, after resolving and executing the saved-up actions.
7170At this transition, some of the states on the stack will have semantic
7171values that are sets (actually multisets) of possible actions. The
7172parser tries to pick one of the actions by first finding one whose rule
7173has the highest dynamic precedence, as set by the @samp{%dprec}
fae437e8 7174declaration. Otherwise, if the alternative actions are not ordered by
676385e2 7175precedence, but there the same merging function is declared for both
fae437e8 7176rules by the @samp{%merge} declaration,
676385e2
PH
7177Bison resolves and evaluates both and then calls the merge function on
7178the result. Otherwise, it reports an ambiguity.
7179
35430378
JD
7180It is possible to use a data structure for the GLR parsing tree that
7181permits the processing of any LR(1) grammar in linear time (in the
c827f760 7182size of the input), any unambiguous (not necessarily
35430378 7183LR(1)) grammar in
fae437e8 7184quadratic worst-case time, and any general (possibly ambiguous)
676385e2
PH
7185context-free grammar in cubic worst-case time. However, Bison currently
7186uses a simpler data structure that requires time proportional to the
7187length of the input times the maximum number of stacks required for any
9d9b8b70 7188prefix of the input. Thus, really ambiguous or nondeterministic
676385e2
PH
7189grammars can require exponential time and space to process. Such badly
7190behaving examples, however, are not generally of practical interest.
9d9b8b70 7191Usually, nondeterminism in a grammar is local---the parser is ``in
676385e2 7192doubt'' only for a few tokens at a time. Therefore, the current data
35430378 7193structure should generally be adequate. On LR(1) portions of a
34a6c2d1 7194grammar, in particular, it is only slightly slower than with the
35430378 7195deterministic LR(1) Bison parser.
676385e2 7196
35430378 7197For a more detailed exposition of GLR parsers, please see: Elizabeth
f6481e2f 7198Scott, Adrian Johnstone and Shamsa Sadaf Hussain, Tomita-Style
35430378 7199Generalised LR Parsers, Royal Holloway, University of
f6481e2f
PE
7200London, Department of Computer Science, TR-00-12,
7201@uref{http://www.cs.rhul.ac.uk/research/languages/publications/tomita_style_1.ps},
7202(2000-12-24).
7203
1a059451
PE
7204@node Memory Management
7205@section Memory Management, and How to Avoid Memory Exhaustion
7206@cindex memory exhaustion
7207@cindex memory management
bfa74976
RS
7208@cindex stack overflow
7209@cindex parser stack overflow
7210@cindex overflow of parser stack
7211
1a059451 7212The Bison parser stack can run out of memory if too many tokens are shifted and
bfa74976 7213not reduced. When this happens, the parser function @code{yyparse}
1a059451 7214calls @code{yyerror} and then returns 2.
bfa74976 7215
c827f760 7216Because Bison parsers have growing stacks, hitting the upper limit
d1a1114f
AD
7217usually results from using a right recursion instead of a left
7218recursion, @xref{Recursion, ,Recursive Rules}.
7219
bfa74976
RS
7220@vindex YYMAXDEPTH
7221By defining the macro @code{YYMAXDEPTH}, you can control how deep the
1a059451 7222parser stack can become before memory is exhausted. Define the
bfa74976
RS
7223macro with a value that is an integer. This value is the maximum number
7224of tokens that can be shifted (and not reduced) before overflow.
bfa74976
RS
7225
7226The stack space allowed is not necessarily allocated. If you specify a
1a059451 7227large value for @code{YYMAXDEPTH}, the parser normally allocates a small
bfa74976
RS
7228stack at first, and then makes it bigger by stages as needed. This
7229increasing allocation happens automatically and silently. Therefore,
7230you do not need to make @code{YYMAXDEPTH} painfully small merely to save
7231space for ordinary inputs that do not need much stack.
7232
d7e14fc0
PE
7233However, do not allow @code{YYMAXDEPTH} to be a value so large that
7234arithmetic overflow could occur when calculating the size of the stack
7235space. Also, do not allow @code{YYMAXDEPTH} to be less than
7236@code{YYINITDEPTH}.
7237
bfa74976
RS
7238@cindex default stack limit
7239The default value of @code{YYMAXDEPTH}, if you do not define it, is
724010000.
7241
7242@vindex YYINITDEPTH
7243You can control how much stack is allocated initially by defining the
34a6c2d1
JD
7244macro @code{YYINITDEPTH} to a positive integer. For the deterministic
7245parser in C, this value must be a compile-time constant
d7e14fc0
PE
7246unless you are assuming C99 or some other target language or compiler
7247that allows variable-length arrays. The default is 200.
7248
1a059451 7249Do not allow @code{YYINITDEPTH} to be greater than @code{YYMAXDEPTH}.
bfa74976 7250
d1a1114f 7251@c FIXME: C++ output.
c781580d 7252Because of semantic differences between C and C++, the deterministic
34a6c2d1 7253parsers in C produced by Bison cannot grow when compiled
1a059451
PE
7254by C++ compilers. In this precise case (compiling a C parser as C++) you are
7255suggested to grow @code{YYINITDEPTH}. The Bison maintainers hope to fix
7256this deficiency in a future release.
d1a1114f 7257
342b8b6e 7258@node Error Recovery
bfa74976
RS
7259@chapter Error Recovery
7260@cindex error recovery
7261@cindex recovery from errors
7262
6e649e65 7263It is not usually acceptable to have a program terminate on a syntax
bfa74976
RS
7264error. For example, a compiler should recover sufficiently to parse the
7265rest of the input file and check it for errors; a calculator should accept
7266another expression.
7267
7268In a simple interactive command parser where each input is one line, it may
7269be sufficient to allow @code{yyparse} to return 1 on error and have the
7270caller ignore the rest of the input line when that happens (and then call
7271@code{yyparse} again). But this is inadequate for a compiler, because it
7272forgets all the syntactic context leading up to the error. A syntax error
7273deep within a function in the compiler input should not cause the compiler
7274to treat the following line like the beginning of a source file.
7275
7276@findex error
7277You can define how to recover from a syntax error by writing rules to
7278recognize the special token @code{error}. This is a terminal symbol that
7279is always defined (you need not declare it) and reserved for error
7280handling. The Bison parser generates an @code{error} token whenever a
7281syntax error happens; if you have provided a rule to recognize this token
13863333 7282in the current context, the parse can continue.
bfa74976
RS
7283
7284For example:
7285
7286@example
7287stmnts: /* empty string */
7288 | stmnts '\n'
7289 | stmnts exp '\n'
7290 | stmnts error '\n'
7291@end example
7292
7293The fourth rule in this example says that an error followed by a newline
7294makes a valid addition to any @code{stmnts}.
7295
7296What happens if a syntax error occurs in the middle of an @code{exp}? The
7297error recovery rule, interpreted strictly, applies to the precise sequence
7298of a @code{stmnts}, an @code{error} and a newline. If an error occurs in
7299the middle of an @code{exp}, there will probably be some additional tokens
7300and subexpressions on the stack after the last @code{stmnts}, and there
7301will be tokens to read before the next newline. So the rule is not
7302applicable in the ordinary way.
7303
7304But Bison can force the situation to fit the rule, by discarding part of
72f889cc
AD
7305the semantic context and part of the input. First it discards states
7306and objects from the stack until it gets back to a state in which the
bfa74976 7307@code{error} token is acceptable. (This means that the subexpressions
72f889cc
AD
7308already parsed are discarded, back to the last complete @code{stmnts}.)
7309At this point the @code{error} token can be shifted. Then, if the old
742e4900 7310lookahead token is not acceptable to be shifted next, the parser reads
bfa74976 7311tokens and discards them until it finds a token which is acceptable. In
72f889cc
AD
7312this example, Bison reads and discards input until the next newline so
7313that the fourth rule can apply. Note that discarded symbols are
7314possible sources of memory leaks, see @ref{Destructor Decl, , Freeing
7315Discarded Symbols}, for a means to reclaim this memory.
bfa74976
RS
7316
7317The choice of error rules in the grammar is a choice of strategies for
7318error recovery. A simple and useful strategy is simply to skip the rest of
7319the current input line or current statement if an error is detected:
7320
7321@example
72d2299c 7322stmnt: error ';' /* On error, skip until ';' is read. */
bfa74976
RS
7323@end example
7324
7325It is also useful to recover to the matching close-delimiter of an
7326opening-delimiter that has already been parsed. Otherwise the
7327close-delimiter will probably appear to be unmatched, and generate another,
7328spurious error message:
7329
7330@example
7331primary: '(' expr ')'
7332 | '(' error ')'
7333 @dots{}
7334 ;
7335@end example
7336
7337Error recovery strategies are necessarily guesses. When they guess wrong,
7338one syntax error often leads to another. In the above example, the error
7339recovery rule guesses that an error is due to bad input within one
7340@code{stmnt}. Suppose that instead a spurious semicolon is inserted in the
7341middle of a valid @code{stmnt}. After the error recovery rule recovers
7342from the first error, another syntax error will be found straightaway,
7343since the text following the spurious semicolon is also an invalid
7344@code{stmnt}.
7345
7346To prevent an outpouring of error messages, the parser will output no error
7347message for another syntax error that happens shortly after the first; only
7348after three consecutive input tokens have been successfully shifted will
7349error messages resume.
7350
7351Note that rules which accept the @code{error} token may have actions, just
7352as any other rules can.
7353
7354@findex yyerrok
7355You can make error messages resume immediately by using the macro
7356@code{yyerrok} in an action. If you do this in the error rule's action, no
7357error messages will be suppressed. This macro requires no arguments;
7358@samp{yyerrok;} is a valid C statement.
7359
7360@findex yyclearin
742e4900 7361The previous lookahead token is reanalyzed immediately after an error. If
bfa74976
RS
7362this is unacceptable, then the macro @code{yyclearin} may be used to clear
7363this token. Write the statement @samp{yyclearin;} in the error rule's
7364action.
32c29292 7365@xref{Action Features, ,Special Features for Use in Actions}.
bfa74976 7366
6e649e65 7367For example, suppose that on a syntax error, an error handling routine is
bfa74976
RS
7368called that advances the input stream to some point where parsing should
7369once again commence. The next symbol returned by the lexical scanner is
742e4900 7370probably correct. The previous lookahead token ought to be discarded
bfa74976
RS
7371with @samp{yyclearin;}.
7372
7373@vindex YYRECOVERING
02103984
PE
7374The expression @code{YYRECOVERING ()} yields 1 when the parser
7375is recovering from a syntax error, and 0 otherwise.
7376Syntax error diagnostics are suppressed while recovering from a syntax
7377error.
bfa74976 7378
342b8b6e 7379@node Context Dependency
bfa74976
RS
7380@chapter Handling Context Dependencies
7381
7382The Bison paradigm is to parse tokens first, then group them into larger
7383syntactic units. In many languages, the meaning of a token is affected by
7384its context. Although this violates the Bison paradigm, certain techniques
7385(known as @dfn{kludges}) may enable you to write Bison parsers for such
7386languages.
7387
7388@menu
7389* Semantic Tokens:: Token parsing can depend on the semantic context.
7390* Lexical Tie-ins:: Token parsing can depend on the syntactic context.
7391* Tie-in Recovery:: Lexical tie-ins have implications for how
7392 error recovery rules must be written.
7393@end menu
7394
7395(Actually, ``kludge'' means any technique that gets its job done but is
7396neither clean nor robust.)
7397
342b8b6e 7398@node Semantic Tokens
bfa74976
RS
7399@section Semantic Info in Token Types
7400
7401The C language has a context dependency: the way an identifier is used
7402depends on what its current meaning is. For example, consider this:
7403
7404@example
7405foo (x);
7406@end example
7407
7408This looks like a function call statement, but if @code{foo} is a typedef
7409name, then this is actually a declaration of @code{x}. How can a Bison
7410parser for C decide how to parse this input?
7411
35430378 7412The method used in GNU C is to have two different token types,
bfa74976
RS
7413@code{IDENTIFIER} and @code{TYPENAME}. When @code{yylex} finds an
7414identifier, it looks up the current declaration of the identifier in order
7415to decide which token type to return: @code{TYPENAME} if the identifier is
7416declared as a typedef, @code{IDENTIFIER} otherwise.
7417
7418The grammar rules can then express the context dependency by the choice of
7419token type to recognize. @code{IDENTIFIER} is accepted as an expression,
7420but @code{TYPENAME} is not. @code{TYPENAME} can start a declaration, but
7421@code{IDENTIFIER} cannot. In contexts where the meaning of the identifier
7422is @emph{not} significant, such as in declarations that can shadow a
7423typedef name, either @code{TYPENAME} or @code{IDENTIFIER} is
7424accepted---there is one rule for each of the two token types.
7425
7426This technique is simple to use if the decision of which kinds of
7427identifiers to allow is made at a place close to where the identifier is
7428parsed. But in C this is not always so: C allows a declaration to
7429redeclare a typedef name provided an explicit type has been specified
7430earlier:
7431
7432@example
3a4f411f
PE
7433typedef int foo, bar;
7434int baz (void)
7435@{
7436 static bar (bar); /* @r{redeclare @code{bar} as static variable} */
7437 extern foo foo (foo); /* @r{redeclare @code{foo} as function} */
7438 return foo (bar);
7439@}
bfa74976
RS
7440@end example
7441
7442Unfortunately, the name being declared is separated from the declaration
7443construct itself by a complicated syntactic structure---the ``declarator''.
7444
9ecbd125 7445As a result, part of the Bison parser for C needs to be duplicated, with
14ded682
AD
7446all the nonterminal names changed: once for parsing a declaration in
7447which a typedef name can be redefined, and once for parsing a
7448declaration in which that can't be done. Here is a part of the
7449duplication, with actions omitted for brevity:
bfa74976
RS
7450
7451@example
7452initdcl:
7453 declarator maybeasm '='
7454 init
7455 | declarator maybeasm
7456 ;
7457
7458notype_initdcl:
7459 notype_declarator maybeasm '='
7460 init
7461 | notype_declarator maybeasm
7462 ;
7463@end example
7464
7465@noindent
7466Here @code{initdcl} can redeclare a typedef name, but @code{notype_initdcl}
7467cannot. The distinction between @code{declarator} and
7468@code{notype_declarator} is the same sort of thing.
7469
7470There is some similarity between this technique and a lexical tie-in
7471(described next), in that information which alters the lexical analysis is
7472changed during parsing by other parts of the program. The difference is
7473here the information is global, and is used for other purposes in the
7474program. A true lexical tie-in has a special-purpose flag controlled by
7475the syntactic context.
7476
342b8b6e 7477@node Lexical Tie-ins
bfa74976
RS
7478@section Lexical Tie-ins
7479@cindex lexical tie-in
7480
7481One way to handle context-dependency is the @dfn{lexical tie-in}: a flag
7482which is set by Bison actions, whose purpose is to alter the way tokens are
7483parsed.
7484
7485For example, suppose we have a language vaguely like C, but with a special
7486construct @samp{hex (@var{hex-expr})}. After the keyword @code{hex} comes
7487an expression in parentheses in which all integers are hexadecimal. In
7488particular, the token @samp{a1b} must be treated as an integer rather than
7489as an identifier if it appears in that context. Here is how you can do it:
7490
7491@example
7492@group
7493%@{
38a92d50
PE
7494 int hexflag;
7495 int yylex (void);
7496 void yyerror (char const *);
bfa74976
RS
7497%@}
7498%%
7499@dots{}
7500@end group
7501@group
7502expr: IDENTIFIER
7503 | constant
7504 | HEX '('
7505 @{ hexflag = 1; @}
7506 expr ')'
7507 @{ hexflag = 0;
7508 $$ = $4; @}
7509 | expr '+' expr
7510 @{ $$ = make_sum ($1, $3); @}
7511 @dots{}
7512 ;
7513@end group
7514
7515@group
7516constant:
7517 INTEGER
7518 | STRING
7519 ;
7520@end group
7521@end example
7522
7523@noindent
7524Here we assume that @code{yylex} looks at the value of @code{hexflag}; when
7525it is nonzero, all integers are parsed in hexadecimal, and tokens starting
7526with letters are parsed as integers if possible.
7527
9913d6e4
JD
7528The declaration of @code{hexflag} shown in the prologue of the grammar
7529file is needed to make it accessible to the actions (@pxref{Prologue,
7530,The Prologue}). You must also write the code in @code{yylex} to obey
7531the flag.
bfa74976 7532
342b8b6e 7533@node Tie-in Recovery
bfa74976
RS
7534@section Lexical Tie-ins and Error Recovery
7535
7536Lexical tie-ins make strict demands on any error recovery rules you have.
7537@xref{Error Recovery}.
7538
7539The reason for this is that the purpose of an error recovery rule is to
7540abort the parsing of one construct and resume in some larger construct.
7541For example, in C-like languages, a typical error recovery rule is to skip
7542tokens until the next semicolon, and then start a new statement, like this:
7543
7544@example
7545stmt: expr ';'
7546 | IF '(' expr ')' stmt @{ @dots{} @}
7547 @dots{}
7548 error ';'
7549 @{ hexflag = 0; @}
7550 ;
7551@end example
7552
7553If there is a syntax error in the middle of a @samp{hex (@var{expr})}
7554construct, this error rule will apply, and then the action for the
7555completed @samp{hex (@var{expr})} will never run. So @code{hexflag} would
7556remain set for the entire rest of the input, or until the next @code{hex}
7557keyword, causing identifiers to be misinterpreted as integers.
7558
7559To avoid this problem the error recovery rule itself clears @code{hexflag}.
7560
7561There may also be an error recovery rule that works within expressions.
7562For example, there could be a rule which applies within parentheses
7563and skips to the close-parenthesis:
7564
7565@example
7566@group
7567expr: @dots{}
7568 | '(' expr ')'
7569 @{ $$ = $2; @}
7570 | '(' error ')'
7571 @dots{}
7572@end group
7573@end example
7574
7575If this rule acts within the @code{hex} construct, it is not going to abort
7576that construct (since it applies to an inner level of parentheses within
7577the construct). Therefore, it should not clear the flag: the rest of
7578the @code{hex} construct should be parsed with the flag still in effect.
7579
7580What if there is an error recovery rule which might abort out of the
7581@code{hex} construct or might not, depending on circumstances? There is no
7582way you can write the action to determine whether a @code{hex} construct is
7583being aborted or not. So if you are using a lexical tie-in, you had better
7584make sure your error recovery rules are not of this kind. Each rule must
7585be such that you can be sure that it always will, or always won't, have to
7586clear the flag.
7587
ec3bc396
AD
7588@c ================================================== Debugging Your Parser
7589
342b8b6e 7590@node Debugging
bfa74976 7591@chapter Debugging Your Parser
ec3bc396
AD
7592
7593Developing a parser can be a challenge, especially if you don't
7594understand the algorithm (@pxref{Algorithm, ,The Bison Parser
7595Algorithm}). Even so, sometimes a detailed description of the automaton
7596can help (@pxref{Understanding, , Understanding Your Parser}), or
7597tracing the execution of the parser can give some insight on why it
7598behaves improperly (@pxref{Tracing, , Tracing Your Parser}).
7599
7600@menu
7601* Understanding:: Understanding the structure of your parser.
7602* Tracing:: Tracing the execution of your parser.
7603@end menu
7604
7605@node Understanding
7606@section Understanding Your Parser
7607
7608As documented elsewhere (@pxref{Algorithm, ,The Bison Parser Algorithm})
7609Bison parsers are @dfn{shift/reduce automata}. In some cases (much more
7610frequent than one would hope), looking at this automaton is required to
7611tune or simply fix a parser. Bison provides two different
35fe0834 7612representation of it, either textually or graphically (as a DOT file).
ec3bc396
AD
7613
7614The textual file is generated when the options @option{--report} or
7615@option{--verbose} are specified, see @xref{Invocation, , Invoking
7616Bison}. Its name is made by removing @samp{.tab.c} or @samp{.c} from
9913d6e4
JD
7617the parser implementation file name, and adding @samp{.output}
7618instead. Therefore, if the grammar file is @file{foo.y}, then the
7619parser implementation file is called @file{foo.tab.c} by default. As
7620a consequence, the verbose output file is called @file{foo.output}.
ec3bc396
AD
7621
7622The following grammar file, @file{calc.y}, will be used in the sequel:
7623
7624@example
7625%token NUM STR
7626%left '+' '-'
7627%left '*'
7628%%
7629exp: exp '+' exp
7630 | exp '-' exp
7631 | exp '*' exp
7632 | exp '/' exp
7633 | NUM
7634 ;
7635useless: STR;
7636%%
7637@end example
7638
88bce5a2
AD
7639@command{bison} reports:
7640
7641@example
379261b3
JD
7642calc.y: warning: 1 nonterminal useless in grammar
7643calc.y: warning: 1 rule useless in grammar
cff03fb2
JD
7644calc.y:11.1-7: warning: nonterminal useless in grammar: useless
7645calc.y:11.10-12: warning: rule useless in grammar: useless: STR
5a99098d 7646calc.y: conflicts: 7 shift/reduce
88bce5a2
AD
7647@end example
7648
7649When given @option{--report=state}, in addition to @file{calc.tab.c}, it
7650creates a file @file{calc.output} with contents detailed below. The
7651order of the output and the exact presentation might vary, but the
7652interpretation is the same.
ec3bc396
AD
7653
7654The first section includes details on conflicts that were solved thanks
7655to precedence and/or associativity:
7656
7657@example
7658Conflict in state 8 between rule 2 and token '+' resolved as reduce.
7659Conflict in state 8 between rule 2 and token '-' resolved as reduce.
7660Conflict in state 8 between rule 2 and token '*' resolved as shift.
7661@exdent @dots{}
7662@end example
7663
7664@noindent
7665The next section lists states that still have conflicts.
7666
7667@example
5a99098d
PE
7668State 8 conflicts: 1 shift/reduce
7669State 9 conflicts: 1 shift/reduce
7670State 10 conflicts: 1 shift/reduce
7671State 11 conflicts: 4 shift/reduce
ec3bc396
AD
7672@end example
7673
7674@noindent
7675@cindex token, useless
7676@cindex useless token
7677@cindex nonterminal, useless
7678@cindex useless nonterminal
7679@cindex rule, useless
7680@cindex useless rule
7681The next section reports useless tokens, nonterminal and rules. Useless
7682nonterminals and rules are removed in order to produce a smaller parser,
7683but useless tokens are preserved, since they might be used by the
d80fb37a 7684scanner (note the difference between ``useless'' and ``unused''
ec3bc396
AD
7685below):
7686
7687@example
d80fb37a 7688Nonterminals useless in grammar:
ec3bc396
AD
7689 useless
7690
d80fb37a 7691Terminals unused in grammar:
ec3bc396
AD
7692 STR
7693
cff03fb2 7694Rules useless in grammar:
ec3bc396
AD
7695#6 useless: STR;
7696@end example
7697
7698@noindent
7699The next section reproduces the exact grammar that Bison used:
7700
7701@example
7702Grammar
7703
7704 Number, Line, Rule
88bce5a2 7705 0 5 $accept -> exp $end
ec3bc396
AD
7706 1 5 exp -> exp '+' exp
7707 2 6 exp -> exp '-' exp
7708 3 7 exp -> exp '*' exp
7709 4 8 exp -> exp '/' exp
7710 5 9 exp -> NUM
7711@end example
7712
7713@noindent
7714and reports the uses of the symbols:
7715
7716@example
7717Terminals, with rules where they appear
7718
88bce5a2 7719$end (0) 0
ec3bc396
AD
7720'*' (42) 3
7721'+' (43) 1
7722'-' (45) 2
7723'/' (47) 4
7724error (256)
7725NUM (258) 5
7726
7727Nonterminals, with rules where they appear
7728
88bce5a2 7729$accept (8)
ec3bc396
AD
7730 on left: 0
7731exp (9)
7732 on left: 1 2 3 4 5, on right: 0 1 2 3 4
7733@end example
7734
7735@noindent
7736@cindex item
7737@cindex pointed rule
7738@cindex rule, pointed
7739Bison then proceeds onto the automaton itself, describing each state
7740with it set of @dfn{items}, also known as @dfn{pointed rules}. Each
7741item is a production rule together with a point (marked by @samp{.})
7742that the input cursor.
7743
7744@example
7745state 0
7746
88bce5a2 7747 $accept -> . exp $ (rule 0)
ec3bc396 7748
2a8d363a 7749 NUM shift, and go to state 1
ec3bc396 7750
2a8d363a 7751 exp go to state 2
ec3bc396
AD
7752@end example
7753
7754This reads as follows: ``state 0 corresponds to being at the very
7755beginning of the parsing, in the initial rule, right before the start
7756symbol (here, @code{exp}). When the parser returns to this state right
7757after having reduced a rule that produced an @code{exp}, the control
7758flow jumps to state 2. If there is no such transition on a nonterminal
742e4900 7759symbol, and the lookahead is a @code{NUM}, then this token is shifted on
ec3bc396 7760the parse stack, and the control flow jumps to state 1. Any other
742e4900 7761lookahead triggers a syntax error.''
ec3bc396
AD
7762
7763@cindex core, item set
7764@cindex item set core
7765@cindex kernel, item set
7766@cindex item set core
7767Even though the only active rule in state 0 seems to be rule 0, the
742e4900 7768report lists @code{NUM} as a lookahead token because @code{NUM} can be
ec3bc396
AD
7769at the beginning of any rule deriving an @code{exp}. By default Bison
7770reports the so-called @dfn{core} or @dfn{kernel} of the item set, but if
7771you want to see more detail you can invoke @command{bison} with
7772@option{--report=itemset} to list all the items, include those that can
7773be derived:
7774
7775@example
7776state 0
7777
88bce5a2 7778 $accept -> . exp $ (rule 0)
ec3bc396
AD
7779 exp -> . exp '+' exp (rule 1)
7780 exp -> . exp '-' exp (rule 2)
7781 exp -> . exp '*' exp (rule 3)
7782 exp -> . exp '/' exp (rule 4)
7783 exp -> . NUM (rule 5)
7784
7785 NUM shift, and go to state 1
7786
7787 exp go to state 2
7788@end example
7789
7790@noindent
7791In the state 1...
7792
7793@example
7794state 1
7795
7796 exp -> NUM . (rule 5)
7797
2a8d363a 7798 $default reduce using rule 5 (exp)
ec3bc396
AD
7799@end example
7800
7801@noindent
742e4900 7802the rule 5, @samp{exp: NUM;}, is completed. Whatever the lookahead token
ec3bc396
AD
7803(@samp{$default}), the parser will reduce it. If it was coming from
7804state 0, then, after this reduction it will return to state 0, and will
7805jump to state 2 (@samp{exp: go to state 2}).
7806
7807@example
7808state 2
7809
88bce5a2 7810 $accept -> exp . $ (rule 0)
ec3bc396
AD
7811 exp -> exp . '+' exp (rule 1)
7812 exp -> exp . '-' exp (rule 2)
7813 exp -> exp . '*' exp (rule 3)
7814 exp -> exp . '/' exp (rule 4)
7815
2a8d363a
AD
7816 $ shift, and go to state 3
7817 '+' shift, and go to state 4
7818 '-' shift, and go to state 5
7819 '*' shift, and go to state 6
7820 '/' shift, and go to state 7
ec3bc396
AD
7821@end example
7822
7823@noindent
7824In state 2, the automaton can only shift a symbol. For instance,
742e4900 7825because of the item @samp{exp -> exp . '+' exp}, if the lookahead if
ec3bc396
AD
7826@samp{+}, it will be shifted on the parse stack, and the automaton
7827control will jump to state 4, corresponding to the item @samp{exp -> exp
7828'+' . exp}. Since there is no default action, any other token than
6e649e65 7829those listed above will trigger a syntax error.
ec3bc396 7830
34a6c2d1 7831@cindex accepting state
ec3bc396
AD
7832The state 3 is named the @dfn{final state}, or the @dfn{accepting
7833state}:
7834
7835@example
7836state 3
7837
88bce5a2 7838 $accept -> exp $ . (rule 0)
ec3bc396 7839
2a8d363a 7840 $default accept
ec3bc396
AD
7841@end example
7842
7843@noindent
7844the initial rule is completed (the start symbol and the end
7845of input were read), the parsing exits successfully.
7846
7847The interpretation of states 4 to 7 is straightforward, and is left to
7848the reader.
7849
7850@example
7851state 4
7852
7853 exp -> exp '+' . exp (rule 1)
7854
2a8d363a 7855 NUM shift, and go to state 1
ec3bc396 7856
2a8d363a 7857 exp go to state 8
ec3bc396
AD
7858
7859state 5
7860
7861 exp -> exp '-' . exp (rule 2)
7862
2a8d363a 7863 NUM shift, and go to state 1
ec3bc396 7864
2a8d363a 7865 exp go to state 9
ec3bc396
AD
7866
7867state 6
7868
7869 exp -> exp '*' . exp (rule 3)
7870
2a8d363a 7871 NUM shift, and go to state 1
ec3bc396 7872
2a8d363a 7873 exp go to state 10
ec3bc396
AD
7874
7875state 7
7876
7877 exp -> exp '/' . exp (rule 4)
7878
2a8d363a 7879 NUM shift, and go to state 1
ec3bc396 7880
2a8d363a 7881 exp go to state 11
ec3bc396
AD
7882@end example
7883
5a99098d
PE
7884As was announced in beginning of the report, @samp{State 8 conflicts:
78851 shift/reduce}:
ec3bc396
AD
7886
7887@example
7888state 8
7889
7890 exp -> exp . '+' exp (rule 1)
7891 exp -> exp '+' exp . (rule 1)
7892 exp -> exp . '-' exp (rule 2)
7893 exp -> exp . '*' exp (rule 3)
7894 exp -> exp . '/' exp (rule 4)
7895
2a8d363a
AD
7896 '*' shift, and go to state 6
7897 '/' shift, and go to state 7
ec3bc396 7898
2a8d363a
AD
7899 '/' [reduce using rule 1 (exp)]
7900 $default reduce using rule 1 (exp)
ec3bc396
AD
7901@end example
7902
742e4900 7903Indeed, there are two actions associated to the lookahead @samp{/}:
ec3bc396
AD
7904either shifting (and going to state 7), or reducing rule 1. The
7905conflict means that either the grammar is ambiguous, or the parser lacks
7906information to make the right decision. Indeed the grammar is
7907ambiguous, as, since we did not specify the precedence of @samp{/}, the
7908sentence @samp{NUM + NUM / NUM} can be parsed as @samp{NUM + (NUM /
7909NUM)}, which corresponds to shifting @samp{/}, or as @samp{(NUM + NUM) /
7910NUM}, which corresponds to reducing rule 1.
7911
34a6c2d1 7912Because in deterministic parsing a single decision can be made, Bison
ec3bc396
AD
7913arbitrarily chose to disable the reduction, see @ref{Shift/Reduce, ,
7914Shift/Reduce Conflicts}. Discarded actions are reported in between
7915square brackets.
7916
7917Note that all the previous states had a single possible action: either
7918shifting the next token and going to the corresponding state, or
7919reducing a single rule. In the other cases, i.e., when shifting
7920@emph{and} reducing is possible or when @emph{several} reductions are
742e4900
JD
7921possible, the lookahead is required to select the action. State 8 is
7922one such state: if the lookahead is @samp{*} or @samp{/} then the action
ec3bc396
AD
7923is shifting, otherwise the action is reducing rule 1. In other words,
7924the first two items, corresponding to rule 1, are not eligible when the
742e4900 7925lookahead token is @samp{*}, since we specified that @samp{*} has higher
8dd162d3 7926precedence than @samp{+}. More generally, some items are eligible only
742e4900
JD
7927with some set of possible lookahead tokens. When run with
7928@option{--report=lookahead}, Bison specifies these lookahead tokens:
ec3bc396
AD
7929
7930@example
7931state 8
7932
88c78747 7933 exp -> exp . '+' exp (rule 1)
ec3bc396
AD
7934 exp -> exp '+' exp . [$, '+', '-', '/'] (rule 1)
7935 exp -> exp . '-' exp (rule 2)
7936 exp -> exp . '*' exp (rule 3)
7937 exp -> exp . '/' exp (rule 4)
7938
7939 '*' shift, and go to state 6
7940 '/' shift, and go to state 7
7941
7942 '/' [reduce using rule 1 (exp)]
7943 $default reduce using rule 1 (exp)
7944@end example
7945
7946The remaining states are similar:
7947
7948@example
7949state 9
7950
7951 exp -> exp . '+' exp (rule 1)
7952 exp -> exp . '-' exp (rule 2)
7953 exp -> exp '-' exp . (rule 2)
7954 exp -> exp . '*' exp (rule 3)
7955 exp -> exp . '/' exp (rule 4)
7956
2a8d363a
AD
7957 '*' shift, and go to state 6
7958 '/' shift, and go to state 7
ec3bc396 7959
2a8d363a
AD
7960 '/' [reduce using rule 2 (exp)]
7961 $default reduce using rule 2 (exp)
ec3bc396
AD
7962
7963state 10
7964
7965 exp -> exp . '+' exp (rule 1)
7966 exp -> exp . '-' exp (rule 2)
7967 exp -> exp . '*' exp (rule 3)
7968 exp -> exp '*' exp . (rule 3)
7969 exp -> exp . '/' exp (rule 4)
7970
2a8d363a 7971 '/' shift, and go to state 7
ec3bc396 7972
2a8d363a
AD
7973 '/' [reduce using rule 3 (exp)]
7974 $default reduce using rule 3 (exp)
ec3bc396
AD
7975
7976state 11
7977
7978 exp -> exp . '+' exp (rule 1)
7979 exp -> exp . '-' exp (rule 2)
7980 exp -> exp . '*' exp (rule 3)
7981 exp -> exp . '/' exp (rule 4)
7982 exp -> exp '/' exp . (rule 4)
7983
2a8d363a
AD
7984 '+' shift, and go to state 4
7985 '-' shift, and go to state 5
7986 '*' shift, and go to state 6
7987 '/' shift, and go to state 7
ec3bc396 7988
2a8d363a
AD
7989 '+' [reduce using rule 4 (exp)]
7990 '-' [reduce using rule 4 (exp)]
7991 '*' [reduce using rule 4 (exp)]
7992 '/' [reduce using rule 4 (exp)]
7993 $default reduce using rule 4 (exp)
ec3bc396
AD
7994@end example
7995
7996@noindent
fa7e68c3
PE
7997Observe that state 11 contains conflicts not only due to the lack of
7998precedence of @samp{/} with respect to @samp{+}, @samp{-}, and
7999@samp{*}, but also because the
ec3bc396
AD
8000associativity of @samp{/} is not specified.
8001
8002
8003@node Tracing
8004@section Tracing Your Parser
bfa74976
RS
8005@findex yydebug
8006@cindex debugging
8007@cindex tracing the parser
8008
8009If a Bison grammar compiles properly but doesn't do what you want when it
8010runs, the @code{yydebug} parser-trace feature can help you figure out why.
8011
3ded9a63
AD
8012There are several means to enable compilation of trace facilities:
8013
8014@table @asis
8015@item the macro @code{YYDEBUG}
8016@findex YYDEBUG
8017Define the macro @code{YYDEBUG} to a nonzero value when you compile the
35430378 8018parser. This is compliant with POSIX Yacc. You could use
3ded9a63
AD
8019@samp{-DYYDEBUG=1} as a compiler option or you could put @samp{#define
8020YYDEBUG 1} in the prologue of the grammar file (@pxref{Prologue, , The
8021Prologue}).
8022
8023@item the option @option{-t}, @option{--debug}
8024Use the @samp{-t} option when you run Bison (@pxref{Invocation,
35430378 8025,Invoking Bison}). This is POSIX compliant too.
3ded9a63
AD
8026
8027@item the directive @samp{%debug}
8028@findex %debug
8029Add the @code{%debug} directive (@pxref{Decl Summary, ,Bison
8030Declaration Summary}). This is a Bison extension, which will prove
8031useful when Bison will output parsers for languages that don't use a
35430378 8032preprocessor. Unless POSIX and Yacc portability matter to
c827f760 8033you, this is
3ded9a63
AD
8034the preferred solution.
8035@end table
8036
8037We suggest that you always enable the debug option so that debugging is
8038always possible.
bfa74976 8039
02a81e05 8040The trace facility outputs messages with macro calls of the form
e2742e46 8041@code{YYFPRINTF (stderr, @var{format}, @var{args})} where
f57a7536 8042@var{format} and @var{args} are the usual @code{printf} format and variadic
4947ebdb
PE
8043arguments. If you define @code{YYDEBUG} to a nonzero value but do not
8044define @code{YYFPRINTF}, @code{<stdio.h>} is automatically included
9c437126 8045and @code{YYFPRINTF} is defined to @code{fprintf}.
bfa74976
RS
8046
8047Once you have compiled the program with trace facilities, the way to
8048request a trace is to store a nonzero value in the variable @code{yydebug}.
8049You can do this by making the C code do it (in @code{main}, perhaps), or
8050you can alter the value with a C debugger.
8051
8052Each step taken by the parser when @code{yydebug} is nonzero produces a
8053line or two of trace information, written on @code{stderr}. The trace
8054messages tell you these things:
8055
8056@itemize @bullet
8057@item
8058Each time the parser calls @code{yylex}, what kind of token was read.
8059
8060@item
8061Each time a token is shifted, the depth and complete contents of the
8062state stack (@pxref{Parser States}).
8063
8064@item
8065Each time a rule is reduced, which rule it is, and the complete contents
8066of the state stack afterward.
8067@end itemize
8068
8069To make sense of this information, it helps to refer to the listing file
704a47c4
AD
8070produced by the Bison @samp{-v} option (@pxref{Invocation, ,Invoking
8071Bison}). This file shows the meaning of each state in terms of
8072positions in various rules, and also what each state will do with each
8073possible input token. As you read the successive trace messages, you
8074can see that the parser is functioning according to its specification in
8075the listing file. Eventually you will arrive at the place where
8076something undesirable happens, and you will see which parts of the
8077grammar are to blame.
bfa74976 8078
9913d6e4
JD
8079The parser implementation file is a C program and you can use C
8080debuggers on it, but it's not easy to interpret what it is doing. The
8081parser function is a finite-state machine interpreter, and aside from
8082the actions it executes the same code over and over. Only the values
8083of variables show where in the grammar it is working.
bfa74976
RS
8084
8085@findex YYPRINT
8086The debugging information normally gives the token type of each token
8087read, but not its semantic value. You can optionally define a macro
8088named @code{YYPRINT} to provide a way to print the value. If you define
8089@code{YYPRINT}, it should take three arguments. The parser will pass a
8090standard I/O stream, the numeric code for the token type, and the token
8091value (from @code{yylval}).
8092
8093Here is an example of @code{YYPRINT} suitable for the multi-function
f56274a8 8094calculator (@pxref{Mfcalc Declarations, ,Declarations for @code{mfcalc}}):
bfa74976
RS
8095
8096@smallexample
38a92d50
PE
8097%@{
8098 static void print_token_value (FILE *, int, YYSTYPE);
8099 #define YYPRINT(file, type, value) print_token_value (file, type, value)
8100%@}
8101
8102@dots{} %% @dots{} %% @dots{}
bfa74976
RS
8103
8104static void
831d3c99 8105print_token_value (FILE *file, int type, YYSTYPE value)
bfa74976
RS
8106@{
8107 if (type == VAR)
d3c4e709 8108 fprintf (file, "%s", value.tptr->name);
bfa74976 8109 else if (type == NUM)
d3c4e709 8110 fprintf (file, "%d", value.val);
bfa74976
RS
8111@}
8112@end smallexample
8113
ec3bc396
AD
8114@c ================================================= Invoking Bison
8115
342b8b6e 8116@node Invocation
bfa74976
RS
8117@chapter Invoking Bison
8118@cindex invoking Bison
8119@cindex Bison invocation
8120@cindex options for invoking Bison
8121
8122The usual way to invoke Bison is as follows:
8123
8124@example
8125bison @var{infile}
8126@end example
8127
8128Here @var{infile} is the grammar file name, which usually ends in
9913d6e4
JD
8129@samp{.y}. The parser implementation file's name is made by replacing
8130the @samp{.y} with @samp{.tab.c} and removing any leading directory.
8131Thus, the @samp{bison foo.y} file name yields @file{foo.tab.c}, and
8132the @samp{bison hack/foo.y} file name yields @file{foo.tab.c}. It's
8133also possible, in case you are writing C++ code instead of C in your
8134grammar file, to name it @file{foo.ypp} or @file{foo.y++}. Then, the
8135output files will take an extension like the given one as input
8136(respectively @file{foo.tab.cpp} and @file{foo.tab.c++}). This
8137feature takes effect with all options that manipulate file names like
234a3be3
AD
8138@samp{-o} or @samp{-d}.
8139
8140For example :
8141
8142@example
8143bison -d @var{infile.yxx}
8144@end example
84163231 8145@noindent
72d2299c 8146will produce @file{infile.tab.cxx} and @file{infile.tab.hxx}, and
234a3be3
AD
8147
8148@example
b56471a6 8149bison -d -o @var{output.c++} @var{infile.y}
234a3be3 8150@end example
84163231 8151@noindent
234a3be3
AD
8152will produce @file{output.c++} and @file{outfile.h++}.
8153
35430378 8154For compatibility with POSIX, the standard Bison
397ec073
PE
8155distribution also contains a shell script called @command{yacc} that
8156invokes Bison with the @option{-y} option.
8157
bfa74976 8158@menu
13863333 8159* Bison Options:: All the options described in detail,
c827f760 8160 in alphabetical order by short options.
bfa74976 8161* Option Cross Key:: Alphabetical list of long options.
93dd49ab 8162* Yacc Library:: Yacc-compatible @code{yylex} and @code{main}.
bfa74976
RS
8163@end menu
8164
342b8b6e 8165@node Bison Options
bfa74976
RS
8166@section Bison Options
8167
8168Bison supports both traditional single-letter options and mnemonic long
8169option names. Long option names are indicated with @samp{--} instead of
8170@samp{-}. Abbreviations for option names are allowed as long as they
8171are unique. When a long option takes an argument, like
8172@samp{--file-prefix}, connect the option name and the argument with
8173@samp{=}.
8174
8175Here is a list of options that can be used with Bison, alphabetized by
8176short option. It is followed by a cross key alphabetized by long
8177option.
8178
89cab50d
AD
8179@c Please, keep this ordered as in `bison --help'.
8180@noindent
8181Operations modes:
8182@table @option
8183@item -h
8184@itemx --help
8185Print a summary of the command-line options to Bison and exit.
bfa74976 8186
89cab50d
AD
8187@item -V
8188@itemx --version
8189Print the version number of Bison and exit.
bfa74976 8190
f7ab6a50
PE
8191@item --print-localedir
8192Print the name of the directory containing locale-dependent data.
8193
a0de5091
JD
8194@item --print-datadir
8195Print the name of the directory containing skeletons and XSLT.
8196
89cab50d
AD
8197@item -y
8198@itemx --yacc
9913d6e4
JD
8199Act more like the traditional Yacc command. This can cause different
8200diagnostics to be generated, and may change behavior in other minor
8201ways. Most importantly, imitate Yacc's output file name conventions,
8202so that the parser implementation file is called @file{y.tab.c}, and
8203the other outputs are called @file{y.output} and @file{y.tab.h}.
8204Also, if generating a deterministic parser in C, generate
8205@code{#define} statements in addition to an @code{enum} to associate
8206token numbers with token names. Thus, the following shell script can
8207substitute for Yacc, and the Bison distribution contains such a script
8208for compatibility with POSIX:
bfa74976 8209
89cab50d 8210@example
397ec073 8211#! /bin/sh
26e06a21 8212bison -y "$@@"
89cab50d 8213@end example
54662697
PE
8214
8215The @option{-y}/@option{--yacc} option is intended for use with
8216traditional Yacc grammars. If your grammar uses a Bison extension
8217like @samp{%glr-parser}, Bison might not be Yacc-compatible even if
8218this option is specified.
8219
ecd1b61c
JD
8220@item -W [@var{category}]
8221@itemx --warnings[=@var{category}]
118d4978
AD
8222Output warnings falling in @var{category}. @var{category} can be one
8223of:
8224@table @code
8225@item midrule-values
8e55b3aa
JD
8226Warn about mid-rule values that are set but not used within any of the actions
8227of the parent rule.
8228For example, warn about unused @code{$2} in:
118d4978
AD
8229
8230@example
8231exp: '1' @{ $$ = 1; @} '+' exp @{ $$ = $1 + $4; @};
8232@end example
8233
8e55b3aa
JD
8234Also warn about mid-rule values that are used but not set.
8235For example, warn about unset @code{$$} in the mid-rule action in:
118d4978
AD
8236
8237@example
8238 exp: '1' @{ $1 = 1; @} '+' exp @{ $$ = $2 + $4; @};
8239@end example
8240
8241These warnings are not enabled by default since they sometimes prove to
8242be false alarms in existing grammars employing the Yacc constructs
8e55b3aa 8243@code{$0} or @code{$-@var{n}} (where @var{n} is some positive integer).
118d4978
AD
8244
8245
8246@item yacc
35430378 8247Incompatibilities with POSIX Yacc.
118d4978
AD
8248
8249@item all
8e55b3aa 8250All the warnings.
118d4978 8251@item none
8e55b3aa 8252Turn off all the warnings.
118d4978 8253@item error
8e55b3aa 8254Treat warnings as errors.
118d4978
AD
8255@end table
8256
8257A category can be turned off by prefixing its name with @samp{no-}. For
cf22447c 8258instance, @option{-Wno-yacc} will hide the warnings about
35430378 8259POSIX Yacc incompatibilities.
89cab50d
AD
8260@end table
8261
8262@noindent
8263Tuning the parser:
8264
8265@table @option
8266@item -t
8267@itemx --debug
9913d6e4
JD
8268In the parser implementation file, define the macro @code{YYDEBUG} to
82691 if it is not already defined, so that the debugging facilities are
8270compiled. @xref{Tracing, ,Tracing Your Parser}.
89cab50d 8271
e14c6831
AD
8272@item -D @var{name}[=@var{value}]
8273@itemx --define=@var{name}[=@var{value}]
c33bc800 8274@itemx -F @var{name}[=@var{value}]
34d41938
JD
8275@itemx --force-define=@var{name}[=@var{value}]
8276Each of these is equivalent to @samp{%define @var{name} "@var{value}"}
2f4518a1 8277(@pxref{%define Summary}) except that Bison processes multiple
34d41938
JD
8278definitions for the same @var{name} as follows:
8279
8280@itemize
8281@item
e3a33f7c
JD
8282Bison quietly ignores all command-line definitions for @var{name} except
8283the last.
34d41938 8284@item
e3a33f7c
JD
8285If that command-line definition is specified by a @code{-D} or
8286@code{--define}, Bison reports an error for any @code{%define}
8287definition for @var{name}.
34d41938 8288@item
e3a33f7c
JD
8289If that command-line definition is specified by a @code{-F} or
8290@code{--force-define} instead, Bison quietly ignores all @code{%define}
8291definitions for @var{name}.
8292@item
8293Otherwise, Bison reports an error if there are multiple @code{%define}
8294definitions for @var{name}.
34d41938
JD
8295@end itemize
8296
8297You should avoid using @code{-F} and @code{--force-define} in your
9913d6e4
JD
8298make files unless you are confident that it is safe to quietly ignore
8299any conflicting @code{%define} that may be added to the grammar file.
e14c6831 8300
0e021770
PE
8301@item -L @var{language}
8302@itemx --language=@var{language}
8303Specify the programming language for the generated parser, as if
8304@code{%language} was specified (@pxref{Decl Summary, , Bison Declaration
59da312b 8305Summary}). Currently supported languages include C, C++, and Java.
e6e704dc 8306@var{language} is case-insensitive.
0e021770 8307
ed4d67dc
JD
8308This option is experimental and its effect may be modified in future
8309releases.
8310
89cab50d 8311@item --locations
d8988b2f 8312Pretend that @code{%locations} was specified. @xref{Decl Summary}.
89cab50d
AD
8313
8314@item -p @var{prefix}
8315@itemx --name-prefix=@var{prefix}
02975b9a 8316Pretend that @code{%name-prefix "@var{prefix}"} was specified.
d8988b2f 8317@xref{Decl Summary}.
bfa74976
RS
8318
8319@item -l
8320@itemx --no-lines
9913d6e4
JD
8321Don't put any @code{#line} preprocessor commands in the parser
8322implementation file. Ordinarily Bison puts them in the parser
8323implementation file so that the C compiler and debuggers will
8324associate errors with your source file, the grammar file. This option
8325causes them to associate errors with the parser implementation file,
8326treating it as an independent source file in its own right.
bfa74976 8327
e6e704dc
JD
8328@item -S @var{file}
8329@itemx --skeleton=@var{file}
a7867f53 8330Specify the skeleton to use, similar to @code{%skeleton}
e6e704dc
JD
8331(@pxref{Decl Summary, , Bison Declaration Summary}).
8332
ed4d67dc
JD
8333@c You probably don't need this option unless you are developing Bison.
8334@c You should use @option{--language} if you want to specify the skeleton for a
8335@c different language, because it is clearer and because it will always
8336@c choose the correct skeleton for non-deterministic or push parsers.
e6e704dc 8337
a7867f53
JD
8338If @var{file} does not contain a @code{/}, @var{file} is the name of a skeleton
8339file in the Bison installation directory.
8340If it does, @var{file} is an absolute file name or a file name relative to the
8341current working directory.
8342This is similar to how most shells resolve commands.
8343
89cab50d
AD
8344@item -k
8345@itemx --token-table
d8988b2f 8346Pretend that @code{%token-table} was specified. @xref{Decl Summary}.
89cab50d 8347@end table
bfa74976 8348
89cab50d
AD
8349@noindent
8350Adjust the output:
bfa74976 8351
89cab50d 8352@table @option
8e55b3aa 8353@item --defines[=@var{file}]
d8988b2f 8354Pretend that @code{%defines} was specified, i.e., write an extra output
6deb4447 8355file containing macro definitions for the token type names defined in
4bfd5e4e 8356the grammar, as well as a few other declarations. @xref{Decl Summary}.
931c7513 8357
8e55b3aa
JD
8358@item -d
8359This is the same as @code{--defines} except @code{-d} does not accept a
8360@var{file} argument since POSIX Yacc requires that @code{-d} can be bundled
8361with other short options.
342b8b6e 8362
89cab50d
AD
8363@item -b @var{file-prefix}
8364@itemx --file-prefix=@var{prefix}
9c437126 8365Pretend that @code{%file-prefix} was specified, i.e., specify prefix to use
72d2299c 8366for all Bison output file names. @xref{Decl Summary}.
bfa74976 8367
ec3bc396
AD
8368@item -r @var{things}
8369@itemx --report=@var{things}
8370Write an extra output file containing verbose description of the comma
8371separated list of @var{things} among:
8372
8373@table @code
8374@item state
8375Description of the grammar, conflicts (resolved and unresolved), and
34a6c2d1 8376parser's automaton.
ec3bc396 8377
742e4900 8378@item lookahead
ec3bc396 8379Implies @code{state} and augments the description of the automaton with
742e4900 8380each rule's lookahead set.
ec3bc396
AD
8381
8382@item itemset
8383Implies @code{state} and augments the description of the automaton with
8384the full set of items for each state, instead of its core only.
8385@end table
8386
1bb2bd75
JD
8387@item --report-file=@var{file}
8388Specify the @var{file} for the verbose description.
8389
bfa74976
RS
8390@item -v
8391@itemx --verbose
9c437126 8392Pretend that @code{%verbose} was specified, i.e., write an extra output
6deb4447 8393file containing verbose descriptions of the grammar and
72d2299c 8394parser. @xref{Decl Summary}.
bfa74976 8395
fa4d969f
PE
8396@item -o @var{file}
8397@itemx --output=@var{file}
9913d6e4 8398Specify the @var{file} for the parser implementation file.
bfa74976 8399
fa4d969f 8400The other output files' names are constructed from @var{file} as
d8988b2f 8401described under the @samp{-v} and @samp{-d} options.
342b8b6e 8402
72183df4 8403@item -g [@var{file}]
8e55b3aa 8404@itemx --graph[=@var{file}]
34a6c2d1 8405Output a graphical representation of the parser's
35fe0834 8406automaton computed by Bison, in @uref{http://www.graphviz.org/, Graphviz}
35430378 8407@uref{http://www.graphviz.org/doc/info/lang.html, DOT} format.
8e55b3aa
JD
8408@code{@var{file}} is optional.
8409If omitted and the grammar file is @file{foo.y}, the output file will be
8410@file{foo.dot}.
59da312b 8411
72183df4 8412@item -x [@var{file}]
8e55b3aa 8413@itemx --xml[=@var{file}]
34a6c2d1 8414Output an XML report of the parser's automaton computed by Bison.
8e55b3aa 8415@code{@var{file}} is optional.
59da312b
JD
8416If omitted and the grammar file is @file{foo.y}, the output file will be
8417@file{foo.xml}.
8418(The current XML schema is experimental and may evolve.
8419More user feedback will help to stabilize it.)
bfa74976
RS
8420@end table
8421
342b8b6e 8422@node Option Cross Key
bfa74976
RS
8423@section Option Cross Key
8424
8425Here is a list of options, alphabetized by long option, to help you find
34d41938 8426the corresponding short option and directive.
bfa74976 8427
34d41938 8428@multitable {@option{--force-define=@var{name}[=@var{value}]}} {@option{-F @var{name}[=@var{value}]}} {@code{%nondeterministic-parser}}
72183df4 8429@headitem Long Option @tab Short Option @tab Bison Directive
f4101aa6 8430@include cross-options.texi
aa08666d 8431@end multitable
bfa74976 8432
93dd49ab
PE
8433@node Yacc Library
8434@section Yacc Library
8435
8436The Yacc library contains default implementations of the
8437@code{yyerror} and @code{main} functions. These default
35430378 8438implementations are normally not useful, but POSIX requires
93dd49ab
PE
8439them. To use the Yacc library, link your program with the
8440@option{-ly} option. Note that Bison's implementation of the Yacc
35430378 8441library is distributed under the terms of the GNU General
93dd49ab
PE
8442Public License (@pxref{Copying}).
8443
8444If you use the Yacc library's @code{yyerror} function, you should
8445declare @code{yyerror} as follows:
8446
8447@example
8448int yyerror (char const *);
8449@end example
8450
8451Bison ignores the @code{int} value returned by this @code{yyerror}.
8452If you use the Yacc library's @code{main} function, your
8453@code{yyparse} function should have the following type signature:
8454
8455@example
8456int yyparse (void);
8457@end example
8458
12545799
AD
8459@c ================================================= C++ Bison
8460
8405b70c
PB
8461@node Other Languages
8462@chapter Parsers Written In Other Languages
12545799
AD
8463
8464@menu
8465* C++ Parsers:: The interface to generate C++ parser classes
8405b70c 8466* Java Parsers:: The interface to generate Java parser classes
12545799
AD
8467@end menu
8468
8469@node C++ Parsers
8470@section C++ Parsers
8471
8472@menu
8473* C++ Bison Interface:: Asking for C++ parser generation
8474* C++ Semantic Values:: %union vs. C++
8475* C++ Location Values:: The position and location classes
8476* C++ Parser Interface:: Instantiating and running the parser
8477* C++ Scanner Interface:: Exchanges between yylex and parse
8405b70c 8478* A Complete C++ Example:: Demonstrating their use
12545799
AD
8479@end menu
8480
8481@node C++ Bison Interface
8482@subsection C++ Bison Interface
ed4d67dc 8483@c - %skeleton "lalr1.cc"
12545799
AD
8484@c - Always pure
8485@c - initial action
8486
34a6c2d1 8487The C++ deterministic parser is selected using the skeleton directive,
baacae49
AD
8488@samp{%skeleton "lalr1.cc"}, or the synonymous command-line option
8489@option{--skeleton=lalr1.cc}.
e6e704dc 8490@xref{Decl Summary}.
0e021770 8491
793fbca5
JD
8492When run, @command{bison} will create several entities in the @samp{yy}
8493namespace.
8494@findex %define namespace
2f4518a1
JD
8495Use the @samp{%define namespace} directive to change the namespace
8496name, see @ref{%define Summary,,namespace}. The various classes are
8497generated in the following files:
aa08666d 8498
12545799
AD
8499@table @file
8500@item position.hh
8501@itemx location.hh
8502The definition of the classes @code{position} and @code{location},
8503used for location tracking. @xref{C++ Location Values}.
8504
8505@item stack.hh
8506An auxiliary class @code{stack} used by the parser.
8507
fa4d969f
PE
8508@item @var{file}.hh
8509@itemx @var{file}.cc
9913d6e4 8510(Assuming the extension of the grammar file was @samp{.yy}.) The
cd8b5791
AD
8511declaration and implementation of the C++ parser class. The basename
8512and extension of these two files follow the same rules as with regular C
8513parsers (@pxref{Invocation}).
12545799 8514
cd8b5791
AD
8515The header is @emph{mandatory}; you must either pass
8516@option{-d}/@option{--defines} to @command{bison}, or use the
12545799
AD
8517@samp{%defines} directive.
8518@end table
8519
8520All these files are documented using Doxygen; run @command{doxygen}
8521for a complete and accurate documentation.
8522
8523@node C++ Semantic Values
8524@subsection C++ Semantic Values
8525@c - No objects in unions
178e123e 8526@c - YYSTYPE
12545799
AD
8527@c - Printer and destructor
8528
8529The @code{%union} directive works as for C, see @ref{Union Decl, ,The
8530Collection of Value Types}. In particular it produces a genuine
8531@code{union}@footnote{In the future techniques to allow complex types
fb9712a9
AD
8532within pseudo-unions (similar to Boost variants) might be implemented to
8533alleviate these issues.}, which have a few specific features in C++.
12545799
AD
8534@itemize @minus
8535@item
fb9712a9
AD
8536The type @code{YYSTYPE} is defined but its use is discouraged: rather
8537you should refer to the parser's encapsulated type
8538@code{yy::parser::semantic_type}.
12545799
AD
8539@item
8540Non POD (Plain Old Data) types cannot be used. C++ forbids any
8541instance of classes with constructors in unions: only @emph{pointers}
8542to such objects are allowed.
8543@end itemize
8544
8545Because objects have to be stored via pointers, memory is not
8546reclaimed automatically: using the @code{%destructor} directive is the
8547only means to avoid leaks. @xref{Destructor Decl, , Freeing Discarded
8548Symbols}.
8549
8550
8551@node C++ Location Values
8552@subsection C++ Location Values
8553@c - %locations
8554@c - class Position
8555@c - class Location
16dc6a9e 8556@c - %define filename_type "const symbol::Symbol"
12545799
AD
8557
8558When the directive @code{%locations} is used, the C++ parser supports
8559location tracking, see @ref{Locations, , Locations Overview}. Two
8560auxiliary classes define a @code{position}, a single point in a file,
8561and a @code{location}, a range composed of a pair of
8562@code{position}s (possibly spanning several files).
8563
fa4d969f 8564@deftypemethod {position} {std::string*} file
12545799
AD
8565The name of the file. It will always be handled as a pointer, the
8566parser will never duplicate nor deallocate it. As an experimental
8567feature you may change it to @samp{@var{type}*} using @samp{%define
16dc6a9e 8568filename_type "@var{type}"}.
12545799
AD
8569@end deftypemethod
8570
8571@deftypemethod {position} {unsigned int} line
8572The line, starting at 1.
8573@end deftypemethod
8574
8575@deftypemethod {position} {unsigned int} lines (int @var{height} = 1)
8576Advance by @var{height} lines, resetting the column number.
8577@end deftypemethod
8578
8579@deftypemethod {position} {unsigned int} column
8580The column, starting at 0.
8581@end deftypemethod
8582
8583@deftypemethod {position} {unsigned int} columns (int @var{width} = 1)
8584Advance by @var{width} columns, without changing the line number.
8585@end deftypemethod
8586
8587@deftypemethod {position} {position&} operator+= (position& @var{pos}, int @var{width})
8588@deftypemethodx {position} {position} operator+ (const position& @var{pos}, int @var{width})
8589@deftypemethodx {position} {position&} operator-= (const position& @var{pos}, int @var{width})
8590@deftypemethodx {position} {position} operator- (position& @var{pos}, int @var{width})
8591Various forms of syntactic sugar for @code{columns}.
8592@end deftypemethod
8593
8594@deftypemethod {position} {position} operator<< (std::ostream @var{o}, const position& @var{p})
8595Report @var{p} on @var{o} like this:
fa4d969f
PE
8596@samp{@var{file}:@var{line}.@var{column}}, or
8597@samp{@var{line}.@var{column}} if @var{file} is null.
12545799
AD
8598@end deftypemethod
8599
8600@deftypemethod {location} {position} begin
8601@deftypemethodx {location} {position} end
8602The first, inclusive, position of the range, and the first beyond.
8603@end deftypemethod
8604
8605@deftypemethod {location} {unsigned int} columns (int @var{width} = 1)
8606@deftypemethodx {location} {unsigned int} lines (int @var{height} = 1)
8607Advance the @code{end} position.
8608@end deftypemethod
8609
8610@deftypemethod {location} {location} operator+ (const location& @var{begin}, const location& @var{end})
8611@deftypemethodx {location} {location} operator+ (const location& @var{begin}, int @var{width})
8612@deftypemethodx {location} {location} operator+= (const location& @var{loc}, int @var{width})
8613Various forms of syntactic sugar.
8614@end deftypemethod
8615
8616@deftypemethod {location} {void} step ()
8617Move @code{begin} onto @code{end}.
8618@end deftypemethod
8619
8620
8621@node C++ Parser Interface
8622@subsection C++ Parser Interface
8623@c - define parser_class_name
8624@c - Ctor
8625@c - parse, error, set_debug_level, debug_level, set_debug_stream,
8626@c debug_stream.
8627@c - Reporting errors
8628
8629The output files @file{@var{output}.hh} and @file{@var{output}.cc}
8630declare and define the parser class in the namespace @code{yy}. The
8631class name defaults to @code{parser}, but may be changed using
16dc6a9e 8632@samp{%define parser_class_name "@var{name}"}. The interface of
9d9b8b70 8633this class is detailed below. It can be extended using the
12545799
AD
8634@code{%parse-param} feature: its semantics is slightly changed since
8635it describes an additional member of the parser class, and an
8636additional argument for its constructor.
8637
baacae49
AD
8638@defcv {Type} {parser} {semantic_type}
8639@defcvx {Type} {parser} {location_type}
12545799 8640The types for semantics value and locations.
8a0adb01 8641@end defcv
12545799 8642
baacae49
AD
8643@defcv {Type} {parser} {token}
8644A structure that contains (only) the definition of the tokens as the
8645@code{yytokentype} enumeration. To refer to the token @code{FOO}, the
8646scanner should use @code{yy::parser::token::FOO}. The scanner can use
8647@samp{typedef yy::parser::token token;} to ``import'' the token enumeration
8648(@pxref{Calc++ Scanner}).
8649@end defcv
8650
12545799
AD
8651@deftypemethod {parser} {} parser (@var{type1} @var{arg1}, ...)
8652Build a new parser object. There are no arguments by default, unless
8653@samp{%parse-param @{@var{type1} @var{arg1}@}} was used.
8654@end deftypemethod
8655
8656@deftypemethod {parser} {int} parse ()
8657Run the syntactic analysis, and return 0 on success, 1 otherwise.
8658@end deftypemethod
8659
8660@deftypemethod {parser} {std::ostream&} debug_stream ()
8661@deftypemethodx {parser} {void} set_debug_stream (std::ostream& @var{o})
8662Get or set the stream used for tracing the parsing. It defaults to
8663@code{std::cerr}.
8664@end deftypemethod
8665
8666@deftypemethod {parser} {debug_level_type} debug_level ()
8667@deftypemethodx {parser} {void} set_debug_level (debug_level @var{l})
8668Get or set the tracing level. Currently its value is either 0, no trace,
9d9b8b70 8669or nonzero, full tracing.
12545799
AD
8670@end deftypemethod
8671
8672@deftypemethod {parser} {void} error (const location_type& @var{l}, const std::string& @var{m})
8673The definition for this member function must be supplied by the user:
8674the parser uses it to report a parser error occurring at @var{l},
8675described by @var{m}.
8676@end deftypemethod
8677
8678
8679@node C++ Scanner Interface
8680@subsection C++ Scanner Interface
8681@c - prefix for yylex.
8682@c - Pure interface to yylex
8683@c - %lex-param
8684
8685The parser invokes the scanner by calling @code{yylex}. Contrary to C
8686parsers, C++ parsers are always pure: there is no point in using the
d9df47b6 8687@code{%define api.pure} directive. Therefore the interface is as follows.
12545799 8688
baacae49 8689@deftypemethod {parser} {int} yylex (semantic_type* @var{yylval}, location_type* @var{yylloc}, @var{type1} @var{arg1}, ...)
12545799
AD
8690Return the next token. Its type is the return value, its semantic
8691value and location being @var{yylval} and @var{yylloc}. Invocations of
8692@samp{%lex-param @{@var{type1} @var{arg1}@}} yield additional arguments.
8693@end deftypemethod
8694
8695
8696@node A Complete C++ Example
8405b70c 8697@subsection A Complete C++ Example
12545799
AD
8698
8699This section demonstrates the use of a C++ parser with a simple but
8700complete example. This example should be available on your system,
8701ready to compile, in the directory @dfn{../bison/examples/calc++}. It
8702focuses on the use of Bison, therefore the design of the various C++
8703classes is very naive: no accessors, no encapsulation of members etc.
8704We will use a Lex scanner, and more precisely, a Flex scanner, to
8705demonstrate the various interaction. A hand written scanner is
8706actually easier to interface with.
8707
8708@menu
8709* Calc++ --- C++ Calculator:: The specifications
8710* Calc++ Parsing Driver:: An active parsing context
8711* Calc++ Parser:: A parser class
8712* Calc++ Scanner:: A pure C++ Flex scanner
8713* Calc++ Top Level:: Conducting the band
8714@end menu
8715
8716@node Calc++ --- C++ Calculator
8405b70c 8717@subsubsection Calc++ --- C++ Calculator
12545799
AD
8718
8719Of course the grammar is dedicated to arithmetics, a single
9d9b8b70 8720expression, possibly preceded by variable assignments. An
12545799
AD
8721environment containing possibly predefined variables such as
8722@code{one} and @code{two}, is exchanged with the parser. An example
8723of valid input follows.
8724
8725@example
8726three := 3
8727seven := one + two * three
8728seven * seven
8729@end example
8730
8731@node Calc++ Parsing Driver
8405b70c 8732@subsubsection Calc++ Parsing Driver
12545799
AD
8733@c - An env
8734@c - A place to store error messages
8735@c - A place for the result
8736
8737To support a pure interface with the parser (and the scanner) the
8738technique of the ``parsing context'' is convenient: a structure
8739containing all the data to exchange. Since, in addition to simply
8740launch the parsing, there are several auxiliary tasks to execute (open
8741the file for parsing, instantiate the parser etc.), we recommend
8742transforming the simple parsing context structure into a fully blown
8743@dfn{parsing driver} class.
8744
8745The declaration of this driver class, @file{calc++-driver.hh}, is as
8746follows. The first part includes the CPP guard and imports the
fb9712a9
AD
8747required standard library components, and the declaration of the parser
8748class.
12545799 8749
1c59e0a1 8750@comment file: calc++-driver.hh
12545799
AD
8751@example
8752#ifndef CALCXX_DRIVER_HH
8753# define CALCXX_DRIVER_HH
8754# include <string>
8755# include <map>
fb9712a9 8756# include "calc++-parser.hh"
12545799
AD
8757@end example
8758
12545799
AD
8759
8760@noindent
8761Then comes the declaration of the scanning function. Flex expects
8762the signature of @code{yylex} to be defined in the macro
8763@code{YY_DECL}, and the C++ parser expects it to be declared. We can
8764factor both as follows.
1c59e0a1
AD
8765
8766@comment file: calc++-driver.hh
12545799 8767@example
3dc5e96b
PE
8768// Tell Flex the lexer's prototype ...
8769# define YY_DECL \
c095d689
AD
8770 yy::calcxx_parser::token_type \
8771 yylex (yy::calcxx_parser::semantic_type* yylval, \
8772 yy::calcxx_parser::location_type* yylloc, \
8773 calcxx_driver& driver)
12545799
AD
8774// ... and declare it for the parser's sake.
8775YY_DECL;
8776@end example
8777
8778@noindent
8779The @code{calcxx_driver} class is then declared with its most obvious
8780members.
8781
1c59e0a1 8782@comment file: calc++-driver.hh
12545799
AD
8783@example
8784// Conducting the whole scanning and parsing of Calc++.
8785class calcxx_driver
8786@{
8787public:
8788 calcxx_driver ();
8789 virtual ~calcxx_driver ();
8790
8791 std::map<std::string, int> variables;
8792
8793 int result;
8794@end example
8795
8796@noindent
8797To encapsulate the coordination with the Flex scanner, it is useful to
8798have two members function to open and close the scanning phase.
12545799 8799
1c59e0a1 8800@comment file: calc++-driver.hh
12545799
AD
8801@example
8802 // Handling the scanner.
8803 void scan_begin ();
8804 void scan_end ();
8805 bool trace_scanning;
8806@end example
8807
8808@noindent
8809Similarly for the parser itself.
8810
1c59e0a1 8811@comment file: calc++-driver.hh
12545799 8812@example
bb32f4f2
AD
8813 // Run the parser. Return 0 on success.
8814 int parse (const std::string& f);
12545799
AD
8815 std::string file;
8816 bool trace_parsing;
8817@end example
8818
8819@noindent
8820To demonstrate pure handling of parse errors, instead of simply
8821dumping them on the standard error output, we will pass them to the
8822compiler driver using the following two member functions. Finally, we
8823close the class declaration and CPP guard.
8824
1c59e0a1 8825@comment file: calc++-driver.hh
12545799
AD
8826@example
8827 // Error handling.
8828 void error (const yy::location& l, const std::string& m);
8829 void error (const std::string& m);
8830@};
8831#endif // ! CALCXX_DRIVER_HH
8832@end example
8833
8834The implementation of the driver is straightforward. The @code{parse}
8835member function deserves some attention. The @code{error} functions
8836are simple stubs, they should actually register the located error
8837messages and set error state.
8838
1c59e0a1 8839@comment file: calc++-driver.cc
12545799
AD
8840@example
8841#include "calc++-driver.hh"
8842#include "calc++-parser.hh"
8843
8844calcxx_driver::calcxx_driver ()
8845 : trace_scanning (false), trace_parsing (false)
8846@{
8847 variables["one"] = 1;
8848 variables["two"] = 2;
8849@}
8850
8851calcxx_driver::~calcxx_driver ()
8852@{
8853@}
8854
bb32f4f2 8855int
12545799
AD
8856calcxx_driver::parse (const std::string &f)
8857@{
8858 file = f;
8859 scan_begin ();
8860 yy::calcxx_parser parser (*this);
8861 parser.set_debug_level (trace_parsing);
bb32f4f2 8862 int res = parser.parse ();
12545799 8863 scan_end ();
bb32f4f2 8864 return res;
12545799
AD
8865@}
8866
8867void
8868calcxx_driver::error (const yy::location& l, const std::string& m)
8869@{
8870 std::cerr << l << ": " << m << std::endl;
8871@}
8872
8873void
8874calcxx_driver::error (const std::string& m)
8875@{
8876 std::cerr << m << std::endl;
8877@}
8878@end example
8879
8880@node Calc++ Parser
8405b70c 8881@subsubsection Calc++ Parser
12545799 8882
9913d6e4
JD
8883The grammar file @file{calc++-parser.yy} starts by asking for the C++
8884deterministic parser skeleton, the creation of the parser header file,
8885and specifies the name of the parser class. Because the C++ skeleton
8886changed several times, it is safer to require the version you designed
8887the grammar for.
1c59e0a1
AD
8888
8889@comment file: calc++-parser.yy
12545799 8890@example
ed4d67dc 8891%skeleton "lalr1.cc" /* -*- C++ -*- */
e6e704dc 8892%require "@value{VERSION}"
12545799 8893%defines
16dc6a9e 8894%define parser_class_name "calcxx_parser"
fb9712a9
AD
8895@end example
8896
8897@noindent
16dc6a9e 8898@findex %code requires
fb9712a9
AD
8899Then come the declarations/inclusions needed to define the
8900@code{%union}. Because the parser uses the parsing driver and
8901reciprocally, both cannot include the header of the other. Because the
8902driver's header needs detailed knowledge about the parser class (in
8903particular its inner types), it is the parser's header which will simply
8904use a forward declaration of the driver.
8e6f2266 8905@xref{%code Summary}.
fb9712a9
AD
8906
8907@comment file: calc++-parser.yy
8908@example
16dc6a9e 8909%code requires @{
12545799 8910# include <string>
fb9712a9 8911class calcxx_driver;
9bc0dd67 8912@}
12545799
AD
8913@end example
8914
8915@noindent
8916The driver is passed by reference to the parser and to the scanner.
8917This provides a simple but effective pure interface, not relying on
8918global variables.
8919
1c59e0a1 8920@comment file: calc++-parser.yy
12545799
AD
8921@example
8922// The parsing context.
8923%parse-param @{ calcxx_driver& driver @}
8924%lex-param @{ calcxx_driver& driver @}
8925@end example
8926
8927@noindent
8928Then we request the location tracking feature, and initialize the
c781580d 8929first location's file name. Afterward new locations are computed
12545799
AD
8930relatively to the previous locations: the file name will be
8931automatically propagated.
8932
1c59e0a1 8933@comment file: calc++-parser.yy
12545799
AD
8934@example
8935%locations
8936%initial-action
8937@{
8938 // Initialize the initial location.
b47dbebe 8939 @@$.begin.filename = @@$.end.filename = &driver.file;
12545799
AD
8940@};
8941@end example
8942
8943@noindent
8944Use the two following directives to enable parser tracing and verbose
8945error messages.
8946
1c59e0a1 8947@comment file: calc++-parser.yy
12545799
AD
8948@example
8949%debug
8950%error-verbose
8951@end example
8952
8953@noindent
8954Semantic values cannot use ``real'' objects, but only pointers to
8955them.
8956
1c59e0a1 8957@comment file: calc++-parser.yy
12545799
AD
8958@example
8959// Symbols.
8960%union
8961@{
8962 int ival;
8963 std::string *sval;
8964@};
8965@end example
8966
fb9712a9 8967@noindent
136a0f76
PB
8968@findex %code
8969The code between @samp{%code @{} and @samp{@}} is output in the
34f98f46 8970@file{*.cc} file; it needs detailed knowledge about the driver.
fb9712a9
AD
8971
8972@comment file: calc++-parser.yy
8973@example
136a0f76 8974%code @{
fb9712a9 8975# include "calc++-driver.hh"
34f98f46 8976@}
fb9712a9
AD
8977@end example
8978
8979
12545799
AD
8980@noindent
8981The token numbered as 0 corresponds to end of file; the following line
8982allows for nicer error messages referring to ``end of file'' instead
8983of ``$end''. Similarly user friendly named are provided for each
8984symbol. Note that the tokens names are prefixed by @code{TOKEN_} to
8985avoid name clashes.
8986
1c59e0a1 8987@comment file: calc++-parser.yy
12545799 8988@example
fb9712a9
AD
8989%token END 0 "end of file"
8990%token ASSIGN ":="
8991%token <sval> IDENTIFIER "identifier"
8992%token <ival> NUMBER "number"
a8c2e813 8993%type <ival> exp
12545799
AD
8994@end example
8995
8996@noindent
8997To enable memory deallocation during error recovery, use
8998@code{%destructor}.
8999
287c78f6 9000@c FIXME: Document %printer, and mention that it takes a braced-code operand.
1c59e0a1 9001@comment file: calc++-parser.yy
12545799
AD
9002@example
9003%printer @{ debug_stream () << *$$; @} "identifier"
9004%destructor @{ delete $$; @} "identifier"
9005
a8c2e813 9006%printer @{ debug_stream () << $$; @} <ival>
12545799
AD
9007@end example
9008
9009@noindent
9010The grammar itself is straightforward.
9011
1c59e0a1 9012@comment file: calc++-parser.yy
12545799
AD
9013@example
9014%%
9015%start unit;
9016unit: assignments exp @{ driver.result = $2; @};
9017
9018assignments: assignments assignment @{@}
9d9b8b70 9019 | /* Nothing. */ @{@};
12545799 9020
3dc5e96b
PE
9021assignment:
9022 "identifier" ":=" exp
9023 @{ driver.variables[*$1] = $3; delete $1; @};
12545799
AD
9024
9025%left '+' '-';
9026%left '*' '/';
9027exp: exp '+' exp @{ $$ = $1 + $3; @}
9028 | exp '-' exp @{ $$ = $1 - $3; @}
9029 | exp '*' exp @{ $$ = $1 * $3; @}
9030 | exp '/' exp @{ $$ = $1 / $3; @}
3dc5e96b 9031 | "identifier" @{ $$ = driver.variables[*$1]; delete $1; @}
fb9712a9 9032 | "number" @{ $$ = $1; @};
12545799
AD
9033%%
9034@end example
9035
9036@noindent
9037Finally the @code{error} member function registers the errors to the
9038driver.
9039
1c59e0a1 9040@comment file: calc++-parser.yy
12545799
AD
9041@example
9042void
1c59e0a1
AD
9043yy::calcxx_parser::error (const yy::calcxx_parser::location_type& l,
9044 const std::string& m)
12545799
AD
9045@{
9046 driver.error (l, m);
9047@}
9048@end example
9049
9050@node Calc++ Scanner
8405b70c 9051@subsubsection Calc++ Scanner
12545799
AD
9052
9053The Flex scanner first includes the driver declaration, then the
9054parser's to get the set of defined tokens.
9055
1c59e0a1 9056@comment file: calc++-scanner.ll
12545799
AD
9057@example
9058%@{ /* -*- C++ -*- */
04098407 9059# include <cstdlib>
b10dd689
AD
9060# include <cerrno>
9061# include <climits>
12545799
AD
9062# include <string>
9063# include "calc++-driver.hh"
9064# include "calc++-parser.hh"
eaea13f5
PE
9065
9066/* Work around an incompatibility in flex (at least versions
9067 2.5.31 through 2.5.33): it generates code that does
9068 not conform to C89. See Debian bug 333231
9069 <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=333231>. */
7870f699
PE
9070# undef yywrap
9071# define yywrap() 1
eaea13f5 9072
c095d689
AD
9073/* By default yylex returns int, we use token_type.
9074 Unfortunately yyterminate by default returns 0, which is
9075 not of token_type. */
8c5b881d 9076#define yyterminate() return token::END
12545799
AD
9077%@}
9078@end example
9079
9080@noindent
9081Because there is no @code{#include}-like feature we don't need
9082@code{yywrap}, we don't need @code{unput} either, and we parse an
9083actual file, this is not an interactive session with the user.
9084Finally we enable the scanner tracing features.
9085
1c59e0a1 9086@comment file: calc++-scanner.ll
12545799
AD
9087@example
9088%option noyywrap nounput batch debug
9089@end example
9090
9091@noindent
9092Abbreviations allow for more readable rules.
9093
1c59e0a1 9094@comment file: calc++-scanner.ll
12545799
AD
9095@example
9096id [a-zA-Z][a-zA-Z_0-9]*
9097int [0-9]+
9098blank [ \t]
9099@end example
9100
9101@noindent
9d9b8b70 9102The following paragraph suffices to track locations accurately. Each
12545799
AD
9103time @code{yylex} is invoked, the begin position is moved onto the end
9104position. Then when a pattern is matched, the end position is
9105advanced of its width. In case it matched ends of lines, the end
9106cursor is adjusted, and each time blanks are matched, the begin cursor
9107is moved onto the end cursor to effectively ignore the blanks
9108preceding tokens. Comments would be treated equally.
9109
1c59e0a1 9110@comment file: calc++-scanner.ll
12545799 9111@example
828c373b
AD
9112%@{
9113# define YY_USER_ACTION yylloc->columns (yyleng);
9114%@}
12545799
AD
9115%%
9116%@{
9117 yylloc->step ();
12545799
AD
9118%@}
9119@{blank@}+ yylloc->step ();
9120[\n]+ yylloc->lines (yyleng); yylloc->step ();
9121@end example
9122
9123@noindent
fb9712a9
AD
9124The rules are simple, just note the use of the driver to report errors.
9125It is convenient to use a typedef to shorten
9126@code{yy::calcxx_parser::token::identifier} into
9d9b8b70 9127@code{token::identifier} for instance.
12545799 9128
1c59e0a1 9129@comment file: calc++-scanner.ll
12545799 9130@example
fb9712a9
AD
9131%@{
9132 typedef yy::calcxx_parser::token token;
9133%@}
8c5b881d 9134 /* Convert ints to the actual type of tokens. */
c095d689 9135[-+*/] return yy::calcxx_parser::token_type (yytext[0]);
fb9712a9 9136":=" return token::ASSIGN;
04098407
PE
9137@{int@} @{
9138 errno = 0;
9139 long n = strtol (yytext, NULL, 10);
9140 if (! (INT_MIN <= n && n <= INT_MAX && errno != ERANGE))
9141 driver.error (*yylloc, "integer is out of range");
9142 yylval->ival = n;
fb9712a9 9143 return token::NUMBER;
04098407 9144@}
fb9712a9 9145@{id@} yylval->sval = new std::string (yytext); return token::IDENTIFIER;
12545799
AD
9146. driver.error (*yylloc, "invalid character");
9147%%
9148@end example
9149
9150@noindent
9151Finally, because the scanner related driver's member function depend
9152on the scanner's data, it is simpler to implement them in this file.
9153
1c59e0a1 9154@comment file: calc++-scanner.ll
12545799
AD
9155@example
9156void
9157calcxx_driver::scan_begin ()
9158@{
9159 yy_flex_debug = trace_scanning;
bb32f4f2
AD
9160 if (file == "-")
9161 yyin = stdin;
9162 else if (!(yyin = fopen (file.c_str (), "r")))
9163 @{
9164 error (std::string ("cannot open ") + file);
9165 exit (1);
9166 @}
12545799
AD
9167@}
9168
9169void
9170calcxx_driver::scan_end ()
9171@{
9172 fclose (yyin);
9173@}
9174@end example
9175
9176@node Calc++ Top Level
8405b70c 9177@subsubsection Calc++ Top Level
12545799
AD
9178
9179The top level file, @file{calc++.cc}, poses no problem.
9180
1c59e0a1 9181@comment file: calc++.cc
12545799
AD
9182@example
9183#include <iostream>
9184#include "calc++-driver.hh"
9185
9186int
fa4d969f 9187main (int argc, char *argv[])
12545799
AD
9188@{
9189 calcxx_driver driver;
9190 for (++argv; argv[0]; ++argv)
9191 if (*argv == std::string ("-p"))
9192 driver.trace_parsing = true;
9193 else if (*argv == std::string ("-s"))
9194 driver.trace_scanning = true;
bb32f4f2
AD
9195 else if (!driver.parse (*argv))
9196 std::cout << driver.result << std::endl;
12545799
AD
9197@}
9198@end example
9199
8405b70c
PB
9200@node Java Parsers
9201@section Java Parsers
9202
9203@menu
f56274a8
DJ
9204* Java Bison Interface:: Asking for Java parser generation
9205* Java Semantic Values:: %type and %token vs. Java
9206* Java Location Values:: The position and location classes
9207* Java Parser Interface:: Instantiating and running the parser
9208* Java Scanner Interface:: Specifying the scanner for the parser
9209* Java Action Features:: Special features for use in actions
9210* Java Differences:: Differences between C/C++ and Java Grammars
9211* Java Declarations Summary:: List of Bison declarations used with Java
8405b70c
PB
9212@end menu
9213
9214@node Java Bison Interface
9215@subsection Java Bison Interface
9216@c - %language "Java"
8405b70c 9217
59da312b
JD
9218(The current Java interface is experimental and may evolve.
9219More user feedback will help to stabilize it.)
9220
e254a580
DJ
9221The Java parser skeletons are selected using the @code{%language "Java"}
9222directive or the @option{-L java}/@option{--language=java} option.
8405b70c 9223
e254a580 9224@c FIXME: Documented bug.
9913d6e4
JD
9225When generating a Java parser, @code{bison @var{basename}.y} will
9226create a single Java source file named @file{@var{basename}.java}
9227containing the parser implementation. Using a grammar file without a
9228@file{.y} suffix is currently broken. The basename of the parser
9229implementation file can be changed by the @code{%file-prefix}
9230directive or the @option{-p}/@option{--name-prefix} option. The
9231entire parser implementation file name can be changed by the
9232@code{%output} directive or the @option{-o}/@option{--output} option.
9233The parser implementation file contains a single class for the parser.
8405b70c 9234
e254a580 9235You can create documentation for generated parsers using Javadoc.
8405b70c 9236
e254a580
DJ
9237Contrary to C parsers, Java parsers do not use global variables; the
9238state of the parser is always local to an instance of the parser class.
9239Therefore, all Java parsers are ``pure'', and the @code{%pure-parser}
9240and @code{%define api.pure} directives does not do anything when used in
9241Java.
8405b70c 9242
e254a580 9243Push parsers are currently unsupported in Java and @code{%define
812775a0 9244api.push-pull} have no effect.
01b477c6 9245
35430378 9246GLR parsers are currently unsupported in Java. Do not use the
e254a580
DJ
9247@code{glr-parser} directive.
9248
9249No header file can be generated for Java parsers. Do not use the
9250@code{%defines} directive or the @option{-d}/@option{--defines} options.
9251
9252@c FIXME: Possible code change.
9253Currently, support for debugging and verbose errors are always compiled
9254in. Thus the @code{%debug} and @code{%token-table} directives and the
9255@option{-t}/@option{--debug} and @option{-k}/@option{--token-table}
9256options have no effect. This may change in the future to eliminate
9257unused code in the generated parser, so use @code{%debug} and
9258@code{%verbose-error} explicitly if needed. Also, in the future the
9259@code{%token-table} directive might enable a public interface to
9260access the token names and codes.
8405b70c
PB
9261
9262@node Java Semantic Values
9263@subsection Java Semantic Values
9264@c - No %union, specify type in %type/%token.
9265@c - YYSTYPE
9266@c - Printer and destructor
9267
9268There is no @code{%union} directive in Java parsers. Instead, the
9269semantic values' types (class names) should be specified in the
9270@code{%type} or @code{%token} directive:
9271
9272@example
9273%type <Expression> expr assignment_expr term factor
9274%type <Integer> number
9275@end example
9276
9277By default, the semantic stack is declared to have @code{Object} members,
9278which means that the class types you specify can be of any class.
9279To improve the type safety of the parser, you can declare the common
e254a580
DJ
9280superclass of all the semantic values using the @code{%define stype}
9281directive. For example, after the following declaration:
8405b70c
PB
9282
9283@example
e254a580 9284%define stype "ASTNode"
8405b70c
PB
9285@end example
9286
9287@noindent
9288any @code{%type} or @code{%token} specifying a semantic type which
9289is not a subclass of ASTNode, will cause a compile-time error.
9290
e254a580 9291@c FIXME: Documented bug.
8405b70c
PB
9292Types used in the directives may be qualified with a package name.
9293Primitive data types are accepted for Java version 1.5 or later. Note
9294that in this case the autoboxing feature of Java 1.5 will be used.
e254a580
DJ
9295Generic types may not be used; this is due to a limitation in the
9296implementation of Bison, and may change in future releases.
8405b70c
PB
9297
9298Java parsers do not support @code{%destructor}, since the language
9299adopts garbage collection. The parser will try to hold references
9300to semantic values for as little time as needed.
9301
9302Java parsers do not support @code{%printer}, as @code{toString()}
9303can be used to print the semantic values. This however may change
9304(in a backwards-compatible way) in future versions of Bison.
9305
9306
9307@node Java Location Values
9308@subsection Java Location Values
9309@c - %locations
9310@c - class Position
9311@c - class Location
9312
9313When the directive @code{%locations} is used, the Java parser
9314supports location tracking, see @ref{Locations, , Locations Overview}.
9315An auxiliary user-defined class defines a @dfn{position}, a single point
9316in a file; Bison itself defines a class representing a @dfn{location},
9317a range composed of a pair of positions (possibly spanning several
9318files). The location class is an inner class of the parser; the name
e254a580 9319is @code{Location} by default, and may also be renamed using
f37495f6 9320@code{%define location_type "@var{class-name}"}.
8405b70c
PB
9321
9322The location class treats the position as a completely opaque value.
9323By default, the class name is @code{Position}, but this can be changed
e254a580
DJ
9324with @code{%define position_type "@var{class-name}"}. This class must
9325be supplied by the user.
8405b70c
PB
9326
9327
e254a580
DJ
9328@deftypeivar {Location} {Position} begin
9329@deftypeivarx {Location} {Position} end
8405b70c 9330The first, inclusive, position of the range, and the first beyond.
e254a580
DJ
9331@end deftypeivar
9332
9333@deftypeop {Constructor} {Location} {} Location (Position @var{loc})
c046698e 9334Create a @code{Location} denoting an empty range located at a given point.
e254a580 9335@end deftypeop
8405b70c 9336
e254a580
DJ
9337@deftypeop {Constructor} {Location} {} Location (Position @var{begin}, Position @var{end})
9338Create a @code{Location} from the endpoints of the range.
9339@end deftypeop
9340
9341@deftypemethod {Location} {String} toString ()
8405b70c
PB
9342Prints the range represented by the location. For this to work
9343properly, the position class should override the @code{equals} and
9344@code{toString} methods appropriately.
9345@end deftypemethod
9346
9347
9348@node Java Parser Interface
9349@subsection Java Parser Interface
9350@c - define parser_class_name
9351@c - Ctor
9352@c - parse, error, set_debug_level, debug_level, set_debug_stream,
9353@c debug_stream.
9354@c - Reporting errors
9355
e254a580
DJ
9356The name of the generated parser class defaults to @code{YYParser}. The
9357@code{YY} prefix may be changed using the @code{%name-prefix} directive
9358or the @option{-p}/@option{--name-prefix} option. Alternatively, use
9359@code{%define parser_class_name "@var{name}"} to give a custom name to
9360the class. The interface of this class is detailed below.
8405b70c 9361
e254a580
DJ
9362By default, the parser class has package visibility. A declaration
9363@code{%define public} will change to public visibility. Remember that,
9364according to the Java language specification, the name of the @file{.java}
9365file should match the name of the class in this case. Similarly, you can
9366use @code{abstract}, @code{final} and @code{strictfp} with the
9367@code{%define} declaration to add other modifiers to the parser class.
9368
9369The Java package name of the parser class can be specified using the
9370@code{%define package} directive. The superclass and the implemented
9371interfaces of the parser class can be specified with the @code{%define
9372extends} and @code{%define implements} directives.
9373
9374The parser class defines an inner class, @code{Location}, that is used
9375for location tracking (see @ref{Java Location Values}), and a inner
9376interface, @code{Lexer} (see @ref{Java Scanner Interface}). Other than
9377these inner class/interface, and the members described in the interface
9378below, all the other members and fields are preceded with a @code{yy} or
9379@code{YY} prefix to avoid clashes with user code.
9380
9381@c FIXME: The following constants and variables are still undocumented:
9382@c @code{bisonVersion}, @code{bisonSkeleton} and @code{errorVerbose}.
9383
9384The parser class can be extended using the @code{%parse-param}
9385directive. Each occurrence of the directive will add a @code{protected
9386final} field to the parser class, and an argument to its constructor,
9387which initialize them automatically.
9388
9389Token names defined by @code{%token} and the predefined @code{EOF} token
9390name are added as constant fields to the parser class.
9391
9392@deftypeop {Constructor} {YYParser} {} YYParser (@var{lex_param}, @dots{}, @var{parse_param}, @dots{})
9393Build a new parser object with embedded @code{%code lexer}. There are
9394no parameters, unless @code{%parse-param}s and/or @code{%lex-param}s are
9395used.
9396@end deftypeop
9397
9398@deftypeop {Constructor} {YYParser} {} YYParser (Lexer @var{lexer}, @var{parse_param}, @dots{})
9399Build a new parser object using the specified scanner. There are no
9400additional parameters unless @code{%parse-param}s are used.
9401
9402If the scanner is defined by @code{%code lexer}, this constructor is
9403declared @code{protected} and is called automatically with a scanner
9404created with the correct @code{%lex-param}s.
9405@end deftypeop
8405b70c
PB
9406
9407@deftypemethod {YYParser} {boolean} parse ()
9408Run the syntactic analysis, and return @code{true} on success,
9409@code{false} otherwise.
9410@end deftypemethod
9411
01b477c6 9412@deftypemethod {YYParser} {boolean} recovering ()
8405b70c 9413During the syntactic analysis, return @code{true} if recovering
e254a580
DJ
9414from a syntax error.
9415@xref{Error Recovery}.
8405b70c
PB
9416@end deftypemethod
9417
9418@deftypemethod {YYParser} {java.io.PrintStream} getDebugStream ()
9419@deftypemethodx {YYParser} {void} setDebugStream (java.io.printStream @var{o})
9420Get or set the stream used for tracing the parsing. It defaults to
9421@code{System.err}.
9422@end deftypemethod
9423
9424@deftypemethod {YYParser} {int} getDebugLevel ()
9425@deftypemethodx {YYParser} {void} setDebugLevel (int @var{l})
9426Get or set the tracing level. Currently its value is either 0, no trace,
9427or nonzero, full tracing.
9428@end deftypemethod
9429
8405b70c
PB
9430
9431@node Java Scanner Interface
9432@subsection Java Scanner Interface
01b477c6 9433@c - %code lexer
8405b70c 9434@c - %lex-param
01b477c6 9435@c - Lexer interface
8405b70c 9436
e254a580
DJ
9437There are two possible ways to interface a Bison-generated Java parser
9438with a scanner: the scanner may be defined by @code{%code lexer}, or
9439defined elsewhere. In either case, the scanner has to implement the
9440@code{Lexer} inner interface of the parser class.
9441
9442In the first case, the body of the scanner class is placed in
9443@code{%code lexer} blocks. If you want to pass parameters from the
9444parser constructor to the scanner constructor, specify them with
9445@code{%lex-param}; they are passed before @code{%parse-param}s to the
9446constructor.
01b477c6 9447
59c5ac72 9448In the second case, the scanner has to implement the @code{Lexer} interface,
01b477c6
PB
9449which is defined within the parser class (e.g., @code{YYParser.Lexer}).
9450The constructor of the parser object will then accept an object
9451implementing the interface; @code{%lex-param} is not used in this
9452case.
9453
9454In both cases, the scanner has to implement the following methods.
9455
e254a580
DJ
9456@deftypemethod {Lexer} {void} yyerror (Location @var{loc}, String @var{msg})
9457This method is defined by the user to emit an error message. The first
9458parameter is omitted if location tracking is not active. Its type can be
9459changed using @code{%define location_type "@var{class-name}".}
8405b70c
PB
9460@end deftypemethod
9461
e254a580 9462@deftypemethod {Lexer} {int} yylex ()
8405b70c 9463Return the next token. Its type is the return value, its semantic
c781580d 9464value and location are saved and returned by the their methods in the
e254a580
DJ
9465interface.
9466
9467Use @code{%define lex_throws} to specify any uncaught exceptions.
9468Default is @code{java.io.IOException}.
8405b70c
PB
9469@end deftypemethod
9470
9471@deftypemethod {Lexer} {Position} getStartPos ()
9472@deftypemethodx {Lexer} {Position} getEndPos ()
01b477c6
PB
9473Return respectively the first position of the last token that
9474@code{yylex} returned, and the first position beyond it. These
9475methods are not needed unless location tracking is active.
8405b70c 9476
e254a580 9477The return type can be changed using @code{%define position_type
8405b70c
PB
9478"@var{class-name}".}
9479@end deftypemethod
9480
9481@deftypemethod {Lexer} {Object} getLVal ()
c781580d 9482Return the semantic value of the last token that yylex returned.
8405b70c 9483
e254a580 9484The return type can be changed using @code{%define stype
8405b70c
PB
9485"@var{class-name}".}
9486@end deftypemethod
9487
9488
e254a580
DJ
9489@node Java Action Features
9490@subsection Special Features for Use in Java Actions
9491
9492The following special constructs can be uses in Java actions.
9493Other analogous C action features are currently unavailable for Java.
9494
9495Use @code{%define throws} to specify any uncaught exceptions from parser
9496actions, and initial actions specified by @code{%initial-action}.
9497
9498@defvar $@var{n}
9499The semantic value for the @var{n}th component of the current rule.
9500This may not be assigned to.
9501@xref{Java Semantic Values}.
9502@end defvar
9503
9504@defvar $<@var{typealt}>@var{n}
9505Like @code{$@var{n}} but specifies a alternative type @var{typealt}.
9506@xref{Java Semantic Values}.
9507@end defvar
9508
9509@defvar $$
9510The semantic value for the grouping made by the current rule. As a
9511value, this is in the base type (@code{Object} or as specified by
9512@code{%define stype}) as in not cast to the declared subtype because
9513casts are not allowed on the left-hand side of Java assignments.
9514Use an explicit Java cast if the correct subtype is needed.
9515@xref{Java Semantic Values}.
9516@end defvar
9517
9518@defvar $<@var{typealt}>$
9519Same as @code{$$} since Java always allow assigning to the base type.
9520Perhaps we should use this and @code{$<>$} for the value and @code{$$}
9521for setting the value but there is currently no easy way to distinguish
9522these constructs.
9523@xref{Java Semantic Values}.
9524@end defvar
9525
9526@defvar @@@var{n}
9527The location information of the @var{n}th component of the current rule.
9528This may not be assigned to.
9529@xref{Java Location Values}.
9530@end defvar
9531
9532@defvar @@$
9533The location information of the grouping made by the current rule.
9534@xref{Java Location Values}.
9535@end defvar
9536
9537@deffn {Statement} {return YYABORT;}
9538Return immediately from the parser, indicating failure.
9539@xref{Java Parser Interface}.
9540@end deffn
8405b70c 9541
e254a580
DJ
9542@deffn {Statement} {return YYACCEPT;}
9543Return immediately from the parser, indicating success.
9544@xref{Java Parser Interface}.
9545@end deffn
8405b70c 9546
e254a580 9547@deffn {Statement} {return YYERROR;}
c046698e 9548Start error recovery without printing an error message.
e254a580
DJ
9549@xref{Error Recovery}.
9550@end deffn
8405b70c 9551
e254a580
DJ
9552@deftypefn {Function} {boolean} recovering ()
9553Return whether error recovery is being done. In this state, the parser
9554reads token until it reaches a known state, and then restarts normal
9555operation.
9556@xref{Error Recovery}.
9557@end deftypefn
8405b70c 9558
e254a580
DJ
9559@deftypefn {Function} {protected void} yyerror (String msg)
9560@deftypefnx {Function} {protected void} yyerror (Position pos, String msg)
9561@deftypefnx {Function} {protected void} yyerror (Location loc, String msg)
9562Print an error message using the @code{yyerror} method of the scanner
9563instance in use.
9564@end deftypefn
8405b70c 9565
8405b70c 9566
8405b70c
PB
9567@node Java Differences
9568@subsection Differences between C/C++ and Java Grammars
9569
9570The different structure of the Java language forces several differences
9571between C/C++ grammars, and grammars designed for Java parsers. This
29553547 9572section summarizes these differences.
8405b70c
PB
9573
9574@itemize
9575@item
01b477c6 9576Java lacks a preprocessor, so the @code{YYERROR}, @code{YYACCEPT},
8405b70c 9577@code{YYABORT} symbols (@pxref{Table of Symbols}) cannot obviously be
01b477c6
PB
9578macros. Instead, they should be preceded by @code{return} when they
9579appear in an action. The actual definition of these symbols is
8405b70c
PB
9580opaque to the Bison grammar, and it might change in the future. The
9581only meaningful operation that you can do, is to return them.
e254a580 9582See @pxref{Java Action Features}.
8405b70c
PB
9583
9584Note that of these three symbols, only @code{YYACCEPT} and
9585@code{YYABORT} will cause a return from the @code{yyparse}
9586method@footnote{Java parsers include the actions in a separate
9587method than @code{yyparse} in order to have an intuitive syntax that
9588corresponds to these C macros.}.
9589
e254a580
DJ
9590@item
9591Java lacks unions, so @code{%union} has no effect. Instead, semantic
9592values have a common base type: @code{Object} or as specified by
c781580d 9593@samp{%define stype}. Angle brackets on @code{%token}, @code{type},
e254a580
DJ
9594@code{$@var{n}} and @code{$$} specify subtypes rather than fields of
9595an union. The type of @code{$$}, even with angle brackets, is the base
9596type since Java casts are not allow on the left-hand side of assignments.
9597Also, @code{$@var{n}} and @code{@@@var{n}} are not allowed on the
9598left-hand side of assignments. See @pxref{Java Semantic Values} and
9599@pxref{Java Action Features}.
9600
8405b70c 9601@item
c781580d 9602The prologue declarations have a different meaning than in C/C++ code.
01b477c6
PB
9603@table @asis
9604@item @code{%code imports}
9605blocks are placed at the beginning of the Java source code. They may
9606include copyright notices. For a @code{package} declarations, it is
9607suggested to use @code{%define package} instead.
8405b70c 9608
01b477c6
PB
9609@item unqualified @code{%code}
9610blocks are placed inside the parser class.
9611
9612@item @code{%code lexer}
9613blocks, if specified, should include the implementation of the
9614scanner. If there is no such block, the scanner can be any class
9615that implements the appropriate interface (see @pxref{Java Scanner
9616Interface}).
29553547 9617@end table
8405b70c
PB
9618
9619Other @code{%code} blocks are not supported in Java parsers.
e254a580
DJ
9620In particular, @code{%@{ @dots{} %@}} blocks should not be used
9621and may give an error in future versions of Bison.
9622
01b477c6 9623The epilogue has the same meaning as in C/C++ code and it can
e254a580
DJ
9624be used to define other classes used by the parser @emph{outside}
9625the parser class.
8405b70c
PB
9626@end itemize
9627
e254a580
DJ
9628
9629@node Java Declarations Summary
9630@subsection Java Declarations Summary
9631
9632This summary only include declarations specific to Java or have special
9633meaning when used in a Java parser.
9634
9635@deffn {Directive} {%language "Java"}
9636Generate a Java class for the parser.
9637@end deffn
9638
9639@deffn {Directive} %lex-param @{@var{type} @var{name}@}
9640A parameter for the lexer class defined by @code{%code lexer}
9641@emph{only}, added as parameters to the lexer constructor and the parser
9642constructor that @emph{creates} a lexer. Default is none.
9643@xref{Java Scanner Interface}.
9644@end deffn
9645
9646@deffn {Directive} %name-prefix "@var{prefix}"
9647The prefix of the parser class name @code{@var{prefix}Parser} if
9648@code{%define parser_class_name} is not used. Default is @code{YY}.
9649@xref{Java Bison Interface}.
9650@end deffn
9651
9652@deffn {Directive} %parse-param @{@var{type} @var{name}@}
9653A parameter for the parser class added as parameters to constructor(s)
9654and as fields initialized by the constructor(s). Default is none.
9655@xref{Java Parser Interface}.
9656@end deffn
9657
9658@deffn {Directive} %token <@var{type}> @var{token} @dots{}
9659Declare tokens. Note that the angle brackets enclose a Java @emph{type}.
9660@xref{Java Semantic Values}.
9661@end deffn
9662
9663@deffn {Directive} %type <@var{type}> @var{nonterminal} @dots{}
9664Declare the type of nonterminals. Note that the angle brackets enclose
9665a Java @emph{type}.
9666@xref{Java Semantic Values}.
9667@end deffn
9668
9669@deffn {Directive} %code @{ @var{code} @dots{} @}
9670Code appended to the inside of the parser class.
9671@xref{Java Differences}.
9672@end deffn
9673
9674@deffn {Directive} {%code imports} @{ @var{code} @dots{} @}
9675Code inserted just after the @code{package} declaration.
9676@xref{Java Differences}.
9677@end deffn
9678
9679@deffn {Directive} {%code lexer} @{ @var{code} @dots{} @}
9680Code added to the body of a inner lexer class within the parser class.
9681@xref{Java Scanner Interface}.
9682@end deffn
9683
9684@deffn {Directive} %% @var{code} @dots{}
9685Code (after the second @code{%%}) appended to the end of the file,
9686@emph{outside} the parser class.
9687@xref{Java Differences}.
9688@end deffn
9689
9690@deffn {Directive} %@{ @var{code} @dots{} %@}
9691Not supported. Use @code{%code import} instead.
9692@xref{Java Differences}.
9693@end deffn
9694
9695@deffn {Directive} {%define abstract}
9696Whether the parser class is declared @code{abstract}. Default is false.
9697@xref{Java Bison Interface}.
9698@end deffn
9699
9700@deffn {Directive} {%define extends} "@var{superclass}"
9701The superclass of the parser class. Default is none.
9702@xref{Java Bison Interface}.
9703@end deffn
9704
9705@deffn {Directive} {%define final}
9706Whether the parser class is declared @code{final}. Default is false.
9707@xref{Java Bison Interface}.
9708@end deffn
9709
9710@deffn {Directive} {%define implements} "@var{interfaces}"
9711The implemented interfaces of the parser class, a comma-separated list.
9712Default is none.
9713@xref{Java Bison Interface}.
9714@end deffn
9715
9716@deffn {Directive} {%define lex_throws} "@var{exceptions}"
9717The exceptions thrown by the @code{yylex} method of the lexer, a
9718comma-separated list. Default is @code{java.io.IOException}.
9719@xref{Java Scanner Interface}.
9720@end deffn
9721
9722@deffn {Directive} {%define location_type} "@var{class}"
9723The name of the class used for locations (a range between two
9724positions). This class is generated as an inner class of the parser
9725class by @command{bison}. Default is @code{Location}.
9726@xref{Java Location Values}.
9727@end deffn
9728
9729@deffn {Directive} {%define package} "@var{package}"
9730The package to put the parser class in. Default is none.
9731@xref{Java Bison Interface}.
9732@end deffn
9733
9734@deffn {Directive} {%define parser_class_name} "@var{name}"
9735The name of the parser class. Default is @code{YYParser} or
9736@code{@var{name-prefix}Parser}.
9737@xref{Java Bison Interface}.
9738@end deffn
9739
9740@deffn {Directive} {%define position_type} "@var{class}"
9741The name of the class used for positions. This class must be supplied by
9742the user. Default is @code{Position}.
9743@xref{Java Location Values}.
9744@end deffn
9745
9746@deffn {Directive} {%define public}
9747Whether the parser class is declared @code{public}. Default is false.
9748@xref{Java Bison Interface}.
9749@end deffn
9750
9751@deffn {Directive} {%define stype} "@var{class}"
9752The base type of semantic values. Default is @code{Object}.
9753@xref{Java Semantic Values}.
9754@end deffn
9755
9756@deffn {Directive} {%define strictfp}
9757Whether the parser class is declared @code{strictfp}. Default is false.
9758@xref{Java Bison Interface}.
9759@end deffn
9760
9761@deffn {Directive} {%define throws} "@var{exceptions}"
9762The exceptions thrown by user-supplied parser actions and
9763@code{%initial-action}, a comma-separated list. Default is none.
9764@xref{Java Parser Interface}.
9765@end deffn
9766
9767
12545799 9768@c ================================================= FAQ
d1a1114f
AD
9769
9770@node FAQ
9771@chapter Frequently Asked Questions
9772@cindex frequently asked questions
9773@cindex questions
9774
9775Several questions about Bison come up occasionally. Here some of them
9776are addressed.
9777
9778@menu
55ba27be
AD
9779* Memory Exhausted:: Breaking the Stack Limits
9780* How Can I Reset the Parser:: @code{yyparse} Keeps some State
9781* Strings are Destroyed:: @code{yylval} Loses Track of Strings
9782* Implementing Gotos/Loops:: Control Flow in the Calculator
ed2e6384 9783* Multiple start-symbols:: Factoring closely related grammars
35430378 9784* Secure? Conform?:: Is Bison POSIX safe?
55ba27be
AD
9785* I can't build Bison:: Troubleshooting
9786* Where can I find help?:: Troubleshouting
9787* Bug Reports:: Troublereporting
8405b70c 9788* More Languages:: Parsers in C++, Java, and so on
55ba27be
AD
9789* Beta Testing:: Experimenting development versions
9790* Mailing Lists:: Meeting other Bison users
d1a1114f
AD
9791@end menu
9792
1a059451
PE
9793@node Memory Exhausted
9794@section Memory Exhausted
d1a1114f
AD
9795
9796@display
1a059451 9797My parser returns with error with a @samp{memory exhausted}
d1a1114f
AD
9798message. What can I do?
9799@end display
9800
9801This question is already addressed elsewhere, @xref{Recursion,
9802,Recursive Rules}.
9803
e64fec0a
PE
9804@node How Can I Reset the Parser
9805@section How Can I Reset the Parser
5b066063 9806
0e14ad77
PE
9807The following phenomenon has several symptoms, resulting in the
9808following typical questions:
5b066063
AD
9809
9810@display
9811I invoke @code{yyparse} several times, and on correct input it works
9812properly; but when a parse error is found, all the other calls fail
0e14ad77 9813too. How can I reset the error flag of @code{yyparse}?
5b066063
AD
9814@end display
9815
9816@noindent
9817or
9818
9819@display
0e14ad77 9820My parser includes support for an @samp{#include}-like feature, in
5b066063 9821which case I run @code{yyparse} from @code{yyparse}. This fails
d9df47b6 9822although I did specify @code{%define api.pure}.
5b066063
AD
9823@end display
9824
0e14ad77
PE
9825These problems typically come not from Bison itself, but from
9826Lex-generated scanners. Because these scanners use large buffers for
5b066063
AD
9827speed, they might not notice a change of input file. As a
9828demonstration, consider the following source file,
9829@file{first-line.l}:
9830
9831@verbatim
9832%{
9833#include <stdio.h>
9834#include <stdlib.h>
9835%}
9836%%
9837.*\n ECHO; return 1;
9838%%
9839int
0e14ad77 9840yyparse (char const *file)
5b066063
AD
9841{
9842 yyin = fopen (file, "r");
9843 if (!yyin)
9844 exit (2);
fa7e68c3 9845 /* One token only. */
5b066063 9846 yylex ();
0e14ad77 9847 if (fclose (yyin) != 0)
5b066063
AD
9848 exit (3);
9849 return 0;
9850}
9851
9852int
0e14ad77 9853main (void)
5b066063
AD
9854{
9855 yyparse ("input");
9856 yyparse ("input");
9857 return 0;
9858}
9859@end verbatim
9860
9861@noindent
9862If the file @file{input} contains
9863
9864@verbatim
9865input:1: Hello,
9866input:2: World!
9867@end verbatim
9868
9869@noindent
0e14ad77 9870then instead of getting the first line twice, you get:
5b066063
AD
9871
9872@example
9873$ @kbd{flex -ofirst-line.c first-line.l}
9874$ @kbd{gcc -ofirst-line first-line.c -ll}
9875$ @kbd{./first-line}
9876input:1: Hello,
9877input:2: World!
9878@end example
9879
0e14ad77
PE
9880Therefore, whenever you change @code{yyin}, you must tell the
9881Lex-generated scanner to discard its current buffer and switch to the
9882new one. This depends upon your implementation of Lex; see its
9883documentation for more. For Flex, it suffices to call
9884@samp{YY_FLUSH_BUFFER} after each change to @code{yyin}. If your
9885Flex-generated scanner needs to read from several input streams to
9886handle features like include files, you might consider using Flex
9887functions like @samp{yy_switch_to_buffer} that manipulate multiple
9888input buffers.
5b066063 9889
b165c324
AD
9890If your Flex-generated scanner uses start conditions (@pxref{Start
9891conditions, , Start conditions, flex, The Flex Manual}), you might
9892also want to reset the scanner's state, i.e., go back to the initial
9893start condition, through a call to @samp{BEGIN (0)}.
9894
fef4cb51
AD
9895@node Strings are Destroyed
9896@section Strings are Destroyed
9897
9898@display
c7e441b4 9899My parser seems to destroy old strings, or maybe it loses track of
fef4cb51
AD
9900them. Instead of reporting @samp{"foo", "bar"}, it reports
9901@samp{"bar", "bar"}, or even @samp{"foo\nbar", "bar"}.
9902@end display
9903
9904This error is probably the single most frequent ``bug report'' sent to
9905Bison lists, but is only concerned with a misunderstanding of the role
8c5b881d 9906of the scanner. Consider the following Lex code:
fef4cb51
AD
9907
9908@verbatim
9909%{
9910#include <stdio.h>
9911char *yylval = NULL;
9912%}
9913%%
9914.* yylval = yytext; return 1;
9915\n /* IGNORE */
9916%%
9917int
9918main ()
9919{
fa7e68c3 9920 /* Similar to using $1, $2 in a Bison action. */
fef4cb51
AD
9921 char *fst = (yylex (), yylval);
9922 char *snd = (yylex (), yylval);
9923 printf ("\"%s\", \"%s\"\n", fst, snd);
9924 return 0;
9925}
9926@end verbatim
9927
9928If you compile and run this code, you get:
9929
9930@example
9931$ @kbd{flex -osplit-lines.c split-lines.l}
9932$ @kbd{gcc -osplit-lines split-lines.c -ll}
9933$ @kbd{printf 'one\ntwo\n' | ./split-lines}
9934"one
9935two", "two"
9936@end example
9937
9938@noindent
9939this is because @code{yytext} is a buffer provided for @emph{reading}
9940in the action, but if you want to keep it, you have to duplicate it
9941(e.g., using @code{strdup}). Note that the output may depend on how
9942your implementation of Lex handles @code{yytext}. For instance, when
9943given the Lex compatibility option @option{-l} (which triggers the
9944option @samp{%array}) Flex generates a different behavior:
9945
9946@example
9947$ @kbd{flex -l -osplit-lines.c split-lines.l}
9948$ @kbd{gcc -osplit-lines split-lines.c -ll}
9949$ @kbd{printf 'one\ntwo\n' | ./split-lines}
9950"two", "two"
9951@end example
9952
9953
2fa09258
AD
9954@node Implementing Gotos/Loops
9955@section Implementing Gotos/Loops
a06ea4aa
AD
9956
9957@display
9958My simple calculator supports variables, assignments, and functions,
2fa09258 9959but how can I implement gotos, or loops?
a06ea4aa
AD
9960@end display
9961
9962Although very pedagogical, the examples included in the document blur
a1c84f45 9963the distinction to make between the parser---whose job is to recover
a06ea4aa 9964the structure of a text and to transmit it to subsequent modules of
a1c84f45 9965the program---and the processing (such as the execution) of this
a06ea4aa
AD
9966structure. This works well with so called straight line programs,
9967i.e., precisely those that have a straightforward execution model:
9968execute simple instructions one after the others.
9969
9970@cindex abstract syntax tree
35430378 9971@cindex AST
a06ea4aa
AD
9972If you want a richer model, you will probably need to use the parser
9973to construct a tree that does represent the structure it has
9974recovered; this tree is usually called the @dfn{abstract syntax tree},
35430378 9975or @dfn{AST} for short. Then, walking through this tree,
a06ea4aa
AD
9976traversing it in various ways, will enable treatments such as its
9977execution or its translation, which will result in an interpreter or a
9978compiler.
9979
9980This topic is way beyond the scope of this manual, and the reader is
9981invited to consult the dedicated literature.
9982
9983
ed2e6384
AD
9984@node Multiple start-symbols
9985@section Multiple start-symbols
9986
9987@display
9988I have several closely related grammars, and I would like to share their
9989implementations. In fact, I could use a single grammar but with
9990multiple entry points.
9991@end display
9992
9993Bison does not support multiple start-symbols, but there is a very
9994simple means to simulate them. If @code{foo} and @code{bar} are the two
9995pseudo start-symbols, then introduce two new tokens, say
9996@code{START_FOO} and @code{START_BAR}, and use them as switches from the
9997real start-symbol:
9998
9999@example
10000%token START_FOO START_BAR;
10001%start start;
10002start: START_FOO foo
10003 | START_BAR bar;
10004@end example
10005
10006These tokens prevents the introduction of new conflicts. As far as the
10007parser goes, that is all that is needed.
10008
10009Now the difficult part is ensuring that the scanner will send these
10010tokens first. If your scanner is hand-written, that should be
10011straightforward. If your scanner is generated by Lex, them there is
10012simple means to do it: recall that anything between @samp{%@{ ... %@}}
10013after the first @code{%%} is copied verbatim in the top of the generated
10014@code{yylex} function. Make sure a variable @code{start_token} is
10015available in the scanner (e.g., a global variable or using
10016@code{%lex-param} etc.), and use the following:
10017
10018@example
10019 /* @r{Prologue.} */
10020%%
10021%@{
10022 if (start_token)
10023 @{
10024 int t = start_token;
10025 start_token = 0;
10026 return t;
10027 @}
10028%@}
10029 /* @r{The rules.} */
10030@end example
10031
10032
55ba27be
AD
10033@node Secure? Conform?
10034@section Secure? Conform?
10035
10036@display
10037Is Bison secure? Does it conform to POSIX?
10038@end display
10039
10040If you're looking for a guarantee or certification, we don't provide it.
10041However, Bison is intended to be a reliable program that conforms to the
35430378 10042POSIX specification for Yacc. If you run into problems,
55ba27be
AD
10043please send us a bug report.
10044
10045@node I can't build Bison
10046@section I can't build Bison
10047
10048@display
8c5b881d
PE
10049I can't build Bison because @command{make} complains that
10050@code{msgfmt} is not found.
55ba27be
AD
10051What should I do?
10052@end display
10053
10054Like most GNU packages with internationalization support, that feature
10055is turned on by default. If you have problems building in the @file{po}
10056subdirectory, it indicates that your system's internationalization
10057support is lacking. You can re-configure Bison with
10058@option{--disable-nls} to turn off this support, or you can install GNU
10059gettext from @url{ftp://ftp.gnu.org/gnu/gettext/} and re-configure
10060Bison. See the file @file{ABOUT-NLS} for more information.
10061
10062
10063@node Where can I find help?
10064@section Where can I find help?
10065
10066@display
10067I'm having trouble using Bison. Where can I find help?
10068@end display
10069
10070First, read this fine manual. Beyond that, you can send mail to
10071@email{help-bison@@gnu.org}. This mailing list is intended to be
10072populated with people who are willing to answer questions about using
10073and installing Bison. Please keep in mind that (most of) the people on
10074the list have aspects of their lives which are not related to Bison (!),
10075so you may not receive an answer to your question right away. This can
10076be frustrating, but please try not to honk them off; remember that any
10077help they provide is purely voluntary and out of the kindness of their
10078hearts.
10079
10080@node Bug Reports
10081@section Bug Reports
10082
10083@display
10084I found a bug. What should I include in the bug report?
10085@end display
10086
10087Before you send a bug report, make sure you are using the latest
10088version. Check @url{ftp://ftp.gnu.org/pub/gnu/bison/} or one of its
10089mirrors. Be sure to include the version number in your bug report. If
10090the bug is present in the latest version but not in a previous version,
10091try to determine the most recent version which did not contain the bug.
10092
10093If the bug is parser-related, you should include the smallest grammar
10094you can which demonstrates the bug. The grammar file should also be
10095complete (i.e., I should be able to run it through Bison without having
10096to edit or add anything). The smaller and simpler the grammar, the
10097easier it will be to fix the bug.
10098
10099Include information about your compilation environment, including your
10100operating system's name and version and your compiler's name and
10101version. If you have trouble compiling, you should also include a
10102transcript of the build session, starting with the invocation of
10103`configure'. Depending on the nature of the bug, you may be asked to
10104send additional files as well (such as `config.h' or `config.cache').
10105
10106Patches are most welcome, but not required. That is, do not hesitate to
10107send a bug report just because you can not provide a fix.
10108
10109Send bug reports to @email{bug-bison@@gnu.org}.
10110
8405b70c
PB
10111@node More Languages
10112@section More Languages
55ba27be
AD
10113
10114@display
8405b70c 10115Will Bison ever have C++ and Java support? How about @var{insert your
55ba27be
AD
10116favorite language here}?
10117@end display
10118
8405b70c 10119C++ and Java support is there now, and is documented. We'd love to add other
55ba27be
AD
10120languages; contributions are welcome.
10121
10122@node Beta Testing
10123@section Beta Testing
10124
10125@display
10126What is involved in being a beta tester?
10127@end display
10128
10129It's not terribly involved. Basically, you would download a test
10130release, compile it, and use it to build and run a parser or two. After
10131that, you would submit either a bug report or a message saying that
10132everything is okay. It is important to report successes as well as
10133failures because test releases eventually become mainstream releases,
10134but only if they are adequately tested. If no one tests, development is
10135essentially halted.
10136
10137Beta testers are particularly needed for operating systems to which the
10138developers do not have easy access. They currently have easy access to
10139recent GNU/Linux and Solaris versions. Reports about other operating
10140systems are especially welcome.
10141
10142@node Mailing Lists
10143@section Mailing Lists
10144
10145@display
10146How do I join the help-bison and bug-bison mailing lists?
10147@end display
10148
10149See @url{http://lists.gnu.org/}.
a06ea4aa 10150
d1a1114f
AD
10151@c ================================================= Table of Symbols
10152
342b8b6e 10153@node Table of Symbols
bfa74976
RS
10154@appendix Bison Symbols
10155@cindex Bison symbols, table of
10156@cindex symbols in Bison, table of
10157
18b519c0 10158@deffn {Variable} @@$
3ded9a63 10159In an action, the location of the left-hand side of the rule.
88bce5a2 10160@xref{Locations, , Locations Overview}.
18b519c0 10161@end deffn
3ded9a63 10162
18b519c0 10163@deffn {Variable} @@@var{n}
3ded9a63
AD
10164In an action, the location of the @var{n}-th symbol of the right-hand
10165side of the rule. @xref{Locations, , Locations Overview}.
18b519c0 10166@end deffn
3ded9a63 10167
1f68dca5
AR
10168@deffn {Variable} @@@var{name}
10169In an action, the location of a symbol addressed by name.
10170@xref{Locations, , Locations Overview}.
10171@end deffn
10172
10173@deffn {Variable} @@[@var{name}]
10174In an action, the location of a symbol addressed by name.
10175@xref{Locations, , Locations Overview}.
10176@end deffn
10177
18b519c0 10178@deffn {Variable} $$
3ded9a63
AD
10179In an action, the semantic value of the left-hand side of the rule.
10180@xref{Actions}.
18b519c0 10181@end deffn
3ded9a63 10182
18b519c0 10183@deffn {Variable} $@var{n}
3ded9a63
AD
10184In an action, the semantic value of the @var{n}-th symbol of the
10185right-hand side of the rule. @xref{Actions}.
18b519c0 10186@end deffn
3ded9a63 10187
1f68dca5
AR
10188@deffn {Variable} $@var{name}
10189In an action, the semantic value of a symbol addressed by name.
10190@xref{Actions}.
10191@end deffn
10192
10193@deffn {Variable} $[@var{name}]
10194In an action, the semantic value of a symbol addressed by name.
10195@xref{Actions}.
10196@end deffn
10197
dd8d9022
AD
10198@deffn {Delimiter} %%
10199Delimiter used to separate the grammar rule section from the
10200Bison declarations section or the epilogue.
10201@xref{Grammar Layout, ,The Overall Layout of a Bison Grammar}.
18b519c0 10202@end deffn
bfa74976 10203
dd8d9022
AD
10204@c Don't insert spaces, or check the DVI output.
10205@deffn {Delimiter} %@{@var{code}%@}
9913d6e4
JD
10206All code listed between @samp{%@{} and @samp{%@}} is copied verbatim
10207to the parser implementation file. Such code forms the prologue of
10208the grammar file. @xref{Grammar Outline, ,Outline of a Bison
dd8d9022 10209Grammar}.
18b519c0 10210@end deffn
bfa74976 10211
dd8d9022
AD
10212@deffn {Construct} /*@dots{}*/
10213Comment delimiters, as in C.
18b519c0 10214@end deffn
bfa74976 10215
dd8d9022
AD
10216@deffn {Delimiter} :
10217Separates a rule's result from its components. @xref{Rules, ,Syntax of
10218Grammar Rules}.
18b519c0 10219@end deffn
bfa74976 10220
dd8d9022
AD
10221@deffn {Delimiter} ;
10222Terminates a rule. @xref{Rules, ,Syntax of Grammar Rules}.
18b519c0 10223@end deffn
bfa74976 10224
dd8d9022
AD
10225@deffn {Delimiter} |
10226Separates alternate rules for the same result nonterminal.
10227@xref{Rules, ,Syntax of Grammar Rules}.
18b519c0 10228@end deffn
bfa74976 10229
12e35840
JD
10230@deffn {Directive} <*>
10231Used to define a default tagged @code{%destructor} or default tagged
10232@code{%printer}.
85894313
JD
10233
10234This feature is experimental.
10235More user feedback will help to determine whether it should become a permanent
10236feature.
10237
12e35840
JD
10238@xref{Destructor Decl, , Freeing Discarded Symbols}.
10239@end deffn
10240
3ebecc24 10241@deffn {Directive} <>
12e35840
JD
10242Used to define a default tagless @code{%destructor} or default tagless
10243@code{%printer}.
85894313
JD
10244
10245This feature is experimental.
10246More user feedback will help to determine whether it should become a permanent
10247feature.
10248
12e35840
JD
10249@xref{Destructor Decl, , Freeing Discarded Symbols}.
10250@end deffn
10251
dd8d9022
AD
10252@deffn {Symbol} $accept
10253The predefined nonterminal whose only rule is @samp{$accept: @var{start}
10254$end}, where @var{start} is the start symbol. @xref{Start Decl, , The
10255Start-Symbol}. It cannot be used in the grammar.
18b519c0 10256@end deffn
bfa74976 10257
136a0f76 10258@deffn {Directive} %code @{@var{code}@}
148d66d8 10259@deffnx {Directive} %code @var{qualifier} @{@var{code}@}
406dec82
JD
10260Insert @var{code} verbatim into the output parser source at the
10261default location or at the location specified by @var{qualifier}.
8e6f2266 10262@xref{%code Summary}.
9bc0dd67 10263@end deffn
9bc0dd67 10264
18b519c0 10265@deffn {Directive} %debug
6deb4447 10266Equip the parser for debugging. @xref{Decl Summary}.
18b519c0 10267@end deffn
6deb4447 10268
91d2c560 10269@ifset defaultprec
22fccf95
PE
10270@deffn {Directive} %default-prec
10271Assign a precedence to rules that lack an explicit @samp{%prec}
10272modifier. @xref{Contextual Precedence, ,Context-Dependent
10273Precedence}.
39a06c25 10274@end deffn
91d2c560 10275@end ifset
39a06c25 10276
148d66d8
JD
10277@deffn {Directive} %define @var{define-variable}
10278@deffnx {Directive} %define @var{define-variable} @var{value}
f37495f6 10279@deffnx {Directive} %define @var{define-variable} "@var{value}"
2f4518a1 10280Define a variable to adjust Bison's behavior. @xref{%define Summary}.
148d66d8
JD
10281@end deffn
10282
18b519c0 10283@deffn {Directive} %defines
9913d6e4
JD
10284Bison declaration to create a parser header file, which is usually
10285meant for the scanner. @xref{Decl Summary}.
18b519c0 10286@end deffn
6deb4447 10287
02975b9a
JD
10288@deffn {Directive} %defines @var{defines-file}
10289Same as above, but save in the file @var{defines-file}.
10290@xref{Decl Summary}.
10291@end deffn
10292
18b519c0 10293@deffn {Directive} %destructor
258b75ca 10294Specify how the parser should reclaim the memory associated to
fa7e68c3 10295discarded symbols. @xref{Destructor Decl, , Freeing Discarded Symbols}.
18b519c0 10296@end deffn
72f889cc 10297
18b519c0 10298@deffn {Directive} %dprec
676385e2 10299Bison declaration to assign a precedence to a rule that is used at parse
c827f760 10300time to resolve reduce/reduce conflicts. @xref{GLR Parsers, ,Writing
35430378 10301GLR Parsers}.
18b519c0 10302@end deffn
676385e2 10303
dd8d9022
AD
10304@deffn {Symbol} $end
10305The predefined token marking the end of the token stream. It cannot be
10306used in the grammar.
10307@end deffn
10308
10309@deffn {Symbol} error
10310A token name reserved for error recovery. This token may be used in
10311grammar rules so as to allow the Bison parser to recognize an error in
10312the grammar without halting the process. In effect, a sentence
10313containing an error may be recognized as valid. On a syntax error, the
742e4900
JD
10314token @code{error} becomes the current lookahead token. Actions
10315corresponding to @code{error} are then executed, and the lookahead
dd8d9022
AD
10316token is reset to the token that originally caused the violation.
10317@xref{Error Recovery}.
18d192f0
AD
10318@end deffn
10319
18b519c0 10320@deffn {Directive} %error-verbose
2a8d363a
AD
10321Bison declaration to request verbose, specific error message strings
10322when @code{yyerror} is called.
18b519c0 10323@end deffn
2a8d363a 10324
02975b9a 10325@deffn {Directive} %file-prefix "@var{prefix}"
72d2299c 10326Bison declaration to set the prefix of the output files. @xref{Decl
d8988b2f 10327Summary}.
18b519c0 10328@end deffn
d8988b2f 10329
18b519c0 10330@deffn {Directive} %glr-parser
35430378
JD
10331Bison declaration to produce a GLR parser. @xref{GLR
10332Parsers, ,Writing GLR Parsers}.
18b519c0 10333@end deffn
676385e2 10334
dd8d9022
AD
10335@deffn {Directive} %initial-action
10336Run user code before parsing. @xref{Initial Action Decl, , Performing Actions before Parsing}.
10337@end deffn
10338
e6e704dc
JD
10339@deffn {Directive} %language
10340Specify the programming language for the generated parser.
10341@xref{Decl Summary}.
10342@end deffn
10343
18b519c0 10344@deffn {Directive} %left
bfa74976
RS
10345Bison declaration to assign left associativity to token(s).
10346@xref{Precedence Decl, ,Operator Precedence}.
18b519c0 10347@end deffn
bfa74976 10348
feeb0eda 10349@deffn {Directive} %lex-param @{@var{argument-declaration}@}
2a8d363a
AD
10350Bison declaration to specifying an additional parameter that
10351@code{yylex} should accept. @xref{Pure Calling,, Calling Conventions
10352for Pure Parsers}.
18b519c0 10353@end deffn
2a8d363a 10354
18b519c0 10355@deffn {Directive} %merge
676385e2 10356Bison declaration to assign a merging function to a rule. If there is a
fae437e8 10357reduce/reduce conflict with a rule having the same merging function, the
676385e2 10358function is applied to the two semantic values to get a single result.
35430378 10359@xref{GLR Parsers, ,Writing GLR Parsers}.
18b519c0 10360@end deffn
676385e2 10361
02975b9a 10362@deffn {Directive} %name-prefix "@var{prefix}"
72d2299c 10363Bison declaration to rename the external symbols. @xref{Decl Summary}.
18b519c0 10364@end deffn
d8988b2f 10365
91d2c560 10366@ifset defaultprec
22fccf95
PE
10367@deffn {Directive} %no-default-prec
10368Do not assign a precedence to rules that lack an explicit @samp{%prec}
10369modifier. @xref{Contextual Precedence, ,Context-Dependent
10370Precedence}.
10371@end deffn
91d2c560 10372@end ifset
22fccf95 10373
18b519c0 10374@deffn {Directive} %no-lines
931c7513 10375Bison declaration to avoid generating @code{#line} directives in the
9913d6e4 10376parser implementation file. @xref{Decl Summary}.
18b519c0 10377@end deffn
931c7513 10378
18b519c0 10379@deffn {Directive} %nonassoc
9d9b8b70 10380Bison declaration to assign nonassociativity to token(s).
bfa74976 10381@xref{Precedence Decl, ,Operator Precedence}.
18b519c0 10382@end deffn
bfa74976 10383
02975b9a 10384@deffn {Directive} %output "@var{file}"
9913d6e4
JD
10385Bison declaration to set the name of the parser implementation file.
10386@xref{Decl Summary}.
18b519c0 10387@end deffn
d8988b2f 10388
feeb0eda 10389@deffn {Directive} %parse-param @{@var{argument-declaration}@}
2a8d363a
AD
10390Bison declaration to specifying an additional parameter that
10391@code{yyparse} should accept. @xref{Parser Function,, The Parser
10392Function @code{yyparse}}.
18b519c0 10393@end deffn
2a8d363a 10394
18b519c0 10395@deffn {Directive} %prec
bfa74976
RS
10396Bison declaration to assign a precedence to a specific rule.
10397@xref{Contextual Precedence, ,Context-Dependent Precedence}.
18b519c0 10398@end deffn
bfa74976 10399
18b519c0 10400@deffn {Directive} %pure-parser
2f4518a1
JD
10401Deprecated version of @code{%define api.pure} (@pxref{%define
10402Summary,,api.pure}), for which Bison is more careful to warn about
10403unreasonable usage.
18b519c0 10404@end deffn
bfa74976 10405
b50d2359 10406@deffn {Directive} %require "@var{version}"
9b8a5ce0
AD
10407Require version @var{version} or higher of Bison. @xref{Require Decl, ,
10408Require a Version of Bison}.
b50d2359
AD
10409@end deffn
10410
18b519c0 10411@deffn {Directive} %right
bfa74976
RS
10412Bison declaration to assign right associativity to token(s).
10413@xref{Precedence Decl, ,Operator Precedence}.
18b519c0 10414@end deffn
bfa74976 10415
e6e704dc
JD
10416@deffn {Directive} %skeleton
10417Specify the skeleton to use; usually for development.
10418@xref{Decl Summary}.
10419@end deffn
10420
18b519c0 10421@deffn {Directive} %start
704a47c4
AD
10422Bison declaration to specify the start symbol. @xref{Start Decl, ,The
10423Start-Symbol}.
18b519c0 10424@end deffn
bfa74976 10425
18b519c0 10426@deffn {Directive} %token
bfa74976
RS
10427Bison declaration to declare token(s) without specifying precedence.
10428@xref{Token Decl, ,Token Type Names}.
18b519c0 10429@end deffn
bfa74976 10430
18b519c0 10431@deffn {Directive} %token-table
9913d6e4
JD
10432Bison declaration to include a token name table in the parser
10433implementation file. @xref{Decl Summary}.
18b519c0 10434@end deffn
931c7513 10435
18b519c0 10436@deffn {Directive} %type
704a47c4
AD
10437Bison declaration to declare nonterminals. @xref{Type Decl,
10438,Nonterminal Symbols}.
18b519c0 10439@end deffn
bfa74976 10440
dd8d9022
AD
10441@deffn {Symbol} $undefined
10442The predefined token onto which all undefined values returned by
10443@code{yylex} are mapped. It cannot be used in the grammar, rather, use
10444@code{error}.
10445@end deffn
10446
18b519c0 10447@deffn {Directive} %union
bfa74976
RS
10448Bison declaration to specify several possible data types for semantic
10449values. @xref{Union Decl, ,The Collection of Value Types}.
18b519c0 10450@end deffn
bfa74976 10451
dd8d9022
AD
10452@deffn {Macro} YYABORT
10453Macro to pretend that an unrecoverable syntax error has occurred, by
10454making @code{yyparse} return 1 immediately. The error reporting
10455function @code{yyerror} is not called. @xref{Parser Function, ,The
10456Parser Function @code{yyparse}}.
8405b70c
PB
10457
10458For Java parsers, this functionality is invoked using @code{return YYABORT;}
10459instead.
dd8d9022 10460@end deffn
3ded9a63 10461
dd8d9022
AD
10462@deffn {Macro} YYACCEPT
10463Macro to pretend that a complete utterance of the language has been
10464read, by making @code{yyparse} return 0 immediately.
10465@xref{Parser Function, ,The Parser Function @code{yyparse}}.
8405b70c
PB
10466
10467For Java parsers, this functionality is invoked using @code{return YYACCEPT;}
10468instead.
dd8d9022 10469@end deffn
bfa74976 10470
dd8d9022 10471@deffn {Macro} YYBACKUP
742e4900 10472Macro to discard a value from the parser stack and fake a lookahead
dd8d9022 10473token. @xref{Action Features, ,Special Features for Use in Actions}.
18b519c0 10474@end deffn
bfa74976 10475
dd8d9022 10476@deffn {Variable} yychar
32c29292 10477External integer variable that contains the integer value of the
742e4900 10478lookahead token. (In a pure parser, it is a local variable within
dd8d9022
AD
10479@code{yyparse}.) Error-recovery rule actions may examine this variable.
10480@xref{Action Features, ,Special Features for Use in Actions}.
18b519c0 10481@end deffn
bfa74976 10482
dd8d9022
AD
10483@deffn {Variable} yyclearin
10484Macro used in error-recovery rule actions. It clears the previous
742e4900 10485lookahead token. @xref{Error Recovery}.
18b519c0 10486@end deffn
bfa74976 10487
dd8d9022
AD
10488@deffn {Macro} YYDEBUG
10489Macro to define to equip the parser with tracing code. @xref{Tracing,
10490,Tracing Your Parser}.
18b519c0 10491@end deffn
bfa74976 10492
dd8d9022
AD
10493@deffn {Variable} yydebug
10494External integer variable set to zero by default. If @code{yydebug}
10495is given a nonzero value, the parser will output information on input
10496symbols and parser action. @xref{Tracing, ,Tracing Your Parser}.
18b519c0 10497@end deffn
bfa74976 10498
dd8d9022
AD
10499@deffn {Macro} yyerrok
10500Macro to cause parser to recover immediately to its normal mode
10501after a syntax error. @xref{Error Recovery}.
10502@end deffn
10503
10504@deffn {Macro} YYERROR
10505Macro to pretend that a syntax error has just been detected: call
10506@code{yyerror} and then perform normal error recovery if possible
10507(@pxref{Error Recovery}), or (if recovery is impossible) make
10508@code{yyparse} return 1. @xref{Error Recovery}.
8405b70c
PB
10509
10510For Java parsers, this functionality is invoked using @code{return YYERROR;}
10511instead.
dd8d9022
AD
10512@end deffn
10513
10514@deffn {Function} yyerror
10515User-supplied function to be called by @code{yyparse} on error.
10516@xref{Error Reporting, ,The Error
10517Reporting Function @code{yyerror}}.
10518@end deffn
10519
10520@deffn {Macro} YYERROR_VERBOSE
10521An obsolete macro that you define with @code{#define} in the prologue
10522to request verbose, specific error message strings
10523when @code{yyerror} is called. It doesn't matter what definition you
10524use for @code{YYERROR_VERBOSE}, just whether you define it. Using
10525@code{%error-verbose} is preferred.
10526@end deffn
10527
10528@deffn {Macro} YYINITDEPTH
10529Macro for specifying the initial size of the parser stack.
1a059451 10530@xref{Memory Management}.
dd8d9022
AD
10531@end deffn
10532
10533@deffn {Function} yylex
10534User-supplied lexical analyzer function, called with no arguments to get
10535the next token. @xref{Lexical, ,The Lexical Analyzer Function
10536@code{yylex}}.
10537@end deffn
10538
10539@deffn {Macro} YYLEX_PARAM
10540An obsolete macro for specifying an extra argument (or list of extra
32c29292 10541arguments) for @code{yyparse} to pass to @code{yylex}. The use of this
dd8d9022
AD
10542macro is deprecated, and is supported only for Yacc like parsers.
10543@xref{Pure Calling,, Calling Conventions for Pure Parsers}.
10544@end deffn
10545
10546@deffn {Variable} yylloc
10547External variable in which @code{yylex} should place the line and column
10548numbers associated with a token. (In a pure parser, it is a local
10549variable within @code{yyparse}, and its address is passed to
32c29292
JD
10550@code{yylex}.)
10551You can ignore this variable if you don't use the @samp{@@} feature in the
10552grammar actions.
10553@xref{Token Locations, ,Textual Locations of Tokens}.
742e4900 10554In semantic actions, it stores the location of the lookahead token.
32c29292 10555@xref{Actions and Locations, ,Actions and Locations}.
dd8d9022
AD
10556@end deffn
10557
10558@deffn {Type} YYLTYPE
10559Data type of @code{yylloc}; by default, a structure with four
10560members. @xref{Location Type, , Data Types of Locations}.
10561@end deffn
10562
10563@deffn {Variable} yylval
10564External variable in which @code{yylex} should place the semantic
10565value associated with a token. (In a pure parser, it is a local
10566variable within @code{yyparse}, and its address is passed to
32c29292
JD
10567@code{yylex}.)
10568@xref{Token Values, ,Semantic Values of Tokens}.
742e4900 10569In semantic actions, it stores the semantic value of the lookahead token.
32c29292 10570@xref{Actions, ,Actions}.
dd8d9022
AD
10571@end deffn
10572
10573@deffn {Macro} YYMAXDEPTH
1a059451
PE
10574Macro for specifying the maximum size of the parser stack. @xref{Memory
10575Management}.
dd8d9022
AD
10576@end deffn
10577
10578@deffn {Variable} yynerrs
8a2800e7 10579Global variable which Bison increments each time it reports a syntax error.
f4101aa6 10580(In a pure parser, it is a local variable within @code{yyparse}. In a
9987d1b3 10581pure push parser, it is a member of yypstate.)
dd8d9022
AD
10582@xref{Error Reporting, ,The Error Reporting Function @code{yyerror}}.
10583@end deffn
10584
10585@deffn {Function} yyparse
10586The parser function produced by Bison; call this function to start
10587parsing. @xref{Parser Function, ,The Parser Function @code{yyparse}}.
10588@end deffn
10589
9987d1b3 10590@deffn {Function} yypstate_delete
f4101aa6 10591The function to delete a parser instance, produced by Bison in push mode;
9987d1b3 10592call this function to delete the memory associated with a parser.
f4101aa6 10593@xref{Parser Delete Function, ,The Parser Delete Function
9987d1b3 10594@code{yypstate_delete}}.
59da312b
JD
10595(The current push parsing interface is experimental and may evolve.
10596More user feedback will help to stabilize it.)
9987d1b3
JD
10597@end deffn
10598
10599@deffn {Function} yypstate_new
f4101aa6 10600The function to create a parser instance, produced by Bison in push mode;
9987d1b3 10601call this function to create a new parser.
f4101aa6 10602@xref{Parser Create Function, ,The Parser Create Function
9987d1b3 10603@code{yypstate_new}}.
59da312b
JD
10604(The current push parsing interface is experimental and may evolve.
10605More user feedback will help to stabilize it.)
9987d1b3
JD
10606@end deffn
10607
10608@deffn {Function} yypull_parse
f4101aa6
AD
10609The parser function produced by Bison in push mode; call this function to
10610parse the rest of the input stream.
10611@xref{Pull Parser Function, ,The Pull Parser Function
9987d1b3 10612@code{yypull_parse}}.
59da312b
JD
10613(The current push parsing interface is experimental and may evolve.
10614More user feedback will help to stabilize it.)
9987d1b3
JD
10615@end deffn
10616
10617@deffn {Function} yypush_parse
f4101aa6
AD
10618The parser function produced by Bison in push mode; call this function to
10619parse a single token. @xref{Push Parser Function, ,The Push Parser Function
9987d1b3 10620@code{yypush_parse}}.
59da312b
JD
10621(The current push parsing interface is experimental and may evolve.
10622More user feedback will help to stabilize it.)
9987d1b3
JD
10623@end deffn
10624
dd8d9022
AD
10625@deffn {Macro} YYPARSE_PARAM
10626An obsolete macro for specifying the name of a parameter that
10627@code{yyparse} should accept. The use of this macro is deprecated, and
10628is supported only for Yacc like parsers. @xref{Pure Calling,, Calling
10629Conventions for Pure Parsers}.
10630@end deffn
10631
10632@deffn {Macro} YYRECOVERING
02103984
PE
10633The expression @code{YYRECOVERING ()} yields 1 when the parser
10634is recovering from a syntax error, and 0 otherwise.
10635@xref{Action Features, ,Special Features for Use in Actions}.
dd8d9022
AD
10636@end deffn
10637
10638@deffn {Macro} YYSTACK_USE_ALLOCA
34a6c2d1
JD
10639Macro used to control the use of @code{alloca} when the
10640deterministic parser in C needs to extend its stacks. If defined to 0,
d7e14fc0
PE
10641the parser will use @code{malloc} to extend its stacks. If defined to
106421, the parser will use @code{alloca}. Values other than 0 and 1 are
10643reserved for future Bison extensions. If not defined,
10644@code{YYSTACK_USE_ALLOCA} defaults to 0.
10645
55289366 10646In the all-too-common case where your code may run on a host with a
d7e14fc0
PE
10647limited stack and with unreliable stack-overflow checking, you should
10648set @code{YYMAXDEPTH} to a value that cannot possibly result in
10649unchecked stack overflow on any of your target hosts when
10650@code{alloca} is called. You can inspect the code that Bison
10651generates in order to determine the proper numeric values. This will
10652require some expertise in low-level implementation details.
dd8d9022
AD
10653@end deffn
10654
10655@deffn {Type} YYSTYPE
10656Data type of semantic values; @code{int} by default.
10657@xref{Value Type, ,Data Types of Semantic Values}.
18b519c0 10658@end deffn
bfa74976 10659
342b8b6e 10660@node Glossary
bfa74976
RS
10661@appendix Glossary
10662@cindex glossary
10663
10664@table @asis
34a6c2d1
JD
10665@item Accepting State
10666A state whose only action is the accept action.
10667The accepting state is thus a consistent state.
10668@xref{Understanding,,}.
10669
35430378 10670@item Backus-Naur Form (BNF; also called ``Backus Normal Form'')
c827f760
PE
10671Formal method of specifying context-free grammars originally proposed
10672by John Backus, and slightly improved by Peter Naur in his 1960-01-02
10673committee document contributing to what became the Algol 60 report.
10674@xref{Language and Grammar, ,Languages and Context-Free Grammars}.
bfa74976 10675
34a6c2d1 10676@item Consistent State
2f4518a1
JD
10677A state containing only one possible action. @xref{%define
10678Summary,,lr.default-reductions}.
34a6c2d1 10679
bfa74976
RS
10680@item Context-free grammars
10681Grammars specified as rules that can be applied regardless of context.
10682Thus, if there is a rule which says that an integer can be used as an
10683expression, integers are allowed @emph{anywhere} an expression is
89cab50d
AD
10684permitted. @xref{Language and Grammar, ,Languages and Context-Free
10685Grammars}.
bfa74976 10686
620b5727
JD
10687@item Default Reduction
10688The reduction that a parser should perform if the current parser state
2f4518a1
JD
10689contains no other action for the lookahead token. In permitted parser
10690states, Bison declares the reduction with the largest lookahead set to
10691be the default reduction and removes that lookahead set.
10692@xref{%define Summary,,lr.default-reductions}.
34a6c2d1 10693
bfa74976
RS
10694@item Dynamic allocation
10695Allocation of memory that occurs during execution, rather than at
10696compile time or on entry to a function.
10697
10698@item Empty string
10699Analogous to the empty set in set theory, the empty string is a
10700character string of length zero.
10701
10702@item Finite-state stack machine
10703A ``machine'' that has discrete states in which it is said to exist at
10704each instant in time. As input to the machine is processed, the
10705machine moves from state to state as specified by the logic of the
10706machine. In the case of the parser, the input is the language being
10707parsed, and the states correspond to various stages in the grammar
c827f760 10708rules. @xref{Algorithm, ,The Bison Parser Algorithm}.
bfa74976 10709
35430378 10710@item Generalized LR (GLR)
676385e2 10711A parsing algorithm that can handle all context-free grammars, including those
35430378 10712that are not LR(1). It resolves situations that Bison's
34a6c2d1 10713deterministic parsing
676385e2
PH
10714algorithm cannot by effectively splitting off multiple parsers, trying all
10715possible parsers, and discarding those that fail in the light of additional
c827f760 10716right context. @xref{Generalized LR Parsing, ,Generalized
35430378 10717LR Parsing}.
676385e2 10718
bfa74976
RS
10719@item Grouping
10720A language construct that is (in general) grammatically divisible;
c827f760 10721for example, `expression' or `declaration' in C@.
bfa74976
RS
10722@xref{Language and Grammar, ,Languages and Context-Free Grammars}.
10723
35430378 10724@item IELR(1)
2f4518a1
JD
10725A minimal LR(1) parser table generation algorithm. That is, given any
10726context-free grammar, IELR(1) generates parser tables with the full
10727language recognition power of canonical LR(1) but with nearly the same
10728number of parser states as LALR(1). This reduction in parser states
10729is often an order of magnitude. More importantly, because canonical
10730LR(1)'s extra parser states may contain duplicate conflicts in the
10731case of non-LR(1) grammars, the number of conflicts for IELR(1) is
10732often an order of magnitude less as well. This can significantly
10733reduce the complexity of developing of a grammar. @xref{%define
10734Summary,,lr.type}.
34a6c2d1 10735
bfa74976
RS
10736@item Infix operator
10737An arithmetic operator that is placed between the operands on which it
10738performs some operation.
10739
10740@item Input stream
10741A continuous flow of data between devices or programs.
10742
35430378 10743@item LAC (Lookahead Correction)
4c38b19e 10744A parsing mechanism that fixes the problem of delayed syntax error
2f4518a1
JD
10745detection, which is caused by LR state merging, default reductions,
10746and the use of @code{%nonassoc}. Delayed syntax error detection
10747results in unexpected semantic actions, initiation of error recovery
10748in the wrong syntactic context, and an incorrect list of expected
10749tokens in a verbose syntax error message. @xref{%define
10750Summary,,parse.lac}.
4c38b19e 10751
bfa74976
RS
10752@item Language construct
10753One of the typical usage schemas of the language. For example, one of
10754the constructs of the C language is the @code{if} statement.
10755@xref{Language and Grammar, ,Languages and Context-Free Grammars}.
10756
10757@item Left associativity
10758Operators having left associativity are analyzed from left to right:
10759@samp{a+b+c} first computes @samp{a+b} and then combines with
10760@samp{c}. @xref{Precedence, ,Operator Precedence}.
10761
10762@item Left recursion
89cab50d
AD
10763A rule whose result symbol is also its first component symbol; for
10764example, @samp{expseq1 : expseq1 ',' exp;}. @xref{Recursion, ,Recursive
10765Rules}.
bfa74976
RS
10766
10767@item Left-to-right parsing
10768Parsing a sentence of a language by analyzing it token by token from
c827f760 10769left to right. @xref{Algorithm, ,The Bison Parser Algorithm}.
bfa74976
RS
10770
10771@item Lexical analyzer (scanner)
10772A function that reads an input stream and returns tokens one by one.
10773@xref{Lexical, ,The Lexical Analyzer Function @code{yylex}}.
10774
10775@item Lexical tie-in
10776A flag, set by actions in the grammar rules, which alters the way
10777tokens are parsed. @xref{Lexical Tie-ins}.
10778
931c7513 10779@item Literal string token
14ded682 10780A token which consists of two or more fixed characters. @xref{Symbols}.
931c7513 10781
742e4900
JD
10782@item Lookahead token
10783A token already read but not yet shifted. @xref{Lookahead, ,Lookahead
89cab50d 10784Tokens}.
bfa74976 10785
35430378 10786@item LALR(1)
bfa74976 10787The class of context-free grammars that Bison (like most other parser
35430378 10788generators) can handle by default; a subset of LR(1).
34a6c2d1 10789@xref{Mystery Conflicts, ,Mysterious Reduce/Reduce Conflicts}.
bfa74976 10790
35430378 10791@item LR(1)
bfa74976 10792The class of context-free grammars in which at most one token of
742e4900 10793lookahead is needed to disambiguate the parsing of any piece of input.
bfa74976
RS
10794
10795@item Nonterminal symbol
10796A grammar symbol standing for a grammatical construct that can
10797be expressed through rules in terms of smaller constructs; in other
10798words, a construct that is not a token. @xref{Symbols}.
10799
bfa74976
RS
10800@item Parser
10801A function that recognizes valid sentences of a language by analyzing
10802the syntax structure of a set of tokens passed to it from a lexical
10803analyzer.
10804
10805@item Postfix operator
10806An arithmetic operator that is placed after the operands upon which it
10807performs some operation.
10808
10809@item Reduction
10810Replacing a string of nonterminals and/or terminals with a single
89cab50d 10811nonterminal, according to a grammar rule. @xref{Algorithm, ,The Bison
c827f760 10812Parser Algorithm}.
bfa74976
RS
10813
10814@item Reentrant
10815A reentrant subprogram is a subprogram which can be in invoked any
10816number of times in parallel, without interference between the various
10817invocations. @xref{Pure Decl, ,A Pure (Reentrant) Parser}.
10818
10819@item Reverse polish notation
10820A language in which all operators are postfix operators.
10821
10822@item Right recursion
89cab50d
AD
10823A rule whose result symbol is also its last component symbol; for
10824example, @samp{expseq1: exp ',' expseq1;}. @xref{Recursion, ,Recursive
10825Rules}.
bfa74976
RS
10826
10827@item Semantics
10828In computer languages, the semantics are specified by the actions
10829taken for each instance of the language, i.e., the meaning of
10830each statement. @xref{Semantics, ,Defining Language Semantics}.
10831
10832@item Shift
10833A parser is said to shift when it makes the choice of analyzing
10834further input from the stream rather than reducing immediately some
c827f760 10835already-recognized rule. @xref{Algorithm, ,The Bison Parser Algorithm}.
bfa74976
RS
10836
10837@item Single-character literal
10838A single character that is recognized and interpreted as is.
10839@xref{Grammar in Bison, ,From Formal Rules to Bison Input}.
10840
10841@item Start symbol
10842The nonterminal symbol that stands for a complete valid utterance in
10843the language being parsed. The start symbol is usually listed as the
13863333 10844first nonterminal symbol in a language specification.
bfa74976
RS
10845@xref{Start Decl, ,The Start-Symbol}.
10846
10847@item Symbol table
10848A data structure where symbol names and associated data are stored
10849during parsing to allow for recognition and use of existing
10850information in repeated uses of a symbol. @xref{Multi-function Calc}.
10851
6e649e65
PE
10852@item Syntax error
10853An error encountered during parsing of an input stream due to invalid
10854syntax. @xref{Error Recovery}.
10855
bfa74976
RS
10856@item Token
10857A basic, grammatically indivisible unit of a language. The symbol
10858that describes a token in the grammar is a terminal symbol.
10859The input of the Bison parser is a stream of tokens which comes from
10860the lexical analyzer. @xref{Symbols}.
10861
10862@item Terminal symbol
89cab50d
AD
10863A grammar symbol that has no rules in the grammar and therefore is
10864grammatically indivisible. The piece of text it represents is a token.
10865@xref{Language and Grammar, ,Languages and Context-Free Grammars}.
bfa74976
RS
10866@end table
10867
342b8b6e 10868@node Copying This Manual
f2b5126e 10869@appendix Copying This Manual
f2b5126e
PB
10870@include fdl.texi
10871
342b8b6e 10872@node Index
bfa74976
RS
10873@unnumbered Index
10874
10875@printindex cp
10876
bfa74976 10877@bye
a06ea4aa 10878
232be91a
AD
10879@c LocalWords: texinfo setfilename settitle setchapternewpage finalout texi FSF
10880@c LocalWords: ifinfo smallbook shorttitlepage titlepage GPL FIXME iftex FSF's
10881@c LocalWords: akim fn cp syncodeindex vr tp synindex dircategory direntry Naur
10882@c LocalWords: ifset vskip pt filll insertcopying sp ISBN Etienne Suvasa Multi
10883@c LocalWords: ifnottex yyparse detailmenu GLR RPN Calc var Decls Rpcalc multi
10884@c LocalWords: rpcalc Lexer Expr ltcalc mfcalc yylex defaultprec Donnelly Gotos
10885@c LocalWords: yyerror pxref LR yylval cindex dfn LALR samp gpl BNF xref yypush
10886@c LocalWords: const int paren ifnotinfo AC noindent emph expr stmt findex lr
10887@c LocalWords: glr YYSTYPE TYPENAME prog dprec printf decl init stmtMerge POSIX
10888@c LocalWords: pre STDC GNUC endif yy YY alloca lf stddef stdlib YYDEBUG yypull
10889@c LocalWords: NUM exp subsubsection kbd Ctrl ctype EOF getchar isdigit nonfree
10890@c LocalWords: ungetc stdin scanf sc calc ulator ls lm cc NEG prec yyerrok rr
10891@c LocalWords: longjmp fprintf stderr yylloc YYLTYPE cos ln Stallman Destructor
10892@c LocalWords: smallexample symrec val tptr FNCT fnctptr func struct sym enum
10893@c LocalWords: fnct putsym getsym fname arith fncts atan ptr malloc sizeof Lex
10894@c LocalWords: strlen strcpy fctn strcmp isalpha symbuf realloc isalnum DOTDOT
10895@c LocalWords: ptypes itype YYPRINT trigraphs yytname expseq vindex dtype Unary
10896@c LocalWords: Rhs YYRHSLOC LE nonassoc op deffn typeless yynerrs nonterminal
10897@c LocalWords: yychar yydebug msg YYNTOKENS YYNNTS YYNRULES YYNSTATES reentrant
10898@c LocalWords: cparse clex deftypefun NE defmac YYACCEPT YYABORT param yypstate
10899@c LocalWords: strncmp intval tindex lvalp locp llocp typealt YYBACKUP subrange
10900@c LocalWords: YYEMPTY YYEOF YYRECOVERING yyclearin GE def UMINUS maybeword loc
10901@c LocalWords: Johnstone Shamsa Sadaf Hussain Tomita TR uref YYMAXDEPTH inline
10902@c LocalWords: YYINITDEPTH stmnts ref stmnt initdcl maybeasm notype Lookahead
10903@c LocalWords: hexflag STR exdent itemset asis DYYDEBUG YYFPRINTF args Autoconf
10904@c LocalWords: infile ypp yxx outfile itemx tex leaderfill Troubleshouting sqrt
10905@c LocalWords: hbox hss hfill tt ly yyin fopen fclose ofirst gcc ll lookahead
10906@c LocalWords: nbar yytext fst snd osplit ntwo strdup AST Troublereporting th
10907@c LocalWords: YYSTACK DVI fdl printindex IELR nondeterministic nonterminals ps
4c38b19e 10908@c LocalWords: subexpressions declarator nondeferred config libintl postfix LAC
232be91a 10909@c LocalWords: preprocessor nonpositive unary nonnumeric typedef extern rhs
9913d6e4 10910@c LocalWords: yytokentype destructor multicharacter nonnull EBCDIC
232be91a
AD
10911@c LocalWords: lvalue nonnegative XNUM CHR chr TAGLESS tagless stdout api TOK
10912@c LocalWords: destructors Reentrancy nonreentrant subgrammar nonassociative
10913@c LocalWords: deffnx namespace xml goto lalr ielr runtime lex yacc yyps env
10914@c LocalWords: yystate variadic Unshift NLS gettext po UTF Automake LOCALEDIR
10915@c LocalWords: YYENABLE bindtextdomain Makefile DEFS CPPFLAGS DBISON DeRemer
10916@c LocalWords: autoreconf Pennello multisets nondeterminism Generalised baz
10917@c LocalWords: redeclare automata Dparse localedir datadir XSLT midrule Wno
9913d6e4 10918@c LocalWords: Graphviz multitable headitem hh basename Doxygen fno
232be91a
AD
10919@c LocalWords: doxygen ival sval deftypemethod deallocate pos deftypemethodx
10920@c LocalWords: Ctor defcv defcvx arg accessors arithmetics CPP ifndef CALCXX
10921@c LocalWords: lexer's calcxx bool LPAREN RPAREN deallocation cerrno climits
10922@c LocalWords: cstdlib Debian undef yywrap unput noyywrap nounput zA yyleng
10923@c LocalWords: errno strtol ERANGE str strerror iostream argc argv Javadoc
10924@c LocalWords: bytecode initializers superclass stype ASTNode autoboxing nls
10925@c LocalWords: toString deftypeivar deftypeivarx deftypeop YYParser strictfp
10926@c LocalWords: superclasses boolean getErrorVerbose setErrorVerbose deftypecv
10927@c LocalWords: getDebugStream setDebugStream getDebugLevel setDebugLevel url
10928@c LocalWords: bisonVersion deftypecvx bisonSkeleton getStartPos getEndPos
840341d6 10929@c LocalWords: getLVal defvar deftypefn deftypefnx gotos msgfmt Corbett
232be91a 10930@c LocalWords: subdirectory Solaris nonassociativity
f3103c5b
AD
10931
10932@c Local Variables:
10933@c ispell-dictionary: "american"
10934@c fill-column: 76
10935@c End: