1 \input texinfo @c -*-texinfo-*-
2 @comment %**start of header
3 @setfilename bison.info
5 @settitle Bison @value{VERSION}
11 @c This edition has been formatted so that you can format and print it in
12 @c the smallbook format.
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.
29 @comment %**end of header
33 This manual (@value{UPDATED}) is for @acronym{GNU} Bison (version
34 @value{VERSION}), the @acronym{GNU} parser generator.
36 Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998,
37 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free
38 Software Foundation, Inc.
41 Permission is granted to copy, distribute and/or modify this document
42 under the terms of the @acronym{GNU} Free Documentation License,
43 Version 1.2 or any later version published by the Free Software
44 Foundation; with no Invariant Sections, with the Front-Cover texts
45 being ``A @acronym{GNU} Manual,'' and with the Back-Cover Texts as in
46 (a) below. A copy of the license is included in the section entitled
47 ``@acronym{GNU} Free Documentation License.''
49 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
50 modify this @acronym{GNU} manual. Buying copies from the @acronym{FSF}
51 supports it in developing @acronym{GNU} and promoting software
56 @dircategory Software development
58 * bison: (bison). @acronym{GNU} parser generator (Yacc replacement).
63 @subtitle The Yacc-compatible Parser Generator
64 @subtitle @value{UPDATED}, Bison Version @value{VERSION}
66 @author by Charles Donnelly and Richard Stallman
69 @vskip 0pt plus 1filll
72 Published by the Free Software Foundation @*
73 51 Franklin Street, Fifth Floor @*
74 Boston, MA 02110-1301 USA @*
75 Printed copies are available from the Free Software Foundation.@*
76 @acronym{ISBN} 1-882114-44-2
78 Cover art by Etienne Suvasa.
92 * Copying:: The @acronym{GNU} General Public License says
93 how you can copy and share Bison.
96 * Concepts:: Basic concepts for understanding Bison.
97 * Examples:: Three simple explained examples of using Bison.
100 * Grammar File:: Writing Bison declarations and rules.
101 * Interface:: C-language interface to the parser function @code{yyparse}.
102 * Algorithm:: How the Bison parser works at run-time.
103 * Error Recovery:: Writing rules for error recovery.
104 * Context Dependency:: What to do if your language syntax is too
105 messy for Bison to handle straightforwardly.
106 * Debugging:: Understanding or debugging Bison parsers.
107 * Invocation:: How to run Bison (to produce the parser source file).
108 * Other Languages:: Creating C++ and Java parsers.
109 * FAQ:: Frequently Asked Questions
110 * Table of Symbols:: All the keywords of the Bison language are explained.
111 * Glossary:: Basic concepts are explained.
112 * Copying This Manual:: License for copying this manual.
113 * Index:: Cross-references to the text.
116 --- The Detailed Node Listing ---
118 The Concepts of Bison
120 * Language and Grammar:: Languages and context-free grammars,
121 as mathematical ideas.
122 * Grammar in Bison:: How we represent grammars for Bison's sake.
123 * Semantic Values:: Each token or syntactic grouping can have
124 a semantic value (the value of an integer,
125 the name of an identifier, etc.).
126 * Semantic Actions:: Each rule can have an action containing C code.
127 * GLR Parsers:: Writing parsers for general context-free languages.
128 * Locations Overview:: Tracking Locations.
129 * Bison Parser:: What are Bison's input and output,
130 how is the output used?
131 * Stages:: Stages in writing and running Bison grammars.
132 * Grammar Layout:: Overall structure of a Bison grammar file.
134 Writing @acronym{GLR} Parsers
136 * Simple GLR Parsers:: Using @acronym{GLR} parsers on unambiguous grammars.
137 * Merging GLR Parses:: Using @acronym{GLR} parsers to resolve ambiguities.
138 * GLR Semantic Actions:: Deferred semantic actions have special concerns.
139 * Compiler Requirements:: @acronym{GLR} parsers require a modern C compiler.
143 * RPN Calc:: Reverse polish notation calculator;
144 a first example with no operator precedence.
145 * Infix Calc:: Infix (algebraic) notation calculator.
146 Operator precedence is introduced.
147 * Simple Error Recovery:: Continuing after syntax errors.
148 * Location Tracking Calc:: Demonstrating the use of @@@var{n} and @@$.
149 * Multi-function Calc:: Calculator with memory and trig functions.
150 It uses multiple data-types for semantic values.
151 * Exercises:: Ideas for improving the multi-function calculator.
153 Reverse Polish Notation Calculator
155 * Rpcalc Declarations:: Prologue (declarations) for rpcalc.
156 * Rpcalc Rules:: Grammar Rules for rpcalc, with explanation.
157 * Rpcalc Lexer:: The lexical analyzer.
158 * Rpcalc Main:: The controlling function.
159 * Rpcalc Error:: The error reporting function.
160 * Rpcalc Generate:: Running Bison on the grammar file.
161 * Rpcalc Compile:: Run the C compiler on the output code.
163 Grammar Rules for @code{rpcalc}
169 Location Tracking Calculator: @code{ltcalc}
171 * Ltcalc Declarations:: Bison and C declarations for ltcalc.
172 * Ltcalc Rules:: Grammar rules for ltcalc, with explanations.
173 * Ltcalc Lexer:: The lexical analyzer.
175 Multi-Function Calculator: @code{mfcalc}
177 * Mfcalc Declarations:: Bison declarations for multi-function calculator.
178 * Mfcalc Rules:: Grammar rules for the calculator.
179 * Mfcalc Symbol Table:: Symbol table management subroutines.
183 * Grammar Outline:: Overall layout of the grammar file.
184 * Symbols:: Terminal and nonterminal symbols.
185 * Rules:: How to write grammar rules.
186 * Recursion:: Writing recursive rules.
187 * Semantics:: Semantic values and actions.
188 * Locations:: Locations and actions.
189 * Declarations:: All kinds of Bison declarations are described here.
190 * Multiple Parsers:: Putting more than one Bison parser in one program.
192 Outline of a Bison Grammar
194 * Prologue:: Syntax and usage of the prologue.
195 * Prologue Alternatives:: Syntax and usage of alternatives to the prologue.
196 * Bison Declarations:: Syntax and usage of the Bison declarations section.
197 * Grammar Rules:: Syntax and usage of the grammar rules section.
198 * Epilogue:: Syntax and usage of the epilogue.
200 Defining Language Semantics
202 * Value Type:: Specifying one data type for all semantic values.
203 * Multiple Types:: Specifying several alternative data types.
204 * Actions:: An action is the semantic definition of a grammar rule.
205 * Action Types:: Specifying data types for actions to operate on.
206 * Mid-Rule Actions:: Most actions go at the end of a rule.
207 This says when, why and how to use the exceptional
208 action in the middle of a rule.
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.
218 * Require Decl:: Requiring a Bison version.
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.
223 * Initial Action Decl:: Code run before parsing starts.
224 * Destructor Decl:: Declaring how symbols are freed.
225 * Expect Decl:: Suppressing warnings about parsing conflicts.
226 * Start Decl:: Specifying the start symbol.
227 * Pure Decl:: Requesting a reentrant parser.
228 * Push Decl:: Requesting a push parser.
229 * Decl Summary:: Table of all Bison declarations.
231 Parser C-Language Interface
233 * Parser Function:: How to call @code{yyparse} and what it returns.
234 * Push Parser Function:: How to call @code{yypush_parse} and what it returns.
235 * Pull Parser Function:: How to call @code{yypull_parse} and what it returns.
236 * Parser Create Function:: How to call @code{yypstate_new} and what it returns.
237 * Parser Delete Function:: How to call @code{yypstate_delete} and what it returns.
238 * Lexical:: You must supply a function @code{yylex}
240 * Error Reporting:: You must supply a function @code{yyerror}.
241 * Action Features:: Special features for use in actions.
242 * Internationalization:: How to let the parser speak in the user's
245 The Lexical Analyzer Function @code{yylex}
247 * Calling Convention:: How @code{yyparse} calls @code{yylex}.
248 * Token Values:: How @code{yylex} must return the semantic value
249 of the token it has read.
250 * Token Locations:: How @code{yylex} must return the text location
251 (line number, etc.) of the token, if the
253 * Pure Calling:: How the calling convention differs in a pure parser
254 (@pxref{Pure Decl, ,A Pure (Reentrant) Parser}).
256 The Bison Parser Algorithm
258 * Lookahead:: Parser looks one token ahead when deciding what to do.
259 * Shift/Reduce:: Conflicts: when either shifting or reduction is valid.
260 * Precedence:: Operator precedence works by resolving conflicts.
261 * Contextual Precedence:: When an operator's precedence depends on context.
262 * Parser States:: The parser is a finite-state-machine with stack.
263 * Reduce/Reduce:: When two rules are applicable in the same situation.
264 * Mystery Conflicts:: Reduce/reduce conflicts that look unjustified.
265 * Generalized LR Parsing:: Parsing arbitrary context-free grammars.
266 * Memory Management:: What happens when memory is exhausted. How to avoid it.
270 * Why Precedence:: An example showing why precedence is needed.
271 * Using Precedence:: How to specify precedence and associativity.
272 * Precedence Only:: How to specify precedence only.
273 * Precedence Examples:: How these features are used in the previous example.
274 * How Precedence:: How they work.
276 Handling Context Dependencies
278 * Semantic Tokens:: Token parsing can depend on the semantic context.
279 * Lexical Tie-ins:: Token parsing can depend on the syntactic context.
280 * Tie-in Recovery:: Lexical tie-ins have implications for how
281 error recovery rules must be written.
283 Debugging Your Parser
285 * Understanding:: Understanding the structure of your parser.
286 * Tracing:: Tracing the execution of your parser.
290 * Bison Options:: All the options described in detail,
291 in alphabetical order by short options.
292 * Option Cross Key:: Alphabetical list of long options.
293 * Yacc Library:: Yacc-compatible @code{yylex} and @code{main}.
295 Parsers Written In Other Languages
297 * C++ Parsers:: The interface to generate C++ parser classes
298 * Java Parsers:: The interface to generate Java parser classes
302 * C++ Bison Interface:: Asking for C++ parser generation
303 * C++ Semantic Values:: %union vs. C++
304 * C++ Location Values:: The position and location classes
305 * C++ Parser Interface:: Instantiating and running the parser
306 * C++ Scanner Interface:: Exchanges between yylex and parse
307 * A Complete C++ Example:: Demonstrating their use
309 A Complete C++ Example
311 * Calc++ --- C++ Calculator:: The specifications
312 * Calc++ Parsing Driver:: An active parsing context
313 * Calc++ Parser:: A parser class
314 * Calc++ Scanner:: A pure C++ Flex scanner
315 * Calc++ Top Level:: Conducting the band
319 * Java Bison Interface:: Asking for Java parser generation
320 * Java Semantic Values:: %type and %token vs. Java
321 * Java Location Values:: The position and location classes
322 * Java Parser Interface:: Instantiating and running the parser
323 * Java Scanner Interface:: Specifying the scanner for the parser
324 * Java Action Features:: Special features for use in actions
325 * Java Differences:: Differences between C/C++ and Java Grammars
326 * Java Declarations Summary:: List of Bison declarations used with Java
328 Frequently Asked Questions
330 * Memory Exhausted:: Breaking the Stack Limits
331 * How Can I Reset the Parser:: @code{yyparse} Keeps some State
332 * Strings are Destroyed:: @code{yylval} Loses Track of Strings
333 * Implementing Gotos/Loops:: Control Flow in the Calculator
334 * Multiple start-symbols:: Factoring closely related grammars
335 * Secure? Conform?:: Is Bison @acronym{POSIX} safe?
336 * I can't build Bison:: Troubleshooting
337 * Where can I find help?:: Troubleshouting
338 * Bug Reports:: Troublereporting
339 * More Languages:: Parsers in C++, Java, and so on
340 * Beta Testing:: Experimenting development versions
341 * Mailing Lists:: Meeting other Bison users
345 * Copying This Manual:: License for copying this manual.
351 @unnumbered Introduction
354 @dfn{Bison} is a general-purpose parser generator that converts an
355 annotated context-free grammar into a deterministic or @acronym{GLR}
356 parser employing @acronym{LALR}(1), @acronym{IELR}(1), or canonical
357 @acronym{LR}(1) parser tables.
358 Once you are proficient with Bison, you can use it to develop a wide
359 range of language parsers, from those used in simple desk calculators to
360 complex programming languages.
362 Bison is upward compatible with Yacc: all properly-written Yacc grammars
363 ought to work with Bison with no change. Anyone familiar with Yacc
364 should be able to use Bison with little trouble. You need to be fluent in
365 C or C++ programming in order to use Bison or to understand this manual.
367 We begin with tutorial chapters that explain the basic concepts of using
368 Bison and show three explained examples, each building on the last. If you
369 don't know Bison or Yacc, start by reading these chapters. Reference
370 chapters follow which describe specific aspects of Bison in detail.
372 Bison was written primarily by Robert Corbett; Richard Stallman made it
373 Yacc-compatible. Wilfred Hansen of Carnegie Mellon University added
374 multi-character string literals and other features.
376 This edition corresponds to version @value{VERSION} of Bison.
379 @unnumbered Conditions for Using Bison
381 The distribution terms for Bison-generated parsers permit using the
382 parsers in nonfree programs. Before Bison version 2.2, these extra
383 permissions applied only when Bison was generating @acronym{LALR}(1)
384 parsers in C@. And before Bison version 1.24, Bison-generated
385 parsers could be used only in programs that were free software.
387 The other @acronym{GNU} programming tools, such as the @acronym{GNU} C
389 had such a requirement. They could always be used for nonfree
390 software. The reason Bison was different was not due to a special
391 policy decision; it resulted from applying the usual General Public
392 License to all of the Bison source code.
394 The output of the Bison utility---the Bison parser file---contains a
395 verbatim copy of a sizable piece of Bison, which is the code for the
396 parser's implementation. (The actions from your grammar are inserted
397 into this implementation at one point, but most of the rest of the
398 implementation is not changed.) When we applied the @acronym{GPL}
399 terms to the skeleton code for the parser's implementation,
400 the effect was to restrict the use of Bison output to free software.
402 We didn't change the terms because of sympathy for people who want to
403 make software proprietary. @strong{Software should be free.} But we
404 concluded that limiting Bison's use to free software was doing little to
405 encourage people to make other software free. So we decided to make the
406 practical conditions for using Bison match the practical conditions for
407 using the other @acronym{GNU} tools.
409 This exception applies when Bison is generating code for a parser.
410 You can tell whether the exception applies to a Bison output file by
411 inspecting the file for text beginning with ``As a special
412 exception@dots{}''. The text spells out the exact terms of the
416 @unnumbered GNU GENERAL PUBLIC LICENSE
417 @include gpl-3.0.texi
420 @chapter The Concepts of Bison
422 This chapter introduces many of the basic concepts without which the
423 details of Bison will not make sense. If you do not already know how to
424 use Bison or Yacc, we suggest you start by reading this chapter carefully.
427 * Language and Grammar:: Languages and context-free grammars,
428 as mathematical ideas.
429 * Grammar in Bison:: How we represent grammars for Bison's sake.
430 * Semantic Values:: Each token or syntactic grouping can have
431 a semantic value (the value of an integer,
432 the name of an identifier, etc.).
433 * Semantic Actions:: Each rule can have an action containing C code.
434 * GLR Parsers:: Writing parsers for general context-free languages.
435 * Locations Overview:: Tracking Locations.
436 * Bison Parser:: What are Bison's input and output,
437 how is the output used?
438 * Stages:: Stages in writing and running Bison grammars.
439 * Grammar Layout:: Overall structure of a Bison grammar file.
442 @node Language and Grammar
443 @section Languages and Context-Free Grammars
445 @cindex context-free grammar
446 @cindex grammar, context-free
447 In order for Bison to parse a language, it must be described by a
448 @dfn{context-free grammar}. This means that you specify one or more
449 @dfn{syntactic groupings} and give rules for constructing them from their
450 parts. For example, in the C language, one kind of grouping is called an
451 `expression'. One rule for making an expression might be, ``An expression
452 can be made of a minus sign and another expression''. Another would be,
453 ``An expression can be an integer''. As you can see, rules are often
454 recursive, but there must be at least one rule which leads out of the
457 @cindex @acronym{BNF}
458 @cindex Backus-Naur form
459 The most common formal system for presenting such rules for humans to read
460 is @dfn{Backus-Naur Form} or ``@acronym{BNF}'', which was developed in
461 order to specify the language Algol 60. Any grammar expressed in
462 @acronym{BNF} is a context-free grammar. The input to Bison is
463 essentially machine-readable @acronym{BNF}.
465 @cindex @acronym{LALR}(1) grammars
466 @cindex @acronym{IELR}(1) grammars
467 @cindex @acronym{LR}(1) grammars
468 There are various important subclasses of context-free grammars.
469 Although it can handle almost all context-free grammars, Bison is
470 optimized for what are called @acronym{LR}(1) grammars.
471 In brief, in these grammars, it must be possible to tell how to parse
472 any portion of an input string with just a single token of lookahead.
473 For historical reasons, Bison by default is limited by the additional
474 restrictions of @acronym{LALR}(1), which is hard to explain simply.
475 @xref{Mystery Conflicts, ,Mysterious Reduce/Reduce Conflicts}, for
476 more information on this.
477 To escape these additional restrictions, you can request
478 @acronym{IELR}(1) or canonical @acronym{LR}(1) parser tables.
479 @xref{Decl Summary,,lr.type}, to learn how.
481 @cindex @acronym{GLR} parsing
482 @cindex generalized @acronym{LR} (@acronym{GLR}) parsing
483 @cindex ambiguous grammars
484 @cindex nondeterministic parsing
486 Parsers for @acronym{LR}(1) grammars are @dfn{deterministic}, meaning
487 roughly that the next grammar rule to apply at any point in the input is
488 uniquely determined by the preceding input and a fixed, finite portion
489 (called a @dfn{lookahead}) of the remaining input. A context-free
490 grammar can be @dfn{ambiguous}, meaning that there are multiple ways to
491 apply the grammar rules to get the same inputs. Even unambiguous
492 grammars can be @dfn{nondeterministic}, meaning that no fixed
493 lookahead always suffices to determine the next grammar rule to apply.
494 With the proper declarations, Bison is also able to parse these more
495 general context-free grammars, using a technique known as @acronym{GLR}
496 parsing (for Generalized @acronym{LR}). Bison's @acronym{GLR} parsers
497 are able to handle any context-free grammar for which the number of
498 possible parses of any given string is finite.
500 @cindex symbols (abstract)
502 @cindex syntactic grouping
503 @cindex grouping, syntactic
504 In the formal grammatical rules for a language, each kind of syntactic
505 unit or grouping is named by a @dfn{symbol}. Those which are built by
506 grouping smaller constructs according to grammatical rules are called
507 @dfn{nonterminal symbols}; those which can't be subdivided are called
508 @dfn{terminal symbols} or @dfn{token types}. We call a piece of input
509 corresponding to a single terminal symbol a @dfn{token}, and a piece
510 corresponding to a single nonterminal symbol a @dfn{grouping}.
512 We can use the C language as an example of what symbols, terminal and
513 nonterminal, mean. The tokens of C are identifiers, constants (numeric
514 and string), and the various keywords, arithmetic operators and
515 punctuation marks. So the terminal symbols of a grammar for C include
516 `identifier', `number', `string', plus one symbol for each keyword,
517 operator or punctuation mark: `if', `return', `const', `static', `int',
518 `char', `plus-sign', `open-brace', `close-brace', `comma' and many more.
519 (These tokens can be subdivided into characters, but that is a matter of
520 lexicography, not grammar.)
522 Here is a simple C function subdivided into tokens:
526 int /* @r{keyword `int'} */
527 square (int x) /* @r{identifier, open-paren, keyword `int',}
528 @r{identifier, close-paren} */
529 @{ /* @r{open-brace} */
530 return x * x; /* @r{keyword `return', identifier, asterisk,}
531 @r{identifier, semicolon} */
532 @} /* @r{close-brace} */
537 int /* @r{keyword `int'} */
538 square (int x) /* @r{identifier, open-paren, keyword `int', identifier, close-paren} */
539 @{ /* @r{open-brace} */
540 return x * x; /* @r{keyword `return', identifier, asterisk, identifier, semicolon} */
541 @} /* @r{close-brace} */
545 The syntactic groupings of C include the expression, the statement, the
546 declaration, and the function definition. These are represented in the
547 grammar of C by nonterminal symbols `expression', `statement',
548 `declaration' and `function definition'. The full grammar uses dozens of
549 additional language constructs, each with its own nonterminal symbol, in
550 order to express the meanings of these four. The example above is a
551 function definition; it contains one declaration, and one statement. In
552 the statement, each @samp{x} is an expression and so is @samp{x * x}.
554 Each nonterminal symbol must have grammatical rules showing how it is made
555 out of simpler constructs. For example, one kind of C statement is the
556 @code{return} statement; this would be described with a grammar rule which
557 reads informally as follows:
560 A `statement' can be made of a `return' keyword, an `expression' and a
565 There would be many other rules for `statement', one for each kind of
569 One nonterminal symbol must be distinguished as the special one which
570 defines a complete utterance in the language. It is called the @dfn{start
571 symbol}. In a compiler, this means a complete input program. In the C
572 language, the nonterminal symbol `sequence of definitions and declarations'
575 For example, @samp{1 + 2} is a valid C expression---a valid part of a C
576 program---but it is not valid as an @emph{entire} C program. In the
577 context-free grammar of C, this follows from the fact that `expression' is
578 not the start symbol.
580 The Bison parser reads a sequence of tokens as its input, and groups the
581 tokens using the grammar rules. If the input is valid, the end result is
582 that the entire token sequence reduces to a single grouping whose symbol is
583 the grammar's start symbol. If we use a grammar for C, the entire input
584 must be a `sequence of definitions and declarations'. If not, the parser
585 reports a syntax error.
587 @node Grammar in Bison
588 @section From Formal Rules to Bison Input
589 @cindex Bison grammar
590 @cindex grammar, Bison
591 @cindex formal grammar
593 A formal grammar is a mathematical construct. To define the language
594 for Bison, you must write a file expressing the grammar in Bison syntax:
595 a @dfn{Bison grammar} file. @xref{Grammar File, ,Bison Grammar Files}.
597 A nonterminal symbol in the formal grammar is represented in Bison input
598 as an identifier, like an identifier in C@. By convention, it should be
599 in lower case, such as @code{expr}, @code{stmt} or @code{declaration}.
601 The Bison representation for a terminal symbol is also called a @dfn{token
602 type}. Token types as well can be represented as C-like identifiers. By
603 convention, these identifiers should be upper case to distinguish them from
604 nonterminals: for example, @code{INTEGER}, @code{IDENTIFIER}, @code{IF} or
605 @code{RETURN}. A terminal symbol that stands for a particular keyword in
606 the language should be named after that keyword converted to upper case.
607 The terminal symbol @code{error} is reserved for error recovery.
610 A terminal symbol can also be represented as a character literal, just like
611 a C character constant. You should do this whenever a token is just a
612 single character (parenthesis, plus-sign, etc.): use that same character in
613 a literal as the terminal symbol for that token.
615 A third way to represent a terminal symbol is with a C string constant
616 containing several characters. @xref{Symbols}, for more information.
618 The grammar rules also have an expression in Bison syntax. For example,
619 here is the Bison rule for a C @code{return} statement. The semicolon in
620 quotes is a literal character token, representing part of the C syntax for
621 the statement; the naked semicolon, and the colon, are Bison punctuation
625 stmt: RETURN expr ';'
630 @xref{Rules, ,Syntax of Grammar Rules}.
632 @node Semantic Values
633 @section Semantic Values
634 @cindex semantic value
635 @cindex value, semantic
637 A formal grammar selects tokens only by their classifications: for example,
638 if a rule mentions the terminal symbol `integer constant', it means that
639 @emph{any} integer constant is grammatically valid in that position. The
640 precise value of the constant is irrelevant to how to parse the input: if
641 @samp{x+4} is grammatical then @samp{x+1} or @samp{x+3989} is equally
644 But the precise value is very important for what the input means once it is
645 parsed. A compiler is useless if it fails to distinguish between 4, 1 and
646 3989 as constants in the program! Therefore, each token in a Bison grammar
647 has both a token type and a @dfn{semantic value}. @xref{Semantics,
648 ,Defining Language Semantics},
651 The token type is a terminal symbol defined in the grammar, such as
652 @code{INTEGER}, @code{IDENTIFIER} or @code{','}. It tells everything
653 you need to know to decide where the token may validly appear and how to
654 group it with other tokens. The grammar rules know nothing about tokens
657 The semantic value has all the rest of the information about the
658 meaning of the token, such as the value of an integer, or the name of an
659 identifier. (A token such as @code{','} which is just punctuation doesn't
660 need to have any semantic value.)
662 For example, an input token might be classified as token type
663 @code{INTEGER} and have the semantic value 4. Another input token might
664 have the same token type @code{INTEGER} but value 3989. When a grammar
665 rule says that @code{INTEGER} is allowed, either of these tokens is
666 acceptable because each is an @code{INTEGER}. When the parser accepts the
667 token, it keeps track of the token's semantic value.
669 Each grouping can also have a semantic value as well as its nonterminal
670 symbol. For example, in a calculator, an expression typically has a
671 semantic value that is a number. In a compiler for a programming
672 language, an expression typically has a semantic value that is a tree
673 structure describing the meaning of the expression.
675 @node Semantic Actions
676 @section Semantic Actions
677 @cindex semantic actions
678 @cindex actions, semantic
680 In order to be useful, a program must do more than parse input; it must
681 also produce some output based on the input. In a Bison grammar, a grammar
682 rule can have an @dfn{action} made up of C statements. Each time the
683 parser recognizes a match for that rule, the action is executed.
686 Most of the time, the purpose of an action is to compute the semantic value
687 of the whole construct from the semantic values of its parts. For example,
688 suppose we have a rule which says an expression can be the sum of two
689 expressions. When the parser recognizes such a sum, each of the
690 subexpressions has a semantic value which describes how it was built up.
691 The action for this rule should create a similar sort of value for the
692 newly recognized larger expression.
694 For example, here is a rule that says an expression can be the sum of
698 expr: expr '+' expr @{ $$ = $1 + $3; @}
703 The action says how to produce the semantic value of the sum expression
704 from the values of the two subexpressions.
707 @section Writing @acronym{GLR} Parsers
708 @cindex @acronym{GLR} parsing
709 @cindex generalized @acronym{LR} (@acronym{GLR}) parsing
712 @cindex shift/reduce conflicts
713 @cindex reduce/reduce conflicts
715 In some grammars, Bison's deterministic
716 @acronym{LR}(1) parsing algorithm cannot decide whether to apply a
717 certain grammar rule at a given point. That is, it may not be able to
718 decide (on the basis of the input read so far) which of two possible
719 reductions (applications of a grammar rule) applies, or whether to apply
720 a reduction or read more of the input and apply a reduction later in the
721 input. These are known respectively as @dfn{reduce/reduce} conflicts
722 (@pxref{Reduce/Reduce}), and @dfn{shift/reduce} conflicts
723 (@pxref{Shift/Reduce}).
725 To use a grammar that is not easily modified to be @acronym{LR}(1), a
726 more general parsing algorithm is sometimes necessary. If you include
727 @code{%glr-parser} among the Bison declarations in your file
728 (@pxref{Grammar Outline}), the result is a Generalized @acronym{LR}
729 (@acronym{GLR}) parser. These parsers handle Bison grammars that
730 contain no unresolved conflicts (i.e., after applying precedence
731 declarations) identically to deterministic parsers. However, when
732 faced with unresolved shift/reduce and reduce/reduce conflicts,
733 @acronym{GLR} parsers use the simple expedient of doing both,
734 effectively cloning the parser to follow both possibilities. Each of
735 the resulting parsers can again split, so that at any given time, there
736 can be any number of possible parses being explored. The parsers
737 proceed in lockstep; that is, all of them consume (shift) a given input
738 symbol before any of them proceed to the next. Each of the cloned
739 parsers eventually meets one of two possible fates: either it runs into
740 a parsing error, in which case it simply vanishes, or it merges with
741 another parser, because the two of them have reduced the input to an
742 identical set of symbols.
744 During the time that there are multiple parsers, semantic actions are
745 recorded, but not performed. When a parser disappears, its recorded
746 semantic actions disappear as well, and are never performed. When a
747 reduction makes two parsers identical, causing them to merge, Bison
748 records both sets of semantic actions. Whenever the last two parsers
749 merge, reverting to the single-parser case, Bison resolves all the
750 outstanding actions either by precedences given to the grammar rules
751 involved, or by performing both actions, and then calling a designated
752 user-defined function on the resulting values to produce an arbitrary
756 * Simple GLR Parsers:: Using @acronym{GLR} parsers on unambiguous grammars.
757 * Merging GLR Parses:: Using @acronym{GLR} parsers to resolve ambiguities.
758 * GLR Semantic Actions:: Deferred semantic actions have special concerns.
759 * Compiler Requirements:: @acronym{GLR} parsers require a modern C compiler.
762 @node Simple GLR Parsers
763 @subsection Using @acronym{GLR} on Unambiguous Grammars
764 @cindex @acronym{GLR} parsing, unambiguous grammars
765 @cindex generalized @acronym{LR} (@acronym{GLR}) parsing, unambiguous grammars
769 @cindex reduce/reduce conflicts
770 @cindex shift/reduce conflicts
772 In the simplest cases, you can use the @acronym{GLR} algorithm
773 to parse grammars that are unambiguous but fail to be @acronym{LR}(1).
774 Such grammars typically require more than one symbol of lookahead.
776 Consider a problem that
777 arises in the declaration of enumerated and subrange types in the
778 programming language Pascal. Here are some examples:
781 type subrange = lo .. hi;
782 type enum = (a, b, c);
786 The original language standard allows only numeric
787 literals and constant identifiers for the subrange bounds (@samp{lo}
788 and @samp{hi}), but Extended Pascal (@acronym{ISO}/@acronym{IEC}
789 10206) and many other
790 Pascal implementations allow arbitrary expressions there. This gives
791 rise to the following situation, containing a superfluous pair of
795 type subrange = (a) .. b;
799 Compare this to the following declaration of an enumerated
800 type with only one value:
807 (These declarations are contrived, but they are syntactically
808 valid, and more-complicated cases can come up in practical programs.)
810 These two declarations look identical until the @samp{..} token.
811 With normal @acronym{LR}(1) one-token lookahead it is not
812 possible to decide between the two forms when the identifier
813 @samp{a} is parsed. It is, however, desirable
814 for a parser to decide this, since in the latter case
815 @samp{a} must become a new identifier to represent the enumeration
816 value, while in the former case @samp{a} must be evaluated with its
817 current meaning, which may be a constant or even a function call.
819 You could parse @samp{(a)} as an ``unspecified identifier in parentheses'',
820 to be resolved later, but this typically requires substantial
821 contortions in both semantic actions and large parts of the
822 grammar, where the parentheses are nested in the recursive rules for
825 You might think of using the lexer to distinguish between the two
826 forms by returning different tokens for currently defined and
827 undefined identifiers. But if these declarations occur in a local
828 scope, and @samp{a} is defined in an outer scope, then both forms
829 are possible---either locally redefining @samp{a}, or using the
830 value of @samp{a} from the outer scope. So this approach cannot
833 A simple solution to this problem is to declare the parser to
834 use the @acronym{GLR} algorithm.
835 When the @acronym{GLR} parser reaches the critical state, it
836 merely splits into two branches and pursues both syntax rules
837 simultaneously. Sooner or later, one of them runs into a parsing
838 error. If there is a @samp{..} token before the next
839 @samp{;}, the rule for enumerated types fails since it cannot
840 accept @samp{..} anywhere; otherwise, the subrange type rule
841 fails since it requires a @samp{..} token. So one of the branches
842 fails silently, and the other one continues normally, performing
843 all the intermediate actions that were postponed during the split.
845 If the input is syntactically incorrect, both branches fail and the parser
846 reports a syntax error as usual.
848 The effect of all this is that the parser seems to ``guess'' the
849 correct branch to take, or in other words, it seems to use more
850 lookahead than the underlying @acronym{LR}(1) algorithm actually allows
851 for. In this example, @acronym{LR}(2) would suffice, but also some cases
852 that are not @acronym{LR}(@math{k}) for any @math{k} can be handled this way.
854 In general, a @acronym{GLR} parser can take quadratic or cubic worst-case time,
855 and the current Bison parser even takes exponential time and space
856 for some grammars. In practice, this rarely happens, and for many
857 grammars it is possible to prove that it cannot happen.
858 The present example contains only one conflict between two
859 rules, and the type-declaration context containing the conflict
860 cannot be nested. So the number of
861 branches that can exist at any time is limited by the constant 2,
862 and the parsing time is still linear.
864 Here is a Bison grammar corresponding to the example above. It
865 parses a vastly simplified form of Pascal type declarations.
868 %token TYPE DOTDOT ID
878 type_decl : TYPE ID '=' type ';'
883 type : '(' id_list ')'
905 When used as a normal @acronym{LR}(1) grammar, Bison correctly complains
906 about one reduce/reduce conflict. In the conflicting situation the
907 parser chooses one of the alternatives, arbitrarily the one
908 declared first. Therefore the following correct input is not
915 The parser can be turned into a @acronym{GLR} parser, while also telling Bison
916 to be silent about the one known reduce/reduce conflict, by
917 adding these two declarations to the Bison input file (before the first
926 No change in the grammar itself is required. Now the
927 parser recognizes all valid declarations, according to the
928 limited syntax above, transparently. In fact, the user does not even
929 notice when the parser splits.
931 So here we have a case where we can use the benefits of @acronym{GLR},
932 almost without disadvantages. Even in simple cases like this, however,
933 there are at least two potential problems to beware. First, always
934 analyze the conflicts reported by Bison to make sure that @acronym{GLR}
935 splitting is only done where it is intended. A @acronym{GLR} parser
936 splitting inadvertently may cause problems less obvious than an
937 @acronym{LR} parser statically choosing the wrong alternative in a
938 conflict. Second, consider interactions with the lexer (@pxref{Semantic
939 Tokens}) with great care. Since a split parser consumes tokens without
940 performing any actions during the split, the lexer cannot obtain
941 information via parser actions. Some cases of lexer interactions can be
942 eliminated by using @acronym{GLR} to shift the complications from the
943 lexer to the parser. You must check the remaining cases for
946 In our example, it would be safe for the lexer to return tokens based on
947 their current meanings in some symbol table, because no new symbols are
948 defined in the middle of a type declaration. Though it is possible for
949 a parser to define the enumeration constants as they are parsed, before
950 the type declaration is completed, it actually makes no difference since
951 they cannot be used within the same enumerated type declaration.
953 @node Merging GLR Parses
954 @subsection Using @acronym{GLR} to Resolve Ambiguities
955 @cindex @acronym{GLR} parsing, ambiguous grammars
956 @cindex generalized @acronym{LR} (@acronym{GLR}) parsing, ambiguous grammars
960 @cindex reduce/reduce conflicts
962 Let's consider an example, vastly simplified from a C++ grammar.
967 #define YYSTYPE char const *
969 void yyerror (char const *);
982 | prog stmt @{ printf ("\n"); @}
985 stmt : expr ';' %dprec 1
989 expr : ID @{ printf ("%s ", $$); @}
990 | TYPENAME '(' expr ')'
991 @{ printf ("%s <cast> ", $1); @}
992 | expr '+' expr @{ printf ("+ "); @}
993 | expr '=' expr @{ printf ("= "); @}
996 decl : TYPENAME declarator ';'
997 @{ printf ("%s <declare> ", $1); @}
998 | TYPENAME declarator '=' expr ';'
999 @{ printf ("%s <init-declare> ", $1); @}
1002 declarator : ID @{ printf ("\"%s\" ", $1); @}
1003 | '(' declarator ')'
1008 This models a problematic part of the C++ grammar---the ambiguity between
1009 certain declarations and statements. For example,
1016 parses as either an @code{expr} or a @code{stmt}
1017 (assuming that @samp{T} is recognized as a @code{TYPENAME} and
1018 @samp{x} as an @code{ID}).
1019 Bison detects this as a reduce/reduce conflict between the rules
1020 @code{expr : ID} and @code{declarator : ID}, which it cannot resolve at the
1021 time it encounters @code{x} in the example above. Since this is a
1022 @acronym{GLR} parser, it therefore splits the problem into two parses, one for
1023 each choice of resolving the reduce/reduce conflict.
1024 Unlike the example from the previous section (@pxref{Simple GLR Parsers}),
1025 however, neither of these parses ``dies,'' because the grammar as it stands is
1026 ambiguous. One of the parsers eventually reduces @code{stmt : expr ';'} and
1027 the other reduces @code{stmt : decl}, after which both parsers are in an
1028 identical state: they've seen @samp{prog stmt} and have the same unprocessed
1029 input remaining. We say that these parses have @dfn{merged.}
1031 At this point, the @acronym{GLR} parser requires a specification in the
1032 grammar of how to choose between the competing parses.
1033 In the example above, the two @code{%dprec}
1034 declarations specify that Bison is to give precedence
1035 to the parse that interprets the example as a
1036 @code{decl}, which implies that @code{x} is a declarator.
1037 The parser therefore prints
1040 "x" y z + T <init-declare>
1043 The @code{%dprec} declarations only come into play when more than one
1044 parse survives. Consider a different input string for this parser:
1051 This is another example of using @acronym{GLR} to parse an unambiguous
1052 construct, as shown in the previous section (@pxref{Simple GLR Parsers}).
1053 Here, there is no ambiguity (this cannot be parsed as a declaration).
1054 However, at the time the Bison parser encounters @code{x}, it does not
1055 have enough information to resolve the reduce/reduce conflict (again,
1056 between @code{x} as an @code{expr} or a @code{declarator}). In this
1057 case, no precedence declaration is used. Again, the parser splits
1058 into two, one assuming that @code{x} is an @code{expr}, and the other
1059 assuming @code{x} is a @code{declarator}. The second of these parsers
1060 then vanishes when it sees @code{+}, and the parser prints
1066 Suppose that instead of resolving the ambiguity, you wanted to see all
1067 the possibilities. For this purpose, you must merge the semantic
1068 actions of the two possible parsers, rather than choosing one over the
1069 other. To do so, you could change the declaration of @code{stmt} as
1073 stmt : expr ';' %merge <stmtMerge>
1074 | decl %merge <stmtMerge>
1079 and define the @code{stmtMerge} function as:
1083 stmtMerge (YYSTYPE x0, YYSTYPE x1)
1091 with an accompanying forward declaration
1092 in the C declarations at the beginning of the file:
1096 #define YYSTYPE char const *
1097 static YYSTYPE stmtMerge (YYSTYPE x0, YYSTYPE x1);
1102 With these declarations, the resulting parser parses the first example
1103 as both an @code{expr} and a @code{decl}, and prints
1106 "x" y z + T <init-declare> x T <cast> y z + = <OR>
1109 Bison requires that all of the
1110 productions that participate in any particular merge have identical
1111 @samp{%merge} clauses. Otherwise, the ambiguity would be unresolvable,
1112 and the parser will report an error during any parse that results in
1113 the offending merge.
1115 @node GLR Semantic Actions
1116 @subsection GLR Semantic Actions
1118 @cindex deferred semantic actions
1119 By definition, a deferred semantic action is not performed at the same time as
1120 the associated reduction.
1121 This raises caveats for several Bison features you might use in a semantic
1122 action in a @acronym{GLR} parser.
1125 @cindex @acronym{GLR} parsers and @code{yychar}
1127 @cindex @acronym{GLR} parsers and @code{yylval}
1129 @cindex @acronym{GLR} parsers and @code{yylloc}
1130 In any semantic action, you can examine @code{yychar} to determine the type of
1131 the lookahead token present at the time of the associated reduction.
1132 After checking that @code{yychar} is not set to @code{YYEMPTY} or @code{YYEOF},
1133 you can then examine @code{yylval} and @code{yylloc} to determine the
1134 lookahead token's semantic value and location, if any.
1135 In a nondeferred semantic action, you can also modify any of these variables to
1136 influence syntax analysis.
1137 @xref{Lookahead, ,Lookahead Tokens}.
1140 @cindex @acronym{GLR} parsers and @code{yyclearin}
1141 In a deferred semantic action, it's too late to influence syntax analysis.
1142 In this case, @code{yychar}, @code{yylval}, and @code{yylloc} are set to
1143 shallow copies of the values they had at the time of the associated reduction.
1144 For this reason alone, modifying them is dangerous.
1145 Moreover, the result of modifying them is undefined and subject to change with
1146 future versions of Bison.
1147 For example, if a semantic action might be deferred, you should never write it
1148 to invoke @code{yyclearin} (@pxref{Action Features}) or to attempt to free
1149 memory referenced by @code{yylval}.
1152 @cindex @acronym{GLR} parsers and @code{YYERROR}
1153 Another Bison feature requiring special consideration is @code{YYERROR}
1154 (@pxref{Action Features}), which you can invoke in a semantic action to
1155 initiate error recovery.
1156 During deterministic @acronym{GLR} operation, the effect of @code{YYERROR} is
1157 the same as its effect in a deterministic parser.
1158 In a deferred semantic action, its effect is undefined.
1159 @c The effect is probably a syntax error at the split point.
1161 Also, see @ref{Location Default Action, ,Default Action for Locations}, which
1162 describes a special usage of @code{YYLLOC_DEFAULT} in @acronym{GLR} parsers.
1164 @node Compiler Requirements
1165 @subsection Considerations when Compiling @acronym{GLR} Parsers
1166 @cindex @code{inline}
1167 @cindex @acronym{GLR} parsers and @code{inline}
1169 The @acronym{GLR} parsers require a compiler for @acronym{ISO} C89 or
1170 later. In addition, they use the @code{inline} keyword, which is not
1171 C89, but is C99 and is a common extension in pre-C99 compilers. It is
1172 up to the user of these parsers to handle
1173 portability issues. For instance, if using Autoconf and the Autoconf
1174 macro @code{AC_C_INLINE}, a mere
1183 will suffice. Otherwise, we suggest
1187 #if __STDC_VERSION__ < 199901 && ! defined __GNUC__ && ! defined inline
1193 @node Locations Overview
1196 @cindex textual location
1197 @cindex location, textual
1199 Many applications, like interpreters or compilers, have to produce verbose
1200 and useful error messages. To achieve this, one must be able to keep track of
1201 the @dfn{textual location}, or @dfn{location}, of each syntactic construct.
1202 Bison provides a mechanism for handling these locations.
1204 Each token has a semantic value. In a similar fashion, each token has an
1205 associated location, but the type of locations is the same for all tokens and
1206 groupings. Moreover, the output parser is equipped with a default data
1207 structure for storing locations (@pxref{Locations}, for more details).
1209 Like semantic values, locations can be reached in actions using a dedicated
1210 set of constructs. In the example above, the location of the whole grouping
1211 is @code{@@$}, while the locations of the subexpressions are @code{@@1} and
1214 When a rule is matched, a default action is used to compute the semantic value
1215 of its left hand side (@pxref{Actions}). In the same way, another default
1216 action is used for locations. However, the action for locations is general
1217 enough for most cases, meaning there is usually no need to describe for each
1218 rule how @code{@@$} should be formed. When building a new location for a given
1219 grouping, the default behavior of the output parser is to take the beginning
1220 of the first symbol, and the end of the last symbol.
1223 @section Bison Output: the Parser File
1224 @cindex Bison parser
1225 @cindex Bison utility
1226 @cindex lexical analyzer, purpose
1229 When you run Bison, you give it a Bison grammar file as input. The output
1230 is a C source file that parses the language described by the grammar.
1231 This file is called a @dfn{Bison parser}. Keep in mind that the Bison
1232 utility and the Bison parser are two distinct programs: the Bison utility
1233 is a program whose output is the Bison parser that becomes part of your
1236 The job of the Bison parser is to group tokens into groupings according to
1237 the grammar rules---for example, to build identifiers and operators into
1238 expressions. As it does this, it runs the actions for the grammar rules it
1241 The tokens come from a function called the @dfn{lexical analyzer} that
1242 you must supply in some fashion (such as by writing it in C). The Bison
1243 parser calls the lexical analyzer each time it wants a new token. It
1244 doesn't know what is ``inside'' the tokens (though their semantic values
1245 may reflect this). Typically the lexical analyzer makes the tokens by
1246 parsing characters of text, but Bison does not depend on this.
1247 @xref{Lexical, ,The Lexical Analyzer Function @code{yylex}}.
1249 The Bison parser file is C code which defines a function named
1250 @code{yyparse} which implements that grammar. This function does not make
1251 a complete C program: you must supply some additional functions. One is
1252 the lexical analyzer. Another is an error-reporting function which the
1253 parser calls to report an error. In addition, a complete C program must
1254 start with a function called @code{main}; you have to provide this, and
1255 arrange for it to call @code{yyparse} or the parser will never run.
1256 @xref{Interface, ,Parser C-Language Interface}.
1258 Aside from the token type names and the symbols in the actions you
1259 write, all symbols defined in the Bison parser file itself
1260 begin with @samp{yy} or @samp{YY}. This includes interface functions
1261 such as the lexical analyzer function @code{yylex}, the error reporting
1262 function @code{yyerror} and the parser function @code{yyparse} itself.
1263 This also includes numerous identifiers used for internal purposes.
1264 Therefore, you should avoid using C identifiers starting with @samp{yy}
1265 or @samp{YY} in the Bison grammar file except for the ones defined in
1266 this manual. Also, you should avoid using the C identifiers
1267 @samp{malloc} and @samp{free} for anything other than their usual
1270 In some cases the Bison parser file includes system headers, and in
1271 those cases your code should respect the identifiers reserved by those
1272 headers. On some non-@acronym{GNU} hosts, @code{<alloca.h>}, @code{<malloc.h>},
1273 @code{<stddef.h>}, and @code{<stdlib.h>} are included as needed to
1274 declare memory allocators and related types. @code{<libintl.h>} is
1275 included if message translation is in use
1276 (@pxref{Internationalization}). Other system headers may
1277 be included if you define @code{YYDEBUG} to a nonzero value
1278 (@pxref{Tracing, ,Tracing Your Parser}).
1281 @section Stages in Using Bison
1282 @cindex stages in using Bison
1285 The actual language-design process using Bison, from grammar specification
1286 to a working compiler or interpreter, has these parts:
1290 Formally specify the grammar in a form recognized by Bison
1291 (@pxref{Grammar File, ,Bison Grammar Files}). For each grammatical rule
1292 in the language, describe the action that is to be taken when an
1293 instance of that rule is recognized. The action is described by a
1294 sequence of C statements.
1297 Write a lexical analyzer to process input and pass tokens to the parser.
1298 The lexical analyzer may be written by hand in C (@pxref{Lexical, ,The
1299 Lexical Analyzer Function @code{yylex}}). It could also be produced
1300 using Lex, but the use of Lex is not discussed in this manual.
1303 Write a controlling function that calls the Bison-produced parser.
1306 Write error-reporting routines.
1309 To turn this source code as written into a runnable program, you
1310 must follow these steps:
1314 Run Bison on the grammar to produce the parser.
1317 Compile the code output by Bison, as well as any other source files.
1320 Link the object files to produce the finished product.
1323 @node Grammar Layout
1324 @section The Overall Layout of a Bison Grammar
1325 @cindex grammar file
1327 @cindex format of grammar file
1328 @cindex layout of Bison grammar
1330 The input file for the Bison utility is a @dfn{Bison grammar file}. The
1331 general form of a Bison grammar file is as follows:
1338 @var{Bison declarations}
1347 The @samp{%%}, @samp{%@{} and @samp{%@}} are punctuation that appears
1348 in every Bison grammar file to separate the sections.
1350 The prologue may define types and variables used in the actions. You can
1351 also use preprocessor commands to define macros used there, and use
1352 @code{#include} to include header files that do any of these things.
1353 You need to declare the lexical analyzer @code{yylex} and the error
1354 printer @code{yyerror} here, along with any other global identifiers
1355 used by the actions in the grammar rules.
1357 The Bison declarations declare the names of the terminal and nonterminal
1358 symbols, and may also describe operator precedence and the data types of
1359 semantic values of various symbols.
1361 The grammar rules define how to construct each nonterminal symbol from its
1364 The epilogue can contain any code you want to use. Often the
1365 definitions of functions declared in the prologue go here. In a
1366 simple program, all the rest of the program can go here.
1370 @cindex simple examples
1371 @cindex examples, simple
1373 Now we show and explain three sample programs written using Bison: a
1374 reverse polish notation calculator, an algebraic (infix) notation
1375 calculator, and a multi-function calculator. All three have been tested
1376 under BSD Unix 4.3; each produces a usable, though limited, interactive
1377 desk-top calculator.
1379 These examples are simple, but Bison grammars for real programming
1380 languages are written the same way. You can copy these examples into a
1381 source file to try them.
1384 * RPN Calc:: Reverse polish notation calculator;
1385 a first example with no operator precedence.
1386 * Infix Calc:: Infix (algebraic) notation calculator.
1387 Operator precedence is introduced.
1388 * Simple Error Recovery:: Continuing after syntax errors.
1389 * Location Tracking Calc:: Demonstrating the use of @@@var{n} and @@$.
1390 * Multi-function Calc:: Calculator with memory and trig functions.
1391 It uses multiple data-types for semantic values.
1392 * Exercises:: Ideas for improving the multi-function calculator.
1396 @section Reverse Polish Notation Calculator
1397 @cindex reverse polish notation
1398 @cindex polish notation calculator
1399 @cindex @code{rpcalc}
1400 @cindex calculator, simple
1402 The first example is that of a simple double-precision @dfn{reverse polish
1403 notation} calculator (a calculator using postfix operators). This example
1404 provides a good starting point, since operator precedence is not an issue.
1405 The second example will illustrate how operator precedence is handled.
1407 The source code for this calculator is named @file{rpcalc.y}. The
1408 @samp{.y} extension is a convention used for Bison input files.
1411 * Rpcalc Declarations:: Prologue (declarations) for rpcalc.
1412 * Rpcalc Rules:: Grammar Rules for rpcalc, with explanation.
1413 * Rpcalc Lexer:: The lexical analyzer.
1414 * Rpcalc Main:: The controlling function.
1415 * Rpcalc Error:: The error reporting function.
1416 * Rpcalc Generate:: Running Bison on the grammar file.
1417 * Rpcalc Compile:: Run the C compiler on the output code.
1420 @node Rpcalc Declarations
1421 @subsection Declarations for @code{rpcalc}
1423 Here are the C and Bison declarations for the reverse polish notation
1424 calculator. As in C, comments are placed between @samp{/*@dots{}*/}.
1427 /* Reverse polish notation calculator. */
1430 #define YYSTYPE double
1433 void yyerror (char const *);
1438 %% /* Grammar rules and actions follow. */
1441 The declarations section (@pxref{Prologue, , The prologue}) contains two
1442 preprocessor directives and two forward declarations.
1444 The @code{#define} directive defines the macro @code{YYSTYPE}, thus
1445 specifying the C data type for semantic values of both tokens and
1446 groupings (@pxref{Value Type, ,Data Types of Semantic Values}). The
1447 Bison parser will use whatever type @code{YYSTYPE} is defined as; if you
1448 don't define it, @code{int} is the default. Because we specify
1449 @code{double}, each token and each expression has an associated value,
1450 which is a floating point number.
1452 The @code{#include} directive is used to declare the exponentiation
1453 function @code{pow}.
1455 The forward declarations for @code{yylex} and @code{yyerror} are
1456 needed because the C language requires that functions be declared
1457 before they are used. These functions will be defined in the
1458 epilogue, but the parser calls them so they must be declared in the
1461 The second section, Bison declarations, provides information to Bison
1462 about the token types (@pxref{Bison Declarations, ,The Bison
1463 Declarations Section}). Each terminal symbol that is not a
1464 single-character literal must be declared here. (Single-character
1465 literals normally don't need to be declared.) In this example, all the
1466 arithmetic operators are designated by single-character literals, so the
1467 only terminal symbol that needs to be declared is @code{NUM}, the token
1468 type for numeric constants.
1471 @subsection Grammar Rules for @code{rpcalc}
1473 Here are the grammar rules for the reverse polish notation calculator.
1481 | exp '\n' @{ printf ("\t%.10g\n", $1); @}
1484 exp: NUM @{ $$ = $1; @}
1485 | exp exp '+' @{ $$ = $1 + $2; @}
1486 | exp exp '-' @{ $$ = $1 - $2; @}
1487 | exp exp '*' @{ $$ = $1 * $2; @}
1488 | exp exp '/' @{ $$ = $1 / $2; @}
1489 /* Exponentiation */
1490 | exp exp '^' @{ $$ = pow ($1, $2); @}
1492 | exp 'n' @{ $$ = -$1; @}
1497 The groupings of the rpcalc ``language'' defined here are the expression
1498 (given the name @code{exp}), the line of input (@code{line}), and the
1499 complete input transcript (@code{input}). Each of these nonterminal
1500 symbols has several alternate rules, joined by the vertical bar @samp{|}
1501 which is read as ``or''. The following sections explain what these rules
1504 The semantics of the language is determined by the actions taken when a
1505 grouping is recognized. The actions are the C code that appears inside
1506 braces. @xref{Actions}.
1508 You must specify these actions in C, but Bison provides the means for
1509 passing semantic values between the rules. In each action, the
1510 pseudo-variable @code{$$} stands for the semantic value for the grouping
1511 that the rule is going to construct. Assigning a value to @code{$$} is the
1512 main job of most actions. The semantic values of the components of the
1513 rule are referred to as @code{$1}, @code{$2}, and so on.
1522 @subsubsection Explanation of @code{input}
1524 Consider the definition of @code{input}:
1532 This definition reads as follows: ``A complete input is either an empty
1533 string, or a complete input followed by an input line''. Notice that
1534 ``complete input'' is defined in terms of itself. This definition is said
1535 to be @dfn{left recursive} since @code{input} appears always as the
1536 leftmost symbol in the sequence. @xref{Recursion, ,Recursive Rules}.
1538 The first alternative is empty because there are no symbols between the
1539 colon and the first @samp{|}; this means that @code{input} can match an
1540 empty string of input (no tokens). We write the rules this way because it
1541 is legitimate to type @kbd{Ctrl-d} right after you start the calculator.
1542 It's conventional to put an empty alternative first and write the comment
1543 @samp{/* empty */} in it.
1545 The second alternate rule (@code{input line}) handles all nontrivial input.
1546 It means, ``After reading any number of lines, read one more line if
1547 possible.'' The left recursion makes this rule into a loop. Since the
1548 first alternative matches empty input, the loop can be executed zero or
1551 The parser function @code{yyparse} continues to process input until a
1552 grammatical error is seen or the lexical analyzer says there are no more
1553 input tokens; we will arrange for the latter to happen at end-of-input.
1556 @subsubsection Explanation of @code{line}
1558 Now consider the definition of @code{line}:
1562 | exp '\n' @{ printf ("\t%.10g\n", $1); @}
1566 The first alternative is a token which is a newline character; this means
1567 that rpcalc accepts a blank line (and ignores it, since there is no
1568 action). The second alternative is an expression followed by a newline.
1569 This is the alternative that makes rpcalc useful. The semantic value of
1570 the @code{exp} grouping is the value of @code{$1} because the @code{exp} in
1571 question is the first symbol in the alternative. The action prints this
1572 value, which is the result of the computation the user asked for.
1574 This action is unusual because it does not assign a value to @code{$$}. As
1575 a consequence, the semantic value associated with the @code{line} is
1576 uninitialized (its value will be unpredictable). This would be a bug if
1577 that value were ever used, but we don't use it: once rpcalc has printed the
1578 value of the user's input line, that value is no longer needed.
1581 @subsubsection Explanation of @code{expr}
1583 The @code{exp} grouping has several rules, one for each kind of expression.
1584 The first rule handles the simplest expressions: those that are just numbers.
1585 The second handles an addition-expression, which looks like two expressions
1586 followed by a plus-sign. The third handles subtraction, and so on.
1590 | exp exp '+' @{ $$ = $1 + $2; @}
1591 | exp exp '-' @{ $$ = $1 - $2; @}
1596 We have used @samp{|} to join all the rules for @code{exp}, but we could
1597 equally well have written them separately:
1601 exp: exp exp '+' @{ $$ = $1 + $2; @} ;
1602 exp: exp exp '-' @{ $$ = $1 - $2; @} ;
1606 Most of the rules have actions that compute the value of the expression in
1607 terms of the value of its parts. For example, in the rule for addition,
1608 @code{$1} refers to the first component @code{exp} and @code{$2} refers to
1609 the second one. The third component, @code{'+'}, has no meaningful
1610 associated semantic value, but if it had one you could refer to it as
1611 @code{$3}. When @code{yyparse} recognizes a sum expression using this
1612 rule, the sum of the two subexpressions' values is produced as the value of
1613 the entire expression. @xref{Actions}.
1615 You don't have to give an action for every rule. When a rule has no
1616 action, Bison by default copies the value of @code{$1} into @code{$$}.
1617 This is what happens in the first rule (the one that uses @code{NUM}).
1619 The formatting shown here is the recommended convention, but Bison does
1620 not require it. You can add or change white space as much as you wish.
1624 exp : NUM | exp exp '+' @{$$ = $1 + $2; @} | @dots{} ;
1628 means the same thing as this:
1632 | exp exp '+' @{ $$ = $1 + $2; @}
1638 The latter, however, is much more readable.
1641 @subsection The @code{rpcalc} Lexical Analyzer
1642 @cindex writing a lexical analyzer
1643 @cindex lexical analyzer, writing
1645 The lexical analyzer's job is low-level parsing: converting characters
1646 or sequences of characters into tokens. The Bison parser gets its
1647 tokens by calling the lexical analyzer. @xref{Lexical, ,The Lexical
1648 Analyzer Function @code{yylex}}.
1650 Only a simple lexical analyzer is needed for the @acronym{RPN}
1652 lexical analyzer skips blanks and tabs, then reads in numbers as
1653 @code{double} and returns them as @code{NUM} tokens. Any other character
1654 that isn't part of a number is a separate token. Note that the token-code
1655 for such a single-character token is the character itself.
1657 The return value of the lexical analyzer function is a numeric code which
1658 represents a token type. The same text used in Bison rules to stand for
1659 this token type is also a C expression for the numeric code for the type.
1660 This works in two ways. If the token type is a character literal, then its
1661 numeric code is that of the character; you can use the same
1662 character literal in the lexical analyzer to express the number. If the
1663 token type is an identifier, that identifier is defined by Bison as a C
1664 macro whose definition is the appropriate number. In this example,
1665 therefore, @code{NUM} becomes a macro for @code{yylex} to use.
1667 The semantic value of the token (if it has one) is stored into the
1668 global variable @code{yylval}, which is where the Bison parser will look
1669 for it. (The C data type of @code{yylval} is @code{YYSTYPE}, which was
1670 defined at the beginning of the grammar; @pxref{Rpcalc Declarations,
1671 ,Declarations for @code{rpcalc}}.)
1673 A token type code of zero is returned if the end-of-input is encountered.
1674 (Bison recognizes any nonpositive value as indicating end-of-input.)
1676 Here is the code for the lexical analyzer:
1680 /* The lexical analyzer returns a double floating point
1681 number on the stack and the token NUM, or the numeric code
1682 of the character read if not a number. It skips all blanks
1683 and tabs, and returns 0 for end-of-input. */
1694 /* Skip white space. */
1695 while ((c = getchar ()) == ' ' || c == '\t')
1699 /* Process numbers. */
1700 if (c == '.' || isdigit (c))
1703 scanf ("%lf", &yylval);
1708 /* Return end-of-input. */
1711 /* Return a single char. */
1718 @subsection The Controlling Function
1719 @cindex controlling function
1720 @cindex main function in simple example
1722 In keeping with the spirit of this example, the controlling function is
1723 kept to the bare minimum. The only requirement is that it call
1724 @code{yyparse} to start the process of parsing.
1737 @subsection The Error Reporting Routine
1738 @cindex error reporting routine
1740 When @code{yyparse} detects a syntax error, it calls the error reporting
1741 function @code{yyerror} to print an error message (usually but not
1742 always @code{"syntax error"}). It is up to the programmer to supply
1743 @code{yyerror} (@pxref{Interface, ,Parser C-Language Interface}), so
1744 here is the definition we will use:
1750 /* Called by yyparse on error. */
1752 yyerror (char const *s)
1754 fprintf (stderr, "%s\n", s);
1759 After @code{yyerror} returns, the Bison parser may recover from the error
1760 and continue parsing if the grammar contains a suitable error rule
1761 (@pxref{Error Recovery}). Otherwise, @code{yyparse} returns nonzero. We
1762 have not written any error rules in this example, so any invalid input will
1763 cause the calculator program to exit. This is not clean behavior for a
1764 real calculator, but it is adequate for the first example.
1766 @node Rpcalc Generate
1767 @subsection Running Bison to Make the Parser
1768 @cindex running Bison (introduction)
1770 Before running Bison to produce a parser, we need to decide how to
1771 arrange all the source code in one or more source files. For such a
1772 simple example, the easiest thing is to put everything in one file. The
1773 definitions of @code{yylex}, @code{yyerror} and @code{main} go at the
1774 end, in the epilogue of the file
1775 (@pxref{Grammar Layout, ,The Overall Layout of a Bison Grammar}).
1777 For a large project, you would probably have several source files, and use
1778 @code{make} to arrange to recompile them.
1780 With all the source in a single file, you use the following command to
1781 convert it into a parser file:
1788 In this example the file was called @file{rpcalc.y} (for ``Reverse Polish
1789 @sc{calc}ulator''). Bison produces a file named @file{@var{file}.tab.c},
1790 removing the @samp{.y} from the original file name. The file output by
1791 Bison contains the source code for @code{yyparse}. The additional
1792 functions in the input file (@code{yylex}, @code{yyerror} and @code{main})
1793 are copied verbatim to the output.
1795 @node Rpcalc Compile
1796 @subsection Compiling the Parser File
1797 @cindex compiling the parser
1799 Here is how to compile and run the parser file:
1803 # @r{List files in current directory.}
1805 rpcalc.tab.c rpcalc.y
1809 # @r{Compile the Bison parser.}
1810 # @r{@samp{-lm} tells compiler to search math library for @code{pow}.}
1811 $ @kbd{cc -lm -o rpcalc rpcalc.tab.c}
1815 # @r{List files again.}
1817 rpcalc rpcalc.tab.c rpcalc.y
1821 The file @file{rpcalc} now contains the executable code. Here is an
1822 example session using @code{rpcalc}.
1828 @kbd{3 7 + 3 4 5 *+-}
1830 @kbd{3 7 + 3 4 5 * + - n} @r{Note the unary minus, @samp{n}}
1834 @kbd{3 4 ^} @r{Exponentiation}
1836 @kbd{^D} @r{End-of-file indicator}
1841 @section Infix Notation Calculator: @code{calc}
1842 @cindex infix notation calculator
1844 @cindex calculator, infix notation
1846 We now modify rpcalc to handle infix operators instead of postfix. Infix
1847 notation involves the concept of operator precedence and the need for
1848 parentheses nested to arbitrary depth. Here is the Bison code for
1849 @file{calc.y}, an infix desk-top calculator.
1852 /* Infix notation calculator. */
1855 #define YYSTYPE double
1859 void yyerror (char const *);
1862 /* Bison declarations. */
1866 %precedence NEG /* negation--unary minus */
1867 %right '^' /* exponentiation */
1869 %% /* The grammar follows. */
1875 | exp '\n' @{ printf ("\t%.10g\n", $1); @}
1878 exp: NUM @{ $$ = $1; @}
1879 | exp '+' exp @{ $$ = $1 + $3; @}
1880 | exp '-' exp @{ $$ = $1 - $3; @}
1881 | exp '*' exp @{ $$ = $1 * $3; @}
1882 | exp '/' exp @{ $$ = $1 / $3; @}
1883 | '-' exp %prec NEG @{ $$ = -$2; @}
1884 | exp '^' exp @{ $$ = pow ($1, $3); @}
1885 | '(' exp ')' @{ $$ = $2; @}
1891 The functions @code{yylex}, @code{yyerror} and @code{main} can be the
1894 There are two important new features shown in this code.
1896 In the second section (Bison declarations), @code{%left} declares token
1897 types and says they are left-associative operators. The declarations
1898 @code{%left} and @code{%right} (right associativity) take the place of
1899 @code{%token} which is used to declare a token type name without
1900 associativity/precedence. (These tokens are single-character literals, which
1901 ordinarily don't need to be declared. We declare them here to specify
1902 the associativity/precedence.)
1904 Operator precedence is determined by the line ordering of the
1905 declarations; the higher the line number of the declaration (lower on
1906 the page or screen), the higher the precedence. Hence, exponentiation
1907 has the highest precedence, unary minus (@code{NEG}) is next, followed
1908 by @samp{*} and @samp{/}, and so on. Unary minus is not associative,
1909 only precedence matters (@code{%precedence}. @xref{Precedence, ,Operator
1912 The other important new feature is the @code{%prec} in the grammar
1913 section for the unary minus operator. The @code{%prec} simply instructs
1914 Bison that the rule @samp{| '-' exp} has the same precedence as
1915 @code{NEG}---in this case the next-to-highest. @xref{Contextual
1916 Precedence, ,Context-Dependent Precedence}.
1918 Here is a sample run of @file{calc.y}:
1923 @kbd{4 + 4.5 - (34/(8*3+-3))}
1931 @node Simple Error Recovery
1932 @section Simple Error Recovery
1933 @cindex error recovery, simple
1935 Up to this point, this manual has not addressed the issue of @dfn{error
1936 recovery}---how to continue parsing after the parser detects a syntax
1937 error. All we have handled is error reporting with @code{yyerror}.
1938 Recall that by default @code{yyparse} returns after calling
1939 @code{yyerror}. This means that an erroneous input line causes the
1940 calculator program to exit. Now we show how to rectify this deficiency.
1942 The Bison language itself includes the reserved word @code{error}, which
1943 may be included in the grammar rules. In the example below it has
1944 been added to one of the alternatives for @code{line}:
1949 | exp '\n' @{ printf ("\t%.10g\n", $1); @}
1950 | error '\n' @{ yyerrok; @}
1955 This addition to the grammar allows for simple error recovery in the
1956 event of a syntax error. If an expression that cannot be evaluated is
1957 read, the error will be recognized by the third rule for @code{line},
1958 and parsing will continue. (The @code{yyerror} function is still called
1959 upon to print its message as well.) The action executes the statement
1960 @code{yyerrok}, a macro defined automatically by Bison; its meaning is
1961 that error recovery is complete (@pxref{Error Recovery}). Note the
1962 difference between @code{yyerrok} and @code{yyerror}; neither one is a
1965 This form of error recovery deals with syntax errors. There are other
1966 kinds of errors; for example, division by zero, which raises an exception
1967 signal that is normally fatal. A real calculator program must handle this
1968 signal and use @code{longjmp} to return to @code{main} and resume parsing
1969 input lines; it would also have to discard the rest of the current line of
1970 input. We won't discuss this issue further because it is not specific to
1973 @node Location Tracking Calc
1974 @section Location Tracking Calculator: @code{ltcalc}
1975 @cindex location tracking calculator
1976 @cindex @code{ltcalc}
1977 @cindex calculator, location tracking
1979 This example extends the infix notation calculator with location
1980 tracking. This feature will be used to improve the error messages. For
1981 the sake of clarity, this example is a simple integer calculator, since
1982 most of the work needed to use locations will be done in the lexical
1986 * Ltcalc Declarations:: Bison and C declarations for ltcalc.
1987 * Ltcalc Rules:: Grammar rules for ltcalc, with explanations.
1988 * Ltcalc Lexer:: The lexical analyzer.
1991 @node Ltcalc Declarations
1992 @subsection Declarations for @code{ltcalc}
1994 The C and Bison declarations for the location tracking calculator are
1995 the same as the declarations for the infix notation calculator.
1998 /* Location tracking calculator. */
2004 void yyerror (char const *);
2007 /* Bison declarations. */
2015 %% /* The grammar follows. */
2019 Note there are no declarations specific to locations. Defining a data
2020 type for storing locations is not needed: we will use the type provided
2021 by default (@pxref{Location Type, ,Data Types of Locations}), which is a
2022 four member structure with the following integer fields:
2023 @code{first_line}, @code{first_column}, @code{last_line} and
2024 @code{last_column}. By conventions, and in accordance with the GNU
2025 Coding Standards and common practice, the line and column count both
2029 @subsection Grammar Rules for @code{ltcalc}
2031 Whether handling locations or not has no effect on the syntax of your
2032 language. Therefore, grammar rules for this example will be very close
2033 to those of the previous example: we will only modify them to benefit
2034 from the new information.
2036 Here, we will use locations to report divisions by zero, and locate the
2037 wrong expressions or subexpressions.
2048 | exp '\n' @{ printf ("%d\n", $1); @}
2053 exp : NUM @{ $$ = $1; @}
2054 | exp '+' exp @{ $$ = $1 + $3; @}
2055 | exp '-' exp @{ $$ = $1 - $3; @}
2056 | exp '*' exp @{ $$ = $1 * $3; @}
2066 fprintf (stderr, "%d.%d-%d.%d: division by zero",
2067 @@3.first_line, @@3.first_column,
2068 @@3.last_line, @@3.last_column);
2073 | '-' exp %prec NEG @{ $$ = -$2; @}
2074 | exp '^' exp @{ $$ = pow ($1, $3); @}
2075 | '(' exp ')' @{ $$ = $2; @}
2079 This code shows how to reach locations inside of semantic actions, by
2080 using the pseudo-variables @code{@@@var{n}} for rule components, and the
2081 pseudo-variable @code{@@$} for groupings.
2083 We don't need to assign a value to @code{@@$}: the output parser does it
2084 automatically. By default, before executing the C code of each action,
2085 @code{@@$} is set to range from the beginning of @code{@@1} to the end
2086 of @code{@@@var{n}}, for a rule with @var{n} components. This behavior
2087 can be redefined (@pxref{Location Default Action, , Default Action for
2088 Locations}), and for very specific rules, @code{@@$} can be computed by
2092 @subsection The @code{ltcalc} Lexical Analyzer.
2094 Until now, we relied on Bison's defaults to enable location
2095 tracking. The next step is to rewrite the lexical analyzer, and make it
2096 able to feed the parser with the token locations, as it already does for
2099 To this end, we must take into account every single character of the
2100 input text, to avoid the computed locations of being fuzzy or wrong:
2111 /* Skip white space. */
2112 while ((c = getchar ()) == ' ' || c == '\t')
2113 ++yylloc.last_column;
2118 yylloc.first_line = yylloc.last_line;
2119 yylloc.first_column = yylloc.last_column;
2123 /* Process numbers. */
2127 ++yylloc.last_column;
2128 while (isdigit (c = getchar ()))
2130 ++yylloc.last_column;
2131 yylval = yylval * 10 + c - '0';
2138 /* Return end-of-input. */
2142 /* Return a single char, and update location. */
2146 yylloc.last_column = 0;
2149 ++yylloc.last_column;
2154 Basically, the lexical analyzer performs the same processing as before:
2155 it skips blanks and tabs, and reads numbers or single-character tokens.
2156 In addition, it updates @code{yylloc}, the global variable (of type
2157 @code{YYLTYPE}) containing the token's location.
2159 Now, each time this function returns a token, the parser has its number
2160 as well as its semantic value, and its location in the text. The last
2161 needed change is to initialize @code{yylloc}, for example in the
2162 controlling function:
2169 yylloc.first_line = yylloc.last_line = 1;
2170 yylloc.first_column = yylloc.last_column = 0;
2176 Remember that computing locations is not a matter of syntax. Every
2177 character must be associated to a location update, whether it is in
2178 valid input, in comments, in literal strings, and so on.
2180 @node Multi-function Calc
2181 @section Multi-Function Calculator: @code{mfcalc}
2182 @cindex multi-function calculator
2183 @cindex @code{mfcalc}
2184 @cindex calculator, multi-function
2186 Now that the basics of Bison have been discussed, it is time to move on to
2187 a more advanced problem. The above calculators provided only five
2188 functions, @samp{+}, @samp{-}, @samp{*}, @samp{/} and @samp{^}. It would
2189 be nice to have a calculator that provides other mathematical functions such
2190 as @code{sin}, @code{cos}, etc.
2192 It is easy to add new operators to the infix calculator as long as they are
2193 only single-character literals. The lexical analyzer @code{yylex} passes
2194 back all nonnumeric characters as tokens, so new grammar rules suffice for
2195 adding a new operator. But we want something more flexible: built-in
2196 functions whose syntax has this form:
2199 @var{function_name} (@var{argument})
2203 At the same time, we will add memory to the calculator, by allowing you
2204 to create named variables, store values in them, and use them later.
2205 Here is a sample session with the multi-function calculator:
2209 @kbd{pi = 3.141592653589}
2213 @kbd{alpha = beta1 = 2.3}
2219 @kbd{exp(ln(beta1))}
2224 Note that multiple assignment and nested function calls are permitted.
2227 * Mfcalc Declarations:: Bison declarations for multi-function calculator.
2228 * Mfcalc Rules:: Grammar rules for the calculator.
2229 * Mfcalc Symbol Table:: Symbol table management subroutines.
2232 @node Mfcalc Declarations
2233 @subsection Declarations for @code{mfcalc}
2235 Here are the C and Bison declarations for the multi-function calculator.
2240 #include <math.h> /* For math functions, cos(), sin(), etc. */
2241 #include "calc.h" /* Contains definition of `symrec'. */
2243 void yyerror (char const *);
2248 double val; /* For returning numbers. */
2249 symrec *tptr; /* For returning symbol-table pointers. */
2252 %token <val> NUM /* Simple double precision number. */
2253 %token <tptr> VAR FNCT /* Variable and Function. */
2260 %precedence NEG /* negation--unary minus */
2261 %right '^' /* exponentiation */
2263 %% /* The grammar follows. */
2266 The above grammar introduces only two new features of the Bison language.
2267 These features allow semantic values to have various data types
2268 (@pxref{Multiple Types, ,More Than One Value Type}).
2270 The @code{%union} declaration specifies the entire list of possible types;
2271 this is instead of defining @code{YYSTYPE}. The allowable types are now
2272 double-floats (for @code{exp} and @code{NUM}) and pointers to entries in
2273 the symbol table. @xref{Union Decl, ,The Collection of Value Types}.
2275 Since values can now have various types, it is necessary to associate a
2276 type with each grammar symbol whose semantic value is used. These symbols
2277 are @code{NUM}, @code{VAR}, @code{FNCT}, and @code{exp}. Their
2278 declarations are augmented with information about their data type (placed
2279 between angle brackets).
2281 The Bison construct @code{%type} is used for declaring nonterminal
2282 symbols, just as @code{%token} is used for declaring token types. We
2283 have not used @code{%type} before because nonterminal symbols are
2284 normally declared implicitly by the rules that define them. But
2285 @code{exp} must be declared explicitly so we can specify its value type.
2286 @xref{Type Decl, ,Nonterminal Symbols}.
2289 @subsection Grammar Rules for @code{mfcalc}
2291 Here are the grammar rules for the multi-function calculator.
2292 Most of them are copied directly from @code{calc}; three rules,
2293 those which mention @code{VAR} or @code{FNCT}, are new.
2305 | exp '\n' @{ printf ("\t%.10g\n", $1); @}
2306 | error '\n' @{ yyerrok; @}
2311 exp: NUM @{ $$ = $1; @}
2312 | VAR @{ $$ = $1->value.var; @}
2313 | VAR '=' exp @{ $$ = $3; $1->value.var = $3; @}
2314 | FNCT '(' exp ')' @{ $$ = (*($1->value.fnctptr))($3); @}
2315 | exp '+' exp @{ $$ = $1 + $3; @}
2316 | exp '-' exp @{ $$ = $1 - $3; @}
2317 | exp '*' exp @{ $$ = $1 * $3; @}
2318 | exp '/' exp @{ $$ = $1 / $3; @}
2319 | '-' exp %prec NEG @{ $$ = -$2; @}
2320 | exp '^' exp @{ $$ = pow ($1, $3); @}
2321 | '(' exp ')' @{ $$ = $2; @}
2324 /* End of grammar. */
2328 @node Mfcalc Symbol Table
2329 @subsection The @code{mfcalc} Symbol Table
2330 @cindex symbol table example
2332 The multi-function calculator requires a symbol table to keep track of the
2333 names and meanings of variables and functions. This doesn't affect the
2334 grammar rules (except for the actions) or the Bison declarations, but it
2335 requires some additional C functions for support.
2337 The symbol table itself consists of a linked list of records. Its
2338 definition, which is kept in the header @file{calc.h}, is as follows. It
2339 provides for either functions or variables to be placed in the table.
2343 /* Function type. */
2344 typedef double (*func_t) (double);
2348 /* Data type for links in the chain of symbols. */
2351 char *name; /* name of symbol */
2352 int type; /* type of symbol: either VAR or FNCT */
2355 double var; /* value of a VAR */
2356 func_t fnctptr; /* value of a FNCT */
2358 struct symrec *next; /* link field */
2363 typedef struct symrec symrec;
2365 /* The symbol table: a chain of `struct symrec'. */
2366 extern symrec *sym_table;
2368 symrec *putsym (char const *, int);
2369 symrec *getsym (char const *);
2373 The new version of @code{main} includes a call to @code{init_table}, a
2374 function that initializes the symbol table. Here it is, and
2375 @code{init_table} as well:
2381 /* Called by yyparse on error. */
2383 yyerror (char const *s)
2393 double (*fnct) (double);
2398 struct init const arith_fncts[] =
2411 /* The symbol table: a chain of `struct symrec'. */
2416 /* Put arithmetic functions in table. */
2422 for (i = 0; arith_fncts[i].fname != 0; i++)
2424 ptr = putsym (arith_fncts[i].fname, FNCT);
2425 ptr->value.fnctptr = arith_fncts[i].fnct;
2440 By simply editing the initialization list and adding the necessary include
2441 files, you can add additional functions to the calculator.
2443 Two important functions allow look-up and installation of symbols in the
2444 symbol table. The function @code{putsym} is passed a name and the type
2445 (@code{VAR} or @code{FNCT}) of the object to be installed. The object is
2446 linked to the front of the list, and a pointer to the object is returned.
2447 The function @code{getsym} is passed the name of the symbol to look up. If
2448 found, a pointer to that symbol is returned; otherwise zero is returned.
2452 putsym (char const *sym_name, int sym_type)
2455 ptr = (symrec *) malloc (sizeof (symrec));
2456 ptr->name = (char *) malloc (strlen (sym_name) + 1);
2457 strcpy (ptr->name,sym_name);
2458 ptr->type = sym_type;
2459 ptr->value.var = 0; /* Set value to 0 even if fctn. */
2460 ptr->next = (struct symrec *)sym_table;
2466 getsym (char const *sym_name)
2469 for (ptr = sym_table; ptr != (symrec *) 0;
2470 ptr = (symrec *)ptr->next)
2471 if (strcmp (ptr->name,sym_name) == 0)
2477 The function @code{yylex} must now recognize variables, numeric values, and
2478 the single-character arithmetic operators. Strings of alphanumeric
2479 characters with a leading letter are recognized as either variables or
2480 functions depending on what the symbol table says about them.
2482 The string is passed to @code{getsym} for look up in the symbol table. If
2483 the name appears in the table, a pointer to its location and its type
2484 (@code{VAR} or @code{FNCT}) is returned to @code{yyparse}. If it is not
2485 already in the table, then it is installed as a @code{VAR} using
2486 @code{putsym}. Again, a pointer and its type (which must be @code{VAR}) is
2487 returned to @code{yyparse}.
2489 No change is needed in the handling of numeric values and arithmetic
2490 operators in @code{yylex}.
2503 /* Ignore white space, get first nonwhite character. */
2504 while ((c = getchar ()) == ' ' || c == '\t');
2511 /* Char starts a number => parse the number. */
2512 if (c == '.' || isdigit (c))
2515 scanf ("%lf", &yylval.val);
2521 /* Char starts an identifier => read the name. */
2525 static char *symbuf = 0;
2526 static int length = 0;
2531 /* Initially make the buffer long enough
2532 for a 40-character symbol name. */
2534 length = 40, symbuf = (char *)malloc (length + 1);
2541 /* If buffer is full, make it bigger. */
2545 symbuf = (char *) realloc (symbuf, length + 1);
2547 /* Add this character to the buffer. */
2549 /* Get another character. */
2554 while (isalnum (c));
2561 s = getsym (symbuf);
2563 s = putsym (symbuf, VAR);
2568 /* Any other character is a token by itself. */
2574 This program is both powerful and flexible. You may easily add new
2575 functions, and it is a simple job to modify this code to install
2576 predefined variables such as @code{pi} or @code{e} as well.
2584 Add some new functions from @file{math.h} to the initialization list.
2587 Add another array that contains constants and their values. Then
2588 modify @code{init_table} to add these constants to the symbol table.
2589 It will be easiest to give the constants type @code{VAR}.
2592 Make the program report an error if the user refers to an
2593 uninitialized variable in any way except to store a value in it.
2597 @chapter Bison Grammar Files
2599 Bison takes as input a context-free grammar specification and produces a
2600 C-language function that recognizes correct instances of the grammar.
2602 The Bison grammar input file conventionally has a name ending in @samp{.y}.
2603 @xref{Invocation, ,Invoking Bison}.
2606 * Grammar Outline:: Overall layout of the grammar file.
2607 * Symbols:: Terminal and nonterminal symbols.
2608 * Rules:: How to write grammar rules.
2609 * Recursion:: Writing recursive rules.
2610 * Semantics:: Semantic values and actions.
2611 * Locations:: Locations and actions.
2612 * Declarations:: All kinds of Bison declarations are described here.
2613 * Multiple Parsers:: Putting more than one Bison parser in one program.
2616 @node Grammar Outline
2617 @section Outline of a Bison Grammar
2619 A Bison grammar file has four main sections, shown here with the
2620 appropriate delimiters:
2627 @var{Bison declarations}
2636 Comments enclosed in @samp{/* @dots{} */} may appear in any of the sections.
2637 As a @acronym{GNU} extension, @samp{//} introduces a comment that
2638 continues until end of line.
2641 * Prologue:: Syntax and usage of the prologue.
2642 * Prologue Alternatives:: Syntax and usage of alternatives to the prologue.
2643 * Bison Declarations:: Syntax and usage of the Bison declarations section.
2644 * Grammar Rules:: Syntax and usage of the grammar rules section.
2645 * Epilogue:: Syntax and usage of the epilogue.
2649 @subsection The prologue
2650 @cindex declarations section
2652 @cindex declarations
2654 The @var{Prologue} section contains macro definitions and declarations
2655 of functions and variables that are used in the actions in the grammar
2656 rules. These are copied to the beginning of the parser file so that
2657 they precede the definition of @code{yyparse}. You can use
2658 @samp{#include} to get the declarations from a header file. If you
2659 don't need any C declarations, you may omit the @samp{%@{} and
2660 @samp{%@}} delimiters that bracket this section.
2662 The @var{Prologue} section is terminated by the first occurrence
2663 of @samp{%@}} that is outside a comment, a string literal, or a
2666 You may have more than one @var{Prologue} section, intermixed with the
2667 @var{Bison declarations}. This allows you to have C and Bison
2668 declarations that refer to each other. For example, the @code{%union}
2669 declaration may use types defined in a header file, and you may wish to
2670 prototype functions that take arguments of type @code{YYSTYPE}. This
2671 can be done with two @var{Prologue} blocks, one before and one after the
2672 @code{%union} declaration.
2683 tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */
2687 static void print_token_value (FILE *, int, YYSTYPE);
2688 #define YYPRINT(F, N, L) print_token_value (F, N, L)
2694 When in doubt, it is usually safer to put prologue code before all
2695 Bison declarations, rather than after. For example, any definitions
2696 of feature test macros like @code{_GNU_SOURCE} or
2697 @code{_POSIX_C_SOURCE} should appear before all Bison declarations, as
2698 feature test macros can affect the behavior of Bison-generated
2699 @code{#include} directives.
2701 @node Prologue Alternatives
2702 @subsection Prologue Alternatives
2703 @cindex Prologue Alternatives
2706 @findex %code requires
2707 @findex %code provides
2710 The functionality of @var{Prologue} sections can often be subtle and
2712 As an alternative, Bison provides a %code directive with an explicit qualifier
2713 field, which identifies the purpose of the code and thus the location(s) where
2714 Bison should generate it.
2715 For C/C++, the qualifier can be omitted for the default location, or it can be
2716 one of @code{requires}, @code{provides}, @code{top}.
2717 @xref{Decl Summary,,%code}.
2719 Look again at the example of the previous section:
2730 tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */
2734 static void print_token_value (FILE *, int, YYSTYPE);
2735 #define YYPRINT(F, N, L) print_token_value (F, N, L)
2742 Notice that there are two @var{Prologue} sections here, but there's a subtle
2743 distinction between their functionality.
2744 For example, if you decide to override Bison's default definition for
2745 @code{YYLTYPE}, in which @var{Prologue} section should you write your new
2747 You should write it in the first since Bison will insert that code into the
2748 parser source code file @emph{before} the default @code{YYLTYPE} definition.
2749 In which @var{Prologue} section should you prototype an internal function,
2750 @code{trace_token}, that accepts @code{YYLTYPE} and @code{yytokentype} as
2752 You should prototype it in the second since Bison will insert that code
2753 @emph{after} the @code{YYLTYPE} and @code{yytokentype} definitions.
2755 This distinction in functionality between the two @var{Prologue} sections is
2756 established by the appearance of the @code{%union} between them.
2757 This behavior raises a few questions.
2758 First, why should the position of a @code{%union} affect definitions related to
2759 @code{YYLTYPE} and @code{yytokentype}?
2760 Second, what if there is no @code{%union}?
2761 In that case, the second kind of @var{Prologue} section is not available.
2762 This behavior is not intuitive.
2764 To avoid this subtle @code{%union} dependency, rewrite the example using a
2765 @code{%code top} and an unqualified @code{%code}.
2766 Let's go ahead and add the new @code{YYLTYPE} definition and the
2767 @code{trace_token} prototype at the same time:
2774 /* WARNING: The following code really belongs
2775 * in a `%code requires'; see below. */
2778 #define YYLTYPE YYLTYPE
2779 typedef struct YYLTYPE
2791 tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */
2795 static void print_token_value (FILE *, int, YYSTYPE);
2796 #define YYPRINT(F, N, L) print_token_value (F, N, L)
2797 static void trace_token (enum yytokentype token, YYLTYPE loc);
2804 In this way, @code{%code top} and the unqualified @code{%code} achieve the same
2805 functionality as the two kinds of @var{Prologue} sections, but it's always
2806 explicit which kind you intend.
2807 Moreover, both kinds are always available even in the absence of @code{%union}.
2809 The @code{%code top} block above logically contains two parts.
2810 The first two lines before the warning need to appear near the top of the
2811 parser source code file.
2812 The first line after the warning is required by @code{YYSTYPE} and thus also
2813 needs to appear in the parser source code file.
2814 However, if you've instructed Bison to generate a parser header file
2815 (@pxref{Decl Summary, ,%defines}), you probably want that line to appear before
2816 the @code{YYSTYPE} definition in that header file as well.
2817 The @code{YYLTYPE} definition should also appear in the parser header file to
2818 override the default @code{YYLTYPE} definition there.
2820 In other words, in the @code{%code top} block above, all but the first two
2821 lines are dependency code required by the @code{YYSTYPE} and @code{YYLTYPE}
2823 Thus, they belong in one or more @code{%code requires}:
2836 tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */
2840 #define YYLTYPE YYLTYPE
2841 typedef struct YYLTYPE
2852 static void print_token_value (FILE *, int, YYSTYPE);
2853 #define YYPRINT(F, N, L) print_token_value (F, N, L)
2854 static void trace_token (enum yytokentype token, YYLTYPE loc);
2861 Now Bison will insert @code{#include "ptypes.h"} and the new @code{YYLTYPE}
2862 definition before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE}
2863 definitions in both the parser source code file and the parser header file.
2864 (By the same reasoning, @code{%code requires} would also be the appropriate
2865 place to write your own definition for @code{YYSTYPE}.)
2867 When you are writing dependency code for @code{YYSTYPE} and @code{YYLTYPE}, you
2868 should prefer @code{%code requires} over @code{%code top} regardless of whether
2869 you instruct Bison to generate a parser header file.
2870 When you are writing code that you need Bison to insert only into the parser
2871 source code file and that has no special need to appear at the top of that
2872 file, you should prefer the unqualified @code{%code} over @code{%code top}.
2873 These practices will make the purpose of each block of your code explicit to
2874 Bison and to other developers reading your grammar file.
2875 Following these practices, we expect the unqualified @code{%code} and
2876 @code{%code requires} to be the most important of the four @var{Prologue}
2879 At some point while developing your parser, you might decide to provide
2880 @code{trace_token} to modules that are external to your parser.
2881 Thus, you might wish for Bison to insert the prototype into both the parser
2882 header file and the parser source code file.
2883 Since this function is not a dependency required by @code{YYSTYPE} or
2884 @code{YYLTYPE}, it doesn't make sense to move its prototype to a
2885 @code{%code requires}.
2886 More importantly, since it depends upon @code{YYLTYPE} and @code{yytokentype},
2887 @code{%code requires} is not sufficient.
2888 Instead, move its prototype from the unqualified @code{%code} to a
2889 @code{%code provides}:
2902 tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */
2906 #define YYLTYPE YYLTYPE
2907 typedef struct YYLTYPE
2918 void trace_token (enum yytokentype token, YYLTYPE loc);
2922 static void print_token_value (FILE *, int, YYSTYPE);
2923 #define YYPRINT(F, N, L) print_token_value (F, N, L)
2930 Bison will insert the @code{trace_token} prototype into both the parser header
2931 file and the parser source code file after the definitions for
2932 @code{yytokentype}, @code{YYLTYPE}, and @code{YYSTYPE}.
2934 The above examples are careful to write directives in an order that reflects
2935 the layout of the generated parser source code and header files:
2936 @code{%code top}, @code{%code requires}, @code{%code provides}, and then
2938 While your grammar files may generally be easier to read if you also follow
2939 this order, Bison does not require it.
2940 Instead, Bison lets you choose an organization that makes sense to you.
2942 You may declare any of these directives multiple times in the grammar file.
2943 In that case, Bison concatenates the contained code in declaration order.
2944 This is the only way in which the position of one of these directives within
2945 the grammar file affects its functionality.
2947 The result of the previous two properties is greater flexibility in how you may
2948 organize your grammar file.
2949 For example, you may organize semantic-type-related directives by semantic
2953 %code requires @{ #include "type1.h" @}
2954 %union @{ type1 field1; @}
2955 %destructor @{ type1_free ($$); @} <field1>
2956 %printer @{ type1_print ($$); @} <field1>
2958 %code requires @{ #include "type2.h" @}
2959 %union @{ type2 field2; @}
2960 %destructor @{ type2_free ($$); @} <field2>
2961 %printer @{ type2_print ($$); @} <field2>
2965 You could even place each of the above directive groups in the rules section of
2966 the grammar file next to the set of rules that uses the associated semantic
2968 (In the rules section, you must terminate each of those directives with a
2970 And you don't have to worry that some directive (like a @code{%union}) in the
2971 definitions section is going to adversely affect their functionality in some
2972 counter-intuitive manner just because it comes first.
2973 Such an organization is not possible using @var{Prologue} sections.
2975 This section has been concerned with explaining the advantages of the four
2976 @var{Prologue} alternatives over the original Yacc @var{Prologue}.
2977 However, in most cases when using these directives, you shouldn't need to
2978 think about all the low-level ordering issues discussed here.
2979 Instead, you should simply use these directives to label each block of your
2980 code according to its purpose and let Bison handle the ordering.
2981 @code{%code} is the most generic label.
2982 Move code to @code{%code requires}, @code{%code provides}, or @code{%code top}
2985 @node Bison Declarations
2986 @subsection The Bison Declarations Section
2987 @cindex Bison declarations (introduction)
2988 @cindex declarations, Bison (introduction)
2990 The @var{Bison declarations} section contains declarations that define
2991 terminal and nonterminal symbols, specify precedence, and so on.
2992 In some simple grammars you may not need any declarations.
2993 @xref{Declarations, ,Bison Declarations}.
2996 @subsection The Grammar Rules Section
2997 @cindex grammar rules section
2998 @cindex rules section for grammar
3000 The @dfn{grammar rules} section contains one or more Bison grammar
3001 rules, and nothing else. @xref{Rules, ,Syntax of Grammar Rules}.
3003 There must always be at least one grammar rule, and the first
3004 @samp{%%} (which precedes the grammar rules) may never be omitted even
3005 if it is the first thing in the file.
3008 @subsection The epilogue
3009 @cindex additional C code section
3011 @cindex C code, section for additional
3013 The @var{Epilogue} is copied verbatim to the end of the parser file, just as
3014 the @var{Prologue} is copied to the beginning. This is the most convenient
3015 place to put anything that you want to have in the parser file but which need
3016 not come before the definition of @code{yyparse}. For example, the
3017 definitions of @code{yylex} and @code{yyerror} often go here. Because
3018 C requires functions to be declared before being used, you often need
3019 to declare functions like @code{yylex} and @code{yyerror} in the Prologue,
3020 even if you define them in the Epilogue.
3021 @xref{Interface, ,Parser C-Language Interface}.
3023 If the last section is empty, you may omit the @samp{%%} that separates it
3024 from the grammar rules.
3026 The Bison parser itself contains many macros and identifiers whose names
3027 start with @samp{yy} or @samp{YY}, so it is a good idea to avoid using
3028 any such names (except those documented in this manual) in the epilogue
3029 of the grammar file.
3032 @section Symbols, Terminal and Nonterminal
3033 @cindex nonterminal symbol
3034 @cindex terminal symbol
3038 @dfn{Symbols} in Bison grammars represent the grammatical classifications
3041 A @dfn{terminal symbol} (also known as a @dfn{token type}) represents a
3042 class of syntactically equivalent tokens. You use the symbol in grammar
3043 rules to mean that a token in that class is allowed. The symbol is
3044 represented in the Bison parser by a numeric code, and the @code{yylex}
3045 function returns a token type code to indicate what kind of token has
3046 been read. You don't need to know what the code value is; you can use
3047 the symbol to stand for it.
3049 A @dfn{nonterminal symbol} stands for a class of syntactically
3050 equivalent groupings. The symbol name is used in writing grammar rules.
3051 By convention, it should be all lower case.
3053 Symbol names can contain letters, underscores, periods, dashes, and (not
3054 at the beginning) digits. Dashes in symbol names are a GNU
3055 extension, incompatible with @acronym{POSIX} Yacc. Terminal symbols
3056 that contain periods or dashes make little sense: since they are not
3057 valid symbols (in most programming languages) they are not exported as
3060 There are three ways of writing terminal symbols in the grammar:
3064 A @dfn{named token type} is written with an identifier, like an
3065 identifier in C@. By convention, it should be all upper case. Each
3066 such name must be defined with a Bison declaration such as
3067 @code{%token}. @xref{Token Decl, ,Token Type Names}.
3070 @cindex character token
3071 @cindex literal token
3072 @cindex single-character literal
3073 A @dfn{character token type} (or @dfn{literal character token}) is
3074 written in the grammar using the same syntax used in C for character
3075 constants; for example, @code{'+'} is a character token type. A
3076 character token type doesn't need to be declared unless you need to
3077 specify its semantic value data type (@pxref{Value Type, ,Data Types of
3078 Semantic Values}), associativity, or precedence (@pxref{Precedence,
3079 ,Operator Precedence}).
3081 By convention, a character token type is used only to represent a
3082 token that consists of that particular character. Thus, the token
3083 type @code{'+'} is used to represent the character @samp{+} as a
3084 token. Nothing enforces this convention, but if you depart from it,
3085 your program will confuse other readers.
3087 All the usual escape sequences used in character literals in C can be
3088 used in Bison as well, but you must not use the null character as a
3089 character literal because its numeric code, zero, signifies
3090 end-of-input (@pxref{Calling Convention, ,Calling Convention
3091 for @code{yylex}}). Also, unlike standard C, trigraphs have no
3092 special meaning in Bison character literals, nor is backslash-newline
3096 @cindex string token
3097 @cindex literal string token
3098 @cindex multicharacter literal
3099 A @dfn{literal string token} is written like a C string constant; for
3100 example, @code{"<="} is a literal string token. A literal string token
3101 doesn't need to be declared unless you need to specify its semantic
3102 value data type (@pxref{Value Type}), associativity, or precedence
3103 (@pxref{Precedence}).
3105 You can associate the literal string token with a symbolic name as an
3106 alias, using the @code{%token} declaration (@pxref{Token Decl, ,Token
3107 Declarations}). If you don't do that, the lexical analyzer has to
3108 retrieve the token number for the literal string token from the
3109 @code{yytname} table (@pxref{Calling Convention}).
3111 @strong{Warning}: literal string tokens do not work in Yacc.
3113 By convention, a literal string token is used only to represent a token
3114 that consists of that particular string. Thus, you should use the token
3115 type @code{"<="} to represent the string @samp{<=} as a token. Bison
3116 does not enforce this convention, but if you depart from it, people who
3117 read your program will be confused.
3119 All the escape sequences used in string literals in C can be used in
3120 Bison as well, except that you must not use a null character within a
3121 string literal. Also, unlike Standard C, trigraphs have no special
3122 meaning in Bison string literals, nor is backslash-newline allowed. A
3123 literal string token must contain two or more characters; for a token
3124 containing just one character, use a character token (see above).
3127 How you choose to write a terminal symbol has no effect on its
3128 grammatical meaning. That depends only on where it appears in rules and
3129 on when the parser function returns that symbol.
3131 The value returned by @code{yylex} is always one of the terminal
3132 symbols, except that a zero or negative value signifies end-of-input.
3133 Whichever way you write the token type in the grammar rules, you write
3134 it the same way in the definition of @code{yylex}. The numeric code
3135 for a character token type is simply the positive numeric code of the
3136 character, so @code{yylex} can use the identical value to generate the
3137 requisite code, though you may need to convert it to @code{unsigned
3138 char} to avoid sign-extension on hosts where @code{char} is signed.
3139 Each named token type becomes a C macro in
3140 the parser file, so @code{yylex} can use the name to stand for the code.
3141 (This is why periods don't make sense in terminal symbols.)
3142 @xref{Calling Convention, ,Calling Convention for @code{yylex}}.
3144 If @code{yylex} is defined in a separate file, you need to arrange for the
3145 token-type macro definitions to be available there. Use the @samp{-d}
3146 option when you run Bison, so that it will write these macro definitions
3147 into a separate header file @file{@var{name}.tab.h} which you can include
3148 in the other source files that need it. @xref{Invocation, ,Invoking Bison}.
3150 If you want to write a grammar that is portable to any Standard C
3151 host, you must use only nonnull character tokens taken from the basic
3152 execution character set of Standard C@. This set consists of the ten
3153 digits, the 52 lower- and upper-case English letters, and the
3154 characters in the following C-language string:
3157 "\a\b\t\n\v\f\r !\"#%&'()*+,-./:;<=>?[\\]^_@{|@}~"
3160 The @code{yylex} function and Bison must use a consistent character set
3161 and encoding for character tokens. For example, if you run Bison in an
3162 @acronym{ASCII} environment, but then compile and run the resulting
3163 program in an environment that uses an incompatible character set like
3164 @acronym{EBCDIC}, the resulting program may not work because the tables
3165 generated by Bison will assume @acronym{ASCII} numeric values for
3166 character tokens. It is standard practice for software distributions to
3167 contain C source files that were generated by Bison in an
3168 @acronym{ASCII} environment, so installers on platforms that are
3169 incompatible with @acronym{ASCII} must rebuild those files before
3172 The symbol @code{error} is a terminal symbol reserved for error recovery
3173 (@pxref{Error Recovery}); you shouldn't use it for any other purpose.
3174 In particular, @code{yylex} should never return this value. The default
3175 value of the error token is 256, unless you explicitly assigned 256 to
3176 one of your tokens with a @code{%token} declaration.
3179 @section Syntax of Grammar Rules
3181 @cindex grammar rule syntax
3182 @cindex syntax of grammar rules
3184 A Bison grammar rule has the following general form:
3188 @var{result}: @var{components}@dots{}
3194 where @var{result} is the nonterminal symbol that this rule describes,
3195 and @var{components} are various terminal and nonterminal symbols that
3196 are put together by this rule (@pxref{Symbols}).
3208 says that two groupings of type @code{exp}, with a @samp{+} token in between,
3209 can be combined into a larger grouping of type @code{exp}.
3211 White space in rules is significant only to separate symbols. You can add
3212 extra white space as you wish.
3214 Scattered among the components can be @var{actions} that determine
3215 the semantics of the rule. An action looks like this:
3218 @{@var{C statements}@}
3223 This is an example of @dfn{braced code}, that is, C code surrounded by
3224 braces, much like a compound statement in C@. Braced code can contain
3225 any sequence of C tokens, so long as its braces are balanced. Bison
3226 does not check the braced code for correctness directly; it merely
3227 copies the code to the output file, where the C compiler can check it.
3229 Within braced code, the balanced-brace count is not affected by braces
3230 within comments, string literals, or character constants, but it is
3231 affected by the C digraphs @samp{<%} and @samp{%>} that represent
3232 braces. At the top level braced code must be terminated by @samp{@}}
3233 and not by a digraph. Bison does not look for trigraphs, so if braced
3234 code uses trigraphs you should ensure that they do not affect the
3235 nesting of braces or the boundaries of comments, string literals, or
3236 character constants.
3238 Usually there is only one action and it follows the components.
3242 Multiple rules for the same @var{result} can be written separately or can
3243 be joined with the vertical-bar character @samp{|} as follows:
3247 @var{result}: @var{rule1-components}@dots{}
3248 | @var{rule2-components}@dots{}
3255 They are still considered distinct rules even when joined in this way.
3257 If @var{components} in a rule is empty, it means that @var{result} can
3258 match the empty string. For example, here is how to define a
3259 comma-separated sequence of zero or more @code{exp} groupings:
3276 It is customary to write a comment @samp{/* empty */} in each rule
3280 @section Recursive Rules
3281 @cindex recursive rule
3283 A rule is called @dfn{recursive} when its @var{result} nonterminal
3284 appears also on its right hand side. Nearly all Bison grammars need to
3285 use recursion, because that is the only way to define a sequence of any
3286 number of a particular thing. Consider this recursive definition of a
3287 comma-separated sequence of one or more expressions:
3297 @cindex left recursion
3298 @cindex right recursion
3300 Since the recursive use of @code{expseq1} is the leftmost symbol in the
3301 right hand side, we call this @dfn{left recursion}. By contrast, here
3302 the same construct is defined using @dfn{right recursion}:
3313 Any kind of sequence can be defined using either left recursion or right
3314 recursion, but you should always use left recursion, because it can
3315 parse a sequence of any number of elements with bounded stack space.
3316 Right recursion uses up space on the Bison stack in proportion to the
3317 number of elements in the sequence, because all the elements must be
3318 shifted onto the stack before the rule can be applied even once.
3319 @xref{Algorithm, ,The Bison Parser Algorithm}, for further explanation
3322 @cindex mutual recursion
3323 @dfn{Indirect} or @dfn{mutual} recursion occurs when the result of the
3324 rule does not appear directly on its right hand side, but does appear
3325 in rules for other nonterminals which do appear on its right hand
3333 | primary '+' primary
3345 defines two mutually-recursive nonterminals, since each refers to the
3349 @section Defining Language Semantics
3350 @cindex defining language semantics
3351 @cindex language semantics, defining
3353 The grammar rules for a language determine only the syntax. The semantics
3354 are determined by the semantic values associated with various tokens and
3355 groupings, and by the actions taken when various groupings are recognized.
3357 For example, the calculator calculates properly because the value
3358 associated with each expression is the proper number; it adds properly
3359 because the action for the grouping @w{@samp{@var{x} + @var{y}}} is to add
3360 the numbers associated with @var{x} and @var{y}.
3363 * Value Type:: Specifying one data type for all semantic values.
3364 * Multiple Types:: Specifying several alternative data types.
3365 * Actions:: An action is the semantic definition of a grammar rule.
3366 * Action Types:: Specifying data types for actions to operate on.
3367 * Mid-Rule Actions:: Most actions go at the end of a rule.
3368 This says when, why and how to use the exceptional
3369 action in the middle of a rule.
3373 @subsection Data Types of Semantic Values
3374 @cindex semantic value type
3375 @cindex value type, semantic
3376 @cindex data types of semantic values
3377 @cindex default data type
3379 In a simple program it may be sufficient to use the same data type for
3380 the semantic values of all language constructs. This was true in the
3381 @acronym{RPN} and infix calculator examples (@pxref{RPN Calc, ,Reverse Polish
3382 Notation Calculator}).
3384 Bison normally uses the type @code{int} for semantic values if your
3385 program uses the same data type for all language constructs. To
3386 specify some other type, define @code{YYSTYPE} as a macro, like this:
3389 #define YYSTYPE double
3393 @code{YYSTYPE}'s replacement list should be a type name
3394 that does not contain parentheses or square brackets.
3395 This macro definition must go in the prologue of the grammar file
3396 (@pxref{Grammar Outline, ,Outline of a Bison Grammar}).
3398 @node Multiple Types
3399 @subsection More Than One Value Type
3401 In most programs, you will need different data types for different kinds
3402 of tokens and groupings. For example, a numeric constant may need type
3403 @code{int} or @code{long int}, while a string constant needs type
3404 @code{char *}, and an identifier might need a pointer to an entry in the
3407 To use more than one data type for semantic values in one parser, Bison
3408 requires you to do two things:
3412 Specify the entire collection of possible data types, either by using the
3413 @code{%union} Bison declaration (@pxref{Union Decl, ,The Collection of
3414 Value Types}), or by using a @code{typedef} or a @code{#define} to
3415 define @code{YYSTYPE} to be a union type whose member names are
3419 Choose one of those types for each symbol (terminal or nonterminal) for
3420 which semantic values are used. This is done for tokens with the
3421 @code{%token} Bison declaration (@pxref{Token Decl, ,Token Type Names})
3422 and for groupings with the @code{%type} Bison declaration (@pxref{Type
3423 Decl, ,Nonterminal Symbols}).
3432 An action accompanies a syntactic rule and contains C code to be executed
3433 each time an instance of that rule is recognized. The task of most actions
3434 is to compute a semantic value for the grouping built by the rule from the
3435 semantic values associated with tokens or smaller groupings.
3437 An action consists of braced code containing C statements, and can be
3438 placed at any position in the rule;
3439 it is executed at that position. Most rules have just one action at the
3440 end of the rule, following all the components. Actions in the middle of
3441 a rule are tricky and used only for special purposes (@pxref{Mid-Rule
3442 Actions, ,Actions in Mid-Rule}).
3444 The C code in an action can refer to the semantic values of the components
3445 matched by the rule with the construct @code{$@var{n}}, which stands for
3446 the value of the @var{n}th component. The semantic value for the grouping
3447 being constructed is @code{$$}. Bison translates both of these
3448 constructs into expressions of the appropriate type when it copies the
3449 actions into the parser file. @code{$$} is translated to a modifiable
3450 lvalue, so it can be assigned to.
3452 Here is a typical example:
3463 This rule constructs an @code{exp} from two smaller @code{exp} groupings
3464 connected by a plus-sign token. In the action, @code{$1} and @code{$3}
3465 refer to the semantic values of the two component @code{exp} groupings,
3466 which are the first and third symbols on the right hand side of the rule.
3467 The sum is stored into @code{$$} so that it becomes the semantic value of
3468 the addition-expression just recognized by the rule. If there were a
3469 useful semantic value associated with the @samp{+} token, it could be
3470 referred to as @code{$2}.
3472 Note that the vertical-bar character @samp{|} is really a rule
3473 separator, and actions are attached to a single rule. This is a
3474 difference with tools like Flex, for which @samp{|} stands for either
3475 ``or'', or ``the same action as that of the next rule''. In the
3476 following example, the action is triggered only when @samp{b} is found:
3480 a-or-b: 'a'|'b' @{ a_or_b_found = 1; @};
3484 @cindex default action
3485 If you don't specify an action for a rule, Bison supplies a default:
3486 @w{@code{$$ = $1}.} Thus, the value of the first symbol in the rule
3487 becomes the value of the whole rule. Of course, the default action is
3488 valid only if the two data types match. There is no meaningful default
3489 action for an empty rule; every empty rule must have an explicit action
3490 unless the rule's value does not matter.
3492 @code{$@var{n}} with @var{n} zero or negative is allowed for reference
3493 to tokens and groupings on the stack @emph{before} those that match the
3494 current rule. This is a very risky practice, and to use it reliably
3495 you must be certain of the context in which the rule is applied. Here
3496 is a case in which you can use this reliably:
3500 foo: expr bar '+' expr @{ @dots{} @}
3501 | expr bar '-' expr @{ @dots{} @}
3507 @{ previous_expr = $0; @}
3512 As long as @code{bar} is used only in the fashion shown here, @code{$0}
3513 always refers to the @code{expr} which precedes @code{bar} in the
3514 definition of @code{foo}.
3517 It is also possible to access the semantic value of the lookahead token, if
3518 any, from a semantic action.
3519 This semantic value is stored in @code{yylval}.
3520 @xref{Action Features, ,Special Features for Use in Actions}.
3523 @subsection Data Types of Values in Actions
3524 @cindex action data types
3525 @cindex data types in actions
3527 If you have chosen a single data type for semantic values, the @code{$$}
3528 and @code{$@var{n}} constructs always have that data type.
3530 If you have used @code{%union} to specify a variety of data types, then you
3531 must declare a choice among these types for each terminal or nonterminal
3532 symbol that can have a semantic value. Then each time you use @code{$$} or
3533 @code{$@var{n}}, its data type is determined by which symbol it refers to
3534 in the rule. In this example,
3545 @code{$1} and @code{$3} refer to instances of @code{exp}, so they all
3546 have the data type declared for the nonterminal symbol @code{exp}. If
3547 @code{$2} were used, it would have the data type declared for the
3548 terminal symbol @code{'+'}, whatever that might be.
3550 Alternatively, you can specify the data type when you refer to the value,
3551 by inserting @samp{<@var{type}>} after the @samp{$} at the beginning of the
3552 reference. For example, if you have defined types as shown here:
3564 then you can write @code{$<itype>1} to refer to the first subunit of the
3565 rule as an integer, or @code{$<dtype>1} to refer to it as a double.
3567 @node Mid-Rule Actions
3568 @subsection Actions in Mid-Rule
3569 @cindex actions in mid-rule
3570 @cindex mid-rule actions
3572 Occasionally it is useful to put an action in the middle of a rule.
3573 These actions are written just like usual end-of-rule actions, but they
3574 are executed before the parser even recognizes the following components.
3576 A mid-rule action may refer to the components preceding it using
3577 @code{$@var{n}}, but it may not refer to subsequent components because
3578 it is run before they are parsed.
3580 The mid-rule action itself counts as one of the components of the rule.
3581 This makes a difference when there is another action later in the same rule
3582 (and usually there is another at the end): you have to count the actions
3583 along with the symbols when working out which number @var{n} to use in
3586 The mid-rule action can also have a semantic value. The action can set
3587 its value with an assignment to @code{$$}, and actions later in the rule
3588 can refer to the value using @code{$@var{n}}. Since there is no symbol
3589 to name the action, there is no way to declare a data type for the value
3590 in advance, so you must use the @samp{$<@dots{}>@var{n}} construct to
3591 specify a data type each time you refer to this value.
3593 There is no way to set the value of the entire rule with a mid-rule
3594 action, because assignments to @code{$$} do not have that effect. The
3595 only way to set the value for the entire rule is with an ordinary action
3596 at the end of the rule.
3598 Here is an example from a hypothetical compiler, handling a @code{let}
3599 statement that looks like @samp{let (@var{variable}) @var{statement}} and
3600 serves to create a variable named @var{variable} temporarily for the
3601 duration of @var{statement}. To parse this construct, we must put
3602 @var{variable} into the symbol table while @var{statement} is parsed, then
3603 remove it afterward. Here is how it is done:
3607 stmt: LET '(' var ')'
3608 @{ $<context>$ = push_context ();
3609 declare_variable ($3); @}
3611 pop_context ($<context>5); @}
3616 As soon as @samp{let (@var{variable})} has been recognized, the first
3617 action is run. It saves a copy of the current semantic context (the
3618 list of accessible variables) as its semantic value, using alternative
3619 @code{context} in the data-type union. Then it calls
3620 @code{declare_variable} to add the new variable to that list. Once the
3621 first action is finished, the embedded statement @code{stmt} can be
3622 parsed. Note that the mid-rule action is component number 5, so the
3623 @samp{stmt} is component number 6.
3625 After the embedded statement is parsed, its semantic value becomes the
3626 value of the entire @code{let}-statement. Then the semantic value from the
3627 earlier action is used to restore the prior list of variables. This
3628 removes the temporary @code{let}-variable from the list so that it won't
3629 appear to exist while the rest of the program is parsed.
3632 @cindex discarded symbols, mid-rule actions
3633 @cindex error recovery, mid-rule actions
3634 In the above example, if the parser initiates error recovery (@pxref{Error
3635 Recovery}) while parsing the tokens in the embedded statement @code{stmt},
3636 it might discard the previous semantic context @code{$<context>5} without
3638 Thus, @code{$<context>5} needs a destructor (@pxref{Destructor Decl, , Freeing
3639 Discarded Symbols}).
3640 However, Bison currently provides no means to declare a destructor specific to
3641 a particular mid-rule action's semantic value.
3643 One solution is to bury the mid-rule action inside a nonterminal symbol and to
3644 declare a destructor for that symbol:
3649 %destructor @{ pop_context ($$); @} let
3655 pop_context ($1); @}
3658 let: LET '(' var ')'
3659 @{ $$ = push_context ();
3660 declare_variable ($3); @}
3667 Note that the action is now at the end of its rule.
3668 Any mid-rule action can be converted to an end-of-rule action in this way, and
3669 this is what Bison actually does to implement mid-rule actions.
3671 Taking action before a rule is completely recognized often leads to
3672 conflicts since the parser must commit to a parse in order to execute the
3673 action. For example, the following two rules, without mid-rule actions,
3674 can coexist in a working parser because the parser can shift the open-brace
3675 token and look at what follows before deciding whether there is a
3680 compound: '@{' declarations statements '@}'
3681 | '@{' statements '@}'
3687 But when we add a mid-rule action as follows, the rules become nonfunctional:
3691 compound: @{ prepare_for_local_variables (); @}
3692 '@{' declarations statements '@}'
3695 | '@{' statements '@}'
3701 Now the parser is forced to decide whether to run the mid-rule action
3702 when it has read no farther than the open-brace. In other words, it
3703 must commit to using one rule or the other, without sufficient
3704 information to do it correctly. (The open-brace token is what is called
3705 the @dfn{lookahead} token at this time, since the parser is still
3706 deciding what to do about it. @xref{Lookahead, ,Lookahead Tokens}.)
3708 You might think that you could correct the problem by putting identical
3709 actions into the two rules, like this:
3713 compound: @{ prepare_for_local_variables (); @}
3714 '@{' declarations statements '@}'
3715 | @{ prepare_for_local_variables (); @}
3716 '@{' statements '@}'
3722 But this does not help, because Bison does not realize that the two actions
3723 are identical. (Bison never tries to understand the C code in an action.)
3725 If the grammar is such that a declaration can be distinguished from a
3726 statement by the first token (which is true in C), then one solution which
3727 does work is to put the action after the open-brace, like this:
3731 compound: '@{' @{ prepare_for_local_variables (); @}
3732 declarations statements '@}'
3733 | '@{' statements '@}'
3739 Now the first token of the following declaration or statement,
3740 which would in any case tell Bison which rule to use, can still do so.
3742 Another solution is to bury the action inside a nonterminal symbol which
3743 serves as a subroutine:
3747 subroutine: /* empty */
3748 @{ prepare_for_local_variables (); @}
3754 compound: subroutine
3755 '@{' declarations statements '@}'
3757 '@{' statements '@}'
3763 Now Bison can execute the action in the rule for @code{subroutine} without
3764 deciding which rule for @code{compound} it will eventually use.
3767 @section Tracking Locations
3769 @cindex textual location
3770 @cindex location, textual
3772 Though grammar rules and semantic actions are enough to write a fully
3773 functional parser, it can be useful to process some additional information,
3774 especially symbol locations.
3776 The way locations are handled is defined by providing a data type, and
3777 actions to take when rules are matched.
3780 * Location Type:: Specifying a data type for locations.
3781 * Actions and Locations:: Using locations in actions.
3782 * Location Default Action:: Defining a general way to compute locations.
3786 @subsection Data Type of Locations
3787 @cindex data type of locations
3788 @cindex default location type
3790 Defining a data type for locations is much simpler than for semantic values,
3791 since all tokens and groupings always use the same type.
3793 You can specify the type of locations by defining a macro called
3794 @code{YYLTYPE}, just as you can specify the semantic value type by
3795 defining a @code{YYSTYPE} macro (@pxref{Value Type}).
3796 When @code{YYLTYPE} is not defined, Bison uses a default structure type with
3800 typedef struct YYLTYPE
3809 When @code{YYLTYPE} is not defined, at the beginning of the parsing, Bison
3810 initializes all these fields to 1 for @code{yylloc}. To initialize
3811 @code{yylloc} with a custom location type (or to chose a different
3812 initialization), use the @code{%initial-action} directive. @xref{Initial
3813 Action Decl, , Performing Actions before Parsing}.
3815 @node Actions and Locations
3816 @subsection Actions and Locations
3817 @cindex location actions
3818 @cindex actions, location
3822 Actions are not only useful for defining language semantics, but also for
3823 describing the behavior of the output parser with locations.
3825 The most obvious way for building locations of syntactic groupings is very
3826 similar to the way semantic values are computed. In a given rule, several
3827 constructs can be used to access the locations of the elements being matched.
3828 The location of the @var{n}th component of the right hand side is
3829 @code{@@@var{n}}, while the location of the left hand side grouping is
3832 Here is a basic example using the default data type for locations:
3839 @@$.first_column = @@1.first_column;
3840 @@$.first_line = @@1.first_line;
3841 @@$.last_column = @@3.last_column;
3842 @@$.last_line = @@3.last_line;
3849 "Division by zero, l%d,c%d-l%d,c%d",
3850 @@3.first_line, @@3.first_column,
3851 @@3.last_line, @@3.last_column);
3857 As for semantic values, there is a default action for locations that is
3858 run each time a rule is matched. It sets the beginning of @code{@@$} to the
3859 beginning of the first symbol, and the end of @code{@@$} to the end of the
3862 With this default action, the location tracking can be fully automatic. The
3863 example above simply rewrites this way:
3876 "Division by zero, l%d,c%d-l%d,c%d",
3877 @@3.first_line, @@3.first_column,
3878 @@3.last_line, @@3.last_column);
3885 It is also possible to access the location of the lookahead token, if any,
3886 from a semantic action.
3887 This location is stored in @code{yylloc}.
3888 @xref{Action Features, ,Special Features for Use in Actions}.
3890 @node Location Default Action
3891 @subsection Default Action for Locations
3892 @vindex YYLLOC_DEFAULT
3893 @cindex @acronym{GLR} parsers and @code{YYLLOC_DEFAULT}
3895 Actually, actions are not the best place to compute locations. Since
3896 locations are much more general than semantic values, there is room in
3897 the output parser to redefine the default action to take for each
3898 rule. The @code{YYLLOC_DEFAULT} macro is invoked each time a rule is
3899 matched, before the associated action is run. It is also invoked
3900 while processing a syntax error, to compute the error's location.
3901 Before reporting an unresolvable syntactic ambiguity, a @acronym{GLR}
3902 parser invokes @code{YYLLOC_DEFAULT} recursively to compute the location
3905 Most of the time, this macro is general enough to suppress location
3906 dedicated code from semantic actions.
3908 The @code{YYLLOC_DEFAULT} macro takes three parameters. The first one is
3909 the location of the grouping (the result of the computation). When a
3910 rule is matched, the second parameter identifies locations of
3911 all right hand side elements of the rule being matched, and the third
3912 parameter is the size of the rule's right hand side.
3913 When a @acronym{GLR} parser reports an ambiguity, which of multiple candidate
3914 right hand sides it passes to @code{YYLLOC_DEFAULT} is undefined.
3915 When processing a syntax error, the second parameter identifies locations
3916 of the symbols that were discarded during error processing, and the third
3917 parameter is the number of discarded symbols.
3919 By default, @code{YYLLOC_DEFAULT} is defined this way:
3923 # define YYLLOC_DEFAULT(Current, Rhs, N) \
3927 (Current).first_line = YYRHSLOC(Rhs, 1).first_line; \
3928 (Current).first_column = YYRHSLOC(Rhs, 1).first_column; \
3929 (Current).last_line = YYRHSLOC(Rhs, N).last_line; \
3930 (Current).last_column = YYRHSLOC(Rhs, N).last_column; \
3934 (Current).first_line = (Current).last_line = \
3935 YYRHSLOC(Rhs, 0).last_line; \
3936 (Current).first_column = (Current).last_column = \
3937 YYRHSLOC(Rhs, 0).last_column; \
3943 where @code{YYRHSLOC (rhs, k)} is the location of the @var{k}th symbol
3944 in @var{rhs} when @var{k} is positive, and the location of the symbol
3945 just before the reduction when @var{k} and @var{n} are both zero.
3947 When defining @code{YYLLOC_DEFAULT}, you should consider that:
3951 All arguments are free of side-effects. However, only the first one (the
3952 result) should be modified by @code{YYLLOC_DEFAULT}.
3955 For consistency with semantic actions, valid indexes within the
3956 right hand side range from 1 to @var{n}. When @var{n} is zero, only 0 is a
3957 valid index, and it refers to the symbol just before the reduction.
3958 During error processing @var{n} is always positive.
3961 Your macro should parenthesize its arguments, if need be, since the
3962 actual arguments may not be surrounded by parentheses. Also, your
3963 macro should expand to something that can be used as a single
3964 statement when it is followed by a semicolon.
3968 @section Bison Declarations
3969 @cindex declarations, Bison
3970 @cindex Bison declarations
3972 The @dfn{Bison declarations} section of a Bison grammar defines the symbols
3973 used in formulating the grammar and the data types of semantic values.
3976 All token type names (but not single-character literal tokens such as
3977 @code{'+'} and @code{'*'}) must be declared. Nonterminal symbols must be
3978 declared if you need to specify which data type to use for the semantic
3979 value (@pxref{Multiple Types, ,More Than One Value Type}).
3981 The first rule in the file also specifies the start symbol, by default.
3982 If you want some other symbol to be the start symbol, you must declare
3983 it explicitly (@pxref{Language and Grammar, ,Languages and Context-Free
3987 * Require Decl:: Requiring a Bison version.
3988 * Token Decl:: Declaring terminal symbols.
3989 * Precedence Decl:: Declaring terminals with precedence and associativity.
3990 * Union Decl:: Declaring the set of all semantic value types.
3991 * Type Decl:: Declaring the choice of type for a nonterminal symbol.
3992 * Initial Action Decl:: Code run before parsing starts.
3993 * Destructor Decl:: Declaring how symbols are freed.
3994 * Expect Decl:: Suppressing warnings about parsing conflicts.
3995 * Start Decl:: Specifying the start symbol.
3996 * Pure Decl:: Requesting a reentrant parser.
3997 * Push Decl:: Requesting a push parser.
3998 * Decl Summary:: Table of all Bison declarations.
4002 @subsection Require a Version of Bison
4003 @cindex version requirement
4004 @cindex requiring a version of Bison
4007 You may require the minimum version of Bison to process the grammar. If
4008 the requirement is not met, @command{bison} exits with an error (exit
4012 %require "@var{version}"
4016 @subsection Token Type Names
4017 @cindex declaring token type names
4018 @cindex token type names, declaring
4019 @cindex declaring literal string tokens
4022 The basic way to declare a token type name (terminal symbol) is as follows:
4028 Bison will convert this into a @code{#define} directive in
4029 the parser, so that the function @code{yylex} (if it is in this file)
4030 can use the name @var{name} to stand for this token type's code.
4032 Alternatively, you can use @code{%left}, @code{%right},
4033 @code{%precedence}, or
4034 @code{%nonassoc} instead of @code{%token}, if you wish to specify
4035 associativity and precedence. @xref{Precedence Decl, ,Operator
4038 You can explicitly specify the numeric code for a token type by appending
4039 a nonnegative decimal or hexadecimal integer value in the field immediately
4040 following the token name:
4044 %token XNUM 0x12d // a GNU extension
4048 It is generally best, however, to let Bison choose the numeric codes for
4049 all token types. Bison will automatically select codes that don't conflict
4050 with each other or with normal characters.
4052 In the event that the stack type is a union, you must augment the
4053 @code{%token} or other token declaration to include the data type
4054 alternative delimited by angle-brackets (@pxref{Multiple Types, ,More
4055 Than One Value Type}).
4061 %union @{ /* define stack type */
4065 %token <val> NUM /* define token NUM and its type */
4069 You can associate a literal string token with a token type name by
4070 writing the literal string at the end of a @code{%token}
4071 declaration which declares the name. For example:
4078 For example, a grammar for the C language might specify these names with
4079 equivalent literal string tokens:
4082 %token <operator> OR "||"
4083 %token <operator> LE 134 "<="
4088 Once you equate the literal string and the token name, you can use them
4089 interchangeably in further declarations or the grammar rules. The
4090 @code{yylex} function can use the token name or the literal string to
4091 obtain the token type code number (@pxref{Calling Convention}).
4092 Syntax error messages passed to @code{yyerror} from the parser will reference
4093 the literal string instead of the token name.
4095 The token numbered as 0 corresponds to end of file; the following line
4096 allows for nicer error messages referring to ``end of file'' instead
4100 %token END 0 "end of file"
4103 @node Precedence Decl
4104 @subsection Operator Precedence
4105 @cindex precedence declarations
4106 @cindex declaring operator precedence
4107 @cindex operator precedence, declaring
4109 Use the @code{%left}, @code{%right}, @code{%nonassoc}, or
4110 @code{%precedence} declaration to
4111 declare a token and specify its precedence and associativity, all at
4112 once. These are called @dfn{precedence declarations}.
4113 @xref{Precedence, ,Operator Precedence}, for general information on
4114 operator precedence.
4116 The syntax of a precedence declaration is nearly the same as that of
4117 @code{%token}: either
4120 %left @var{symbols}@dots{}
4127 %left <@var{type}> @var{symbols}@dots{}
4130 And indeed any of these declarations serves the purposes of @code{%token}.
4131 But in addition, they specify the associativity and relative precedence for
4132 all the @var{symbols}:
4136 The associativity of an operator @var{op} determines how repeated uses
4137 of the operator nest: whether @samp{@var{x} @var{op} @var{y} @var{op}
4138 @var{z}} is parsed by grouping @var{x} with @var{y} first or by
4139 grouping @var{y} with @var{z} first. @code{%left} specifies
4140 left-associativity (grouping @var{x} with @var{y} first) and
4141 @code{%right} specifies right-associativity (grouping @var{y} with
4142 @var{z} first). @code{%nonassoc} specifies no associativity, which
4143 means that @samp{@var{x} @var{op} @var{y} @var{op} @var{z}} is
4144 considered a syntax error.
4146 @code{%precedence} gives only precedence to the @var{symbols}, and
4147 defines no associativity at all. Use this to define precedence only,
4148 and leave any potential conflict due to associativity enabled.
4151 The precedence of an operator determines how it nests with other operators.
4152 All the tokens declared in a single precedence declaration have equal
4153 precedence and nest together according to their associativity.
4154 When two tokens declared in different precedence declarations associate,
4155 the one declared later has the higher precedence and is grouped first.
4158 For backward compatibility, there is a confusing difference between the
4159 argument lists of @code{%token} and precedence declarations.
4160 Only a @code{%token} can associate a literal string with a token type name.
4161 A precedence declaration always interprets a literal string as a reference to a
4166 %left OR "<=" // Does not declare an alias.
4167 %left OR 134 "<=" 135 // Declares 134 for OR and 135 for "<=".
4171 @subsection The Collection of Value Types
4172 @cindex declaring value types
4173 @cindex value types, declaring
4176 The @code{%union} declaration specifies the entire collection of
4177 possible data types for semantic values. The keyword @code{%union} is
4178 followed by braced code containing the same thing that goes inside a
4193 This says that the two alternative types are @code{double} and @code{symrec
4194 *}. They are given names @code{val} and @code{tptr}; these names are used
4195 in the @code{%token} and @code{%type} declarations to pick one of the types
4196 for a terminal or nonterminal symbol (@pxref{Type Decl, ,Nonterminal Symbols}).
4198 As an extension to @acronym{POSIX}, a tag is allowed after the
4199 @code{union}. For example:
4211 specifies the union tag @code{value}, so the corresponding C type is
4212 @code{union value}. If you do not specify a tag, it defaults to
4215 As another extension to @acronym{POSIX}, you may specify multiple
4216 @code{%union} declarations; their contents are concatenated. However,
4217 only the first @code{%union} declaration can specify a tag.
4219 Note that, unlike making a @code{union} declaration in C, you need not write
4220 a semicolon after the closing brace.
4222 Instead of @code{%union}, you can define and use your own union type
4223 @code{YYSTYPE} if your grammar contains at least one
4224 @samp{<@var{type}>} tag. For example, you can put the following into
4225 a header file @file{parser.h}:
4233 typedef union YYSTYPE YYSTYPE;
4238 and then your grammar can use the following
4239 instead of @code{%union}:
4252 @subsection Nonterminal Symbols
4253 @cindex declaring value types, nonterminals
4254 @cindex value types, nonterminals, declaring
4258 When you use @code{%union} to specify multiple value types, you must
4259 declare the value type of each nonterminal symbol for which values are
4260 used. This is done with a @code{%type} declaration, like this:
4263 %type <@var{type}> @var{nonterminal}@dots{}
4267 Here @var{nonterminal} is the name of a nonterminal symbol, and
4268 @var{type} is the name given in the @code{%union} to the alternative
4269 that you want (@pxref{Union Decl, ,The Collection of Value Types}). You
4270 can give any number of nonterminal symbols in the same @code{%type}
4271 declaration, if they have the same value type. Use spaces to separate
4274 You can also declare the value type of a terminal symbol. To do this,
4275 use the same @code{<@var{type}>} construction in a declaration for the
4276 terminal symbol. All kinds of token declarations allow
4277 @code{<@var{type}>}.
4279 @node Initial Action Decl
4280 @subsection Performing Actions before Parsing
4281 @findex %initial-action
4283 Sometimes your parser needs to perform some initializations before
4284 parsing. The @code{%initial-action} directive allows for such arbitrary
4287 @deffn {Directive} %initial-action @{ @var{code} @}
4288 @findex %initial-action
4289 Declare that the braced @var{code} must be invoked before parsing each time
4290 @code{yyparse} is called. The @var{code} may use @code{$$} and
4291 @code{@@$} --- initial value and location of the lookahead --- and the
4292 @code{%parse-param}.
4295 For instance, if your locations use a file name, you may use
4298 %parse-param @{ char const *file_name @};
4301 @@$.initialize (file_name);
4306 @node Destructor Decl
4307 @subsection Freeing Discarded Symbols
4308 @cindex freeing discarded symbols
4312 During error recovery (@pxref{Error Recovery}), symbols already pushed
4313 on the stack and tokens coming from the rest of the file are discarded
4314 until the parser falls on its feet. If the parser runs out of memory,
4315 or if it returns via @code{YYABORT} or @code{YYACCEPT}, all the
4316 symbols on the stack must be discarded. Even if the parser succeeds, it
4317 must discard the start symbol.
4319 When discarded symbols convey heap based information, this memory is
4320 lost. While this behavior can be tolerable for batch parsers, such as
4321 in traditional compilers, it is unacceptable for programs like shells or
4322 protocol implementations that may parse and execute indefinitely.
4324 The @code{%destructor} directive defines code that is called when a
4325 symbol is automatically discarded.
4327 @deffn {Directive} %destructor @{ @var{code} @} @var{symbols}
4329 Invoke the braced @var{code} whenever the parser discards one of the
4331 Within @var{code}, @code{$$} designates the semantic value associated
4332 with the discarded symbol, and @code{@@$} designates its location.
4333 The additional parser parameters are also available (@pxref{Parser Function, ,
4334 The Parser Function @code{yyparse}}).
4336 When a symbol is listed among @var{symbols}, its @code{%destructor} is called a
4337 per-symbol @code{%destructor}.
4338 You may also define a per-type @code{%destructor} by listing a semantic type
4339 tag among @var{symbols}.
4340 In that case, the parser will invoke this @var{code} whenever it discards any
4341 grammar symbol that has that semantic type tag unless that symbol has its own
4342 per-symbol @code{%destructor}.
4344 Finally, you can define two different kinds of default @code{%destructor}s.
4345 (These default forms are experimental.
4346 More user feedback will help to determine whether they should become permanent
4348 You can place each of @code{<*>} and @code{<>} in the @var{symbols} list of
4349 exactly one @code{%destructor} declaration in your grammar file.
4350 The parser will invoke the @var{code} associated with one of these whenever it
4351 discards any user-defined grammar symbol that has no per-symbol and no per-type
4353 The parser uses the @var{code} for @code{<*>} in the case of such a grammar
4354 symbol for which you have formally declared a semantic type tag (@code{%type}
4355 counts as such a declaration, but @code{$<tag>$} does not).
4356 The parser uses the @var{code} for @code{<>} in the case of such a grammar
4357 symbol that has no declared semantic type tag.
4364 %union @{ char *string; @}
4365 %token <string> STRING1
4366 %token <string> STRING2
4367 %type <string> string1
4368 %type <string> string2
4369 %union @{ char character; @}
4370 %token <character> CHR
4371 %type <character> chr
4374 %destructor @{ @} <character>
4375 %destructor @{ free ($$); @} <*>
4376 %destructor @{ free ($$); printf ("%d", @@$.first_line); @} STRING1 string1
4377 %destructor @{ printf ("Discarding tagless symbol.\n"); @} <>
4381 guarantees that, when the parser discards any user-defined symbol that has a
4382 semantic type tag other than @code{<character>}, it passes its semantic value
4383 to @code{free} by default.
4384 However, when the parser discards a @code{STRING1} or a @code{string1}, it also
4385 prints its line number to @code{stdout}.
4386 It performs only the second @code{%destructor} in this case, so it invokes
4387 @code{free} only once.
4388 Finally, the parser merely prints a message whenever it discards any symbol,
4389 such as @code{TAGLESS}, that has no semantic type tag.
4391 A Bison-generated parser invokes the default @code{%destructor}s only for
4392 user-defined as opposed to Bison-defined symbols.
4393 For example, the parser will not invoke either kind of default
4394 @code{%destructor} for the special Bison-defined symbols @code{$accept},
4395 @code{$undefined}, or @code{$end} (@pxref{Table of Symbols, ,Bison Symbols}),
4396 none of which you can reference in your grammar.
4397 It also will not invoke either for the @code{error} token (@pxref{Table of
4398 Symbols, ,error}), which is always defined by Bison regardless of whether you
4399 reference it in your grammar.
4400 However, it may invoke one of them for the end token (token 0) if you
4401 redefine it from @code{$end} to, for example, @code{END}:
4407 @cindex actions in mid-rule
4408 @cindex mid-rule actions
4409 Finally, Bison will never invoke a @code{%destructor} for an unreferenced
4410 mid-rule semantic value (@pxref{Mid-Rule Actions,,Actions in Mid-Rule}).
4411 That is, Bison does not consider a mid-rule to have a semantic value if you do
4412 not reference @code{$$} in the mid-rule's action or @code{$@var{n}} (where
4413 @var{n} is the RHS symbol position of the mid-rule) in any later action in that
4415 However, if you do reference either, the Bison-generated parser will invoke the
4416 @code{<>} @code{%destructor} whenever it discards the mid-rule symbol.
4420 In the future, it may be possible to redefine the @code{error} token as a
4421 nonterminal that captures the discarded symbols.
4422 In that case, the parser will invoke the default destructor for it as well.
4427 @cindex discarded symbols
4428 @dfn{Discarded symbols} are the following:
4432 stacked symbols popped during the first phase of error recovery,
4434 incoming terminals during the second phase of error recovery,
4436 the current lookahead and the entire stack (except the current
4437 right-hand side symbols) when the parser returns immediately, and
4439 the start symbol, when the parser succeeds.
4442 The parser can @dfn{return immediately} because of an explicit call to
4443 @code{YYABORT} or @code{YYACCEPT}, or failed error recovery, or memory
4446 Right-hand side symbols of a rule that explicitly triggers a syntax
4447 error via @code{YYERROR} are not discarded automatically. As a rule
4448 of thumb, destructors are invoked only when user actions cannot manage
4452 @subsection Suppressing Conflict Warnings
4453 @cindex suppressing conflict warnings
4454 @cindex preventing warnings about conflicts
4455 @cindex warnings, preventing
4456 @cindex conflicts, suppressing warnings of
4460 Bison normally warns if there are any conflicts in the grammar
4461 (@pxref{Shift/Reduce, ,Shift/Reduce Conflicts}), but most real grammars
4462 have harmless shift/reduce conflicts which are resolved in a predictable
4463 way and would be difficult to eliminate. It is desirable to suppress
4464 the warning about these conflicts unless the number of conflicts
4465 changes. You can do this with the @code{%expect} declaration.
4467 The declaration looks like this:
4473 Here @var{n} is a decimal integer. The declaration says there should
4474 be @var{n} shift/reduce conflicts and no reduce/reduce conflicts.
4475 Bison reports an error if the number of shift/reduce conflicts differs
4476 from @var{n}, or if there are any reduce/reduce conflicts.
4478 For deterministic parsers, reduce/reduce conflicts are more
4479 serious, and should be eliminated entirely. Bison will always report
4480 reduce/reduce conflicts for these parsers. With @acronym{GLR}
4481 parsers, however, both kinds of conflicts are routine; otherwise,
4482 there would be no need to use @acronym{GLR} parsing. Therefore, it is
4483 also possible to specify an expected number of reduce/reduce conflicts
4484 in @acronym{GLR} parsers, using the declaration:
4490 In general, using @code{%expect} involves these steps:
4494 Compile your grammar without @code{%expect}. Use the @samp{-v} option
4495 to get a verbose list of where the conflicts occur. Bison will also
4496 print the number of conflicts.
4499 Check each of the conflicts to make sure that Bison's default
4500 resolution is what you really want. If not, rewrite the grammar and
4501 go back to the beginning.
4504 Add an @code{%expect} declaration, copying the number @var{n} from the
4505 number which Bison printed. With @acronym{GLR} parsers, add an
4506 @code{%expect-rr} declaration as well.
4509 Now Bison will warn you if you introduce an unexpected conflict, but
4510 will keep silent otherwise.
4513 @subsection The Start-Symbol
4514 @cindex declaring the start symbol
4515 @cindex start symbol, declaring
4516 @cindex default start symbol
4519 Bison assumes by default that the start symbol for the grammar is the first
4520 nonterminal specified in the grammar specification section. The programmer
4521 may override this restriction with the @code{%start} declaration as follows:
4528 @subsection A Pure (Reentrant) Parser
4529 @cindex reentrant parser
4531 @findex %define api.pure
4533 A @dfn{reentrant} program is one which does not alter in the course of
4534 execution; in other words, it consists entirely of @dfn{pure} (read-only)
4535 code. Reentrancy is important whenever asynchronous execution is possible;
4536 for example, a nonreentrant program may not be safe to call from a signal
4537 handler. In systems with multiple threads of control, a nonreentrant
4538 program must be called only within interlocks.
4540 Normally, Bison generates a parser which is not reentrant. This is
4541 suitable for most uses, and it permits compatibility with Yacc. (The
4542 standard Yacc interfaces are inherently nonreentrant, because they use
4543 statically allocated variables for communication with @code{yylex},
4544 including @code{yylval} and @code{yylloc}.)
4546 Alternatively, you can generate a pure, reentrant parser. The Bison
4547 declaration @samp{%define api.pure} says that you want the parser to be
4548 reentrant. It looks like this:
4554 The result is that the communication variables @code{yylval} and
4555 @code{yylloc} become local variables in @code{yyparse}, and a different
4556 calling convention is used for the lexical analyzer function
4557 @code{yylex}. @xref{Pure Calling, ,Calling Conventions for Pure
4558 Parsers}, for the details of this. The variable @code{yynerrs}
4559 becomes local in @code{yyparse} in pull mode but it becomes a member
4560 of yypstate in push mode. (@pxref{Error Reporting, ,The Error
4561 Reporting Function @code{yyerror}}). The convention for calling
4562 @code{yyparse} itself is unchanged.
4564 Whether the parser is pure has nothing to do with the grammar rules.
4565 You can generate either a pure parser or a nonreentrant parser from any
4569 @subsection A Push Parser
4572 @findex %define api.push-pull
4574 (The current push parsing interface is experimental and may evolve.
4575 More user feedback will help to stabilize it.)
4577 A pull parser is called once and it takes control until all its input
4578 is completely parsed. A push parser, on the other hand, is called
4579 each time a new token is made available.
4581 A push parser is typically useful when the parser is part of a
4582 main event loop in the client's application. This is typically
4583 a requirement of a GUI, when the main event loop needs to be triggered
4584 within a certain time period.
4586 Normally, Bison generates a pull parser.
4587 The following Bison declaration says that you want the parser to be a push
4588 parser (@pxref{Decl Summary,,%define api.push-pull}):
4591 %define api.push-pull push
4594 In almost all cases, you want to ensure that your push parser is also
4595 a pure parser (@pxref{Pure Decl, ,A Pure (Reentrant) Parser}). The only
4596 time you should create an impure push parser is to have backwards
4597 compatibility with the impure Yacc pull mode interface. Unless you know
4598 what you are doing, your declarations should look like this:
4602 %define api.push-pull push
4605 There is a major notable functional difference between the pure push parser
4606 and the impure push parser. It is acceptable for a pure push parser to have
4607 many parser instances, of the same type of parser, in memory at the same time.
4608 An impure push parser should only use one parser at a time.
4610 When a push parser is selected, Bison will generate some new symbols in
4611 the generated parser. @code{yypstate} is a structure that the generated
4612 parser uses to store the parser's state. @code{yypstate_new} is the
4613 function that will create a new parser instance. @code{yypstate_delete}
4614 will free the resources associated with the corresponding parser instance.
4615 Finally, @code{yypush_parse} is the function that should be called whenever a
4616 token is available to provide the parser. A trivial example
4617 of using a pure push parser would look like this:
4621 yypstate *ps = yypstate_new ();
4623 status = yypush_parse (ps, yylex (), NULL);
4624 @} while (status == YYPUSH_MORE);
4625 yypstate_delete (ps);
4628 If the user decided to use an impure push parser, a few things about
4629 the generated parser will change. The @code{yychar} variable becomes
4630 a global variable instead of a variable in the @code{yypush_parse} function.
4631 For this reason, the signature of the @code{yypush_parse} function is
4632 changed to remove the token as a parameter. A nonreentrant push parser
4633 example would thus look like this:
4638 yypstate *ps = yypstate_new ();
4641 status = yypush_parse (ps);
4642 @} while (status == YYPUSH_MORE);
4643 yypstate_delete (ps);
4646 That's it. Notice the next token is put into the global variable @code{yychar}
4647 for use by the next invocation of the @code{yypush_parse} function.
4649 Bison also supports both the push parser interface along with the pull parser
4650 interface in the same generated parser. In order to get this functionality,
4651 you should replace the @samp{%define api.push-pull push} declaration with the
4652 @samp{%define api.push-pull both} declaration. Doing this will create all of
4653 the symbols mentioned earlier along with the two extra symbols, @code{yyparse}
4654 and @code{yypull_parse}. @code{yyparse} can be used exactly as it normally
4655 would be used. However, the user should note that it is implemented in the
4656 generated parser by calling @code{yypull_parse}.
4657 This makes the @code{yyparse} function that is generated with the
4658 @samp{%define api.push-pull both} declaration slower than the normal
4659 @code{yyparse} function. If the user
4660 calls the @code{yypull_parse} function it will parse the rest of the input
4661 stream. It is possible to @code{yypush_parse} tokens to select a subgrammar
4662 and then @code{yypull_parse} the rest of the input stream. If you would like
4663 to switch back and forth between between parsing styles, you would have to
4664 write your own @code{yypull_parse} function that knows when to quit looking
4665 for input. An example of using the @code{yypull_parse} function would look
4669 yypstate *ps = yypstate_new ();
4670 yypull_parse (ps); /* Will call the lexer */
4671 yypstate_delete (ps);
4674 Adding the @samp{%define api.pure} declaration does exactly the same thing to
4675 the generated parser with @samp{%define api.push-pull both} as it did for
4676 @samp{%define api.push-pull push}.
4679 @subsection Bison Declaration Summary
4680 @cindex Bison declaration summary
4681 @cindex declaration summary
4682 @cindex summary, Bison declaration
4684 Here is a summary of the declarations used to define a grammar:
4686 @deffn {Directive} %union
4687 Declare the collection of data types that semantic values may have
4688 (@pxref{Union Decl, ,The Collection of Value Types}).
4691 @deffn {Directive} %token
4692 Declare a terminal symbol (token type name) with no precedence
4693 or associativity specified (@pxref{Token Decl, ,Token Type Names}).
4696 @deffn {Directive} %right
4697 Declare a terminal symbol (token type name) that is right-associative
4698 (@pxref{Precedence Decl, ,Operator Precedence}).
4701 @deffn {Directive} %left
4702 Declare a terminal symbol (token type name) that is left-associative
4703 (@pxref{Precedence Decl, ,Operator Precedence}).
4706 @deffn {Directive} %nonassoc
4707 Declare a terminal symbol (token type name) that is nonassociative
4708 (@pxref{Precedence Decl, ,Operator Precedence}).
4709 Using it in a way that would be associative is a syntax error.
4713 @deffn {Directive} %default-prec
4714 Assign a precedence to rules lacking an explicit @code{%prec} modifier
4715 (@pxref{Contextual Precedence, ,Context-Dependent Precedence}).
4719 @deffn {Directive} %type
4720 Declare the type of semantic values for a nonterminal symbol
4721 (@pxref{Type Decl, ,Nonterminal Symbols}).
4724 @deffn {Directive} %start
4725 Specify the grammar's start symbol (@pxref{Start Decl, ,The
4729 @deffn {Directive} %expect
4730 Declare the expected number of shift-reduce conflicts
4731 (@pxref{Expect Decl, ,Suppressing Conflict Warnings}).
4737 In order to change the behavior of @command{bison}, use the following
4740 @deffn {Directive} %code @{@var{code}@}
4742 This is the unqualified form of the @code{%code} directive.
4743 It inserts @var{code} verbatim at a language-dependent default location in the
4744 output@footnote{The default location is actually skeleton-dependent;
4745 writers of non-standard skeletons however should choose the default location
4746 consistently with the behavior of the standard Bison skeletons.}.
4749 For C/C++, the default location is the parser source code
4750 file after the usual contents of the parser header file.
4751 Thus, @code{%code} replaces the traditional Yacc prologue,
4752 @code{%@{@var{code}%@}}, for most purposes.
4753 For a detailed discussion, see @ref{Prologue Alternatives}.
4755 For Java, the default location is inside the parser class.
4758 @deffn {Directive} %code @var{qualifier} @{@var{code}@}
4759 This is the qualified form of the @code{%code} directive.
4760 If you need to specify location-sensitive verbatim @var{code} that does not
4761 belong at the default location selected by the unqualified @code{%code} form,
4762 use this form instead.
4764 @var{qualifier} identifies the purpose of @var{code} and thus the location(s)
4765 where Bison should generate it.
4766 Not all @var{qualifier}s are accepted for all target languages.
4767 Unaccepted @var{qualifier}s produce an error.
4768 Some of the accepted @var{qualifier}s are:
4772 @findex %code requires
4775 @item Language(s): C, C++
4777 @item Purpose: This is the best place to write dependency code required for
4778 @code{YYSTYPE} and @code{YYLTYPE}.
4779 In other words, it's the best place to define types referenced in @code{%union}
4780 directives, and it's the best place to override Bison's default @code{YYSTYPE}
4781 and @code{YYLTYPE} definitions.
4783 @item Location(s): The parser header file and the parser source code file
4784 before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE} definitions.
4788 @findex %code provides
4791 @item Language(s): C, C++
4793 @item Purpose: This is the best place to write additional definitions and
4794 declarations that should be provided to other modules.
4796 @item Location(s): The parser header file and the parser source code file after
4797 the Bison-generated @code{YYSTYPE}, @code{YYLTYPE}, and token definitions.
4804 @item Language(s): C, C++
4806 @item Purpose: The unqualified @code{%code} or @code{%code requires} should
4807 usually be more appropriate than @code{%code top}.
4808 However, occasionally it is necessary to insert code much nearer the top of the
4809 parser source code file.
4819 @item Location(s): Near the top of the parser source code file.
4823 @findex %code imports
4826 @item Language(s): Java
4828 @item Purpose: This is the best place to write Java import directives.
4830 @item Location(s): The parser Java file after any Java package directive and
4831 before any class definitions.
4836 For a detailed discussion of how to use @code{%code} in place of the
4837 traditional Yacc prologue for C/C++, see @ref{Prologue Alternatives}.
4840 @deffn {Directive} %debug
4841 Instrument the output parser for traces. Obsoleted by @samp{%define
4843 @xref{Tracing, ,Tracing Your Parser}.
4846 @deffn {Directive} %define @var{variable}
4847 @deffnx {Directive} %define @var{variable} @var{value}
4848 @deffnx {Directive} %define @var{variable} "@var{value}"
4849 Define a variable to adjust Bison's behavior.
4851 It is an error if a @var{variable} is defined by @code{%define} multiple
4852 times, but see @ref{Bison Options,,-D @var{name}[=@var{value}]}.
4854 @var{value} must be placed in quotation marks if it contains any
4855 character other than a letter, underscore, period, dash, or non-initial
4858 Omitting @code{"@var{value}"} entirely is always equivalent to specifying
4861 Some @var{variable}s take Boolean values.
4862 In this case, Bison will complain if the variable definition does not meet one
4863 of the following four conditions:
4866 @item @code{@var{value}} is @code{true}
4868 @item @code{@var{value}} is omitted (or @code{""} is specified).
4869 This is equivalent to @code{true}.
4871 @item @code{@var{value}} is @code{false}.
4873 @item @var{variable} is never defined.
4874 In this case, Bison selects a default value.
4877 What @var{variable}s are accepted, as well as their meanings and default
4878 values, depend on the selected target language and/or the parser
4879 skeleton (@pxref{Decl Summary,,%language}, @pxref{Decl
4880 Summary,,%skeleton}).
4881 Unaccepted @var{variable}s produce an error.
4882 Some of the accepted @var{variable}s are:
4885 @c ================================================== api.namespace
4887 @findex %define api.namespace
4889 @item Languages(s): C++
4891 @item Purpose: Specifies the namespace for the parser class.
4892 For example, if you specify:
4895 %define api.namespace "foo::bar"
4898 Bison uses @code{foo::bar} verbatim in references such as:
4901 foo::bar::parser::semantic_type
4904 However, to open a namespace, Bison removes any leading @code{::} and then
4905 splits on any remaining occurrences:
4908 namespace foo @{ namespace bar @{
4914 @item Accepted Values:
4915 Any absolute or relative C++ namespace reference without a trailing
4916 @code{"::"}. For example, @code{"foo"} or @code{"::foo::bar"}.
4918 @item Default Value:
4919 The value specified by @code{%name-prefix}, which defaults to @code{yy}.
4920 This usage of @code{%name-prefix} is for backward compatibility and can
4921 be confusing since @code{%name-prefix} also specifies the textual prefix
4922 for the lexical analyzer function. Thus, if you specify
4923 @code{%name-prefix}, it is best to also specify @samp{%define
4924 api.namespace} so that @code{%name-prefix} @emph{only} affects the
4925 lexical analyzer function. For example, if you specify:
4928 %define api.namespace "foo"
4929 %name-prefix "bar::"
4932 The parser namespace is @code{foo} and @code{yylex} is referenced as
4939 @c ================================================== api.pure
4941 @findex %define api.pure
4944 @item Language(s): C
4946 @item Purpose: Request a pure (reentrant) parser program.
4947 @xref{Pure Decl, ,A Pure (Reentrant) Parser}.
4949 @item Accepted Values: Boolean
4951 @item Default Value: @code{false}
4957 @c ================================================== api.push-pull
4959 @findex %define api.push-pull
4962 @item Language(s): C (deterministic parsers only)
4964 @item Purpose: Requests a pull parser, a push parser, or both.
4965 @xref{Push Decl, ,A Push Parser}.
4966 (The current push parsing interface is experimental and may evolve.
4967 More user feedback will help to stabilize it.)
4969 @item Accepted Values: @code{pull}, @code{push}, @code{both}
4971 @item Default Value: @code{pull}
4977 @c ================================================== api.tokens.prefix
4978 @item api.tokens.prefix
4979 @findex %define api.tokens.prefix
4982 @item Languages(s): all
4985 Add a prefix to the token names when generating their definition in the
4986 target language. For instance
4989 %token FILE for ERROR
4990 %define api.tokens.prefix "TOK_"
4992 start: FILE for ERROR;
4996 generates the definition of the symbols @code{TOK_FILE}, @code{TOK_for},
4997 and @code{TOK_ERROR} in the generated source files. In particular, the
4998 scanner must use these prefixed token names, while the grammar itself
4999 may still use the short names (as in the sample rule given above). The
5000 generated informational files (@file{*.output}, @file{*.xml},
5001 @file{*.dot}) are not modified by this prefix. See @ref{Calc++ Parser}
5002 and @ref{Calc++ Scanner}, for a complete example.
5004 @item Accepted Values:
5005 Any string. Should be a valid identifier prefix in the target language,
5006 in other words, it should typically be an identifier itself (sequence of
5007 letters, underscores, and ---not at the beginning--- digits).
5009 @item Default Value:
5012 @c api.tokens.prefix
5015 @c ================================================== lr.default-reductions
5017 @item lr.default-reductions
5018 @cindex default reductions
5019 @findex %define lr.default-reductions
5020 @cindex delayed syntax errors
5021 @cindex syntax errors delayed
5024 @item Language(s): all
5026 @item Purpose: Specifies the kind of states that are permitted to
5027 contain default reductions.
5028 That is, in such a state, Bison declares the reduction with the largest
5029 lookahead set to be the default reduction and then removes that
5031 The advantages of default reductions are discussed below.
5032 The disadvantage is that, when the generated parser encounters a
5033 syntactically unacceptable token, the parser might then perform
5034 unnecessary default reductions before it can detect the syntax error.
5036 (This feature is experimental.
5037 More user feedback will help to stabilize it.)
5039 @item Accepted Values:
5042 For @acronym{LALR} and @acronym{IELR} parsers (@pxref{Decl
5043 Summary,,lr.type}) by default, all states are permitted to contain
5045 The advantage is that parser table sizes can be significantly reduced.
5046 The reason Bison does not by default attempt to address the disadvantage
5047 of delayed syntax error detection is that this disadvantage is already
5048 inherent in @acronym{LALR} and @acronym{IELR} parser tables.
5049 That is, unlike in a canonical @acronym{LR} state, the lookahead sets of
5050 reductions in an @acronym{LALR} or @acronym{IELR} state can contain
5051 tokens that are syntactically incorrect for some left contexts.
5053 @item @code{consistent}.
5054 @cindex consistent states
5055 A consistent state is a state that has only one possible action.
5056 If that action is a reduction, then the parser does not need to request
5057 a lookahead token from the scanner before performing that action.
5058 However, the parser only recognizes the ability to ignore the lookahead
5059 token when such a reduction is encoded as a default reduction.
5060 Thus, if default reductions are permitted in and only in consistent
5061 states, then a canonical @acronym{LR} parser reports a syntax error as
5062 soon as it @emph{needs} the syntactically unacceptable token from the
5065 @item @code{accepting}.
5066 @cindex accepting state
5067 By default, the only default reduction permitted in a canonical
5068 @acronym{LR} parser is the accept action in the accepting state, which
5069 the parser reaches only after reading all tokens from the input.
5070 Thus, the default canonical @acronym{LR} parser reports a syntax error
5071 as soon as it @emph{reaches} the syntactically unacceptable token
5072 without performing any extra reductions.
5075 @item Default Value:
5077 @item @code{accepting} if @code{lr.type} is @code{canonical-lr}.
5078 @item @code{all} otherwise.
5082 @c ============================================ lr.keep-unreachable-states
5084 @item lr.keep-unreachable-states
5085 @findex %define lr.keep-unreachable-states
5088 @item Language(s): all
5090 @item Purpose: Requests that Bison allow unreachable parser states to remain in
5092 Bison considers a state to be unreachable if there exists no sequence of
5093 transitions from the start state to that state.
5094 A state can become unreachable during conflict resolution if Bison disables a
5095 shift action leading to it from a predecessor state.
5096 Keeping unreachable states is sometimes useful for analysis purposes, but they
5097 are useless in the generated parser.
5099 @item Accepted Values: Boolean
5101 @item Default Value: @code{false}
5107 @item Unreachable states may contain conflicts and may use rules not used in
5109 Thus, keeping unreachable states may induce warnings that are irrelevant to
5110 your parser's behavior, and it may eliminate warnings that are relevant.
5111 Of course, the change in warnings may actually be relevant to a parser table
5112 analysis that wants to keep unreachable states, so this behavior will likely
5113 remain in future Bison releases.
5115 @item While Bison is able to remove unreachable states, it is not guaranteed to
5116 remove other kinds of useless states.
5117 Specifically, when Bison disables reduce actions during conflict resolution,
5118 some goto actions may become useless, and thus some additional states may
5120 If Bison were to compute which goto actions were useless and then disable those
5121 actions, it could identify such states as unreachable and then remove those
5123 However, Bison does not compute which goto actions are useless.
5126 @c lr.keep-unreachable-states
5128 @c ================================================== lr.type
5131 @findex %define lr.type
5132 @cindex @acronym{LALR}
5133 @cindex @acronym{IELR}
5134 @cindex @acronym{LR}
5137 @item Language(s): all
5139 @item Purpose: Specifies the type of parser tables within the
5140 @acronym{LR}(1) family.
5141 (This feature is experimental.
5142 More user feedback will help to stabilize it.)
5144 @item Accepted Values:
5147 While Bison generates @acronym{LALR} parser tables by default for
5148 historical reasons, @acronym{IELR} or canonical @acronym{LR} is almost
5149 always preferable for deterministic parsers.
5150 The trouble is that @acronym{LALR} parser tables can suffer from
5151 mysterious conflicts and thus may not accept the full set of sentences
5152 that @acronym{IELR} and canonical @acronym{LR} accept.
5153 @xref{Mystery Conflicts}, for details.
5154 However, there are at least two scenarios where @acronym{LALR} may be
5157 @cindex @acronym{GLR} with @acronym{LALR}
5158 @item When employing @acronym{GLR} parsers (@pxref{GLR Parsers}), if you
5159 do not resolve any conflicts statically (for example, with @code{%left}
5160 or @code{%prec}), then the parser explores all potential parses of any
5162 In this case, the use of @acronym{LALR} parser tables is guaranteed not
5163 to alter the language accepted by the parser.
5164 @acronym{LALR} parser tables are the smallest parser tables Bison can
5165 currently generate, so they may be preferable.
5167 @item Occasionally during development, an especially malformed grammar
5168 with a major recurring flaw may severely impede the @acronym{IELR} or
5169 canonical @acronym{LR} parser table generation algorithm.
5170 @acronym{LALR} can be a quick way to generate parser tables in order to
5171 investigate such problems while ignoring the more subtle differences
5172 from @acronym{IELR} and canonical @acronym{LR}.
5176 @acronym{IELR} is a minimal @acronym{LR} algorithm.
5177 That is, given any grammar (@acronym{LR} or non-@acronym{LR}),
5178 @acronym{IELR} and canonical @acronym{LR} always accept exactly the same
5180 However, as for @acronym{LALR}, the number of parser states is often an
5181 order of magnitude less for @acronym{IELR} than for canonical
5183 More importantly, because canonical @acronym{LR}'s extra parser states
5184 may contain duplicate conflicts in the case of non-@acronym{LR}
5185 grammars, the number of conflicts for @acronym{IELR} is often an order
5186 of magnitude less as well.
5187 This can significantly reduce the complexity of developing of a grammar.
5189 @item @code{canonical-lr}.
5190 @cindex delayed syntax errors
5191 @cindex syntax errors delayed
5192 The only advantage of canonical @acronym{LR} over @acronym{IELR} is
5193 that, for every left context of every canonical @acronym{LR} state, the
5194 set of tokens accepted by that state is the exact set of tokens that is
5195 syntactically acceptable in that left context.
5196 Thus, the only difference in parsing behavior is that the canonical
5197 @acronym{LR} parser can report a syntax error as soon as possible
5198 without performing any unnecessary reductions.
5199 @xref{Decl Summary,,lr.default-reductions}, for further details.
5200 Even when canonical @acronym{LR} behavior is ultimately desired,
5201 @acronym{IELR}'s elimination of duplicate conflicts should still
5202 facilitate the development of a grammar.
5205 @item Default Value: @code{lalr}
5209 @c ================================================== namespace
5211 @findex %define namespace
5212 Obsoleted by @code{api.namespace}
5216 @c ================================================== parse.assert
5218 @findex %define parse.assert
5221 @item Languages(s): C++
5223 @item Purpose: Issue runtime assertions to catch invalid uses.
5224 In C++, when variants are used, symbols must be constructed and
5225 destroyed properly. This option checks these constraints.
5227 @item Accepted Values: Boolean
5229 @item Default Value: @code{false}
5234 @c ================================================== parse.error
5236 @findex %define parse.error
5241 Control the kind of error messages passed to the error reporting
5242 function. @xref{Error Reporting, ,The Error Reporting Function
5244 @item Accepted Values:
5247 Error messages passed to @code{yyerror} are simply @w{@code{"syntax
5249 @item @code{verbose}
5250 Error messages report the unexpected token, and possibly the expected
5254 @item Default Value:
5260 @c ================================================== parse.trace
5262 @findex %define parse.trace
5265 @item Languages(s): C, C++
5267 @item Purpose: Require parser instrumentation for tracing.
5268 In C/C++, define the macro @code{YYDEBUG} to 1 in the parser file if it
5269 is not already defined, so that the debugging facilities are compiled.
5270 @xref{Tracing, ,Tracing Your Parser}.
5272 @item Accepted Values: Boolean
5274 @item Default Value: @code{false}
5280 @c ---------------------------------------------------------- %define
5282 @deffn {Directive} %defines
5283 Write a header file containing macro definitions for the token type
5284 names defined in the grammar as well as a few other declarations.
5285 If the parser output file is named @file{@var{name}.c} then this file
5286 is named @file{@var{name}.h}.
5288 For C parsers, the output header declares @code{YYSTYPE} unless
5289 @code{YYSTYPE} is already defined as a macro or you have used a
5290 @code{<@var{type}>} tag without using @code{%union}.
5291 Therefore, if you are using a @code{%union}
5292 (@pxref{Multiple Types, ,More Than One Value Type}) with components that
5293 require other definitions, or if you have defined a @code{YYSTYPE} macro
5295 (@pxref{Value Type, ,Data Types of Semantic Values}), you need to
5296 arrange for these definitions to be propagated to all modules, e.g., by
5297 putting them in a prerequisite header that is included both by your
5298 parser and by any other module that needs @code{YYSTYPE}.
5300 Unless your parser is pure, the output header declares @code{yylval}
5301 as an external variable. @xref{Pure Decl, ,A Pure (Reentrant)
5304 If you have also used locations, the output header declares
5305 @code{YYLTYPE} and @code{yylloc} using a protocol similar to that of
5306 the @code{YYSTYPE} macro and @code{yylval}. @xref{Locations, ,Tracking
5309 This output file is normally essential if you wish to put the definition
5310 of @code{yylex} in a separate source file, because @code{yylex}
5311 typically needs to be able to refer to the above-mentioned declarations
5312 and to the token type codes. @xref{Token Values, ,Semantic Values of
5315 @findex %code requires
5316 @findex %code provides
5317 If you have declared @code{%code requires} or @code{%code provides}, the output
5318 header also contains their code.
5319 @xref{Decl Summary, ,%code}.
5322 @deffn {Directive} %defines @var{defines-file}
5323 Same as above, but save in the file @var{defines-file}.
5326 @deffn {Directive} %destructor
5327 Specify how the parser should reclaim the memory associated to
5328 discarded symbols. @xref{Destructor Decl, , Freeing Discarded Symbols}.
5331 @deffn {Directive} %file-prefix "@var{prefix}"
5332 Specify a prefix to use for all Bison output file names. The names are
5333 chosen as if the input file were named @file{@var{prefix}.y}.
5336 @deffn {Directive} %language "@var{language}"
5337 Specify the programming language for the generated parser. Currently
5338 supported languages include C, C++, and Java.
5339 @var{language} is case-insensitive.
5341 This directive is experimental and its effect may be modified in future
5345 @deffn {Directive} %locations
5346 Generate the code processing the locations (@pxref{Action Features,
5347 ,Special Features for Use in Actions}). This mode is enabled as soon as
5348 the grammar uses the special @samp{@@@var{n}} tokens, but if your
5349 grammar does not use it, using @samp{%locations} allows for more
5350 accurate syntax error messages.
5353 @deffn {Directive} %name-prefix "@var{prefix}"
5354 Rename the external symbols used in the parser so that they start with
5355 @var{prefix} instead of @samp{yy}. The precise list of symbols renamed
5357 is @code{yyparse}, @code{yylex}, @code{yyerror}, @code{yynerrs},
5358 @code{yylval}, @code{yychar}, @code{yydebug}, and
5359 (if locations are used) @code{yylloc}. If you use a push parser,
5360 @code{yypush_parse}, @code{yypull_parse}, @code{yypstate},
5361 @code{yypstate_new} and @code{yypstate_delete} will
5362 also be renamed. For example, if you use @samp{%name-prefix "c_"}, the
5363 names become @code{c_parse}, @code{c_lex}, and so on.
5364 For C++ parsers, see the @samp{%define api.namespace} documentation in this
5366 @xref{Multiple Parsers, ,Multiple Parsers in the Same Program}.
5370 @deffn {Directive} %no-default-prec
5371 Do not assign a precedence to rules lacking an explicit @code{%prec}
5372 modifier (@pxref{Contextual Precedence, ,Context-Dependent
5377 @deffn {Directive} %no-lines
5378 Don't generate any @code{#line} preprocessor commands in the parser
5379 file. Ordinarily Bison writes these commands in the parser file so that
5380 the C compiler and debuggers will associate errors and object code with
5381 your source file (the grammar file). This directive causes them to
5382 associate errors with the parser file, treating it an independent source
5383 file in its own right.
5386 @deffn {Directive} %output "@var{file}"
5387 Specify @var{file} for the parser file.
5390 @deffn {Directive} %pure-parser
5391 Deprecated version of @samp{%define api.pure} (@pxref{Decl Summary, ,%define}),
5392 for which Bison is more careful to warn about unreasonable usage.
5395 @deffn {Directive} %require "@var{version}"
5396 Require version @var{version} or higher of Bison. @xref{Require Decl, ,
5397 Require a Version of Bison}.
5400 @deffn {Directive} %skeleton "@var{file}"
5401 Specify the skeleton to use.
5403 @c You probably don't need this option unless you are developing Bison.
5404 @c You should use @code{%language} if you want to specify the skeleton for a
5405 @c different language, because it is clearer and because it will always choose the
5406 @c correct skeleton for non-deterministic or push parsers.
5408 If @var{file} does not contain a @code{/}, @var{file} is the name of a skeleton
5409 file in the Bison installation directory.
5410 If it does, @var{file} is an absolute file name or a file name relative to the
5411 directory of the grammar file.
5412 This is similar to how most shells resolve commands.
5415 @deffn {Directive} %token-table
5416 Generate an array of token names in the parser file. The name of the
5417 array is @code{yytname}; @code{yytname[@var{i}]} is the name of the
5418 token whose internal Bison token code number is @var{i}. The first
5419 three elements of @code{yytname} correspond to the predefined tokens
5421 @code{"error"}, and @code{"$undefined"}; after these come the symbols
5422 defined in the grammar file.
5424 The name in the table includes all the characters needed to represent
5425 the token in Bison. For single-character literals and literal
5426 strings, this includes the surrounding quoting characters and any
5427 escape sequences. For example, the Bison single-character literal
5428 @code{'+'} corresponds to a three-character name, represented in C as
5429 @code{"'+'"}; and the Bison two-character literal string @code{"\\/"}
5430 corresponds to a five-character name, represented in C as
5433 When you specify @code{%token-table}, Bison also generates macro
5434 definitions for macros @code{YYNTOKENS}, @code{YYNNTS}, and
5435 @code{YYNRULES}, and @code{YYNSTATES}:
5439 The highest token number, plus one.
5441 The number of nonterminal symbols.
5443 The number of grammar rules,
5445 The number of parser states (@pxref{Parser States}).
5449 @deffn {Directive} %verbose
5450 Write an extra output file containing verbose descriptions of the
5451 parser states and what is done for each type of lookahead token in
5452 that state. @xref{Understanding, , Understanding Your Parser}, for more
5456 @deffn {Directive} %yacc
5457 Pretend the option @option{--yacc} was given, i.e., imitate Yacc,
5458 including its naming conventions. @xref{Bison Options}, for more.
5462 @node Multiple Parsers
5463 @section Multiple Parsers in the Same Program
5465 Most programs that use Bison parse only one language and therefore contain
5466 only one Bison parser. But what if you want to parse more than one
5467 language with the same program? Then you need to avoid a name conflict
5468 between different definitions of @code{yyparse}, @code{yylval}, and so on.
5470 The easy way to do this is to use the option @samp{-p @var{prefix}}
5471 (@pxref{Invocation, ,Invoking Bison}). This renames the interface
5472 functions and variables of the Bison parser to start with @var{prefix}
5473 instead of @samp{yy}. You can use this to give each parser distinct
5474 names that do not conflict.
5476 The precise list of symbols renamed is @code{yyparse}, @code{yylex},
5477 @code{yyerror}, @code{yynerrs}, @code{yylval}, @code{yylloc},
5478 @code{yychar} and @code{yydebug}. If you use a push parser,
5479 @code{yypush_parse}, @code{yypull_parse}, @code{yypstate},
5480 @code{yypstate_new} and @code{yypstate_delete} will also be renamed.
5481 For example, if you use @samp{-p c}, the names become @code{cparse},
5482 @code{clex}, and so on.
5484 @strong{All the other variables and macros associated with Bison are not
5485 renamed.} These others are not global; there is no conflict if the same
5486 name is used in different parsers. For example, @code{YYSTYPE} is not
5487 renamed, but defining this in different ways in different parsers causes
5488 no trouble (@pxref{Value Type, ,Data Types of Semantic Values}).
5490 The @samp{-p} option works by adding macro definitions to the beginning
5491 of the parser source file, defining @code{yyparse} as
5492 @code{@var{prefix}parse}, and so on. This effectively substitutes one
5493 name for the other in the entire parser file.
5496 @chapter Parser C-Language Interface
5497 @cindex C-language interface
5500 The Bison parser is actually a C function named @code{yyparse}. Here we
5501 describe the interface conventions of @code{yyparse} and the other
5502 functions that it needs to use.
5504 Keep in mind that the parser uses many C identifiers starting with
5505 @samp{yy} and @samp{YY} for internal purposes. If you use such an
5506 identifier (aside from those in this manual) in an action or in epilogue
5507 in the grammar file, you are likely to run into trouble.
5510 * Parser Function:: How to call @code{yyparse} and what it returns.
5511 * Push Parser Function:: How to call @code{yypush_parse} and what it returns.
5512 * Pull Parser Function:: How to call @code{yypull_parse} and what it returns.
5513 * Parser Create Function:: How to call @code{yypstate_new} and what it returns.
5514 * Parser Delete Function:: How to call @code{yypstate_delete} and what it returns.
5515 * Lexical:: You must supply a function @code{yylex}
5517 * Error Reporting:: You must supply a function @code{yyerror}.
5518 * Action Features:: Special features for use in actions.
5519 * Internationalization:: How to let the parser speak in the user's
5523 @node Parser Function
5524 @section The Parser Function @code{yyparse}
5527 You call the function @code{yyparse} to cause parsing to occur. This
5528 function reads tokens, executes actions, and ultimately returns when it
5529 encounters end-of-input or an unrecoverable syntax error. You can also
5530 write an action which directs @code{yyparse} to return immediately
5531 without reading further.
5534 @deftypefun int yyparse (void)
5535 The value returned by @code{yyparse} is 0 if parsing was successful (return
5536 is due to end-of-input).
5538 The value is 1 if parsing failed because of invalid input, i.e., input
5539 that contains a syntax error or that causes @code{YYABORT} to be
5542 The value is 2 if parsing failed due to memory exhaustion.
5545 In an action, you can cause immediate return from @code{yyparse} by using
5550 Return immediately with value 0 (to report success).
5555 Return immediately with value 1 (to report failure).
5558 If you use a reentrant parser, you can optionally pass additional
5559 parameter information to it in a reentrant way. To do so, use the
5560 declaration @code{%parse-param}:
5562 @deffn {Directive} %parse-param @{@var{argument-declaration}@} @dots{}
5563 @findex %parse-param
5564 Declare that one or more
5565 @var{argument-declaration} are additional @code{yyparse} arguments.
5566 The @var{argument-declaration} is used when declaring
5567 functions or prototypes. The last identifier in
5568 @var{argument-declaration} must be the argument name.
5571 Here's an example. Write this in the parser:
5574 %parse-param @{int *nastiness@} @{int *randomness@}
5578 Then call the parser like this:
5582 int nastiness, randomness;
5583 @dots{} /* @r{Store proper data in @code{nastiness} and @code{randomness}.} */
5584 value = yyparse (&nastiness, &randomness);
5590 In the grammar actions, use expressions like this to refer to the data:
5593 exp: @dots{} @{ @dots{}; *randomness += 1; @dots{} @}
5596 @node Push Parser Function
5597 @section The Push Parser Function @code{yypush_parse}
5598 @findex yypush_parse
5600 (The current push parsing interface is experimental and may evolve.
5601 More user feedback will help to stabilize it.)
5603 You call the function @code{yypush_parse} to parse a single token. This
5604 function is available if either the @samp{%define api.push-pull push} or
5605 @samp{%define api.push-pull both} declaration is used.
5606 @xref{Push Decl, ,A Push Parser}.
5608 @deftypefun int yypush_parse (yypstate *yyps)
5609 The value returned by @code{yypush_parse} is the same as for yyparse with the
5610 following exception. @code{yypush_parse} will return YYPUSH_MORE if more input
5611 is required to finish parsing the grammar.
5614 @node Pull Parser Function
5615 @section The Pull Parser Function @code{yypull_parse}
5616 @findex yypull_parse
5618 (The current push parsing interface is experimental and may evolve.
5619 More user feedback will help to stabilize it.)
5621 You call the function @code{yypull_parse} to parse the rest of the input
5622 stream. This function is available if the @samp{%define api.push-pull both}
5623 declaration is used.
5624 @xref{Push Decl, ,A Push Parser}.
5626 @deftypefun int yypull_parse (yypstate *yyps)
5627 The value returned by @code{yypull_parse} is the same as for @code{yyparse}.
5630 @node Parser Create Function
5631 @section The Parser Create Function @code{yystate_new}
5632 @findex yypstate_new
5634 (The current push parsing interface is experimental and may evolve.
5635 More user feedback will help to stabilize it.)
5637 You call the function @code{yypstate_new} to create a new parser instance.
5638 This function is available if either the @samp{%define api.push-pull push} or
5639 @samp{%define api.push-pull both} declaration is used.
5640 @xref{Push Decl, ,A Push Parser}.
5642 @deftypefun yypstate *yypstate_new (void)
5643 The fuction will return a valid parser instance if there was memory available
5644 or 0 if no memory was available.
5645 In impure mode, it will also return 0 if a parser instance is currently
5649 @node Parser Delete Function
5650 @section The Parser Delete Function @code{yystate_delete}
5651 @findex yypstate_delete
5653 (The current push parsing interface is experimental and may evolve.
5654 More user feedback will help to stabilize it.)
5656 You call the function @code{yypstate_delete} to delete a parser instance.
5657 function is available if either the @samp{%define api.push-pull push} or
5658 @samp{%define api.push-pull both} declaration is used.
5659 @xref{Push Decl, ,A Push Parser}.
5661 @deftypefun void yypstate_delete (yypstate *yyps)
5662 This function will reclaim the memory associated with a parser instance.
5663 After this call, you should no longer attempt to use the parser instance.
5667 @section The Lexical Analyzer Function @code{yylex}
5669 @cindex lexical analyzer
5671 The @dfn{lexical analyzer} function, @code{yylex}, recognizes tokens from
5672 the input stream and returns them to the parser. Bison does not create
5673 this function automatically; you must write it so that @code{yyparse} can
5674 call it. The function is sometimes referred to as a lexical scanner.
5676 In simple programs, @code{yylex} is often defined at the end of the Bison
5677 grammar file. If @code{yylex} is defined in a separate source file, you
5678 need to arrange for the token-type macro definitions to be available there.
5679 To do this, use the @samp{-d} option when you run Bison, so that it will
5680 write these macro definitions into a separate header file
5681 @file{@var{name}.tab.h} which you can include in the other source files
5682 that need it. @xref{Invocation, ,Invoking Bison}.
5685 * Calling Convention:: How @code{yyparse} calls @code{yylex}.
5686 * Token Values:: How @code{yylex} must return the semantic value
5687 of the token it has read.
5688 * Token Locations:: How @code{yylex} must return the text location
5689 (line number, etc.) of the token, if the
5691 * Pure Calling:: How the calling convention differs in a pure parser
5692 (@pxref{Pure Decl, ,A Pure (Reentrant) Parser}).
5695 @node Calling Convention
5696 @subsection Calling Convention for @code{yylex}
5698 The value that @code{yylex} returns must be the positive numeric code
5699 for the type of token it has just found; a zero or negative value
5700 signifies end-of-input.
5702 When a token is referred to in the grammar rules by a name, that name
5703 in the parser file becomes a C macro whose definition is the proper
5704 numeric code for that token type. So @code{yylex} can use the name
5705 to indicate that type. @xref{Symbols}.
5707 When a token is referred to in the grammar rules by a character literal,
5708 the numeric code for that character is also the code for the token type.
5709 So @code{yylex} can simply return that character code, possibly converted
5710 to @code{unsigned char} to avoid sign-extension. The null character
5711 must not be used this way, because its code is zero and that
5712 signifies end-of-input.
5714 Here is an example showing these things:
5721 if (c == EOF) /* Detect end-of-input. */
5724 if (c == '+' || c == '-')
5725 return c; /* Assume token type for `+' is '+'. */
5727 return INT; /* Return the type of the token. */
5733 This interface has been designed so that the output from the @code{lex}
5734 utility can be used without change as the definition of @code{yylex}.
5736 If the grammar uses literal string tokens, there are two ways that
5737 @code{yylex} can determine the token type codes for them:
5741 If the grammar defines symbolic token names as aliases for the
5742 literal string tokens, @code{yylex} can use these symbolic names like
5743 all others. In this case, the use of the literal string tokens in
5744 the grammar file has no effect on @code{yylex}.
5747 @code{yylex} can find the multicharacter token in the @code{yytname}
5748 table. The index of the token in the table is the token type's code.
5749 The name of a multicharacter token is recorded in @code{yytname} with a
5750 double-quote, the token's characters, and another double-quote. The
5751 token's characters are escaped as necessary to be suitable as input
5754 Here's code for looking up a multicharacter token in @code{yytname},
5755 assuming that the characters of the token are stored in
5756 @code{token_buffer}, and assuming that the token does not contain any
5757 characters like @samp{"} that require escaping.
5760 for (i = 0; i < YYNTOKENS; i++)
5763 && yytname[i][0] == '"'
5764 && ! strncmp (yytname[i] + 1, token_buffer,
5765 strlen (token_buffer))
5766 && yytname[i][strlen (token_buffer) + 1] == '"'
5767 && yytname[i][strlen (token_buffer) + 2] == 0)
5772 The @code{yytname} table is generated only if you use the
5773 @code{%token-table} declaration. @xref{Decl Summary}.
5777 @subsection Semantic Values of Tokens
5780 In an ordinary (nonreentrant) parser, the semantic value of the token must
5781 be stored into the global variable @code{yylval}. When you are using
5782 just one data type for semantic values, @code{yylval} has that type.
5783 Thus, if the type is @code{int} (the default), you might write this in
5789 yylval = value; /* Put value onto Bison stack. */
5790 return INT; /* Return the type of the token. */
5795 When you are using multiple data types, @code{yylval}'s type is a union
5796 made from the @code{%union} declaration (@pxref{Union Decl, ,The
5797 Collection of Value Types}). So when you store a token's value, you
5798 must use the proper member of the union. If the @code{%union}
5799 declaration looks like this:
5812 then the code in @code{yylex} might look like this:
5817 yylval.intval = value; /* Put value onto Bison stack. */
5818 return INT; /* Return the type of the token. */
5823 @node Token Locations
5824 @subsection Textual Locations of Tokens
5827 If you are using the @samp{@@@var{n}}-feature (@pxref{Locations, ,
5828 Tracking Locations}) in actions to keep track of the textual locations
5829 of tokens and groupings, then you must provide this information in
5830 @code{yylex}. The function @code{yyparse} expects to find the textual
5831 location of a token just parsed in the global variable @code{yylloc}.
5832 So @code{yylex} must store the proper data in that variable.
5834 By default, the value of @code{yylloc} is a structure and you need only
5835 initialize the members that are going to be used by the actions. The
5836 four members are called @code{first_line}, @code{first_column},
5837 @code{last_line} and @code{last_column}. Note that the use of this
5838 feature makes the parser noticeably slower.
5841 The data type of @code{yylloc} has the name @code{YYLTYPE}.
5844 @subsection Calling Conventions for Pure Parsers
5846 When you use the Bison declaration @samp{%define api.pure} to request a
5847 pure, reentrant parser, the global communication variables @code{yylval}
5848 and @code{yylloc} cannot be used. (@xref{Pure Decl, ,A Pure (Reentrant)
5849 Parser}.) In such parsers the two global variables are replaced by
5850 pointers passed as arguments to @code{yylex}. You must declare them as
5851 shown here, and pass the information back by storing it through those
5856 yylex (YYSTYPE *lvalp, YYLTYPE *llocp)
5859 *lvalp = value; /* Put value onto Bison stack. */
5860 return INT; /* Return the type of the token. */
5865 If the grammar file does not use the @samp{@@} constructs to refer to
5866 textual locations, then the type @code{YYLTYPE} will not be defined. In
5867 this case, omit the second argument; @code{yylex} will be called with
5870 If you wish to pass additional arguments to @code{yylex}, use
5871 @code{%lex-param} just like @code{%parse-param} (@pxref{Parser
5872 Function}). To pass additional arguments to both @code{yylex} and
5873 @code{yyparse}, use @code{%param}.
5875 @deffn {Directive} %lex-param @{@var{argument-declaration}@} @dots{}
5877 Specify that @var{argument-declaration} are additional @code{yylex} argument
5878 declarations. You may pass one or more such declarations, which is
5879 equivalent to repeating @code{%lex-param}.
5882 @deffn {Directive} %param @{@var{argument-declaration}@} @dots{}
5884 Specify that @var{argument-declaration} are additional
5885 @code{yylex}/@code{yyparse} argument declaration. This is equivalent to
5886 @samp{%lex-param @{@var{argument-declaration}@} @dots{} %parse-param
5887 @{@var{argument-declaration}@} @dots{}}. You may pass one or more
5888 declarations, which is equivalent to repeating @code{%param}.
5894 %lex-param @{scanner_mode *mode@}
5895 %parse-param @{parser_mode *mode@}
5896 %param @{environment_type *env@}
5900 results in the following signature:
5903 int yylex (scanner_mode *mode, environment_type *env);
5904 int yyparse (parser_mode *mode, environment_type *env);
5907 If @samp{%define api.pure} is added:
5910 int yylex (YYSTYPE *lvalp, scanner_mode *mode, environment_type *env);
5911 int yyparse (parser_mode *mode, environment_type *env);
5915 and finally, if both @samp{%define api.pure} and @code{%locations} are used:
5918 int yylex (YYSTYPE *lvalp, YYLTYPE *llocp,
5919 scanner_mode *mode, environment_type *env);
5920 int yyparse (parser_mode *mode, environment_type *env);
5923 @node Error Reporting
5924 @section The Error Reporting Function @code{yyerror}
5925 @cindex error reporting function
5928 @cindex syntax error
5930 The Bison parser detects a @dfn{syntax error} (or @dfn{parse error})
5931 whenever it reads a token which cannot satisfy any syntax rule. An
5932 action in the grammar can also explicitly proclaim an error, using the
5933 macro @code{YYERROR} (@pxref{Action Features, ,Special Features for Use
5936 The Bison parser expects to report the error by calling an error
5937 reporting function named @code{yyerror}, which you must supply. It is
5938 called by @code{yyparse} whenever a syntax error is found, and it
5939 receives one argument. For a syntax error, the string is normally
5940 @w{@code{"syntax error"}}.
5942 @findex %define parse.error
5943 If you invoke @samp{%define parse.error verbose} in the Bison
5944 declarations section (@pxref{Bison Declarations, ,The Bison Declarations
5945 Section}), then Bison provides a more verbose and specific error message
5946 string instead of just plain @w{@code{"syntax error"}}.
5948 The parser can detect one other kind of error: memory exhaustion. This
5949 can happen when the input contains constructions that are very deeply
5950 nested. It isn't likely you will encounter this, since the Bison
5951 parser normally extends its stack automatically up to a very large limit. But
5952 if memory is exhausted, @code{yyparse} calls @code{yyerror} in the usual
5953 fashion, except that the argument string is @w{@code{"memory exhausted"}}.
5955 In some cases diagnostics like @w{@code{"syntax error"}} are
5956 translated automatically from English to some other language before
5957 they are passed to @code{yyerror}. @xref{Internationalization}.
5959 The following definition suffices in simple programs:
5964 yyerror (char const *s)
5968 fprintf (stderr, "%s\n", s);
5973 After @code{yyerror} returns to @code{yyparse}, the latter will attempt
5974 error recovery if you have written suitable error recovery grammar rules
5975 (@pxref{Error Recovery}). If recovery is impossible, @code{yyparse} will
5976 immediately return 1.
5978 Obviously, in location tracking pure parsers, @code{yyerror} should have
5979 an access to the current location.
5980 This is indeed the case for the @acronym{GLR}
5981 parsers, but not for the Yacc parser, for historical reasons. I.e., if
5982 @samp{%locations %define api.pure} is passed then the prototypes for
5986 void yyerror (char const *msg); /* Yacc parsers. */
5987 void yyerror (YYLTYPE *locp, char const *msg); /* GLR parsers. */
5990 If @samp{%parse-param @{int *nastiness@}} is used, then:
5993 void yyerror (int *nastiness, char const *msg); /* Yacc parsers. */
5994 void yyerror (int *nastiness, char const *msg); /* GLR parsers. */
5997 Finally, @acronym{GLR} and Yacc parsers share the same @code{yyerror} calling
5998 convention for absolutely pure parsers, i.e., when the calling
5999 convention of @code{yylex} @emph{and} the calling convention of
6000 @samp{%define api.pure} are pure.
6004 /* Location tracking. */
6008 %lex-param @{int *nastiness@}
6010 %parse-param @{int *nastiness@}
6011 %parse-param @{int *randomness@}
6015 results in the following signatures for all the parser kinds:
6018 int yylex (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness);
6019 int yyparse (int *nastiness, int *randomness);
6020 void yyerror (YYLTYPE *locp,
6021 int *nastiness, int *randomness,
6026 The prototypes are only indications of how the code produced by Bison
6027 uses @code{yyerror}. Bison-generated code always ignores the returned
6028 value, so @code{yyerror} can return any type, including @code{void}.
6029 Also, @code{yyerror} can be a variadic function; that is why the
6030 message is always passed last.
6032 Traditionally @code{yyerror} returns an @code{int} that is always
6033 ignored, but this is purely for historical reasons, and @code{void} is
6034 preferable since it more accurately describes the return type for
6038 The variable @code{yynerrs} contains the number of syntax errors
6039 reported so far. Normally this variable is global; but if you
6040 request a pure parser (@pxref{Pure Decl, ,A Pure (Reentrant) Parser})
6041 then it is a local variable which only the actions can access.
6043 @node Action Features
6044 @section Special Features for Use in Actions
6045 @cindex summary, action features
6046 @cindex action features summary
6048 Here is a table of Bison constructs, variables and macros that
6049 are useful in actions.
6051 @deffn {Variable} $$
6052 Acts like a variable that contains the semantic value for the
6053 grouping made by the current rule. @xref{Actions}.
6056 @deffn {Variable} $@var{n}
6057 Acts like a variable that contains the semantic value for the
6058 @var{n}th component of the current rule. @xref{Actions}.
6061 @deffn {Variable} $<@var{typealt}>$
6062 Like @code{$$} but specifies alternative @var{typealt} in the union
6063 specified by the @code{%union} declaration. @xref{Action Types, ,Data
6064 Types of Values in Actions}.
6067 @deffn {Variable} $<@var{typealt}>@var{n}
6068 Like @code{$@var{n}} but specifies alternative @var{typealt} in the
6069 union specified by the @code{%union} declaration.
6070 @xref{Action Types, ,Data Types of Values in Actions}.
6073 @deffn {Macro} YYABORT;
6074 Return immediately from @code{yyparse}, indicating failure.
6075 @xref{Parser Function, ,The Parser Function @code{yyparse}}.
6078 @deffn {Macro} YYACCEPT;
6079 Return immediately from @code{yyparse}, indicating success.
6080 @xref{Parser Function, ,The Parser Function @code{yyparse}}.
6083 @deffn {Macro} YYBACKUP (@var{token}, @var{value});
6085 Unshift a token. This macro is allowed only for rules that reduce
6086 a single value, and only when there is no lookahead token.
6087 It is also disallowed in @acronym{GLR} parsers.
6088 It installs a lookahead token with token type @var{token} and
6089 semantic value @var{value}; then it discards the value that was
6090 going to be reduced by this rule.
6092 If the macro is used when it is not valid, such as when there is
6093 a lookahead token already, then it reports a syntax error with
6094 a message @samp{cannot back up} and performs ordinary error
6097 In either case, the rest of the action is not executed.
6100 @deffn {Macro} YYEMPTY
6102 Value stored in @code{yychar} when there is no lookahead token.
6105 @deffn {Macro} YYEOF
6107 Value stored in @code{yychar} when the lookahead is the end of the input
6111 @deffn {Macro} YYERROR;
6113 Cause an immediate syntax error. This statement initiates error
6114 recovery just as if the parser itself had detected an error; however, it
6115 does not call @code{yyerror}, and does not print any message. If you
6116 want to print an error message, call @code{yyerror} explicitly before
6117 the @samp{YYERROR;} statement. @xref{Error Recovery}.
6120 @deffn {Macro} YYRECOVERING
6121 @findex YYRECOVERING
6122 The expression @code{YYRECOVERING ()} yields 1 when the parser
6123 is recovering from a syntax error, and 0 otherwise.
6124 @xref{Error Recovery}.
6127 @deffn {Variable} yychar
6128 Variable containing either the lookahead token, or @code{YYEOF} when the
6129 lookahead is the end of the input stream, or @code{YYEMPTY} when no lookahead
6130 has been performed so the next token is not yet known.
6131 Do not modify @code{yychar} in a deferred semantic action (@pxref{GLR Semantic
6133 @xref{Lookahead, ,Lookahead Tokens}.
6136 @deffn {Macro} yyclearin;
6137 Discard the current lookahead token. This is useful primarily in
6139 Do not invoke @code{yyclearin} in a deferred semantic action (@pxref{GLR
6141 @xref{Error Recovery}.
6144 @deffn {Macro} yyerrok;
6145 Resume generating error messages immediately for subsequent syntax
6146 errors. This is useful primarily in error rules.
6147 @xref{Error Recovery}.
6150 @deffn {Variable} yylloc
6151 Variable containing the lookahead token location when @code{yychar} is not set
6152 to @code{YYEMPTY} or @code{YYEOF}.
6153 Do not modify @code{yylloc} in a deferred semantic action (@pxref{GLR Semantic
6155 @xref{Actions and Locations, ,Actions and Locations}.
6158 @deffn {Variable} yylval
6159 Variable containing the lookahead token semantic value when @code{yychar} is
6160 not set to @code{YYEMPTY} or @code{YYEOF}.
6161 Do not modify @code{yylval} in a deferred semantic action (@pxref{GLR Semantic
6163 @xref{Actions, ,Actions}.
6168 Acts like a structure variable containing information on the textual location
6169 of the grouping made by the current rule. @xref{Locations, ,
6170 Tracking Locations}.
6172 @c Check if those paragraphs are still useful or not.
6176 @c int first_line, last_line;
6177 @c int first_column, last_column;
6181 @c Thus, to get the starting line number of the third component, you would
6182 @c use @samp{@@3.first_line}.
6184 @c In order for the members of this structure to contain valid information,
6185 @c you must make @code{yylex} supply this information about each token.
6186 @c If you need only certain members, then @code{yylex} need only fill in
6189 @c The use of this feature makes the parser noticeably slower.
6192 @deffn {Value} @@@var{n}
6194 Acts like a structure variable containing information on the textual location
6195 of the @var{n}th component of the current rule. @xref{Locations, ,
6196 Tracking Locations}.
6199 @node Internationalization
6200 @section Parser Internationalization
6201 @cindex internationalization
6207 A Bison-generated parser can print diagnostics, including error and
6208 tracing messages. By default, they appear in English. However, Bison
6209 also supports outputting diagnostics in the user's native language. To
6210 make this work, the user should set the usual environment variables.
6211 @xref{Users, , The User's View, gettext, GNU @code{gettext} utilities}.
6212 For example, the shell command @samp{export LC_ALL=fr_CA.UTF-8} might
6213 set the user's locale to French Canadian using the @acronym{UTF}-8
6214 encoding. The exact set of available locales depends on the user's
6217 The maintainer of a package that uses a Bison-generated parser enables
6218 the internationalization of the parser's output through the following
6219 steps. Here we assume a package that uses @acronym{GNU} Autoconf and
6220 @acronym{GNU} Automake.
6224 @cindex bison-i18n.m4
6225 Into the directory containing the @acronym{GNU} Autoconf macros used
6226 by the package---often called @file{m4}---copy the
6227 @file{bison-i18n.m4} file installed by Bison under
6228 @samp{share/aclocal/bison-i18n.m4} in Bison's installation directory.
6232 cp /usr/local/share/aclocal/bison-i18n.m4 m4/bison-i18n.m4
6237 @vindex BISON_LOCALEDIR
6238 @vindex YYENABLE_NLS
6239 In the top-level @file{configure.ac}, after the @code{AM_GNU_GETTEXT}
6240 invocation, add an invocation of @code{BISON_I18N}. This macro is
6241 defined in the file @file{bison-i18n.m4} that you copied earlier. It
6242 causes @samp{configure} to find the value of the
6243 @code{BISON_LOCALEDIR} variable, and it defines the source-language
6244 symbol @code{YYENABLE_NLS} to enable translations in the
6245 Bison-generated parser.
6248 In the @code{main} function of your program, designate the directory
6249 containing Bison's runtime message catalog, through a call to
6250 @samp{bindtextdomain} with domain name @samp{bison-runtime}.
6254 bindtextdomain ("bison-runtime", BISON_LOCALEDIR);
6257 Typically this appears after any other call @code{bindtextdomain
6258 (PACKAGE, LOCALEDIR)} that your package already has. Here we rely on
6259 @samp{BISON_LOCALEDIR} to be defined as a string through the
6263 In the @file{Makefile.am} that controls the compilation of the @code{main}
6264 function, make @samp{BISON_LOCALEDIR} available as a C preprocessor macro,
6265 either in @samp{DEFS} or in @samp{AM_CPPFLAGS}. For example:
6268 DEFS = @@DEFS@@ -DBISON_LOCALEDIR='"$(BISON_LOCALEDIR)"'
6274 AM_CPPFLAGS = -DBISON_LOCALEDIR='"$(BISON_LOCALEDIR)"'
6278 Finally, invoke the command @command{autoreconf} to generate the build
6284 @chapter The Bison Parser Algorithm
6285 @cindex Bison parser algorithm
6286 @cindex algorithm of parser
6289 @cindex parser stack
6290 @cindex stack, parser
6292 As Bison reads tokens, it pushes them onto a stack along with their
6293 semantic values. The stack is called the @dfn{parser stack}. Pushing a
6294 token is traditionally called @dfn{shifting}.
6296 For example, suppose the infix calculator has read @samp{1 + 5 *}, with a
6297 @samp{3} to come. The stack will have four elements, one for each token
6300 But the stack does not always have an element for each token read. When
6301 the last @var{n} tokens and groupings shifted match the components of a
6302 grammar rule, they can be combined according to that rule. This is called
6303 @dfn{reduction}. Those tokens and groupings are replaced on the stack by a
6304 single grouping whose symbol is the result (left hand side) of that rule.
6305 Running the rule's action is part of the process of reduction, because this
6306 is what computes the semantic value of the resulting grouping.
6308 For example, if the infix calculator's parser stack contains this:
6315 and the next input token is a newline character, then the last three
6316 elements can be reduced to 15 via the rule:
6319 expr: expr '*' expr;
6323 Then the stack contains just these three elements:
6330 At this point, another reduction can be made, resulting in the single value
6331 16. Then the newline token can be shifted.
6333 The parser tries, by shifts and reductions, to reduce the entire input down
6334 to a single grouping whose symbol is the grammar's start-symbol
6335 (@pxref{Language and Grammar, ,Languages and Context-Free Grammars}).
6337 This kind of parser is known in the literature as a bottom-up parser.
6340 * Lookahead:: Parser looks one token ahead when deciding what to do.
6341 * Shift/Reduce:: Conflicts: when either shifting or reduction is valid.
6342 * Precedence:: Operator precedence works by resolving conflicts.
6343 * Contextual Precedence:: When an operator's precedence depends on context.
6344 * Parser States:: The parser is a finite-state-machine with stack.
6345 * Reduce/Reduce:: When two rules are applicable in the same situation.
6346 * Mystery Conflicts:: Reduce/reduce conflicts that look unjustified.
6347 * Generalized LR Parsing:: Parsing arbitrary context-free grammars.
6348 * Memory Management:: What happens when memory is exhausted. How to avoid it.
6352 @section Lookahead Tokens
6353 @cindex lookahead token
6355 The Bison parser does @emph{not} always reduce immediately as soon as the
6356 last @var{n} tokens and groupings match a rule. This is because such a
6357 simple strategy is inadequate to handle most languages. Instead, when a
6358 reduction is possible, the parser sometimes ``looks ahead'' at the next
6359 token in order to decide what to do.
6361 When a token is read, it is not immediately shifted; first it becomes the
6362 @dfn{lookahead token}, which is not on the stack. Now the parser can
6363 perform one or more reductions of tokens and groupings on the stack, while
6364 the lookahead token remains off to the side. When no more reductions
6365 should take place, the lookahead token is shifted onto the stack. This
6366 does not mean that all possible reductions have been done; depending on the
6367 token type of the lookahead token, some rules may choose to delay their
6370 Here is a simple case where lookahead is needed. These three rules define
6371 expressions which contain binary addition operators and postfix unary
6372 factorial operators (@samp{!}), and allow parentheses for grouping.
6389 Suppose that the tokens @w{@samp{1 + 2}} have been read and shifted; what
6390 should be done? If the following token is @samp{)}, then the first three
6391 tokens must be reduced to form an @code{expr}. This is the only valid
6392 course, because shifting the @samp{)} would produce a sequence of symbols
6393 @w{@code{term ')'}}, and no rule allows this.
6395 If the following token is @samp{!}, then it must be shifted immediately so
6396 that @w{@samp{2 !}} can be reduced to make a @code{term}. If instead the
6397 parser were to reduce before shifting, @w{@samp{1 + 2}} would become an
6398 @code{expr}. It would then be impossible to shift the @samp{!} because
6399 doing so would produce on the stack the sequence of symbols @code{expr
6400 '!'}. No rule allows that sequence.
6405 The lookahead token is stored in the variable @code{yychar}.
6406 Its semantic value and location, if any, are stored in the variables
6407 @code{yylval} and @code{yylloc}.
6408 @xref{Action Features, ,Special Features for Use in Actions}.
6411 @section Shift/Reduce Conflicts
6413 @cindex shift/reduce conflicts
6414 @cindex dangling @code{else}
6415 @cindex @code{else}, dangling
6417 Suppose we are parsing a language which has if-then and if-then-else
6418 statements, with a pair of rules like this:
6424 | IF expr THEN stmt ELSE stmt
6430 Here we assume that @code{IF}, @code{THEN} and @code{ELSE} are
6431 terminal symbols for specific keyword tokens.
6433 When the @code{ELSE} token is read and becomes the lookahead token, the
6434 contents of the stack (assuming the input is valid) are just right for
6435 reduction by the first rule. But it is also legitimate to shift the
6436 @code{ELSE}, because that would lead to eventual reduction by the second
6439 This situation, where either a shift or a reduction would be valid, is
6440 called a @dfn{shift/reduce conflict}. Bison is designed to resolve
6441 these conflicts by choosing to shift, unless otherwise directed by
6442 operator precedence declarations. To see the reason for this, let's
6443 contrast it with the other alternative.
6445 Since the parser prefers to shift the @code{ELSE}, the result is to attach
6446 the else-clause to the innermost if-statement, making these two inputs
6450 if x then if y then win (); else lose;
6452 if x then do; if y then win (); else lose; end;
6455 But if the parser chose to reduce when possible rather than shift, the
6456 result would be to attach the else-clause to the outermost if-statement,
6457 making these two inputs equivalent:
6460 if x then if y then win (); else lose;
6462 if x then do; if y then win (); end; else lose;
6465 The conflict exists because the grammar as written is ambiguous: either
6466 parsing of the simple nested if-statement is legitimate. The established
6467 convention is that these ambiguities are resolved by attaching the
6468 else-clause to the innermost if-statement; this is what Bison accomplishes
6469 by choosing to shift rather than reduce. (It would ideally be cleaner to
6470 write an unambiguous grammar, but that is very hard to do in this case.)
6471 This particular ambiguity was first encountered in the specifications of
6472 Algol 60 and is called the ``dangling @code{else}'' ambiguity.
6474 To avoid warnings from Bison about predictable, legitimate shift/reduce
6475 conflicts, use the @code{%expect @var{n}} declaration. There will be no
6476 warning as long as the number of shift/reduce conflicts is exactly @var{n}.
6477 @xref{Expect Decl, ,Suppressing Conflict Warnings}.
6479 The definition of @code{if_stmt} above is solely to blame for the
6480 conflict, but the conflict does not actually appear without additional
6481 rules. Here is a complete Bison input file that actually manifests the
6486 %token IF THEN ELSE variable
6498 | IF expr THEN stmt ELSE stmt
6507 @section Operator Precedence
6508 @cindex operator precedence
6509 @cindex precedence of operators
6511 Another situation where shift/reduce conflicts appear is in arithmetic
6512 expressions. Here shifting is not always the preferred resolution; the
6513 Bison declarations for operator precedence allow you to specify when to
6514 shift and when to reduce.
6517 * Why Precedence:: An example showing why precedence is needed.
6518 * Using Precedence:: How to specify precedence and associativity.
6519 * Precedence Only:: How to specify precedence only.
6520 * Precedence Examples:: How these features are used in the previous example.
6521 * How Precedence:: How they work.
6524 @node Why Precedence
6525 @subsection When Precedence is Needed
6527 Consider the following ambiguous grammar fragment (ambiguous because the
6528 input @w{@samp{1 - 2 * 3}} can be parsed in two different ways):
6542 Suppose the parser has seen the tokens @samp{1}, @samp{-} and @samp{2};
6543 should it reduce them via the rule for the subtraction operator? It
6544 depends on the next token. Of course, if the next token is @samp{)}, we
6545 must reduce; shifting is invalid because no single rule can reduce the
6546 token sequence @w{@samp{- 2 )}} or anything starting with that. But if
6547 the next token is @samp{*} or @samp{<}, we have a choice: either
6548 shifting or reduction would allow the parse to complete, but with
6551 To decide which one Bison should do, we must consider the results. If
6552 the next operator token @var{op} is shifted, then it must be reduced
6553 first in order to permit another opportunity to reduce the difference.
6554 The result is (in effect) @w{@samp{1 - (2 @var{op} 3)}}. On the other
6555 hand, if the subtraction is reduced before shifting @var{op}, the result
6556 is @w{@samp{(1 - 2) @var{op} 3}}. Clearly, then, the choice of shift or
6557 reduce should depend on the relative precedence of the operators
6558 @samp{-} and @var{op}: @samp{*} should be shifted first, but not
6561 @cindex associativity
6562 What about input such as @w{@samp{1 - 2 - 5}}; should this be
6563 @w{@samp{(1 - 2) - 5}} or should it be @w{@samp{1 - (2 - 5)}}? For most
6564 operators we prefer the former, which is called @dfn{left association}.
6565 The latter alternative, @dfn{right association}, is desirable for
6566 assignment operators. The choice of left or right association is a
6567 matter of whether the parser chooses to shift or reduce when the stack
6568 contains @w{@samp{1 - 2}} and the lookahead token is @samp{-}: shifting
6569 makes right-associativity.
6571 @node Using Precedence
6572 @subsection Specifying Operator Precedence
6578 Bison allows you to specify these choices with the operator precedence
6579 declarations @code{%left} and @code{%right}. Each such declaration
6580 contains a list of tokens, which are operators whose precedence and
6581 associativity is being declared. The @code{%left} declaration makes all
6582 those operators left-associative and the @code{%right} declaration makes
6583 them right-associative. A third alternative is @code{%nonassoc}, which
6584 declares that it is a syntax error to find the same operator twice ``in a
6586 The last alternative, @code{%precedence}, allows to define only
6587 precedence and no associativity at all. As a result, any
6588 associativity-related conflict that remains will be reported as an
6589 compile-time error. The directive @code{%nonassoc} creates run-time
6590 error: using the operator in a associative way is a syntax error. The
6591 directive @code{%precedence} creates compile-time errors: an operator
6592 @emph{can} be involved in an associativity-related conflict, contrary to
6593 what expected the grammar author.
6595 The relative precedence of different operators is controlled by the
6596 order in which they are declared. The first precedence/associativity
6597 declaration in the file declares the operators whose
6598 precedence is lowest, the next such declaration declares the operators
6599 whose precedence is a little higher, and so on.
6601 @node Precedence Only
6602 @subsection Specifying Precedence Only
6605 Since @acronym{POSIX} Yacc defines only @code{%left}, @code{%right}, and
6606 @code{%nonassoc}, which all defines precedence and associativity, little
6607 attention is paid to the fact that precedence cannot be defined without
6608 defining associativity. Yet, sometimes, when trying to solve a
6609 conflict, precedence suffices. In such a case, using @code{%left},
6610 @code{%right}, or @code{%nonassoc} might hide future (associativity
6611 related) conflicts that would remain hidden.
6613 The dangling @code{else} ambiguity (@pxref{Shift/Reduce, , Shift/Reduce
6614 Conflicts}) can be solved explictly. This shift/reduce conflicts occurs
6615 in the following situation, where the period denotes the current parsing
6619 if @var{e1} then if @var{e2} then @var{s1} . else @var{s2}
6622 The conflict involves the reduction of the rule @samp{IF expr THEN
6623 stmt}, which precedence is by default that of its last token
6624 (@code{THEN}), and the shifting of the token @code{ELSE}. The usual
6625 disambiguation (attach the @code{else} to the closest @code{if}),
6626 shifting must be preferred, i.e., the precedence of @code{ELSE} must be
6627 higher than that of @code{THEN}. But neither is expected to be involved
6628 in an associativity related conflict, which can be specified as follows.
6635 The unary-minus is another typical example where associativity is
6636 usually over-specified, see @ref{Infix Calc, , Infix Notation
6637 Calculator: @code{calc}}. The @code{%left} directive is traditionaly
6638 used to declare the precedence of @code{NEG}, which is more than needed
6639 since it also defines its associativity. While this is harmless in the
6640 traditional example, who knows how @code{NEG} might be used in future
6641 evolutions of the grammar@dots{}
6643 @node Precedence Examples
6644 @subsection Precedence Examples
6646 In our example, we would want the following declarations:
6654 In a more complete example, which supports other operators as well, we
6655 would declare them in groups of equal precedence. For example, @code{'+'} is
6656 declared with @code{'-'}:
6659 %left '<' '>' '=' NE LE GE
6665 (Here @code{NE} and so on stand for the operators for ``not equal''
6666 and so on. We assume that these tokens are more than one character long
6667 and therefore are represented by names, not character literals.)
6669 @node How Precedence
6670 @subsection How Precedence Works
6672 The first effect of the precedence declarations is to assign precedence
6673 levels to the terminal symbols declared. The second effect is to assign
6674 precedence levels to certain rules: each rule gets its precedence from
6675 the last terminal symbol mentioned in the components. (You can also
6676 specify explicitly the precedence of a rule. @xref{Contextual
6677 Precedence, ,Context-Dependent Precedence}.)
6679 Finally, the resolution of conflicts works by comparing the precedence
6680 of the rule being considered with that of the lookahead token. If the
6681 token's precedence is higher, the choice is to shift. If the rule's
6682 precedence is higher, the choice is to reduce. If they have equal
6683 precedence, the choice is made based on the associativity of that
6684 precedence level. The verbose output file made by @samp{-v}
6685 (@pxref{Invocation, ,Invoking Bison}) says how each conflict was
6688 Not all rules and not all tokens have precedence. If either the rule or
6689 the lookahead token has no precedence, then the default is to shift.
6691 @node Contextual Precedence
6692 @section Context-Dependent Precedence
6693 @cindex context-dependent precedence
6694 @cindex unary operator precedence
6695 @cindex precedence, context-dependent
6696 @cindex precedence, unary operator
6699 Often the precedence of an operator depends on the context. This sounds
6700 outlandish at first, but it is really very common. For example, a minus
6701 sign typically has a very high precedence as a unary operator, and a
6702 somewhat lower precedence (lower than multiplication) as a binary operator.
6704 The Bison precedence declarations
6705 can only be used once for a given token; so a token has
6706 only one precedence declared in this way. For context-dependent
6707 precedence, you need to use an additional mechanism: the @code{%prec}
6710 The @code{%prec} modifier declares the precedence of a particular rule by
6711 specifying a terminal symbol whose precedence should be used for that rule.
6712 It's not necessary for that symbol to appear otherwise in the rule. The
6713 modifier's syntax is:
6716 %prec @var{terminal-symbol}
6720 and it is written after the components of the rule. Its effect is to
6721 assign the rule the precedence of @var{terminal-symbol}, overriding
6722 the precedence that would be deduced for it in the ordinary way. The
6723 altered rule precedence then affects how conflicts involving that rule
6724 are resolved (@pxref{Precedence, ,Operator Precedence}).
6726 Here is how @code{%prec} solves the problem of unary minus. First, declare
6727 a precedence for a fictitious terminal symbol named @code{UMINUS}. There
6728 are no tokens of this type, but the symbol serves to stand for its
6738 Now the precedence of @code{UMINUS} can be used in specific rules:
6745 | '-' exp %prec UMINUS
6750 If you forget to append @code{%prec UMINUS} to the rule for unary
6751 minus, Bison silently assumes that minus has its usual precedence.
6752 This kind of problem can be tricky to debug, since one typically
6753 discovers the mistake only by testing the code.
6755 The @code{%no-default-prec;} declaration makes it easier to discover
6756 this kind of problem systematically. It causes rules that lack a
6757 @code{%prec} modifier to have no precedence, even if the last terminal
6758 symbol mentioned in their components has a declared precedence.
6760 If @code{%no-default-prec;} is in effect, you must specify @code{%prec}
6761 for all rules that participate in precedence conflict resolution.
6762 Then you will see any shift/reduce conflict until you tell Bison how
6763 to resolve it, either by changing your grammar or by adding an
6764 explicit precedence. This will probably add declarations to the
6765 grammar, but it helps to protect against incorrect rule precedences.
6767 The effect of @code{%no-default-prec;} can be reversed by giving
6768 @code{%default-prec;}, which is the default.
6772 @section Parser States
6773 @cindex finite-state machine
6774 @cindex parser state
6775 @cindex state (of parser)
6777 The function @code{yyparse} is implemented using a finite-state machine.
6778 The values pushed on the parser stack are not simply token type codes; they
6779 represent the entire sequence of terminal and nonterminal symbols at or
6780 near the top of the stack. The current state collects all the information
6781 about previous input which is relevant to deciding what to do next.
6783 Each time a lookahead token is read, the current parser state together
6784 with the type of lookahead token are looked up in a table. This table
6785 entry can say, ``Shift the lookahead token.'' In this case, it also
6786 specifies the new parser state, which is pushed onto the top of the
6787 parser stack. Or it can say, ``Reduce using rule number @var{n}.''
6788 This means that a certain number of tokens or groupings are taken off
6789 the top of the stack, and replaced by one grouping. In other words,
6790 that number of states are popped from the stack, and one new state is
6793 There is one other alternative: the table can say that the lookahead token
6794 is erroneous in the current state. This causes error processing to begin
6795 (@pxref{Error Recovery}).
6798 @section Reduce/Reduce Conflicts
6799 @cindex reduce/reduce conflict
6800 @cindex conflicts, reduce/reduce
6802 A reduce/reduce conflict occurs if there are two or more rules that apply
6803 to the same sequence of input. This usually indicates a serious error
6806 For example, here is an erroneous attempt to define a sequence
6807 of zero or more @code{word} groupings.
6810 sequence: /* empty */
6811 @{ printf ("empty sequence\n"); @}
6814 @{ printf ("added word %s\n", $2); @}
6817 maybeword: /* empty */
6818 @{ printf ("empty maybeword\n"); @}
6820 @{ printf ("single word %s\n", $1); @}
6825 The error is an ambiguity: there is more than one way to parse a single
6826 @code{word} into a @code{sequence}. It could be reduced to a
6827 @code{maybeword} and then into a @code{sequence} via the second rule.
6828 Alternatively, nothing-at-all could be reduced into a @code{sequence}
6829 via the first rule, and this could be combined with the @code{word}
6830 using the third rule for @code{sequence}.
6832 There is also more than one way to reduce nothing-at-all into a
6833 @code{sequence}. This can be done directly via the first rule,
6834 or indirectly via @code{maybeword} and then the second rule.
6836 You might think that this is a distinction without a difference, because it
6837 does not change whether any particular input is valid or not. But it does
6838 affect which actions are run. One parsing order runs the second rule's
6839 action; the other runs the first rule's action and the third rule's action.
6840 In this example, the output of the program changes.
6842 Bison resolves a reduce/reduce conflict by choosing to use the rule that
6843 appears first in the grammar, but it is very risky to rely on this. Every
6844 reduce/reduce conflict must be studied and usually eliminated. Here is the
6845 proper way to define @code{sequence}:
6848 sequence: /* empty */
6849 @{ printf ("empty sequence\n"); @}
6851 @{ printf ("added word %s\n", $2); @}
6855 Here is another common error that yields a reduce/reduce conflict:
6858 sequence: /* empty */
6860 | sequence redirects
6867 redirects:/* empty */
6868 | redirects redirect
6873 The intention here is to define a sequence which can contain either
6874 @code{word} or @code{redirect} groupings. The individual definitions of
6875 @code{sequence}, @code{words} and @code{redirects} are error-free, but the
6876 three together make a subtle ambiguity: even an empty input can be parsed
6877 in infinitely many ways!
6879 Consider: nothing-at-all could be a @code{words}. Or it could be two
6880 @code{words} in a row, or three, or any number. It could equally well be a
6881 @code{redirects}, or two, or any number. Or it could be a @code{words}
6882 followed by three @code{redirects} and another @code{words}. And so on.
6884 Here are two ways to correct these rules. First, to make it a single level
6888 sequence: /* empty */
6894 Second, to prevent either a @code{words} or a @code{redirects}
6898 sequence: /* empty */
6900 | sequence redirects
6908 | redirects redirect
6912 @node Mystery Conflicts
6913 @section Mysterious Reduce/Reduce Conflicts
6915 Sometimes reduce/reduce conflicts can occur that don't look warranted.
6923 def: param_spec return_spec ','
6927 | name_list ':' type
6945 | name ',' name_list
6950 It would seem that this grammar can be parsed with only a single token
6951 of lookahead: when a @code{param_spec} is being read, an @code{ID} is
6952 a @code{name} if a comma or colon follows, or a @code{type} if another
6953 @code{ID} follows. In other words, this grammar is @acronym{LR}(1).
6955 @cindex @acronym{LR}(1)
6956 @cindex @acronym{LALR}(1)
6957 However, for historical reasons, Bison cannot by default handle all
6958 @acronym{LR}(1) grammars.
6959 In this grammar, two contexts, that after an @code{ID} at the beginning
6960 of a @code{param_spec} and likewise at the beginning of a
6961 @code{return_spec}, are similar enough that Bison assumes they are the
6963 They appear similar because the same set of rules would be
6964 active---the rule for reducing to a @code{name} and that for reducing to
6965 a @code{type}. Bison is unable to determine at that stage of processing
6966 that the rules would require different lookahead tokens in the two
6967 contexts, so it makes a single parser state for them both. Combining
6968 the two contexts causes a conflict later. In parser terminology, this
6969 occurrence means that the grammar is not @acronym{LALR}(1).
6971 For many practical grammars (specifically those that fall into the
6972 non-@acronym{LR}(1) class), the limitations of @acronym{LALR}(1) result in
6973 difficulties beyond just mysterious reduce/reduce conflicts.
6974 The best way to fix all these problems is to select a different parser
6975 table generation algorithm.
6976 Either @acronym{IELR}(1) or canonical @acronym{LR}(1) would suffice, but
6977 the former is more efficient and easier to debug during development.
6978 @xref{Decl Summary,,lr.type}, for details.
6979 (Bison's @acronym{IELR}(1) and canonical @acronym{LR}(1) implementations
6981 More user feedback will help to stabilize them.)
6983 If you instead wish to work around @acronym{LALR}(1)'s limitations, you
6984 can often fix a mysterious conflict by identifying the two parser states
6985 that are being confused, and adding something to make them look
6986 distinct. In the above example, adding one rule to
6987 @code{return_spec} as follows makes the problem go away:
6998 /* This rule is never used. */
7004 This corrects the problem because it introduces the possibility of an
7005 additional active rule in the context after the @code{ID} at the beginning of
7006 @code{return_spec}. This rule is not active in the corresponding context
7007 in a @code{param_spec}, so the two contexts receive distinct parser states.
7008 As long as the token @code{BOGUS} is never generated by @code{yylex},
7009 the added rule cannot alter the way actual input is parsed.
7011 In this particular example, there is another way to solve the problem:
7012 rewrite the rule for @code{return_spec} to use @code{ID} directly
7013 instead of via @code{name}. This also causes the two confusing
7014 contexts to have different sets of active rules, because the one for
7015 @code{return_spec} activates the altered rule for @code{return_spec}
7016 rather than the one for @code{name}.
7021 | name_list ':' type
7029 For a more detailed exposition of @acronym{LALR}(1) parsers and parser
7030 generators, please see:
7031 Frank DeRemer and Thomas Pennello, Efficient Computation of
7032 @acronym{LALR}(1) Look-Ahead Sets, @cite{@acronym{ACM} Transactions on
7033 Programming Languages and Systems}, Vol.@: 4, No.@: 4 (October 1982),
7034 pp.@: 615--649 @uref{http://doi.acm.org/10.1145/69622.357187}.
7036 @node Generalized LR Parsing
7037 @section Generalized @acronym{LR} (@acronym{GLR}) Parsing
7038 @cindex @acronym{GLR} parsing
7039 @cindex generalized @acronym{LR} (@acronym{GLR}) parsing
7040 @cindex ambiguous grammars
7041 @cindex nondeterministic parsing
7043 Bison produces @emph{deterministic} parsers that choose uniquely
7044 when to reduce and which reduction to apply
7045 based on a summary of the preceding input and on one extra token of lookahead.
7046 As a result, normal Bison handles a proper subset of the family of
7047 context-free languages.
7048 Ambiguous grammars, since they have strings with more than one possible
7049 sequence of reductions cannot have deterministic parsers in this sense.
7050 The same is true of languages that require more than one symbol of
7051 lookahead, since the parser lacks the information necessary to make a
7052 decision at the point it must be made in a shift-reduce parser.
7053 Finally, as previously mentioned (@pxref{Mystery Conflicts}),
7054 there are languages where Bison's default choice of how to
7055 summarize the input seen so far loses necessary information.
7057 When you use the @samp{%glr-parser} declaration in your grammar file,
7058 Bison generates a parser that uses a different algorithm, called
7059 Generalized @acronym{LR} (or @acronym{GLR}). A Bison @acronym{GLR}
7060 parser uses the same basic
7061 algorithm for parsing as an ordinary Bison parser, but behaves
7062 differently in cases where there is a shift-reduce conflict that has not
7063 been resolved by precedence rules (@pxref{Precedence}) or a
7064 reduce-reduce conflict. When a @acronym{GLR} parser encounters such a
7066 effectively @emph{splits} into a several parsers, one for each possible
7067 shift or reduction. These parsers then proceed as usual, consuming
7068 tokens in lock-step. Some of the stacks may encounter other conflicts
7069 and split further, with the result that instead of a sequence of states,
7070 a Bison @acronym{GLR} parsing stack is what is in effect a tree of states.
7072 In effect, each stack represents a guess as to what the proper parse
7073 is. Additional input may indicate that a guess was wrong, in which case
7074 the appropriate stack silently disappears. Otherwise, the semantics
7075 actions generated in each stack are saved, rather than being executed
7076 immediately. When a stack disappears, its saved semantic actions never
7077 get executed. When a reduction causes two stacks to become equivalent,
7078 their sets of semantic actions are both saved with the state that
7079 results from the reduction. We say that two stacks are equivalent
7080 when they both represent the same sequence of states,
7081 and each pair of corresponding states represents a
7082 grammar symbol that produces the same segment of the input token
7085 Whenever the parser makes a transition from having multiple
7086 states to having one, it reverts to the normal deterministic parsing
7087 algorithm, after resolving and executing the saved-up actions.
7088 At this transition, some of the states on the stack will have semantic
7089 values that are sets (actually multisets) of possible actions. The
7090 parser tries to pick one of the actions by first finding one whose rule
7091 has the highest dynamic precedence, as set by the @samp{%dprec}
7092 declaration. Otherwise, if the alternative actions are not ordered by
7093 precedence, but there the same merging function is declared for both
7094 rules by the @samp{%merge} declaration,
7095 Bison resolves and evaluates both and then calls the merge function on
7096 the result. Otherwise, it reports an ambiguity.
7098 It is possible to use a data structure for the @acronym{GLR} parsing tree that
7099 permits the processing of any @acronym{LR}(1) grammar in linear time (in the
7100 size of the input), any unambiguous (not necessarily
7101 @acronym{LR}(1)) grammar in
7102 quadratic worst-case time, and any general (possibly ambiguous)
7103 context-free grammar in cubic worst-case time. However, Bison currently
7104 uses a simpler data structure that requires time proportional to the
7105 length of the input times the maximum number of stacks required for any
7106 prefix of the input. Thus, really ambiguous or nondeterministic
7107 grammars can require exponential time and space to process. Such badly
7108 behaving examples, however, are not generally of practical interest.
7109 Usually, nondeterminism in a grammar is local---the parser is ``in
7110 doubt'' only for a few tokens at a time. Therefore, the current data
7111 structure should generally be adequate. On @acronym{LR}(1) portions of a
7112 grammar, in particular, it is only slightly slower than with the
7113 deterministic @acronym{LR}(1) Bison parser.
7115 For a more detailed exposition of @acronym{GLR} parsers, please see: Elizabeth
7116 Scott, Adrian Johnstone and Shamsa Sadaf Hussain, Tomita-Style
7117 Generalised @acronym{LR} Parsers, Royal Holloway, University of
7118 London, Department of Computer Science, TR-00-12,
7119 @uref{http://www.cs.rhul.ac.uk/research/languages/publications/tomita_style_1.ps},
7122 @node Memory Management
7123 @section Memory Management, and How to Avoid Memory Exhaustion
7124 @cindex memory exhaustion
7125 @cindex memory management
7126 @cindex stack overflow
7127 @cindex parser stack overflow
7128 @cindex overflow of parser stack
7130 The Bison parser stack can run out of memory if too many tokens are shifted and
7131 not reduced. When this happens, the parser function @code{yyparse}
7132 calls @code{yyerror} and then returns 2.
7134 Because Bison parsers have growing stacks, hitting the upper limit
7135 usually results from using a right recursion instead of a left
7136 recursion, @xref{Recursion, ,Recursive Rules}.
7139 By defining the macro @code{YYMAXDEPTH}, you can control how deep the
7140 parser stack can become before memory is exhausted. Define the
7141 macro with a value that is an integer. This value is the maximum number
7142 of tokens that can be shifted (and not reduced) before overflow.
7144 The stack space allowed is not necessarily allocated. If you specify a
7145 large value for @code{YYMAXDEPTH}, the parser normally allocates a small
7146 stack at first, and then makes it bigger by stages as needed. This
7147 increasing allocation happens automatically and silently. Therefore,
7148 you do not need to make @code{YYMAXDEPTH} painfully small merely to save
7149 space for ordinary inputs that do not need much stack.
7151 However, do not allow @code{YYMAXDEPTH} to be a value so large that
7152 arithmetic overflow could occur when calculating the size of the stack
7153 space. Also, do not allow @code{YYMAXDEPTH} to be less than
7156 @cindex default stack limit
7157 The default value of @code{YYMAXDEPTH}, if you do not define it, is
7161 You can control how much stack is allocated initially by defining the
7162 macro @code{YYINITDEPTH} to a positive integer. For the deterministic
7163 parser in C, this value must be a compile-time constant
7164 unless you are assuming C99 or some other target language or compiler
7165 that allows variable-length arrays. The default is 200.
7167 Do not allow @code{YYINITDEPTH} to be greater than @code{YYMAXDEPTH}.
7169 @c FIXME: C++ output.
7170 Because of semantical differences between C and C++, the deterministic
7171 parsers in C produced by Bison cannot grow when compiled
7172 by C++ compilers. In this precise case (compiling a C parser as C++) you are
7173 suggested to grow @code{YYINITDEPTH}. The Bison maintainers hope to fix
7174 this deficiency in a future release.
7176 @node Error Recovery
7177 @chapter Error Recovery
7178 @cindex error recovery
7179 @cindex recovery from errors
7181 It is not usually acceptable to have a program terminate on a syntax
7182 error. For example, a compiler should recover sufficiently to parse the
7183 rest of the input file and check it for errors; a calculator should accept
7186 In a simple interactive command parser where each input is one line, it may
7187 be sufficient to allow @code{yyparse} to return 1 on error and have the
7188 caller ignore the rest of the input line when that happens (and then call
7189 @code{yyparse} again). But this is inadequate for a compiler, because it
7190 forgets all the syntactic context leading up to the error. A syntax error
7191 deep within a function in the compiler input should not cause the compiler
7192 to treat the following line like the beginning of a source file.
7195 You can define how to recover from a syntax error by writing rules to
7196 recognize the special token @code{error}. This is a terminal symbol that
7197 is always defined (you need not declare it) and reserved for error
7198 handling. The Bison parser generates an @code{error} token whenever a
7199 syntax error happens; if you have provided a rule to recognize this token
7200 in the current context, the parse can continue.
7205 stmnts: /* empty string */
7211 The fourth rule in this example says that an error followed by a newline
7212 makes a valid addition to any @code{stmnts}.
7214 What happens if a syntax error occurs in the middle of an @code{exp}? The
7215 error recovery rule, interpreted strictly, applies to the precise sequence
7216 of a @code{stmnts}, an @code{error} and a newline. If an error occurs in
7217 the middle of an @code{exp}, there will probably be some additional tokens
7218 and subexpressions on the stack after the last @code{stmnts}, and there
7219 will be tokens to read before the next newline. So the rule is not
7220 applicable in the ordinary way.
7222 But Bison can force the situation to fit the rule, by discarding part of
7223 the semantic context and part of the input. First it discards states
7224 and objects from the stack until it gets back to a state in which the
7225 @code{error} token is acceptable. (This means that the subexpressions
7226 already parsed are discarded, back to the last complete @code{stmnts}.)
7227 At this point the @code{error} token can be shifted. Then, if the old
7228 lookahead token is not acceptable to be shifted next, the parser reads
7229 tokens and discards them until it finds a token which is acceptable. In
7230 this example, Bison reads and discards input until the next newline so
7231 that the fourth rule can apply. Note that discarded symbols are
7232 possible sources of memory leaks, see @ref{Destructor Decl, , Freeing
7233 Discarded Symbols}, for a means to reclaim this memory.
7235 The choice of error rules in the grammar is a choice of strategies for
7236 error recovery. A simple and useful strategy is simply to skip the rest of
7237 the current input line or current statement if an error is detected:
7240 stmnt: error ';' /* On error, skip until ';' is read. */
7243 It is also useful to recover to the matching close-delimiter of an
7244 opening-delimiter that has already been parsed. Otherwise the
7245 close-delimiter will probably appear to be unmatched, and generate another,
7246 spurious error message:
7249 primary: '(' expr ')'
7255 Error recovery strategies are necessarily guesses. When they guess wrong,
7256 one syntax error often leads to another. In the above example, the error
7257 recovery rule guesses that an error is due to bad input within one
7258 @code{stmnt}. Suppose that instead a spurious semicolon is inserted in the
7259 middle of a valid @code{stmnt}. After the error recovery rule recovers
7260 from the first error, another syntax error will be found straightaway,
7261 since the text following the spurious semicolon is also an invalid
7264 To prevent an outpouring of error messages, the parser will output no error
7265 message for another syntax error that happens shortly after the first; only
7266 after three consecutive input tokens have been successfully shifted will
7267 error messages resume.
7269 Note that rules which accept the @code{error} token may have actions, just
7270 as any other rules can.
7273 You can make error messages resume immediately by using the macro
7274 @code{yyerrok} in an action. If you do this in the error rule's action, no
7275 error messages will be suppressed. This macro requires no arguments;
7276 @samp{yyerrok;} is a valid C statement.
7279 The previous lookahead token is reanalyzed immediately after an error. If
7280 this is unacceptable, then the macro @code{yyclearin} may be used to clear
7281 this token. Write the statement @samp{yyclearin;} in the error rule's
7283 @xref{Action Features, ,Special Features for Use in Actions}.
7285 For example, suppose that on a syntax error, an error handling routine is
7286 called that advances the input stream to some point where parsing should
7287 once again commence. The next symbol returned by the lexical scanner is
7288 probably correct. The previous lookahead token ought to be discarded
7289 with @samp{yyclearin;}.
7291 @vindex YYRECOVERING
7292 The expression @code{YYRECOVERING ()} yields 1 when the parser
7293 is recovering from a syntax error, and 0 otherwise.
7294 Syntax error diagnostics are suppressed while recovering from a syntax
7297 @node Context Dependency
7298 @chapter Handling Context Dependencies
7300 The Bison paradigm is to parse tokens first, then group them into larger
7301 syntactic units. In many languages, the meaning of a token is affected by
7302 its context. Although this violates the Bison paradigm, certain techniques
7303 (known as @dfn{kludges}) may enable you to write Bison parsers for such
7307 * Semantic Tokens:: Token parsing can depend on the semantic context.
7308 * Lexical Tie-ins:: Token parsing can depend on the syntactic context.
7309 * Tie-in Recovery:: Lexical tie-ins have implications for how
7310 error recovery rules must be written.
7313 (Actually, ``kludge'' means any technique that gets its job done but is
7314 neither clean nor robust.)
7316 @node Semantic Tokens
7317 @section Semantic Info in Token Types
7319 The C language has a context dependency: the way an identifier is used
7320 depends on what its current meaning is. For example, consider this:
7326 This looks like a function call statement, but if @code{foo} is a typedef
7327 name, then this is actually a declaration of @code{x}. How can a Bison
7328 parser for C decide how to parse this input?
7330 The method used in @acronym{GNU} C is to have two different token types,
7331 @code{IDENTIFIER} and @code{TYPENAME}. When @code{yylex} finds an
7332 identifier, it looks up the current declaration of the identifier in order
7333 to decide which token type to return: @code{TYPENAME} if the identifier is
7334 declared as a typedef, @code{IDENTIFIER} otherwise.
7336 The grammar rules can then express the context dependency by the choice of
7337 token type to recognize. @code{IDENTIFIER} is accepted as an expression,
7338 but @code{TYPENAME} is not. @code{TYPENAME} can start a declaration, but
7339 @code{IDENTIFIER} cannot. In contexts where the meaning of the identifier
7340 is @emph{not} significant, such as in declarations that can shadow a
7341 typedef name, either @code{TYPENAME} or @code{IDENTIFIER} is
7342 accepted---there is one rule for each of the two token types.
7344 This technique is simple to use if the decision of which kinds of
7345 identifiers to allow is made at a place close to where the identifier is
7346 parsed. But in C this is not always so: C allows a declaration to
7347 redeclare a typedef name provided an explicit type has been specified
7351 typedef int foo, bar;
7354 static bar (bar); /* @r{redeclare @code{bar} as static variable} */
7355 extern foo foo (foo); /* @r{redeclare @code{foo} as function} */
7360 Unfortunately, the name being declared is separated from the declaration
7361 construct itself by a complicated syntactic structure---the ``declarator''.
7363 As a result, part of the Bison parser for C needs to be duplicated, with
7364 all the nonterminal names changed: once for parsing a declaration in
7365 which a typedef name can be redefined, and once for parsing a
7366 declaration in which that can't be done. Here is a part of the
7367 duplication, with actions omitted for brevity:
7371 declarator maybeasm '='
7373 | declarator maybeasm
7377 notype_declarator maybeasm '='
7379 | notype_declarator maybeasm
7384 Here @code{initdcl} can redeclare a typedef name, but @code{notype_initdcl}
7385 cannot. The distinction between @code{declarator} and
7386 @code{notype_declarator} is the same sort of thing.
7388 There is some similarity between this technique and a lexical tie-in
7389 (described next), in that information which alters the lexical analysis is
7390 changed during parsing by other parts of the program. The difference is
7391 here the information is global, and is used for other purposes in the
7392 program. A true lexical tie-in has a special-purpose flag controlled by
7393 the syntactic context.
7395 @node Lexical Tie-ins
7396 @section Lexical Tie-ins
7397 @cindex lexical tie-in
7399 One way to handle context-dependency is the @dfn{lexical tie-in}: a flag
7400 which is set by Bison actions, whose purpose is to alter the way tokens are
7403 For example, suppose we have a language vaguely like C, but with a special
7404 construct @samp{hex (@var{hex-expr})}. After the keyword @code{hex} comes
7405 an expression in parentheses in which all integers are hexadecimal. In
7406 particular, the token @samp{a1b} must be treated as an integer rather than
7407 as an identifier if it appears in that context. Here is how you can do it:
7414 void yyerror (char const *);
7428 @{ $$ = make_sum ($1, $3); @}
7442 Here we assume that @code{yylex} looks at the value of @code{hexflag}; when
7443 it is nonzero, all integers are parsed in hexadecimal, and tokens starting
7444 with letters are parsed as integers if possible.
7446 The declaration of @code{hexflag} shown in the prologue of the parser file
7447 is needed to make it accessible to the actions (@pxref{Prologue, ,The Prologue}).
7448 You must also write the code in @code{yylex} to obey the flag.
7450 @node Tie-in Recovery
7451 @section Lexical Tie-ins and Error Recovery
7453 Lexical tie-ins make strict demands on any error recovery rules you have.
7454 @xref{Error Recovery}.
7456 The reason for this is that the purpose of an error recovery rule is to
7457 abort the parsing of one construct and resume in some larger construct.
7458 For example, in C-like languages, a typical error recovery rule is to skip
7459 tokens until the next semicolon, and then start a new statement, like this:
7463 | IF '(' expr ')' stmt @{ @dots{} @}
7470 If there is a syntax error in the middle of a @samp{hex (@var{expr})}
7471 construct, this error rule will apply, and then the action for the
7472 completed @samp{hex (@var{expr})} will never run. So @code{hexflag} would
7473 remain set for the entire rest of the input, or until the next @code{hex}
7474 keyword, causing identifiers to be misinterpreted as integers.
7476 To avoid this problem the error recovery rule itself clears @code{hexflag}.
7478 There may also be an error recovery rule that works within expressions.
7479 For example, there could be a rule which applies within parentheses
7480 and skips to the close-parenthesis:
7492 If this rule acts within the @code{hex} construct, it is not going to abort
7493 that construct (since it applies to an inner level of parentheses within
7494 the construct). Therefore, it should not clear the flag: the rest of
7495 the @code{hex} construct should be parsed with the flag still in effect.
7497 What if there is an error recovery rule which might abort out of the
7498 @code{hex} construct or might not, depending on circumstances? There is no
7499 way you can write the action to determine whether a @code{hex} construct is
7500 being aborted or not. So if you are using a lexical tie-in, you had better
7501 make sure your error recovery rules are not of this kind. Each rule must
7502 be such that you can be sure that it always will, or always won't, have to
7505 @c ================================================== Debugging Your Parser
7508 @chapter Debugging Your Parser
7510 Developing a parser can be a challenge, especially if you don't
7511 understand the algorithm (@pxref{Algorithm, ,The Bison Parser
7512 Algorithm}). Even so, sometimes a detailed description of the automaton
7513 can help (@pxref{Understanding, , Understanding Your Parser}), or
7514 tracing the execution of the parser can give some insight on why it
7515 behaves improperly (@pxref{Tracing, , Tracing Your Parser}).
7518 * Understanding:: Understanding the structure of your parser.
7519 * Tracing:: Tracing the execution of your parser.
7523 @section Understanding Your Parser
7525 As documented elsewhere (@pxref{Algorithm, ,The Bison Parser Algorithm})
7526 Bison parsers are @dfn{shift/reduce automata}. In some cases (much more
7527 frequent than one would hope), looking at this automaton is required to
7528 tune or simply fix a parser. Bison provides two different
7529 representation of it, either textually or graphically (as a DOT file).
7531 The textual file is generated when the options @option{--report} or
7532 @option{--verbose} are specified, see @xref{Invocation, , Invoking
7533 Bison}. Its name is made by removing @samp{.tab.c} or @samp{.c} from
7534 the parser output file name, and adding @samp{.output} instead.
7535 Therefore, if the input file is @file{foo.y}, then the parser file is
7536 called @file{foo.tab.c} by default. As a consequence, the verbose
7537 output file is called @file{foo.output}.
7539 The following grammar file, @file{calc.y}, will be used in the sequel:
7556 @command{bison} reports:
7559 calc.y: warning: 1 nonterminal useless in grammar
7560 calc.y: warning: 1 rule useless in grammar
7561 calc.y:11.1-7: warning: nonterminal useless in grammar: useless
7562 calc.y:11.10-12: warning: rule useless in grammar: useless: STR
7563 calc.y: conflicts: 7 shift/reduce
7566 When given @option{--report=state}, in addition to @file{calc.tab.c}, it
7567 creates a file @file{calc.output} with contents detailed below. The
7568 order of the output and the exact presentation might vary, but the
7569 interpretation is the same.
7571 The first section includes details on conflicts that were solved thanks
7572 to precedence and/or associativity:
7575 Conflict in state 8 between rule 2 and token '+' resolved as reduce.
7576 Conflict in state 8 between rule 2 and token '-' resolved as reduce.
7577 Conflict in state 8 between rule 2 and token '*' resolved as shift.
7582 The next section lists states that still have conflicts.
7585 State 8 conflicts: 1 shift/reduce
7586 State 9 conflicts: 1 shift/reduce
7587 State 10 conflicts: 1 shift/reduce
7588 State 11 conflicts: 4 shift/reduce
7592 @cindex token, useless
7593 @cindex useless token
7594 @cindex nonterminal, useless
7595 @cindex useless nonterminal
7596 @cindex rule, useless
7597 @cindex useless rule
7598 The next section reports useless tokens, nonterminal and rules. Useless
7599 nonterminals and rules are removed in order to produce a smaller parser,
7600 but useless tokens are preserved, since they might be used by the
7601 scanner (note the difference between ``useless'' and ``unused''
7605 Nonterminals useless in grammar:
7608 Terminals unused in grammar:
7611 Rules useless in grammar:
7616 The next section reproduces the exact grammar that Bison used:
7622 0 5 $accept -> exp $end
7623 1 5 exp -> exp '+' exp
7624 2 6 exp -> exp '-' exp
7625 3 7 exp -> exp '*' exp
7626 4 8 exp -> exp '/' exp
7631 and reports the uses of the symbols:
7634 Terminals, with rules where they appear
7644 Nonterminals, with rules where they appear
7649 on left: 1 2 3 4 5, on right: 0 1 2 3 4
7654 @cindex pointed rule
7655 @cindex rule, pointed
7656 Bison then proceeds onto the automaton itself, describing each state
7657 with it set of @dfn{items}, also known as @dfn{pointed rules}. Each
7658 item is a production rule together with a point (marked by @samp{.})
7659 that the input cursor.
7664 $accept -> . exp $ (rule 0)
7666 NUM shift, and go to state 1
7671 This reads as follows: ``state 0 corresponds to being at the very
7672 beginning of the parsing, in the initial rule, right before the start
7673 symbol (here, @code{exp}). When the parser returns to this state right
7674 after having reduced a rule that produced an @code{exp}, the control
7675 flow jumps to state 2. If there is no such transition on a nonterminal
7676 symbol, and the lookahead is a @code{NUM}, then this token is shifted on
7677 the parse stack, and the control flow jumps to state 1. Any other
7678 lookahead triggers a syntax error.''
7680 @cindex core, item set
7681 @cindex item set core
7682 @cindex kernel, item set
7683 @cindex item set core
7684 Even though the only active rule in state 0 seems to be rule 0, the
7685 report lists @code{NUM} as a lookahead token because @code{NUM} can be
7686 at the beginning of any rule deriving an @code{exp}. By default Bison
7687 reports the so-called @dfn{core} or @dfn{kernel} of the item set, but if
7688 you want to see more detail you can invoke @command{bison} with
7689 @option{--report=itemset} to list all the items, include those that can
7695 $accept -> . exp $ (rule 0)
7696 exp -> . exp '+' exp (rule 1)
7697 exp -> . exp '-' exp (rule 2)
7698 exp -> . exp '*' exp (rule 3)
7699 exp -> . exp '/' exp (rule 4)
7700 exp -> . NUM (rule 5)
7702 NUM shift, and go to state 1
7713 exp -> NUM . (rule 5)
7715 $default reduce using rule 5 (exp)
7719 the rule 5, @samp{exp: NUM;}, is completed. Whatever the lookahead token
7720 (@samp{$default}), the parser will reduce it. If it was coming from
7721 state 0, then, after this reduction it will return to state 0, and will
7722 jump to state 2 (@samp{exp: go to state 2}).
7727 $accept -> exp . $ (rule 0)
7728 exp -> exp . '+' exp (rule 1)
7729 exp -> exp . '-' exp (rule 2)
7730 exp -> exp . '*' exp (rule 3)
7731 exp -> exp . '/' exp (rule 4)
7733 $ shift, and go to state 3
7734 '+' shift, and go to state 4
7735 '-' shift, and go to state 5
7736 '*' shift, and go to state 6
7737 '/' shift, and go to state 7
7741 In state 2, the automaton can only shift a symbol. For instance,
7742 because of the item @samp{exp -> exp . '+' exp}, if the lookahead if
7743 @samp{+}, it will be shifted on the parse stack, and the automaton
7744 control will jump to state 4, corresponding to the item @samp{exp -> exp
7745 '+' . exp}. Since there is no default action, any other token than
7746 those listed above will trigger a syntax error.
7748 @cindex accepting state
7749 The state 3 is named the @dfn{final state}, or the @dfn{accepting
7755 $accept -> exp $ . (rule 0)
7761 the initial rule is completed (the start symbol and the end
7762 of input were read), the parsing exits successfully.
7764 The interpretation of states 4 to 7 is straightforward, and is left to
7770 exp -> exp '+' . exp (rule 1)
7772 NUM shift, and go to state 1
7778 exp -> exp '-' . exp (rule 2)
7780 NUM shift, and go to state 1
7786 exp -> exp '*' . exp (rule 3)
7788 NUM shift, and go to state 1
7794 exp -> exp '/' . exp (rule 4)
7796 NUM shift, and go to state 1
7801 As was announced in beginning of the report, @samp{State 8 conflicts:
7807 exp -> exp . '+' exp (rule 1)
7808 exp -> exp '+' exp . (rule 1)
7809 exp -> exp . '-' exp (rule 2)
7810 exp -> exp . '*' exp (rule 3)
7811 exp -> exp . '/' exp (rule 4)
7813 '*' shift, and go to state 6
7814 '/' shift, and go to state 7
7816 '/' [reduce using rule 1 (exp)]
7817 $default reduce using rule 1 (exp)
7820 Indeed, there are two actions associated to the lookahead @samp{/}:
7821 either shifting (and going to state 7), or reducing rule 1. The
7822 conflict means that either the grammar is ambiguous, or the parser lacks
7823 information to make the right decision. Indeed the grammar is
7824 ambiguous, as, since we did not specify the precedence of @samp{/}, the
7825 sentence @samp{NUM + NUM / NUM} can be parsed as @samp{NUM + (NUM /
7826 NUM)}, which corresponds to shifting @samp{/}, or as @samp{(NUM + NUM) /
7827 NUM}, which corresponds to reducing rule 1.
7829 Because in deterministic parsing a single decision can be made, Bison
7830 arbitrarily chose to disable the reduction, see @ref{Shift/Reduce, ,
7831 Shift/Reduce Conflicts}. Discarded actions are reported in between
7834 Note that all the previous states had a single possible action: either
7835 shifting the next token and going to the corresponding state, or
7836 reducing a single rule. In the other cases, i.e., when shifting
7837 @emph{and} reducing is possible or when @emph{several} reductions are
7838 possible, the lookahead is required to select the action. State 8 is
7839 one such state: if the lookahead is @samp{*} or @samp{/} then the action
7840 is shifting, otherwise the action is reducing rule 1. In other words,
7841 the first two items, corresponding to rule 1, are not eligible when the
7842 lookahead token is @samp{*}, since we specified that @samp{*} has higher
7843 precedence than @samp{+}. More generally, some items are eligible only
7844 with some set of possible lookahead tokens. When run with
7845 @option{--report=lookahead}, Bison specifies these lookahead tokens:
7850 exp -> exp . '+' exp (rule 1)
7851 exp -> exp '+' exp . [$, '+', '-', '/'] (rule 1)
7852 exp -> exp . '-' exp (rule 2)
7853 exp -> exp . '*' exp (rule 3)
7854 exp -> exp . '/' exp (rule 4)
7856 '*' shift, and go to state 6
7857 '/' shift, and go to state 7
7859 '/' [reduce using rule 1 (exp)]
7860 $default reduce using rule 1 (exp)
7863 The remaining states are similar:
7868 exp -> exp . '+' exp (rule 1)
7869 exp -> exp . '-' exp (rule 2)
7870 exp -> exp '-' exp . (rule 2)
7871 exp -> exp . '*' exp (rule 3)
7872 exp -> exp . '/' exp (rule 4)
7874 '*' shift, and go to state 6
7875 '/' shift, and go to state 7
7877 '/' [reduce using rule 2 (exp)]
7878 $default reduce using rule 2 (exp)
7882 exp -> exp . '+' exp (rule 1)
7883 exp -> exp . '-' exp (rule 2)
7884 exp -> exp . '*' exp (rule 3)
7885 exp -> exp '*' exp . (rule 3)
7886 exp -> exp . '/' exp (rule 4)
7888 '/' shift, and go to state 7
7890 '/' [reduce using rule 3 (exp)]
7891 $default reduce using rule 3 (exp)
7895 exp -> exp . '+' exp (rule 1)
7896 exp -> exp . '-' exp (rule 2)
7897 exp -> exp . '*' exp (rule 3)
7898 exp -> exp . '/' exp (rule 4)
7899 exp -> exp '/' exp . (rule 4)
7901 '+' shift, and go to state 4
7902 '-' shift, and go to state 5
7903 '*' shift, and go to state 6
7904 '/' shift, and go to state 7
7906 '+' [reduce using rule 4 (exp)]
7907 '-' [reduce using rule 4 (exp)]
7908 '*' [reduce using rule 4 (exp)]
7909 '/' [reduce using rule 4 (exp)]
7910 $default reduce using rule 4 (exp)
7914 Observe that state 11 contains conflicts not only due to the lack of
7915 precedence of @samp{/} with respect to @samp{+}, @samp{-}, and
7916 @samp{*}, but also because the
7917 associativity of @samp{/} is not specified.
7921 @section Tracing Your Parser
7924 @cindex tracing the parser
7926 If a Bison grammar compiles properly but doesn't do what you want when it
7927 runs, the @code{yydebug} parser-trace feature can help you figure out why.
7929 There are several means to enable compilation of trace facilities:
7932 @item the macro @code{YYDEBUG}
7934 Define the macro @code{YYDEBUG} to a nonzero value when you compile the
7935 parser. This is compliant with @acronym{POSIX} Yacc. You could use
7936 @samp{-DYYDEBUG=1} as a compiler option or you could put @samp{#define
7937 YYDEBUG 1} in the prologue of the grammar file (@pxref{Prologue, , The
7940 @item the option @option{-t}, @option{--debug}
7941 Use the @samp{-t} option when you run Bison (@pxref{Invocation,
7942 ,Invoking Bison}). This is @acronym{POSIX} compliant too.
7944 @item the directive @samp{%debug}
7946 Add the @code{%debug} directive (@pxref{Decl Summary, ,Bison Declaration
7947 Summary}). This Bison extension is maintained for backward
7948 compatibility with previous versions of Bison.
7950 @item the variable @samp{parse.trace}
7951 @findex %define parse.trace
7952 Add the @samp{%define parse.trace} directive (@pxref{Decl Summary,
7953 ,Bison Declaration Summary}), or pass the @option{-Dparse.trace} option
7954 (@pxref{Bison Options}). This is a Bison extension, which is especially
7955 useful for languages that don't use a preprocessor. Unless
7956 @acronym{POSIX} and Yacc portability matter to you, this is the
7960 We suggest that you always enable the trace option so that debugging is
7963 The trace facility outputs messages with macro calls of the form
7964 @code{YYFPRINTF (stderr, @var{format}, @var{args})} where
7965 @var{format} and @var{args} are the usual @code{printf} format and variadic
7966 arguments. If you define @code{YYDEBUG} to a nonzero value but do not
7967 define @code{YYFPRINTF}, @code{<stdio.h>} is automatically included
7968 and @code{YYFPRINTF} is defined to @code{fprintf}.
7970 Once you have compiled the program with trace facilities, the way to
7971 request a trace is to store a nonzero value in the variable @code{yydebug}.
7972 You can do this by making the C code do it (in @code{main}, perhaps), or
7973 you can alter the value with a C debugger.
7975 Each step taken by the parser when @code{yydebug} is nonzero produces a
7976 line or two of trace information, written on @code{stderr}. The trace
7977 messages tell you these things:
7981 Each time the parser calls @code{yylex}, what kind of token was read.
7984 Each time a token is shifted, the depth and complete contents of the
7985 state stack (@pxref{Parser States}).
7988 Each time a rule is reduced, which rule it is, and the complete contents
7989 of the state stack afterward.
7992 To make sense of this information, it helps to refer to the listing file
7993 produced by the Bison @samp{-v} option (@pxref{Invocation, ,Invoking
7994 Bison}). This file shows the meaning of each state in terms of
7995 positions in various rules, and also what each state will do with each
7996 possible input token. As you read the successive trace messages, you
7997 can see that the parser is functioning according to its specification in
7998 the listing file. Eventually you will arrive at the place where
7999 something undesirable happens, and you will see which parts of the
8000 grammar are to blame.
8002 The parser file is a C program and you can use C debuggers on it, but it's
8003 not easy to interpret what it is doing. The parser function is a
8004 finite-state machine interpreter, and aside from the actions it executes
8005 the same code over and over. Only the values of variables show where in
8006 the grammar it is working.
8009 The debugging information normally gives the token type of each token
8010 read, but not its semantic value. You can optionally define a macro
8011 named @code{YYPRINT} to provide a way to print the value. If you define
8012 @code{YYPRINT}, it should take three arguments. The parser will pass a
8013 standard I/O stream, the numeric code for the token type, and the token
8014 value (from @code{yylval}).
8016 Here is an example of @code{YYPRINT} suitable for the multi-function
8017 calculator (@pxref{Mfcalc Declarations, ,Declarations for @code{mfcalc}}):
8021 static void print_token_value (FILE *, int, YYSTYPE);
8022 #define YYPRINT(file, type, value) print_token_value (file, type, value)
8025 @dots{} %% @dots{} %% @dots{}
8028 print_token_value (FILE *file, int type, YYSTYPE value)
8031 fprintf (file, "%s", value.tptr->name);
8032 else if (type == NUM)
8033 fprintf (file, "%d", value.val);
8037 @c ================================================= Invoking Bison
8040 @chapter Invoking Bison
8041 @cindex invoking Bison
8042 @cindex Bison invocation
8043 @cindex options for invoking Bison
8045 The usual way to invoke Bison is as follows:
8051 Here @var{infile} is the grammar file name, which usually ends in
8052 @samp{.y}. The parser file's name is made by replacing the @samp{.y}
8053 with @samp{.tab.c} and removing any leading directory. Thus, the
8054 @samp{bison foo.y} file name yields
8055 @file{foo.tab.c}, and the @samp{bison hack/foo.y} file name yields
8056 @file{foo.tab.c}. It's also possible, in case you are writing
8057 C++ code instead of C in your grammar file, to name it @file{foo.ypp}
8058 or @file{foo.y++}. Then, the output files will take an extension like
8059 the given one as input (respectively @file{foo.tab.cpp} and
8060 @file{foo.tab.c++}).
8061 This feature takes effect with all options that manipulate file names like
8062 @samp{-o} or @samp{-d}.
8067 bison -d @var{infile.yxx}
8070 will produce @file{infile.tab.cxx} and @file{infile.tab.hxx}, and
8073 bison -d -o @var{output.c++} @var{infile.y}
8076 will produce @file{output.c++} and @file{outfile.h++}.
8078 For compatibility with @acronym{POSIX}, the standard Bison
8079 distribution also contains a shell script called @command{yacc} that
8080 invokes Bison with the @option{-y} option.
8083 * Bison Options:: All the options described in detail,
8084 in alphabetical order by short options.
8085 * Option Cross Key:: Alphabetical list of long options.
8086 * Yacc Library:: Yacc-compatible @code{yylex} and @code{main}.
8090 @section Bison Options
8092 Bison supports both traditional single-letter options and mnemonic long
8093 option names. Long option names are indicated with @samp{--} instead of
8094 @samp{-}. Abbreviations for option names are allowed as long as they
8095 are unique. When a long option takes an argument, like
8096 @samp{--file-prefix}, connect the option name and the argument with
8099 Here is a list of options that can be used with Bison, alphabetized by
8100 short option. It is followed by a cross key alphabetized by long
8103 @c Please, keep this ordered as in `bison --help'.
8109 Print a summary of the command-line options to Bison and exit.
8113 Print the version number of Bison and exit.
8115 @item --print-localedir
8116 Print the name of the directory containing locale-dependent data.
8118 @item --print-datadir
8119 Print the name of the directory containing skeletons and XSLT.
8123 Act more like the traditional Yacc command. This can cause
8124 different diagnostics to be generated, and may change behavior in
8125 other minor ways. Most importantly, imitate Yacc's output
8126 file name conventions, so that the parser output file is called
8127 @file{y.tab.c}, and the other outputs are called @file{y.output} and
8129 Also, if generating a deterministic parser in C, generate @code{#define}
8130 statements in addition to an @code{enum} to associate token numbers with token
8132 Thus, the following shell script can substitute for Yacc, and the Bison
8133 distribution contains such a script for compatibility with @acronym{POSIX}:
8140 The @option{-y}/@option{--yacc} option is intended for use with
8141 traditional Yacc grammars. If your grammar uses a Bison extension
8142 like @samp{%glr-parser}, Bison might not be Yacc-compatible even if
8143 this option is specified.
8145 @item -W [@var{category}]
8146 @itemx --warnings[=@var{category}]
8147 Output warnings falling in @var{category}. @var{category} can be one
8150 @item midrule-values
8151 Warn about mid-rule values that are set but not used within any of the actions
8153 For example, warn about unused @code{$2} in:
8156 exp: '1' @{ $$ = 1; @} '+' exp @{ $$ = $1 + $4; @};
8159 Also warn about mid-rule values that are used but not set.
8160 For example, warn about unset @code{$$} in the mid-rule action in:
8163 exp: '1' @{ $1 = 1; @} '+' exp @{ $$ = $2 + $4; @};
8166 These warnings are not enabled by default since they sometimes prove to
8167 be false alarms in existing grammars employing the Yacc constructs
8168 @code{$0} or @code{$-@var{n}} (where @var{n} is some positive integer).
8172 Incompatibilities with @acronym{POSIX} Yacc.
8177 Turn off all the warnings.
8179 Treat warnings as errors.
8182 A category can be turned off by prefixing its name with @samp{no-}. For
8183 instance, @option{-Wno-syntax} will hide the warnings about unused
8193 In the parser file, define the macro @code{YYDEBUG} to 1 if it is not
8194 already defined, so that the debugging facilities are compiled.
8195 @xref{Tracing, ,Tracing Your Parser}.
8197 @item -D @var{name}[=@var{value}]
8198 @itemx --define=@var{name}[=@var{value}]
8199 @itemx -F @var{name}[=@var{value}]
8200 @itemx --force-define=@var{name}[=@var{value}]
8201 Each of these is equivalent to @samp{%define @var{name} "@var{value}"}
8202 (@pxref{Decl Summary, ,%define}) except that Bison processes multiple
8203 definitions for the same @var{name} as follows:
8207 Bison quietly ignores all command-line definitions for @var{name} except
8210 If that command-line definition is specified by a @code{-D} or
8211 @code{--define}, Bison reports an error for any @code{%define}
8212 definition for @var{name}.
8214 If that command-line definition is specified by a @code{-F} or
8215 @code{--force-define} instead, Bison quietly ignores all @code{%define}
8216 definitions for @var{name}.
8218 Otherwise, Bison reports an error if there are multiple @code{%define}
8219 definitions for @var{name}.
8222 You should avoid using @code{-F} and @code{--force-define} in your
8223 makefiles unless you are confident that it is safe to quietly ignore any
8224 conflicting @code{%define} that may be added to the grammar file.
8226 @item -L @var{language}
8227 @itemx --language=@var{language}
8228 Specify the programming language for the generated parser, as if
8229 @code{%language} was specified (@pxref{Decl Summary, , Bison Declaration
8230 Summary}). Currently supported languages include C, C++, and Java.
8231 @var{language} is case-insensitive.
8233 This option is experimental and its effect may be modified in future
8237 Pretend that @code{%locations} was specified. @xref{Decl Summary}.
8239 @item -p @var{prefix}
8240 @itemx --name-prefix=@var{prefix}
8241 Pretend that @code{%name-prefix "@var{prefix}"} was specified.
8242 @xref{Decl Summary}.
8246 Don't put any @code{#line} preprocessor commands in the parser file.
8247 Ordinarily Bison puts them in the parser file so that the C compiler
8248 and debuggers will associate errors with your source file, the
8249 grammar file. This option causes them to associate errors with the
8250 parser file, treating it as an independent source file in its own right.
8253 @itemx --skeleton=@var{file}
8254 Specify the skeleton to use, similar to @code{%skeleton}
8255 (@pxref{Decl Summary, , Bison Declaration Summary}).
8257 @c You probably don't need this option unless you are developing Bison.
8258 @c You should use @option{--language} if you want to specify the skeleton for a
8259 @c different language, because it is clearer and because it will always
8260 @c choose the correct skeleton for non-deterministic or push parsers.
8262 If @var{file} does not contain a @code{/}, @var{file} is the name of a skeleton
8263 file in the Bison installation directory.
8264 If it does, @var{file} is an absolute file name or a file name relative to the
8265 current working directory.
8266 This is similar to how most shells resolve commands.
8269 @itemx --token-table
8270 Pretend that @code{%token-table} was specified. @xref{Decl Summary}.
8277 @item --defines[=@var{file}]
8278 Pretend that @code{%defines} was specified, i.e., write an extra output
8279 file containing macro definitions for the token type names defined in
8280 the grammar, as well as a few other declarations. @xref{Decl Summary}.
8283 This is the same as @code{--defines} except @code{-d} does not accept a
8284 @var{file} argument since POSIX Yacc requires that @code{-d} can be bundled
8285 with other short options.
8287 @item -b @var{file-prefix}
8288 @itemx --file-prefix=@var{prefix}
8289 Pretend that @code{%file-prefix} was specified, i.e., specify prefix to use
8290 for all Bison output file names. @xref{Decl Summary}.
8292 @item -r @var{things}
8293 @itemx --report=@var{things}
8294 Write an extra output file containing verbose description of the comma
8295 separated list of @var{things} among:
8299 Description of the grammar, conflicts (resolved and unresolved), and
8303 Implies @code{state} and augments the description of the automaton with
8304 each rule's lookahead set.
8307 Implies @code{state} and augments the description of the automaton with
8308 the full set of items for each state, instead of its core only.
8311 @item --report-file=@var{file}
8312 Specify the @var{file} for the verbose description.
8316 Pretend that @code{%verbose} was specified, i.e., write an extra output
8317 file containing verbose descriptions of the grammar and
8318 parser. @xref{Decl Summary}.
8321 @itemx --output=@var{file}
8322 Specify the @var{file} for the parser file.
8324 The other output files' names are constructed from @var{file} as
8325 described under the @samp{-v} and @samp{-d} options.
8327 @item -g [@var{file}]
8328 @itemx --graph[=@var{file}]
8329 Output a graphical representation of the parser's
8330 automaton computed by Bison, in @uref{http://www.graphviz.org/, Graphviz}
8331 @uref{http://www.graphviz.org/doc/info/lang.html, @acronym{DOT}} format.
8332 @code{@var{file}} is optional.
8333 If omitted and the grammar file is @file{foo.y}, the output file will be
8336 @item -x [@var{file}]
8337 @itemx --xml[=@var{file}]
8338 Output an XML report of the parser's automaton computed by Bison.
8339 @code{@var{file}} is optional.
8340 If omitted and the grammar file is @file{foo.y}, the output file will be
8342 (The current XML schema is experimental and may evolve.
8343 More user feedback will help to stabilize it.)
8346 @node Option Cross Key
8347 @section Option Cross Key
8349 Here is a list of options, alphabetized by long option, to help you find
8350 the corresponding short option and directive.
8352 @multitable {@option{--force-define=@var{name}[=@var{value}]}} {@option{-F @var{name}[=@var{value}]}} {@code{%nondeterministic-parser}}
8353 @headitem Long Option @tab Short Option @tab Bison Directive
8354 @include cross-options.texi
8358 @section Yacc Library
8360 The Yacc library contains default implementations of the
8361 @code{yyerror} and @code{main} functions. These default
8362 implementations are normally not useful, but @acronym{POSIX} requires
8363 them. To use the Yacc library, link your program with the
8364 @option{-ly} option. Note that Bison's implementation of the Yacc
8365 library is distributed under the terms of the @acronym{GNU} General
8366 Public License (@pxref{Copying}).
8368 If you use the Yacc library's @code{yyerror} function, you should
8369 declare @code{yyerror} as follows:
8372 int yyerror (char const *);
8375 Bison ignores the @code{int} value returned by this @code{yyerror}.
8376 If you use the Yacc library's @code{main} function, your
8377 @code{yyparse} function should have the following type signature:
8383 @c ================================================= C++ Bison
8385 @node Other Languages
8386 @chapter Parsers Written In Other Languages
8389 * C++ Parsers:: The interface to generate C++ parser classes
8390 * Java Parsers:: The interface to generate Java parser classes
8394 @section C++ Parsers
8397 * C++ Bison Interface:: Asking for C++ parser generation
8398 * C++ Semantic Values:: %union vs. C++
8399 * C++ Location Values:: The position and location classes
8400 * C++ Parser Interface:: Instantiating and running the parser
8401 * C++ Scanner Interface:: Exchanges between yylex and parse
8402 * A Complete C++ Example:: Demonstrating their use
8405 @node C++ Bison Interface
8406 @subsection C++ Bison Interface
8407 @c - %skeleton "lalr1.cc"
8411 The C++ deterministic parser is selected using the skeleton directive,
8412 @samp{%skeleton "lalr1.c"}, or the synonymous command-line option
8413 @option{--skeleton=lalr1.c}.
8414 @xref{Decl Summary}.
8416 When run, @command{bison} will create several entities in the @samp{yy}
8418 @findex %define api.namespace
8419 Use the @samp{%define api.namespace} directive to change the namespace
8422 The various classes are generated in the following files:
8427 The definition of the classes @code{position} and @code{location},
8428 used for location tracking. @xref{C++ Location Values}.
8431 An auxiliary class @code{stack} used by the parser.
8434 @itemx @var{file}.cc
8435 (Assuming the extension of the input file was @samp{.yy}.) The
8436 declaration and implementation of the C++ parser class. The basename
8437 and extension of these two files follow the same rules as with regular C
8438 parsers (@pxref{Invocation}).
8440 The header is @emph{mandatory}; you must either pass
8441 @option{-d}/@option{--defines} to @command{bison}, or use the
8442 @samp{%defines} directive.
8445 All these files are documented using Doxygen; run @command{doxygen}
8446 for a complete and accurate documentation.
8448 @node C++ Semantic Values
8449 @subsection C++ Semantic Values
8450 @c - No objects in unions
8452 @c - Printer and destructor
8454 The @code{%union} directive works as for C, see @ref{Union Decl, ,The
8455 Collection of Value Types}. In particular it produces a genuine
8456 @code{union}@footnote{In the future techniques to allow complex types
8457 within pseudo-unions (similar to Boost variants) might be implemented to
8458 alleviate these issues.}, which have a few specific features in C++.
8461 The type @code{YYSTYPE} is defined but its use is discouraged: rather
8462 you should refer to the parser's encapsulated type
8463 @code{yy::parser::semantic_type}.
8465 Non POD (Plain Old Data) types cannot be used. C++ forbids any
8466 instance of classes with constructors in unions: only @emph{pointers}
8467 to such objects are allowed.
8470 Because objects have to be stored via pointers, memory is not
8471 reclaimed automatically: using the @code{%destructor} directive is the
8472 only means to avoid leaks. @xref{Destructor Decl, , Freeing Discarded
8476 @node C++ Location Values
8477 @subsection C++ Location Values
8481 @c - %define filename_type "const symbol::Symbol"
8483 When the directive @code{%locations} is used, the C++ parser supports
8484 location tracking, see @ref{Locations, , Locations Overview}. Two
8485 auxiliary classes define a @code{position}, a single point in a file,
8486 and a @code{location}, a range composed of a pair of
8487 @code{position}s (possibly spanning several files).
8489 @deftypemethod {position} {std::string*} file
8490 The name of the file. It will always be handled as a pointer, the
8491 parser will never duplicate nor deallocate it. As an experimental
8492 feature you may change it to @samp{@var{type}*} using @samp{%define
8493 filename_type "@var{type}"}.
8496 @deftypemethod {position} {unsigned int} line
8497 The line, starting at 1.
8500 @deftypemethod {position} {unsigned int} lines (int @var{height} = 1)
8501 Advance by @var{height} lines, resetting the column number.
8504 @deftypemethod {position} {unsigned int} column
8505 The column, starting at 0.
8508 @deftypemethod {position} {unsigned int} columns (int @var{width} = 1)
8509 Advance by @var{width} columns, without changing the line number.
8512 @deftypemethod {position} {position&} operator+= (position& @var{pos}, int @var{width})
8513 @deftypemethodx {position} {position} operator+ (const position& @var{pos}, int @var{width})
8514 @deftypemethodx {position} {position&} operator-= (const position& @var{pos}, int @var{width})
8515 @deftypemethodx {position} {position} operator- (position& @var{pos}, int @var{width})
8516 Various forms of syntactic sugar for @code{columns}.
8519 @deftypemethod {position} {position} operator<< (std::ostream @var{o}, const position& @var{p})
8520 Report @var{p} on @var{o} like this:
8521 @samp{@var{file}:@var{line}.@var{column}}, or
8522 @samp{@var{line}.@var{column}} if @var{file} is null.
8525 @deftypemethod {location} {position} begin
8526 @deftypemethodx {location} {position} end
8527 The first, inclusive, position of the range, and the first beyond.
8530 @deftypemethod {location} {unsigned int} columns (int @var{width} = 1)
8531 @deftypemethodx {location} {unsigned int} lines (int @var{height} = 1)
8532 Advance the @code{end} position.
8535 @deftypemethod {location} {location} operator+ (const location& @var{begin}, const location& @var{end})
8536 @deftypemethodx {location} {location} operator+ (const location& @var{begin}, int @var{width})
8537 @deftypemethodx {location} {location} operator+= (const location& @var{loc}, int @var{width})
8538 Various forms of syntactic sugar.
8541 @deftypemethod {location} {void} step ()
8542 Move @code{begin} onto @code{end}.
8546 @node C++ Parser Interface
8547 @subsection C++ Parser Interface
8548 @c - define parser_class_name
8550 @c - parse, error, set_debug_level, debug_level, set_debug_stream,
8552 @c - Reporting errors
8554 The output files @file{@var{output}.hh} and @file{@var{output}.cc}
8555 declare and define the parser class in the namespace @code{yy}. The
8556 class name defaults to @code{parser}, but may be changed using
8557 @samp{%define parser_class_name "@var{name}"}. The interface of
8558 this class is detailed below. It can be extended using the
8559 @code{%parse-param} feature: its semantics is slightly changed since
8560 it describes an additional member of the parser class, and an
8561 additional argument for its constructor.
8563 @defcv {Type} {parser} {semantic_value_type}
8564 @defcvx {Type} {parser} {location_value_type}
8565 The types for semantics value and locations.
8568 @deftypemethod {parser} {} parser (@var{type1} @var{arg1}, ...)
8569 Build a new parser object. There are no arguments by default, unless
8570 @samp{%parse-param @{@var{type1} @var{arg1}@}} was used.
8573 @deftypemethod {parser} {int} parse ()
8574 Run the syntactic analysis, and return 0 on success, 1 otherwise.
8577 @deftypemethod {parser} {std::ostream&} debug_stream ()
8578 @deftypemethodx {parser} {void} set_debug_stream (std::ostream& @var{o})
8579 Get or set the stream used for tracing the parsing. It defaults to
8583 @deftypemethod {parser} {debug_level_type} debug_level ()
8584 @deftypemethodx {parser} {void} set_debug_level (debug_level @var{l})
8585 Get or set the tracing level. Currently its value is either 0, no trace,
8586 or nonzero, full tracing.
8589 @deftypemethod {parser} {void} error (const location_type& @var{l}, const std::string& @var{m})
8590 The definition for this member function must be supplied by the user:
8591 the parser uses it to report a parser error occurring at @var{l},
8592 described by @var{m}.
8596 @node C++ Scanner Interface
8597 @subsection C++ Scanner Interface
8598 @c - prefix for yylex.
8599 @c - Pure interface to yylex
8602 The parser invokes the scanner by calling @code{yylex}. Contrary to C
8603 parsers, C++ parsers are always pure: there is no point in using the
8604 @samp{%define api.pure} directive. Therefore the interface is as follows.
8606 @deftypemethod {parser} {int} yylex (semantic_value_type& @var{yylval}, location_type& @var{yylloc}, @var{type1} @var{arg1}, ...)
8607 Return the next token. Its type is the return value, its semantic
8608 value and location being @var{yylval} and @var{yylloc}. Invocations of
8609 @samp{%lex-param @{@var{type1} @var{arg1}@}} yield additional arguments.
8613 @node A Complete C++ Example
8614 @subsection A Complete C++ Example
8616 This section demonstrates the use of a C++ parser with a simple but
8617 complete example. This example should be available on your system,
8618 ready to compile, in the directory @dfn{../bison/examples/calc++}. It
8619 focuses on the use of Bison, therefore the design of the various C++
8620 classes is very naive: no accessors, no encapsulation of members etc.
8621 We will use a Lex scanner, and more precisely, a Flex scanner, to
8622 demonstrate the various interaction. A hand written scanner is
8623 actually easier to interface with.
8626 * Calc++ --- C++ Calculator:: The specifications
8627 * Calc++ Parsing Driver:: An active parsing context
8628 * Calc++ Parser:: A parser class
8629 * Calc++ Scanner:: A pure C++ Flex scanner
8630 * Calc++ Top Level:: Conducting the band
8633 @node Calc++ --- C++ Calculator
8634 @subsubsection Calc++ --- C++ Calculator
8636 Of course the grammar is dedicated to arithmetics, a single
8637 expression, possibly preceded by variable assignments. An
8638 environment containing possibly predefined variables such as
8639 @code{one} and @code{two}, is exchanged with the parser. An example
8640 of valid input follows.
8644 seven := one + two * three
8648 @node Calc++ Parsing Driver
8649 @subsubsection Calc++ Parsing Driver
8651 @c - A place to store error messages
8652 @c - A place for the result
8654 To support a pure interface with the parser (and the scanner) the
8655 technique of the ``parsing context'' is convenient: a structure
8656 containing all the data to exchange. Since, in addition to simply
8657 launch the parsing, there are several auxiliary tasks to execute (open
8658 the file for parsing, instantiate the parser etc.), we recommend
8659 transforming the simple parsing context structure into a fully blown
8660 @dfn{parsing driver} class.
8662 The declaration of this driver class, @file{calc++-driver.hh}, is as
8663 follows. The first part includes the CPP guard and imports the
8664 required standard library components, and the declaration of the parser
8667 @comment file: calc++-driver.hh
8669 #ifndef CALCXX_DRIVER_HH
8670 # define CALCXX_DRIVER_HH
8673 # include "calc++-parser.hh"
8678 Then comes the declaration of the scanning function. Flex expects
8679 the signature of @code{yylex} to be defined in the macro
8680 @code{YY_DECL}, and the C++ parser expects it to be declared. We can
8681 factor both as follows.
8683 @comment file: calc++-driver.hh
8685 // Tell Flex the lexer's prototype ...
8687 yy::calcxx_parser::token_type \
8688 yylex (yy::calcxx_parser::semantic_type* yylval, \
8689 yy::calcxx_parser::location_type* yylloc, \
8690 calcxx_driver& driver)
8691 // ... and declare it for the parser's sake.
8696 The @code{calcxx_driver} class is then declared with its most obvious
8699 @comment file: calc++-driver.hh
8701 // Conducting the whole scanning and parsing of Calc++.
8706 virtual ~calcxx_driver ();
8708 std::map<std::string, int> variables;
8714 To encapsulate the coordination with the Flex scanner, it is useful to
8715 have two members function to open and close the scanning phase.
8717 @comment file: calc++-driver.hh
8719 // Handling the scanner.
8722 bool trace_scanning;
8726 Similarly for the parser itself.
8728 @comment file: calc++-driver.hh
8730 // Run the parser. Return 0 on success.
8731 int parse (const std::string& f);
8737 To demonstrate pure handling of parse errors, instead of simply
8738 dumping them on the standard error output, we will pass them to the
8739 compiler driver using the following two member functions. Finally, we
8740 close the class declaration and CPP guard.
8742 @comment file: calc++-driver.hh
8745 void error (const yy::location& l, const std::string& m);
8746 void error (const std::string& m);
8748 #endif // ! CALCXX_DRIVER_HH
8751 The implementation of the driver is straightforward. The @code{parse}
8752 member function deserves some attention. The @code{error} functions
8753 are simple stubs, they should actually register the located error
8754 messages and set error state.
8756 @comment file: calc++-driver.cc
8758 #include "calc++-driver.hh"
8759 #include "calc++-parser.hh"
8761 calcxx_driver::calcxx_driver ()
8762 : trace_scanning (false), trace_parsing (false)
8764 variables["one"] = 1;
8765 variables["two"] = 2;
8768 calcxx_driver::~calcxx_driver ()
8773 calcxx_driver::parse (const std::string &f)
8777 yy::calcxx_parser parser (*this);
8778 parser.set_debug_level (trace_parsing);
8779 int res = parser.parse ();
8785 calcxx_driver::error (const yy::location& l, const std::string& m)
8787 std::cerr << l << ": " << m << std::endl;
8791 calcxx_driver::error (const std::string& m)
8793 std::cerr << m << std::endl;
8798 @subsubsection Calc++ Parser
8800 The parser definition file @file{calc++-parser.yy} starts by asking for
8801 the C++ deterministic parser skeleton, the creation of the parser header
8802 file, and specifies the name of the parser class.
8803 Because the C++ skeleton changed several times, it is safer to require
8804 the version you designed the grammar for.
8806 @comment file: calc++-parser.yy
8808 %skeleton "lalr1.cc" /* -*- C++ -*- */
8809 %require "@value{VERSION}"
8811 %define parser_class_name "calcxx_parser"
8815 @findex %code requires
8816 Then come the declarations/inclusions needed to define the
8817 @code{%union}. Because the parser uses the parsing driver and
8818 reciprocally, both cannot include the header of the other. Because the
8819 driver's header needs detailed knowledge about the parser class (in
8820 particular its inner types), it is the parser's header which will simply
8821 use a forward declaration of the driver.
8822 @xref{Decl Summary, ,%code}.
8824 @comment file: calc++-parser.yy
8828 class calcxx_driver;
8833 The driver is passed by reference to the parser and to the scanner.
8834 This provides a simple but effective pure interface, not relying on
8837 @comment file: calc++-parser.yy
8839 // The parsing context.
8840 %param @{ calcxx_driver& driver @}
8844 Then we request location tracking, and initialize the
8845 first location's file name. Afterwards new locations are computed
8846 relatively to the previous locations: the file name will be
8849 @comment file: calc++-parser.yy
8854 // Initialize the initial location.
8855 @@$.begin.filename = @@$.end.filename = &driver.file;
8860 Use the following two directives to enable parser tracing and verbose
8863 @comment file: calc++-parser.yy
8866 %define parse.error verbose
8870 Semantic values cannot use ``real'' objects, but only pointers to
8873 @comment file: calc++-parser.yy
8885 The code between @samp{%code @{} and @samp{@}} is output in the
8886 @file{*.cc} file; it needs detailed knowledge about the driver.
8888 @comment file: calc++-parser.yy
8891 # include "calc++-driver.hh"
8897 The token numbered as 0 corresponds to end of file; the following line
8898 allows for nicer error messages referring to ``end of file'' instead of
8899 ``$end''. Similarly user friendly names are provided for each symbol.
8900 To avoid name clashes in the generated files (@pxref{Calc++ Scanner}),
8901 prefix tokens with @code{TOK_} (@pxref{Decl Summary,, api.tokens.prefix}).
8903 @comment file: calc++-parser.yy
8905 %define api.tokens.prefix "TOK_"
8906 %token END 0 "end of file"
8908 %token <sval> IDENTIFIER "identifier"
8909 %token <ival> NUMBER "number"
8914 To enable memory deallocation during error recovery, use
8917 @c FIXME: Document %printer, and mention that it takes a braced-code operand.
8918 @comment file: calc++-parser.yy
8920 %printer @{ debug_stream () << *$$; @} "identifier"
8921 %destructor @{ delete $$; @} "identifier"
8923 %printer @{ debug_stream () << $$; @} <ival>
8927 The grammar itself is straightforward.
8929 @comment file: calc++-parser.yy
8933 unit: assignments exp @{ driver.result = $2; @};
8936 assignments assignment @{@}
8937 | /* Nothing. */ @{@};
8940 "identifier" ":=" exp
8941 @{ driver.variables[*$1] = $3; delete $1; @};
8946 exp '+' exp @{ $$ = $1 + $3; @}
8947 | exp '-' exp @{ $$ = $1 - $3; @}
8948 | exp '*' exp @{ $$ = $1 * $3; @}
8949 | exp '/' exp @{ $$ = $1 / $3; @}
8950 | '(' exp ')' @{ $$ = $2; @}
8951 | "identifier" @{ $$ = driver.variables[*$1]; delete $1; @}
8952 | "number" @{ $$ = $1; @};
8957 Finally the @code{error} member function registers the errors to the
8960 @comment file: calc++-parser.yy
8963 yy::calcxx_parser::error (const yy::calcxx_parser::location_type& l,
8964 const std::string& m)
8966 driver.error (l, m);
8970 @node Calc++ Scanner
8971 @subsubsection Calc++ Scanner
8973 The Flex scanner first includes the driver declaration, then the
8974 parser's to get the set of defined tokens.
8976 @comment file: calc++-scanner.ll
8978 %@{ /* -*- C++ -*- */
8983 # include "calc++-driver.hh"
8984 # include "calc++-parser.hh"
8986 /* Work around an incompatibility in flex (at least versions
8987 2.5.31 through 2.5.33): it generates code that does
8988 not conform to C89. See Debian bug 333231
8989 <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=333231>. */
8993 /* By default yylex returns an int; we use token_type.
8994 The default yyterminate implementation returns 0, which is
8995 not of token_type. */
8996 #define yyterminate() return TOKEN(END)
9001 Because there is no @code{#include}-like feature we don't need
9002 @code{yywrap}, we don't need @code{unput} either, and we parse an
9003 actual file, this is not an interactive session with the user.
9004 Finally we enable the scanner tracing features.
9006 @comment file: calc++-scanner.ll
9008 %option noyywrap nounput batch debug
9012 Abbreviations allow for more readable rules.
9014 @comment file: calc++-scanner.ll
9016 id [a-zA-Z][a-zA-Z_0-9]*
9022 The following paragraph suffices to track locations accurately. Each
9023 time @code{yylex} is invoked, the begin position is moved onto the end
9024 position. Then when a pattern is matched, the end position is
9025 advanced of its width. In case it matched ends of lines, the end
9026 cursor is adjusted, and each time blanks are matched, the begin cursor
9027 is moved onto the end cursor to effectively ignore the blanks
9028 preceding tokens. Comments would be treated equally.
9030 @comment file: calc++-scanner.ll
9033 # define YY_USER_ACTION yylloc->columns (yyleng);
9039 @{blank@}+ yylloc->step ();
9040 [\n]+ yylloc->lines (yyleng); yylloc->step ();
9044 The rules are simple. The driver is used to report errors. It is
9045 convenient to use a macro to shorten
9046 @code{yy::calcxx_parser::token::TOK_@var{Name}} into
9047 @code{TOKEN(@var{Name})}; note the token prefix, @code{TOK_}.
9049 @comment file: calc++-scanner.ll
9052 # define TOKEN(Name) \
9053 yy::calcxx_parser::token::TOK_ ## Name
9055 /* Convert ints to the actual type of tokens. */
9056 [-+*/()] return yy::calcxx_parser::token_type (yytext[0]);
9057 ":=" return TOKEN(ASSIGN);
9060 long n = strtol (yytext, NULL, 10);
9061 if (! (INT_MIN <= n && n <= INT_MAX && errno != ERANGE))
9062 driver.error (*yylloc, "integer is out of range");
9064 return TOKEN(NUMBER);
9067 yylval->sval = new std::string (yytext);
9068 return TOKEN(IDENTIFIER);
9070 . driver.error (*yylloc, "invalid character");
9075 Finally, because the scanner related driver's member function depend
9076 on the scanner's data, it is simpler to implement them in this file.
9078 @comment file: calc++-scanner.ll
9081 calcxx_driver::scan_begin ()
9083 yy_flex_debug = trace_scanning;
9086 else if (!(yyin = fopen (file.c_str (), "r")))
9088 error (std::string ("cannot open ") + file);
9094 calcxx_driver::scan_end ()
9100 @node Calc++ Top Level
9101 @subsubsection Calc++ Top Level
9103 The top level file, @file{calc++.cc}, poses no problem.
9105 @comment file: calc++.cc
9108 #include "calc++-driver.hh"
9111 main (int argc, char *argv[])
9114 calcxx_driver driver;
9115 for (++argv; argv[0]; ++argv)
9116 if (*argv == std::string ("-p"))
9117 driver.trace_parsing = true;
9118 else if (*argv == std::string ("-s"))
9119 driver.trace_scanning = true;
9120 else if (!driver.parse (*argv))
9121 std::cout << driver.result << std::endl;
9129 @section Java Parsers
9132 * Java Bison Interface:: Asking for Java parser generation
9133 * Java Semantic Values:: %type and %token vs. Java
9134 * Java Location Values:: The position and location classes
9135 * Java Parser Interface:: Instantiating and running the parser
9136 * Java Scanner Interface:: Specifying the scanner for the parser
9137 * Java Action Features:: Special features for use in actions
9138 * Java Differences:: Differences between C/C++ and Java Grammars
9139 * Java Declarations Summary:: List of Bison declarations used with Java
9142 @node Java Bison Interface
9143 @subsection Java Bison Interface
9144 @c - %language "Java"
9146 (The current Java interface is experimental and may evolve.
9147 More user feedback will help to stabilize it.)
9149 The Java parser skeletons are selected using the @code{%language "Java"}
9150 directive or the @option{-L java}/@option{--language=java} option.
9152 @c FIXME: Documented bug.
9153 When generating a Java parser, @code{bison @var{basename}.y} will create
9154 a single Java source file named @file{@var{basename}.java}. Using an
9155 input file without a @file{.y} suffix is currently broken. The basename
9156 of the output file can be changed by the @code{%file-prefix} directive
9157 or the @option{-p}/@option{--name-prefix} option. The entire output file
9158 name can be changed by the @code{%output} directive or the
9159 @option{-o}/@option{--output} option. The output file contains a single
9160 class for the parser.
9162 You can create documentation for generated parsers using Javadoc.
9164 Contrary to C parsers, Java parsers do not use global variables; the
9165 state of the parser is always local to an instance of the parser class.
9166 Therefore, all Java parsers are ``pure'', and the @code{%pure-parser}
9167 and @samp{%define api.pure} directives does not do anything when used in
9170 Push parsers are currently unsupported in Java and @code{%define
9171 api.push-pull} have no effect.
9173 @acronym{GLR} parsers are currently unsupported in Java. Do not use the
9174 @code{glr-parser} directive.
9176 No header file can be generated for Java parsers. Do not use the
9177 @code{%defines} directive or the @option{-d}/@option{--defines} options.
9179 @c FIXME: Possible code change.
9180 Currently, support for tracing is always compiled
9181 in. Thus the @samp{%define parse.trace} and @samp{%token-table}
9183 @option{-t}/@option{--debug} and @option{-k}/@option{--token-table}
9184 options have no effect. This may change in the future to eliminate
9185 unused code in the generated parser, so use @samp{%define parse.trace}
9187 if needed. Also, in the future the
9188 @code{%token-table} directive might enable a public interface to
9189 access the token names and codes.
9191 Getting a ``code too large'' error from the Java compiler means the code
9192 hit the 64KB bytecode per method limination of the Java class file.
9193 Try reducing the amount of code in actions and static initializers;
9194 otherwise, report a bug so that the parser skeleton will be improved.
9197 @node Java Semantic Values
9198 @subsection Java Semantic Values
9199 @c - No %union, specify type in %type/%token.
9201 @c - Printer and destructor
9203 There is no @code{%union} directive in Java parsers. Instead, the
9204 semantic values' types (class names) should be specified in the
9205 @code{%type} or @code{%token} directive:
9208 %type <Expression> expr assignment_expr term factor
9209 %type <Integer> number
9212 By default, the semantic stack is declared to have @code{Object} members,
9213 which means that the class types you specify can be of any class.
9214 To improve the type safety of the parser, you can declare the common
9215 superclass of all the semantic values using the @samp{%define stype}
9216 directive. For example, after the following declaration:
9219 %define stype "ASTNode"
9223 any @code{%type} or @code{%token} specifying a semantic type which
9224 is not a subclass of ASTNode, will cause a compile-time error.
9226 @c FIXME: Documented bug.
9227 Types used in the directives may be qualified with a package name.
9228 Primitive data types are accepted for Java version 1.5 or later. Note
9229 that in this case the autoboxing feature of Java 1.5 will be used.
9230 Generic types may not be used; this is due to a limitation in the
9231 implementation of Bison, and may change in future releases.
9233 Java parsers do not support @code{%destructor}, since the language
9234 adopts garbage collection. The parser will try to hold references
9235 to semantic values for as little time as needed.
9237 Java parsers do not support @code{%printer}, as @code{toString()}
9238 can be used to print the semantic values. This however may change
9239 (in a backwards-compatible way) in future versions of Bison.
9242 @node Java Location Values
9243 @subsection Java Location Values
9248 When the directive @code{%locations} is used, the Java parser
9249 supports location tracking, see @ref{Locations, , Locations Overview}.
9250 An auxiliary user-defined class defines a @dfn{position}, a single point
9251 in a file; Bison itself defines a class representing a @dfn{location},
9252 a range composed of a pair of positions (possibly spanning several
9253 files). The location class is an inner class of the parser; the name
9254 is @code{Location} by default, and may also be renamed using
9255 @samp{%define location_type "@var{class-name}"}.
9257 The location class treats the position as a completely opaque value.
9258 By default, the class name is @code{Position}, but this can be changed
9259 with @samp{%define position_type "@var{class-name}"}. This class must
9260 be supplied by the user.
9263 @deftypeivar {Location} {Position} begin
9264 @deftypeivarx {Location} {Position} end
9265 The first, inclusive, position of the range, and the first beyond.
9268 @deftypeop {Constructor} {Location} {} Location (Position @var{loc})
9269 Create a @code{Location} denoting an empty range located at a given point.
9272 @deftypeop {Constructor} {Location} {} Location (Position @var{begin}, Position @var{end})
9273 Create a @code{Location} from the endpoints of the range.
9276 @deftypemethod {Location} {String} toString ()
9277 Prints the range represented by the location. For this to work
9278 properly, the position class should override the @code{equals} and
9279 @code{toString} methods appropriately.
9283 @node Java Parser Interface
9284 @subsection Java Parser Interface
9285 @c - define parser_class_name
9287 @c - parse, error, set_debug_level, debug_level, set_debug_stream,
9289 @c - Reporting errors
9291 The name of the generated parser class defaults to @code{YYParser}. The
9292 @code{YY} prefix may be changed using the @code{%name-prefix} directive
9293 or the @option{-p}/@option{--name-prefix} option. Alternatively, use
9294 @samp{%define parser_class_name "@var{name}"} to give a custom name to
9295 the class. The interface of this class is detailed below.
9297 By default, the parser class has package visibility. A declaration
9298 @samp{%define public} will change to public visibility. Remember that,
9299 according to the Java language specification, the name of the @file{.java}
9300 file should match the name of the class in this case. Similarly, you can
9301 use @code{abstract}, @code{final} and @code{strictfp} with the
9302 @code{%define} declaration to add other modifiers to the parser class.
9303 A single @samp{%define annotations "@var{annotations}"} directive can
9304 be used to add any number of annotations to the parser class.
9306 The Java package name of the parser class can be specified using the
9307 @samp{%define package} directive. The superclass and the implemented
9308 interfaces of the parser class can be specified with the @code{%define
9309 extends} and @samp{%define implements} directives.
9311 The parser class defines an inner class, @code{Location}, that is used
9312 for location tracking (see @ref{Java Location Values}), and a inner
9313 interface, @code{Lexer} (see @ref{Java Scanner Interface}). Other than
9314 these inner class/interface, and the members described in the interface
9315 below, all the other members and fields are preceded with a @code{yy} or
9316 @code{YY} prefix to avoid clashes with user code.
9318 The parser class can be extended using the @code{%parse-param}
9319 directive. Each occurrence of the directive will add a @code{protected
9320 final} field to the parser class, and an argument to its constructor,
9321 which initialize them automatically.
9323 @deftypeop {Constructor} {YYParser} {} YYParser (@var{lex_param}, @dots{}, @var{parse_param}, @dots{})
9324 Build a new parser object with embedded @code{%code lexer}. There are
9325 no parameters, unless @code{%param}s and/or @code{%parse-param}s and/or
9326 @code{%lex-param}s are used.
9328 Use @code{%code init} for code added to the start of the constructor
9329 body. This is especially useful to initialize superclasses. Use
9330 @samp{%define init_throws} to specify any uncatch exceptions.
9333 @deftypeop {Constructor} {YYParser} {} YYParser (Lexer @var{lexer}, @var{parse_param}, @dots{})
9334 Build a new parser object using the specified scanner. There are no
9335 additional parameters unless @code{%param}s and/or @code{%parse-param}s are
9338 If the scanner is defined by @code{%code lexer}, this constructor is
9339 declared @code{protected} and is called automatically with a scanner
9340 created with the correct @code{%param}s and/or @code{%lex-param}s.
9342 Use @code{%code init} for code added to the start of the constructor
9343 body. This is especially useful to initialize superclasses. Use
9344 @samp{%define init_throws} to specify any uncatch exceptions.
9347 @deftypemethod {YYParser} {boolean} parse ()
9348 Run the syntactic analysis, and return @code{true} on success,
9349 @code{false} otherwise.
9352 @deftypemethod {YYParser} {boolean} getErrorVerbose ()
9353 @deftypemethodx {YYParser} {void} setErrorVerbose (boolean @var{verbose})
9354 Get or set the option to produce verbose error messages. These are only
9355 available with @samp{%define parse.error verbose}, which also turns on
9356 verbose error messages.
9359 @deftypemethod {YYParser} {void} yyerror (String @var{msg})
9360 @deftypemethodx {YYParser} {void} yyerror (Position @var{pos}, String @var{msg})
9361 @deftypemethodx {YYParser} {void} yyerror (Location @var{loc}, String @var{msg})
9362 Print an error message using the @code{yyerror} method of the scanner
9363 instance in use. The @code{Location} and @code{Position} parameters are
9364 available only if location tracking is active.
9367 @deftypemethod {YYParser} {boolean} recovering ()
9368 During the syntactic analysis, return @code{true} if recovering
9369 from a syntax error.
9370 @xref{Error Recovery}.
9373 @deftypemethod {YYParser} {java.io.PrintStream} getDebugStream ()
9374 @deftypemethodx {YYParser} {void} setDebugStream (java.io.printStream @var{o})
9375 Get or set the stream used for tracing the parsing. It defaults to
9379 @deftypemethod {YYParser} {int} getDebugLevel ()
9380 @deftypemethodx {YYParser} {void} setDebugLevel (int @var{l})
9381 Get or set the tracing level. Currently its value is either 0, no trace,
9382 or nonzero, full tracing.
9385 @deftypecv {Constant} {YYParser} {String} {bisonVersion}
9386 @deftypecvx {Constant} {YYParser} {String} {bisonSkeleton}
9387 Identify the Bison version and skeleton used to generate this parser.
9391 @node Java Scanner Interface
9392 @subsection Java Scanner Interface
9395 @c - Lexer interface
9397 There are two possible ways to interface a Bison-generated Java parser
9398 with a scanner: the scanner may be defined by @code{%code lexer}, or
9399 defined elsewhere. In either case, the scanner has to implement the
9400 @code{Lexer} inner interface of the parser class. This interface also
9401 contain constants for all user-defined token names and the predefined
9404 In the first case, the body of the scanner class is placed in
9405 @code{%code lexer} blocks. If you want to pass parameters from the
9406 parser constructor to the scanner constructor, specify them with
9407 @code{%lex-param}; they are passed before @code{%parse-param}s to the
9410 In the second case, the scanner has to implement the @code{Lexer} interface,
9411 which is defined within the parser class (e.g., @code{YYParser.Lexer}).
9412 The constructor of the parser object will then accept an object
9413 implementing the interface; @code{%lex-param} is not used in this
9416 In both cases, the scanner has to implement the following methods.
9418 @deftypemethod {Lexer} {void} yyerror (Location @var{loc}, String @var{msg})
9419 This method is defined by the user to emit an error message. The first
9420 parameter is omitted if location tracking is not active. Its type can be
9421 changed using @samp{%define location_type "@var{class-name}".}
9424 @deftypemethod {Lexer} {int} yylex ()
9425 Return the next token. Its type is the return value, its semantic
9426 value and location are saved and returned by the ther methods in the
9429 Use @samp{%define lex_throws} to specify any uncaught exceptions.
9430 Default is @code{java.io.IOException}.
9433 @deftypemethod {Lexer} {Position} getStartPos ()
9434 @deftypemethodx {Lexer} {Position} getEndPos ()
9435 Return respectively the first position of the last token that
9436 @code{yylex} returned, and the first position beyond it. These
9437 methods are not needed unless location tracking is active.
9439 The return type can be changed using @samp{%define position_type
9440 "@var{class-name}".}
9443 @deftypemethod {Lexer} {Object} getLVal ()
9444 Return the semantical value of the last token that yylex returned.
9446 The return type can be changed using @samp{%define stype
9447 "@var{class-name}".}
9451 @node Java Action Features
9452 @subsection Special Features for Use in Java Actions
9454 The following special constructs can be uses in Java actions.
9455 Other analogous C action features are currently unavailable for Java.
9457 Use @samp{%define throws} to specify any uncaught exceptions from parser
9458 actions, and initial actions specified by @code{%initial-action}.
9461 The semantic value for the @var{n}th component of the current rule.
9462 This may not be assigned to.
9463 @xref{Java Semantic Values}.
9466 @defvar $<@var{typealt}>@var{n}
9467 Like @code{$@var{n}} but specifies a alternative type @var{typealt}.
9468 @xref{Java Semantic Values}.
9472 The semantic value for the grouping made by the current rule. As a
9473 value, this is in the base type (@code{Object} or as specified by
9474 @samp{%define stype}) as in not cast to the declared subtype because
9475 casts are not allowed on the left-hand side of Java assignments.
9476 Use an explicit Java cast if the correct subtype is needed.
9477 @xref{Java Semantic Values}.
9480 @defvar $<@var{typealt}>$
9481 Same as @code{$$} since Java always allow assigning to the base type.
9482 Perhaps we should use this and @code{$<>$} for the value and @code{$$}
9483 for setting the value but there is currently no easy way to distinguish
9485 @xref{Java Semantic Values}.
9489 The location information of the @var{n}th component of the current rule.
9490 This may not be assigned to.
9491 @xref{Java Location Values}.
9495 The location information of the grouping made by the current rule.
9496 @xref{Java Location Values}.
9499 @deffn {Statement} {return YYABORT;}
9500 Return immediately from the parser, indicating failure.
9501 @xref{Java Parser Interface}.
9504 @deffn {Statement} {return YYACCEPT;}
9505 Return immediately from the parser, indicating success.
9506 @xref{Java Parser Interface}.
9509 @deffn {Statement} {return YYERROR;}
9510 Start error recovery without printing an error message.
9511 @xref{Error Recovery}.
9514 @deffn {Statement} {return YYFAIL;}
9515 Print an error message and start error recovery.
9516 @xref{Error Recovery}.
9519 @deftypefn {Function} {boolean} recovering ()
9520 Return whether error recovery is being done. In this state, the parser
9521 reads token until it reaches a known state, and then restarts normal
9523 @xref{Error Recovery}.
9526 @deftypefn {Function} {void} yyerror (String @var{msg})
9527 @deftypefnx {Function} {void} yyerror (Position @var{loc}, String @var{msg})
9528 @deftypefnx {Function} {void} yyerror (Location @var{loc}, String @var{msg})
9529 Print an error message using the @code{yyerror} method of the scanner
9530 instance in use. The @code{Location} and @code{Position} parameters are
9531 available only if location tracking is active.
9535 @node Java Differences
9536 @subsection Differences between C/C++ and Java Grammars
9538 The different structure of the Java language forces several differences
9539 between C/C++ grammars, and grammars designed for Java parsers. This
9540 section summarizes these differences.
9544 Java lacks a preprocessor, so the @code{YYERROR}, @code{YYACCEPT},
9545 @code{YYABORT} symbols (@pxref{Table of Symbols}) cannot obviously be
9546 macros. Instead, they should be preceded by @code{return} when they
9547 appear in an action. The actual definition of these symbols is
9548 opaque to the Bison grammar, and it might change in the future. The
9549 only meaningful operation that you can do, is to return them.
9550 See @pxref{Java Action Features}.
9552 Note that of these three symbols, only @code{YYACCEPT} and
9553 @code{YYABORT} will cause a return from the @code{yyparse}
9554 method@footnote{Java parsers include the actions in a separate
9555 method than @code{yyparse} in order to have an intuitive syntax that
9556 corresponds to these C macros.}.
9559 Java lacks unions, so @code{%union} has no effect. Instead, semantic
9560 values have a common base type: @code{Object} or as specified by
9561 @samp{%define stype}. Angle backets on @code{%token}, @code{type},
9562 @code{$@var{n}} and @code{$$} specify subtypes rather than fields of
9563 an union. The type of @code{$$}, even with angle brackets, is the base
9564 type since Java casts are not allow on the left-hand side of assignments.
9565 Also, @code{$@var{n}} and @code{@@@var{n}} are not allowed on the
9566 left-hand side of assignments. See @pxref{Java Semantic Values} and
9567 @pxref{Java Action Features}.
9570 The prolog declarations have a different meaning than in C/C++ code.
9572 @item @code{%code imports}
9573 blocks are placed at the beginning of the Java source code. They may
9574 include copyright notices. For a @code{package} declarations, it is
9575 suggested to use @samp{%define package} instead.
9577 @item unqualified @code{%code}
9578 blocks are placed inside the parser class.
9580 @item @code{%code lexer}
9581 blocks, if specified, should include the implementation of the
9582 scanner. If there is no such block, the scanner can be any class
9583 that implements the appropriate interface (see @pxref{Java Scanner
9587 Other @code{%code} blocks are not supported in Java parsers.
9588 In particular, @code{%@{ @dots{} %@}} blocks should not be used
9589 and may give an error in future versions of Bison.
9591 The epilogue has the same meaning as in C/C++ code and it can
9592 be used to define other classes used by the parser @emph{outside}
9597 @node Java Declarations Summary
9598 @subsection Java Declarations Summary
9600 This summary only include declarations specific to Java or have special
9601 meaning when used in a Java parser.
9603 @deffn {Directive} {%language "Java"}
9604 Generate a Java class for the parser.
9607 @deffn {Directive} %lex-param @{@var{type} @var{name}@}
9608 A parameter for the lexer class defined by @code{%code lexer}
9609 @emph{only}, added as parameters to the lexer constructor and the parser
9610 constructor that @emph{creates} a lexer. Default is none.
9611 @xref{Java Scanner Interface}.
9614 @deffn {Directive} %name-prefix "@var{prefix}"
9615 The prefix of the parser class name @code{@var{prefix}Parser} if
9616 @samp{%define parser_class_name} is not used. Default is @code{YY}.
9617 @xref{Java Bison Interface}.
9620 @deffn {Directive} %parse-param @{@var{type} @var{name}@}
9621 A parameter for the parser class added as parameters to constructor(s)
9622 and as fields initialized by the constructor(s). Default is none.
9623 @xref{Java Parser Interface}.
9626 @deffn {Directive} %token <@var{type}> @var{token} @dots{}
9627 Declare tokens. Note that the angle brackets enclose a Java @emph{type}.
9628 @xref{Java Semantic Values}.
9631 @deffn {Directive} %type <@var{type}> @var{nonterminal} @dots{}
9632 Declare the type of nonterminals. Note that the angle brackets enclose
9634 @xref{Java Semantic Values}.
9637 @deffn {Directive} %code @{ @var{code} @dots{} @}
9638 Code appended to the inside of the parser class.
9639 @xref{Java Differences}.
9642 @deffn {Directive} {%code imports} @{ @var{code} @dots{} @}
9643 Code inserted just after the @code{package} declaration.
9644 @xref{Java Differences}.
9647 @deffn {Directive} {%code init} @{ @var{code} @dots{} @}
9648 Code inserted at the beginning of the parser constructor body.
9649 @xref{Java Parser Interface}.
9652 @deffn {Directive} {%code lexer} @{ @var{code} @dots{} @}
9653 Code added to the body of a inner lexer class within the parser class.
9654 @xref{Java Scanner Interface}.
9657 @deffn {Directive} %% @var{code} @dots{}
9658 Code (after the second @code{%%}) appended to the end of the file,
9659 @emph{outside} the parser class.
9660 @xref{Java Differences}.
9663 @deffn {Directive} %@{ @var{code} @dots{} %@}
9664 Not supported. Use @code{%code imports} instead.
9665 @xref{Java Differences}.
9668 @deffn {Directive} {%define abstract}
9669 Whether the parser class is declared @code{abstract}. Default is false.
9670 @xref{Java Bison Interface}.
9673 @deffn {Directive} {%define annotations} "@var{annotations}"
9674 The Java annotations for the parser class. Default is none.
9675 @xref{Java Bison Interface}.
9678 @deffn {Directive} {%define extends} "@var{superclass}"
9679 The superclass of the parser class. Default is none.
9680 @xref{Java Bison Interface}.
9683 @deffn {Directive} {%define final}
9684 Whether the parser class is declared @code{final}. Default is false.
9685 @xref{Java Bison Interface}.
9688 @deffn {Directive} {%define implements} "@var{interfaces}"
9689 The implemented interfaces of the parser class, a comma-separated list.
9691 @xref{Java Bison Interface}.
9694 @deffn {Directive} {%define init_throws} "@var{exceptions}"
9695 The exceptions thrown by @code{%code init} from the parser class
9696 constructor. Default is none.
9697 @xref{Java Parser Interface}.
9700 @deffn {Directive} {%define lex_throws} "@var{exceptions}"
9701 The exceptions thrown by the @code{yylex} method of the lexer, a
9702 comma-separated list. Default is @code{java.io.IOException}.
9703 @xref{Java Scanner Interface}.
9706 @deffn {Directive} {%define location_type} "@var{class}"
9707 The name of the class used for locations (a range between two
9708 positions). This class is generated as an inner class of the parser
9709 class by @command{bison}. Default is @code{Location}.
9710 @xref{Java Location Values}.
9713 @deffn {Directive} {%define package} "@var{package}"
9714 The package to put the parser class in. Default is none.
9715 @xref{Java Bison Interface}.
9718 @deffn {Directive} {%define parser_class_name} "@var{name}"
9719 The name of the parser class. Default is @code{YYParser} or
9720 @code{@var{name-prefix}Parser}.
9721 @xref{Java Bison Interface}.
9724 @deffn {Directive} {%define position_type} "@var{class}"
9725 The name of the class used for positions. This class must be supplied by
9726 the user. Default is @code{Position}.
9727 @xref{Java Location Values}.
9730 @deffn {Directive} {%define public}
9731 Whether the parser class is declared @code{public}. Default is false.
9732 @xref{Java Bison Interface}.
9735 @deffn {Directive} {%define stype} "@var{class}"
9736 The base type of semantic values. Default is @code{Object}.
9737 @xref{Java Semantic Values}.
9740 @deffn {Directive} {%define strictfp}
9741 Whether the parser class is declared @code{strictfp}. Default is false.
9742 @xref{Java Bison Interface}.
9745 @deffn {Directive} {%define throws} "@var{exceptions}"
9746 The exceptions thrown by user-supplied parser actions and
9747 @code{%initial-action}, a comma-separated list. Default is none.
9748 @xref{Java Parser Interface}.
9752 @c ================================================= FAQ
9755 @chapter Frequently Asked Questions
9756 @cindex frequently asked questions
9759 Several questions about Bison come up occasionally. Here some of them
9763 * Memory Exhausted:: Breaking the Stack Limits
9764 * How Can I Reset the Parser:: @code{yyparse} Keeps some State
9765 * Strings are Destroyed:: @code{yylval} Loses Track of Strings
9766 * Implementing Gotos/Loops:: Control Flow in the Calculator
9767 * Multiple start-symbols:: Factoring closely related grammars
9768 * Secure? Conform?:: Is Bison @acronym{POSIX} safe?
9769 * I can't build Bison:: Troubleshooting
9770 * Where can I find help?:: Troubleshouting
9771 * Bug Reports:: Troublereporting
9772 * More Languages:: Parsers in C++, Java, and so on
9773 * Beta Testing:: Experimenting development versions
9774 * Mailing Lists:: Meeting other Bison users
9777 @node Memory Exhausted
9778 @section Memory Exhausted
9781 My parser returns with error with a @samp{memory exhausted}
9782 message. What can I do?
9785 This question is already addressed elsewhere, @xref{Recursion,
9788 @node How Can I Reset the Parser
9789 @section How Can I Reset the Parser
9791 The following phenomenon has several symptoms, resulting in the
9792 following typical questions:
9795 I invoke @code{yyparse} several times, and on correct input it works
9796 properly; but when a parse error is found, all the other calls fail
9797 too. How can I reset the error flag of @code{yyparse}?
9804 My parser includes support for an @samp{#include}-like feature, in
9805 which case I run @code{yyparse} from @code{yyparse}. This fails
9806 although I did specify @samp{%define api.pure}.
9809 These problems typically come not from Bison itself, but from
9810 Lex-generated scanners. Because these scanners use large buffers for
9811 speed, they might not notice a change of input file. As a
9812 demonstration, consider the following source file,
9813 @file{first-line.l}:
9821 .*\n ECHO; return 1;
9824 yyparse (char const *file)
9826 yyin = fopen (file, "r");
9829 /* One token only. */
9831 if (fclose (yyin) != 0)
9846 If the file @file{input} contains
9854 then instead of getting the first line twice, you get:
9857 $ @kbd{flex -ofirst-line.c first-line.l}
9858 $ @kbd{gcc -ofirst-line first-line.c -ll}
9859 $ @kbd{./first-line}
9864 Therefore, whenever you change @code{yyin}, you must tell the
9865 Lex-generated scanner to discard its current buffer and switch to the
9866 new one. This depends upon your implementation of Lex; see its
9867 documentation for more. For Flex, it suffices to call
9868 @samp{YY_FLUSH_BUFFER} after each change to @code{yyin}. If your
9869 Flex-generated scanner needs to read from several input streams to
9870 handle features like include files, you might consider using Flex
9871 functions like @samp{yy_switch_to_buffer} that manipulate multiple
9874 If your Flex-generated scanner uses start conditions (@pxref{Start
9875 conditions, , Start conditions, flex, The Flex Manual}), you might
9876 also want to reset the scanner's state, i.e., go back to the initial
9877 start condition, through a call to @samp{BEGIN (0)}.
9879 @node Strings are Destroyed
9880 @section Strings are Destroyed
9883 My parser seems to destroy old strings, or maybe it loses track of
9884 them. Instead of reporting @samp{"foo", "bar"}, it reports
9885 @samp{"bar", "bar"}, or even @samp{"foo\nbar", "bar"}.
9888 This error is probably the single most frequent ``bug report'' sent to
9889 Bison lists, but is only concerned with a misunderstanding of the role
9890 of the scanner. Consider the following Lex code:
9895 char *yylval = NULL;
9898 .* yylval = yytext; return 1;
9904 /* Similar to using $1, $2 in a Bison action. */
9905 char *fst = (yylex (), yylval);
9906 char *snd = (yylex (), yylval);
9907 printf ("\"%s\", \"%s\"\n", fst, snd);
9912 If you compile and run this code, you get:
9915 $ @kbd{flex -osplit-lines.c split-lines.l}
9916 $ @kbd{gcc -osplit-lines split-lines.c -ll}
9917 $ @kbd{printf 'one\ntwo\n' | ./split-lines}
9923 this is because @code{yytext} is a buffer provided for @emph{reading}
9924 in the action, but if you want to keep it, you have to duplicate it
9925 (e.g., using @code{strdup}). Note that the output may depend on how
9926 your implementation of Lex handles @code{yytext}. For instance, when
9927 given the Lex compatibility option @option{-l} (which triggers the
9928 option @samp{%array}) Flex generates a different behavior:
9931 $ @kbd{flex -l -osplit-lines.c split-lines.l}
9932 $ @kbd{gcc -osplit-lines split-lines.c -ll}
9933 $ @kbd{printf 'one\ntwo\n' | ./split-lines}
9938 @node Implementing Gotos/Loops
9939 @section Implementing Gotos/Loops
9942 My simple calculator supports variables, assignments, and functions,
9943 but how can I implement gotos, or loops?
9946 Although very pedagogical, the examples included in the document blur
9947 the distinction to make between the parser---whose job is to recover
9948 the structure of a text and to transmit it to subsequent modules of
9949 the program---and the processing (such as the execution) of this
9950 structure. This works well with so called straight line programs,
9951 i.e., precisely those that have a straightforward execution model:
9952 execute simple instructions one after the others.
9954 @cindex abstract syntax tree
9955 @cindex @acronym{AST}
9956 If you want a richer model, you will probably need to use the parser
9957 to construct a tree that does represent the structure it has
9958 recovered; this tree is usually called the @dfn{abstract syntax tree},
9959 or @dfn{@acronym{AST}} for short. Then, walking through this tree,
9960 traversing it in various ways, will enable treatments such as its
9961 execution or its translation, which will result in an interpreter or a
9964 This topic is way beyond the scope of this manual, and the reader is
9965 invited to consult the dedicated literature.
9968 @node Multiple start-symbols
9969 @section Multiple start-symbols
9972 I have several closely related grammars, and I would like to share their
9973 implementations. In fact, I could use a single grammar but with
9974 multiple entry points.
9977 Bison does not support multiple start-symbols, but there is a very
9978 simple means to simulate them. If @code{foo} and @code{bar} are the two
9979 pseudo start-symbols, then introduce two new tokens, say
9980 @code{START_FOO} and @code{START_BAR}, and use them as switches from the
9984 %token START_FOO START_BAR;
9986 start: START_FOO foo
9990 These tokens prevents the introduction of new conflicts. As far as the
9991 parser goes, that is all that is needed.
9993 Now the difficult part is ensuring that the scanner will send these
9994 tokens first. If your scanner is hand-written, that should be
9995 straightforward. If your scanner is generated by Lex, them there is
9996 simple means to do it: recall that anything between @samp{%@{ ... %@}}
9997 after the first @code{%%} is copied verbatim in the top of the generated
9998 @code{yylex} function. Make sure a variable @code{start_token} is
9999 available in the scanner (e.g., a global variable or using
10000 @code{%lex-param} etc.), and use the following:
10003 /* @r{Prologue.} */
10008 int t = start_token;
10013 /* @r{The rules.} */
10017 @node Secure? Conform?
10018 @section Secure? Conform?
10021 Is Bison secure? Does it conform to POSIX?
10024 If you're looking for a guarantee or certification, we don't provide it.
10025 However, Bison is intended to be a reliable program that conforms to the
10026 @acronym{POSIX} specification for Yacc. If you run into problems,
10027 please send us a bug report.
10029 @node I can't build Bison
10030 @section I can't build Bison
10033 I can't build Bison because @command{make} complains that
10034 @code{msgfmt} is not found.
10038 Like most GNU packages with internationalization support, that feature
10039 is turned on by default. If you have problems building in the @file{po}
10040 subdirectory, it indicates that your system's internationalization
10041 support is lacking. You can re-configure Bison with
10042 @option{--disable-nls} to turn off this support, or you can install GNU
10043 gettext from @url{ftp://ftp.gnu.org/gnu/gettext/} and re-configure
10044 Bison. See the file @file{ABOUT-NLS} for more information.
10047 @node Where can I find help?
10048 @section Where can I find help?
10051 I'm having trouble using Bison. Where can I find help?
10054 First, read this fine manual. Beyond that, you can send mail to
10055 @email{help-bison@@gnu.org}. This mailing list is intended to be
10056 populated with people who are willing to answer questions about using
10057 and installing Bison. Please keep in mind that (most of) the people on
10058 the list have aspects of their lives which are not related to Bison (!),
10059 so you may not receive an answer to your question right away. This can
10060 be frustrating, but please try not to honk them off; remember that any
10061 help they provide is purely voluntary and out of the kindness of their
10065 @section Bug Reports
10068 I found a bug. What should I include in the bug report?
10071 Before you send a bug report, make sure you are using the latest
10072 version. Check @url{ftp://ftp.gnu.org/pub/gnu/bison/} or one of its
10073 mirrors. Be sure to include the version number in your bug report. If
10074 the bug is present in the latest version but not in a previous version,
10075 try to determine the most recent version which did not contain the bug.
10077 If the bug is parser-related, you should include the smallest grammar
10078 you can which demonstrates the bug. The grammar file should also be
10079 complete (i.e., I should be able to run it through Bison without having
10080 to edit or add anything). The smaller and simpler the grammar, the
10081 easier it will be to fix the bug.
10083 Include information about your compilation environment, including your
10084 operating system's name and version and your compiler's name and
10085 version. If you have trouble compiling, you should also include a
10086 transcript of the build session, starting with the invocation of
10087 `configure'. Depending on the nature of the bug, you may be asked to
10088 send additional files as well (such as `config.h' or `config.cache').
10090 Patches are most welcome, but not required. That is, do not hesitate to
10091 send a bug report just because you can not provide a fix.
10093 Send bug reports to @email{bug-bison@@gnu.org}.
10095 @node More Languages
10096 @section More Languages
10099 Will Bison ever have C++ and Java support? How about @var{insert your
10100 favorite language here}?
10103 C++ and Java support is there now, and is documented. We'd love to add other
10104 languages; contributions are welcome.
10107 @section Beta Testing
10110 What is involved in being a beta tester?
10113 It's not terribly involved. Basically, you would download a test
10114 release, compile it, and use it to build and run a parser or two. After
10115 that, you would submit either a bug report or a message saying that
10116 everything is okay. It is important to report successes as well as
10117 failures because test releases eventually become mainstream releases,
10118 but only if they are adequately tested. If no one tests, development is
10119 essentially halted.
10121 Beta testers are particularly needed for operating systems to which the
10122 developers do not have easy access. They currently have easy access to
10123 recent GNU/Linux and Solaris versions. Reports about other operating
10124 systems are especially welcome.
10126 @node Mailing Lists
10127 @section Mailing Lists
10130 How do I join the help-bison and bug-bison mailing lists?
10133 See @url{http://lists.gnu.org/}.
10135 @c ================================================= Table of Symbols
10137 @node Table of Symbols
10138 @appendix Bison Symbols
10139 @cindex Bison symbols, table of
10140 @cindex symbols in Bison, table of
10142 @deffn {Variable} @@$
10143 In an action, the location of the left-hand side of the rule.
10144 @xref{Locations, , Locations Overview}.
10147 @deffn {Variable} @@@var{n}
10148 In an action, the location of the @var{n}-th symbol of the right-hand
10149 side of the rule. @xref{Locations, , Locations Overview}.
10152 @deffn {Variable} $$
10153 In an action, the semantic value of the left-hand side of the rule.
10157 @deffn {Variable} $@var{n}
10158 In an action, the semantic value of the @var{n}-th symbol of the
10159 right-hand side of the rule. @xref{Actions}.
10162 @deffn {Delimiter} %%
10163 Delimiter used to separate the grammar rule section from the
10164 Bison declarations section or the epilogue.
10165 @xref{Grammar Layout, ,The Overall Layout of a Bison Grammar}.
10168 @c Don't insert spaces, or check the DVI output.
10169 @deffn {Delimiter} %@{@var{code}%@}
10170 All code listed between @samp{%@{} and @samp{%@}} is copied directly to
10171 the output file uninterpreted. Such code forms the prologue of the input
10172 file. @xref{Grammar Outline, ,Outline of a Bison
10176 @deffn {Construct} /*@dots{}*/
10177 Comment delimiters, as in C.
10180 @deffn {Delimiter} :
10181 Separates a rule's result from its components. @xref{Rules, ,Syntax of
10185 @deffn {Delimiter} ;
10186 Terminates a rule. @xref{Rules, ,Syntax of Grammar Rules}.
10189 @deffn {Delimiter} |
10190 Separates alternate rules for the same result nonterminal.
10191 @xref{Rules, ,Syntax of Grammar Rules}.
10194 @deffn {Directive} <*>
10195 Used to define a default tagged @code{%destructor} or default tagged
10198 This feature is experimental.
10199 More user feedback will help to determine whether it should become a permanent
10202 @xref{Destructor Decl, , Freeing Discarded Symbols}.
10205 @deffn {Directive} <>
10206 Used to define a default tagless @code{%destructor} or default tagless
10209 This feature is experimental.
10210 More user feedback will help to determine whether it should become a permanent
10213 @xref{Destructor Decl, , Freeing Discarded Symbols}.
10216 @deffn {Symbol} $accept
10217 The predefined nonterminal whose only rule is @samp{$accept: @var{start}
10218 $end}, where @var{start} is the start symbol. @xref{Start Decl, , The
10219 Start-Symbol}. It cannot be used in the grammar.
10222 @deffn {Directive} %code @{@var{code}@}
10223 @deffnx {Directive} %code @var{qualifier} @{@var{code}@}
10224 Insert @var{code} verbatim into output parser source.
10225 @xref{Decl Summary,,%code}.
10228 @deffn {Directive} %debug
10229 Equip the parser for debugging. @xref{Decl Summary}.
10233 @deffn {Directive} %default-prec
10234 Assign a precedence to rules that lack an explicit @samp{%prec}
10235 modifier. @xref{Contextual Precedence, ,Context-Dependent
10240 @deffn {Directive} %define @var{define-variable}
10241 @deffnx {Directive} %define @var{define-variable} @var{value}
10242 @deffnx {Directive} %define @var{define-variable} "@var{value}"
10243 Define a variable to adjust Bison's behavior.
10244 @xref{Decl Summary,,%define}.
10247 @deffn {Directive} %defines
10248 Bison declaration to create a header file meant for the scanner.
10249 @xref{Decl Summary}.
10252 @deffn {Directive} %defines @var{defines-file}
10253 Same as above, but save in the file @var{defines-file}.
10254 @xref{Decl Summary}.
10257 @deffn {Directive} %destructor
10258 Specify how the parser should reclaim the memory associated to
10259 discarded symbols. @xref{Destructor Decl, , Freeing Discarded Symbols}.
10262 @deffn {Directive} %dprec
10263 Bison declaration to assign a precedence to a rule that is used at parse
10264 time to resolve reduce/reduce conflicts. @xref{GLR Parsers, ,Writing
10265 @acronym{GLR} Parsers}.
10268 @deffn {Symbol} $end
10269 The predefined token marking the end of the token stream. It cannot be
10270 used in the grammar.
10273 @deffn {Symbol} error
10274 A token name reserved for error recovery. This token may be used in
10275 grammar rules so as to allow the Bison parser to recognize an error in
10276 the grammar without halting the process. In effect, a sentence
10277 containing an error may be recognized as valid. On a syntax error, the
10278 token @code{error} becomes the current lookahead token. Actions
10279 corresponding to @code{error} are then executed, and the lookahead
10280 token is reset to the token that originally caused the violation.
10281 @xref{Error Recovery}.
10284 @deffn {Directive} %error-verbose
10285 An obsolete directive standing for @samp{%define parse.error verbose}.
10288 @deffn {Directive} %file-prefix "@var{prefix}"
10289 Bison declaration to set the prefix of the output files. @xref{Decl
10293 @deffn {Directive} %glr-parser
10294 Bison declaration to produce a @acronym{GLR} parser. @xref{GLR
10295 Parsers, ,Writing @acronym{GLR} Parsers}.
10298 @deffn {Directive} %initial-action
10299 Run user code before parsing. @xref{Initial Action Decl, , Performing Actions before Parsing}.
10302 @deffn {Directive} %language
10303 Specify the programming language for the generated parser.
10304 @xref{Decl Summary}.
10307 @deffn {Directive} %left
10308 Bison declaration to assign precedence and left associativity to token(s).
10309 @xref{Precedence Decl, ,Operator Precedence}.
10312 @deffn {Directive} %lex-param @{@var{argument-declaration}@} @dots{}
10313 Bison declaration to specifying additional arguments that
10314 @code{yylex} should accept. @xref{Pure Calling,, Calling Conventions
10318 @deffn {Directive} %merge
10319 Bison declaration to assign a merging function to a rule. If there is a
10320 reduce/reduce conflict with a rule having the same merging function, the
10321 function is applied to the two semantic values to get a single result.
10322 @xref{GLR Parsers, ,Writing @acronym{GLR} Parsers}.
10325 @deffn {Directive} %name-prefix "@var{prefix}"
10326 Bison declaration to rename the external symbols. @xref{Decl Summary}.
10330 @deffn {Directive} %no-default-prec
10331 Do not assign a precedence to rules that lack an explicit @samp{%prec}
10332 modifier. @xref{Contextual Precedence, ,Context-Dependent
10337 @deffn {Directive} %no-lines
10338 Bison declaration to avoid generating @code{#line} directives in the
10339 parser file. @xref{Decl Summary}.
10342 @deffn {Directive} %nonassoc
10343 Bison declaration to assign precedence and nonassociativity to token(s).
10344 @xref{Precedence Decl, ,Operator Precedence}.
10347 @deffn {Directive} %output "@var{file}"
10348 Bison declaration to set the name of the parser file. @xref{Decl
10352 @deffn {Directive} %param @{@var{argument-declaration}@} @dots{}
10353 Bison declaration to specify additional arguments that both
10354 @code{yylex} and @code{yyparse} should accept. @xref{Parser Function,, The
10355 Parser Function @code{yyparse}}.
10358 @deffn {Directive} %parse-param @{@var{argument-declaration}@} @dots{}
10359 Bison declaration to specify additional arguments that @code{yyparse}
10360 should accept. @xref{Parser Function,, The Parser Function @code{yyparse}}.
10363 @deffn {Directive} %prec
10364 Bison declaration to assign a precedence to a specific rule.
10365 @xref{Contextual Precedence, ,Context-Dependent Precedence}.
10368 @deffn {Directive} %precedence
10369 Bison declaration to assign precedence to token(s), but no associativity
10370 @xref{Precedence Decl, ,Operator Precedence}.
10373 @deffn {Directive} %pure-parser
10374 Deprecated version of @samp{%define api.pure} (@pxref{Decl Summary, ,%define}),
10375 for which Bison is more careful to warn about unreasonable usage.
10378 @deffn {Directive} %require "@var{version}"
10379 Require version @var{version} or higher of Bison. @xref{Require Decl, ,
10380 Require a Version of Bison}.
10383 @deffn {Directive} %right
10384 Bison declaration to assign precedence and right associativity to token(s).
10385 @xref{Precedence Decl, ,Operator Precedence}.
10388 @deffn {Directive} %skeleton
10389 Specify the skeleton to use; usually for development.
10390 @xref{Decl Summary}.
10393 @deffn {Directive} %start
10394 Bison declaration to specify the start symbol. @xref{Start Decl, ,The
10398 @deffn {Directive} %token
10399 Bison declaration to declare token(s) without specifying precedence.
10400 @xref{Token Decl, ,Token Type Names}.
10403 @deffn {Directive} %token-table
10404 Bison declaration to include a token name table in the parser file.
10405 @xref{Decl Summary}.
10408 @deffn {Directive} %type
10409 Bison declaration to declare nonterminals. @xref{Type Decl,
10410 ,Nonterminal Symbols}.
10413 @deffn {Symbol} $undefined
10414 The predefined token onto which all undefined values returned by
10415 @code{yylex} are mapped. It cannot be used in the grammar, rather, use
10419 @deffn {Directive} %union
10420 Bison declaration to specify several possible data types for semantic
10421 values. @xref{Union Decl, ,The Collection of Value Types}.
10424 @deffn {Macro} YYABORT
10425 Macro to pretend that an unrecoverable syntax error has occurred, by
10426 making @code{yyparse} return 1 immediately. The error reporting
10427 function @code{yyerror} is not called. @xref{Parser Function, ,The
10428 Parser Function @code{yyparse}}.
10430 For Java parsers, this functionality is invoked using @code{return YYABORT;}
10434 @deffn {Macro} YYACCEPT
10435 Macro to pretend that a complete utterance of the language has been
10436 read, by making @code{yyparse} return 0 immediately.
10437 @xref{Parser Function, ,The Parser Function @code{yyparse}}.
10439 For Java parsers, this functionality is invoked using @code{return YYACCEPT;}
10443 @deffn {Macro} YYBACKUP
10444 Macro to discard a value from the parser stack and fake a lookahead
10445 token. @xref{Action Features, ,Special Features for Use in Actions}.
10448 @deffn {Variable} yychar
10449 External integer variable that contains the integer value of the
10450 lookahead token. (In a pure parser, it is a local variable within
10451 @code{yyparse}.) Error-recovery rule actions may examine this variable.
10452 @xref{Action Features, ,Special Features for Use in Actions}.
10455 @deffn {Variable} yyclearin
10456 Macro used in error-recovery rule actions. It clears the previous
10457 lookahead token. @xref{Error Recovery}.
10460 @deffn {Macro} YYDEBUG
10461 Macro to define to equip the parser with tracing code. @xref{Tracing,
10462 ,Tracing Your Parser}.
10465 @deffn {Variable} yydebug
10466 External integer variable set to zero by default. If @code{yydebug}
10467 is given a nonzero value, the parser will output information on input
10468 symbols and parser action. @xref{Tracing, ,Tracing Your Parser}.
10471 @deffn {Macro} yyerrok
10472 Macro to cause parser to recover immediately to its normal mode
10473 after a syntax error. @xref{Error Recovery}.
10476 @deffn {Macro} YYERROR
10477 Macro to pretend that a syntax error has just been detected: call
10478 @code{yyerror} and then perform normal error recovery if possible
10479 (@pxref{Error Recovery}), or (if recovery is impossible) make
10480 @code{yyparse} return 1. @xref{Error Recovery}.
10482 For Java parsers, this functionality is invoked using @code{return YYERROR;}
10486 @deffn {Function} yyerror
10487 User-supplied function to be called by @code{yyparse} on error.
10488 @xref{Error Reporting, ,The Error Reporting Function @code{yyerror}}.
10491 @deffn {Macro} YYERROR_VERBOSE
10492 An obsolete macro used in the @file{yacc.c} skeleton, that you define
10493 with @code{#define} in the prologue to request verbose, specific error
10494 message strings when @code{yyerror} is called. It doesn't matter what
10495 definition you use for @code{YYERROR_VERBOSE}, just whether you define
10496 it. Using @samp{%define parse.error verbose} is preferred
10497 (@pxref{Error Reporting, ,The Error Reporting Function @code{yyerror}}).
10500 @deffn {Macro} YYINITDEPTH
10501 Macro for specifying the initial size of the parser stack.
10502 @xref{Memory Management}.
10505 @deffn {Function} yylex
10506 User-supplied lexical analyzer function, called with no arguments to get
10507 the next token. @xref{Lexical, ,The Lexical Analyzer Function
10511 @deffn {Macro} YYLEX_PARAM
10512 An obsolete macro for specifying an extra argument (or list of extra
10513 arguments) for @code{yyparse} to pass to @code{yylex}. The use of this
10514 macro is deprecated, and is supported only for Yacc like parsers.
10515 @xref{Pure Calling,, Calling Conventions for Pure Parsers}.
10518 @deffn {Variable} yylloc
10519 External variable in which @code{yylex} should place the line and column
10520 numbers associated with a token. (In a pure parser, it is a local
10521 variable within @code{yyparse}, and its address is passed to
10523 You can ignore this variable if you don't use the @samp{@@} feature in the
10525 @xref{Token Locations, ,Textual Locations of Tokens}.
10526 In semantic actions, it stores the location of the lookahead token.
10527 @xref{Actions and Locations, ,Actions and Locations}.
10530 @deffn {Type} YYLTYPE
10531 Data type of @code{yylloc}; by default, a structure with four
10532 members. @xref{Location Type, , Data Types of Locations}.
10535 @deffn {Variable} yylval
10536 External variable in which @code{yylex} should place the semantic
10537 value associated with a token. (In a pure parser, it is a local
10538 variable within @code{yyparse}, and its address is passed to
10540 @xref{Token Values, ,Semantic Values of Tokens}.
10541 In semantic actions, it stores the semantic value of the lookahead token.
10542 @xref{Actions, ,Actions}.
10545 @deffn {Macro} YYMAXDEPTH
10546 Macro for specifying the maximum size of the parser stack. @xref{Memory
10550 @deffn {Variable} yynerrs
10551 Global variable which Bison increments each time it reports a syntax error.
10552 (In a pure parser, it is a local variable within @code{yyparse}. In a
10553 pure push parser, it is a member of yypstate.)
10554 @xref{Error Reporting, ,The Error Reporting Function @code{yyerror}}.
10557 @deffn {Function} yyparse
10558 The parser function produced by Bison; call this function to start
10559 parsing. @xref{Parser Function, ,The Parser Function @code{yyparse}}.
10562 @deffn {Function} yypstate_delete
10563 The function to delete a parser instance, produced by Bison in push mode;
10564 call this function to delete the memory associated with a parser.
10565 @xref{Parser Delete Function, ,The Parser Delete Function
10566 @code{yypstate_delete}}.
10567 (The current push parsing interface is experimental and may evolve.
10568 More user feedback will help to stabilize it.)
10571 @deffn {Function} yypstate_new
10572 The function to create a parser instance, produced by Bison in push mode;
10573 call this function to create a new parser.
10574 @xref{Parser Create Function, ,The Parser Create Function
10575 @code{yypstate_new}}.
10576 (The current push parsing interface is experimental and may evolve.
10577 More user feedback will help to stabilize it.)
10580 @deffn {Function} yypull_parse
10581 The parser function produced by Bison in push mode; call this function to
10582 parse the rest of the input stream.
10583 @xref{Pull Parser Function, ,The Pull Parser Function
10584 @code{yypull_parse}}.
10585 (The current push parsing interface is experimental and may evolve.
10586 More user feedback will help to stabilize it.)
10589 @deffn {Function} yypush_parse
10590 The parser function produced by Bison in push mode; call this function to
10591 parse a single token. @xref{Push Parser Function, ,The Push Parser Function
10592 @code{yypush_parse}}.
10593 (The current push parsing interface is experimental and may evolve.
10594 More user feedback will help to stabilize it.)
10597 @deffn {Macro} YYPARSE_PARAM
10598 An obsolete macro for specifying the name of a parameter that
10599 @code{yyparse} should accept. The use of this macro is deprecated, and
10600 is supported only for Yacc like parsers. @xref{Pure Calling,, Calling
10601 Conventions for Pure Parsers}.
10604 @deffn {Macro} YYRECOVERING
10605 The expression @code{YYRECOVERING ()} yields 1 when the parser
10606 is recovering from a syntax error, and 0 otherwise.
10607 @xref{Action Features, ,Special Features for Use in Actions}.
10610 @deffn {Macro} YYSTACK_USE_ALLOCA
10611 Macro used to control the use of @code{alloca} when the
10612 deterministic parser in C needs to extend its stacks. If defined to 0,
10613 the parser will use @code{malloc} to extend its stacks. If defined to
10614 1, the parser will use @code{alloca}. Values other than 0 and 1 are
10615 reserved for future Bison extensions. If not defined,
10616 @code{YYSTACK_USE_ALLOCA} defaults to 0.
10618 In the all-too-common case where your code may run on a host with a
10619 limited stack and with unreliable stack-overflow checking, you should
10620 set @code{YYMAXDEPTH} to a value that cannot possibly result in
10621 unchecked stack overflow on any of your target hosts when
10622 @code{alloca} is called. You can inspect the code that Bison
10623 generates in order to determine the proper numeric values. This will
10624 require some expertise in low-level implementation details.
10627 @deffn {Type} YYSTYPE
10628 Data type of semantic values; @code{int} by default.
10629 @xref{Value Type, ,Data Types of Semantic Values}.
10637 @item Accepting State
10638 A state whose only action is the accept action.
10639 The accepting state is thus a consistent state.
10640 @xref{Understanding,,}.
10642 @item Backus-Naur Form (@acronym{BNF}; also called ``Backus Normal Form'')
10643 Formal method of specifying context-free grammars originally proposed
10644 by John Backus, and slightly improved by Peter Naur in his 1960-01-02
10645 committee document contributing to what became the Algol 60 report.
10646 @xref{Language and Grammar, ,Languages and Context-Free Grammars}.
10648 @item Consistent State
10649 A state containing only one possible action.
10650 @xref{Decl Summary,,lr.default-reductions}.
10652 @item Context-free grammars
10653 Grammars specified as rules that can be applied regardless of context.
10654 Thus, if there is a rule which says that an integer can be used as an
10655 expression, integers are allowed @emph{anywhere} an expression is
10656 permitted. @xref{Language and Grammar, ,Languages and Context-Free
10659 @item Default Reduction
10660 The reduction that a parser should perform if the current parser state
10661 contains no other action for the lookahead token.
10662 In permitted parser states, Bison declares the reduction with the
10663 largest lookahead set to be the default reduction and removes that
10665 @xref{Decl Summary,,lr.default-reductions}.
10667 @item Dynamic allocation
10668 Allocation of memory that occurs during execution, rather than at
10669 compile time or on entry to a function.
10672 Analogous to the empty set in set theory, the empty string is a
10673 character string of length zero.
10675 @item Finite-state stack machine
10676 A ``machine'' that has discrete states in which it is said to exist at
10677 each instant in time. As input to the machine is processed, the
10678 machine moves from state to state as specified by the logic of the
10679 machine. In the case of the parser, the input is the language being
10680 parsed, and the states correspond to various stages in the grammar
10681 rules. @xref{Algorithm, ,The Bison Parser Algorithm}.
10683 @item Generalized @acronym{LR} (@acronym{GLR})
10684 A parsing algorithm that can handle all context-free grammars, including those
10685 that are not @acronym{LR}(1). It resolves situations that Bison's
10686 deterministic parsing
10687 algorithm cannot by effectively splitting off multiple parsers, trying all
10688 possible parsers, and discarding those that fail in the light of additional
10689 right context. @xref{Generalized LR Parsing, ,Generalized
10690 @acronym{LR} Parsing}.
10693 A language construct that is (in general) grammatically divisible;
10694 for example, `expression' or `declaration' in C@.
10695 @xref{Language and Grammar, ,Languages and Context-Free Grammars}.
10697 @item @acronym{IELR}(1)
10698 A minimal @acronym{LR}(1) parser table generation algorithm.
10699 That is, given any context-free grammar, @acronym{IELR}(1) generates
10700 parser tables with the full language recognition power of canonical
10701 @acronym{LR}(1) but with nearly the same number of parser states as
10703 This reduction in parser states is often an order of magnitude.
10704 More importantly, because canonical @acronym{LR}(1)'s extra parser
10705 states may contain duplicate conflicts in the case of
10706 non-@acronym{LR}(1) grammars, the number of conflicts for
10707 @acronym{IELR}(1) is often an order of magnitude less as well.
10708 This can significantly reduce the complexity of developing of a grammar.
10709 @xref{Decl Summary,,lr.type}.
10711 @item Infix operator
10712 An arithmetic operator that is placed between the operands on which it
10713 performs some operation.
10716 A continuous flow of data between devices or programs.
10718 @item Language construct
10719 One of the typical usage schemas of the language. For example, one of
10720 the constructs of the C language is the @code{if} statement.
10721 @xref{Language and Grammar, ,Languages and Context-Free Grammars}.
10723 @item Left associativity
10724 Operators having left associativity are analyzed from left to right:
10725 @samp{a+b+c} first computes @samp{a+b} and then combines with
10726 @samp{c}. @xref{Precedence, ,Operator Precedence}.
10728 @item Left recursion
10729 A rule whose result symbol is also its first component symbol; for
10730 example, @samp{expseq1 : expseq1 ',' exp;}. @xref{Recursion, ,Recursive
10733 @item Left-to-right parsing
10734 Parsing a sentence of a language by analyzing it token by token from
10735 left to right. @xref{Algorithm, ,The Bison Parser Algorithm}.
10737 @item Lexical analyzer (scanner)
10738 A function that reads an input stream and returns tokens one by one.
10739 @xref{Lexical, ,The Lexical Analyzer Function @code{yylex}}.
10741 @item Lexical tie-in
10742 A flag, set by actions in the grammar rules, which alters the way
10743 tokens are parsed. @xref{Lexical Tie-ins}.
10745 @item Literal string token
10746 A token which consists of two or more fixed characters. @xref{Symbols}.
10748 @item Lookahead token
10749 A token already read but not yet shifted. @xref{Lookahead, ,Lookahead
10752 @item @acronym{LALR}(1)
10753 The class of context-free grammars that Bison (like most other parser
10754 generators) can handle by default; a subset of @acronym{LR}(1).
10755 @xref{Mystery Conflicts, ,Mysterious Reduce/Reduce Conflicts}.
10757 @item @acronym{LR}(1)
10758 The class of context-free grammars in which at most one token of
10759 lookahead is needed to disambiguate the parsing of any piece of input.
10761 @item Nonterminal symbol
10762 A grammar symbol standing for a grammatical construct that can
10763 be expressed through rules in terms of smaller constructs; in other
10764 words, a construct that is not a token. @xref{Symbols}.
10767 A function that recognizes valid sentences of a language by analyzing
10768 the syntax structure of a set of tokens passed to it from a lexical
10771 @item Postfix operator
10772 An arithmetic operator that is placed after the operands upon which it
10773 performs some operation.
10776 Replacing a string of nonterminals and/or terminals with a single
10777 nonterminal, according to a grammar rule. @xref{Algorithm, ,The Bison
10781 A reentrant subprogram is a subprogram which can be in invoked any
10782 number of times in parallel, without interference between the various
10783 invocations. @xref{Pure Decl, ,A Pure (Reentrant) Parser}.
10785 @item Reverse polish notation
10786 A language in which all operators are postfix operators.
10788 @item Right recursion
10789 A rule whose result symbol is also its last component symbol; for
10790 example, @samp{expseq1: exp ',' expseq1;}. @xref{Recursion, ,Recursive
10794 In computer languages, the semantics are specified by the actions
10795 taken for each instance of the language, i.e., the meaning of
10796 each statement. @xref{Semantics, ,Defining Language Semantics}.
10799 A parser is said to shift when it makes the choice of analyzing
10800 further input from the stream rather than reducing immediately some
10801 already-recognized rule. @xref{Algorithm, ,The Bison Parser Algorithm}.
10803 @item Single-character literal
10804 A single character that is recognized and interpreted as is.
10805 @xref{Grammar in Bison, ,From Formal Rules to Bison Input}.
10808 The nonterminal symbol that stands for a complete valid utterance in
10809 the language being parsed. The start symbol is usually listed as the
10810 first nonterminal symbol in a language specification.
10811 @xref{Start Decl, ,The Start-Symbol}.
10814 A data structure where symbol names and associated data are stored
10815 during parsing to allow for recognition and use of existing
10816 information in repeated uses of a symbol. @xref{Multi-function Calc}.
10819 An error encountered during parsing of an input stream due to invalid
10820 syntax. @xref{Error Recovery}.
10823 A basic, grammatically indivisible unit of a language. The symbol
10824 that describes a token in the grammar is a terminal symbol.
10825 The input of the Bison parser is a stream of tokens which comes from
10826 the lexical analyzer. @xref{Symbols}.
10828 @item Terminal symbol
10829 A grammar symbol that has no rules in the grammar and therefore is
10830 grammatically indivisible. The piece of text it represents is a token.
10831 @xref{Language and Grammar, ,Languages and Context-Free Grammars}.
10834 @node Copying This Manual
10835 @appendix Copying This Manual
10845 @c Local Variables:
10849 @c LocalWords: texinfo setfilename settitle setchapternewpage finalout texi FSF
10850 @c LocalWords: ifinfo smallbook shorttitlepage titlepage GPL FIXME iftex FSF's
10851 @c LocalWords: akim fn cp syncodeindex vr tp synindex dircategory direntry Naur
10852 @c LocalWords: ifset vskip pt filll insertcopying sp ISBN Etienne Suvasa Multi
10853 @c LocalWords: ifnottex yyparse detailmenu GLR RPN Calc var Decls Rpcalc multi
10854 @c LocalWords: rpcalc Lexer Expr ltcalc mfcalc yylex defaultprec Donnelly Gotos
10855 @c LocalWords: yyerror pxref LR yylval cindex dfn LALR samp gpl BNF xref yypush
10856 @c LocalWords: const int paren ifnotinfo AC noindent emph expr stmt findex lr
10857 @c LocalWords: glr YYSTYPE TYPENAME prog dprec printf decl init stmtMerge POSIX
10858 @c LocalWords: pre STDC GNUC endif yy YY alloca lf stddef stdlib YYDEBUG yypull
10859 @c LocalWords: NUM exp subsubsection kbd Ctrl ctype EOF getchar isdigit nonfree
10860 @c LocalWords: ungetc stdin scanf sc calc ulator ls lm cc NEG prec yyerrok rr
10861 @c LocalWords: longjmp fprintf stderr yylloc YYLTYPE cos ln Stallman Destructor
10862 @c LocalWords: smallexample symrec val tptr FNCT fnctptr func struct sym enum
10863 @c LocalWords: fnct putsym getsym fname arith fncts atan ptr malloc sizeof Lex
10864 @c LocalWords: strlen strcpy fctn strcmp isalpha symbuf realloc isalnum DOTDOT
10865 @c LocalWords: ptypes itype YYPRINT trigraphs yytname expseq vindex dtype Unary
10866 @c LocalWords: Rhs YYRHSLOC LE nonassoc op deffn typeless yynerrs nonterminal
10867 @c LocalWords: yychar yydebug msg YYNTOKENS YYNNTS YYNRULES YYNSTATES reentrant
10868 @c LocalWords: cparse clex deftypefun NE defmac YYACCEPT YYABORT param yypstate
10869 @c LocalWords: strncmp intval tindex lvalp locp llocp typealt YYBACKUP subrange
10870 @c LocalWords: YYEMPTY YYEOF YYRECOVERING yyclearin GE def UMINUS maybeword loc
10871 @c LocalWords: Johnstone Shamsa Sadaf Hussain Tomita TR uref YYMAXDEPTH inline
10872 @c LocalWords: YYINITDEPTH stmnts ref stmnt initdcl maybeasm notype Lookahead
10873 @c LocalWords: hexflag STR exdent itemset asis DYYDEBUG YYFPRINTF args Autoconf
10874 @c LocalWords: infile ypp yxx outfile itemx tex leaderfill Troubleshouting sqrt
10875 @c LocalWords: hbox hss hfill tt ly yyin fopen fclose ofirst gcc ll lookahead
10876 @c LocalWords: nbar yytext fst snd osplit ntwo strdup AST Troublereporting th
10877 @c LocalWords: YYSTACK DVI fdl printindex IELR nondeterministic nonterminals ps
10878 @c LocalWords: subexpressions declarator nondeferred config libintl postfix
10879 @c LocalWords: preprocessor nonpositive unary nonnumeric typedef extern rhs
10880 @c LocalWords: yytokentype filename destructor multicharacter nonnull EBCDIC
10881 @c LocalWords: lvalue nonnegative XNUM CHR chr TAGLESS tagless stdout api TOK
10882 @c LocalWords: destructors Reentrancy nonreentrant subgrammar nonassociative
10883 @c LocalWords: deffnx namespace xml goto lalr ielr runtime lex yacc yyps env
10884 @c LocalWords: yystate variadic Unshift NLS gettext po UTF Automake LOCALEDIR
10885 @c LocalWords: YYENABLE bindtextdomain Makefile DEFS CPPFLAGS DBISON DeRemer
10886 @c LocalWords: autoreconf Pennello multisets nondeterminism Generalised baz
10887 @c LocalWords: redeclare automata Dparse localedir datadir XSLT midrule Wno
10888 @c LocalWords: makefiles Graphviz multitable headitem hh basename Doxygen fno
10889 @c LocalWords: doxygen ival sval deftypemethod deallocate pos deftypemethodx
10890 @c LocalWords: Ctor defcv defcvx arg accessors arithmetics CPP ifndef CALCXX
10891 @c LocalWords: lexer's calcxx bool LPAREN RPAREN deallocation cerrno climits
10892 @c LocalWords: cstdlib Debian undef yywrap unput noyywrap nounput zA yyleng
10893 @c LocalWords: errno strtol ERANGE str strerror iostream argc argv Javadoc
10894 @c LocalWords: bytecode initializers superclass stype ASTNode autoboxing nls
10895 @c LocalWords: toString deftypeivar deftypeivarx deftypeop YYParser strictfp
10896 @c LocalWords: superclasses boolean getErrorVerbose setErrorVerbose deftypecv
10897 @c LocalWords: getDebugStream setDebugStream getDebugLevel setDebugLevel url
10898 @c LocalWords: bisonVersion deftypecvx bisonSkeleton getStartPos getEndPos
10899 @c LocalWords: getLVal defvar YYFAIL deftypefn deftypefnx gotos msgfmt
10900 @c LocalWords: subdirectory Solaris nonassociativity