]> git.saurik.com Git - bison.git/blob - doc/bison.texinfo
doc: comment changes.
[bison.git] / doc / bison.texinfo
1 \input texinfo @c -*-texinfo-*-
2 @comment %**start of header
3 @setfilename bison.info
4 @include version.texi
5 @settitle Bison @value{VERSION}
6 @setchapternewpage odd
7
8 @finalout
9
10 @c SMALL BOOK version
11 @c This edition has been formatted so that you can format and print it in
12 @c the smallbook format.
13 @c @smallbook
14
15 @c Set following if you want to document %default-prec and %no-default-prec.
16 @c This feature is experimental and may change in future Bison versions.
17 @c @set defaultprec
18
19 @ifnotinfo
20 @syncodeindex fn cp
21 @syncodeindex vr cp
22 @syncodeindex tp cp
23 @end ifnotinfo
24 @ifinfo
25 @synindex fn cp
26 @synindex vr cp
27 @synindex tp cp
28 @end ifinfo
29 @comment %**end of header
30
31 @copying
32
33 This manual (@value{UPDATED}) is for @acronym{GNU} Bison (version
34 @value{VERSION}), the @acronym{GNU} parser generator.
35
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.
39
40 @quotation
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.''
48
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
52 freedom.''
53 @end quotation
54 @end copying
55
56 @dircategory Software development
57 @direntry
58 * bison: (bison). @acronym{GNU} parser generator (Yacc replacement).
59 @end direntry
60
61 @titlepage
62 @title Bison
63 @subtitle The Yacc-compatible Parser Generator
64 @subtitle @value{UPDATED}, Bison Version @value{VERSION}
65
66 @author by Charles Donnelly and Richard Stallman
67
68 @page
69 @vskip 0pt plus 1filll
70 @insertcopying
71 @sp 2
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
77 @sp 2
78 Cover art by Etienne Suvasa.
79 @end titlepage
80
81 @contents
82
83 @ifnottex
84 @node Top
85 @top Bison
86 @insertcopying
87 @end ifnottex
88
89 @menu
90 * Introduction::
91 * Conditions::
92 * Copying:: The @acronym{GNU} General Public License says
93 how you can copy and share Bison.
94
95 Tutorial sections:
96 * Concepts:: Basic concepts for understanding Bison.
97 * Examples:: Three simple explained examples of using Bison.
98
99 Reference sections:
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.
114
115 @detailmenu
116 --- The Detailed Node Listing ---
117
118 The Concepts of Bison
119
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.
133
134 Writing @acronym{GLR} Parsers
135
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.
140
141 Examples
142
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.
152
153 Reverse Polish Notation Calculator
154
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.
162
163 Grammar Rules for @code{rpcalc}
164
165 * Rpcalc Input::
166 * Rpcalc Line::
167 * Rpcalc Expr::
168
169 Location Tracking Calculator: @code{ltcalc}
170
171 * Ltcalc Declarations:: Bison and C declarations for ltcalc.
172 * Ltcalc Rules:: Grammar rules for ltcalc, with explanations.
173 * Ltcalc Lexer:: The lexical analyzer.
174
175 Multi-Function Calculator: @code{mfcalc}
176
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.
180
181 Bison Grammar Files
182
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.
191
192 Outline of a Bison Grammar
193
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.
199
200 Defining Language Semantics
201
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.
209
210 Tracking Locations
211
212 * Location Type:: Specifying a data type for locations.
213 * Actions and Locations:: Using locations in actions.
214 * Location Default Action:: Defining a general way to compute locations.
215
216 Bison Declarations
217
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.
230
231 Parser C-Language Interface
232
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}
239 which reads tokens.
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
243 native language.
244
245 The Lexical Analyzer Function @code{yylex}
246
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
252 actions want that.
253 * Pure Calling:: How the calling convention differs in a pure parser
254 (@pxref{Pure Decl, ,A Pure (Reentrant) Parser}).
255
256 The Bison Parser Algorithm
257
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.
267
268 Operator Precedence
269
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.
275
276 Handling Context Dependencies
277
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.
282
283 Debugging Your Parser
284
285 * Understanding:: Understanding the structure of your parser.
286 * Tracing:: Tracing the execution of your parser.
287
288 Invoking Bison
289
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}.
294
295 Parsers Written In Other Languages
296
297 * C++ Parsers:: The interface to generate C++ parser classes
298 * Java Parsers:: The interface to generate Java parser classes
299
300 C++ Parsers
301
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
308
309 A Complete C++ Example
310
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
316
317 Java Parsers
318
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
327
328 Frequently Asked Questions
329
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
342
343 Copying This Manual
344
345 * Copying This Manual:: License for copying this manual.
346
347 @end detailmenu
348 @end menu
349
350 @node Introduction
351 @unnumbered Introduction
352 @cindex introduction
353
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.
361
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.
366
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.
371
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.
375
376 This edition corresponds to version @value{VERSION} of Bison.
377
378 @node Conditions
379 @unnumbered Conditions for Using Bison
380
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.
386
387 The other @acronym{GNU} programming tools, such as the @acronym{GNU} C
388 compiler, have never
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.
393
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.
401
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.
408
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
413 exception.
414
415 @node Copying
416 @unnumbered GNU GENERAL PUBLIC LICENSE
417 @include gpl-3.0.texi
418
419 @node Concepts
420 @chapter The Concepts of Bison
421
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.
425
426 @menu
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.
440 @end menu
441
442 @node Language and Grammar
443 @section Languages and Context-Free Grammars
444
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
455 recursion.
456
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}.
464
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.
480
481 @cindex @acronym{GLR} parsing
482 @cindex generalized @acronym{LR} (@acronym{GLR}) parsing
483 @cindex ambiguous grammars
484 @cindex nondeterministic parsing
485
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.
499
500 @cindex symbols (abstract)
501 @cindex token
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}.
511
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.)
521
522 Here is a simple C function subdivided into tokens:
523
524 @ifinfo
525 @example
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} */
533 @end example
534 @end ifinfo
535 @ifnotinfo
536 @example
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} */
542 @end example
543 @end ifnotinfo
544
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}.
553
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:
558
559 @quotation
560 A `statement' can be made of a `return' keyword, an `expression' and a
561 `semicolon'.
562 @end quotation
563
564 @noindent
565 There would be many other rules for `statement', one for each kind of
566 statement in C.
567
568 @cindex start symbol
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'
573 plays this role.
574
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.
579
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.
586
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
592
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}.
596
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}.
600
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.
608 @xref{Symbols}.
609
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.
614
615 A third way to represent a terminal symbol is with a C string constant
616 containing several characters. @xref{Symbols}, for more information.
617
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
622 used in every rule.
623
624 @example
625 stmt: RETURN expr ';'
626 ;
627 @end example
628
629 @noindent
630 @xref{Rules, ,Syntax of Grammar Rules}.
631
632 @node Semantic Values
633 @section Semantic Values
634 @cindex semantic value
635 @cindex value, semantic
636
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
642 grammatical.
643
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},
649 for details.
650
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
655 except their types.
656
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.)
661
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.
668
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.
674
675 @node Semantic Actions
676 @section Semantic Actions
677 @cindex semantic actions
678 @cindex actions, semantic
679
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.
684 @xref{Actions}.
685
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.
693
694 For example, here is a rule that says an expression can be the sum of
695 two subexpressions:
696
697 @example
698 expr: expr '+' expr @{ $$ = $1 + $3; @}
699 ;
700 @end example
701
702 @noindent
703 The action says how to produce the semantic value of the sum expression
704 from the values of the two subexpressions.
705
706 @node GLR Parsers
707 @section Writing @acronym{GLR} Parsers
708 @cindex @acronym{GLR} parsing
709 @cindex generalized @acronym{LR} (@acronym{GLR}) parsing
710 @findex %glr-parser
711 @cindex conflicts
712 @cindex shift/reduce conflicts
713 @cindex reduce/reduce conflicts
714
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}).
724
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.
743
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
753 merged result.
754
755 @menu
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.
760 @end menu
761
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
766 @findex %glr-parser
767 @findex %expect-rr
768 @cindex conflicts
769 @cindex reduce/reduce conflicts
770 @cindex shift/reduce conflicts
771
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.
775
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:
779
780 @example
781 type subrange = lo .. hi;
782 type enum = (a, b, c);
783 @end example
784
785 @noindent
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
792 parentheses:
793
794 @example
795 type subrange = (a) .. b;
796 @end example
797
798 @noindent
799 Compare this to the following declaration of an enumerated
800 type with only one value:
801
802 @example
803 type enum = (a);
804 @end example
805
806 @noindent
807 (These declarations are contrived, but they are syntactically
808 valid, and more-complicated cases can come up in practical programs.)
809
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.
818
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
823 expressions.
824
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
831 work.
832
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.
844
845 If the input is syntactically incorrect, both branches fail and the parser
846 reports a syntax error as usual.
847
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.
853
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.
863
864 Here is a Bison grammar corresponding to the example above. It
865 parses a vastly simplified form of Pascal type declarations.
866
867 @example
868 %token TYPE DOTDOT ID
869
870 @group
871 %left '+' '-'
872 %left '*' '/'
873 @end group
874
875 %%
876
877 @group
878 type_decl : TYPE ID '=' type ';'
879 ;
880 @end group
881
882 @group
883 type : '(' id_list ')'
884 | expr DOTDOT expr
885 ;
886 @end group
887
888 @group
889 id_list : ID
890 | id_list ',' ID
891 ;
892 @end group
893
894 @group
895 expr : '(' expr ')'
896 | expr '+' expr
897 | expr '-' expr
898 | expr '*' expr
899 | expr '/' expr
900 | ID
901 ;
902 @end group
903 @end example
904
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
909 recognized:
910
911 @example
912 type t = (a) .. b;
913 @end example
914
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
918 @samp{%%}):
919
920 @example
921 %glr-parser
922 %expect-rr 1
923 @end example
924
925 @noindent
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.
930
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
944 correctness.
945
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.
952
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
957 @findex %dprec
958 @findex %merge
959 @cindex conflicts
960 @cindex reduce/reduce conflicts
961
962 Let's consider an example, vastly simplified from a C++ grammar.
963
964 @example
965 %@{
966 #include <stdio.h>
967 #define YYSTYPE char const *
968 int yylex (void);
969 void yyerror (char const *);
970 %@}
971
972 %token TYPENAME ID
973
974 %right '='
975 %left '+'
976
977 %glr-parser
978
979 %%
980
981 prog :
982 | prog stmt @{ printf ("\n"); @}
983 ;
984
985 stmt : expr ';' %dprec 1
986 | decl %dprec 2
987 ;
988
989 expr : ID @{ printf ("%s ", $$); @}
990 | TYPENAME '(' expr ')'
991 @{ printf ("%s <cast> ", $1); @}
992 | expr '+' expr @{ printf ("+ "); @}
993 | expr '=' expr @{ printf ("= "); @}
994 ;
995
996 decl : TYPENAME declarator ';'
997 @{ printf ("%s <declare> ", $1); @}
998 | TYPENAME declarator '=' expr ';'
999 @{ printf ("%s <init-declare> ", $1); @}
1000 ;
1001
1002 declarator : ID @{ printf ("\"%s\" ", $1); @}
1003 | '(' declarator ')'
1004 ;
1005 @end example
1006
1007 @noindent
1008 This models a problematic part of the C++ grammar---the ambiguity between
1009 certain declarations and statements. For example,
1010
1011 @example
1012 T (x) = y+z;
1013 @end example
1014
1015 @noindent
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.}
1030
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
1038
1039 @example
1040 "x" y z + T <init-declare>
1041 @end example
1042
1043 The @code{%dprec} declarations only come into play when more than one
1044 parse survives. Consider a different input string for this parser:
1045
1046 @example
1047 T (x) + y;
1048 @end example
1049
1050 @noindent
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
1061
1062 @example
1063 x T <cast> y +
1064 @end example
1065
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
1070 follows:
1071
1072 @example
1073 stmt : expr ';' %merge <stmtMerge>
1074 | decl %merge <stmtMerge>
1075 ;
1076 @end example
1077
1078 @noindent
1079 and define the @code{stmtMerge} function as:
1080
1081 @example
1082 static YYSTYPE
1083 stmtMerge (YYSTYPE x0, YYSTYPE x1)
1084 @{
1085 printf ("<OR> ");
1086 return "";
1087 @}
1088 @end example
1089
1090 @noindent
1091 with an accompanying forward declaration
1092 in the C declarations at the beginning of the file:
1093
1094 @example
1095 %@{
1096 #define YYSTYPE char const *
1097 static YYSTYPE stmtMerge (YYSTYPE x0, YYSTYPE x1);
1098 %@}
1099 @end example
1100
1101 @noindent
1102 With these declarations, the resulting parser parses the first example
1103 as both an @code{expr} and a @code{decl}, and prints
1104
1105 @example
1106 "x" y z + T <init-declare> x T <cast> y z + = <OR>
1107 @end example
1108
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.
1114
1115 @node GLR Semantic Actions
1116 @subsection GLR Semantic Actions
1117
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.
1123
1124 @vindex yychar
1125 @cindex @acronym{GLR} parsers and @code{yychar}
1126 @vindex yylval
1127 @cindex @acronym{GLR} parsers and @code{yylval}
1128 @vindex yylloc
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}.
1138
1139 @findex yyclearin
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}.
1150
1151 @findex YYERROR
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.
1160
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.
1163
1164 @node Compiler Requirements
1165 @subsection Considerations when Compiling @acronym{GLR} Parsers
1166 @cindex @code{inline}
1167 @cindex @acronym{GLR} parsers and @code{inline}
1168
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
1175
1176 @example
1177 %@{
1178 #include <config.h>
1179 %@}
1180 @end example
1181
1182 @noindent
1183 will suffice. Otherwise, we suggest
1184
1185 @example
1186 %@{
1187 #if __STDC_VERSION__ < 199901 && ! defined __GNUC__ && ! defined inline
1188 #define inline
1189 #endif
1190 %@}
1191 @end example
1192
1193 @node Locations Overview
1194 @section Locations
1195 @cindex location
1196 @cindex textual location
1197 @cindex location, textual
1198
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.
1203
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).
1208
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
1212 @code{@@3}.
1213
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.
1221
1222 @node Bison Parser
1223 @section Bison Output: the Parser File
1224 @cindex Bison parser
1225 @cindex Bison utility
1226 @cindex lexical analyzer, purpose
1227 @cindex parser
1228
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
1234 program.
1235
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
1239 uses.
1240
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}}.
1248
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}.
1257
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
1268 meanings.
1269
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}).
1279
1280 @node Stages
1281 @section Stages in Using Bison
1282 @cindex stages in using Bison
1283 @cindex using Bison
1284
1285 The actual language-design process using Bison, from grammar specification
1286 to a working compiler or interpreter, has these parts:
1287
1288 @enumerate
1289 @item
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.
1295
1296 @item
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.
1301
1302 @item
1303 Write a controlling function that calls the Bison-produced parser.
1304
1305 @item
1306 Write error-reporting routines.
1307 @end enumerate
1308
1309 To turn this source code as written into a runnable program, you
1310 must follow these steps:
1311
1312 @enumerate
1313 @item
1314 Run Bison on the grammar to produce the parser.
1315
1316 @item
1317 Compile the code output by Bison, as well as any other source files.
1318
1319 @item
1320 Link the object files to produce the finished product.
1321 @end enumerate
1322
1323 @node Grammar Layout
1324 @section The Overall Layout of a Bison Grammar
1325 @cindex grammar file
1326 @cindex file format
1327 @cindex format of grammar file
1328 @cindex layout of Bison grammar
1329
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:
1332
1333 @example
1334 %@{
1335 @var{Prologue}
1336 %@}
1337
1338 @var{Bison declarations}
1339
1340 %%
1341 @var{Grammar rules}
1342 %%
1343 @var{Epilogue}
1344 @end example
1345
1346 @noindent
1347 The @samp{%%}, @samp{%@{} and @samp{%@}} are punctuation that appears
1348 in every Bison grammar file to separate the sections.
1349
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.
1356
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.
1360
1361 The grammar rules define how to construct each nonterminal symbol from its
1362 parts.
1363
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.
1367
1368 @node Examples
1369 @chapter Examples
1370 @cindex simple examples
1371 @cindex examples, simple
1372
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.
1378
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.
1382
1383 @menu
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.
1393 @end menu
1394
1395 @node RPN Calc
1396 @section Reverse Polish Notation Calculator
1397 @cindex reverse polish notation
1398 @cindex polish notation calculator
1399 @cindex @code{rpcalc}
1400 @cindex calculator, simple
1401
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.
1406
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.
1409
1410 @menu
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.
1418 @end menu
1419
1420 @node Rpcalc Declarations
1421 @subsection Declarations for @code{rpcalc}
1422
1423 Here are the C and Bison declarations for the reverse polish notation
1424 calculator. As in C, comments are placed between @samp{/*@dots{}*/}.
1425
1426 @example
1427 /* Reverse polish notation calculator. */
1428
1429 %@{
1430 #define YYSTYPE double
1431 #include <math.h>
1432 int yylex (void);
1433 void yyerror (char const *);
1434 %@}
1435
1436 %token NUM
1437
1438 %% /* Grammar rules and actions follow. */
1439 @end example
1440
1441 The declarations section (@pxref{Prologue, , The prologue}) contains two
1442 preprocessor directives and two forward declarations.
1443
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.
1451
1452 The @code{#include} directive is used to declare the exponentiation
1453 function @code{pow}.
1454
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
1459 prologue.
1460
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.
1469
1470 @node Rpcalc Rules
1471 @subsection Grammar Rules for @code{rpcalc}
1472
1473 Here are the grammar rules for the reverse polish notation calculator.
1474
1475 @example
1476 input: /* empty */
1477 | input line
1478 ;
1479
1480 line: '\n'
1481 | exp '\n' @{ printf ("\t%.10g\n", $1); @}
1482 ;
1483
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); @}
1491 /* Unary minus */
1492 | exp 'n' @{ $$ = -$1; @}
1493 ;
1494 %%
1495 @end example
1496
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
1502 mean.
1503
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}.
1507
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.
1514
1515 @menu
1516 * Rpcalc Input::
1517 * Rpcalc Line::
1518 * Rpcalc Expr::
1519 @end menu
1520
1521 @node Rpcalc Input
1522 @subsubsection Explanation of @code{input}
1523
1524 Consider the definition of @code{input}:
1525
1526 @example
1527 input: /* empty */
1528 | input line
1529 ;
1530 @end example
1531
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}.
1537
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.
1544
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
1549 more times.
1550
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.
1554
1555 @node Rpcalc Line
1556 @subsubsection Explanation of @code{line}
1557
1558 Now consider the definition of @code{line}:
1559
1560 @example
1561 line: '\n'
1562 | exp '\n' @{ printf ("\t%.10g\n", $1); @}
1563 ;
1564 @end example
1565
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.
1573
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.
1579
1580 @node Rpcalc Expr
1581 @subsubsection Explanation of @code{expr}
1582
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.
1587
1588 @example
1589 exp: NUM
1590 | exp exp '+' @{ $$ = $1 + $2; @}
1591 | exp exp '-' @{ $$ = $1 - $2; @}
1592 @dots{}
1593 ;
1594 @end example
1595
1596 We have used @samp{|} to join all the rules for @code{exp}, but we could
1597 equally well have written them separately:
1598
1599 @example
1600 exp: NUM ;
1601 exp: exp exp '+' @{ $$ = $1 + $2; @} ;
1602 exp: exp exp '-' @{ $$ = $1 - $2; @} ;
1603 @dots{}
1604 @end example
1605
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}.
1614
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}).
1618
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.
1621 For example, this:
1622
1623 @example
1624 exp : NUM | exp exp '+' @{$$ = $1 + $2; @} | @dots{} ;
1625 @end example
1626
1627 @noindent
1628 means the same thing as this:
1629
1630 @example
1631 exp: NUM
1632 | exp exp '+' @{ $$ = $1 + $2; @}
1633 | @dots{}
1634 ;
1635 @end example
1636
1637 @noindent
1638 The latter, however, is much more readable.
1639
1640 @node Rpcalc Lexer
1641 @subsection The @code{rpcalc} Lexical Analyzer
1642 @cindex writing a lexical analyzer
1643 @cindex lexical analyzer, writing
1644
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}}.
1649
1650 Only a simple lexical analyzer is needed for the @acronym{RPN}
1651 calculator. This
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.
1656
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.
1666
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}}.)
1672
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.)
1675
1676 Here is the code for the lexical analyzer:
1677
1678 @example
1679 @group
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. */
1684
1685 #include <ctype.h>
1686 @end group
1687
1688 @group
1689 int
1690 yylex (void)
1691 @{
1692 int c;
1693
1694 /* Skip white space. */
1695 while ((c = getchar ()) == ' ' || c == '\t')
1696 ;
1697 @end group
1698 @group
1699 /* Process numbers. */
1700 if (c == '.' || isdigit (c))
1701 @{
1702 ungetc (c, stdin);
1703 scanf ("%lf", &yylval);
1704 return NUM;
1705 @}
1706 @end group
1707 @group
1708 /* Return end-of-input. */
1709 if (c == EOF)
1710 return 0;
1711 /* Return a single char. */
1712 return c;
1713 @}
1714 @end group
1715 @end example
1716
1717 @node Rpcalc Main
1718 @subsection The Controlling Function
1719 @cindex controlling function
1720 @cindex main function in simple example
1721
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.
1725
1726 @example
1727 @group
1728 int
1729 main (void)
1730 @{
1731 return yyparse ();
1732 @}
1733 @end group
1734 @end example
1735
1736 @node Rpcalc Error
1737 @subsection The Error Reporting Routine
1738 @cindex error reporting routine
1739
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:
1745
1746 @example
1747 @group
1748 #include <stdio.h>
1749
1750 /* Called by yyparse on error. */
1751 void
1752 yyerror (char const *s)
1753 @{
1754 fprintf (stderr, "%s\n", s);
1755 @}
1756 @end group
1757 @end example
1758
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.
1765
1766 @node Rpcalc Generate
1767 @subsection Running Bison to Make the Parser
1768 @cindex running Bison (introduction)
1769
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}).
1776
1777 For a large project, you would probably have several source files, and use
1778 @code{make} to arrange to recompile them.
1779
1780 With all the source in a single file, you use the following command to
1781 convert it into a parser file:
1782
1783 @example
1784 bison @var{file}.y
1785 @end example
1786
1787 @noindent
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.
1794
1795 @node Rpcalc Compile
1796 @subsection Compiling the Parser File
1797 @cindex compiling the parser
1798
1799 Here is how to compile and run the parser file:
1800
1801 @example
1802 @group
1803 # @r{List files in current directory.}
1804 $ @kbd{ls}
1805 rpcalc.tab.c rpcalc.y
1806 @end group
1807
1808 @group
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}
1812 @end group
1813
1814 @group
1815 # @r{List files again.}
1816 $ @kbd{ls}
1817 rpcalc rpcalc.tab.c rpcalc.y
1818 @end group
1819 @end example
1820
1821 The file @file{rpcalc} now contains the executable code. Here is an
1822 example session using @code{rpcalc}.
1823
1824 @example
1825 $ @kbd{rpcalc}
1826 @kbd{4 9 +}
1827 13
1828 @kbd{3 7 + 3 4 5 *+-}
1829 -13
1830 @kbd{3 7 + 3 4 5 * + - n} @r{Note the unary minus, @samp{n}}
1831 13
1832 @kbd{5 6 / 4 n +}
1833 -3.166666667
1834 @kbd{3 4 ^} @r{Exponentiation}
1835 81
1836 @kbd{^D} @r{End-of-file indicator}
1837 $
1838 @end example
1839
1840 @node Infix Calc
1841 @section Infix Notation Calculator: @code{calc}
1842 @cindex infix notation calculator
1843 @cindex @code{calc}
1844 @cindex calculator, infix notation
1845
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.
1850
1851 @example
1852 /* Infix notation calculator. */
1853
1854 %@{
1855 #define YYSTYPE double
1856 #include <math.h>
1857 #include <stdio.h>
1858 int yylex (void);
1859 void yyerror (char const *);
1860 %@}
1861
1862 /* Bison declarations. */
1863 %token NUM
1864 %left '-' '+'
1865 %left '*' '/'
1866 %precedence NEG /* negation--unary minus */
1867 %right '^' /* exponentiation */
1868
1869 %% /* The grammar follows. */
1870 input: /* empty */
1871 | input line
1872 ;
1873
1874 line: '\n'
1875 | exp '\n' @{ printf ("\t%.10g\n", $1); @}
1876 ;
1877
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; @}
1886 ;
1887 %%
1888 @end example
1889
1890 @noindent
1891 The functions @code{yylex}, @code{yyerror} and @code{main} can be the
1892 same as before.
1893
1894 There are two important new features shown in this code.
1895
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.)
1903
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
1910 Precedence}.
1911
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}.
1917
1918 Here is a sample run of @file{calc.y}:
1919
1920 @need 500
1921 @example
1922 $ @kbd{calc}
1923 @kbd{4 + 4.5 - (34/(8*3+-3))}
1924 6.880952381
1925 @kbd{-56 + 2}
1926 -54
1927 @kbd{3 ^ 2}
1928 9
1929 @end example
1930
1931 @node Simple Error Recovery
1932 @section Simple Error Recovery
1933 @cindex error recovery, simple
1934
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.
1941
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}:
1945
1946 @example
1947 @group
1948 line: '\n'
1949 | exp '\n' @{ printf ("\t%.10g\n", $1); @}
1950 | error '\n' @{ yyerrok; @}
1951 ;
1952 @end group
1953 @end example
1954
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
1963 misprint.
1964
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
1971 Bison programs.
1972
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
1978
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
1983 analyzer.
1984
1985 @menu
1986 * Ltcalc Declarations:: Bison and C declarations for ltcalc.
1987 * Ltcalc Rules:: Grammar rules for ltcalc, with explanations.
1988 * Ltcalc Lexer:: The lexical analyzer.
1989 @end menu
1990
1991 @node Ltcalc Declarations
1992 @subsection Declarations for @code{ltcalc}
1993
1994 The C and Bison declarations for the location tracking calculator are
1995 the same as the declarations for the infix notation calculator.
1996
1997 @example
1998 /* Location tracking calculator. */
1999
2000 %@{
2001 #define YYSTYPE int
2002 #include <math.h>
2003 int yylex (void);
2004 void yyerror (char const *);
2005 %@}
2006
2007 /* Bison declarations. */
2008 %token NUM
2009
2010 %left '-' '+'
2011 %left '*' '/'
2012 %precedence NEG
2013 %right '^'
2014
2015 %% /* The grammar follows. */
2016 @end example
2017
2018 @noindent
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
2026 start at 1.
2027
2028 @node Ltcalc Rules
2029 @subsection Grammar Rules for @code{ltcalc}
2030
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.
2035
2036 Here, we will use locations to report divisions by zero, and locate the
2037 wrong expressions or subexpressions.
2038
2039 @example
2040 @group
2041 input : /* empty */
2042 | input line
2043 ;
2044 @end group
2045
2046 @group
2047 line : '\n'
2048 | exp '\n' @{ printf ("%d\n", $1); @}
2049 ;
2050 @end group
2051
2052 @group
2053 exp : NUM @{ $$ = $1; @}
2054 | exp '+' exp @{ $$ = $1 + $3; @}
2055 | exp '-' exp @{ $$ = $1 - $3; @}
2056 | exp '*' exp @{ $$ = $1 * $3; @}
2057 @end group
2058 @group
2059 | exp '/' exp
2060 @{
2061 if ($3)
2062 $$ = $1 / $3;
2063 else
2064 @{
2065 $$ = 1;
2066 fprintf (stderr, "%d.%d-%d.%d: division by zero",
2067 @@3.first_line, @@3.first_column,
2068 @@3.last_line, @@3.last_column);
2069 @}
2070 @}
2071 @end group
2072 @group
2073 | '-' exp %prec NEG @{ $$ = -$2; @}
2074 | exp '^' exp @{ $$ = pow ($1, $3); @}
2075 | '(' exp ')' @{ $$ = $2; @}
2076 @end group
2077 @end example
2078
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.
2082
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
2089 hand.
2090
2091 @node Ltcalc Lexer
2092 @subsection The @code{ltcalc} Lexical Analyzer.
2093
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
2097 semantic values.
2098
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:
2101
2102 @example
2103 @group
2104 int
2105 yylex (void)
2106 @{
2107 int c;
2108 @end group
2109
2110 @group
2111 /* Skip white space. */
2112 while ((c = getchar ()) == ' ' || c == '\t')
2113 ++yylloc.last_column;
2114 @end group
2115
2116 @group
2117 /* Step. */
2118 yylloc.first_line = yylloc.last_line;
2119 yylloc.first_column = yylloc.last_column;
2120 @end group
2121
2122 @group
2123 /* Process numbers. */
2124 if (isdigit (c))
2125 @{
2126 yylval = c - '0';
2127 ++yylloc.last_column;
2128 while (isdigit (c = getchar ()))
2129 @{
2130 ++yylloc.last_column;
2131 yylval = yylval * 10 + c - '0';
2132 @}
2133 ungetc (c, stdin);
2134 return NUM;
2135 @}
2136 @end group
2137
2138 /* Return end-of-input. */
2139 if (c == EOF)
2140 return 0;
2141
2142 /* Return a single char, and update location. */
2143 if (c == '\n')
2144 @{
2145 ++yylloc.last_line;
2146 yylloc.last_column = 0;
2147 @}
2148 else
2149 ++yylloc.last_column;
2150 return c;
2151 @}
2152 @end example
2153
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.
2158
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:
2163
2164 @example
2165 @group
2166 int
2167 main (void)
2168 @{
2169 yylloc.first_line = yylloc.last_line = 1;
2170 yylloc.first_column = yylloc.last_column = 0;
2171 return yyparse ();
2172 @}
2173 @end group
2174 @end example
2175
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.
2179
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
2185
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.
2191
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:
2197
2198 @example
2199 @var{function_name} (@var{argument})
2200 @end example
2201
2202 @noindent
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:
2206
2207 @example
2208 $ @kbd{mfcalc}
2209 @kbd{pi = 3.141592653589}
2210 3.1415926536
2211 @kbd{sin(pi)}
2212 0.0000000000
2213 @kbd{alpha = beta1 = 2.3}
2214 2.3000000000
2215 @kbd{alpha}
2216 2.3000000000
2217 @kbd{ln(alpha)}
2218 0.8329091229
2219 @kbd{exp(ln(beta1))}
2220 2.3000000000
2221 $
2222 @end example
2223
2224 Note that multiple assignment and nested function calls are permitted.
2225
2226 @menu
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.
2230 @end menu
2231
2232 @node Mfcalc Declarations
2233 @subsection Declarations for @code{mfcalc}
2234
2235 Here are the C and Bison declarations for the multi-function calculator.
2236
2237 @smallexample
2238 @group
2239 %@{
2240 #include <math.h> /* For math functions, cos(), sin(), etc. */
2241 #include "calc.h" /* Contains definition of `symrec'. */
2242 int yylex (void);
2243 void yyerror (char const *);
2244 %@}
2245 @end group
2246 @group
2247 %union @{
2248 double val; /* For returning numbers. */
2249 symrec *tptr; /* For returning symbol-table pointers. */
2250 @}
2251 @end group
2252 %token <val> NUM /* Simple double precision number. */
2253 %token <tptr> VAR FNCT /* Variable and Function. */
2254 %type <val> exp
2255
2256 @group
2257 %right '='
2258 %left '-' '+'
2259 %left '*' '/'
2260 %precedence NEG /* negation--unary minus */
2261 %right '^' /* exponentiation */
2262 @end group
2263 %% /* The grammar follows. */
2264 @end smallexample
2265
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}).
2269
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}.
2274
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).
2280
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}.
2287
2288 @node Mfcalc Rules
2289 @subsection Grammar Rules for @code{mfcalc}
2290
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.
2294
2295 @smallexample
2296 @group
2297 input: /* empty */
2298 | input line
2299 ;
2300 @end group
2301
2302 @group
2303 line:
2304 '\n'
2305 | exp '\n' @{ printf ("\t%.10g\n", $1); @}
2306 | error '\n' @{ yyerrok; @}
2307 ;
2308 @end group
2309
2310 @group
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; @}
2322 ;
2323 @end group
2324 /* End of grammar. */
2325 %%
2326 @end smallexample
2327
2328 @node Mfcalc Symbol Table
2329 @subsection The @code{mfcalc} Symbol Table
2330 @cindex symbol table example
2331
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.
2336
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.
2340
2341 @smallexample
2342 @group
2343 /* Function type. */
2344 typedef double (*func_t) (double);
2345 @end group
2346
2347 @group
2348 /* Data type for links in the chain of symbols. */
2349 struct symrec
2350 @{
2351 char *name; /* name of symbol */
2352 int type; /* type of symbol: either VAR or FNCT */
2353 union
2354 @{
2355 double var; /* value of a VAR */
2356 func_t fnctptr; /* value of a FNCT */
2357 @} value;
2358 struct symrec *next; /* link field */
2359 @};
2360 @end group
2361
2362 @group
2363 typedef struct symrec symrec;
2364
2365 /* The symbol table: a chain of `struct symrec'. */
2366 extern symrec *sym_table;
2367
2368 symrec *putsym (char const *, int);
2369 symrec *getsym (char const *);
2370 @end group
2371 @end smallexample
2372
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:
2376
2377 @smallexample
2378 #include <stdio.h>
2379
2380 @group
2381 /* Called by yyparse on error. */
2382 void
2383 yyerror (char const *s)
2384 @{
2385 printf ("%s\n", s);
2386 @}
2387 @end group
2388
2389 @group
2390 struct init
2391 @{
2392 char const *fname;
2393 double (*fnct) (double);
2394 @};
2395 @end group
2396
2397 @group
2398 struct init const arith_fncts[] =
2399 @{
2400 "sin", sin,
2401 "cos", cos,
2402 "atan", atan,
2403 "ln", log,
2404 "exp", exp,
2405 "sqrt", sqrt,
2406 0, 0
2407 @};
2408 @end group
2409
2410 @group
2411 /* The symbol table: a chain of `struct symrec'. */
2412 symrec *sym_table;
2413 @end group
2414
2415 @group
2416 /* Put arithmetic functions in table. */
2417 void
2418 init_table (void)
2419 @{
2420 int i;
2421 symrec *ptr;
2422 for (i = 0; arith_fncts[i].fname != 0; i++)
2423 @{
2424 ptr = putsym (arith_fncts[i].fname, FNCT);
2425 ptr->value.fnctptr = arith_fncts[i].fnct;
2426 @}
2427 @}
2428 @end group
2429
2430 @group
2431 int
2432 main (void)
2433 @{
2434 init_table ();
2435 return yyparse ();
2436 @}
2437 @end group
2438 @end smallexample
2439
2440 By simply editing the initialization list and adding the necessary include
2441 files, you can add additional functions to the calculator.
2442
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.
2449
2450 @smallexample
2451 symrec *
2452 putsym (char const *sym_name, int sym_type)
2453 @{
2454 symrec *ptr;
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;
2461 sym_table = ptr;
2462 return ptr;
2463 @}
2464
2465 symrec *
2466 getsym (char const *sym_name)
2467 @{
2468 symrec *ptr;
2469 for (ptr = sym_table; ptr != (symrec *) 0;
2470 ptr = (symrec *)ptr->next)
2471 if (strcmp (ptr->name,sym_name) == 0)
2472 return ptr;
2473 return 0;
2474 @}
2475 @end smallexample
2476
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.
2481
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}.
2488
2489 No change is needed in the handling of numeric values and arithmetic
2490 operators in @code{yylex}.
2491
2492 @smallexample
2493 @group
2494 #include <ctype.h>
2495 @end group
2496
2497 @group
2498 int
2499 yylex (void)
2500 @{
2501 int c;
2502
2503 /* Ignore white space, get first nonwhite character. */
2504 while ((c = getchar ()) == ' ' || c == '\t');
2505
2506 if (c == EOF)
2507 return 0;
2508 @end group
2509
2510 @group
2511 /* Char starts a number => parse the number. */
2512 if (c == '.' || isdigit (c))
2513 @{
2514 ungetc (c, stdin);
2515 scanf ("%lf", &yylval.val);
2516 return NUM;
2517 @}
2518 @end group
2519
2520 @group
2521 /* Char starts an identifier => read the name. */
2522 if (isalpha (c))
2523 @{
2524 symrec *s;
2525 static char *symbuf = 0;
2526 static int length = 0;
2527 int i;
2528 @end group
2529
2530 @group
2531 /* Initially make the buffer long enough
2532 for a 40-character symbol name. */
2533 if (length == 0)
2534 length = 40, symbuf = (char *)malloc (length + 1);
2535
2536 i = 0;
2537 do
2538 @end group
2539 @group
2540 @{
2541 /* If buffer is full, make it bigger. */
2542 if (i == length)
2543 @{
2544 length *= 2;
2545 symbuf = (char *) realloc (symbuf, length + 1);
2546 @}
2547 /* Add this character to the buffer. */
2548 symbuf[i++] = c;
2549 /* Get another character. */
2550 c = getchar ();
2551 @}
2552 @end group
2553 @group
2554 while (isalnum (c));
2555
2556 ungetc (c, stdin);
2557 symbuf[i] = '\0';
2558 @end group
2559
2560 @group
2561 s = getsym (symbuf);
2562 if (s == 0)
2563 s = putsym (symbuf, VAR);
2564 yylval.tptr = s;
2565 return s->type;
2566 @}
2567
2568 /* Any other character is a token by itself. */
2569 return c;
2570 @}
2571 @end group
2572 @end smallexample
2573
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.
2577
2578 @node Exercises
2579 @section Exercises
2580 @cindex exercises
2581
2582 @enumerate
2583 @item
2584 Add some new functions from @file{math.h} to the initialization list.
2585
2586 @item
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}.
2590
2591 @item
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.
2594 @end enumerate
2595
2596 @node Grammar File
2597 @chapter Bison Grammar Files
2598
2599 Bison takes as input a context-free grammar specification and produces a
2600 C-language function that recognizes correct instances of the grammar.
2601
2602 The Bison grammar input file conventionally has a name ending in @samp{.y}.
2603 @xref{Invocation, ,Invoking Bison}.
2604
2605 @menu
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.
2614 @end menu
2615
2616 @node Grammar Outline
2617 @section Outline of a Bison Grammar
2618
2619 A Bison grammar file has four main sections, shown here with the
2620 appropriate delimiters:
2621
2622 @example
2623 %@{
2624 @var{Prologue}
2625 %@}
2626
2627 @var{Bison declarations}
2628
2629 %%
2630 @var{Grammar rules}
2631 %%
2632
2633 @var{Epilogue}
2634 @end example
2635
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.
2639
2640 @menu
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.
2646 @end menu
2647
2648 @node Prologue
2649 @subsection The prologue
2650 @cindex declarations section
2651 @cindex Prologue
2652 @cindex declarations
2653
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.
2661
2662 The @var{Prologue} section is terminated by the first occurrence
2663 of @samp{%@}} that is outside a comment, a string literal, or a
2664 character constant.
2665
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.
2673
2674 @smallexample
2675 %@{
2676 #define _GNU_SOURCE
2677 #include <stdio.h>
2678 #include "ptypes.h"
2679 %@}
2680
2681 %union @{
2682 long int n;
2683 tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */
2684 @}
2685
2686 %@{
2687 static void print_token_value (FILE *, int, YYSTYPE);
2688 #define YYPRINT(F, N, L) print_token_value (F, N, L)
2689 %@}
2690
2691 @dots{}
2692 @end smallexample
2693
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.
2700
2701 @node Prologue Alternatives
2702 @subsection Prologue Alternatives
2703 @cindex Prologue Alternatives
2704
2705 @findex %code
2706 @findex %code requires
2707 @findex %code provides
2708 @findex %code top
2709
2710 The functionality of @var{Prologue} sections can often be subtle and
2711 inflexible.
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}.
2718
2719 Look again at the example of the previous section:
2720
2721 @smallexample
2722 %@{
2723 #define _GNU_SOURCE
2724 #include <stdio.h>
2725 #include "ptypes.h"
2726 %@}
2727
2728 %union @{
2729 long int n;
2730 tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */
2731 @}
2732
2733 %@{
2734 static void print_token_value (FILE *, int, YYSTYPE);
2735 #define YYPRINT(F, N, L) print_token_value (F, N, L)
2736 %@}
2737
2738 @dots{}
2739 @end smallexample
2740
2741 @noindent
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
2746 definition?
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
2751 arguments?
2752 You should prototype it in the second since Bison will insert that code
2753 @emph{after} the @code{YYLTYPE} and @code{yytokentype} definitions.
2754
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.
2763
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:
2768
2769 @smallexample
2770 %code top @{
2771 #define _GNU_SOURCE
2772 #include <stdio.h>
2773
2774 /* WARNING: The following code really belongs
2775 * in a `%code requires'; see below. */
2776
2777 #include "ptypes.h"
2778 #define YYLTYPE YYLTYPE
2779 typedef struct YYLTYPE
2780 @{
2781 int first_line;
2782 int first_column;
2783 int last_line;
2784 int last_column;
2785 char *filename;
2786 @} YYLTYPE;
2787 @}
2788
2789 %union @{
2790 long int n;
2791 tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */
2792 @}
2793
2794 %code @{
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);
2798 @}
2799
2800 @dots{}
2801 @end smallexample
2802
2803 @noindent
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}.
2808
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.
2819
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}
2822 definitions.
2823 Thus, they belong in one or more @code{%code requires}:
2824
2825 @smallexample
2826 %code top @{
2827 #define _GNU_SOURCE
2828 #include <stdio.h>
2829 @}
2830
2831 %code requires @{
2832 #include "ptypes.h"
2833 @}
2834 %union @{
2835 long int n;
2836 tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */
2837 @}
2838
2839 %code requires @{
2840 #define YYLTYPE YYLTYPE
2841 typedef struct YYLTYPE
2842 @{
2843 int first_line;
2844 int first_column;
2845 int last_line;
2846 int last_column;
2847 char *filename;
2848 @} YYLTYPE;
2849 @}
2850
2851 %code @{
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);
2855 @}
2856
2857 @dots{}
2858 @end smallexample
2859
2860 @noindent
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}.)
2866
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}
2877 alternatives.
2878
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}:
2890
2891 @smallexample
2892 %code top @{
2893 #define _GNU_SOURCE
2894 #include <stdio.h>
2895 @}
2896
2897 %code requires @{
2898 #include "ptypes.h"
2899 @}
2900 %union @{
2901 long int n;
2902 tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */
2903 @}
2904
2905 %code requires @{
2906 #define YYLTYPE YYLTYPE
2907 typedef struct YYLTYPE
2908 @{
2909 int first_line;
2910 int first_column;
2911 int last_line;
2912 int last_column;
2913 char *filename;
2914 @} YYLTYPE;
2915 @}
2916
2917 %code provides @{
2918 void trace_token (enum yytokentype token, YYLTYPE loc);
2919 @}
2920
2921 %code @{
2922 static void print_token_value (FILE *, int, YYSTYPE);
2923 #define YYPRINT(F, N, L) print_token_value (F, N, L)
2924 @}
2925
2926 @dots{}
2927 @end smallexample
2928
2929 @noindent
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}.
2933
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
2937 @code{%code}.
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.
2941
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.
2946
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
2950 type:
2951
2952 @smallexample
2953 %code requires @{ #include "type1.h" @}
2954 %union @{ type1 field1; @}
2955 %destructor @{ type1_free ($$); @} <field1>
2956 %printer @{ type1_print ($$); @} <field1>
2957
2958 %code requires @{ #include "type2.h" @}
2959 %union @{ type2 field2; @}
2960 %destructor @{ type2_free ($$); @} <field2>
2961 %printer @{ type2_print ($$); @} <field2>
2962 @end smallexample
2963
2964 @noindent
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
2967 type.
2968 (In the rules section, you must terminate each of those directives with a
2969 semicolon.)
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.
2974
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}
2983 as needed.
2984
2985 @node Bison Declarations
2986 @subsection The Bison Declarations Section
2987 @cindex Bison declarations (introduction)
2988 @cindex declarations, Bison (introduction)
2989
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}.
2994
2995 @node Grammar Rules
2996 @subsection The Grammar Rules Section
2997 @cindex grammar rules section
2998 @cindex rules section for grammar
2999
3000 The @dfn{grammar rules} section contains one or more Bison grammar
3001 rules, and nothing else. @xref{Rules, ,Syntax of Grammar Rules}.
3002
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.
3006
3007 @node Epilogue
3008 @subsection The epilogue
3009 @cindex additional C code section
3010 @cindex epilogue
3011 @cindex C code, section for additional
3012
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}.
3022
3023 If the last section is empty, you may omit the @samp{%%} that separates it
3024 from the grammar rules.
3025
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.
3030
3031 @node Symbols
3032 @section Symbols, Terminal and Nonterminal
3033 @cindex nonterminal symbol
3034 @cindex terminal symbol
3035 @cindex token type
3036 @cindex symbol
3037
3038 @dfn{Symbols} in Bison grammars represent the grammatical classifications
3039 of the language.
3040
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.
3048
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.
3052
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
3058 token names.
3059
3060 There are three ways of writing terminal symbols in the grammar:
3061
3062 @itemize @bullet
3063 @item
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}.
3068
3069 @item
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}).
3080
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.
3086
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
3093 allowed.
3094
3095 @item
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}).
3104
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}).
3110
3111 @strong{Warning}: literal string tokens do not work in Yacc.
3112
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.
3118
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).
3125 @end itemize
3126
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.
3130
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}}.
3143
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}.
3149
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:
3155
3156 @example
3157 "\a\b\t\n\v\f\r !\"#%&'()*+,-./:;<=>?[\\]^_@{|@}~"
3158 @end example
3159
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
3170 compiling them.
3171
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.
3177
3178 @node Rules
3179 @section Syntax of Grammar Rules
3180 @cindex rule syntax
3181 @cindex grammar rule syntax
3182 @cindex syntax of grammar rules
3183
3184 A Bison grammar rule has the following general form:
3185
3186 @example
3187 @group
3188 @var{result}: @var{components}@dots{}
3189 ;
3190 @end group
3191 @end example
3192
3193 @noindent
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}).
3197
3198 For example,
3199
3200 @example
3201 @group
3202 exp: exp '+' exp
3203 ;
3204 @end group
3205 @end example
3206
3207 @noindent
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}.
3210
3211 White space in rules is significant only to separate symbols. You can add
3212 extra white space as you wish.
3213
3214 Scattered among the components can be @var{actions} that determine
3215 the semantics of the rule. An action looks like this:
3216
3217 @example
3218 @{@var{C statements}@}
3219 @end example
3220
3221 @noindent
3222 @cindex braced code
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.
3228
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.
3237
3238 Usually there is only one action and it follows the components.
3239 @xref{Actions}.
3240
3241 @findex |
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:
3244
3245 @example
3246 @group
3247 @var{result}: @var{rule1-components}@dots{}
3248 | @var{rule2-components}@dots{}
3249 @dots{}
3250 ;
3251 @end group
3252 @end example
3253
3254 @noindent
3255 They are still considered distinct rules even when joined in this way.
3256
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:
3260
3261 @example
3262 @group
3263 expseq: /* empty */
3264 | expseq1
3265 ;
3266 @end group
3267
3268 @group
3269 expseq1: exp
3270 | expseq1 ',' exp
3271 ;
3272 @end group
3273 @end example
3274
3275 @noindent
3276 It is customary to write a comment @samp{/* empty */} in each rule
3277 with no components.
3278
3279 @node Recursion
3280 @section Recursive Rules
3281 @cindex recursive rule
3282
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:
3288
3289 @example
3290 @group
3291 expseq1: exp
3292 | expseq1 ',' exp
3293 ;
3294 @end group
3295 @end example
3296
3297 @cindex left recursion
3298 @cindex right recursion
3299 @noindent
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}:
3303
3304 @example
3305 @group
3306 expseq1: exp
3307 | exp ',' expseq1
3308 ;
3309 @end group
3310 @end example
3311
3312 @noindent
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
3320 of this.
3321
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
3326 side.
3327
3328 For example:
3329
3330 @example
3331 @group
3332 expr: primary
3333 | primary '+' primary
3334 ;
3335 @end group
3336
3337 @group
3338 primary: constant
3339 | '(' expr ')'
3340 ;
3341 @end group
3342 @end example
3343
3344 @noindent
3345 defines two mutually-recursive nonterminals, since each refers to the
3346 other.
3347
3348 @node Semantics
3349 @section Defining Language Semantics
3350 @cindex defining language semantics
3351 @cindex language semantics, defining
3352
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.
3356
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}.
3361
3362 @menu
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.
3370 @end menu
3371
3372 @node Value Type
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
3378
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}).
3383
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:
3387
3388 @example
3389 #define YYSTYPE double
3390 @end example
3391
3392 @noindent
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}).
3397
3398 @node Multiple Types
3399 @subsection More Than One Value Type
3400
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
3405 symbol table.
3406
3407 To use more than one data type for semantic values in one parser, Bison
3408 requires you to do two things:
3409
3410 @itemize @bullet
3411 @item
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
3416 the type tags.
3417
3418 @item
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}).
3424 @end itemize
3425
3426 @node Actions
3427 @subsection Actions
3428 @cindex action
3429 @vindex $$
3430 @vindex $@var{n}
3431
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.
3436
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}).
3443
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.
3451
3452 Here is a typical example:
3453
3454 @example
3455 @group
3456 exp: @dots{}
3457 | exp '+' exp
3458 @{ $$ = $1 + $3; @}
3459 @end group
3460 @end example
3461
3462 @noindent
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}.
3471
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:
3477
3478 @example
3479 @group
3480 a-or-b: 'a'|'b' @{ a_or_b_found = 1; @};
3481 @end group
3482 @end example
3483
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.
3491
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:
3497
3498 @example
3499 @group
3500 foo: expr bar '+' expr @{ @dots{} @}
3501 | expr bar '-' expr @{ @dots{} @}
3502 ;
3503 @end group
3504
3505 @group
3506 bar: /* empty */
3507 @{ previous_expr = $0; @}
3508 ;
3509 @end group
3510 @end example
3511
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}.
3515
3516 @vindex yylval
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}.
3521
3522 @node Action Types
3523 @subsection Data Types of Values in Actions
3524 @cindex action data types
3525 @cindex data types in actions
3526
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.
3529
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,
3535
3536 @example
3537 @group
3538 exp: @dots{}
3539 | exp '+' exp
3540 @{ $$ = $1 + $3; @}
3541 @end group
3542 @end example
3543
3544 @noindent
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.
3549
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:
3553
3554 @example
3555 @group
3556 %union @{
3557 int itype;
3558 double dtype;
3559 @}
3560 @end group
3561 @end example
3562
3563 @noindent
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.
3566
3567 @node Mid-Rule Actions
3568 @subsection Actions in Mid-Rule
3569 @cindex actions in mid-rule
3570 @cindex mid-rule actions
3571
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.
3575
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.
3579
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
3584 @code{$@var{n}}.
3585
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.
3592
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.
3597
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:
3604
3605 @example
3606 @group
3607 stmt: LET '(' var ')'
3608 @{ $<context>$ = push_context ();
3609 declare_variable ($3); @}
3610 stmt @{ $$ = $6;
3611 pop_context ($<context>5); @}
3612 @end group
3613 @end example
3614
3615 @noindent
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.
3624
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.
3630
3631 @findex %destructor
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
3637 restoring it.
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.
3642
3643 One solution is to bury the mid-rule action inside a nonterminal symbol and to
3644 declare a destructor for that symbol:
3645
3646 @example
3647 @group
3648 %type <context> let
3649 %destructor @{ pop_context ($$); @} let
3650
3651 %%
3652
3653 stmt: let stmt
3654 @{ $$ = $2;
3655 pop_context ($1); @}
3656 ;
3657
3658 let: LET '(' var ')'
3659 @{ $$ = push_context ();
3660 declare_variable ($3); @}
3661 ;
3662
3663 @end group
3664 @end example
3665
3666 @noindent
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.
3670
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
3676 declaration or not:
3677
3678 @example
3679 @group
3680 compound: '@{' declarations statements '@}'
3681 | '@{' statements '@}'
3682 ;
3683 @end group
3684 @end example
3685
3686 @noindent
3687 But when we add a mid-rule action as follows, the rules become nonfunctional:
3688
3689 @example
3690 @group
3691 compound: @{ prepare_for_local_variables (); @}
3692 '@{' declarations statements '@}'
3693 @end group
3694 @group
3695 | '@{' statements '@}'
3696 ;
3697 @end group
3698 @end example
3699
3700 @noindent
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}.)
3707
3708 You might think that you could correct the problem by putting identical
3709 actions into the two rules, like this:
3710
3711 @example
3712 @group
3713 compound: @{ prepare_for_local_variables (); @}
3714 '@{' declarations statements '@}'
3715 | @{ prepare_for_local_variables (); @}
3716 '@{' statements '@}'
3717 ;
3718 @end group
3719 @end example
3720
3721 @noindent
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.)
3724
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:
3728
3729 @example
3730 @group
3731 compound: '@{' @{ prepare_for_local_variables (); @}
3732 declarations statements '@}'
3733 | '@{' statements '@}'
3734 ;
3735 @end group
3736 @end example
3737
3738 @noindent
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.
3741
3742 Another solution is to bury the action inside a nonterminal symbol which
3743 serves as a subroutine:
3744
3745 @example
3746 @group
3747 subroutine: /* empty */
3748 @{ prepare_for_local_variables (); @}
3749 ;
3750
3751 @end group
3752
3753 @group
3754 compound: subroutine
3755 '@{' declarations statements '@}'
3756 | subroutine
3757 '@{' statements '@}'
3758 ;
3759 @end group
3760 @end example
3761
3762 @noindent
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.
3765
3766 @node Locations
3767 @section Tracking Locations
3768 @cindex location
3769 @cindex textual location
3770 @cindex location, textual
3771
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.
3775
3776 The way locations are handled is defined by providing a data type, and
3777 actions to take when rules are matched.
3778
3779 @menu
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.
3783 @end menu
3784
3785 @node Location Type
3786 @subsection Data Type of Locations
3787 @cindex data type of locations
3788 @cindex default location type
3789
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.
3792
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
3797 four members:
3798
3799 @example
3800 typedef struct YYLTYPE
3801 @{
3802 int first_line;
3803 int first_column;
3804 int last_line;
3805 int last_column;
3806 @} YYLTYPE;
3807 @end example
3808
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}.
3814
3815 @node Actions and Locations
3816 @subsection Actions and Locations
3817 @cindex location actions
3818 @cindex actions, location
3819 @vindex @@$
3820 @vindex @@@var{n}
3821
3822 Actions are not only useful for defining language semantics, but also for
3823 describing the behavior of the output parser with locations.
3824
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
3830 @code{@@$}.
3831
3832 Here is a basic example using the default data type for locations:
3833
3834 @example
3835 @group
3836 exp: @dots{}
3837 | exp '/' exp
3838 @{
3839 @@$.first_column = @@1.first_column;
3840 @@$.first_line = @@1.first_line;
3841 @@$.last_column = @@3.last_column;
3842 @@$.last_line = @@3.last_line;
3843 if ($3)
3844 $$ = $1 / $3;
3845 else
3846 @{
3847 $$ = 1;
3848 fprintf (stderr,
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);
3852 @}
3853 @}
3854 @end group
3855 @end example
3856
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
3860 last symbol.
3861
3862 With this default action, the location tracking can be fully automatic. The
3863 example above simply rewrites this way:
3864
3865 @example
3866 @group
3867 exp: @dots{}
3868 | exp '/' exp
3869 @{
3870 if ($3)
3871 $$ = $1 / $3;
3872 else
3873 @{
3874 $$ = 1;
3875 fprintf (stderr,
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);
3879 @}
3880 @}
3881 @end group
3882 @end example
3883
3884 @vindex yylloc
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}.
3889
3890 @node Location Default Action
3891 @subsection Default Action for Locations
3892 @vindex YYLLOC_DEFAULT
3893 @cindex @acronym{GLR} parsers and @code{YYLLOC_DEFAULT}
3894
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
3903 of that ambiguity.
3904
3905 Most of the time, this macro is general enough to suppress location
3906 dedicated code from semantic actions.
3907
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.
3918
3919 By default, @code{YYLLOC_DEFAULT} is defined this way:
3920
3921 @smallexample
3922 @group
3923 # define YYLLOC_DEFAULT(Current, Rhs, N) \
3924 do \
3925 if (N) \
3926 @{ \
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; \
3931 @} \
3932 else \
3933 @{ \
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; \
3938 @} \
3939 while (0)
3940 @end group
3941 @end smallexample
3942
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.
3946
3947 When defining @code{YYLLOC_DEFAULT}, you should consider that:
3948
3949 @itemize @bullet
3950 @item
3951 All arguments are free of side-effects. However, only the first one (the
3952 result) should be modified by @code{YYLLOC_DEFAULT}.
3953
3954 @item
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.
3959
3960 @item
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.
3965 @end itemize
3966
3967 @node Declarations
3968 @section Bison Declarations
3969 @cindex declarations, Bison
3970 @cindex Bison declarations
3971
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.
3974 @xref{Symbols}.
3975
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}).
3980
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
3984 Grammars}).
3985
3986 @menu
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.
3999 @end menu
4000
4001 @node Require Decl
4002 @subsection Require a Version of Bison
4003 @cindex version requirement
4004 @cindex requiring a version of Bison
4005 @findex %require
4006
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
4009 status 63).
4010
4011 @example
4012 %require "@var{version}"
4013 @end example
4014
4015 @node Token Decl
4016 @subsection Token Type Names
4017 @cindex declaring token type names
4018 @cindex token type names, declaring
4019 @cindex declaring literal string tokens
4020 @findex %token
4021
4022 The basic way to declare a token type name (terminal symbol) is as follows:
4023
4024 @example
4025 %token @var{name}
4026 @end example
4027
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.
4031
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
4036 Precedence}.
4037
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:
4041
4042 @example
4043 %token NUM 300
4044 %token XNUM 0x12d // a GNU extension
4045 @end example
4046
4047 @noindent
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.
4051
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}).
4056
4057 For example:
4058
4059 @example
4060 @group
4061 %union @{ /* define stack type */
4062 double val;
4063 symrec *tptr;
4064 @}
4065 %token <val> NUM /* define token NUM and its type */
4066 @end group
4067 @end example
4068
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:
4072
4073 @example
4074 %token arrow "=>"
4075 @end example
4076
4077 @noindent
4078 For example, a grammar for the C language might specify these names with
4079 equivalent literal string tokens:
4080
4081 @example
4082 %token <operator> OR "||"
4083 %token <operator> LE 134 "<="
4084 %left OR "<="
4085 @end example
4086
4087 @noindent
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.
4094
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
4097 of ``$end'':
4098
4099 @example
4100 %token END 0 "end of file"
4101 @end example
4102
4103 @node Precedence Decl
4104 @subsection Operator Precedence
4105 @cindex precedence declarations
4106 @cindex declaring operator precedence
4107 @cindex operator precedence, declaring
4108
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.
4115
4116 The syntax of a precedence declaration is nearly the same as that of
4117 @code{%token}: either
4118
4119 @example
4120 %left @var{symbols}@dots{}
4121 @end example
4122
4123 @noindent
4124 or
4125
4126 @example
4127 %left <@var{type}> @var{symbols}@dots{}
4128 @end example
4129
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}:
4133
4134 @itemize @bullet
4135 @item
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.
4145
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.
4149
4150 @item
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.
4156 @end itemize
4157
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
4162 separate token.
4163 For example:
4164
4165 @example
4166 %left OR "<=" // Does not declare an alias.
4167 %left OR 134 "<=" 135 // Declares 134 for OR and 135 for "<=".
4168 @end example
4169
4170 @node Union Decl
4171 @subsection The Collection of Value Types
4172 @cindex declaring value types
4173 @cindex value types, declaring
4174 @findex %union
4175
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
4179 @code{union} in C@.
4180
4181 For example:
4182
4183 @example
4184 @group
4185 %union @{
4186 double val;
4187 symrec *tptr;
4188 @}
4189 @end group
4190 @end example
4191
4192 @noindent
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}).
4197
4198 As an extension to @acronym{POSIX}, a tag is allowed after the
4199 @code{union}. For example:
4200
4201 @example
4202 @group
4203 %union value @{
4204 double val;
4205 symrec *tptr;
4206 @}
4207 @end group
4208 @end example
4209
4210 @noindent
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
4213 @code{YYSTYPE}.
4214
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.
4218
4219 Note that, unlike making a @code{union} declaration in C, you need not write
4220 a semicolon after the closing brace.
4221
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}:
4226
4227 @example
4228 @group
4229 union YYSTYPE @{
4230 double val;
4231 symrec *tptr;
4232 @};
4233 typedef union YYSTYPE YYSTYPE;
4234 @end group
4235 @end example
4236
4237 @noindent
4238 and then your grammar can use the following
4239 instead of @code{%union}:
4240
4241 @example
4242 @group
4243 %@{
4244 #include "parser.h"
4245 %@}
4246 %type <val> expr
4247 %token <tptr> ID
4248 @end group
4249 @end example
4250
4251 @node Type Decl
4252 @subsection Nonterminal Symbols
4253 @cindex declaring value types, nonterminals
4254 @cindex value types, nonterminals, declaring
4255 @findex %type
4256
4257 @noindent
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:
4261
4262 @example
4263 %type <@var{type}> @var{nonterminal}@dots{}
4264 @end example
4265
4266 @noindent
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
4272 the symbol names.
4273
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}>}.
4278
4279 @node Initial Action Decl
4280 @subsection Performing Actions before Parsing
4281 @findex %initial-action
4282
4283 Sometimes your parser needs to perform some initializations before
4284 parsing. The @code{%initial-action} directive allows for such arbitrary
4285 code.
4286
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}.
4293 @end deffn
4294
4295 For instance, if your locations use a file name, you may use
4296
4297 @example
4298 %parse-param @{ char const *file_name @};
4299 %initial-action
4300 @{
4301 @@$.initialize (file_name);
4302 @};
4303 @end example
4304
4305
4306 @node Destructor Decl
4307 @subsection Freeing Discarded Symbols
4308 @cindex freeing discarded symbols
4309 @findex %destructor
4310 @findex <*>
4311 @findex <>
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.
4318
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.
4323
4324 The @code{%destructor} directive defines code that is called when a
4325 symbol is automatically discarded.
4326
4327 @deffn {Directive} %destructor @{ @var{code} @} @var{symbols}
4328 @findex %destructor
4329 Invoke the braced @var{code} whenever the parser discards one of the
4330 @var{symbols}.
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}}).
4335
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}.
4343
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
4347 features.)
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
4352 @code{%destructor}.
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.
4358 @end deffn
4359
4360 @noindent
4361 For example:
4362
4363 @smallexample
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
4372 %token TAGLESS
4373
4374 %destructor @{ @} <character>
4375 %destructor @{ free ($$); @} <*>
4376 %destructor @{ free ($$); printf ("%d", @@$.first_line); @} STRING1 string1
4377 %destructor @{ printf ("Discarding tagless symbol.\n"); @} <>
4378 @end smallexample
4379
4380 @noindent
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.
4390
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}:
4402
4403 @smallexample
4404 %token END 0
4405 @end smallexample
4406
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
4414 rule.
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.
4417
4418 @ignore
4419 @noindent
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.
4423 @end ignore
4424
4425 @sp 1
4426
4427 @cindex discarded symbols
4428 @dfn{Discarded symbols} are the following:
4429
4430 @itemize
4431 @item
4432 stacked symbols popped during the first phase of error recovery,
4433 @item
4434 incoming terminals during the second phase of error recovery,
4435 @item
4436 the current lookahead and the entire stack (except the current
4437 right-hand side symbols) when the parser returns immediately, and
4438 @item
4439 the start symbol, when the parser succeeds.
4440 @end itemize
4441
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
4444 exhaustion.
4445
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
4449 the memory.
4450
4451 @node Expect Decl
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
4457 @findex %expect
4458 @findex %expect-rr
4459
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.
4466
4467 The declaration looks like this:
4468
4469 @example
4470 %expect @var{n}
4471 @end example
4472
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.
4477
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:
4485
4486 @example
4487 %expect-rr @var{n}
4488 @end example
4489
4490 In general, using @code{%expect} involves these steps:
4491
4492 @itemize @bullet
4493 @item
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.
4497
4498 @item
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.
4502
4503 @item
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.
4507 @end itemize
4508
4509 Now Bison will warn you if you introduce an unexpected conflict, but
4510 will keep silent otherwise.
4511
4512 @node Start Decl
4513 @subsection The Start-Symbol
4514 @cindex declaring the start symbol
4515 @cindex start symbol, declaring
4516 @cindex default start symbol
4517 @findex %start
4518
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:
4522
4523 @example
4524 %start @var{symbol}
4525 @end example
4526
4527 @node Pure Decl
4528 @subsection A Pure (Reentrant) Parser
4529 @cindex reentrant parser
4530 @cindex pure parser
4531 @findex %define api.pure
4532
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.
4539
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}.)
4545
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:
4549
4550 @example
4551 %define api.pure
4552 @end example
4553
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.
4563
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
4566 valid grammar.
4567
4568 @node Push Decl
4569 @subsection A Push Parser
4570 @cindex push parser
4571 @cindex push parser
4572 @findex %define api.push-pull
4573
4574 (The current push parsing interface is experimental and may evolve.
4575 More user feedback will help to stabilize it.)
4576
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.
4580
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.
4585
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}):
4589
4590 @example
4591 %define api.push-pull push
4592 @end example
4593
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:
4599
4600 @example
4601 %define api.pure
4602 %define api.push-pull push
4603 @end example
4604
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.
4609
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:
4618
4619 @example
4620 int status;
4621 yypstate *ps = yypstate_new ();
4622 do @{
4623 status = yypush_parse (ps, yylex (), NULL);
4624 @} while (status == YYPUSH_MORE);
4625 yypstate_delete (ps);
4626 @end example
4627
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:
4634
4635 @example
4636 extern int yychar;
4637 int status;
4638 yypstate *ps = yypstate_new ();
4639 do @{
4640 yychar = yylex ();
4641 status = yypush_parse (ps);
4642 @} while (status == YYPUSH_MORE);
4643 yypstate_delete (ps);
4644 @end example
4645
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.
4648
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
4666 like this:
4667
4668 @example
4669 yypstate *ps = yypstate_new ();
4670 yypull_parse (ps); /* Will call the lexer */
4671 yypstate_delete (ps);
4672 @end example
4673
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}.
4677
4678 @node Decl Summary
4679 @subsection Bison Declaration Summary
4680 @cindex Bison declaration summary
4681 @cindex declaration summary
4682 @cindex summary, Bison declaration
4683
4684 Here is a summary of the declarations used to define a grammar:
4685
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}).
4689 @end deffn
4690
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}).
4694 @end deffn
4695
4696 @deffn {Directive} %right
4697 Declare a terminal symbol (token type name) that is right-associative
4698 (@pxref{Precedence Decl, ,Operator Precedence}).
4699 @end deffn
4700
4701 @deffn {Directive} %left
4702 Declare a terminal symbol (token type name) that is left-associative
4703 (@pxref{Precedence Decl, ,Operator Precedence}).
4704 @end deffn
4705
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.
4710 @end deffn
4711
4712 @ifset defaultprec
4713 @deffn {Directive} %default-prec
4714 Assign a precedence to rules lacking an explicit @code{%prec} modifier
4715 (@pxref{Contextual Precedence, ,Context-Dependent Precedence}).
4716 @end deffn
4717 @end ifset
4718
4719 @deffn {Directive} %type
4720 Declare the type of semantic values for a nonterminal symbol
4721 (@pxref{Type Decl, ,Nonterminal Symbols}).
4722 @end deffn
4723
4724 @deffn {Directive} %start
4725 Specify the grammar's start symbol (@pxref{Start Decl, ,The
4726 Start-Symbol}).
4727 @end deffn
4728
4729 @deffn {Directive} %expect
4730 Declare the expected number of shift-reduce conflicts
4731 (@pxref{Expect Decl, ,Suppressing Conflict Warnings}).
4732 @end deffn
4733
4734
4735 @sp 1
4736 @noindent
4737 In order to change the behavior of @command{bison}, use the following
4738 directives:
4739
4740 @deffn {Directive} %code @{@var{code}@}
4741 @findex %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.}.
4747
4748 @cindex Prologue
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}.
4754
4755 For Java, the default location is inside the parser class.
4756 @end deffn
4757
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.
4763
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:
4769
4770 @itemize @bullet
4771 @item requires
4772 @findex %code requires
4773
4774 @itemize @bullet
4775 @item Language(s): C, C++
4776
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.
4782
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.
4785 @end itemize
4786
4787 @item provides
4788 @findex %code provides
4789
4790 @itemize @bullet
4791 @item Language(s): C, C++
4792
4793 @item Purpose: This is the best place to write additional definitions and
4794 declarations that should be provided to other modules.
4795
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.
4798 @end itemize
4799
4800 @item top
4801 @findex %code top
4802
4803 @itemize @bullet
4804 @item Language(s): C, C++
4805
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.
4810 For example:
4811
4812 @smallexample
4813 %code top @{
4814 #define _GNU_SOURCE
4815 #include <stdio.h>
4816 @}
4817 @end smallexample
4818
4819 @item Location(s): Near the top of the parser source code file.
4820 @end itemize
4821
4822 @item imports
4823 @findex %code imports
4824
4825 @itemize @bullet
4826 @item Language(s): Java
4827
4828 @item Purpose: This is the best place to write Java import directives.
4829
4830 @item Location(s): The parser Java file after any Java package directive and
4831 before any class definitions.
4832 @end itemize
4833 @end itemize
4834
4835 @cindex Prologue
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}.
4838 @end deffn
4839
4840 @deffn {Directive} %debug
4841 Instrument the output parser for traces. Obsoleted by @samp{%define
4842 parse.trace}.
4843 @xref{Tracing, ,Tracing Your Parser}.
4844 @end deffn
4845
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.
4850
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}]}.
4853
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
4856 digit.
4857
4858 Omitting @code{"@var{value}"} entirely is always equivalent to specifying
4859 @code{""}.
4860
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:
4864
4865 @enumerate
4866 @item @code{@var{value}} is @code{true}
4867
4868 @item @code{@var{value}} is omitted (or @code{""} is specified).
4869 This is equivalent to @code{true}.
4870
4871 @item @code{@var{value}} is @code{false}.
4872
4873 @item @var{variable} is never defined.
4874 In this case, Bison selects a default value.
4875 @end enumerate
4876
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:
4883
4884 @table @code
4885 @c ================================================== api.namespace
4886 @item api.namespace
4887 @findex %define api.namespace
4888 @itemize
4889 @item Languages(s): C++
4890
4891 @item Purpose: Specifies the namespace for the parser class.
4892 For example, if you specify:
4893
4894 @smallexample
4895 %define api.namespace "foo::bar"
4896 @end smallexample
4897
4898 Bison uses @code{foo::bar} verbatim in references such as:
4899
4900 @smallexample
4901 foo::bar::parser::semantic_type
4902 @end smallexample
4903
4904 However, to open a namespace, Bison removes any leading @code{::} and then
4905 splits on any remaining occurrences:
4906
4907 @smallexample
4908 namespace foo @{ namespace bar @{
4909 class position;
4910 class location;
4911 @} @}
4912 @end smallexample
4913
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"}.
4917
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:
4926
4927 @smallexample
4928 %define api.namespace "foo"
4929 %name-prefix "bar::"
4930 @end smallexample
4931
4932 The parser namespace is @code{foo} and @code{yylex} is referenced as
4933 @code{bar::lex}.
4934 @end itemize
4935 @c namespace
4936
4937
4938
4939 @c ================================================== api.pure
4940 @item api.pure
4941 @findex %define api.pure
4942
4943 @itemize @bullet
4944 @item Language(s): C
4945
4946 @item Purpose: Request a pure (reentrant) parser program.
4947 @xref{Pure Decl, ,A Pure (Reentrant) Parser}.
4948
4949 @item Accepted Values: Boolean
4950
4951 @item Default Value: @code{false}
4952 @end itemize
4953 @c api.pure
4954
4955
4956
4957 @c ================================================== api.push-pull
4958 @item api.push-pull
4959 @findex %define api.push-pull
4960
4961 @itemize @bullet
4962 @item Language(s): C (deterministic parsers only)
4963
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.)
4968
4969 @item Accepted Values: @code{pull}, @code{push}, @code{both}
4970
4971 @item Default Value: @code{pull}
4972 @end itemize
4973 @c api.push-pull
4974
4975
4976
4977 @c ================================================== api.tokens.prefix
4978 @item api.tokens.prefix
4979 @findex %define api.tokens.prefix
4980
4981 @itemize
4982 @item Languages(s): all
4983
4984 @item Purpose:
4985 Add a prefix to the token names when generating their definition in the
4986 target language. For instance
4987
4988 @example
4989 %token FILE for ERROR
4990 %define api.tokens.prefix "TOK_"
4991 %%
4992 start: FILE for ERROR;
4993 @end example
4994
4995 @noindent
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.
5003
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).
5008
5009 @item Default Value:
5010 empty
5011 @end itemize
5012 @c api.tokens.prefix
5013
5014
5015 @c ================================================== lr.default-reductions
5016
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
5022
5023 @itemize @bullet
5024 @item Language(s): all
5025
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
5030 lookahead set.
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.
5035
5036 (This feature is experimental.
5037 More user feedback will help to stabilize it.)
5038
5039 @item Accepted Values:
5040 @itemize
5041 @item @code{all}.
5042 For @acronym{LALR} and @acronym{IELR} parsers (@pxref{Decl
5043 Summary,,lr.type}) by default, all states are permitted to contain
5044 default reductions.
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.
5052
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
5063 scanner.
5064
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.
5073 @end itemize
5074
5075 @item Default Value:
5076 @itemize
5077 @item @code{accepting} if @code{lr.type} is @code{canonical-lr}.
5078 @item @code{all} otherwise.
5079 @end itemize
5080 @end itemize
5081
5082 @c ============================================ lr.keep-unreachable-states
5083
5084 @item lr.keep-unreachable-states
5085 @findex %define lr.keep-unreachable-states
5086
5087 @itemize @bullet
5088 @item Language(s): all
5089
5090 @item Purpose: Requests that Bison allow unreachable parser states to remain in
5091 the parser tables.
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.
5098
5099 @item Accepted Values: Boolean
5100
5101 @item Default Value: @code{false}
5102
5103 @item Caveats:
5104
5105 @itemize @bullet
5106
5107 @item Unreachable states may contain conflicts and may use rules not used in
5108 any other state.
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.
5114
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
5119 become useless.
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
5122 states.
5123 However, Bison does not compute which goto actions are useless.
5124 @end itemize
5125 @end itemize
5126 @c lr.keep-unreachable-states
5127
5128 @c ================================================== lr.type
5129
5130 @item lr.type
5131 @findex %define lr.type
5132 @cindex @acronym{LALR}
5133 @cindex @acronym{IELR}
5134 @cindex @acronym{LR}
5135
5136 @itemize @bullet
5137 @item Language(s): all
5138
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.)
5143
5144 @item Accepted Values:
5145 @itemize
5146 @item @code{lalr}.
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
5155 worthwhile:
5156 @itemize
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
5161 given input.
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.
5166
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}.
5173 @end itemize
5174
5175 @item @code{ielr}.
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
5179 set of sentences.
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
5182 @acronym{LR}.
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.
5188
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.
5203 @end itemize
5204
5205 @item Default Value: @code{lalr}
5206 @end itemize
5207
5208
5209 @c ================================================== namespace
5210 @item namespace
5211 @findex %define namespace
5212 Obsoleted by @code{api.namespace}
5213 @c namespace
5214
5215
5216 @c ================================================== parse.assert
5217 @item parse.assert
5218 @findex %define parse.assert
5219
5220 @itemize
5221 @item Languages(s): C++
5222
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.
5226
5227 @item Accepted Values: Boolean
5228
5229 @item Default Value: @code{false}
5230 @end itemize
5231 @c parse.assert
5232
5233
5234 @c ================================================== parse.error
5235 @item parse.error
5236 @findex %define parse.error
5237 @itemize
5238 @item Languages(s):
5239 all.
5240 @item Purpose:
5241 Control the kind of error messages passed to the error reporting
5242 function. @xref{Error Reporting, ,The Error Reporting Function
5243 @code{yyerror}}.
5244 @item Accepted Values:
5245 @itemize
5246 @item @code{simple}
5247 Error messages passed to @code{yyerror} are simply @w{@code{"syntax
5248 error"}}.
5249 @item @code{verbose}
5250 Error messages report the unexpected token, and possibly the expected
5251 ones.
5252 @end itemize
5253
5254 @item Default Value:
5255 @code{simple}
5256 @end itemize
5257 @c parse.error
5258
5259
5260 @c ================================================== parse.trace
5261 @item parse.trace
5262 @findex %define parse.trace
5263
5264 @itemize
5265 @item Languages(s): C, C++
5266
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}.
5271
5272 @item Accepted Values: Boolean
5273
5274 @item Default Value: @code{false}
5275 @end itemize
5276 @c parse.trace
5277
5278 @end table
5279 @end deffn
5280 @c ---------------------------------------------------------- %define
5281
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}.
5287
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
5294 or type definition
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}.
5299
5300 Unless your parser is pure, the output header declares @code{yylval}
5301 as an external variable. @xref{Pure Decl, ,A Pure (Reentrant)
5302 Parser}.
5303
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
5307 Locations}.
5308
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
5313 Tokens}.
5314
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}.
5320 @end deffn
5321
5322 @deffn {Directive} %defines @var{defines-file}
5323 Same as above, but save in the file @var{defines-file}.
5324 @end deffn
5325
5326 @deffn {Directive} %destructor
5327 Specify how the parser should reclaim the memory associated to
5328 discarded symbols. @xref{Destructor Decl, , Freeing Discarded Symbols}.
5329 @end deffn
5330
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}.
5334 @end deffn
5335
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.
5340
5341 This directive is experimental and its effect may be modified in future
5342 releases.
5343 @end deffn
5344
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.
5351 @end deffn
5352
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
5356 in C parsers
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
5365 section.
5366 @xref{Multiple Parsers, ,Multiple Parsers in the Same Program}.
5367 @end deffn
5368
5369 @ifset defaultprec
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
5373 Precedence}).
5374 @end deffn
5375 @end ifset
5376
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.
5384 @end deffn
5385
5386 @deffn {Directive} %output "@var{file}"
5387 Specify @var{file} for the parser file.
5388 @end deffn
5389
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.
5393 @end deffn
5394
5395 @deffn {Directive} %require "@var{version}"
5396 Require version @var{version} or higher of Bison. @xref{Require Decl, ,
5397 Require a Version of Bison}.
5398 @end deffn
5399
5400 @deffn {Directive} %skeleton "@var{file}"
5401 Specify the skeleton to use.
5402
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.
5407
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.
5413 @end deffn
5414
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
5420 @code{"$end"},
5421 @code{"error"}, and @code{"$undefined"}; after these come the symbols
5422 defined in the grammar file.
5423
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
5431 @code{"\"\\\\/\""}.
5432
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}:
5436
5437 @table @code
5438 @item YYNTOKENS
5439 The highest token number, plus one.
5440 @item YYNNTS
5441 The number of nonterminal symbols.
5442 @item YYNRULES
5443 The number of grammar rules,
5444 @item YYNSTATES
5445 The number of parser states (@pxref{Parser States}).
5446 @end table
5447 @end deffn
5448
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
5453 information.
5454 @end deffn
5455
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.
5459 @end deffn
5460
5461
5462 @node Multiple Parsers
5463 @section Multiple Parsers in the Same Program
5464
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.
5469
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.
5475
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.
5483
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}).
5489
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.
5494
5495 @node Interface
5496 @chapter Parser C-Language Interface
5497 @cindex C-language interface
5498 @cindex interface
5499
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.
5503
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.
5508
5509 @menu
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}
5516 which reads tokens.
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
5520 native language.
5521 @end menu
5522
5523 @node Parser Function
5524 @section The Parser Function @code{yyparse}
5525 @findex yyparse
5526
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.
5532
5533
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).
5537
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
5540 invoked.
5541
5542 The value is 2 if parsing failed due to memory exhaustion.
5543 @end deftypefun
5544
5545 In an action, you can cause immediate return from @code{yyparse} by using
5546 these macros:
5547
5548 @defmac YYACCEPT
5549 @findex YYACCEPT
5550 Return immediately with value 0 (to report success).
5551 @end defmac
5552
5553 @defmac YYABORT
5554 @findex YYABORT
5555 Return immediately with value 1 (to report failure).
5556 @end defmac
5557
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}:
5561
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.
5569 @end deffn
5570
5571 Here's an example. Write this in the parser:
5572
5573 @example
5574 %parse-param @{int *nastiness@} @{int *randomness@}
5575 @end example
5576
5577 @noindent
5578 Then call the parser like this:
5579
5580 @example
5581 @{
5582 int nastiness, randomness;
5583 @dots{} /* @r{Store proper data in @code{nastiness} and @code{randomness}.} */
5584 value = yyparse (&nastiness, &randomness);
5585 @dots{}
5586 @}
5587 @end example
5588
5589 @noindent
5590 In the grammar actions, use expressions like this to refer to the data:
5591
5592 @example
5593 exp: @dots{} @{ @dots{}; *randomness += 1; @dots{} @}
5594 @end example
5595
5596 @node Push Parser Function
5597 @section The Push Parser Function @code{yypush_parse}
5598 @findex yypush_parse
5599
5600 (The current push parsing interface is experimental and may evolve.
5601 More user feedback will help to stabilize it.)
5602
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}.
5607
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.
5612 @end deftypefun
5613
5614 @node Pull Parser Function
5615 @section The Pull Parser Function @code{yypull_parse}
5616 @findex yypull_parse
5617
5618 (The current push parsing interface is experimental and may evolve.
5619 More user feedback will help to stabilize it.)
5620
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}.
5625
5626 @deftypefun int yypull_parse (yypstate *yyps)
5627 The value returned by @code{yypull_parse} is the same as for @code{yyparse}.
5628 @end deftypefun
5629
5630 @node Parser Create Function
5631 @section The Parser Create Function @code{yystate_new}
5632 @findex yypstate_new
5633
5634 (The current push parsing interface is experimental and may evolve.
5635 More user feedback will help to stabilize it.)
5636
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}.
5641
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
5646 allocated.
5647 @end deftypefun
5648
5649 @node Parser Delete Function
5650 @section The Parser Delete Function @code{yystate_delete}
5651 @findex yypstate_delete
5652
5653 (The current push parsing interface is experimental and may evolve.
5654 More user feedback will help to stabilize it.)
5655
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}.
5660
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.
5664 @end deftypefun
5665
5666 @node Lexical
5667 @section The Lexical Analyzer Function @code{yylex}
5668 @findex yylex
5669 @cindex lexical analyzer
5670
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.
5675
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}.
5683
5684 @menu
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
5690 actions want that.
5691 * Pure Calling:: How the calling convention differs in a pure parser
5692 (@pxref{Pure Decl, ,A Pure (Reentrant) Parser}).
5693 @end menu
5694
5695 @node Calling Convention
5696 @subsection Calling Convention for @code{yylex}
5697
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.
5701
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}.
5706
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.
5713
5714 Here is an example showing these things:
5715
5716 @example
5717 int
5718 yylex (void)
5719 @{
5720 @dots{}
5721 if (c == EOF) /* Detect end-of-input. */
5722 return 0;
5723 @dots{}
5724 if (c == '+' || c == '-')
5725 return c; /* Assume token type for `+' is '+'. */
5726 @dots{}
5727 return INT; /* Return the type of the token. */
5728 @dots{}
5729 @}
5730 @end example
5731
5732 @noindent
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}.
5735
5736 If the grammar uses literal string tokens, there are two ways that
5737 @code{yylex} can determine the token type codes for them:
5738
5739 @itemize @bullet
5740 @item
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}.
5745
5746 @item
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
5752 to Bison.
5753
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.
5758
5759 @smallexample
5760 for (i = 0; i < YYNTOKENS; i++)
5761 @{
5762 if (yytname[i] != 0
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)
5768 break;
5769 @}
5770 @end smallexample
5771
5772 The @code{yytname} table is generated only if you use the
5773 @code{%token-table} declaration. @xref{Decl Summary}.
5774 @end itemize
5775
5776 @node Token Values
5777 @subsection Semantic Values of Tokens
5778
5779 @vindex yylval
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
5784 @code{yylex}:
5785
5786 @example
5787 @group
5788 @dots{}
5789 yylval = value; /* Put value onto Bison stack. */
5790 return INT; /* Return the type of the token. */
5791 @dots{}
5792 @end group
5793 @end example
5794
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:
5800
5801 @example
5802 @group
5803 %union @{
5804 int intval;
5805 double val;
5806 symrec *tptr;
5807 @}
5808 @end group
5809 @end example
5810
5811 @noindent
5812 then the code in @code{yylex} might look like this:
5813
5814 @example
5815 @group
5816 @dots{}
5817 yylval.intval = value; /* Put value onto Bison stack. */
5818 return INT; /* Return the type of the token. */
5819 @dots{}
5820 @end group
5821 @end example
5822
5823 @node Token Locations
5824 @subsection Textual Locations of Tokens
5825
5826 @vindex yylloc
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.
5833
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.
5839
5840 @tindex YYLTYPE
5841 The data type of @code{yylloc} has the name @code{YYLTYPE}.
5842
5843 @node Pure Calling
5844 @subsection Calling Conventions for Pure Parsers
5845
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
5852 pointers.
5853
5854 @example
5855 int
5856 yylex (YYSTYPE *lvalp, YYLTYPE *llocp)
5857 @{
5858 @dots{}
5859 *lvalp = value; /* Put value onto Bison stack. */
5860 return INT; /* Return the type of the token. */
5861 @dots{}
5862 @}
5863 @end example
5864
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
5868 only one argument.
5869
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}.
5874
5875 @deffn {Directive} %lex-param @{@var{argument-declaration}@} @dots{}
5876 @findex %lex-param
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}.
5880 @end deffn
5881
5882 @deffn {Directive} %param @{@var{argument-declaration}@} @dots{}
5883 @findex %param
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}.
5889 @end deffn
5890
5891 For instance:
5892
5893 @example
5894 %lex-param @{scanner_mode *mode@}
5895 %parse-param @{parser_mode *mode@}
5896 %param @{environment_type *env@}
5897 @end example
5898
5899 @noindent
5900 results in the following signature:
5901
5902 @example
5903 int yylex (scanner_mode *mode, environment_type *env);
5904 int yyparse (parser_mode *mode, environment_type *env);
5905 @end example
5906
5907 If @samp{%define api.pure} is added:
5908
5909 @example
5910 int yylex (YYSTYPE *lvalp, scanner_mode *mode, environment_type *env);
5911 int yyparse (parser_mode *mode, environment_type *env);
5912 @end example
5913
5914 @noindent
5915 and finally, if both @samp{%define api.pure} and @code{%locations} are used:
5916
5917 @example
5918 int yylex (YYSTYPE *lvalp, YYLTYPE *llocp,
5919 scanner_mode *mode, environment_type *env);
5920 int yyparse (parser_mode *mode, environment_type *env);
5921 @end example
5922
5923 @node Error Reporting
5924 @section The Error Reporting Function @code{yyerror}
5925 @cindex error reporting function
5926 @findex yyerror
5927 @cindex parse error
5928 @cindex syntax error
5929
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
5934 in Actions}).
5935
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"}}.
5941
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"}}.
5947
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"}}.
5954
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}.
5958
5959 The following definition suffices in simple programs:
5960
5961 @example
5962 @group
5963 void
5964 yyerror (char const *s)
5965 @{
5966 @end group
5967 @group
5968 fprintf (stderr, "%s\n", s);
5969 @}
5970 @end group
5971 @end example
5972
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.
5977
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
5983 @code{yyerror} are:
5984
5985 @example
5986 void yyerror (char const *msg); /* Yacc parsers. */
5987 void yyerror (YYLTYPE *locp, char const *msg); /* GLR parsers. */
5988 @end example
5989
5990 If @samp{%parse-param @{int *nastiness@}} is used, then:
5991
5992 @example
5993 void yyerror (int *nastiness, char const *msg); /* Yacc parsers. */
5994 void yyerror (int *nastiness, char const *msg); /* GLR parsers. */
5995 @end example
5996
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.
6001 I.e.:
6002
6003 @example
6004 /* Location tracking. */
6005 %locations
6006 /* Pure yylex. */
6007 %define api.pure
6008 %lex-param @{int *nastiness@}
6009 /* Pure yyparse. */
6010 %parse-param @{int *nastiness@}
6011 %parse-param @{int *randomness@}
6012 @end example
6013
6014 @noindent
6015 results in the following signatures for all the parser kinds:
6016
6017 @example
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,
6022 char const *msg);
6023 @end example
6024
6025 @noindent
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.
6031
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
6035 @code{yyerror}.
6036
6037 @vindex yynerrs
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.
6042
6043 @node Action Features
6044 @section Special Features for Use in Actions
6045 @cindex summary, action features
6046 @cindex action features summary
6047
6048 Here is a table of Bison constructs, variables and macros that
6049 are useful in actions.
6050
6051 @deffn {Variable} $$
6052 Acts like a variable that contains the semantic value for the
6053 grouping made by the current rule. @xref{Actions}.
6054 @end deffn
6055
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}.
6059 @end deffn
6060
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}.
6065 @end deffn
6066
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}.
6071 @end deffn
6072
6073 @deffn {Macro} YYABORT;
6074 Return immediately from @code{yyparse}, indicating failure.
6075 @xref{Parser Function, ,The Parser Function @code{yyparse}}.
6076 @end deffn
6077
6078 @deffn {Macro} YYACCEPT;
6079 Return immediately from @code{yyparse}, indicating success.
6080 @xref{Parser Function, ,The Parser Function @code{yyparse}}.
6081 @end deffn
6082
6083 @deffn {Macro} YYBACKUP (@var{token}, @var{value});
6084 @findex YYBACKUP
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.
6091
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
6095 recovery.
6096
6097 In either case, the rest of the action is not executed.
6098 @end deffn
6099
6100 @deffn {Macro} YYEMPTY
6101 @vindex YYEMPTY
6102 Value stored in @code{yychar} when there is no lookahead token.
6103 @end deffn
6104
6105 @deffn {Macro} YYEOF
6106 @vindex YYEOF
6107 Value stored in @code{yychar} when the lookahead is the end of the input
6108 stream.
6109 @end deffn
6110
6111 @deffn {Macro} YYERROR;
6112 @findex 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}.
6118 @end deffn
6119
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}.
6125 @end deffn
6126
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
6132 Actions}).
6133 @xref{Lookahead, ,Lookahead Tokens}.
6134 @end deffn
6135
6136 @deffn {Macro} yyclearin;
6137 Discard the current lookahead token. This is useful primarily in
6138 error rules.
6139 Do not invoke @code{yyclearin} in a deferred semantic action (@pxref{GLR
6140 Semantic Actions}).
6141 @xref{Error Recovery}.
6142 @end deffn
6143
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}.
6148 @end deffn
6149
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
6154 Actions}).
6155 @xref{Actions and Locations, ,Actions and Locations}.
6156 @end deffn
6157
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
6162 Actions}).
6163 @xref{Actions, ,Actions}.
6164 @end deffn
6165
6166 @deffn {Value} @@$
6167 @findex @@$
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}.
6171
6172 @c Check if those paragraphs are still useful or not.
6173
6174 @c @example
6175 @c struct @{
6176 @c int first_line, last_line;
6177 @c int first_column, last_column;
6178 @c @};
6179 @c @end example
6180
6181 @c Thus, to get the starting line number of the third component, you would
6182 @c use @samp{@@3.first_line}.
6183
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
6187 @c those members.
6188
6189 @c The use of this feature makes the parser noticeably slower.
6190 @end deffn
6191
6192 @deffn {Value} @@@var{n}
6193 @findex @@@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}.
6197 @end deffn
6198
6199 @node Internationalization
6200 @section Parser Internationalization
6201 @cindex internationalization
6202 @cindex i18n
6203 @cindex NLS
6204 @cindex gettext
6205 @cindex bison-po
6206
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
6215 installation.
6216
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.
6221
6222 @enumerate
6223 @item
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.
6229 For example:
6230
6231 @example
6232 cp /usr/local/share/aclocal/bison-i18n.m4 m4/bison-i18n.m4
6233 @end example
6234
6235 @item
6236 @findex BISON_I18N
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.
6246
6247 @item
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}.
6251 For example:
6252
6253 @example
6254 bindtextdomain ("bison-runtime", BISON_LOCALEDIR);
6255 @end example
6256
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
6260 @file{Makefile}.
6261
6262 @item
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:
6266
6267 @example
6268 DEFS = @@DEFS@@ -DBISON_LOCALEDIR='"$(BISON_LOCALEDIR)"'
6269 @end example
6270
6271 or:
6272
6273 @example
6274 AM_CPPFLAGS = -DBISON_LOCALEDIR='"$(BISON_LOCALEDIR)"'
6275 @end example
6276
6277 @item
6278 Finally, invoke the command @command{autoreconf} to generate the build
6279 infrastructure.
6280 @end enumerate
6281
6282
6283 @node Algorithm
6284 @chapter The Bison Parser Algorithm
6285 @cindex Bison parser algorithm
6286 @cindex algorithm of parser
6287 @cindex shifting
6288 @cindex reduction
6289 @cindex parser stack
6290 @cindex stack, parser
6291
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}.
6295
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
6298 that was shifted.
6299
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.
6307
6308 For example, if the infix calculator's parser stack contains this:
6309
6310 @example
6311 1 + 5 * 3
6312 @end example
6313
6314 @noindent
6315 and the next input token is a newline character, then the last three
6316 elements can be reduced to 15 via the rule:
6317
6318 @example
6319 expr: expr '*' expr;
6320 @end example
6321
6322 @noindent
6323 Then the stack contains just these three elements:
6324
6325 @example
6326 1 + 15
6327 @end example
6328
6329 @noindent
6330 At this point, another reduction can be made, resulting in the single value
6331 16. Then the newline token can be shifted.
6332
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}).
6336
6337 This kind of parser is known in the literature as a bottom-up parser.
6338
6339 @menu
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.
6349 @end menu
6350
6351 @node Lookahead
6352 @section Lookahead Tokens
6353 @cindex lookahead token
6354
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.
6360
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
6368 application.
6369
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.
6373
6374 @example
6375 @group
6376 expr: term '+' expr
6377 | term
6378 ;
6379 @end group
6380
6381 @group
6382 term: '(' expr ')'
6383 | term '!'
6384 | NUMBER
6385 ;
6386 @end group
6387 @end example
6388
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.
6394
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.
6401
6402 @vindex yychar
6403 @vindex yylval
6404 @vindex yylloc
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}.
6409
6410 @node Shift/Reduce
6411 @section Shift/Reduce Conflicts
6412 @cindex conflicts
6413 @cindex shift/reduce conflicts
6414 @cindex dangling @code{else}
6415 @cindex @code{else}, dangling
6416
6417 Suppose we are parsing a language which has if-then and if-then-else
6418 statements, with a pair of rules like this:
6419
6420 @example
6421 @group
6422 if_stmt:
6423 IF expr THEN stmt
6424 | IF expr THEN stmt ELSE stmt
6425 ;
6426 @end group
6427 @end example
6428
6429 @noindent
6430 Here we assume that @code{IF}, @code{THEN} and @code{ELSE} are
6431 terminal symbols for specific keyword tokens.
6432
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
6437 rule.
6438
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.
6444
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
6447 equivalent:
6448
6449 @example
6450 if x then if y then win (); else lose;
6451
6452 if x then do; if y then win (); else lose; end;
6453 @end example
6454
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:
6458
6459 @example
6460 if x then if y then win (); else lose;
6461
6462 if x then do; if y then win (); end; else lose;
6463 @end example
6464
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.
6473
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}.
6478
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
6482 conflict:
6483
6484 @example
6485 @group
6486 %token IF THEN ELSE variable
6487 %%
6488 @end group
6489 @group
6490 stmt: expr
6491 | if_stmt
6492 ;
6493 @end group
6494
6495 @group
6496 if_stmt:
6497 IF expr THEN stmt
6498 | IF expr THEN stmt ELSE stmt
6499 ;
6500 @end group
6501
6502 expr: variable
6503 ;
6504 @end example
6505
6506 @node Precedence
6507 @section Operator Precedence
6508 @cindex operator precedence
6509 @cindex precedence of operators
6510
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.
6515
6516 @menu
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.
6522 @end menu
6523
6524 @node Why Precedence
6525 @subsection When Precedence is Needed
6526
6527 Consider the following ambiguous grammar fragment (ambiguous because the
6528 input @w{@samp{1 - 2 * 3}} can be parsed in two different ways):
6529
6530 @example
6531 @group
6532 expr: expr '-' expr
6533 | expr '*' expr
6534 | expr '<' expr
6535 | '(' expr ')'
6536 @dots{}
6537 ;
6538 @end group
6539 @end example
6540
6541 @noindent
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
6549 different results.
6550
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
6559 @samp{<}.
6560
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.
6570
6571 @node Using Precedence
6572 @subsection Specifying Operator Precedence
6573 @findex %left
6574 @findex %nonassoc
6575 @findex %precedence
6576 @findex %right
6577
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
6585 row''.
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.
6594
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.
6600
6601 @node Precedence Only
6602 @subsection Specifying Precedence Only
6603 @findex %precedence
6604
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.
6612
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
6616 state:
6617
6618 @example
6619 if @var{e1} then if @var{e2} then @var{s1} . else @var{s2}
6620 @end example
6621
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.
6629
6630 @example
6631 %precedence THEN
6632 %precedence ELSE
6633 @end example
6634
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{}
6642
6643 @node Precedence Examples
6644 @subsection Precedence Examples
6645
6646 In our example, we would want the following declarations:
6647
6648 @example
6649 %left '<'
6650 %left '-'
6651 %left '*'
6652 @end example
6653
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{'-'}:
6657
6658 @example
6659 %left '<' '>' '=' NE LE GE
6660 %left '+' '-'
6661 %left '*' '/'
6662 @end example
6663
6664 @noindent
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.)
6668
6669 @node How Precedence
6670 @subsection How Precedence Works
6671
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}.)
6678
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
6686 resolved.
6687
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.
6690
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
6697 @findex %prec
6698
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.
6703
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}
6708 modifier for rules.
6709
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:
6714
6715 @example
6716 %prec @var{terminal-symbol}
6717 @end example
6718
6719 @noindent
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}).
6725
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
6729 precedence:
6730
6731 @example
6732 @dots{}
6733 %left '+' '-'
6734 %left '*'
6735 %left UMINUS
6736 @end example
6737
6738 Now the precedence of @code{UMINUS} can be used in specific rules:
6739
6740 @example
6741 @group
6742 exp: @dots{}
6743 | exp '-' exp
6744 @dots{}
6745 | '-' exp %prec UMINUS
6746 @end group
6747 @end example
6748
6749 @ifset defaultprec
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.
6754
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.
6759
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.
6766
6767 The effect of @code{%no-default-prec;} can be reversed by giving
6768 @code{%default-prec;}, which is the default.
6769 @end ifset
6770
6771 @node Parser States
6772 @section Parser States
6773 @cindex finite-state machine
6774 @cindex parser state
6775 @cindex state (of parser)
6776
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.
6782
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
6791 pushed.
6792
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}).
6796
6797 @node Reduce/Reduce
6798 @section Reduce/Reduce Conflicts
6799 @cindex reduce/reduce conflict
6800 @cindex conflicts, reduce/reduce
6801
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
6804 in the grammar.
6805
6806 For example, here is an erroneous attempt to define a sequence
6807 of zero or more @code{word} groupings.
6808
6809 @example
6810 sequence: /* empty */
6811 @{ printf ("empty sequence\n"); @}
6812 | maybeword
6813 | sequence word
6814 @{ printf ("added word %s\n", $2); @}
6815 ;
6816
6817 maybeword: /* empty */
6818 @{ printf ("empty maybeword\n"); @}
6819 | word
6820 @{ printf ("single word %s\n", $1); @}
6821 ;
6822 @end example
6823
6824 @noindent
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}.
6831
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.
6835
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.
6841
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}:
6846
6847 @example
6848 sequence: /* empty */
6849 @{ printf ("empty sequence\n"); @}
6850 | sequence word
6851 @{ printf ("added word %s\n", $2); @}
6852 ;
6853 @end example
6854
6855 Here is another common error that yields a reduce/reduce conflict:
6856
6857 @example
6858 sequence: /* empty */
6859 | sequence words
6860 | sequence redirects
6861 ;
6862
6863 words: /* empty */
6864 | words word
6865 ;
6866
6867 redirects:/* empty */
6868 | redirects redirect
6869 ;
6870 @end example
6871
6872 @noindent
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!
6878
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.
6883
6884 Here are two ways to correct these rules. First, to make it a single level
6885 of sequence:
6886
6887 @example
6888 sequence: /* empty */
6889 | sequence word
6890 | sequence redirect
6891 ;
6892 @end example
6893
6894 Second, to prevent either a @code{words} or a @code{redirects}
6895 from being empty:
6896
6897 @example
6898 sequence: /* empty */
6899 | sequence words
6900 | sequence redirects
6901 ;
6902
6903 words: word
6904 | words word
6905 ;
6906
6907 redirects:redirect
6908 | redirects redirect
6909 ;
6910 @end example
6911
6912 @node Mystery Conflicts
6913 @section Mysterious Reduce/Reduce Conflicts
6914
6915 Sometimes reduce/reduce conflicts can occur that don't look warranted.
6916 Here is an example:
6917
6918 @example
6919 @group
6920 %token ID
6921
6922 %%
6923 def: param_spec return_spec ','
6924 ;
6925 param_spec:
6926 type
6927 | name_list ':' type
6928 ;
6929 @end group
6930 @group
6931 return_spec:
6932 type
6933 | name ':' type
6934 ;
6935 @end group
6936 @group
6937 type: ID
6938 ;
6939 @end group
6940 @group
6941 name: ID
6942 ;
6943 name_list:
6944 name
6945 | name ',' name_list
6946 ;
6947 @end group
6948 @end example
6949
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).
6954
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
6962 same.
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).
6970
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
6980 are experimental.
6981 More user feedback will help to stabilize them.)
6982
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:
6988
6989 @example
6990 @group
6991 %token BOGUS
6992 @dots{}
6993 %%
6994 @dots{}
6995 return_spec:
6996 type
6997 | name ':' type
6998 /* This rule is never used. */
6999 | ID BOGUS
7000 ;
7001 @end group
7002 @end example
7003
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.
7010
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}.
7017
7018 @example
7019 param_spec:
7020 type
7021 | name_list ':' type
7022 ;
7023 return_spec:
7024 type
7025 | ID ':' type
7026 ;
7027 @end example
7028
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}.
7035
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
7042
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.
7056
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
7065 situation, it
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.
7071
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
7083 stream.
7084
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.
7097
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.
7114
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},
7120 (2000-12-24).
7121
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
7129
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.
7133
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}.
7137
7138 @vindex YYMAXDEPTH
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.
7143
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.
7150
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
7154 @code{YYINITDEPTH}.
7155
7156 @cindex default stack limit
7157 The default value of @code{YYMAXDEPTH}, if you do not define it, is
7158 10000.
7159
7160 @vindex YYINITDEPTH
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.
7166
7167 Do not allow @code{YYINITDEPTH} to be greater than @code{YYMAXDEPTH}.
7168
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.
7175
7176 @node Error Recovery
7177 @chapter Error Recovery
7178 @cindex error recovery
7179 @cindex recovery from errors
7180
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
7184 another expression.
7185
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.
7193
7194 @findex error
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.
7201
7202 For example:
7203
7204 @example
7205 stmnts: /* empty string */
7206 | stmnts '\n'
7207 | stmnts exp '\n'
7208 | stmnts error '\n'
7209 @end example
7210
7211 The fourth rule in this example says that an error followed by a newline
7212 makes a valid addition to any @code{stmnts}.
7213
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.
7221
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.
7234
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:
7238
7239 @example
7240 stmnt: error ';' /* On error, skip until ';' is read. */
7241 @end example
7242
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:
7247
7248 @example
7249 primary: '(' expr ')'
7250 | '(' error ')'
7251 @dots{}
7252 ;
7253 @end example
7254
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
7262 @code{stmnt}.
7263
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.
7268
7269 Note that rules which accept the @code{error} token may have actions, just
7270 as any other rules can.
7271
7272 @findex yyerrok
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.
7277
7278 @findex yyclearin
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
7282 action.
7283 @xref{Action Features, ,Special Features for Use in Actions}.
7284
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;}.
7290
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
7295 error.
7296
7297 @node Context Dependency
7298 @chapter Handling Context Dependencies
7299
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
7304 languages.
7305
7306 @menu
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.
7311 @end menu
7312
7313 (Actually, ``kludge'' means any technique that gets its job done but is
7314 neither clean nor robust.)
7315
7316 @node Semantic Tokens
7317 @section Semantic Info in Token Types
7318
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:
7321
7322 @example
7323 foo (x);
7324 @end example
7325
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?
7329
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.
7335
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.
7343
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
7348 earlier:
7349
7350 @example
7351 typedef int foo, bar;
7352 int baz (void)
7353 @{
7354 static bar (bar); /* @r{redeclare @code{bar} as static variable} */
7355 extern foo foo (foo); /* @r{redeclare @code{foo} as function} */
7356 return foo (bar);
7357 @}
7358 @end example
7359
7360 Unfortunately, the name being declared is separated from the declaration
7361 construct itself by a complicated syntactic structure---the ``declarator''.
7362
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:
7368
7369 @example
7370 initdcl:
7371 declarator maybeasm '='
7372 init
7373 | declarator maybeasm
7374 ;
7375
7376 notype_initdcl:
7377 notype_declarator maybeasm '='
7378 init
7379 | notype_declarator maybeasm
7380 ;
7381 @end example
7382
7383 @noindent
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.
7387
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.
7394
7395 @node Lexical Tie-ins
7396 @section Lexical Tie-ins
7397 @cindex lexical tie-in
7398
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
7401 parsed.
7402
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:
7408
7409 @example
7410 @group
7411 %@{
7412 int hexflag;
7413 int yylex (void);
7414 void yyerror (char const *);
7415 %@}
7416 %%
7417 @dots{}
7418 @end group
7419 @group
7420 expr: IDENTIFIER
7421 | constant
7422 | HEX '('
7423 @{ hexflag = 1; @}
7424 expr ')'
7425 @{ hexflag = 0;
7426 $$ = $4; @}
7427 | expr '+' expr
7428 @{ $$ = make_sum ($1, $3); @}
7429 @dots{}
7430 ;
7431 @end group
7432
7433 @group
7434 constant:
7435 INTEGER
7436 | STRING
7437 ;
7438 @end group
7439 @end example
7440
7441 @noindent
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.
7445
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.
7449
7450 @node Tie-in Recovery
7451 @section Lexical Tie-ins and Error Recovery
7452
7453 Lexical tie-ins make strict demands on any error recovery rules you have.
7454 @xref{Error Recovery}.
7455
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:
7460
7461 @example
7462 stmt: expr ';'
7463 | IF '(' expr ')' stmt @{ @dots{} @}
7464 @dots{}
7465 error ';'
7466 @{ hexflag = 0; @}
7467 ;
7468 @end example
7469
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.
7475
7476 To avoid this problem the error recovery rule itself clears @code{hexflag}.
7477
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:
7481
7482 @example
7483 @group
7484 expr: @dots{}
7485 | '(' expr ')'
7486 @{ $$ = $2; @}
7487 | '(' error ')'
7488 @dots{}
7489 @end group
7490 @end example
7491
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.
7496
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
7503 clear the flag.
7504
7505 @c ================================================== Debugging Your Parser
7506
7507 @node Debugging
7508 @chapter Debugging Your Parser
7509
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}).
7516
7517 @menu
7518 * Understanding:: Understanding the structure of your parser.
7519 * Tracing:: Tracing the execution of your parser.
7520 @end menu
7521
7522 @node Understanding
7523 @section Understanding Your Parser
7524
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).
7530
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}.
7538
7539 The following grammar file, @file{calc.y}, will be used in the sequel:
7540
7541 @example
7542 %token NUM STR
7543 %left '+' '-'
7544 %left '*'
7545 %%
7546 exp: exp '+' exp
7547 | exp '-' exp
7548 | exp '*' exp
7549 | exp '/' exp
7550 | NUM
7551 ;
7552 useless: STR;
7553 %%
7554 @end example
7555
7556 @command{bison} reports:
7557
7558 @example
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
7564 @end example
7565
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.
7570
7571 The first section includes details on conflicts that were solved thanks
7572 to precedence and/or associativity:
7573
7574 @example
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.
7578 @exdent @dots{}
7579 @end example
7580
7581 @noindent
7582 The next section lists states that still have conflicts.
7583
7584 @example
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
7589 @end example
7590
7591 @noindent
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''
7602 below):
7603
7604 @example
7605 Nonterminals useless in grammar:
7606 useless
7607
7608 Terminals unused in grammar:
7609 STR
7610
7611 Rules useless in grammar:
7612 #6 useless: STR;
7613 @end example
7614
7615 @noindent
7616 The next section reproduces the exact grammar that Bison used:
7617
7618 @example
7619 Grammar
7620
7621 Number, Line, Rule
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
7627 5 9 exp -> NUM
7628 @end example
7629
7630 @noindent
7631 and reports the uses of the symbols:
7632
7633 @example
7634 Terminals, with rules where they appear
7635
7636 $end (0) 0
7637 '*' (42) 3
7638 '+' (43) 1
7639 '-' (45) 2
7640 '/' (47) 4
7641 error (256)
7642 NUM (258) 5
7643
7644 Nonterminals, with rules where they appear
7645
7646 $accept (8)
7647 on left: 0
7648 exp (9)
7649 on left: 1 2 3 4 5, on right: 0 1 2 3 4
7650 @end example
7651
7652 @noindent
7653 @cindex item
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.
7660
7661 @example
7662 state 0
7663
7664 $accept -> . exp $ (rule 0)
7665
7666 NUM shift, and go to state 1
7667
7668 exp go to state 2
7669 @end example
7670
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.''
7679
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
7690 be derived:
7691
7692 @example
7693 state 0
7694
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)
7701
7702 NUM shift, and go to state 1
7703
7704 exp go to state 2
7705 @end example
7706
7707 @noindent
7708 In the state 1...
7709
7710 @example
7711 state 1
7712
7713 exp -> NUM . (rule 5)
7714
7715 $default reduce using rule 5 (exp)
7716 @end example
7717
7718 @noindent
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}).
7723
7724 @example
7725 state 2
7726
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)
7732
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
7738 @end example
7739
7740 @noindent
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.
7747
7748 @cindex accepting state
7749 The state 3 is named the @dfn{final state}, or the @dfn{accepting
7750 state}:
7751
7752 @example
7753 state 3
7754
7755 $accept -> exp $ . (rule 0)
7756
7757 $default accept
7758 @end example
7759
7760 @noindent
7761 the initial rule is completed (the start symbol and the end
7762 of input were read), the parsing exits successfully.
7763
7764 The interpretation of states 4 to 7 is straightforward, and is left to
7765 the reader.
7766
7767 @example
7768 state 4
7769
7770 exp -> exp '+' . exp (rule 1)
7771
7772 NUM shift, and go to state 1
7773
7774 exp go to state 8
7775
7776 state 5
7777
7778 exp -> exp '-' . exp (rule 2)
7779
7780 NUM shift, and go to state 1
7781
7782 exp go to state 9
7783
7784 state 6
7785
7786 exp -> exp '*' . exp (rule 3)
7787
7788 NUM shift, and go to state 1
7789
7790 exp go to state 10
7791
7792 state 7
7793
7794 exp -> exp '/' . exp (rule 4)
7795
7796 NUM shift, and go to state 1
7797
7798 exp go to state 11
7799 @end example
7800
7801 As was announced in beginning of the report, @samp{State 8 conflicts:
7802 1 shift/reduce}:
7803
7804 @example
7805 state 8
7806
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)
7812
7813 '*' shift, and go to state 6
7814 '/' shift, and go to state 7
7815
7816 '/' [reduce using rule 1 (exp)]
7817 $default reduce using rule 1 (exp)
7818 @end example
7819
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.
7828
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
7832 square brackets.
7833
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:
7846
7847 @example
7848 state 8
7849
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)
7855
7856 '*' shift, and go to state 6
7857 '/' shift, and go to state 7
7858
7859 '/' [reduce using rule 1 (exp)]
7860 $default reduce using rule 1 (exp)
7861 @end example
7862
7863 The remaining states are similar:
7864
7865 @example
7866 state 9
7867
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)
7873
7874 '*' shift, and go to state 6
7875 '/' shift, and go to state 7
7876
7877 '/' [reduce using rule 2 (exp)]
7878 $default reduce using rule 2 (exp)
7879
7880 state 10
7881
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)
7887
7888 '/' shift, and go to state 7
7889
7890 '/' [reduce using rule 3 (exp)]
7891 $default reduce using rule 3 (exp)
7892
7893 state 11
7894
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)
7900
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
7905
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)
7911 @end example
7912
7913 @noindent
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.
7918
7919
7920 @node Tracing
7921 @section Tracing Your Parser
7922 @findex yydebug
7923 @cindex debugging
7924 @cindex tracing the parser
7925
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.
7928
7929 There are several means to enable compilation of trace facilities:
7930
7931 @table @asis
7932 @item the macro @code{YYDEBUG}
7933 @findex 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
7938 Prologue}).
7939
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.
7943
7944 @item the directive @samp{%debug}
7945 @findex %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.
7949
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
7957 preferred solution.
7958 @end table
7959
7960 We suggest that you always enable the trace option so that debugging is
7961 always possible.
7962
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}.
7969
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.
7974
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:
7978
7979 @itemize @bullet
7980 @item
7981 Each time the parser calls @code{yylex}, what kind of token was read.
7982
7983 @item
7984 Each time a token is shifted, the depth and complete contents of the
7985 state stack (@pxref{Parser States}).
7986
7987 @item
7988 Each time a rule is reduced, which rule it is, and the complete contents
7989 of the state stack afterward.
7990 @end itemize
7991
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.
8001
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.
8007
8008 @findex YYPRINT
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}).
8015
8016 Here is an example of @code{YYPRINT} suitable for the multi-function
8017 calculator (@pxref{Mfcalc Declarations, ,Declarations for @code{mfcalc}}):
8018
8019 @smallexample
8020 %@{
8021 static void print_token_value (FILE *, int, YYSTYPE);
8022 #define YYPRINT(file, type, value) print_token_value (file, type, value)
8023 %@}
8024
8025 @dots{} %% @dots{} %% @dots{}
8026
8027 static void
8028 print_token_value (FILE *file, int type, YYSTYPE value)
8029 @{
8030 if (type == VAR)
8031 fprintf (file, "%s", value.tptr->name);
8032 else if (type == NUM)
8033 fprintf (file, "%d", value.val);
8034 @}
8035 @end smallexample
8036
8037 @c ================================================= Invoking Bison
8038
8039 @node Invocation
8040 @chapter Invoking Bison
8041 @cindex invoking Bison
8042 @cindex Bison invocation
8043 @cindex options for invoking Bison
8044
8045 The usual way to invoke Bison is as follows:
8046
8047 @example
8048 bison @var{infile}
8049 @end example
8050
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}.
8063
8064 For example :
8065
8066 @example
8067 bison -d @var{infile.yxx}
8068 @end example
8069 @noindent
8070 will produce @file{infile.tab.cxx} and @file{infile.tab.hxx}, and
8071
8072 @example
8073 bison -d -o @var{output.c++} @var{infile.y}
8074 @end example
8075 @noindent
8076 will produce @file{output.c++} and @file{outfile.h++}.
8077
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.
8081
8082 @menu
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}.
8087 @end menu
8088
8089 @node Bison Options
8090 @section Bison Options
8091
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
8097 @samp{=}.
8098
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
8101 option.
8102
8103 @c Please, keep this ordered as in `bison --help'.
8104 @noindent
8105 Operations modes:
8106 @table @option
8107 @item -h
8108 @itemx --help
8109 Print a summary of the command-line options to Bison and exit.
8110
8111 @item -V
8112 @itemx --version
8113 Print the version number of Bison and exit.
8114
8115 @item --print-localedir
8116 Print the name of the directory containing locale-dependent data.
8117
8118 @item --print-datadir
8119 Print the name of the directory containing skeletons and XSLT.
8120
8121 @item -y
8122 @itemx --yacc
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
8128 @file{y.tab.h}.
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
8131 names.
8132 Thus, the following shell script can substitute for Yacc, and the Bison
8133 distribution contains such a script for compatibility with @acronym{POSIX}:
8134
8135 @example
8136 #! /bin/sh
8137 bison -y "$@@"
8138 @end example
8139
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.
8144
8145 @item -W [@var{category}]
8146 @itemx --warnings[=@var{category}]
8147 Output warnings falling in @var{category}. @var{category} can be one
8148 of:
8149 @table @code
8150 @item midrule-values
8151 Warn about mid-rule values that are set but not used within any of the actions
8152 of the parent rule.
8153 For example, warn about unused @code{$2} in:
8154
8155 @example
8156 exp: '1' @{ $$ = 1; @} '+' exp @{ $$ = $1 + $4; @};
8157 @end example
8158
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:
8161
8162 @example
8163 exp: '1' @{ $1 = 1; @} '+' exp @{ $$ = $2 + $4; @};
8164 @end example
8165
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).
8169
8170
8171 @item yacc
8172 Incompatibilities with @acronym{POSIX} Yacc.
8173
8174 @item all
8175 All the warnings.
8176 @item none
8177 Turn off all the warnings.
8178 @item error
8179 Treat warnings as errors.
8180 @end table
8181
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
8184 variables.
8185 @end table
8186
8187 @noindent
8188 Tuning the parser:
8189
8190 @table @option
8191 @item -t
8192 @itemx --debug
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}.
8196
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:
8204
8205 @itemize
8206 @item
8207 Bison quietly ignores all command-line definitions for @var{name} except
8208 the last.
8209 @item
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}.
8213 @item
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}.
8217 @item
8218 Otherwise, Bison reports an error if there are multiple @code{%define}
8219 definitions for @var{name}.
8220 @end itemize
8221
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.
8225
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.
8232
8233 This option is experimental and its effect may be modified in future
8234 releases.
8235
8236 @item --locations
8237 Pretend that @code{%locations} was specified. @xref{Decl Summary}.
8238
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}.
8243
8244 @item -l
8245 @itemx --no-lines
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.
8251
8252 @item -S @var{file}
8253 @itemx --skeleton=@var{file}
8254 Specify the skeleton to use, similar to @code{%skeleton}
8255 (@pxref{Decl Summary, , Bison Declaration Summary}).
8256
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.
8261
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.
8267
8268 @item -k
8269 @itemx --token-table
8270 Pretend that @code{%token-table} was specified. @xref{Decl Summary}.
8271 @end table
8272
8273 @noindent
8274 Adjust the output:
8275
8276 @table @option
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}.
8281
8282 @item -d
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.
8286
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}.
8291
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:
8296
8297 @table @code
8298 @item state
8299 Description of the grammar, conflicts (resolved and unresolved), and
8300 parser's automaton.
8301
8302 @item lookahead
8303 Implies @code{state} and augments the description of the automaton with
8304 each rule's lookahead set.
8305
8306 @item itemset
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.
8309 @end table
8310
8311 @item --report-file=@var{file}
8312 Specify the @var{file} for the verbose description.
8313
8314 @item -v
8315 @itemx --verbose
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}.
8319
8320 @item -o @var{file}
8321 @itemx --output=@var{file}
8322 Specify the @var{file} for the parser file.
8323
8324 The other output files' names are constructed from @var{file} as
8325 described under the @samp{-v} and @samp{-d} options.
8326
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
8334 @file{foo.dot}.
8335
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
8341 @file{foo.xml}.
8342 (The current XML schema is experimental and may evolve.
8343 More user feedback will help to stabilize it.)
8344 @end table
8345
8346 @node Option Cross Key
8347 @section Option Cross Key
8348
8349 Here is a list of options, alphabetized by long option, to help you find
8350 the corresponding short option and directive.
8351
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
8355 @end multitable
8356
8357 @node Yacc Library
8358 @section Yacc Library
8359
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}).
8367
8368 If you use the Yacc library's @code{yyerror} function, you should
8369 declare @code{yyerror} as follows:
8370
8371 @example
8372 int yyerror (char const *);
8373 @end example
8374
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:
8378
8379 @example
8380 int yyparse (void);
8381 @end example
8382
8383 @c ================================================= C++ Bison
8384
8385 @node Other Languages
8386 @chapter Parsers Written In Other Languages
8387
8388 @menu
8389 * C++ Parsers:: The interface to generate C++ parser classes
8390 * Java Parsers:: The interface to generate Java parser classes
8391 @end menu
8392
8393 @node C++ Parsers
8394 @section C++ Parsers
8395
8396 @menu
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
8403 @end menu
8404
8405 @node C++ Bison Interface
8406 @subsection C++ Bison Interface
8407 @c - %skeleton "lalr1.cc"
8408 @c - Always pure
8409 @c - initial action
8410
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}.
8415
8416 When run, @command{bison} will create several entities in the @samp{yy}
8417 namespace.
8418 @findex %define api.namespace
8419 Use the @samp{%define api.namespace} directive to change the namespace
8420 name, see
8421 @ref{Decl Summary}.
8422 The various classes are generated in the following files:
8423
8424 @table @file
8425 @item position.hh
8426 @itemx location.hh
8427 The definition of the classes @code{position} and @code{location},
8428 used for location tracking. @xref{C++ Location Values}.
8429
8430 @item stack.hh
8431 An auxiliary class @code{stack} used by the parser.
8432
8433 @item @var{file}.hh
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}).
8439
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.
8443 @end table
8444
8445 All these files are documented using Doxygen; run @command{doxygen}
8446 for a complete and accurate documentation.
8447
8448 @node C++ Semantic Values
8449 @subsection C++ Semantic Values
8450 @c - No objects in unions
8451 @c - YYSTYPE
8452 @c - Printer and destructor
8453
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++.
8459 @itemize @minus
8460 @item
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}.
8464 @item
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.
8468 @end itemize
8469
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
8473 Symbols}.
8474
8475
8476 @node C++ Location Values
8477 @subsection C++ Location Values
8478 @c - %locations
8479 @c - class Position
8480 @c - class Location
8481 @c - %define filename_type "const symbol::Symbol"
8482
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).
8488
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}"}.
8494 @end deftypemethod
8495
8496 @deftypemethod {position} {unsigned int} line
8497 The line, starting at 1.
8498 @end deftypemethod
8499
8500 @deftypemethod {position} {unsigned int} lines (int @var{height} = 1)
8501 Advance by @var{height} lines, resetting the column number.
8502 @end deftypemethod
8503
8504 @deftypemethod {position} {unsigned int} column
8505 The column, starting at 0.
8506 @end deftypemethod
8507
8508 @deftypemethod {position} {unsigned int} columns (int @var{width} = 1)
8509 Advance by @var{width} columns, without changing the line number.
8510 @end deftypemethod
8511
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}.
8517 @end deftypemethod
8518
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.
8523 @end deftypemethod
8524
8525 @deftypemethod {location} {position} begin
8526 @deftypemethodx {location} {position} end
8527 The first, inclusive, position of the range, and the first beyond.
8528 @end deftypemethod
8529
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.
8533 @end deftypemethod
8534
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.
8539 @end deftypemethod
8540
8541 @deftypemethod {location} {void} step ()
8542 Move @code{begin} onto @code{end}.
8543 @end deftypemethod
8544
8545
8546 @node C++ Parser Interface
8547 @subsection C++ Parser Interface
8548 @c - define parser_class_name
8549 @c - Ctor
8550 @c - parse, error, set_debug_level, debug_level, set_debug_stream,
8551 @c debug_stream.
8552 @c - Reporting errors
8553
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.
8562
8563 @defcv {Type} {parser} {semantic_value_type}
8564 @defcvx {Type} {parser} {location_value_type}
8565 The types for semantics value and locations.
8566 @end defcv
8567
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.
8571 @end deftypemethod
8572
8573 @deftypemethod {parser} {int} parse ()
8574 Run the syntactic analysis, and return 0 on success, 1 otherwise.
8575 @end deftypemethod
8576
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
8580 @code{std::cerr}.
8581 @end deftypemethod
8582
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.
8587 @end deftypemethod
8588
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}.
8593 @end deftypemethod
8594
8595
8596 @node C++ Scanner Interface
8597 @subsection C++ Scanner Interface
8598 @c - prefix for yylex.
8599 @c - Pure interface to yylex
8600 @c - %lex-param
8601
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.
8605
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.
8610 @end deftypemethod
8611
8612
8613 @node A Complete C++ Example
8614 @subsection A Complete C++ Example
8615
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.
8624
8625 @menu
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
8631 @end menu
8632
8633 @node Calc++ --- C++ Calculator
8634 @subsubsection Calc++ --- C++ Calculator
8635
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.
8641
8642 @example
8643 three := 3
8644 seven := one + two * three
8645 seven * seven
8646 @end example
8647
8648 @node Calc++ Parsing Driver
8649 @subsubsection Calc++ Parsing Driver
8650 @c - An env
8651 @c - A place to store error messages
8652 @c - A place for the result
8653
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.
8661
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
8665 class.
8666
8667 @comment file: calc++-driver.hh
8668 @example
8669 #ifndef CALCXX_DRIVER_HH
8670 # define CALCXX_DRIVER_HH
8671 # include <string>
8672 # include <map>
8673 # include "calc++-parser.hh"
8674 @end example
8675
8676
8677 @noindent
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.
8682
8683 @comment file: calc++-driver.hh
8684 @example
8685 // Tell Flex the lexer's prototype ...
8686 # define YY_DECL \
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.
8692 YY_DECL;
8693 @end example
8694
8695 @noindent
8696 The @code{calcxx_driver} class is then declared with its most obvious
8697 members.
8698
8699 @comment file: calc++-driver.hh
8700 @example
8701 // Conducting the whole scanning and parsing of Calc++.
8702 class calcxx_driver
8703 @{
8704 public:
8705 calcxx_driver ();
8706 virtual ~calcxx_driver ();
8707
8708 std::map<std::string, int> variables;
8709
8710 int result;
8711 @end example
8712
8713 @noindent
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.
8716
8717 @comment file: calc++-driver.hh
8718 @example
8719 // Handling the scanner.
8720 void scan_begin ();
8721 void scan_end ();
8722 bool trace_scanning;
8723 @end example
8724
8725 @noindent
8726 Similarly for the parser itself.
8727
8728 @comment file: calc++-driver.hh
8729 @example
8730 // Run the parser. Return 0 on success.
8731 int parse (const std::string& f);
8732 std::string file;
8733 bool trace_parsing;
8734 @end example
8735
8736 @noindent
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.
8741
8742 @comment file: calc++-driver.hh
8743 @example
8744 // Error handling.
8745 void error (const yy::location& l, const std::string& m);
8746 void error (const std::string& m);
8747 @};
8748 #endif // ! CALCXX_DRIVER_HH
8749 @end example
8750
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.
8755
8756 @comment file: calc++-driver.cc
8757 @example
8758 #include "calc++-driver.hh"
8759 #include "calc++-parser.hh"
8760
8761 calcxx_driver::calcxx_driver ()
8762 : trace_scanning (false), trace_parsing (false)
8763 @{
8764 variables["one"] = 1;
8765 variables["two"] = 2;
8766 @}
8767
8768 calcxx_driver::~calcxx_driver ()
8769 @{
8770 @}
8771
8772 int
8773 calcxx_driver::parse (const std::string &f)
8774 @{
8775 file = f;
8776 scan_begin ();
8777 yy::calcxx_parser parser (*this);
8778 parser.set_debug_level (trace_parsing);
8779 int res = parser.parse ();
8780 scan_end ();
8781 return res;
8782 @}
8783
8784 void
8785 calcxx_driver::error (const yy::location& l, const std::string& m)
8786 @{
8787 std::cerr << l << ": " << m << std::endl;
8788 @}
8789
8790 void
8791 calcxx_driver::error (const std::string& m)
8792 @{
8793 std::cerr << m << std::endl;
8794 @}
8795 @end example
8796
8797 @node Calc++ Parser
8798 @subsubsection Calc++ Parser
8799
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.
8805
8806 @comment file: calc++-parser.yy
8807 @example
8808 %skeleton "lalr1.cc" /* -*- C++ -*- */
8809 %require "@value{VERSION}"
8810 %defines
8811 %define parser_class_name "calcxx_parser"
8812 @end example
8813
8814 @noindent
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}.
8823
8824 @comment file: calc++-parser.yy
8825 @example
8826 %code requires @{
8827 # include <string>
8828 class calcxx_driver;
8829 @}
8830 @end example
8831
8832 @noindent
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
8835 global variables.
8836
8837 @comment file: calc++-parser.yy
8838 @example
8839 // The parsing context.
8840 %param @{ calcxx_driver& driver @}
8841 @end example
8842
8843 @noindent
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
8847 propagated.
8848
8849 @comment file: calc++-parser.yy
8850 @example
8851 %locations
8852 %initial-action
8853 @{
8854 // Initialize the initial location.
8855 @@$.begin.filename = @@$.end.filename = &driver.file;
8856 @};
8857 @end example
8858
8859 @noindent
8860 Use the following two directives to enable parser tracing and verbose
8861 error messages.
8862
8863 @comment file: calc++-parser.yy
8864 @example
8865 %define parse.trace
8866 %define parse.error verbose
8867 @end example
8868
8869 @noindent
8870 Semantic values cannot use ``real'' objects, but only pointers to
8871 them.
8872
8873 @comment file: calc++-parser.yy
8874 @example
8875 // Symbols.
8876 %union
8877 @{
8878 int ival;
8879 std::string *sval;
8880 @};
8881 @end example
8882
8883 @noindent
8884 @findex %code
8885 The code between @samp{%code @{} and @samp{@}} is output in the
8886 @file{*.cc} file; it needs detailed knowledge about the driver.
8887
8888 @comment file: calc++-parser.yy
8889 @example
8890 %code @{
8891 # include "calc++-driver.hh"
8892 @}
8893 @end example
8894
8895
8896 @noindent
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}).
8902
8903 @comment file: calc++-parser.yy
8904 @example
8905 %define api.tokens.prefix "TOK_"
8906 %token END 0 "end of file"
8907 %token ASSIGN ":="
8908 %token <sval> IDENTIFIER "identifier"
8909 %token <ival> NUMBER "number"
8910 %type <ival> exp
8911 @end example
8912
8913 @noindent
8914 To enable memory deallocation during error recovery, use
8915 @code{%destructor}.
8916
8917 @c FIXME: Document %printer, and mention that it takes a braced-code operand.
8918 @comment file: calc++-parser.yy
8919 @example
8920 %printer @{ debug_stream () << *$$; @} "identifier"
8921 %destructor @{ delete $$; @} "identifier"
8922
8923 %printer @{ debug_stream () << $$; @} <ival>
8924 @end example
8925
8926 @noindent
8927 The grammar itself is straightforward.
8928
8929 @comment file: calc++-parser.yy
8930 @example
8931 %%
8932 %start unit;
8933 unit: assignments exp @{ driver.result = $2; @};
8934
8935 assignments:
8936 assignments assignment @{@}
8937 | /* Nothing. */ @{@};
8938
8939 assignment:
8940 "identifier" ":=" exp
8941 @{ driver.variables[*$1] = $3; delete $1; @};
8942
8943 %left '+' '-';
8944 %left '*' '/';
8945 exp:
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; @};
8953 %%
8954 @end example
8955
8956 @noindent
8957 Finally the @code{error} member function registers the errors to the
8958 driver.
8959
8960 @comment file: calc++-parser.yy
8961 @example
8962 void
8963 yy::calcxx_parser::error (const yy::calcxx_parser::location_type& l,
8964 const std::string& m)
8965 @{
8966 driver.error (l, m);
8967 @}
8968 @end example
8969
8970 @node Calc++ Scanner
8971 @subsubsection Calc++ Scanner
8972
8973 The Flex scanner first includes the driver declaration, then the
8974 parser's to get the set of defined tokens.
8975
8976 @comment file: calc++-scanner.ll
8977 @example
8978 %@{ /* -*- C++ -*- */
8979 # include <cstdlib>
8980 # include <cerrno>
8981 # include <climits>
8982 # include <string>
8983 # include "calc++-driver.hh"
8984 # include "calc++-parser.hh"
8985
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>. */
8990 # undef yywrap
8991 # define yywrap() 1
8992
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)
8997 %@}
8998 @end example
8999
9000 @noindent
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.
9005
9006 @comment file: calc++-scanner.ll
9007 @example
9008 %option noyywrap nounput batch debug
9009 @end example
9010
9011 @noindent
9012 Abbreviations allow for more readable rules.
9013
9014 @comment file: calc++-scanner.ll
9015 @example
9016 id [a-zA-Z][a-zA-Z_0-9]*
9017 int [0-9]+
9018 blank [ \t]
9019 @end example
9020
9021 @noindent
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.
9029
9030 @comment file: calc++-scanner.ll
9031 @example
9032 %@{
9033 # define YY_USER_ACTION yylloc->columns (yyleng);
9034 %@}
9035 %%
9036 %@{
9037 yylloc->step ();
9038 %@}
9039 @{blank@}+ yylloc->step ();
9040 [\n]+ yylloc->lines (yyleng); yylloc->step ();
9041 @end example
9042
9043 @noindent
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_}.
9048
9049 @comment file: calc++-scanner.ll
9050 @example
9051 %@{
9052 # define TOKEN(Name) \
9053 yy::calcxx_parser::token::TOK_ ## Name
9054 %@}
9055 /* Convert ints to the actual type of tokens. */
9056 [-+*/()] return yy::calcxx_parser::token_type (yytext[0]);
9057 ":=" return TOKEN(ASSIGN);
9058 @{int@} @{
9059 errno = 0;
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");
9063 yylval->ival = n;
9064 return TOKEN(NUMBER);
9065 @}
9066 @{id@} @{
9067 yylval->sval = new std::string (yytext);
9068 return TOKEN(IDENTIFIER);
9069 @}
9070 . driver.error (*yylloc, "invalid character");
9071 %%
9072 @end example
9073
9074 @noindent
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.
9077
9078 @comment file: calc++-scanner.ll
9079 @example
9080 void
9081 calcxx_driver::scan_begin ()
9082 @{
9083 yy_flex_debug = trace_scanning;
9084 if (file == "-")
9085 yyin = stdin;
9086 else if (!(yyin = fopen (file.c_str (), "r")))
9087 @{
9088 error (std::string ("cannot open ") + file);
9089 exit (1);
9090 @}
9091 @}
9092
9093 void
9094 calcxx_driver::scan_end ()
9095 @{
9096 fclose (yyin);
9097 @}
9098 @end example
9099
9100 @node Calc++ Top Level
9101 @subsubsection Calc++ Top Level
9102
9103 The top level file, @file{calc++.cc}, poses no problem.
9104
9105 @comment file: calc++.cc
9106 @example
9107 #include <iostream>
9108 #include "calc++-driver.hh"
9109
9110 int
9111 main (int argc, char *argv[])
9112 @{
9113 int res = 0;
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;
9122 else
9123 res = 1;
9124 return res;
9125 @}
9126 @end example
9127
9128 @node Java Parsers
9129 @section Java Parsers
9130
9131 @menu
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
9140 @end menu
9141
9142 @node Java Bison Interface
9143 @subsection Java Bison Interface
9144 @c - %language "Java"
9145
9146 (The current Java interface is experimental and may evolve.
9147 More user feedback will help to stabilize it.)
9148
9149 The Java parser skeletons are selected using the @code{%language "Java"}
9150 directive or the @option{-L java}/@option{--language=java} option.
9151
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.
9161
9162 You can create documentation for generated parsers using Javadoc.
9163
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
9168 Java.
9169
9170 Push parsers are currently unsupported in Java and @code{%define
9171 api.push-pull} have no effect.
9172
9173 @acronym{GLR} parsers are currently unsupported in Java. Do not use the
9174 @code{glr-parser} directive.
9175
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.
9178
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}
9182 directives and the
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}
9186 explicitly
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.
9190
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.
9195
9196
9197 @node Java Semantic Values
9198 @subsection Java Semantic Values
9199 @c - No %union, specify type in %type/%token.
9200 @c - YYSTYPE
9201 @c - Printer and destructor
9202
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:
9206
9207 @example
9208 %type <Expression> expr assignment_expr term factor
9209 %type <Integer> number
9210 @end example
9211
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:
9217
9218 @example
9219 %define stype "ASTNode"
9220 @end example
9221
9222 @noindent
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.
9225
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.
9232
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.
9236
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.
9240
9241
9242 @node Java Location Values
9243 @subsection Java Location Values
9244 @c - %locations
9245 @c - class Position
9246 @c - class Location
9247
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}"}.
9256
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.
9261
9262
9263 @deftypeivar {Location} {Position} begin
9264 @deftypeivarx {Location} {Position} end
9265 The first, inclusive, position of the range, and the first beyond.
9266 @end deftypeivar
9267
9268 @deftypeop {Constructor} {Location} {} Location (Position @var{loc})
9269 Create a @code{Location} denoting an empty range located at a given point.
9270 @end deftypeop
9271
9272 @deftypeop {Constructor} {Location} {} Location (Position @var{begin}, Position @var{end})
9273 Create a @code{Location} from the endpoints of the range.
9274 @end deftypeop
9275
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.
9280 @end deftypemethod
9281
9282
9283 @node Java Parser Interface
9284 @subsection Java Parser Interface
9285 @c - define parser_class_name
9286 @c - Ctor
9287 @c - parse, error, set_debug_level, debug_level, set_debug_stream,
9288 @c debug_stream.
9289 @c - Reporting errors
9290
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.
9296
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.
9305
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.
9310
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.
9317
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.
9322
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.
9327
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.
9331 @end deftypeop
9332
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
9336 used.
9337
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.
9341
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.
9345 @end deftypeop
9346
9347 @deftypemethod {YYParser} {boolean} parse ()
9348 Run the syntactic analysis, and return @code{true} on success,
9349 @code{false} otherwise.
9350 @end deftypemethod
9351
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.
9357 @end deftypemethod
9358
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.
9365 @end deftypemethod
9366
9367 @deftypemethod {YYParser} {boolean} recovering ()
9368 During the syntactic analysis, return @code{true} if recovering
9369 from a syntax error.
9370 @xref{Error Recovery}.
9371 @end deftypemethod
9372
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
9376 @code{System.err}.
9377 @end deftypemethod
9378
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.
9383 @end deftypemethod
9384
9385 @deftypecv {Constant} {YYParser} {String} {bisonVersion}
9386 @deftypecvx {Constant} {YYParser} {String} {bisonSkeleton}
9387 Identify the Bison version and skeleton used to generate this parser.
9388 @end deftypecv
9389
9390
9391 @node Java Scanner Interface
9392 @subsection Java Scanner Interface
9393 @c - %code lexer
9394 @c - %lex-param
9395 @c - Lexer interface
9396
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
9402 @code{EOF} token.
9403
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
9408 constructor.
9409
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
9414 case.
9415
9416 In both cases, the scanner has to implement the following methods.
9417
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}".}
9422 @end deftypemethod
9423
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
9427 interface.
9428
9429 Use @samp{%define lex_throws} to specify any uncaught exceptions.
9430 Default is @code{java.io.IOException}.
9431 @end deftypemethod
9432
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.
9438
9439 The return type can be changed using @samp{%define position_type
9440 "@var{class-name}".}
9441 @end deftypemethod
9442
9443 @deftypemethod {Lexer} {Object} getLVal ()
9444 Return the semantical value of the last token that yylex returned.
9445
9446 The return type can be changed using @samp{%define stype
9447 "@var{class-name}".}
9448 @end deftypemethod
9449
9450
9451 @node Java Action Features
9452 @subsection Special Features for Use in Java Actions
9453
9454 The following special constructs can be uses in Java actions.
9455 Other analogous C action features are currently unavailable for Java.
9456
9457 Use @samp{%define throws} to specify any uncaught exceptions from parser
9458 actions, and initial actions specified by @code{%initial-action}.
9459
9460 @defvar $@var{n}
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}.
9464 @end defvar
9465
9466 @defvar $<@var{typealt}>@var{n}
9467 Like @code{$@var{n}} but specifies a alternative type @var{typealt}.
9468 @xref{Java Semantic Values}.
9469 @end defvar
9470
9471 @defvar $$
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}.
9478 @end defvar
9479
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
9484 these constructs.
9485 @xref{Java Semantic Values}.
9486 @end defvar
9487
9488 @defvar @@@var{n}
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}.
9492 @end defvar
9493
9494 @defvar @@$
9495 The location information of the grouping made by the current rule.
9496 @xref{Java Location Values}.
9497 @end defvar
9498
9499 @deffn {Statement} {return YYABORT;}
9500 Return immediately from the parser, indicating failure.
9501 @xref{Java Parser Interface}.
9502 @end deffn
9503
9504 @deffn {Statement} {return YYACCEPT;}
9505 Return immediately from the parser, indicating success.
9506 @xref{Java Parser Interface}.
9507 @end deffn
9508
9509 @deffn {Statement} {return YYERROR;}
9510 Start error recovery without printing an error message.
9511 @xref{Error Recovery}.
9512 @end deffn
9513
9514 @deffn {Statement} {return YYFAIL;}
9515 Print an error message and start error recovery.
9516 @xref{Error Recovery}.
9517 @end deffn
9518
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
9522 operation.
9523 @xref{Error Recovery}.
9524 @end deftypefn
9525
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.
9532 @end deftypefn
9533
9534
9535 @node Java Differences
9536 @subsection Differences between C/C++ and Java Grammars
9537
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.
9541
9542 @itemize
9543 @item
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}.
9551
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.}.
9557
9558 @item
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}.
9568
9569 @item
9570 The prolog declarations have a different meaning than in C/C++ code.
9571 @table @asis
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.
9576
9577 @item unqualified @code{%code}
9578 blocks are placed inside the parser class.
9579
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
9584 Interface}).
9585 @end table
9586
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.
9590
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}
9593 the parser class.
9594 @end itemize
9595
9596
9597 @node Java Declarations Summary
9598 @subsection Java Declarations Summary
9599
9600 This summary only include declarations specific to Java or have special
9601 meaning when used in a Java parser.
9602
9603 @deffn {Directive} {%language "Java"}
9604 Generate a Java class for the parser.
9605 @end deffn
9606
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}.
9612 @end deffn
9613
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}.
9618 @end deffn
9619
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}.
9624 @end deffn
9625
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}.
9629 @end deffn
9630
9631 @deffn {Directive} %type <@var{type}> @var{nonterminal} @dots{}
9632 Declare the type of nonterminals. Note that the angle brackets enclose
9633 a Java @emph{type}.
9634 @xref{Java Semantic Values}.
9635 @end deffn
9636
9637 @deffn {Directive} %code @{ @var{code} @dots{} @}
9638 Code appended to the inside of the parser class.
9639 @xref{Java Differences}.
9640 @end deffn
9641
9642 @deffn {Directive} {%code imports} @{ @var{code} @dots{} @}
9643 Code inserted just after the @code{package} declaration.
9644 @xref{Java Differences}.
9645 @end deffn
9646
9647 @deffn {Directive} {%code init} @{ @var{code} @dots{} @}
9648 Code inserted at the beginning of the parser constructor body.
9649 @xref{Java Parser Interface}.
9650 @end deffn
9651
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}.
9655 @end deffn
9656
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}.
9661 @end deffn
9662
9663 @deffn {Directive} %@{ @var{code} @dots{} %@}
9664 Not supported. Use @code{%code imports} instead.
9665 @xref{Java Differences}.
9666 @end deffn
9667
9668 @deffn {Directive} {%define abstract}
9669 Whether the parser class is declared @code{abstract}. Default is false.
9670 @xref{Java Bison Interface}.
9671 @end deffn
9672
9673 @deffn {Directive} {%define annotations} "@var{annotations}"
9674 The Java annotations for the parser class. Default is none.
9675 @xref{Java Bison Interface}.
9676 @end deffn
9677
9678 @deffn {Directive} {%define extends} "@var{superclass}"
9679 The superclass of the parser class. Default is none.
9680 @xref{Java Bison Interface}.
9681 @end deffn
9682
9683 @deffn {Directive} {%define final}
9684 Whether the parser class is declared @code{final}. Default is false.
9685 @xref{Java Bison Interface}.
9686 @end deffn
9687
9688 @deffn {Directive} {%define implements} "@var{interfaces}"
9689 The implemented interfaces of the parser class, a comma-separated list.
9690 Default is none.
9691 @xref{Java Bison Interface}.
9692 @end deffn
9693
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}.
9698 @end deffn
9699
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}.
9704 @end deffn
9705
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}.
9711 @end deffn
9712
9713 @deffn {Directive} {%define package} "@var{package}"
9714 The package to put the parser class in. Default is none.
9715 @xref{Java Bison Interface}.
9716 @end deffn
9717
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}.
9722 @end deffn
9723
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}.
9728 @end deffn
9729
9730 @deffn {Directive} {%define public}
9731 Whether the parser class is declared @code{public}. Default is false.
9732 @xref{Java Bison Interface}.
9733 @end deffn
9734
9735 @deffn {Directive} {%define stype} "@var{class}"
9736 The base type of semantic values. Default is @code{Object}.
9737 @xref{Java Semantic Values}.
9738 @end deffn
9739
9740 @deffn {Directive} {%define strictfp}
9741 Whether the parser class is declared @code{strictfp}. Default is false.
9742 @xref{Java Bison Interface}.
9743 @end deffn
9744
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}.
9749 @end deffn
9750
9751
9752 @c ================================================= FAQ
9753
9754 @node FAQ
9755 @chapter Frequently Asked Questions
9756 @cindex frequently asked questions
9757 @cindex questions
9758
9759 Several questions about Bison come up occasionally. Here some of them
9760 are addressed.
9761
9762 @menu
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
9775 @end menu
9776
9777 @node Memory Exhausted
9778 @section Memory Exhausted
9779
9780 @display
9781 My parser returns with error with a @samp{memory exhausted}
9782 message. What can I do?
9783 @end display
9784
9785 This question is already addressed elsewhere, @xref{Recursion,
9786 ,Recursive Rules}.
9787
9788 @node How Can I Reset the Parser
9789 @section How Can I Reset the Parser
9790
9791 The following phenomenon has several symptoms, resulting in the
9792 following typical questions:
9793
9794 @display
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}?
9798 @end display
9799
9800 @noindent
9801 or
9802
9803 @display
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}.
9807 @end display
9808
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}:
9814
9815 @verbatim
9816 %{
9817 #include <stdio.h>
9818 #include <stdlib.h>
9819 %}
9820 %%
9821 .*\n ECHO; return 1;
9822 %%
9823 int
9824 yyparse (char const *file)
9825 {
9826 yyin = fopen (file, "r");
9827 if (!yyin)
9828 exit (2);
9829 /* One token only. */
9830 yylex ();
9831 if (fclose (yyin) != 0)
9832 exit (3);
9833 return 0;
9834 }
9835
9836 int
9837 main (void)
9838 {
9839 yyparse ("input");
9840 yyparse ("input");
9841 return 0;
9842 }
9843 @end verbatim
9844
9845 @noindent
9846 If the file @file{input} contains
9847
9848 @verbatim
9849 input:1: Hello,
9850 input:2: World!
9851 @end verbatim
9852
9853 @noindent
9854 then instead of getting the first line twice, you get:
9855
9856 @example
9857 $ @kbd{flex -ofirst-line.c first-line.l}
9858 $ @kbd{gcc -ofirst-line first-line.c -ll}
9859 $ @kbd{./first-line}
9860 input:1: Hello,
9861 input:2: World!
9862 @end example
9863
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
9872 input buffers.
9873
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)}.
9878
9879 @node Strings are Destroyed
9880 @section Strings are Destroyed
9881
9882 @display
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"}.
9886 @end display
9887
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:
9891
9892 @verbatim
9893 %{
9894 #include <stdio.h>
9895 char *yylval = NULL;
9896 %}
9897 %%
9898 .* yylval = yytext; return 1;
9899 \n /* IGNORE */
9900 %%
9901 int
9902 main ()
9903 {
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);
9908 return 0;
9909 }
9910 @end verbatim
9911
9912 If you compile and run this code, you get:
9913
9914 @example
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}
9918 "one
9919 two", "two"
9920 @end example
9921
9922 @noindent
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:
9929
9930 @example
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}
9934 "two", "two"
9935 @end example
9936
9937
9938 @node Implementing Gotos/Loops
9939 @section Implementing Gotos/Loops
9940
9941 @display
9942 My simple calculator supports variables, assignments, and functions,
9943 but how can I implement gotos, or loops?
9944 @end display
9945
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.
9953
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
9962 compiler.
9963
9964 This topic is way beyond the scope of this manual, and the reader is
9965 invited to consult the dedicated literature.
9966
9967
9968 @node Multiple start-symbols
9969 @section Multiple start-symbols
9970
9971 @display
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.
9975 @end display
9976
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
9981 real start-symbol:
9982
9983 @example
9984 %token START_FOO START_BAR;
9985 %start start;
9986 start: START_FOO foo
9987 | START_BAR bar;
9988 @end example
9989
9990 These tokens prevents the introduction of new conflicts. As far as the
9991 parser goes, that is all that is needed.
9992
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:
10001
10002 @example
10003 /* @r{Prologue.} */
10004 %%
10005 %@{
10006 if (start_token)
10007 @{
10008 int t = start_token;
10009 start_token = 0;
10010 return t;
10011 @}
10012 %@}
10013 /* @r{The rules.} */
10014 @end example
10015
10016
10017 @node Secure? Conform?
10018 @section Secure? Conform?
10019
10020 @display
10021 Is Bison secure? Does it conform to POSIX?
10022 @end display
10023
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.
10028
10029 @node I can't build Bison
10030 @section I can't build Bison
10031
10032 @display
10033 I can't build Bison because @command{make} complains that
10034 @code{msgfmt} is not found.
10035 What should I do?
10036 @end display
10037
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.
10045
10046
10047 @node Where can I find help?
10048 @section Where can I find help?
10049
10050 @display
10051 I'm having trouble using Bison. Where can I find help?
10052 @end display
10053
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
10062 hearts.
10063
10064 @node Bug Reports
10065 @section Bug Reports
10066
10067 @display
10068 I found a bug. What should I include in the bug report?
10069 @end display
10070
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.
10076
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.
10082
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').
10089
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.
10092
10093 Send bug reports to @email{bug-bison@@gnu.org}.
10094
10095 @node More Languages
10096 @section More Languages
10097
10098 @display
10099 Will Bison ever have C++ and Java support? How about @var{insert your
10100 favorite language here}?
10101 @end display
10102
10103 C++ and Java support is there now, and is documented. We'd love to add other
10104 languages; contributions are welcome.
10105
10106 @node Beta Testing
10107 @section Beta Testing
10108
10109 @display
10110 What is involved in being a beta tester?
10111 @end display
10112
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.
10120
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.
10125
10126 @node Mailing Lists
10127 @section Mailing Lists
10128
10129 @display
10130 How do I join the help-bison and bug-bison mailing lists?
10131 @end display
10132
10133 See @url{http://lists.gnu.org/}.
10134
10135 @c ================================================= Table of Symbols
10136
10137 @node Table of Symbols
10138 @appendix Bison Symbols
10139 @cindex Bison symbols, table of
10140 @cindex symbols in Bison, table of
10141
10142 @deffn {Variable} @@$
10143 In an action, the location of the left-hand side of the rule.
10144 @xref{Locations, , Locations Overview}.
10145 @end deffn
10146
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}.
10150 @end deffn
10151
10152 @deffn {Variable} $$
10153 In an action, the semantic value of the left-hand side of the rule.
10154 @xref{Actions}.
10155 @end deffn
10156
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}.
10160 @end deffn
10161
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}.
10166 @end deffn
10167
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
10173 Grammar}.
10174 @end deffn
10175
10176 @deffn {Construct} /*@dots{}*/
10177 Comment delimiters, as in C.
10178 @end deffn
10179
10180 @deffn {Delimiter} :
10181 Separates a rule's result from its components. @xref{Rules, ,Syntax of
10182 Grammar Rules}.
10183 @end deffn
10184
10185 @deffn {Delimiter} ;
10186 Terminates a rule. @xref{Rules, ,Syntax of Grammar Rules}.
10187 @end deffn
10188
10189 @deffn {Delimiter} |
10190 Separates alternate rules for the same result nonterminal.
10191 @xref{Rules, ,Syntax of Grammar Rules}.
10192 @end deffn
10193
10194 @deffn {Directive} <*>
10195 Used to define a default tagged @code{%destructor} or default tagged
10196 @code{%printer}.
10197
10198 This feature is experimental.
10199 More user feedback will help to determine whether it should become a permanent
10200 feature.
10201
10202 @xref{Destructor Decl, , Freeing Discarded Symbols}.
10203 @end deffn
10204
10205 @deffn {Directive} <>
10206 Used to define a default tagless @code{%destructor} or default tagless
10207 @code{%printer}.
10208
10209 This feature is experimental.
10210 More user feedback will help to determine whether it should become a permanent
10211 feature.
10212
10213 @xref{Destructor Decl, , Freeing Discarded Symbols}.
10214 @end deffn
10215
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.
10220 @end deffn
10221
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}.
10226 @end deffn
10227
10228 @deffn {Directive} %debug
10229 Equip the parser for debugging. @xref{Decl Summary}.
10230 @end deffn
10231
10232 @ifset defaultprec
10233 @deffn {Directive} %default-prec
10234 Assign a precedence to rules that lack an explicit @samp{%prec}
10235 modifier. @xref{Contextual Precedence, ,Context-Dependent
10236 Precedence}.
10237 @end deffn
10238 @end ifset
10239
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}.
10245 @end deffn
10246
10247 @deffn {Directive} %defines
10248 Bison declaration to create a header file meant for the scanner.
10249 @xref{Decl Summary}.
10250 @end deffn
10251
10252 @deffn {Directive} %defines @var{defines-file}
10253 Same as above, but save in the file @var{defines-file}.
10254 @xref{Decl Summary}.
10255 @end deffn
10256
10257 @deffn {Directive} %destructor
10258 Specify how the parser should reclaim the memory associated to
10259 discarded symbols. @xref{Destructor Decl, , Freeing Discarded Symbols}.
10260 @end deffn
10261
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}.
10266 @end deffn
10267
10268 @deffn {Symbol} $end
10269 The predefined token marking the end of the token stream. It cannot be
10270 used in the grammar.
10271 @end deffn
10272
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}.
10282 @end deffn
10283
10284 @deffn {Directive} %error-verbose
10285 An obsolete directive standing for @samp{%define parse.error verbose}.
10286 @end deffn
10287
10288 @deffn {Directive} %file-prefix "@var{prefix}"
10289 Bison declaration to set the prefix of the output files. @xref{Decl
10290 Summary}.
10291 @end deffn
10292
10293 @deffn {Directive} %glr-parser
10294 Bison declaration to produce a @acronym{GLR} parser. @xref{GLR
10295 Parsers, ,Writing @acronym{GLR} Parsers}.
10296 @end deffn
10297
10298 @deffn {Directive} %initial-action
10299 Run user code before parsing. @xref{Initial Action Decl, , Performing Actions before Parsing}.
10300 @end deffn
10301
10302 @deffn {Directive} %language
10303 Specify the programming language for the generated parser.
10304 @xref{Decl Summary}.
10305 @end deffn
10306
10307 @deffn {Directive} %left
10308 Bison declaration to assign precedence and left associativity to token(s).
10309 @xref{Precedence Decl, ,Operator Precedence}.
10310 @end deffn
10311
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
10315 for Pure Parsers}.
10316 @end deffn
10317
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}.
10323 @end deffn
10324
10325 @deffn {Directive} %name-prefix "@var{prefix}"
10326 Bison declaration to rename the external symbols. @xref{Decl Summary}.
10327 @end deffn
10328
10329 @ifset defaultprec
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
10333 Precedence}.
10334 @end deffn
10335 @end ifset
10336
10337 @deffn {Directive} %no-lines
10338 Bison declaration to avoid generating @code{#line} directives in the
10339 parser file. @xref{Decl Summary}.
10340 @end deffn
10341
10342 @deffn {Directive} %nonassoc
10343 Bison declaration to assign precedence and nonassociativity to token(s).
10344 @xref{Precedence Decl, ,Operator Precedence}.
10345 @end deffn
10346
10347 @deffn {Directive} %output "@var{file}"
10348 Bison declaration to set the name of the parser file. @xref{Decl
10349 Summary}.
10350 @end deffn
10351
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}}.
10356 @end deffn
10357
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}}.
10361 @end deffn
10362
10363 @deffn {Directive} %prec
10364 Bison declaration to assign a precedence to a specific rule.
10365 @xref{Contextual Precedence, ,Context-Dependent Precedence}.
10366 @end deffn
10367
10368 @deffn {Directive} %precedence
10369 Bison declaration to assign precedence to token(s), but no associativity
10370 @xref{Precedence Decl, ,Operator Precedence}.
10371 @end deffn
10372
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.
10376 @end deffn
10377
10378 @deffn {Directive} %require "@var{version}"
10379 Require version @var{version} or higher of Bison. @xref{Require Decl, ,
10380 Require a Version of Bison}.
10381 @end deffn
10382
10383 @deffn {Directive} %right
10384 Bison declaration to assign precedence and right associativity to token(s).
10385 @xref{Precedence Decl, ,Operator Precedence}.
10386 @end deffn
10387
10388 @deffn {Directive} %skeleton
10389 Specify the skeleton to use; usually for development.
10390 @xref{Decl Summary}.
10391 @end deffn
10392
10393 @deffn {Directive} %start
10394 Bison declaration to specify the start symbol. @xref{Start Decl, ,The
10395 Start-Symbol}.
10396 @end deffn
10397
10398 @deffn {Directive} %token
10399 Bison declaration to declare token(s) without specifying precedence.
10400 @xref{Token Decl, ,Token Type Names}.
10401 @end deffn
10402
10403 @deffn {Directive} %token-table
10404 Bison declaration to include a token name table in the parser file.
10405 @xref{Decl Summary}.
10406 @end deffn
10407
10408 @deffn {Directive} %type
10409 Bison declaration to declare nonterminals. @xref{Type Decl,
10410 ,Nonterminal Symbols}.
10411 @end deffn
10412
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
10416 @code{error}.
10417 @end deffn
10418
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}.
10422 @end deffn
10423
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}}.
10429
10430 For Java parsers, this functionality is invoked using @code{return YYABORT;}
10431 instead.
10432 @end deffn
10433
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}}.
10438
10439 For Java parsers, this functionality is invoked using @code{return YYACCEPT;}
10440 instead.
10441 @end deffn
10442
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}.
10446 @end deffn
10447
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}.
10453 @end deffn
10454
10455 @deffn {Variable} yyclearin
10456 Macro used in error-recovery rule actions. It clears the previous
10457 lookahead token. @xref{Error Recovery}.
10458 @end deffn
10459
10460 @deffn {Macro} YYDEBUG
10461 Macro to define to equip the parser with tracing code. @xref{Tracing,
10462 ,Tracing Your Parser}.
10463 @end deffn
10464
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}.
10469 @end deffn
10470
10471 @deffn {Macro} yyerrok
10472 Macro to cause parser to recover immediately to its normal mode
10473 after a syntax error. @xref{Error Recovery}.
10474 @end deffn
10475
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}.
10481
10482 For Java parsers, this functionality is invoked using @code{return YYERROR;}
10483 instead.
10484 @end deffn
10485
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}}.
10489 @end deffn
10490
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}}).
10498 @end deffn
10499
10500 @deffn {Macro} YYINITDEPTH
10501 Macro for specifying the initial size of the parser stack.
10502 @xref{Memory Management}.
10503 @end deffn
10504
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
10508 @code{yylex}}.
10509 @end deffn
10510
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}.
10516 @end deffn
10517
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
10522 @code{yylex}.)
10523 You can ignore this variable if you don't use the @samp{@@} feature in the
10524 grammar actions.
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}.
10528 @end deffn
10529
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}.
10533 @end deffn
10534
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
10539 @code{yylex}.)
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}.
10543 @end deffn
10544
10545 @deffn {Macro} YYMAXDEPTH
10546 Macro for specifying the maximum size of the parser stack. @xref{Memory
10547 Management}.
10548 @end deffn
10549
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}}.
10555 @end deffn
10556
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}}.
10560 @end deffn
10561
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.)
10569 @end deffn
10570
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.)
10578 @end deffn
10579
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.)
10587 @end deffn
10588
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.)
10595 @end deffn
10596
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}.
10602 @end deffn
10603
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}.
10608 @end deffn
10609
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.
10617
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.
10625 @end deffn
10626
10627 @deffn {Type} YYSTYPE
10628 Data type of semantic values; @code{int} by default.
10629 @xref{Value Type, ,Data Types of Semantic Values}.
10630 @end deffn
10631
10632 @node Glossary
10633 @appendix Glossary
10634 @cindex glossary
10635
10636 @table @asis
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,,}.
10641
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}.
10647
10648 @item Consistent State
10649 A state containing only one possible action.
10650 @xref{Decl Summary,,lr.default-reductions}.
10651
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
10657 Grammars}.
10658
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
10664 lookahead set.
10665 @xref{Decl Summary,,lr.default-reductions}.
10666
10667 @item Dynamic allocation
10668 Allocation of memory that occurs during execution, rather than at
10669 compile time or on entry to a function.
10670
10671 @item Empty string
10672 Analogous to the empty set in set theory, the empty string is a
10673 character string of length zero.
10674
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}.
10682
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}.
10691
10692 @item Grouping
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}.
10696
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
10702 @acronym{LALR}(1).
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}.
10710
10711 @item Infix operator
10712 An arithmetic operator that is placed between the operands on which it
10713 performs some operation.
10714
10715 @item Input stream
10716 A continuous flow of data between devices or programs.
10717
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}.
10722
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}.
10727
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
10731 Rules}.
10732
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}.
10736
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}}.
10740
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}.
10744
10745 @item Literal string token
10746 A token which consists of two or more fixed characters. @xref{Symbols}.
10747
10748 @item Lookahead token
10749 A token already read but not yet shifted. @xref{Lookahead, ,Lookahead
10750 Tokens}.
10751
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}.
10756
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.
10760
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}.
10765
10766 @item Parser
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
10769 analyzer.
10770
10771 @item Postfix operator
10772 An arithmetic operator that is placed after the operands upon which it
10773 performs some operation.
10774
10775 @item Reduction
10776 Replacing a string of nonterminals and/or terminals with a single
10777 nonterminal, according to a grammar rule. @xref{Algorithm, ,The Bison
10778 Parser Algorithm}.
10779
10780 @item Reentrant
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}.
10784
10785 @item Reverse polish notation
10786 A language in which all operators are postfix operators.
10787
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
10791 Rules}.
10792
10793 @item Semantics
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}.
10797
10798 @item Shift
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}.
10802
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}.
10806
10807 @item Start symbol
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}.
10812
10813 @item Symbol table
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}.
10817
10818 @item Syntax error
10819 An error encountered during parsing of an input stream due to invalid
10820 syntax. @xref{Error Recovery}.
10821
10822 @item Token
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}.
10827
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}.
10832 @end table
10833
10834 @node Copying This Manual
10835 @appendix Copying This Manual
10836 @include fdl.texi
10837
10838 @node Index
10839 @unnumbered Index
10840
10841 @printindex cp
10842
10843 @bye
10844
10845 @c Local Variables:
10846 @c fill-column: 76
10847 @c End:
10848
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