diff options
Diffstat (limited to 'gnuwin32/contrib/bison/2.4.1/bison-2.4.1-src/doc/bison.info')
| -rw-r--r-- | gnuwin32/contrib/bison/2.4.1/bison-2.4.1-src/doc/bison.info | 11009 |
1 files changed, 11009 insertions, 0 deletions
diff --git a/gnuwin32/contrib/bison/2.4.1/bison-2.4.1-src/doc/bison.info b/gnuwin32/contrib/bison/2.4.1/bison-2.4.1-src/doc/bison.info new file mode 100644 index 00000000..35f574f3 --- /dev/null +++ b/gnuwin32/contrib/bison/2.4.1/bison-2.4.1-src/doc/bison.info @@ -0,0 +1,11009 @@ +This is ../../bison-2.4.1-src/doc/bison.info, produced by makeinfo +version 4.8 from ../../bison-2.4.1-src/doc/bison.texinfo. + + This manual (19 November 2008) is for GNU Bison (version 2.4.1), the +GNU parser generator. + + Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998, 1999, +2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software +Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.2 or any later version published by the Free Software + Foundation; with no Invariant Sections, with the Front-Cover texts + being "A GNU Manual," and with the Back-Cover Texts as in (a) + below. A copy of the license is included in the section entitled + "GNU Free Documentation License." + + (a) The FSF's Back-Cover Text is: "You have the freedom to copy and + modify this GNU manual. Buying copies from the FSF supports it in + developing GNU and promoting software freedom." + +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* bison: (bison). GNU parser generator (Yacc replacement). +END-INFO-DIR-ENTRY + + +File: bison.info, Node: Top, Next: Introduction, Up: (dir) + +Bison +***** + +This manual (19 November 2008) is for GNU Bison (version 2.4.1), the +GNU parser generator. + + Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998, 1999, +2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software +Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.2 or any later version published by the Free Software + Foundation; with no Invariant Sections, with the Front-Cover texts + being "A GNU Manual," and with the Back-Cover Texts as in (a) + below. A copy of the license is included in the section entitled + "GNU Free Documentation License." + + (a) The FSF's Back-Cover Text is: "You have the freedom to copy and + modify this GNU manual. Buying copies from the FSF supports it in + developing GNU and promoting software freedom." + +* Menu: + +* Introduction:: +* Conditions:: +* Copying:: The GNU General Public License says + how you can copy and share Bison. + +Tutorial sections: +* Concepts:: Basic concepts for understanding Bison. +* Examples:: Three simple explained examples of using Bison. + +Reference sections: +* Grammar File:: Writing Bison declarations and rules. +* Interface:: C-language interface to the parser function `yyparse'. +* Algorithm:: How the Bison parser works at run-time. +* Error Recovery:: Writing rules for error recovery. +* Context Dependency:: What to do if your language syntax is too + messy for Bison to handle straightforwardly. +* Debugging:: Understanding or debugging Bison parsers. +* Invocation:: How to run Bison (to produce the parser source file). +* Other Languages:: Creating C++ and Java parsers. +* FAQ:: Frequently Asked Questions +* Table of Symbols:: All the keywords of the Bison language are explained. +* Glossary:: Basic concepts are explained. +* Copying This Manual:: License for copying this manual. +* Index:: Cross-references to the text. + + --- The Detailed Node Listing --- + +The Concepts of Bison + +* Language and Grammar:: Languages and context-free grammars, + as mathematical ideas. +* Grammar in Bison:: How we represent grammars for Bison's sake. +* Semantic Values:: Each token or syntactic grouping can have + a semantic value (the value of an integer, + the name of an identifier, etc.). +* Semantic Actions:: Each rule can have an action containing C code. +* GLR Parsers:: Writing parsers for general context-free languages. +* Locations Overview:: Tracking Locations. +* Bison Parser:: What are Bison's input and output, + how is the output used? +* Stages:: Stages in writing and running Bison grammars. +* Grammar Layout:: Overall structure of a Bison grammar file. + +Writing GLR Parsers + +* Simple GLR Parsers:: Using GLR parsers on unambiguous grammars. +* Merging GLR Parses:: Using GLR parsers to resolve ambiguities. +* GLR Semantic Actions:: Deferred semantic actions have special concerns. +* Compiler Requirements:: GLR parsers require a modern C compiler. + +Examples + +* RPN Calc:: Reverse polish notation calculator; + a first example with no operator precedence. +* Infix Calc:: Infix (algebraic) notation calculator. + Operator precedence is introduced. +* Simple Error Recovery:: Continuing after syntax errors. +* Location Tracking Calc:: Demonstrating the use of @N and @$. +* Multi-function Calc:: Calculator with memory and trig functions. + It uses multiple data-types for semantic values. +* Exercises:: Ideas for improving the multi-function calculator. + +Reverse Polish Notation Calculator + +* Rpcalc Declarations:: Prologue (declarations) for rpcalc. +* Rpcalc Rules:: Grammar Rules for rpcalc, with explanation. +* Rpcalc Lexer:: The lexical analyzer. +* Rpcalc Main:: The controlling function. +* Rpcalc Error:: The error reporting function. +* Rpcalc Generate:: Running Bison on the grammar file. +* Rpcalc Compile:: Run the C compiler on the output code. + +Grammar Rules for `rpcalc' + +* Rpcalc Input:: +* Rpcalc Line:: +* Rpcalc Expr:: + +Location Tracking Calculator: `ltcalc' + +* Ltcalc Declarations:: Bison and C declarations for ltcalc. +* Ltcalc Rules:: Grammar rules for ltcalc, with explanations. +* Ltcalc Lexer:: The lexical analyzer. + +Multi-Function Calculator: `mfcalc' + +* Mfcalc Declarations:: Bison declarations for multi-function calculator. +* Mfcalc Rules:: Grammar rules for the calculator. +* Mfcalc Symbol Table:: Symbol table management subroutines. + +Bison Grammar Files + +* Grammar Outline:: Overall layout of the grammar file. +* Symbols:: Terminal and nonterminal symbols. +* Rules:: How to write grammar rules. +* Recursion:: Writing recursive rules. +* Semantics:: Semantic values and actions. +* Locations:: Locations and actions. +* Declarations:: All kinds of Bison declarations are described here. +* Multiple Parsers:: Putting more than one Bison parser in one program. + +Outline of a Bison Grammar + +* Prologue:: Syntax and usage of the prologue. +* Prologue Alternatives:: Syntax and usage of alternatives to the prologue. +* Bison Declarations:: Syntax and usage of the Bison declarations section. +* Grammar Rules:: Syntax and usage of the grammar rules section. +* Epilogue:: Syntax and usage of the epilogue. + +Defining Language Semantics + +* Value Type:: Specifying one data type for all semantic values. +* Multiple Types:: Specifying several alternative data types. +* Actions:: An action is the semantic definition of a grammar rule. +* Action Types:: Specifying data types for actions to operate on. +* Mid-Rule Actions:: Most actions go at the end of a rule. + This says when, why and how to use the exceptional + action in the middle of a rule. + +Tracking Locations + +* Location Type:: Specifying a data type for locations. +* Actions and Locations:: Using locations in actions. +* Location Default Action:: Defining a general way to compute locations. + +Bison Declarations + +* Require Decl:: Requiring a Bison version. +* Token Decl:: Declaring terminal symbols. +* Precedence Decl:: Declaring terminals with precedence and associativity. +* Union Decl:: Declaring the set of all semantic value types. +* Type Decl:: Declaring the choice of type for a nonterminal symbol. +* Initial Action Decl:: Code run before parsing starts. +* Destructor Decl:: Declaring how symbols are freed. +* Expect Decl:: Suppressing warnings about parsing conflicts. +* Start Decl:: Specifying the start symbol. +* Pure Decl:: Requesting a reentrant parser. +* Push Decl:: Requesting a push parser. +* Decl Summary:: Table of all Bison declarations. + +Parser C-Language Interface + +* Parser Function:: How to call `yyparse' and what it returns. +* Push Parser Function:: How to call `yypush_parse' and what it returns. +* Pull Parser Function:: How to call `yypull_parse' and what it returns. +* Parser Create Function:: How to call `yypstate_new' and what it returns. +* Parser Delete Function:: How to call `yypstate_delete' and what it returns. +* Lexical:: You must supply a function `yylex' + which reads tokens. +* Error Reporting:: You must supply a function `yyerror'. +* Action Features:: Special features for use in actions. +* Internationalization:: How to let the parser speak in the user's + native language. + +The Lexical Analyzer Function `yylex' + +* Calling Convention:: How `yyparse' calls `yylex'. +* Token Values:: How `yylex' must return the semantic value + of the token it has read. +* Token Locations:: How `yylex' must return the text location + (line number, etc.) of the token, if the + actions want that. +* Pure Calling:: How the calling convention differs in a pure parser + (*note A Pure (Reentrant) Parser: Pure Decl.). + +The Bison Parser Algorithm + +* Lookahead:: Parser looks one token ahead when deciding what to do. +* Shift/Reduce:: Conflicts: when either shifting or reduction is valid. +* Precedence:: Operator precedence works by resolving conflicts. +* Contextual Precedence:: When an operator's precedence depends on context. +* Parser States:: The parser is a finite-state-machine with stack. +* Reduce/Reduce:: When two rules are applicable in the same situation. +* Mystery Conflicts:: Reduce/reduce conflicts that look unjustified. +* Generalized LR Parsing:: Parsing arbitrary context-free grammars. +* Memory Management:: What happens when memory is exhausted. How to avoid it. + +Operator Precedence + +* Why Precedence:: An example showing why precedence is needed. +* Using Precedence:: How to specify precedence in Bison grammars. +* Precedence Examples:: How these features are used in the previous example. +* How Precedence:: How they work. + +Handling Context Dependencies + +* Semantic Tokens:: Token parsing can depend on the semantic context. +* Lexical Tie-ins:: Token parsing can depend on the syntactic context. +* Tie-in Recovery:: Lexical tie-ins have implications for how + error recovery rules must be written. + +Debugging Your Parser + +* Understanding:: Understanding the structure of your parser. +* Tracing:: Tracing the execution of your parser. + +Invoking Bison + +* Bison Options:: All the options described in detail, + in alphabetical order by short options. +* Option Cross Key:: Alphabetical list of long options. +* Yacc Library:: Yacc-compatible `yylex' and `main'. + +Parsers Written In Other Languages + +* C++ Parsers:: The interface to generate C++ parser classes +* Java Parsers:: The interface to generate Java parser classes + +C++ Parsers + +* C++ Bison Interface:: Asking for C++ parser generation +* C++ Semantic Values:: %union vs. C++ +* C++ Location Values:: The position and location classes +* C++ Parser Interface:: Instantiating and running the parser +* C++ Scanner Interface:: Exchanges between yylex and parse +* A Complete C++ Example:: Demonstrating their use + +A Complete C++ Example + +* Calc++ --- C++ Calculator:: The specifications +* Calc++ Parsing Driver:: An active parsing context +* Calc++ Parser:: A parser class +* Calc++ Scanner:: A pure C++ Flex scanner +* Calc++ Top Level:: Conducting the band + +Java Parsers + +* Java Bison Interface:: Asking for Java parser generation +* Java Semantic Values:: %type and %token vs. Java +* Java Location Values:: The position and location classes +* Java Parser Interface:: Instantiating and running the parser +* Java Scanner Interface:: Specifying the scanner for the parser +* Java Action Features:: Special features for use in actions +* Java Differences:: Differences between C/C++ and Java Grammars +* Java Declarations Summary:: List of Bison declarations used with Java + +Frequently Asked Questions + +* Memory Exhausted:: Breaking the Stack Limits +* How Can I Reset the Parser:: `yyparse' Keeps some State +* Strings are Destroyed:: `yylval' Loses Track of Strings +* Implementing Gotos/Loops:: Control Flow in the Calculator +* Multiple start-symbols:: Factoring closely related grammars +* Secure? Conform?:: Is Bison POSIX safe? +* I can't build Bison:: Troubleshooting +* Where can I find help?:: Troubleshouting +* Bug Reports:: Troublereporting +* More Languages:: Parsers in C++, Java, and so on +* Beta Testing:: Experimenting development versions +* Mailing Lists:: Meeting other Bison users + +Copying This Manual + +* Copying This Manual:: License for copying this manual. + + +File: bison.info, Node: Introduction, Next: Conditions, Prev: Top, Up: Top + +Introduction +************ + +"Bison" is a general-purpose parser generator that converts an +annotated context-free grammar into an LALR(1) or GLR parser for that +grammar. Once you are proficient with Bison, you can use it to develop +a wide range of language parsers, from those used in simple desk +calculators to complex programming languages. + + Bison is upward compatible with Yacc: all properly-written Yacc +grammars ought to work with Bison with no change. Anyone familiar with +Yacc should be able to use Bison with little trouble. You need to be +fluent in C or C++ programming in order to use Bison or to understand +this manual. + + We begin with tutorial chapters that explain the basic concepts of +using Bison and show three explained examples, each building on the +last. If you don't know Bison or Yacc, start by reading these +chapters. Reference chapters follow which describe specific aspects of +Bison in detail. + + Bison was written primarily by Robert Corbett; Richard Stallman made +it Yacc-compatible. Wilfred Hansen of Carnegie Mellon University added +multi-character string literals and other features. + + This edition corresponds to version 2.4.1 of Bison. + + +File: bison.info, Node: Conditions, Next: Copying, Prev: Introduction, Up: Top + +Conditions for Using Bison +************************** + +The distribution terms for Bison-generated parsers permit using the +parsers in nonfree programs. Before Bison version 2.2, these extra +permissions applied only when Bison was generating LALR(1) parsers in +C. And before Bison version 1.24, Bison-generated parsers could be +used only in programs that were free software. + + The other GNU programming tools, such as the GNU C compiler, have +never had such a requirement. They could always be used for nonfree +software. The reason Bison was different was not due to a special +policy decision; it resulted from applying the usual General Public +License to all of the Bison source code. + + The output of the Bison utility--the Bison parser file--contains a +verbatim copy of a sizable piece of Bison, which is the code for the +parser's implementation. (The actions from your grammar are inserted +into this implementation at one point, but most of the rest of the +implementation is not changed.) When we applied the GPL terms to the +skeleton code for the parser's implementation, the effect was to +restrict the use of Bison output to free software. + + We didn't change the terms because of sympathy for people who want to +make software proprietary. *Software should be free.* But we +concluded that limiting Bison's use to free software was doing little to +encourage people to make other software free. So we decided to make the +practical conditions for using Bison match the practical conditions for +using the other GNU tools. + + This exception applies when Bison is generating code for a parser. +You can tell whether the exception applies to a Bison output file by +inspecting the file for text beginning with "As a special +exception...". The text spells out the exact terms of the exception. + + +File: bison.info, Node: Copying, Next: Concepts, Prev: Conditions, Up: Top + +GNU GENERAL PUBLIC LICENSE +************************** + + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. `http://fsf.org/' + + Everyone is permitted to copy and distribute verbatim copies of this + license document, but changing it is not allowed. + +Preamble +======== + +The GNU General Public License is a free, copyleft license for software +and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains +free software for all its users. We, the Free Software Foundation, use +the GNU General Public License for most of our software; it applies +also to any other work released this way by its authors. You can apply +it to your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you +have certain responsibilities if you distribute copies of the software, +or if you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the +manufacturer can do so. This is fundamentally incompatible with the +aim of protecting users' freedom to change the software. The +systematic pattern of such abuse occurs in the area of products for +individuals to use, which is precisely where it is most unacceptable. +Therefore, we have designed this version of the GPL to prohibit the +practice for those products. If such problems arise substantially in +other domains, we stand ready to extend this provision to those domains +in future versions of the GPL, as needed to protect the freedom of +users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + +TERMS AND CONDITIONS +==================== + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public + License. + + "Copyright" also means copyright-like laws that apply to other + kinds of works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this + License. Each licensee is addressed as "you". "Licensees" and + "recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the + work in a fashion requiring copyright permission, other than the + making of an exact copy. The resulting work is called a "modified + version" of the earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work + based on the Program. + + To "propagate" a work means to do anything with it that, without + permission, would make you directly or secondarily liable for + infringement under applicable copyright law, except executing it + on a computer or modifying a private copy. Propagation includes + copying, distribution (with or without modification), making + available to the public, and in some countries other activities as + well. + + To "convey" a work means any kind of propagation that enables other + parties to make or receive copies. Mere interaction with a user + through a computer network, with no transfer of a copy, is not + conveying. + + An interactive user interface displays "Appropriate Legal Notices" + to the extent that it includes a convenient and prominently visible + feature that (1) displays an appropriate copyright notice, and (2) + tells the user that there is no warranty for the work (except to + the extent that warranties are provided), that licensees may + convey the work under this License, and how to view a copy of this + License. If the interface presents a list of user commands or + options, such as a menu, a prominent item in the list meets this + criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work + for making modifications to it. "Object code" means any + non-source form of a work. + + A "Standard Interface" means an interface that either is an + official standard defined by a recognized standards body, or, in + the case of interfaces specified for a particular programming + language, one that is widely used among developers working in that + language. + + The "System Libraries" of an executable work include anything, + other than the work as a whole, that (a) is included in the normal + form of packaging a Major Component, but which is not part of that + Major Component, and (b) serves only to enable use of the work + with that Major Component, or to implement a Standard Interface + for which an implementation is available to the public in source + code form. A "Major Component", in this context, means a major + essential component (kernel, window system, and so on) of the + specific operating system (if any) on which the executable work + runs, or a compiler used to produce the work, or an object code + interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all + the source code needed to generate, install, and (for an executable + work) run the object code and to modify the work, including + scripts to control those activities. However, it does not include + the work's System Libraries, or general-purpose tools or generally + available free programs which are used unmodified in performing + those activities but which are not part of the work. For example, + Corresponding Source includes interface definition files + associated with source files for the work, and the source code for + shared libraries and dynamically linked subprograms that the work + is specifically designed to require, such as by intimate data + communication or control flow between those subprograms and other + parts of the work. + + The Corresponding Source need not include anything that users can + regenerate automatically from other parts of the Corresponding + Source. + + The Corresponding Source for a work in source code form is that + same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of + copyright on the Program, and are irrevocable provided the stated + conditions are met. This License explicitly affirms your unlimited + permission to run the unmodified Program. The output from running + a covered work is covered by this License only if the output, + given its content, constitutes a covered work. This License + acknowledges your rights of fair use or other equivalent, as + provided by copyright law. + + You may make, run and propagate covered works that you do not + convey, without conditions so long as your license otherwise + remains in force. You may convey covered works to others for the + sole purpose of having them make modifications exclusively for + you, or provide you with facilities for running those works, + provided that you comply with the terms of this License in + conveying all material for which you do not control copyright. + Those thus making or running the covered works for you must do so + exclusively on your behalf, under your direction and control, on + terms that prohibit them from making any copies of your + copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under + the conditions stated below. Sublicensing is not allowed; section + 10 makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological + measure under any applicable law fulfilling obligations under + article 11 of the WIPO copyright treaty adopted on 20 December + 1996, or similar laws prohibiting or restricting circumvention of + such measures. + + When you convey a covered work, you waive any legal power to forbid + circumvention of technological measures to the extent such + circumvention is effected by exercising rights under this License + with respect to the covered work, and you disclaim any intention + to limit operation or modification of the work as a means of + enforcing, against the work's users, your or third parties' legal + rights to forbid circumvention of technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you + receive it, in any medium, provided that you conspicuously and + appropriately publish on each copy an appropriate copyright notice; + keep intact all notices stating that this License and any + non-permissive terms added in accord with section 7 apply to the + code; keep intact all notices of the absence of any warranty; and + give all recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, + and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to + produce it from the Program, in the form of source code under the + terms of section 4, provided that you also meet all of these + conditions: + + a. The work must carry prominent notices stating that you + modified it, and giving a relevant date. + + b. The work must carry prominent notices stating that it is + released under this License and any conditions added under + section 7. This requirement modifies the requirement in + section 4 to "keep intact all notices". + + c. You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable + section 7 additional terms, to the whole of the work, and all + its parts, regardless of how they are packaged. This License + gives no permission to license the work in any other way, but + it does not invalidate such permission if you have separately + received it. + + d. If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has + interactive interfaces that do not display Appropriate Legal + Notices, your work need not make them do so. + + A compilation of a covered work with other separate and independent + works, which are not by their nature extensions of the covered + work, and which are not combined with it such as to form a larger + program, in or on a volume of a storage or distribution medium, is + called an "aggregate" if the compilation and its resulting + copyright are not used to limit the access or legal rights of the + compilation's users beyond what the individual works permit. + Inclusion of a covered work in an aggregate does not cause this + License to apply to the other parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms + of sections 4 and 5, provided that you also convey the + machine-readable Corresponding Source under the terms of this + License, in one of these ways: + + a. Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b. Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for + as long as you offer spare parts or customer support for that + product model, to give anyone who possesses the object code + either (1) a copy of the Corresponding Source for all the + software in the product that is covered by this License, on a + durable physical medium customarily used for software + interchange, for a price no more than your reasonable cost of + physically performing this conveying of source, or (2) access + to copy the Corresponding Source from a network server at no + charge. + + c. Convey individual copies of the object code with a copy of + the written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, + and only if you received the object code with such an offer, + in accord with subsection 6b. + + d. Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access + to the Corresponding Source in the same way through the same + place at no further charge. You need not require recipients + to copy the Corresponding Source along with the object code. + If the place to copy the object code is a network server, the + Corresponding Source may be on a different server (operated + by you or a third party) that supports equivalent copying + facilities, provided you maintain clear directions next to + the object code saying where to find the Corresponding Source. + Regardless of what server hosts the Corresponding Source, you + remain obligated to ensure that it is available for as long + as needed to satisfy these requirements. + + e. Convey the object code using peer-to-peer transmission, + provided you inform other peers where the object code and + Corresponding Source of the work are being offered to the + general public at no charge under subsection 6d. + + + A separable portion of the object code, whose source code is + excluded from the Corresponding Source as a System Library, need + not be included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means + any tangible personal property which is normally used for personal, + family, or household purposes, or (2) anything designed or sold for + incorporation into a dwelling. In determining whether a product + is a consumer product, doubtful cases shall be resolved in favor of + coverage. For a particular product received by a particular user, + "normally used" refers to a typical or common use of that class of + product, regardless of the status of the particular user or of the + way in which the particular user actually uses, or expects or is + expected to use, the product. A product is a consumer product + regardless of whether the product has substantial commercial, + industrial or non-consumer uses, unless such uses represent the + only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, + procedures, authorization keys, or other information required to + install and execute modified versions of a covered work in that + User Product from a modified version of its Corresponding Source. + The information must suffice to ensure that the continued + functioning of the modified object code is in no case prevented or + interfered with solely because modification has been made. + + If you convey an object code work under this section in, or with, + or specifically for use in, a User Product, and the conveying + occurs as part of a transaction in which the right of possession + and use of the User Product is transferred to the recipient in + perpetuity or for a fixed term (regardless of how the transaction + is characterized), the Corresponding Source conveyed under this + section must be accompanied by the Installation Information. But + this requirement does not apply if neither you nor any third party + retains the ability to install modified object code on the User + Product (for example, the work has been installed in ROM). + + The requirement to provide Installation Information does not + include a requirement to continue to provide support service, + warranty, or updates for a work that has been modified or + installed by the recipient, or for the User Product in which it + has been modified or installed. Access to a network may be denied + when the modification itself materially and adversely affects the + operation of the network or violates the rules and protocols for + communication across the network. + + Corresponding Source conveyed, and Installation Information + provided, in accord with this section must be in a format that is + publicly documented (and with an implementation available to the + public in source code form), and must require no special password + or key for unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of + this License by making exceptions from one or more of its + conditions. Additional permissions that are applicable to the + entire Program shall be treated as though they were included in + this License, to the extent that they are valid under applicable + law. If additional permissions apply only to part of the Program, + that part may be used separately under those permissions, but the + entire Program remains governed by this License without regard to + the additional permissions. + + When you convey a copy of a covered work, you may at your option + remove any additional permissions from that copy, or from any part + of it. (Additional permissions may be written to require their own + removal in certain cases when you modify the work.) You may place + additional permissions on material, added by you to a covered work, + for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material + you add to a covered work, you may (if authorized by the copyright + holders of that material) supplement the terms of this License + with terms: + + a. Disclaiming warranty or limiting liability differently from + the terms of sections 15 and 16 of this License; or + + b. Requiring preservation of specified reasonable legal notices + or author attributions in that material or in the Appropriate + Legal Notices displayed by works containing it; or + + c. Prohibiting misrepresentation of the origin of that material, + or requiring that modified versions of such material be + marked in reasonable ways as different from the original + version; or + + d. Limiting the use for publicity purposes of names of licensors + or authors of the material; or + + e. Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f. Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified + versions of it) with contractual assumptions of liability to + the recipient, for any liability that these contractual + assumptions directly impose on those licensors and authors. + + All other non-permissive additional terms are considered "further + restrictions" within the meaning of section 10. If the Program as + you received it, or any part of it, contains a notice stating that + it is governed by this License along with a term that is a further + restriction, you may remove that term. If a license document + contains a further restriction but permits relicensing or + conveying under this License, you may add to a covered work + material governed by the terms of that license document, provided + that the further restriction does not survive such relicensing or + conveying. + + If you add terms to a covered work in accord with this section, you + must place, in the relevant source files, a statement of the + additional terms that apply to those files, or a notice indicating + where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in + the form of a separately written license, or stated as exceptions; + the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly + provided under this License. Any attempt otherwise to propagate or + modify it is void, and will automatically terminate your rights + under this License (including any patent licenses granted under + the third paragraph of section 11). + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly + and finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from + you under this License. If your rights have been terminated and + not permanently reinstated, you do not qualify to receive new + licenses for the same material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or + run a copy of the Program. Ancillary propagation of a covered work + occurring solely as a consequence of using peer-to-peer + transmission to receive a copy likewise does not require + acceptance. However, nothing other than this License grants you + permission to propagate or modify any covered work. These actions + infringe copyright if you do not accept this License. Therefore, + by modifying or propagating a covered work, you indicate your + acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically + receives a license from the original licensors, to run, modify and + propagate that work, subject to this License. You are not + responsible for enforcing compliance by third parties with this + License. + + An "entity transaction" is a transaction transferring control of an + organization, or substantially all assets of one, or subdividing an + organization, or merging organizations. If propagation of a + covered work results from an entity transaction, each party to that + transaction who receives a copy of the work also receives whatever + licenses to the work the party's predecessor in interest had or + could give under the previous paragraph, plus a right to + possession of the Corresponding Source of the work from the + predecessor in interest, if the predecessor has it or can get it + with reasonable efforts. + + You may not impose any further restrictions on the exercise of the + rights granted or affirmed under this License. For example, you + may not impose a license fee, royalty, or other charge for + exercise of rights granted under this License, and you may not + initiate litigation (including a cross-claim or counterclaim in a + lawsuit) alleging that any patent claim is infringed by making, + using, selling, offering for sale, or importing the Program or any + portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this + License of the Program or a work on which the Program is based. + The work thus licensed is called the contributor's "contributor + version". + + A contributor's "essential patent claims" are all patent claims + owned or controlled by the contributor, whether already acquired or + hereafter acquired, that would be infringed by some manner, + permitted by this License, of making, using, or selling its + contributor version, but do not include claims that would be + infringed only as a consequence of further modification of the + contributor version. For purposes of this definition, "control" + includes the right to grant patent sublicenses in a manner + consistent with the requirements of this License. + + Each contributor grants you a non-exclusive, worldwide, + royalty-free patent license under the contributor's essential + patent claims, to make, use, sell, offer for sale, import and + otherwise run, modify and propagate the contents of its + contributor version. + + In the following three paragraphs, a "patent license" is any + express agreement or commitment, however denominated, not to + enforce a patent (such as an express permission to practice a + patent or covenant not to sue for patent infringement). To + "grant" such a patent license to a party means to make such an + agreement or commitment not to enforce a patent against the party. + + If you convey a covered work, knowingly relying on a patent + license, and the Corresponding Source of the work is not available + for anyone to copy, free of charge and under the terms of this + License, through a publicly available network server or other + readily accessible means, then you must either (1) cause the + Corresponding Source to be so available, or (2) arrange to deprive + yourself of the benefit of the patent license for this particular + work, or (3) arrange, in a manner consistent with the requirements + of this License, to extend the patent license to downstream + recipients. "Knowingly relying" means you have actual knowledge + that, but for the patent license, your conveying the covered work + in a country, or your recipient's use of the covered work in a + country, would infringe one or more identifiable patents in that + country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or + arrangement, you convey, or propagate by procuring conveyance of, a + covered work, and grant a patent license to some of the parties + receiving the covered work authorizing them to use, propagate, + modify or convey a specific copy of the covered work, then the + patent license you grant is automatically extended to all + recipients of the covered work and works based on it. + + A patent license is "discriminatory" if it does not include within + the scope of its coverage, prohibits the exercise of, or is + conditioned on the non-exercise of one or more of the rights that + are specifically granted under this License. You may not convey a + covered work if you are a party to an arrangement with a third + party that is in the business of distributing software, under + which you make payment to the third party based on the extent of + your activity of conveying the work, and under which the third + party grants, to any of the parties who would receive the covered + work from you, a discriminatory patent license (a) in connection + with copies of the covered work conveyed by you (or copies made + from those copies), or (b) primarily for and in connection with + specific products or compilations that contain the covered work, + unless you entered into that arrangement, or that patent license + was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting + any implied license or other defenses to infringement that may + otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, + agreement or otherwise) that contradict the conditions of this + License, they do not excuse you from the conditions of this + License. If you cannot convey a covered work so as to satisfy + simultaneously your obligations under this License and any other + pertinent obligations, then as a consequence you may not convey it + at all. For example, if you agree to terms that obligate you to + collect a royalty for further conveying from those to whom you + convey the Program, the only way you could satisfy both those + terms and this License would be to refrain entirely from conveying + the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have + permission to link or combine any covered work with a work licensed + under version 3 of the GNU Affero General Public License into a + single combined work, and to convey the resulting work. The terms + of this License will continue to apply to the part which is the + covered work, but the special requirements of the GNU Affero + General Public License, section 13, concerning interaction through + a network will apply to the combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new + versions of the GNU General Public License from time to time. + Such new versions will be similar in spirit to the present + version, but may differ in detail to address new problems or + concerns. + + Each version is given a distinguishing version number. If the + Program specifies that a certain numbered version of the GNU + General Public License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that numbered version or of any later version published by the + Free Software Foundation. If the Program does not specify a + version number of the GNU General Public License, you may choose + any version ever published by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future + versions of the GNU General Public License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Program. + + Later license versions may give you additional or different + permissions. However, no additional obligations are imposed on any + author or copyright holder as a result of your choosing to follow a + later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY + APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE + COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" + WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE + RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. + SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL + NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES + AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU + FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR + CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE + THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA + BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD + PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER + PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF + THE POSSIBILITY OF SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided + above cannot be given local legal effect according to their terms, + reviewing courts shall apply local law that most closely + approximates an absolute waiver of all civil liability in + connection with the Program, unless a warranty or assumption of + liability accompanies a copy of the Program in return for a fee. + + +END OF TERMS AND CONDITIONS +=========================== + +How to Apply These Terms to Your New Programs +============================================= + +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least the +"copyright" line and a pointer to where the full notice is found. + + ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. + Copyright (C) YEAR NAME OF AUTHOR + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or (at + your option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see `http://www.gnu.org/licenses/'. + + Also add information on how to contact you by electronic and paper +mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + PROGRAM Copyright (C) YEAR NAME OF AUTHOR + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + + The hypothetical commands `show w' and `show c' should show the +appropriate parts of the General Public License. Of course, your +program's commands might be different; for a GUI interface, you would +use an "about box". + + You should also get your employer (if you work as a programmer) or +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. For more information on this, and how to apply and follow +the GNU GPL, see `http://www.gnu.org/licenses/'. + + The GNU General Public License does not permit incorporating your +program into proprietary programs. If your program is a subroutine +library, you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use the +GNU Lesser General Public License instead of this License. But first, +please read `http://www.gnu.org/philosophy/why-not-lgpl.html'. + + +File: bison.info, Node: Concepts, Next: Examples, Prev: Copying, Up: Top + +1 The Concepts of Bison +*********************** + +This chapter introduces many of the basic concepts without which the +details of Bison will not make sense. If you do not already know how to +use Bison or Yacc, we suggest you start by reading this chapter +carefully. + +* Menu: + +* Language and Grammar:: Languages and context-free grammars, + as mathematical ideas. +* Grammar in Bison:: How we represent grammars for Bison's sake. +* Semantic Values:: Each token or syntactic grouping can have + a semantic value (the value of an integer, + the name of an identifier, etc.). +* Semantic Actions:: Each rule can have an action containing C code. +* GLR Parsers:: Writing parsers for general context-free languages. +* Locations Overview:: Tracking Locations. +* Bison Parser:: What are Bison's input and output, + how is the output used? +* Stages:: Stages in writing and running Bison grammars. +* Grammar Layout:: Overall structure of a Bison grammar file. + + +File: bison.info, Node: Language and Grammar, Next: Grammar in Bison, Up: Concepts + +1.1 Languages and Context-Free Grammars +======================================= + +In order for Bison to parse a language, it must be described by a +"context-free grammar". This means that you specify one or more +"syntactic groupings" and give rules for constructing them from their +parts. For example, in the C language, one kind of grouping is called +an `expression'. One rule for making an expression might be, "An +expression can be made of a minus sign and another expression". +Another would be, "An expression can be an integer". As you can see, +rules are often recursive, but there must be at least one rule which +leads out of the recursion. + + The most common formal system for presenting such rules for humans +to read is "Backus-Naur Form" or "BNF", which was developed in order to +specify the language Algol 60. Any grammar expressed in BNF is a +context-free grammar. The input to Bison is essentially +machine-readable BNF. + + There are various important subclasses of context-free grammar. +Although it can handle almost all context-free grammars, Bison is +optimized for what are called LALR(1) grammars. In brief, in these +grammars, it must be possible to tell how to parse any portion of an +input string with just a single token of lookahead. Strictly speaking, +that is a description of an LR(1) grammar, and LALR(1) involves +additional restrictions that are hard to explain simply; but it is rare +in actual practice to find an LR(1) grammar that fails to be LALR(1). +*Note Mysterious Reduce/Reduce Conflicts: Mystery Conflicts, for more +information on this. + + Parsers for LALR(1) grammars are "deterministic", meaning roughly +that the next grammar rule to apply at any point in the input is +uniquely determined by the preceding input and a fixed, finite portion +(called a "lookahead") of the remaining input. A context-free grammar +can be "ambiguous", meaning that there are multiple ways to apply the +grammar rules to get the same inputs. Even unambiguous grammars can be +"nondeterministic", meaning that no fixed lookahead always suffices to +determine the next grammar rule to apply. With the proper +declarations, Bison is also able to parse these more general +context-free grammars, using a technique known as GLR parsing (for +Generalized LR). Bison's GLR parsers are able to handle any +context-free grammar for which the number of possible parses of any +given string is finite. + + In the formal grammatical rules for a language, each kind of +syntactic unit or grouping is named by a "symbol". Those which are +built by grouping smaller constructs according to grammatical rules are +called "nonterminal symbols"; those which can't be subdivided are called +"terminal symbols" or "token types". We call a piece of input +corresponding to a single terminal symbol a "token", and a piece +corresponding to a single nonterminal symbol a "grouping". + + We can use the C language as an example of what symbols, terminal and +nonterminal, mean. The tokens of C are identifiers, constants (numeric +and string), and the various keywords, arithmetic operators and +punctuation marks. So the terminal symbols of a grammar for C include +`identifier', `number', `string', plus one symbol for each keyword, +operator or punctuation mark: `if', `return', `const', `static', `int', +`char', `plus-sign', `open-brace', `close-brace', `comma' and many more. +(These tokens can be subdivided into characters, but that is a matter of +lexicography, not grammar.) + + Here is a simple C function subdivided into tokens: + + int /* keyword `int' */ + square (int x) /* identifier, open-paren, keyword `int', + identifier, close-paren */ + { /* open-brace */ + return x * x; /* keyword `return', identifier, asterisk, + identifier, semicolon */ + } /* close-brace */ + + The syntactic groupings of C include the expression, the statement, +the declaration, and the function definition. These are represented in +the grammar of C by nonterminal symbols `expression', `statement', +`declaration' and `function definition'. The full grammar uses dozens +of additional language constructs, each with its own nonterminal +symbol, in order to express the meanings of these four. The example +above is a function definition; it contains one declaration, and one +statement. In the statement, each `x' is an expression and so is `x * +x'. + + Each nonterminal symbol must have grammatical rules showing how it +is made out of simpler constructs. For example, one kind of C +statement is the `return' statement; this would be described with a +grammar rule which reads informally as follows: + + A `statement' can be made of a `return' keyword, an `expression' + and a `semicolon'. + +There would be many other rules for `statement', one for each kind of +statement in C. + + One nonterminal symbol must be distinguished as the special one which +defines a complete utterance in the language. It is called the "start +symbol". In a compiler, this means a complete input program. In the C +language, the nonterminal symbol `sequence of definitions and +declarations' plays this role. + + For example, `1 + 2' is a valid C expression--a valid part of a C +program--but it is not valid as an _entire_ C program. In the +context-free grammar of C, this follows from the fact that `expression' +is not the start symbol. + + The Bison parser reads a sequence of tokens as its input, and groups +the tokens using the grammar rules. If the input is valid, the end +result is that the entire token sequence reduces to a single grouping +whose symbol is the grammar's start symbol. If we use a grammar for C, +the entire input must be a `sequence of definitions and declarations'. +If not, the parser reports a syntax error. + + +File: bison.info, Node: Grammar in Bison, Next: Semantic Values, Prev: Language and Grammar, Up: Concepts + +1.2 From Formal Rules to Bison Input +==================================== + +A formal grammar is a mathematical construct. To define the language +for Bison, you must write a file expressing the grammar in Bison syntax: +a "Bison grammar" file. *Note Bison Grammar Files: Grammar File. + + A nonterminal symbol in the formal grammar is represented in Bison +input as an identifier, like an identifier in C. By convention, it +should be in lower case, such as `expr', `stmt' or `declaration'. + + The Bison representation for a terminal symbol is also called a +"token type". Token types as well can be represented as C-like +identifiers. By convention, these identifiers should be upper case to +distinguish them from nonterminals: for example, `INTEGER', +`IDENTIFIER', `IF' or `RETURN'. A terminal symbol that stands for a +particular keyword in the language should be named after that keyword +converted to upper case. The terminal symbol `error' is reserved for +error recovery. *Note Symbols::. + + A terminal symbol can also be represented as a character literal, +just like a C character constant. You should do this whenever a token +is just a single character (parenthesis, plus-sign, etc.): use that +same character in a literal as the terminal symbol for that token. + + A third way to represent a terminal symbol is with a C string +constant containing several characters. *Note Symbols::, for more +information. + + The grammar rules also have an expression in Bison syntax. For +example, here is the Bison rule for a C `return' statement. The +semicolon in quotes is a literal character token, representing part of +the C syntax for the statement; the naked semicolon, and the colon, are +Bison punctuation used in every rule. + + stmt: RETURN expr ';' + ; + +*Note Syntax of Grammar Rules: Rules. + + +File: bison.info, Node: Semantic Values, Next: Semantic Actions, Prev: Grammar in Bison, Up: Concepts + +1.3 Semantic Values +=================== + +A formal grammar selects tokens only by their classifications: for +example, if a rule mentions the terminal symbol `integer constant', it +means that _any_ integer constant is grammatically valid in that +position. The precise value of the constant is irrelevant to how to +parse the input: if `x+4' is grammatical then `x+1' or `x+3989' is +equally grammatical. + + But the precise value is very important for what the input means +once it is parsed. A compiler is useless if it fails to distinguish +between 4, 1 and 3989 as constants in the program! Therefore, each +token in a Bison grammar has both a token type and a "semantic value". +*Note Defining Language Semantics: Semantics, for details. + + The token type is a terminal symbol defined in the grammar, such as +`INTEGER', `IDENTIFIER' or `',''. It tells everything you need to know +to decide where the token may validly appear and how to group it with +other tokens. The grammar rules know nothing about tokens except their +types. + + The semantic value has all the rest of the information about the +meaning of the token, such as the value of an integer, or the name of an +identifier. (A token such as `','' which is just punctuation doesn't +need to have any semantic value.) + + For example, an input token might be classified as token type +`INTEGER' and have the semantic value 4. Another input token might +have the same token type `INTEGER' but value 3989. When a grammar rule +says that `INTEGER' is allowed, either of these tokens is acceptable +because each is an `INTEGER'. When the parser accepts the token, it +keeps track of the token's semantic value. + + Each grouping can also have a semantic value as well as its +nonterminal symbol. For example, in a calculator, an expression +typically has a semantic value that is a number. In a compiler for a +programming language, an expression typically has a semantic value that +is a tree structure describing the meaning of the expression. + + +File: bison.info, Node: Semantic Actions, Next: GLR Parsers, Prev: Semantic Values, Up: Concepts + +1.4 Semantic Actions +==================== + +In order to be useful, a program must do more than parse input; it must +also produce some output based on the input. In a Bison grammar, a +grammar rule can have an "action" made up of C statements. Each time +the parser recognizes a match for that rule, the action is executed. +*Note Actions::. + + Most of the time, the purpose of an action is to compute the +semantic value of the whole construct from the semantic values of its +parts. For example, suppose we have a rule which says an expression +can be the sum of two expressions. When the parser recognizes such a +sum, each of the subexpressions has a semantic value which describes +how it was built up. The action for this rule should create a similar +sort of value for the newly recognized larger expression. + + For example, here is a rule that says an expression can be the sum of +two subexpressions: + + expr: expr '+' expr { $$ = $1 + $3; } + ; + +The action says how to produce the semantic value of the sum expression +from the values of the two subexpressions. + + +File: bison.info, Node: GLR Parsers, Next: Locations Overview, Prev: Semantic Actions, Up: Concepts + +1.5 Writing GLR Parsers +======================= + +In some grammars, Bison's standard LALR(1) parsing algorithm cannot +decide whether to apply a certain grammar rule at a given point. That +is, it may not be able to decide (on the basis of the input read so +far) which of two possible reductions (applications of a grammar rule) +applies, or whether to apply a reduction or read more of the input and +apply a reduction later in the input. These are known respectively as +"reduce/reduce" conflicts (*note Reduce/Reduce::), and "shift/reduce" +conflicts (*note Shift/Reduce::). + + To use a grammar that is not easily modified to be LALR(1), a more +general parsing algorithm is sometimes necessary. If you include +`%glr-parser' among the Bison declarations in your file (*note Grammar +Outline::), the result is a Generalized LR (GLR) parser. These parsers +handle Bison grammars that contain no unresolved conflicts (i.e., after +applying precedence declarations) identically to LALR(1) parsers. +However, when faced with unresolved shift/reduce and reduce/reduce +conflicts, GLR parsers use the simple expedient of doing both, +effectively cloning the parser to follow both possibilities. Each of +the resulting parsers can again split, so that at any given time, there +can be any number of possible parses being explored. The parsers +proceed in lockstep; that is, all of them consume (shift) a given input +symbol before any of them proceed to the next. Each of the cloned +parsers eventually meets one of two possible fates: either it runs into +a parsing error, in which case it simply vanishes, or it merges with +another parser, because the two of them have reduced the input to an +identical set of symbols. + + During the time that there are multiple parsers, semantic actions are +recorded, but not performed. When a parser disappears, its recorded +semantic actions disappear as well, and are never performed. When a +reduction makes two parsers identical, causing them to merge, Bison +records both sets of semantic actions. Whenever the last two parsers +merge, reverting to the single-parser case, Bison resolves all the +outstanding actions either by precedences given to the grammar rules +involved, or by performing both actions, and then calling a designated +user-defined function on the resulting values to produce an arbitrary +merged result. + +* Menu: + +* Simple GLR Parsers:: Using GLR parsers on unambiguous grammars. +* Merging GLR Parses:: Using GLR parsers to resolve ambiguities. +* GLR Semantic Actions:: Deferred semantic actions have special concerns. +* Compiler Requirements:: GLR parsers require a modern C compiler. + + +File: bison.info, Node: Simple GLR Parsers, Next: Merging GLR Parses, Up: GLR Parsers + +1.5.1 Using GLR on Unambiguous Grammars +--------------------------------------- + +In the simplest cases, you can use the GLR algorithm to parse grammars +that are unambiguous, but fail to be LALR(1). Such grammars typically +require more than one symbol of lookahead, or (in rare cases) fall into +the category of grammars in which the LALR(1) algorithm throws away too +much information (they are in LR(1), but not LALR(1), *Note Mystery +Conflicts::). + + Consider a problem that arises in the declaration of enumerated and +subrange types in the programming language Pascal. Here are some +examples: + + type subrange = lo .. hi; + type enum = (a, b, c); + +The original language standard allows only numeric literals and +constant identifiers for the subrange bounds (`lo' and `hi'), but +Extended Pascal (ISO/IEC 10206) and many other Pascal implementations +allow arbitrary expressions there. This gives rise to the following +situation, containing a superfluous pair of parentheses: + + type subrange = (a) .. b; + +Compare this to the following declaration of an enumerated type with +only one value: + + type enum = (a); + +(These declarations are contrived, but they are syntactically valid, +and more-complicated cases can come up in practical programs.) + + These two declarations look identical until the `..' token. With +normal LALR(1) one-token lookahead it is not possible to decide between +the two forms when the identifier `a' is parsed. It is, however, +desirable for a parser to decide this, since in the latter case `a' +must become a new identifier to represent the enumeration value, while +in the former case `a' must be evaluated with its current meaning, +which may be a constant or even a function call. + + You could parse `(a)' as an "unspecified identifier in parentheses", +to be resolved later, but this typically requires substantial +contortions in both semantic actions and large parts of the grammar, +where the parentheses are nested in the recursive rules for expressions. + + You might think of using the lexer to distinguish between the two +forms by returning different tokens for currently defined and undefined +identifiers. But if these declarations occur in a local scope, and `a' +is defined in an outer scope, then both forms are possible--either +locally redefining `a', or using the value of `a' from the outer scope. +So this approach cannot work. + + A simple solution to this problem is to declare the parser to use +the GLR algorithm. When the GLR parser reaches the critical state, it +merely splits into two branches and pursues both syntax rules +simultaneously. Sooner or later, one of them runs into a parsing +error. If there is a `..' token before the next `;', the rule for +enumerated types fails since it cannot accept `..' anywhere; otherwise, +the subrange type rule fails since it requires a `..' token. So one of +the branches fails silently, and the other one continues normally, +performing all the intermediate actions that were postponed during the +split. + + If the input is syntactically incorrect, both branches fail and the +parser reports a syntax error as usual. + + The effect of all this is that the parser seems to "guess" the +correct branch to take, or in other words, it seems to use more +lookahead than the underlying LALR(1) algorithm actually allows for. +In this example, LALR(2) would suffice, but also some cases that are +not LALR(k) for any k can be handled this way. + + In general, a GLR parser can take quadratic or cubic worst-case time, +and the current Bison parser even takes exponential time and space for +some grammars. In practice, this rarely happens, and for many grammars +it is possible to prove that it cannot happen. The present example +contains only one conflict between two rules, and the type-declaration +context containing the conflict cannot be nested. So the number of +branches that can exist at any time is limited by the constant 2, and +the parsing time is still linear. + + Here is a Bison grammar corresponding to the example above. It +parses a vastly simplified form of Pascal type declarations. + + %token TYPE DOTDOT ID + + %left '+' '-' + %left '*' '/' + + %% + + type_decl : TYPE ID '=' type ';' + ; + + type : '(' id_list ')' + | expr DOTDOT expr + ; + + id_list : ID + | id_list ',' ID + ; + + expr : '(' expr ')' + | expr '+' expr + | expr '-' expr + | expr '*' expr + | expr '/' expr + | ID + ; + + When used as a normal LALR(1) grammar, Bison correctly complains +about one reduce/reduce conflict. In the conflicting situation the +parser chooses one of the alternatives, arbitrarily the one declared +first. Therefore the following correct input is not recognized: + + type t = (a) .. b; + + The parser can be turned into a GLR parser, while also telling Bison +to be silent about the one known reduce/reduce conflict, by adding +these two declarations to the Bison input file (before the first `%%'): + + %glr-parser + %expect-rr 1 + +No change in the grammar itself is required. Now the parser recognizes +all valid declarations, according to the limited syntax above, +transparently. In fact, the user does not even notice when the parser +splits. + + So here we have a case where we can use the benefits of GLR, almost +without disadvantages. Even in simple cases like this, however, there +are at least two potential problems to beware. First, always analyze +the conflicts reported by Bison to make sure that GLR splitting is only +done where it is intended. A GLR parser splitting inadvertently may +cause problems less obvious than an LALR parser statically choosing the +wrong alternative in a conflict. Second, consider interactions with +the lexer (*note Semantic Tokens::) with great care. Since a split +parser consumes tokens without performing any actions during the split, +the lexer cannot obtain information via parser actions. Some cases of +lexer interactions can be eliminated by using GLR to shift the +complications from the lexer to the parser. You must check the +remaining cases for correctness. + + In our example, it would be safe for the lexer to return tokens +based on their current meanings in some symbol table, because no new +symbols are defined in the middle of a type declaration. Though it is +possible for a parser to define the enumeration constants as they are +parsed, before the type declaration is completed, it actually makes no +difference since they cannot be used within the same enumerated type +declaration. + + +File: bison.info, Node: Merging GLR Parses, Next: GLR Semantic Actions, Prev: Simple GLR Parsers, Up: GLR Parsers + +1.5.2 Using GLR to Resolve Ambiguities +-------------------------------------- + +Let's consider an example, vastly simplified from a C++ grammar. + + %{ + #include <stdio.h> + #define YYSTYPE char const * + int yylex (void); + void yyerror (char const *); + %} + + %token TYPENAME ID + + %right '=' + %left '+' + + %glr-parser + + %% + + prog : + | prog stmt { printf ("\n"); } + ; + + stmt : expr ';' %dprec 1 + | decl %dprec 2 + ; + + expr : ID { printf ("%s ", $$); } + | TYPENAME '(' expr ')' + { printf ("%s <cast> ", $1); } + | expr '+' expr { printf ("+ "); } + | expr '=' expr { printf ("= "); } + ; + + decl : TYPENAME declarator ';' + { printf ("%s <declare> ", $1); } + | TYPENAME declarator '=' expr ';' + { printf ("%s <init-declare> ", $1); } + ; + + declarator : ID { printf ("\"%s\" ", $1); } + | '(' declarator ')' + ; + +This models a problematic part of the C++ grammar--the ambiguity between +certain declarations and statements. For example, + + T (x) = y+z; + +parses as either an `expr' or a `stmt' (assuming that `T' is recognized +as a `TYPENAME' and `x' as an `ID'). Bison detects this as a +reduce/reduce conflict between the rules `expr : ID' and `declarator : +ID', which it cannot resolve at the time it encounters `x' in the +example above. Since this is a GLR parser, it therefore splits the +problem into two parses, one for each choice of resolving the +reduce/reduce conflict. Unlike the example from the previous section +(*note Simple GLR Parsers::), however, neither of these parses "dies," +because the grammar as it stands is ambiguous. One of the parsers +eventually reduces `stmt : expr ';'' and the other reduces `stmt : +decl', after which both parsers are in an identical state: they've seen +`prog stmt' and have the same unprocessed input remaining. We say that +these parses have "merged." + + At this point, the GLR parser requires a specification in the +grammar of how to choose between the competing parses. In the example +above, the two `%dprec' declarations specify that Bison is to give +precedence to the parse that interprets the example as a `decl', which +implies that `x' is a declarator. The parser therefore prints + + "x" y z + T <init-declare> + + The `%dprec' declarations only come into play when more than one +parse survives. Consider a different input string for this parser: + + T (x) + y; + +This is another example of using GLR to parse an unambiguous construct, +as shown in the previous section (*note Simple GLR Parsers::). Here, +there is no ambiguity (this cannot be parsed as a declaration). +However, at the time the Bison parser encounters `x', it does not have +enough information to resolve the reduce/reduce conflict (again, +between `x' as an `expr' or a `declarator'). In this case, no +precedence declaration is used. Again, the parser splits into two, one +assuming that `x' is an `expr', and the other assuming `x' is a +`declarator'. The second of these parsers then vanishes when it sees +`+', and the parser prints + + x T <cast> y + + + Suppose that instead of resolving the ambiguity, you wanted to see +all the possibilities. For this purpose, you must merge the semantic +actions of the two possible parsers, rather than choosing one over the +other. To do so, you could change the declaration of `stmt' as follows: + + stmt : expr ';' %merge <stmtMerge> + | decl %merge <stmtMerge> + ; + +and define the `stmtMerge' function as: + + static YYSTYPE + stmtMerge (YYSTYPE x0, YYSTYPE x1) + { + printf ("<OR> "); + return ""; + } + +with an accompanying forward declaration in the C declarations at the +beginning of the file: + + %{ + #define YYSTYPE char const * + static YYSTYPE stmtMerge (YYSTYPE x0, YYSTYPE x1); + %} + +With these declarations, the resulting parser parses the first example +as both an `expr' and a `decl', and prints + + "x" y z + T <init-declare> x T <cast> y z + = <OR> + + Bison requires that all of the productions that participate in any +particular merge have identical `%merge' clauses. Otherwise, the +ambiguity would be unresolvable, and the parser will report an error +during any parse that results in the offending merge. + + +File: bison.info, Node: GLR Semantic Actions, Next: Compiler Requirements, Prev: Merging GLR Parses, Up: GLR Parsers + +1.5.3 GLR Semantic Actions +-------------------------- + +By definition, a deferred semantic action is not performed at the same +time as the associated reduction. This raises caveats for several +Bison features you might use in a semantic action in a GLR parser. + + In any semantic action, you can examine `yychar' to determine the +type of the lookahead token present at the time of the associated +reduction. After checking that `yychar' is not set to `YYEMPTY' or +`YYEOF', you can then examine `yylval' and `yylloc' to determine the +lookahead token's semantic value and location, if any. In a +nondeferred semantic action, you can also modify any of these variables +to influence syntax analysis. *Note Lookahead Tokens: Lookahead. + + In a deferred semantic action, it's too late to influence syntax +analysis. In this case, `yychar', `yylval', and `yylloc' are set to +shallow copies of the values they had at the time of the associated +reduction. For this reason alone, modifying them is dangerous. +Moreover, the result of modifying them is undefined and subject to +change with future versions of Bison. For example, if a semantic +action might be deferred, you should never write it to invoke +`yyclearin' (*note Action Features::) or to attempt to free memory +referenced by `yylval'. + + Another Bison feature requiring special consideration is `YYERROR' +(*note Action Features::), which you can invoke in a semantic action to +initiate error recovery. During deterministic GLR operation, the +effect of `YYERROR' is the same as its effect in an LALR(1) parser. In +a deferred semantic action, its effect is undefined. + + Also, see *Note Default Action for Locations: Location Default +Action, which describes a special usage of `YYLLOC_DEFAULT' in GLR +parsers. + + +File: bison.info, Node: Compiler Requirements, Prev: GLR Semantic Actions, Up: GLR Parsers + +1.5.4 Considerations when Compiling GLR Parsers +----------------------------------------------- + +The GLR parsers require a compiler for ISO C89 or later. In addition, +they use the `inline' keyword, which is not C89, but is C99 and is a +common extension in pre-C99 compilers. It is up to the user of these +parsers to handle portability issues. For instance, if using Autoconf +and the Autoconf macro `AC_C_INLINE', a mere + + %{ + #include <config.h> + %} + +will suffice. Otherwise, we suggest + + %{ + #if __STDC_VERSION__ < 199901 && ! defined __GNUC__ && ! defined inline + #define inline + #endif + %} + + +File: bison.info, Node: Locations Overview, Next: Bison Parser, Prev: GLR Parsers, Up: Concepts + +1.6 Locations +============= + +Many applications, like interpreters or compilers, have to produce +verbose and useful error messages. To achieve this, one must be able +to keep track of the "textual location", or "location", of each +syntactic construct. Bison provides a mechanism for handling these +locations. + + Each token has a semantic value. In a similar fashion, each token +has an associated location, but the type of locations is the same for +all tokens and groupings. Moreover, the output parser is equipped with +a default data structure for storing locations (*note Locations::, for +more details). + + Like semantic values, locations can be reached in actions using a +dedicated set of constructs. In the example above, the location of the +whole grouping is `@$', while the locations of the subexpressions are +`@1' and `@3'. + + When a rule is matched, a default action is used to compute the +semantic value of its left hand side (*note Actions::). In the same +way, another default action is used for locations. However, the action +for locations is general enough for most cases, meaning there is +usually no need to describe for each rule how `@$' should be formed. +When building a new location for a given grouping, the default behavior +of the output parser is to take the beginning of the first symbol, and +the end of the last symbol. + + +File: bison.info, Node: Bison Parser, Next: Stages, Prev: Locations Overview, Up: Concepts + +1.7 Bison Output: the Parser File +================================= + +When you run Bison, you give it a Bison grammar file as input. The +output is a C source file that parses the language described by the +grammar. This file is called a "Bison parser". Keep in mind that the +Bison utility and the Bison parser are two distinct programs: the Bison +utility is a program whose output is the Bison parser that becomes part +of your program. + + The job of the Bison parser is to group tokens into groupings +according to the grammar rules--for example, to build identifiers and +operators into expressions. As it does this, it runs the actions for +the grammar rules it uses. + + The tokens come from a function called the "lexical analyzer" that +you must supply in some fashion (such as by writing it in C). The Bison +parser calls the lexical analyzer each time it wants a new token. It +doesn't know what is "inside" the tokens (though their semantic values +may reflect this). Typically the lexical analyzer makes the tokens by +parsing characters of text, but Bison does not depend on this. *Note +The Lexical Analyzer Function `yylex': Lexical. + + The Bison parser file is C code which defines a function named +`yyparse' which implements that grammar. This function does not make a +complete C program: you must supply some additional functions. One is +the lexical analyzer. Another is an error-reporting function which the +parser calls to report an error. In addition, a complete C program must +start with a function called `main'; you have to provide this, and +arrange for it to call `yyparse' or the parser will never run. *Note +Parser C-Language Interface: Interface. + + Aside from the token type names and the symbols in the actions you +write, all symbols defined in the Bison parser file itself begin with +`yy' or `YY'. This includes interface functions such as the lexical +analyzer function `yylex', the error reporting function `yyerror' and +the parser function `yyparse' itself. This also includes numerous +identifiers used for internal purposes. Therefore, you should avoid +using C identifiers starting with `yy' or `YY' in the Bison grammar +file except for the ones defined in this manual. Also, you should +avoid using the C identifiers `malloc' and `free' for anything other +than their usual meanings. + + In some cases the Bison parser file includes system headers, and in +those cases your code should respect the identifiers reserved by those +headers. On some non-GNU hosts, `<alloca.h>', `<malloc.h>', +`<stddef.h>', and `<stdlib.h>' are included as needed to declare memory +allocators and related types. `<libintl.h>' is included if message +translation is in use (*note Internationalization::). Other system +headers may be included if you define `YYDEBUG' to a nonzero value +(*note Tracing Your Parser: Tracing.). + + +File: bison.info, Node: Stages, Next: Grammar Layout, Prev: Bison Parser, Up: Concepts + +1.8 Stages in Using Bison +========================= + +The actual language-design process using Bison, from grammar +specification to a working compiler or interpreter, has these parts: + + 1. Formally specify the grammar in a form recognized by Bison (*note + Bison Grammar Files: Grammar File.). For each grammatical rule in + the language, describe the action that is to be taken when an + instance of that rule is recognized. The action is described by a + sequence of C statements. + + 2. Write a lexical analyzer to process input and pass tokens to the + parser. The lexical analyzer may be written by hand in C (*note + The Lexical Analyzer Function `yylex': Lexical.). It could also + be produced using Lex, but the use of Lex is not discussed in this + manual. + + 3. Write a controlling function that calls the Bison-produced parser. + + 4. Write error-reporting routines. + + To turn this source code as written into a runnable program, you +must follow these steps: + + 1. Run Bison on the grammar to produce the parser. + + 2. Compile the code output by Bison, as well as any other source + files. + + 3. Link the object files to produce the finished product. + + +File: bison.info, Node: Grammar Layout, Prev: Stages, Up: Concepts + +1.9 The Overall Layout of a Bison Grammar +========================================= + +The input file for the Bison utility is a "Bison grammar file". The +general form of a Bison grammar file is as follows: + + %{ + PROLOGUE + %} + + BISON DECLARATIONS + + %% + GRAMMAR RULES + %% + EPILOGUE + +The `%%', `%{' and `%}' are punctuation that appears in every Bison +grammar file to separate the sections. + + The prologue may define types and variables used in the actions. +You can also use preprocessor commands to define macros used there, and +use `#include' to include header files that do any of these things. +You need to declare the lexical analyzer `yylex' and the error printer +`yyerror' here, along with any other global identifiers used by the +actions in the grammar rules. + + The Bison declarations declare the names of the terminal and +nonterminal symbols, and may also describe operator precedence and the +data types of semantic values of various symbols. + + The grammar rules define how to construct each nonterminal symbol +from its parts. + + The epilogue can contain any code you want to use. Often the +definitions of functions declared in the prologue go here. In a simple +program, all the rest of the program can go here. + + +File: bison.info, Node: Examples, Next: Grammar File, Prev: Concepts, Up: Top + +2 Examples +********** + +Now we show and explain three sample programs written using Bison: a +reverse polish notation calculator, an algebraic (infix) notation +calculator, and a multi-function calculator. All three have been tested +under BSD Unix 4.3; each produces a usable, though limited, interactive +desk-top calculator. + + These examples are simple, but Bison grammars for real programming +languages are written the same way. You can copy these examples into a +source file to try them. + +* Menu: + +* RPN Calc:: Reverse polish notation calculator; + a first example with no operator precedence. +* Infix Calc:: Infix (algebraic) notation calculator. + Operator precedence is introduced. +* Simple Error Recovery:: Continuing after syntax errors. +* Location Tracking Calc:: Demonstrating the use of @N and @$. +* Multi-function Calc:: Calculator with memory and trig functions. + It uses multiple data-types for semantic values. +* Exercises:: Ideas for improving the multi-function calculator. + + +File: bison.info, Node: RPN Calc, Next: Infix Calc, Up: Examples + +2.1 Reverse Polish Notation Calculator +====================================== + +The first example is that of a simple double-precision "reverse polish +notation" calculator (a calculator using postfix operators). This +example provides a good starting point, since operator precedence is +not an issue. The second example will illustrate how operator +precedence is handled. + + The source code for this calculator is named `rpcalc.y'. The `.y' +extension is a convention used for Bison input files. + +* Menu: + +* Rpcalc Declarations:: Prologue (declarations) for rpcalc. +* Rpcalc Rules:: Grammar Rules for rpcalc, with explanation. +* Rpcalc Lexer:: The lexical analyzer. +* Rpcalc Main:: The controlling function. +* Rpcalc Error:: The error reporting function. +* Rpcalc Generate:: Running Bison on the grammar file. +* Rpcalc Compile:: Run the C compiler on the output code. + + +File: bison.info, Node: Rpcalc Declarations, Next: Rpcalc Rules, Up: RPN Calc + +2.1.1 Declarations for `rpcalc' +------------------------------- + +Here are the C and Bison declarations for the reverse polish notation +calculator. As in C, comments are placed between `/*...*/'. + + /* Reverse polish notation calculator. */ + + %{ + #define YYSTYPE double + #include <math.h> + int yylex (void); + void yyerror (char const *); + %} + + %token NUM + + %% /* Grammar rules and actions follow. */ + + The declarations section (*note The prologue: Prologue.) contains two +preprocessor directives and two forward declarations. + + The `#define' directive defines the macro `YYSTYPE', thus specifying +the C data type for semantic values of both tokens and groupings (*note +Data Types of Semantic Values: Value Type.). The Bison parser will use +whatever type `YYSTYPE' is defined as; if you don't define it, `int' is +the default. Because we specify `double', each token and each +expression has an associated value, which is a floating point number. + + The `#include' directive is used to declare the exponentiation +function `pow'. + + The forward declarations for `yylex' and `yyerror' are needed +because the C language requires that functions be declared before they +are used. These functions will be defined in the epilogue, but the +parser calls them so they must be declared in the prologue. + + The second section, Bison declarations, provides information to Bison +about the token types (*note The Bison Declarations Section: Bison +Declarations.). Each terminal symbol that is not a single-character +literal must be declared here. (Single-character literals normally +don't need to be declared.) In this example, all the arithmetic +operators are designated by single-character literals, so the only +terminal symbol that needs to be declared is `NUM', the token type for +numeric constants. + + +File: bison.info, Node: Rpcalc Rules, Next: Rpcalc Lexer, Prev: Rpcalc Declarations, Up: RPN Calc + +2.1.2 Grammar Rules for `rpcalc' +-------------------------------- + +Here are the grammar rules for the reverse polish notation calculator. + + input: /* empty */ + | input line + ; + + line: '\n' + | exp '\n' { printf ("\t%.10g\n", $1); } + ; + + exp: NUM { $$ = $1; } + | exp exp '+' { $$ = $1 + $2; } + | exp exp '-' { $$ = $1 - $2; } + | exp exp '*' { $$ = $1 * $2; } + | exp exp '/' { $$ = $1 / $2; } + /* Exponentiation */ + | exp exp '^' { $$ = pow ($1, $2); } + /* Unary minus */ + | exp 'n' { $$ = -$1; } + ; + %% + + The groupings of the rpcalc "language" defined here are the +expression (given the name `exp'), the line of input (`line'), and the +complete input transcript (`input'). Each of these nonterminal symbols +has several alternate rules, joined by the vertical bar `|' which is +read as "or". The following sections explain what these rules mean. + + The semantics of the language is determined by the actions taken +when a grouping is recognized. The actions are the C code that appears +inside braces. *Note Actions::. + + You must specify these actions in C, but Bison provides the means for +passing semantic values between the rules. In each action, the +pseudo-variable `$$' stands for the semantic value for the grouping +that the rule is going to construct. Assigning a value to `$$' is the +main job of most actions. The semantic values of the components of the +rule are referred to as `$1', `$2', and so on. + +* Menu: + +* Rpcalc Input:: +* Rpcalc Line:: +* Rpcalc Expr:: + + +File: bison.info, Node: Rpcalc Input, Next: Rpcalc Line, Up: Rpcalc Rules + +2.1.2.1 Explanation of `input' +.............................. + +Consider the definition of `input': + + input: /* empty */ + | input line + ; + + This definition reads as follows: "A complete input is either an +empty string, or a complete input followed by an input line". Notice +that "complete input" is defined in terms of itself. This definition +is said to be "left recursive" since `input' appears always as the +leftmost symbol in the sequence. *Note Recursive Rules: Recursion. + + The first alternative is empty because there are no symbols between +the colon and the first `|'; this means that `input' can match an empty +string of input (no tokens). We write the rules this way because it is +legitimate to type `Ctrl-d' right after you start the calculator. It's +conventional to put an empty alternative first and write the comment +`/* empty */' in it. + + The second alternate rule (`input line') handles all nontrivial +input. It means, "After reading any number of lines, read one more +line if possible." The left recursion makes this rule into a loop. +Since the first alternative matches empty input, the loop can be +executed zero or more times. + + The parser function `yyparse' continues to process input until a +grammatical error is seen or the lexical analyzer says there are no more +input tokens; we will arrange for the latter to happen at end-of-input. + + +File: bison.info, Node: Rpcalc Line, Next: Rpcalc Expr, Prev: Rpcalc Input, Up: Rpcalc Rules + +2.1.2.2 Explanation of `line' +............................. + +Now consider the definition of `line': + + line: '\n' + | exp '\n' { printf ("\t%.10g\n", $1); } + ; + + The first alternative is a token which is a newline character; this +means that rpcalc accepts a blank line (and ignores it, since there is +no action). The second alternative is an expression followed by a +newline. This is the alternative that makes rpcalc useful. The +semantic value of the `exp' grouping is the value of `$1' because the +`exp' in question is the first symbol in the alternative. The action +prints this value, which is the result of the computation the user +asked for. + + This action is unusual because it does not assign a value to `$$'. +As a consequence, the semantic value associated with the `line' is +uninitialized (its value will be unpredictable). This would be a bug if +that value were ever used, but we don't use it: once rpcalc has printed +the value of the user's input line, that value is no longer needed. + + +File: bison.info, Node: Rpcalc Expr, Prev: Rpcalc Line, Up: Rpcalc Rules + +2.1.2.3 Explanation of `expr' +............................. + +The `exp' grouping has several rules, one for each kind of expression. +The first rule handles the simplest expressions: those that are just +numbers. The second handles an addition-expression, which looks like +two expressions followed by a plus-sign. The third handles +subtraction, and so on. + + exp: NUM + | exp exp '+' { $$ = $1 + $2; } + | exp exp '-' { $$ = $1 - $2; } + ... + ; + + We have used `|' to join all the rules for `exp', but we could +equally well have written them separately: + + exp: NUM ; + exp: exp exp '+' { $$ = $1 + $2; } ; + exp: exp exp '-' { $$ = $1 - $2; } ; + ... + + Most of the rules have actions that compute the value of the +expression in terms of the value of its parts. For example, in the +rule for addition, `$1' refers to the first component `exp' and `$2' +refers to the second one. The third component, `'+'', has no meaningful +associated semantic value, but if it had one you could refer to it as +`$3'. When `yyparse' recognizes a sum expression using this rule, the +sum of the two subexpressions' values is produced as the value of the +entire expression. *Note Actions::. + + You don't have to give an action for every rule. When a rule has no +action, Bison by default copies the value of `$1' into `$$'. This is +what happens in the first rule (the one that uses `NUM'). + + The formatting shown here is the recommended convention, but Bison +does not require it. You can add or change white space as much as you +wish. For example, this: + + exp : NUM | exp exp '+' {$$ = $1 + $2; } | ... ; + +means the same thing as this: + + exp: NUM + | exp exp '+' { $$ = $1 + $2; } + | ... + ; + +The latter, however, is much more readable. + + +File: bison.info, Node: Rpcalc Lexer, Next: Rpcalc Main, Prev: Rpcalc Rules, Up: RPN Calc + +2.1.3 The `rpcalc' Lexical Analyzer +----------------------------------- + +The lexical analyzer's job is low-level parsing: converting characters +or sequences of characters into tokens. The Bison parser gets its +tokens by calling the lexical analyzer. *Note The Lexical Analyzer +Function `yylex': Lexical. + + Only a simple lexical analyzer is needed for the RPN calculator. +This lexical analyzer skips blanks and tabs, then reads in numbers as +`double' and returns them as `NUM' tokens. Any other character that +isn't part of a number is a separate token. Note that the token-code +for such a single-character token is the character itself. + + The return value of the lexical analyzer function is a numeric code +which represents a token type. The same text used in Bison rules to +stand for this token type is also a C expression for the numeric code +for the type. This works in two ways. If the token type is a +character literal, then its numeric code is that of the character; you +can use the same character literal in the lexical analyzer to express +the number. If the token type is an identifier, that identifier is +defined by Bison as a C macro whose definition is the appropriate +number. In this example, therefore, `NUM' becomes a macro for `yylex' +to use. + + The semantic value of the token (if it has one) is stored into the +global variable `yylval', which is where the Bison parser will look for +it. (The C data type of `yylval' is `YYSTYPE', which was defined at +the beginning of the grammar; *note Declarations for `rpcalc': Rpcalc +Declarations.) + + A token type code of zero is returned if the end-of-input is +encountered. (Bison recognizes any nonpositive value as indicating +end-of-input.) + + Here is the code for the lexical analyzer: + + /* The lexical analyzer returns a double floating point + number on the stack and the token NUM, or the numeric code + of the character read if not a number. It skips all blanks + and tabs, and returns 0 for end-of-input. */ + + #include <ctype.h> + + int + yylex (void) + { + int c; + + /* Skip white space. */ + while ((c = getchar ()) == ' ' || c == '\t') + ; + /* Process numbers. */ + if (c == '.' || isdigit (c)) + { + ungetc (c, stdin); + scanf ("%lf", &yylval); + return NUM; + } + /* Return end-of-input. */ + if (c == EOF) + return 0; + /* Return a single char. */ + return c; + } + + +File: bison.info, Node: Rpcalc Main, Next: Rpcalc Error, Prev: Rpcalc Lexer, Up: RPN Calc + +2.1.4 The Controlling Function +------------------------------ + +In keeping with the spirit of this example, the controlling function is +kept to the bare minimum. The only requirement is that it call +`yyparse' to start the process of parsing. + + int + main (void) + { + return yyparse (); + } + + +File: bison.info, Node: Rpcalc Error, Next: Rpcalc Generate, Prev: Rpcalc Main, Up: RPN Calc + +2.1.5 The Error Reporting Routine +--------------------------------- + +When `yyparse' detects a syntax error, it calls the error reporting +function `yyerror' to print an error message (usually but not always +`"syntax error"'). It is up to the programmer to supply `yyerror' +(*note Parser C-Language Interface: Interface.), so here is the +definition we will use: + + #include <stdio.h> + + /* Called by yyparse on error. */ + void + yyerror (char const *s) + { + fprintf (stderr, "%s\n", s); + } + + After `yyerror' returns, the Bison parser may recover from the error +and continue parsing if the grammar contains a suitable error rule +(*note Error Recovery::). Otherwise, `yyparse' returns nonzero. We +have not written any error rules in this example, so any invalid input +will cause the calculator program to exit. This is not clean behavior +for a real calculator, but it is adequate for the first example. + + +File: bison.info, Node: Rpcalc Generate, Next: Rpcalc Compile, Prev: Rpcalc Error, Up: RPN Calc + +2.1.6 Running Bison to Make the Parser +-------------------------------------- + +Before running Bison to produce a parser, we need to decide how to +arrange all the source code in one or more source files. For such a +simple example, the easiest thing is to put everything in one file. The +definitions of `yylex', `yyerror' and `main' go at the end, in the +epilogue of the file (*note The Overall Layout of a Bison Grammar: +Grammar Layout.). + + For a large project, you would probably have several source files, +and use `make' to arrange to recompile them. + + With all the source in a single file, you use the following command +to convert it into a parser file: + + bison FILE.y + +In this example the file was called `rpcalc.y' (for "Reverse Polish +CALCulator"). Bison produces a file named `FILE.tab.c', removing the +`.y' from the original file name. The file output by Bison contains +the source code for `yyparse'. The additional functions in the input +file (`yylex', `yyerror' and `main') are copied verbatim to the output. + + +File: bison.info, Node: Rpcalc Compile, Prev: Rpcalc Generate, Up: RPN Calc + +2.1.7 Compiling the Parser File +------------------------------- + +Here is how to compile and run the parser file: + + # List files in current directory. + $ ls + rpcalc.tab.c rpcalc.y + + # Compile the Bison parser. + # `-lm' tells compiler to search math library for `pow'. + $ cc -lm -o rpcalc rpcalc.tab.c + + # List files again. + $ ls + rpcalc rpcalc.tab.c rpcalc.y + + The file `rpcalc' now contains the executable code. Here is an +example session using `rpcalc'. + + $ rpcalc + 4 9 + + 13 + 3 7 + 3 4 5 *+- + -13 + 3 7 + 3 4 5 * + - n Note the unary minus, `n' + 13 + 5 6 / 4 n + + -3.166666667 + 3 4 ^ Exponentiation + 81 + ^D End-of-file indicator + $ + + +File: bison.info, Node: Infix Calc, Next: Simple Error Recovery, Prev: RPN Calc, Up: Examples + +2.2 Infix Notation Calculator: `calc' +===================================== + +We now modify rpcalc to handle infix operators instead of postfix. +Infix notation involves the concept of operator precedence and the need +for parentheses nested to arbitrary depth. Here is the Bison code for +`calc.y', an infix desk-top calculator. + + /* Infix notation calculator. */ + + %{ + #define YYSTYPE double + #include <math.h> + #include <stdio.h> + int yylex (void); + void yyerror (char const *); + %} + + /* Bison declarations. */ + %token NUM + %left '-' '+' + %left '*' '/' + %left NEG /* negation--unary minus */ + %right '^' /* exponentiation */ + + %% /* The grammar follows. */ + input: /* empty */ + | input line + ; + + line: '\n' + | exp '\n' { printf ("\t%.10g\n", $1); } + ; + + exp: NUM { $$ = $1; } + | exp '+' exp { $$ = $1 + $3; } + | exp '-' exp { $$ = $1 - $3; } + | exp '*' exp { $$ = $1 * $3; } + | exp '/' exp { $$ = $1 / $3; } + | '-' exp %prec NEG { $$ = -$2; } + | exp '^' exp { $$ = pow ($1, $3); } + | '(' exp ')' { $$ = $2; } + ; + %% + +The functions `yylex', `yyerror' and `main' can be the same as before. + + There are two important new features shown in this code. + + In the second section (Bison declarations), `%left' declares token +types and says they are left-associative operators. The declarations +`%left' and `%right' (right associativity) take the place of `%token' +which is used to declare a token type name without associativity. +(These tokens are single-character literals, which ordinarily don't +need to be declared. We declare them here to specify the +associativity.) + + Operator precedence is determined by the line ordering of the +declarations; the higher the line number of the declaration (lower on +the page or screen), the higher the precedence. Hence, exponentiation +has the highest precedence, unary minus (`NEG') is next, followed by +`*' and `/', and so on. *Note Operator Precedence: Precedence. + + The other important new feature is the `%prec' in the grammar +section for the unary minus operator. The `%prec' simply instructs +Bison that the rule `| '-' exp' has the same precedence as `NEG'--in +this case the next-to-highest. *Note Context-Dependent Precedence: +Contextual Precedence. + + Here is a sample run of `calc.y': + + $ calc + 4 + 4.5 - (34/(8*3+-3)) + 6.880952381 + -56 + 2 + -54 + 3 ^ 2 + 9 + + +File: bison.info, Node: Simple Error Recovery, Next: Location Tracking Calc, Prev: Infix Calc, Up: Examples + +2.3 Simple Error Recovery +========================= + +Up to this point, this manual has not addressed the issue of "error +recovery"--how to continue parsing after the parser detects a syntax +error. All we have handled is error reporting with `yyerror'. Recall +that by default `yyparse' returns after calling `yyerror'. This means +that an erroneous input line causes the calculator program to exit. +Now we show how to rectify this deficiency. + + The Bison language itself includes the reserved word `error', which +may be included in the grammar rules. In the example below it has been +added to one of the alternatives for `line': + + line: '\n' + | exp '\n' { printf ("\t%.10g\n", $1); } + | error '\n' { yyerrok; } + ; + + This addition to the grammar allows for simple error recovery in the +event of a syntax error. If an expression that cannot be evaluated is +read, the error will be recognized by the third rule for `line', and +parsing will continue. (The `yyerror' function is still called upon to +print its message as well.) The action executes the statement +`yyerrok', a macro defined automatically by Bison; its meaning is that +error recovery is complete (*note Error Recovery::). Note the +difference between `yyerrok' and `yyerror'; neither one is a misprint. + + This form of error recovery deals with syntax errors. There are +other kinds of errors; for example, division by zero, which raises an +exception signal that is normally fatal. A real calculator program +must handle this signal and use `longjmp' to return to `main' and +resume parsing input lines; it would also have to discard the rest of +the current line of input. We won't discuss this issue further because +it is not specific to Bison programs. + + +File: bison.info, Node: Location Tracking Calc, Next: Multi-function Calc, Prev: Simple Error Recovery, Up: Examples + +2.4 Location Tracking Calculator: `ltcalc' +========================================== + +This example extends the infix notation calculator with location +tracking. This feature will be used to improve the error messages. For +the sake of clarity, this example is a simple integer calculator, since +most of the work needed to use locations will be done in the lexical +analyzer. + +* Menu: + +* Ltcalc Declarations:: Bison and C declarations for ltcalc. +* Ltcalc Rules:: Grammar rules for ltcalc, with explanations. +* Ltcalc Lexer:: The lexical analyzer. + + +File: bison.info, Node: Ltcalc Declarations, Next: Ltcalc Rules, Up: Location Tracking Calc + +2.4.1 Declarations for `ltcalc' +------------------------------- + +The C and Bison declarations for the location tracking calculator are +the same as the declarations for the infix notation calculator. + + /* Location tracking calculator. */ + + %{ + #define YYSTYPE int + #include <math.h> + int yylex (void); + void yyerror (char const *); + %} + + /* Bison declarations. */ + %token NUM + + %left '-' '+' + %left '*' '/' + %left NEG + %right '^' + + %% /* The grammar follows. */ + +Note there are no declarations specific to locations. Defining a data +type for storing locations is not needed: we will use the type provided +by default (*note Data Types of Locations: Location Type.), which is a +four member structure with the following integer fields: `first_line', +`first_column', `last_line' and `last_column'. By conventions, and in +accordance with the GNU Coding Standards and common practice, the line +and column count both start at 1. + + +File: bison.info, Node: Ltcalc Rules, Next: Ltcalc Lexer, Prev: Ltcalc Declarations, Up: Location Tracking Calc + +2.4.2 Grammar Rules for `ltcalc' +-------------------------------- + +Whether handling locations or not has no effect on the syntax of your +language. Therefore, grammar rules for this example will be very close +to those of the previous example: we will only modify them to benefit +from the new information. + + Here, we will use locations to report divisions by zero, and locate +the wrong expressions or subexpressions. + + input : /* empty */ + | input line + ; + + line : '\n' + | exp '\n' { printf ("%d\n", $1); } + ; + + exp : NUM { $$ = $1; } + | exp '+' exp { $$ = $1 + $3; } + | exp '-' exp { $$ = $1 - $3; } + | exp '*' exp { $$ = $1 * $3; } + | exp '/' exp + { + if ($3) + $$ = $1 / $3; + else + { + $$ = 1; + fprintf (stderr, "%d.%d-%d.%d: division by zero", + @3.first_line, @3.first_column, + @3.last_line, @3.last_column); + } + } + | '-' exp %prec NEG { $$ = -$2; } + | exp '^' exp { $$ = pow ($1, $3); } + | '(' exp ')' { $$ = $2; } + + This code shows how to reach locations inside of semantic actions, by +using the pseudo-variables `@N' for rule components, and the +pseudo-variable `@$' for groupings. + + We don't need to assign a value to `@$': the output parser does it +automatically. By default, before executing the C code of each action, +`@$' is set to range from the beginning of `@1' to the end of `@N', for +a rule with N components. This behavior can be redefined (*note +Default Action for Locations: Location Default Action.), and for very +specific rules, `@$' can be computed by hand. + + +File: bison.info, Node: Ltcalc Lexer, Prev: Ltcalc Rules, Up: Location Tracking Calc + +2.4.3 The `ltcalc' Lexical Analyzer. +------------------------------------ + +Until now, we relied on Bison's defaults to enable location tracking. +The next step is to rewrite the lexical analyzer, and make it able to +feed the parser with the token locations, as it already does for +semantic values. + + To this end, we must take into account every single character of the +input text, to avoid the computed locations of being fuzzy or wrong: + + int + yylex (void) + { + int c; + + /* Skip white space. */ + while ((c = getchar ()) == ' ' || c == '\t') + ++yylloc.last_column; + + /* Step. */ + yylloc.first_line = yylloc.last_line; + yylloc.first_column = yylloc.last_column; + + /* Process numbers. */ + if (isdigit (c)) + { + yylval = c - '0'; + ++yylloc.last_column; + while (isdigit (c = getchar ())) + { + ++yylloc.last_column; + yylval = yylval * 10 + c - '0'; + } + ungetc (c, stdin); + return NUM; + } + + /* Return end-of-input. */ + if (c == EOF) + return 0; + + /* Return a single char, and update location. */ + if (c == '\n') + { + ++yylloc.last_line; + yylloc.last_column = 0; + } + else + ++yylloc.last_column; + return c; + } + + Basically, the lexical analyzer performs the same processing as +before: it skips blanks and tabs, and reads numbers or single-character +tokens. In addition, it updates `yylloc', the global variable (of type +`YYLTYPE') containing the token's location. + + Now, each time this function returns a token, the parser has its +number as well as its semantic value, and its location in the text. +The last needed change is to initialize `yylloc', for example in the +controlling function: + + int + main (void) + { + yylloc.first_line = yylloc.last_line = 1; + yylloc.first_column = yylloc.last_column = 0; + return yyparse (); + } + + Remember that computing locations is not a matter of syntax. Every +character must be associated to a location update, whether it is in +valid input, in comments, in literal strings, and so on. + + +File: bison.info, Node: Multi-function Calc, Next: Exercises, Prev: Location Tracking Calc, Up: Examples + +2.5 Multi-Function Calculator: `mfcalc' +======================================= + +Now that the basics of Bison have been discussed, it is time to move on +to a more advanced problem. The above calculators provided only five +functions, `+', `-', `*', `/' and `^'. It would be nice to have a +calculator that provides other mathematical functions such as `sin', +`cos', etc. + + It is easy to add new operators to the infix calculator as long as +they are only single-character literals. The lexical analyzer `yylex' +passes back all nonnumeric characters as tokens, so new grammar rules +suffice for adding a new operator. But we want something more +flexible: built-in functions whose syntax has this form: + + FUNCTION_NAME (ARGUMENT) + +At the same time, we will add memory to the calculator, by allowing you +to create named variables, store values in them, and use them later. +Here is a sample session with the multi-function calculator: + + $ mfcalc + pi = 3.141592653589 + 3.1415926536 + sin(pi) + 0.0000000000 + alpha = beta1 = 2.3 + 2.3000000000 + alpha + 2.3000000000 + ln(alpha) + 0.8329091229 + exp(ln(beta1)) + 2.3000000000 + $ + + Note that multiple assignment and nested function calls are +permitted. + +* Menu: + +* Mfcalc Declarations:: Bison declarations for multi-function calculator. +* Mfcalc Rules:: Grammar rules for the calculator. +* Mfcalc Symbol Table:: Symbol table management subroutines. + + +File: bison.info, Node: Mfcalc Declarations, Next: Mfcalc Rules, Up: Multi-function Calc + +2.5.1 Declarations for `mfcalc' +------------------------------- + +Here are the C and Bison declarations for the multi-function calculator. + + %{ + #include <math.h> /* For math functions, cos(), sin(), etc. */ + #include "calc.h" /* Contains definition of `symrec'. */ + int yylex (void); + void yyerror (char const *); + %} + %union { + double val; /* For returning numbers. */ + symrec *tptr; /* For returning symbol-table pointers. */ + } + %token <val> NUM /* Simple double precision number. */ + %token <tptr> VAR FNCT /* Variable and Function. */ + %type <val> exp + + %right '=' + %left '-' '+' + %left '*' '/' + %left NEG /* negation--unary minus */ + %right '^' /* exponentiation */ + %% /* The grammar follows. */ + + The above grammar introduces only two new features of the Bison +language. These features allow semantic values to have various data +types (*note More Than One Value Type: Multiple Types.). + + The `%union' declaration specifies the entire list of possible types; +this is instead of defining `YYSTYPE'. The allowable types are now +double-floats (for `exp' and `NUM') and pointers to entries in the +symbol table. *Note The Collection of Value Types: Union Decl. + + Since values can now have various types, it is necessary to +associate a type with each grammar symbol whose semantic value is used. +These symbols are `NUM', `VAR', `FNCT', and `exp'. Their declarations +are augmented with information about their data type (placed between +angle brackets). + + The Bison construct `%type' is used for declaring nonterminal +symbols, just as `%token' is used for declaring token types. We have +not used `%type' before because nonterminal symbols are normally +declared implicitly by the rules that define them. But `exp' must be +declared explicitly so we can specify its value type. *Note +Nonterminal Symbols: Type Decl. + + +File: bison.info, Node: Mfcalc Rules, Next: Mfcalc Symbol Table, Prev: Mfcalc Declarations, Up: Multi-function Calc + +2.5.2 Grammar Rules for `mfcalc' +-------------------------------- + +Here are the grammar rules for the multi-function calculator. Most of +them are copied directly from `calc'; three rules, those which mention +`VAR' or `FNCT', are new. + + input: /* empty */ + | input line + ; + + line: + '\n' + | exp '\n' { printf ("\t%.10g\n", $1); } + | error '\n' { yyerrok; } + ; + + exp: NUM { $$ = $1; } + | VAR { $$ = $1->value.var; } + | VAR '=' exp { $$ = $3; $1->value.var = $3; } + | FNCT '(' exp ')' { $$ = (*($1->value.fnctptr))($3); } + | exp '+' exp { $$ = $1 + $3; } + | exp '-' exp { $$ = $1 - $3; } + | exp '*' exp { $$ = $1 * $3; } + | exp '/' exp { $$ = $1 / $3; } + | '-' exp %prec NEG { $$ = -$2; } + | exp '^' exp { $$ = pow ($1, $3); } + | '(' exp ')' { $$ = $2; } + ; + /* End of grammar. */ + %% + + +File: bison.info, Node: Mfcalc Symbol Table, Prev: Mfcalc Rules, Up: Multi-function Calc + +2.5.3 The `mfcalc' Symbol Table +------------------------------- + +The multi-function calculator requires a symbol table to keep track of +the names and meanings of variables and functions. This doesn't affect +the grammar rules (except for the actions) or the Bison declarations, +but it requires some additional C functions for support. + + The symbol table itself consists of a linked list of records. Its +definition, which is kept in the header `calc.h', is as follows. It +provides for either functions or variables to be placed in the table. + + /* Function type. */ + typedef double (*func_t) (double); + + /* Data type for links in the chain of symbols. */ + struct symrec + { + char *name; /* name of symbol */ + int type; /* type of symbol: either VAR or FNCT */ + union + { + double var; /* value of a VAR */ + func_t fnctptr; /* value of a FNCT */ + } value; + struct symrec *next; /* link field */ + }; + + typedef struct symrec symrec; + + /* The symbol table: a chain of `struct symrec'. */ + extern symrec *sym_table; + + symrec *putsym (char const *, int); + symrec *getsym (char const *); + + The new version of `main' includes a call to `init_table', a +function that initializes the symbol table. Here it is, and +`init_table' as well: + + #include <stdio.h> + + /* Called by yyparse on error. */ + void + yyerror (char const *s) + { + printf ("%s\n", s); + } + + struct init + { + char const *fname; + double (*fnct) (double); + }; + + struct init const arith_fncts[] = + { + "sin", sin, + "cos", cos, + "atan", atan, + "ln", log, + "exp", exp, + "sqrt", sqrt, + 0, 0 + }; + + /* The symbol table: a chain of `struct symrec'. */ + symrec *sym_table; + + /* Put arithmetic functions in table. */ + void + init_table (void) + { + int i; + symrec *ptr; + for (i = 0; arith_fncts[i].fname != 0; i++) + { + ptr = putsym (arith_fncts[i].fname, FNCT); + ptr->value.fnctptr = arith_fncts[i].fnct; + } + } + + int + main (void) + { + init_table (); + return yyparse (); + } + + By simply editing the initialization list and adding the necessary +include files, you can add additional functions to the calculator. + + Two important functions allow look-up and installation of symbols in +the symbol table. The function `putsym' is passed a name and the type +(`VAR' or `FNCT') of the object to be installed. The object is linked +to the front of the list, and a pointer to the object is returned. The +function `getsym' is passed the name of the symbol to look up. If +found, a pointer to that symbol is returned; otherwise zero is returned. + + symrec * + putsym (char const *sym_name, int sym_type) + { + symrec *ptr; + ptr = (symrec *) malloc (sizeof (symrec)); + ptr->name = (char *) malloc (strlen (sym_name) + 1); + strcpy (ptr->name,sym_name); + ptr->type = sym_type; + ptr->value.var = 0; /* Set value to 0 even if fctn. */ + ptr->next = (struct symrec *)sym_table; + sym_table = ptr; + return ptr; + } + + symrec * + getsym (char const *sym_name) + { + symrec *ptr; + for (ptr = sym_table; ptr != (symrec *) 0; + ptr = (symrec *)ptr->next) + if (strcmp (ptr->name,sym_name) == 0) + return ptr; + return 0; + } + + The function `yylex' must now recognize variables, numeric values, +and the single-character arithmetic operators. Strings of alphanumeric +characters with a leading letter are recognized as either variables or +functions depending on what the symbol table says about them. + + The string is passed to `getsym' for look up in the symbol table. If +the name appears in the table, a pointer to its location and its type +(`VAR' or `FNCT') is returned to `yyparse'. If it is not already in +the table, then it is installed as a `VAR' using `putsym'. Again, a +pointer and its type (which must be `VAR') is returned to `yyparse'. + + No change is needed in the handling of numeric values and arithmetic +operators in `yylex'. + + #include <ctype.h> + + int + yylex (void) + { + int c; + + /* Ignore white space, get first nonwhite character. */ + while ((c = getchar ()) == ' ' || c == '\t'); + + if (c == EOF) + return 0; + + /* Char starts a number => parse the number. */ + if (c == '.' || isdigit (c)) + { + ungetc (c, stdin); + scanf ("%lf", &yylval.val); + return NUM; + } + + /* Char starts an identifier => read the name. */ + if (isalpha (c)) + { + symrec *s; + static char *symbuf = 0; + static int length = 0; + int i; + + /* Initially make the buffer long enough + for a 40-character symbol name. */ + if (length == 0) + length = 40, symbuf = (char *)malloc (length + 1); + + i = 0; + do + { + /* If buffer is full, make it bigger. */ + if (i == length) + { + length *= 2; + symbuf = (char *) realloc (symbuf, length + 1); + } + /* Add this character to the buffer. */ + symbuf[i++] = c; + /* Get another character. */ + c = getchar (); + } + while (isalnum (c)); + + ungetc (c, stdin); + symbuf[i] = '\0'; + + s = getsym (symbuf); + if (s == 0) + s = putsym (symbuf, VAR); + yylval.tptr = s; + return s->type; + } + + /* Any other character is a token by itself. */ + return c; + } + + This program is both powerful and flexible. You may easily add new +functions, and it is a simple job to modify this code to install +predefined variables such as `pi' or `e' as well. + + +File: bison.info, Node: Exercises, Prev: Multi-function Calc, Up: Examples + +2.6 Exercises +============= + + 1. Add some new functions from `math.h' to the initialization list. + + 2. Add another array that contains constants and their values. Then + modify `init_table' to add these constants to the symbol table. + It will be easiest to give the constants type `VAR'. + + 3. Make the program report an error if the user refers to an + uninitialized variable in any way except to store a value in it. + + +File: bison.info, Node: Grammar File, Next: Interface, Prev: Examples, Up: Top + +3 Bison Grammar Files +********************* + +Bison takes as input a context-free grammar specification and produces a +C-language function that recognizes correct instances of the grammar. + + The Bison grammar input file conventionally has a name ending in +`.y'. *Note Invoking Bison: Invocation. + +* Menu: + +* Grammar Outline:: Overall layout of the grammar file. +* Symbols:: Terminal and nonterminal symbols. +* Rules:: How to write grammar rules. +* Recursion:: Writing recursive rules. +* Semantics:: Semantic values and actions. +* Locations:: Locations and actions. +* Declarations:: All kinds of Bison declarations are described here. +* Multiple Parsers:: Putting more than one Bison parser in one program. + + +File: bison.info, Node: Grammar Outline, Next: Symbols, Up: Grammar File + +3.1 Outline of a Bison Grammar +============================== + +A Bison grammar file has four main sections, shown here with the +appropriate delimiters: + + %{ + PROLOGUE + %} + + BISON DECLARATIONS + + %% + GRAMMAR RULES + %% + + EPILOGUE + + Comments enclosed in `/* ... */' may appear in any of the sections. +As a GNU extension, `//' introduces a comment that continues until end +of line. + +* Menu: + +* Prologue:: Syntax and usage of the prologue. +* Prologue Alternatives:: Syntax and usage of alternatives to the prologue. +* Bison Declarations:: Syntax and usage of the Bison declarations section. +* Grammar Rules:: Syntax and usage of the grammar rules section. +* Epilogue:: Syntax and usage of the epilogue. + + +File: bison.info, Node: Prologue, Next: Prologue Alternatives, Up: Grammar Outline + +3.1.1 The prologue +------------------ + +The PROLOGUE section contains macro definitions and declarations of +functions and variables that are used in the actions in the grammar +rules. These are copied to the beginning of the parser file so that +they precede the definition of `yyparse'. You can use `#include' to +get the declarations from a header file. If you don't need any C +declarations, you may omit the `%{' and `%}' delimiters that bracket +this section. + + The PROLOGUE section is terminated by the first occurrence of `%}' +that is outside a comment, a string literal, or a character constant. + + You may have more than one PROLOGUE section, intermixed with the +BISON DECLARATIONS. This allows you to have C and Bison declarations +that refer to each other. For example, the `%union' declaration may +use types defined in a header file, and you may wish to prototype +functions that take arguments of type `YYSTYPE'. This can be done with +two PROLOGUE blocks, one before and one after the `%union' declaration. + + %{ + #define _GNU_SOURCE + #include <stdio.h> + #include "ptypes.h" + %} + + %union { + long int n; + tree t; /* `tree' is defined in `ptypes.h'. */ + } + + %{ + static void print_token_value (FILE *, int, YYSTYPE); + #define YYPRINT(F, N, L) print_token_value (F, N, L) + %} + + ... + + When in doubt, it is usually safer to put prologue code before all +Bison declarations, rather than after. For example, any definitions of +feature test macros like `_GNU_SOURCE' or `_POSIX_C_SOURCE' should +appear before all Bison declarations, as feature test macros can affect +the behavior of Bison-generated `#include' directives. + + +File: bison.info, Node: Prologue Alternatives, Next: Bison Declarations, Prev: Prologue, Up: Grammar Outline + +3.1.2 Prologue Alternatives +--------------------------- + +(The prologue alternatives described here are experimental. More user +feedback will help to determine whether they should become permanent +features.) + + The functionality of PROLOGUE sections can often be subtle and +inflexible. As an alternative, Bison provides a %code directive with +an explicit qualifier field, which identifies the purpose of the code +and thus the location(s) where Bison should generate it. For C/C++, +the qualifier can be omitted for the default location, or it can be one +of `requires', `provides', `top'. *Note %code: Decl Summary. + + Look again at the example of the previous section: + + %{ + #define _GNU_SOURCE + #include <stdio.h> + #include "ptypes.h" + %} + + %union { + long int n; + tree t; /* `tree' is defined in `ptypes.h'. */ + } + + %{ + static void print_token_value (FILE *, int, YYSTYPE); + #define YYPRINT(F, N, L) print_token_value (F, N, L) + %} + + ... + +Notice that there are two PROLOGUE sections here, but there's a subtle +distinction between their functionality. For example, if you decide to +override Bison's default definition for `YYLTYPE', in which PROLOGUE +section should you write your new definition? You should write it in +the first since Bison will insert that code into the parser source code +file _before_ the default `YYLTYPE' definition. In which PROLOGUE +section should you prototype an internal function, `trace_token', that +accepts `YYLTYPE' and `yytokentype' as arguments? You should prototype +it in the second since Bison will insert that code _after_ the +`YYLTYPE' and `yytokentype' definitions. + + This distinction in functionality between the two PROLOGUE sections +is established by the appearance of the `%union' between them. This +behavior raises a few questions. First, why should the position of a +`%union' affect definitions related to `YYLTYPE' and `yytokentype'? +Second, what if there is no `%union'? In that case, the second kind of +PROLOGUE section is not available. This behavior is not intuitive. + + To avoid this subtle `%union' dependency, rewrite the example using a +`%code top' and an unqualified `%code'. Let's go ahead and add the new +`YYLTYPE' definition and the `trace_token' prototype at the same time: + + %code top { + #define _GNU_SOURCE + #include <stdio.h> + + /* WARNING: The following code really belongs + * in a `%code requires'; see below. */ + + #include "ptypes.h" + #define YYLTYPE YYLTYPE + typedef struct YYLTYPE + { + int first_line; + int first_column; + int last_line; + int last_column; + char *filename; + } YYLTYPE; + } + + %union { + long int n; + tree t; /* `tree' is defined in `ptypes.h'. */ + } + + %code { + static void print_token_value (FILE *, int, YYSTYPE); + #define YYPRINT(F, N, L) print_token_value (F, N, L) + static void trace_token (enum yytokentype token, YYLTYPE loc); + } + + ... + +In this way, `%code top' and the unqualified `%code' achieve the same +functionality as the two kinds of PROLOGUE sections, but it's always +explicit which kind you intend. Moreover, both kinds are always +available even in the absence of `%union'. + + The `%code top' block above logically contains two parts. The first +two lines before the warning need to appear near the top of the parser +source code file. The first line after the warning is required by +`YYSTYPE' and thus also needs to appear in the parser source code file. +However, if you've instructed Bison to generate a parser header file +(*note %defines: Decl Summary.), you probably want that line to appear +before the `YYSTYPE' definition in that header file as well. The +`YYLTYPE' definition should also appear in the parser header file to +override the default `YYLTYPE' definition there. + + In other words, in the `%code top' block above, all but the first two +lines are dependency code required by the `YYSTYPE' and `YYLTYPE' +definitions. Thus, they belong in one or more `%code requires': + + %code top { + #define _GNU_SOURCE + #include <stdio.h> + } + + %code requires { + #include "ptypes.h" + } + %union { + long int n; + tree t; /* `tree' is defined in `ptypes.h'. */ + } + + %code requires { + #define YYLTYPE YYLTYPE + typedef struct YYLTYPE + { + int first_line; + int first_column; + int last_line; + int last_column; + char *filename; + } YYLTYPE; + } + + %code { + static void print_token_value (FILE *, int, YYSTYPE); + #define YYPRINT(F, N, L) print_token_value (F, N, L) + static void trace_token (enum yytokentype token, YYLTYPE loc); + } + + ... + +Now Bison will insert `#include "ptypes.h"' and the new `YYLTYPE' +definition before the Bison-generated `YYSTYPE' and `YYLTYPE' +definitions in both the parser source code file and the parser header +file. (By the same reasoning, `%code requires' would also be the +appropriate place to write your own definition for `YYSTYPE'.) + + When you are writing dependency code for `YYSTYPE' and `YYLTYPE', you +should prefer `%code requires' over `%code top' regardless of whether +you instruct Bison to generate a parser header file. When you are +writing code that you need Bison to insert only into the parser source +code file and that has no special need to appear at the top of that +file, you should prefer the unqualified `%code' over `%code top'. +These practices will make the purpose of each block of your code +explicit to Bison and to other developers reading your grammar file. +Following these practices, we expect the unqualified `%code' and `%code +requires' to be the most important of the four PROLOGUE alternatives. + + At some point while developing your parser, you might decide to +provide `trace_token' to modules that are external to your parser. +Thus, you might wish for Bison to insert the prototype into both the +parser header file and the parser source code file. Since this +function is not a dependency required by `YYSTYPE' or `YYLTYPE', it +doesn't make sense to move its prototype to a `%code requires'. More +importantly, since it depends upon `YYLTYPE' and `yytokentype', `%code +requires' is not sufficient. Instead, move its prototype from the +unqualified `%code' to a `%code provides': + + %code top { + #define _GNU_SOURCE + #include <stdio.h> + } + + %code requires { + #include "ptypes.h" + } + %union { + long int n; + tree t; /* `tree' is defined in `ptypes.h'. */ + } + + %code requires { + #define YYLTYPE YYLTYPE + typedef struct YYLTYPE + { + int first_line; + int first_column; + int last_line; + int last_column; + char *filename; + } YYLTYPE; + } + + %code provides { + void trace_token (enum yytokentype token, YYLTYPE loc); + } + + %code { + static void print_token_value (FILE *, int, YYSTYPE); + #define YYPRINT(F, N, L) print_token_value (F, N, L) + } + + ... + +Bison will insert the `trace_token' prototype into both the parser +header file and the parser source code file after the definitions for +`yytokentype', `YYLTYPE', and `YYSTYPE'. + + The above examples are careful to write directives in an order that +reflects the layout of the generated parser source code and header +files: `%code top', `%code requires', `%code provides', and then +`%code'. While your grammar files may generally be easier to read if +you also follow this order, Bison does not require it. Instead, Bison +lets you choose an organization that makes sense to you. + + You may declare any of these directives multiple times in the +grammar file. In that case, Bison concatenates the contained code in +declaration order. This is the only way in which the position of one +of these directives within the grammar file affects its functionality. + + The result of the previous two properties is greater flexibility in +how you may organize your grammar file. For example, you may organize +semantic-type-related directives by semantic type: + + %code requires { #include "type1.h" } + %union { type1 field1; } + %destructor { type1_free ($$); } <field1> + %printer { type1_print ($$); } <field1> + + %code requires { #include "type2.h" } + %union { type2 field2; } + %destructor { type2_free ($$); } <field2> + %printer { type2_print ($$); } <field2> + +You could even place each of the above directive groups in the rules +section of the grammar file next to the set of rules that uses the +associated semantic type. (In the rules section, you must terminate +each of those directives with a semicolon.) And you don't have to +worry that some directive (like a `%union') in the definitions section +is going to adversely affect their functionality in some +counter-intuitive manner just because it comes first. Such an +organization is not possible using PROLOGUE sections. + + This section has been concerned with explaining the advantages of +the four PROLOGUE alternatives over the original Yacc PROLOGUE. +However, in most cases when using these directives, you shouldn't need +to think about all the low-level ordering issues discussed here. +Instead, you should simply use these directives to label each block of +your code according to its purpose and let Bison handle the ordering. +`%code' is the most generic label. Move code to `%code requires', +`%code provides', or `%code top' as needed. + + +File: bison.info, Node: Bison Declarations, Next: Grammar Rules, Prev: Prologue Alternatives, Up: Grammar Outline + +3.1.3 The Bison Declarations Section +------------------------------------ + +The BISON DECLARATIONS section contains declarations that define +terminal and nonterminal symbols, specify precedence, and so on. In +some simple grammars you may not need any declarations. *Note Bison +Declarations: Declarations. + + +File: bison.info, Node: Grammar Rules, Next: Epilogue, Prev: Bison Declarations, Up: Grammar Outline + +3.1.4 The Grammar Rules Section +------------------------------- + +The "grammar rules" section contains one or more Bison grammar rules, +and nothing else. *Note Syntax of Grammar Rules: Rules. + + There must always be at least one grammar rule, and the first `%%' +(which precedes the grammar rules) may never be omitted even if it is +the first thing in the file. + + +File: bison.info, Node: Epilogue, Prev: Grammar Rules, Up: Grammar Outline + +3.1.5 The epilogue +------------------ + +The EPILOGUE is copied verbatim to the end of the parser file, just as +the PROLOGUE is copied to the beginning. This is the most convenient +place to put anything that you want to have in the parser file but +which need not come before the definition of `yyparse'. For example, +the definitions of `yylex' and `yyerror' often go here. Because C +requires functions to be declared before being used, you often need to +declare functions like `yylex' and `yyerror' in the Prologue, even if +you define them in the Epilogue. *Note Parser C-Language Interface: +Interface. + + If the last section is empty, you may omit the `%%' that separates it +from the grammar rules. + + The Bison parser itself contains many macros and identifiers whose +names start with `yy' or `YY', so it is a good idea to avoid using any +such names (except those documented in this manual) in the epilogue of +the grammar file. + + +File: bison.info, Node: Symbols, Next: Rules, Prev: Grammar Outline, Up: Grammar File + +3.2 Symbols, Terminal and Nonterminal +===================================== + +"Symbols" in Bison grammars represent the grammatical classifications +of the language. + + A "terminal symbol" (also known as a "token type") represents a +class of syntactically equivalent tokens. You use the symbol in grammar +rules to mean that a token in that class is allowed. The symbol is +represented in the Bison parser by a numeric code, and the `yylex' +function returns a token type code to indicate what kind of token has +been read. You don't need to know what the code value is; you can use +the symbol to stand for it. + + A "nonterminal symbol" stands for a class of syntactically +equivalent groupings. The symbol name is used in writing grammar rules. +By convention, it should be all lower case. + + Symbol names can contain letters, digits (not at the beginning), +underscores and periods. Periods make sense only in nonterminals. + + There are three ways of writing terminal symbols in the grammar: + + * A "named token type" is written with an identifier, like an + identifier in C. By convention, it should be all upper case. Each + such name must be defined with a Bison declaration such as + `%token'. *Note Token Type Names: Token Decl. + + * A "character token type" (or "literal character token") is written + in the grammar using the same syntax used in C for character + constants; for example, `'+'' is a character token type. A + character token type doesn't need to be declared unless you need to + specify its semantic value data type (*note Data Types of Semantic + Values: Value Type.), associativity, or precedence (*note Operator + Precedence: Precedence.). + + By convention, a character token type is used only to represent a + token that consists of that particular character. Thus, the token + type `'+'' is used to represent the character `+' as a token. + Nothing enforces this convention, but if you depart from it, your + program will confuse other readers. + + All the usual escape sequences used in character literals in C can + be used in Bison as well, but you must not use the null character + as a character literal because its numeric code, zero, signifies + end-of-input (*note Calling Convention for `yylex': Calling + Convention.). Also, unlike standard C, trigraphs have no special + meaning in Bison character literals, nor is backslash-newline + allowed. + + * A "literal string token" is written like a C string constant; for + example, `"<="' is a literal string token. A literal string token + doesn't need to be declared unless you need to specify its semantic + value data type (*note Value Type::), associativity, or precedence + (*note Precedence::). + + You can associate the literal string token with a symbolic name as + an alias, using the `%token' declaration (*note Token + Declarations: Token Decl.). If you don't do that, the lexical + analyzer has to retrieve the token number for the literal string + token from the `yytname' table (*note Calling Convention::). + + *Warning*: literal string tokens do not work in Yacc. + + By convention, a literal string token is used only to represent a + token that consists of that particular string. Thus, you should + use the token type `"<="' to represent the string `<=' as a token. + Bison does not enforce this convention, but if you depart from + it, people who read your program will be confused. + + All the escape sequences used in string literals in C can be used + in Bison as well, except that you must not use a null character + within a string literal. Also, unlike Standard C, trigraphs have + no special meaning in Bison string literals, nor is + backslash-newline allowed. A literal string token must contain + two or more characters; for a token containing just one character, + use a character token (see above). + + How you choose to write a terminal symbol has no effect on its +grammatical meaning. That depends only on where it appears in rules and +on when the parser function returns that symbol. + + The value returned by `yylex' is always one of the terminal symbols, +except that a zero or negative value signifies end-of-input. Whichever +way you write the token type in the grammar rules, you write it the +same way in the definition of `yylex'. The numeric code for a +character token type is simply the positive numeric code of the +character, so `yylex' can use the identical value to generate the +requisite code, though you may need to convert it to `unsigned char' to +avoid sign-extension on hosts where `char' is signed. Each named token +type becomes a C macro in the parser file, so `yylex' can use the name +to stand for the code. (This is why periods don't make sense in +terminal symbols.) *Note Calling Convention for `yylex': Calling +Convention. + + If `yylex' is defined in a separate file, you need to arrange for the +token-type macro definitions to be available there. Use the `-d' +option when you run Bison, so that it will write these macro definitions +into a separate header file `NAME.tab.h' which you can include in the +other source files that need it. *Note Invoking Bison: Invocation. + + If you want to write a grammar that is portable to any Standard C +host, you must use only nonnull character tokens taken from the basic +execution character set of Standard C. This set consists of the ten +digits, the 52 lower- and upper-case English letters, and the +characters in the following C-language string: + + "\a\b\t\n\v\f\r !\"#%&'()*+,-./:;<=>?[\\]^_{|}~" + + The `yylex' function and Bison must use a consistent character set +and encoding for character tokens. For example, if you run Bison in an +ASCII environment, but then compile and run the resulting program in an +environment that uses an incompatible character set like EBCDIC, the +resulting program may not work because the tables generated by Bison +will assume ASCII numeric values for character tokens. It is standard +practice for software distributions to contain C source files that were +generated by Bison in an ASCII environment, so installers on platforms +that are incompatible with ASCII must rebuild those files before +compiling them. + + The symbol `error' is a terminal symbol reserved for error recovery +(*note Error Recovery::); you shouldn't use it for any other purpose. +In particular, `yylex' should never return this value. The default +value of the error token is 256, unless you explicitly assigned 256 to +one of your tokens with a `%token' declaration. + + +File: bison.info, Node: Rules, Next: Recursion, Prev: Symbols, Up: Grammar File + +3.3 Syntax of Grammar Rules +=========================== + +A Bison grammar rule has the following general form: + + RESULT: COMPONENTS... + ; + +where RESULT is the nonterminal symbol that this rule describes, and +COMPONENTS are various terminal and nonterminal symbols that are put +together by this rule (*note Symbols::). + + For example, + + exp: exp '+' exp + ; + +says that two groupings of type `exp', with a `+' token in between, can +be combined into a larger grouping of type `exp'. + + White space in rules is significant only to separate symbols. You +can add extra white space as you wish. + + Scattered among the components can be ACTIONS that determine the +semantics of the rule. An action looks like this: + + {C STATEMENTS} + +This is an example of "braced code", that is, C code surrounded by +braces, much like a compound statement in C. Braced code can contain +any sequence of C tokens, so long as its braces are balanced. Bison +does not check the braced code for correctness directly; it merely +copies the code to the output file, where the C compiler can check it. + + Within braced code, the balanced-brace count is not affected by +braces within comments, string literals, or character constants, but it +is affected by the C digraphs `<%' and `%>' that represent braces. At +the top level braced code must be terminated by `}' and not by a +digraph. Bison does not look for trigraphs, so if braced code uses +trigraphs you should ensure that they do not affect the nesting of +braces or the boundaries of comments, string literals, or character +constants. + + Usually there is only one action and it follows the components. +*Note Actions::. + + Multiple rules for the same RESULT can be written separately or can +be joined with the vertical-bar character `|' as follows: + + RESULT: RULE1-COMPONENTS... + | RULE2-COMPONENTS... + ... + ; + +They are still considered distinct rules even when joined in this way. + + If COMPONENTS in a rule is empty, it means that RESULT can match the +empty string. For example, here is how to define a comma-separated +sequence of zero or more `exp' groupings: + + expseq: /* empty */ + | expseq1 + ; + + expseq1: exp + | expseq1 ',' exp + ; + +It is customary to write a comment `/* empty */' in each rule with no +components. + + +File: bison.info, Node: Recursion, Next: Semantics, Prev: Rules, Up: Grammar File + +3.4 Recursive Rules +=================== + +A rule is called "recursive" when its RESULT nonterminal appears also +on its right hand side. Nearly all Bison grammars need to use +recursion, because that is the only way to define a sequence of any +number of a particular thing. Consider this recursive definition of a +comma-separated sequence of one or more expressions: + + expseq1: exp + | expseq1 ',' exp + ; + +Since the recursive use of `expseq1' is the leftmost symbol in the +right hand side, we call this "left recursion". By contrast, here the +same construct is defined using "right recursion": + + expseq1: exp + | exp ',' expseq1 + ; + +Any kind of sequence can be defined using either left recursion or right +recursion, but you should always use left recursion, because it can +parse a sequence of any number of elements with bounded stack space. +Right recursion uses up space on the Bison stack in proportion to the +number of elements in the sequence, because all the elements must be +shifted onto the stack before the rule can be applied even once. *Note +The Bison Parser Algorithm: Algorithm, for further explanation of this. + + "Indirect" or "mutual" recursion occurs when the result of the rule +does not appear directly on its right hand side, but does appear in +rules for other nonterminals which do appear on its right hand side. + + For example: + + expr: primary + | primary '+' primary + ; + + primary: constant + | '(' expr ')' + ; + +defines two mutually-recursive nonterminals, since each refers to the +other. + + +File: bison.info, Node: Semantics, Next: Locations, Prev: Recursion, Up: Grammar File + +3.5 Defining Language Semantics +=============================== + +The grammar rules for a language determine only the syntax. The +semantics are determined by the semantic values associated with various +tokens and groupings, and by the actions taken when various groupings +are recognized. + + For example, the calculator calculates properly because the value +associated with each expression is the proper number; it adds properly +because the action for the grouping `X + Y' is to add the numbers +associated with X and Y. + +* Menu: + +* Value Type:: Specifying one data type for all semantic values. +* Multiple Types:: Specifying several alternative data types. +* Actions:: An action is the semantic definition of a grammar rule. +* Action Types:: Specifying data types for actions to operate on. +* Mid-Rule Actions:: Most actions go at the end of a rule. + This says when, why and how to use the exceptional + action in the middle of a rule. + + +File: bison.info, Node: Value Type, Next: Multiple Types, Up: Semantics + +3.5.1 Data Types of Semantic Values +----------------------------------- + +In a simple program it may be sufficient to use the same data type for +the semantic values of all language constructs. This was true in the +RPN and infix calculator examples (*note Reverse Polish Notation +Calculator: RPN Calc.). + + Bison normally uses the type `int' for semantic values if your +program uses the same data type for all language constructs. To +specify some other type, define `YYSTYPE' as a macro, like this: + + #define YYSTYPE double + +`YYSTYPE''s replacement list should be a type name that does not +contain parentheses or square brackets. This macro definition must go +in the prologue of the grammar file (*note Outline of a Bison Grammar: +Grammar Outline.). + + +File: bison.info, Node: Multiple Types, Next: Actions, Prev: Value Type, Up: Semantics + +3.5.2 More Than One Value Type +------------------------------ + +In most programs, you will need different data types for different kinds +of tokens and groupings. For example, a numeric constant may need type +`int' or `long int', while a string constant needs type `char *', and +an identifier might need a pointer to an entry in the symbol table. + + To use more than one data type for semantic values in one parser, +Bison requires you to do two things: + + * Specify the entire collection of possible data types, either by + using the `%union' Bison declaration (*note The Collection of + Value Types: Union Decl.), or by using a `typedef' or a `#define' + to define `YYSTYPE' to be a union type whose member names are the + type tags. + + * Choose one of those types for each symbol (terminal or + nonterminal) for which semantic values are used. This is done for + tokens with the `%token' Bison declaration (*note Token Type + Names: Token Decl.) and for groupings with the `%type' Bison + declaration (*note Nonterminal Symbols: Type Decl.). + + +File: bison.info, Node: Actions, Next: Action Types, Prev: Multiple Types, Up: Semantics + +3.5.3 Actions +------------- + +An action accompanies a syntactic rule and contains C code to be +executed each time an instance of that rule is recognized. The task of +most actions is to compute a semantic value for the grouping built by +the rule from the semantic values associated with tokens or smaller +groupings. + + An action consists of braced code containing C statements, and can be +placed at any position in the rule; it is executed at that position. +Most rules have just one action at the end of the rule, following all +the components. Actions in the middle of a rule are tricky and used +only for special purposes (*note Actions in Mid-Rule: Mid-Rule +Actions.). + + The C code in an action can refer to the semantic values of the +components matched by the rule with the construct `$N', which stands for +the value of the Nth component. The semantic value for the grouping +being constructed is `$$'. Bison translates both of these constructs +into expressions of the appropriate type when it copies the actions +into the parser file. `$$' is translated to a modifiable lvalue, so it +can be assigned to. + + Here is a typical example: + + exp: ... + | exp '+' exp + { $$ = $1 + $3; } + +This rule constructs an `exp' from two smaller `exp' groupings +connected by a plus-sign token. In the action, `$1' and `$3' refer to +the semantic values of the two component `exp' groupings, which are the +first and third symbols on the right hand side of the rule. The sum is +stored into `$$' so that it becomes the semantic value of the +addition-expression just recognized by the rule. If there were a +useful semantic value associated with the `+' token, it could be +referred to as `$2'. + + Note that the vertical-bar character `|' is really a rule separator, +and actions are attached to a single rule. This is a difference with +tools like Flex, for which `|' stands for either "or", or "the same +action as that of the next rule". In the following example, the action +is triggered only when `b' is found: + + a-or-b: 'a'|'b' { a_or_b_found = 1; }; + + If you don't specify an action for a rule, Bison supplies a default: +`$$ = $1'. Thus, the value of the first symbol in the rule becomes the +value of the whole rule. Of course, the default action is valid only +if the two data types match. There is no meaningful default action for +an empty rule; every empty rule must have an explicit action unless the +rule's value does not matter. + + `$N' with N zero or negative is allowed for reference to tokens and +groupings on the stack _before_ those that match the current rule. +This is a very risky practice, and to use it reliably you must be +certain of the context in which the rule is applied. Here is a case in +which you can use this reliably: + + foo: expr bar '+' expr { ... } + | expr bar '-' expr { ... } + ; + + bar: /* empty */ + { previous_expr = $0; } + ; + + As long as `bar' is used only in the fashion shown here, `$0' always +refers to the `expr' which precedes `bar' in the definition of `foo'. + + It is also possible to access the semantic value of the lookahead +token, if any, from a semantic action. This semantic value is stored +in `yylval'. *Note Special Features for Use in Actions: Action +Features. + + +File: bison.info, Node: Action Types, Next: Mid-Rule Actions, Prev: Actions, Up: Semantics + +3.5.4 Data Types of Values in Actions +------------------------------------- + +If you have chosen a single data type for semantic values, the `$$' and +`$N' constructs always have that data type. + + If you have used `%union' to specify a variety of data types, then +you must declare a choice among these types for each terminal or +nonterminal symbol that can have a semantic value. Then each time you +use `$$' or `$N', its data type is determined by which symbol it refers +to in the rule. In this example, + + exp: ... + | exp '+' exp + { $$ = $1 + $3; } + +`$1' and `$3' refer to instances of `exp', so they all have the data +type declared for the nonterminal symbol `exp'. If `$2' were used, it +would have the data type declared for the terminal symbol `'+'', +whatever that might be. + + Alternatively, you can specify the data type when you refer to the +value, by inserting `<TYPE>' after the `$' at the beginning of the +reference. For example, if you have defined types as shown here: + + %union { + int itype; + double dtype; + } + +then you can write `$<itype>1' to refer to the first subunit of the +rule as an integer, or `$<dtype>1' to refer to it as a double. + + +File: bison.info, Node: Mid-Rule Actions, Prev: Action Types, Up: Semantics + +3.5.5 Actions in Mid-Rule +------------------------- + +Occasionally it is useful to put an action in the middle of a rule. +These actions are written just like usual end-of-rule actions, but they +are executed before the parser even recognizes the following components. + + A mid-rule action may refer to the components preceding it using +`$N', but it may not refer to subsequent components because it is run +before they are parsed. + + The mid-rule action itself counts as one of the components of the +rule. This makes a difference when there is another action later in +the same rule (and usually there is another at the end): you have to +count the actions along with the symbols when working out which number +N to use in `$N'. + + The mid-rule action can also have a semantic value. The action can +set its value with an assignment to `$$', and actions later in the rule +can refer to the value using `$N'. Since there is no symbol to name +the action, there is no way to declare a data type for the value in +advance, so you must use the `$<...>N' construct to specify a data type +each time you refer to this value. + + There is no way to set the value of the entire rule with a mid-rule +action, because assignments to `$$' do not have that effect. The only +way to set the value for the entire rule is with an ordinary action at +the end of the rule. + + Here is an example from a hypothetical compiler, handling a `let' +statement that looks like `let (VARIABLE) STATEMENT' and serves to +create a variable named VARIABLE temporarily for the duration of +STATEMENT. To parse this construct, we must put VARIABLE into the +symbol table while STATEMENT is parsed, then remove it afterward. Here +is how it is done: + + stmt: LET '(' var ')' + { $<context>$ = push_context (); + declare_variable ($3); } + stmt { $$ = $6; + pop_context ($<context>5); } + +As soon as `let (VARIABLE)' has been recognized, the first action is +run. It saves a copy of the current semantic context (the list of +accessible variables) as its semantic value, using alternative +`context' in the data-type union. Then it calls `declare_variable' to +add the new variable to that list. Once the first action is finished, +the embedded statement `stmt' can be parsed. Note that the mid-rule +action is component number 5, so the `stmt' is component number 6. + + After the embedded statement is parsed, its semantic value becomes +the value of the entire `let'-statement. Then the semantic value from +the earlier action is used to restore the prior list of variables. This +removes the temporary `let'-variable from the list so that it won't +appear to exist while the rest of the program is parsed. + + In the above example, if the parser initiates error recovery (*note +Error Recovery::) while parsing the tokens in the embedded statement +`stmt', it might discard the previous semantic context `$<context>5' +without restoring it. Thus, `$<context>5' needs a destructor (*note +Freeing Discarded Symbols: Destructor Decl.). However, Bison currently +provides no means to declare a destructor specific to a particular +mid-rule action's semantic value. + + One solution is to bury the mid-rule action inside a nonterminal +symbol and to declare a destructor for that symbol: + + %type <context> let + %destructor { pop_context ($$); } let + + %% + + stmt: let stmt + { $$ = $2; + pop_context ($1); } + ; + + let: LET '(' var ')' + { $$ = push_context (); + declare_variable ($3); } + ; + +Note that the action is now at the end of its rule. Any mid-rule +action can be converted to an end-of-rule action in this way, and this +is what Bison actually does to implement mid-rule actions. + + Taking action before a rule is completely recognized often leads to +conflicts since the parser must commit to a parse in order to execute +the action. For example, the following two rules, without mid-rule +actions, can coexist in a working parser because the parser can shift +the open-brace token and look at what follows before deciding whether +there is a declaration or not: + + compound: '{' declarations statements '}' + | '{' statements '}' + ; + +But when we add a mid-rule action as follows, the rules become +nonfunctional: + + compound: { prepare_for_local_variables (); } + '{' declarations statements '}' + | '{' statements '}' + ; + +Now the parser is forced to decide whether to run the mid-rule action +when it has read no farther than the open-brace. In other words, it +must commit to using one rule or the other, without sufficient +information to do it correctly. (The open-brace token is what is called +the "lookahead" token at this time, since the parser is still deciding +what to do about it. *Note Lookahead Tokens: Lookahead.) + + You might think that you could correct the problem by putting +identical actions into the two rules, like this: + + compound: { prepare_for_local_variables (); } + '{' declarations statements '}' + | { prepare_for_local_variables (); } + '{' statements '}' + ; + +But this does not help, because Bison does not realize that the two +actions are identical. (Bison never tries to understand the C code in +an action.) + + If the grammar is such that a declaration can be distinguished from a +statement by the first token (which is true in C), then one solution +which does work is to put the action after the open-brace, like this: + + compound: '{' { prepare_for_local_variables (); } + declarations statements '}' + | '{' statements '}' + ; + +Now the first token of the following declaration or statement, which +would in any case tell Bison which rule to use, can still do so. + + Another solution is to bury the action inside a nonterminal symbol +which serves as a subroutine: + + subroutine: /* empty */ + { prepare_for_local_variables (); } + ; + + compound: subroutine + '{' declarations statements '}' + | subroutine + '{' statements '}' + ; + +Now Bison can execute the action in the rule for `subroutine' without +deciding which rule for `compound' it will eventually use. + + +File: bison.info, Node: Locations, Next: Declarations, Prev: Semantics, Up: Grammar File + +3.6 Tracking Locations +====================== + +Though grammar rules and semantic actions are enough to write a fully +functional parser, it can be useful to process some additional +information, especially symbol locations. + + The way locations are handled is defined by providing a data type, +and actions to take when rules are matched. + +* Menu: + +* Location Type:: Specifying a data type for locations. +* Actions and Locations:: Using locations in actions. +* Location Default Action:: Defining a general way to compute locations. + + +File: bison.info, Node: Location Type, Next: Actions and Locations, Up: Locations + +3.6.1 Data Type of Locations +---------------------------- + +Defining a data type for locations is much simpler than for semantic +values, since all tokens and groupings always use the same type. + + You can specify the type of locations by defining a macro called +`YYLTYPE', just as you can specify the semantic value type by defining +a `YYSTYPE' macro (*note Value Type::). When `YYLTYPE' is not defined, +Bison uses a default structure type with four members: + + typedef struct YYLTYPE + { + int first_line; + int first_column; + int last_line; + int last_column; + } YYLTYPE; + + At the beginning of the parsing, Bison initializes all these fields +to 1 for `yylloc'. + + +File: bison.info, Node: Actions and Locations, Next: Location Default Action, Prev: Location Type, Up: Locations + +3.6.2 Actions and Locations +--------------------------- + +Actions are not only useful for defining language semantics, but also +for describing the behavior of the output parser with locations. + + The most obvious way for building locations of syntactic groupings +is very similar to the way semantic values are computed. In a given +rule, several constructs can be used to access the locations of the +elements being matched. The location of the Nth component of the right +hand side is `@N', while the location of the left hand side grouping is +`@$'. + + Here is a basic example using the default data type for locations: + + exp: ... + | exp '/' exp + { + @$.first_column = @1.first_column; + @$.first_line = @1.first_line; + @$.last_column = @3.last_column; + @$.last_line = @3.last_line; + if ($3) + $$ = $1 / $3; + else + { + $$ = 1; + fprintf (stderr, + "Division by zero, l%d,c%d-l%d,c%d", + @3.first_line, @3.first_column, + @3.last_line, @3.last_column); + } + } + + As for semantic values, there is a default action for locations that +is run each time a rule is matched. It sets the beginning of `@$' to +the beginning of the first symbol, and the end of `@$' to the end of the +last symbol. + + With this default action, the location tracking can be fully +automatic. The example above simply rewrites this way: + + exp: ... + | exp '/' exp + { + if ($3) + $$ = $1 / $3; + else + { + $$ = 1; + fprintf (stderr, + "Division by zero, l%d,c%d-l%d,c%d", + @3.first_line, @3.first_column, + @3.last_line, @3.last_column); + } + } + + It is also possible to access the location of the lookahead token, +if any, from a semantic action. This location is stored in `yylloc'. +*Note Special Features for Use in Actions: Action Features. + + +File: bison.info, Node: Location Default Action, Prev: Actions and Locations, Up: Locations + +3.6.3 Default Action for Locations +---------------------------------- + +Actually, actions are not the best place to compute locations. Since +locations are much more general than semantic values, there is room in +the output parser to redefine the default action to take for each rule. +The `YYLLOC_DEFAULT' macro is invoked each time a rule is matched, +before the associated action is run. It is also invoked while +processing a syntax error, to compute the error's location. Before +reporting an unresolvable syntactic ambiguity, a GLR parser invokes +`YYLLOC_DEFAULT' recursively to compute the location of that ambiguity. + + Most of the time, this macro is general enough to suppress location +dedicated code from semantic actions. + + The `YYLLOC_DEFAULT' macro takes three parameters. The first one is +the location of the grouping (the result of the computation). When a +rule is matched, the second parameter identifies locations of all right +hand side elements of the rule being matched, and the third parameter +is the size of the rule's right hand side. When a GLR parser reports +an ambiguity, which of multiple candidate right hand sides it passes to +`YYLLOC_DEFAULT' is undefined. When processing a syntax error, the +second parameter identifies locations of the symbols that were +discarded during error processing, and the third parameter is the +number of discarded symbols. + + By default, `YYLLOC_DEFAULT' is defined this way: + + # define YYLLOC_DEFAULT(Current, Rhs, N) \ + do \ + if (N) \ + { \ + (Current).first_line = YYRHSLOC(Rhs, 1).first_line; \ + (Current).first_column = YYRHSLOC(Rhs, 1).first_column; \ + (Current).last_line = YYRHSLOC(Rhs, N).last_line; \ + (Current).last_column = YYRHSLOC(Rhs, N).last_column; \ + } \ + else \ + { \ + (Current).first_line = (Current).last_line = \ + YYRHSLOC(Rhs, 0).last_line; \ + (Current).first_column = (Current).last_column = \ + YYRHSLOC(Rhs, 0).last_column; \ + } \ + while (0) + + where `YYRHSLOC (rhs, k)' is the location of the Kth symbol in RHS +when K is positive, and the location of the symbol just before the +reduction when K and N are both zero. + + When defining `YYLLOC_DEFAULT', you should consider that: + + * All arguments are free of side-effects. However, only the first + one (the result) should be modified by `YYLLOC_DEFAULT'. + + * For consistency with semantic actions, valid indexes within the + right hand side range from 1 to N. When N is zero, only 0 is a + valid index, and it refers to the symbol just before the reduction. + During error processing N is always positive. + + * Your macro should parenthesize its arguments, if need be, since the + actual arguments may not be surrounded by parentheses. Also, your + macro should expand to something that can be used as a single + statement when it is followed by a semicolon. + + +File: bison.info, Node: Declarations, Next: Multiple Parsers, Prev: Locations, Up: Grammar File + +3.7 Bison Declarations +====================== + +The "Bison declarations" section of a Bison grammar defines the symbols +used in formulating the grammar and the data types of semantic values. +*Note Symbols::. + + All token type names (but not single-character literal tokens such as +`'+'' and `'*'') must be declared. Nonterminal symbols must be +declared if you need to specify which data type to use for the semantic +value (*note More Than One Value Type: Multiple Types.). + + The first rule in the file also specifies the start symbol, by +default. If you want some other symbol to be the start symbol, you +must declare it explicitly (*note Languages and Context-Free Grammars: +Language and Grammar.). + +* Menu: + +* Require Decl:: Requiring a Bison version. +* Token Decl:: Declaring terminal symbols. +* Precedence Decl:: Declaring terminals with precedence and associativity. +* Union Decl:: Declaring the set of all semantic value types. +* Type Decl:: Declaring the choice of type for a nonterminal symbol. +* Initial Action Decl:: Code run before parsing starts. +* Destructor Decl:: Declaring how symbols are freed. +* Expect Decl:: Suppressing warnings about parsing conflicts. +* Start Decl:: Specifying the start symbol. +* Pure Decl:: Requesting a reentrant parser. +* Push Decl:: Requesting a push parser. +* Decl Summary:: Table of all Bison declarations. + + +File: bison.info, Node: Require Decl, Next: Token Decl, Up: Declarations + +3.7.1 Require a Version of Bison +-------------------------------- + +You may require the minimum version of Bison to process the grammar. If +the requirement is not met, `bison' exits with an error (exit status +63). + + %require "VERSION" + + +File: bison.info, Node: Token Decl, Next: Precedence Decl, Prev: Require Decl, Up: Declarations + +3.7.2 Token Type Names +---------------------- + +The basic way to declare a token type name (terminal symbol) is as +follows: + + %token NAME + + Bison will convert this into a `#define' directive in the parser, so +that the function `yylex' (if it is in this file) can use the name NAME +to stand for this token type's code. + + Alternatively, you can use `%left', `%right', or `%nonassoc' instead +of `%token', if you wish to specify associativity and precedence. +*Note Operator Precedence: Precedence Decl. + + You can explicitly specify the numeric code for a token type by +appending a nonnegative decimal or hexadecimal integer value in the +field immediately following the token name: + + %token NUM 300 + %token XNUM 0x12d // a GNU extension + +It is generally best, however, to let Bison choose the numeric codes for +all token types. Bison will automatically select codes that don't +conflict with each other or with normal characters. + + In the event that the stack type is a union, you must augment the +`%token' or other token declaration to include the data type +alternative delimited by angle-brackets (*note More Than One Value +Type: Multiple Types.). + + For example: + + %union { /* define stack type */ + double val; + symrec *tptr; + } + %token <val> NUM /* define token NUM and its type */ + + You can associate a literal string token with a token type name by +writing the literal string at the end of a `%token' declaration which +declares the name. For example: + + %token arrow "=>" + +For example, a grammar for the C language might specify these names with +equivalent literal string tokens: + + %token <operator> OR "||" + %token <operator> LE 134 "<=" + %left OR "<=" + +Once you equate the literal string and the token name, you can use them +interchangeably in further declarations or the grammar rules. The +`yylex' function can use the token name or the literal string to obtain +the token type code number (*note Calling Convention::). Syntax error +messages passed to `yyerror' from the parser will reference the literal +string instead of the token name. + + The token numbered as 0 corresponds to end of file; the following +line allows for nicer error messages referring to "end of file" instead +of "$end": + + %token END 0 "end of file" + + +File: bison.info, Node: Precedence Decl, Next: Union Decl, Prev: Token Decl, Up: Declarations + +3.7.3 Operator Precedence +------------------------- + +Use the `%left', `%right' or `%nonassoc' declaration to declare a token +and specify its precedence and associativity, all at once. These are +called "precedence declarations". *Note Operator Precedence: +Precedence, for general information on operator precedence. + + The syntax of a precedence declaration is nearly the same as that of +`%token': either + + %left SYMBOLS... + +or + + %left <TYPE> SYMBOLS... + + And indeed any of these declarations serves the purposes of `%token'. +But in addition, they specify the associativity and relative precedence +for all the SYMBOLS: + + * The associativity of an operator OP determines how repeated uses + of the operator nest: whether `X OP Y OP Z' is parsed by grouping + X with Y first or by grouping Y with Z first. `%left' specifies + left-associativity (grouping X with Y first) and `%right' + specifies right-associativity (grouping Y with Z first). + `%nonassoc' specifies no associativity, which means that `X OP Y + OP Z' is considered a syntax error. + + * The precedence of an operator determines how it nests with other + operators. All the tokens declared in a single precedence + declaration have equal precedence and nest together according to + their associativity. When two tokens declared in different + precedence declarations associate, the one declared later has the + higher precedence and is grouped first. + + For backward compatibility, there is a confusing difference between +the argument lists of `%token' and precedence declarations. Only a +`%token' can associate a literal string with a token type name. A +precedence declaration always interprets a literal string as a +reference to a separate token. For example: + + %left OR "<=" // Does not declare an alias. + %left OR 134 "<=" 135 // Declares 134 for OR and 135 for "<=". + + +File: bison.info, Node: Union Decl, Next: Type Decl, Prev: Precedence Decl, Up: Declarations + +3.7.4 The Collection of Value Types +----------------------------------- + +The `%union' declaration specifies the entire collection of possible +data types for semantic values. The keyword `%union' is followed by +braced code containing the same thing that goes inside a `union' in C. + + For example: + + %union { + double val; + symrec *tptr; + } + +This says that the two alternative types are `double' and `symrec *'. +They are given names `val' and `tptr'; these names are used in the +`%token' and `%type' declarations to pick one of the types for a +terminal or nonterminal symbol (*note Nonterminal Symbols: Type Decl.). + + As an extension to POSIX, a tag is allowed after the `union'. For +example: + + %union value { + double val; + symrec *tptr; + } + +specifies the union tag `value', so the corresponding C type is `union +value'. If you do not specify a tag, it defaults to `YYSTYPE'. + + As another extension to POSIX, you may specify multiple `%union' +declarations; their contents are concatenated. However, only the first +`%union' declaration can specify a tag. + + Note that, unlike making a `union' declaration in C, you need not +write a semicolon after the closing brace. + + Instead of `%union', you can define and use your own union type +`YYSTYPE' if your grammar contains at least one `<TYPE>' tag. For +example, you can put the following into a header file `parser.h': + + union YYSTYPE { + double val; + symrec *tptr; + }; + typedef union YYSTYPE YYSTYPE; + +and then your grammar can use the following instead of `%union': + + %{ + #include "parser.h" + %} + %type <val> expr + %token <tptr> ID + + +File: bison.info, Node: Type Decl, Next: Initial Action Decl, Prev: Union Decl, Up: Declarations + +3.7.5 Nonterminal Symbols +------------------------- + +When you use `%union' to specify multiple value types, you must declare +the value type of each nonterminal symbol for which values are used. +This is done with a `%type' declaration, like this: + + %type <TYPE> NONTERMINAL... + +Here NONTERMINAL is the name of a nonterminal symbol, and TYPE is the +name given in the `%union' to the alternative that you want (*note The +Collection of Value Types: Union Decl.). You can give any number of +nonterminal symbols in the same `%type' declaration, if they have the +same value type. Use spaces to separate the symbol names. + + You can also declare the value type of a terminal symbol. To do +this, use the same `<TYPE>' construction in a declaration for the +terminal symbol. All kinds of token declarations allow `<TYPE>'. + + +File: bison.info, Node: Initial Action Decl, Next: Destructor Decl, Prev: Type Decl, Up: Declarations + +3.7.6 Performing Actions before Parsing +--------------------------------------- + +Sometimes your parser needs to perform some initializations before +parsing. The `%initial-action' directive allows for such arbitrary +code. + + -- Directive: %initial-action { CODE } + Declare that the braced CODE must be invoked before parsing each + time `yyparse' is called. The CODE may use `$$' and `@$' -- + initial value and location of the lookahead -- and the + `%parse-param'. + + For instance, if your locations use a file name, you may use + + %parse-param { char const *file_name }; + %initial-action + { + @$.initialize (file_name); + }; + + +File: bison.info, Node: Destructor Decl, Next: Expect Decl, Prev: Initial Action Decl, Up: Declarations + +3.7.7 Freeing Discarded Symbols +------------------------------- + +During error recovery (*note Error Recovery::), symbols already pushed +on the stack and tokens coming from the rest of the file are discarded +until the parser falls on its feet. If the parser runs out of memory, +or if it returns via `YYABORT' or `YYACCEPT', all the symbols on the +stack must be discarded. Even if the parser succeeds, it must discard +the start symbol. + + When discarded symbols convey heap based information, this memory is +lost. While this behavior can be tolerable for batch parsers, such as +in traditional compilers, it is unacceptable for programs like shells or +protocol implementations that may parse and execute indefinitely. + + The `%destructor' directive defines code that is called when a +symbol is automatically discarded. + + -- Directive: %destructor { CODE } SYMBOLS + Invoke the braced CODE whenever the parser discards one of the + SYMBOLS. Within CODE, `$$' designates the semantic value + associated with the discarded symbol, and `@$' designates its + location. The additional parser parameters are also available + (*note The Parser Function `yyparse': Parser Function.). + + When a symbol is listed among SYMBOLS, its `%destructor' is called + a per-symbol `%destructor'. You may also define a per-type + `%destructor' by listing a semantic type tag among SYMBOLS. In + that case, the parser will invoke this CODE whenever it discards + any grammar symbol that has that semantic type tag unless that + symbol has its own per-symbol `%destructor'. + + Finally, you can define two different kinds of default + `%destructor's. (These default forms are experimental. More user + feedback will help to determine whether they should become + permanent features.) You can place each of `<*>' and `<>' in the + SYMBOLS list of exactly one `%destructor' declaration in your + grammar file. The parser will invoke the CODE associated with one + of these whenever it discards any user-defined grammar symbol that + has no per-symbol and no per-type `%destructor'. The parser uses + the CODE for `<*>' in the case of such a grammar symbol for which + you have formally declared a semantic type tag (`%type' counts as + such a declaration, but `$<tag>$' does not). The parser uses the + CODE for `<>' in the case of such a grammar symbol that has no + declared semantic type tag. + +For example: + + %union { char *string; } + %token <string> STRING1 + %token <string> STRING2 + %type <string> string1 + %type <string> string2 + %union { char character; } + %token <character> CHR + %type <character> chr + %token TAGLESS + + %destructor { } <character> + %destructor { free ($$); } <*> + %destructor { free ($$); printf ("%d", @$.first_line); } STRING1 string1 + %destructor { printf ("Discarding tagless symbol.\n"); } <> + +guarantees that, when the parser discards any user-defined symbol that +has a semantic type tag other than `<character>', it passes its +semantic value to `free' by default. However, when the parser discards +a `STRING1' or a `string1', it also prints its line number to `stdout'. +It performs only the second `%destructor' in this case, so it invokes +`free' only once. Finally, the parser merely prints a message whenever +it discards any symbol, such as `TAGLESS', that has no semantic type +tag. + + A Bison-generated parser invokes the default `%destructor's only for +user-defined as opposed to Bison-defined symbols. For example, the +parser will not invoke either kind of default `%destructor' for the +special Bison-defined symbols `$accept', `$undefined', or `$end' (*note +Bison Symbols: Table of Symbols.), none of which you can reference in +your grammar. It also will not invoke either for the `error' token +(*note error: Table of Symbols.), which is always defined by Bison +regardless of whether you reference it in your grammar. However, it +may invoke one of them for the end token (token 0) if you redefine it +from `$end' to, for example, `END': + + %token END 0 + + Finally, Bison will never invoke a `%destructor' for an unreferenced +mid-rule semantic value (*note Actions in Mid-Rule: Mid-Rule Actions.). +That is, Bison does not consider a mid-rule to have a semantic value if +you do not reference `$$' in the mid-rule's action or `$N' (where N is +the RHS symbol position of the mid-rule) in any later action in that +rule. However, if you do reference either, the Bison-generated parser +will invoke the `<>' `%destructor' whenever it discards the mid-rule +symbol. + + + "Discarded symbols" are the following: + + * stacked symbols popped during the first phase of error recovery, + + * incoming terminals during the second phase of error recovery, + + * the current lookahead and the entire stack (except the current + right-hand side symbols) when the parser returns immediately, and + + * the start symbol, when the parser succeeds. + + The parser can "return immediately" because of an explicit call to +`YYABORT' or `YYACCEPT', or failed error recovery, or memory exhaustion. + + Right-hand side symbols of a rule that explicitly triggers a syntax +error via `YYERROR' are not discarded automatically. As a rule of +thumb, destructors are invoked only when user actions cannot manage the +memory. + + +File: bison.info, Node: Expect Decl, Next: Start Decl, Prev: Destructor Decl, Up: Declarations + +3.7.8 Suppressing Conflict Warnings +----------------------------------- + +Bison normally warns if there are any conflicts in the grammar (*note +Shift/Reduce Conflicts: Shift/Reduce.), but most real grammars have +harmless shift/reduce conflicts which are resolved in a predictable way +and would be difficult to eliminate. It is desirable to suppress the +warning about these conflicts unless the number of conflicts changes. +You can do this with the `%expect' declaration. + + The declaration looks like this: + + %expect N + + Here N is a decimal integer. The declaration says there should be N +shift/reduce conflicts and no reduce/reduce conflicts. Bison reports +an error if the number of shift/reduce conflicts differs from N, or if +there are any reduce/reduce conflicts. + + For normal LALR(1) parsers, reduce/reduce conflicts are more +serious, and should be eliminated entirely. Bison will always report +reduce/reduce conflicts for these parsers. With GLR parsers, however, +both kinds of conflicts are routine; otherwise, there would be no need +to use GLR parsing. Therefore, it is also possible to specify an +expected number of reduce/reduce conflicts in GLR parsers, using the +declaration: + + %expect-rr N + + In general, using `%expect' involves these steps: + + * Compile your grammar without `%expect'. Use the `-v' option to + get a verbose list of where the conflicts occur. Bison will also + print the number of conflicts. + + * Check each of the conflicts to make sure that Bison's default + resolution is what you really want. If not, rewrite the grammar + and go back to the beginning. + + * Add an `%expect' declaration, copying the number N from the number + which Bison printed. With GLR parsers, add an `%expect-rr' + declaration as well. + + Now Bison will warn you if you introduce an unexpected conflict, but +will keep silent otherwise. + + +File: bison.info, Node: Start Decl, Next: Pure Decl, Prev: Expect Decl, Up: Declarations + +3.7.9 The Start-Symbol +---------------------- + +Bison assumes by default that the start symbol for the grammar is the +first nonterminal specified in the grammar specification section. The +programmer may override this restriction with the `%start' declaration +as follows: + + %start SYMBOL + + +File: bison.info, Node: Pure Decl, Next: Push Decl, Prev: Start Decl, Up: Declarations + +3.7.10 A Pure (Reentrant) Parser +-------------------------------- + +A "reentrant" program is one which does not alter in the course of +execution; in other words, it consists entirely of "pure" (read-only) +code. Reentrancy is important whenever asynchronous execution is +possible; for example, a nonreentrant program may not be safe to call +from a signal handler. In systems with multiple threads of control, a +nonreentrant program must be called only within interlocks. + + Normally, Bison generates a parser which is not reentrant. This is +suitable for most uses, and it permits compatibility with Yacc. (The +standard Yacc interfaces are inherently nonreentrant, because they use +statically allocated variables for communication with `yylex', +including `yylval' and `yylloc'.) + + Alternatively, you can generate a pure, reentrant parser. The Bison +declaration `%define api.pure' says that you want the parser to be +reentrant. It looks like this: + + %define api.pure + + The result is that the communication variables `yylval' and `yylloc' +become local variables in `yyparse', and a different calling convention +is used for the lexical analyzer function `yylex'. *Note Calling +Conventions for Pure Parsers: Pure Calling, for the details of this. +The variable `yynerrs' becomes local in `yyparse' in pull mode but it +becomes a member of yypstate in push mode. (*note The Error Reporting +Function `yyerror': Error Reporting.). The convention for calling +`yyparse' itself is unchanged. + + Whether the parser is pure has nothing to do with the grammar rules. +You can generate either a pure parser or a nonreentrant parser from any +valid grammar. + + +File: bison.info, Node: Push Decl, Next: Decl Summary, Prev: Pure Decl, Up: Declarations + +3.7.11 A Push Parser +-------------------- + +(The current push parsing interface is experimental and may evolve. +More user feedback will help to stabilize it.) + + A pull parser is called once and it takes control until all its input +is completely parsed. A push parser, on the other hand, is called each +time a new token is made available. + + A push parser is typically useful when the parser is part of a main +event loop in the client's application. This is typically a +requirement of a GUI, when the main event loop needs to be triggered +within a certain time period. + + Normally, Bison generates a pull parser. The following Bison +declaration says that you want the parser to be a push parser (*note +%define api.push_pull: Decl Summary.): + + %define api.push_pull "push" + + In almost all cases, you want to ensure that your push parser is also +a pure parser (*note A Pure (Reentrant) Parser: Pure Decl.). The only +time you should create an impure push parser is to have backwards +compatibility with the impure Yacc pull mode interface. Unless you know +what you are doing, your declarations should look like this: + + %define api.pure + %define api.push_pull "push" + + There is a major notable functional difference between the pure push +parser and the impure push parser. It is acceptable for a pure push +parser to have many parser instances, of the same type of parser, in +memory at the same time. An impure push parser should only use one +parser at a time. + + When a push parser is selected, Bison will generate some new symbols +in the generated parser. `yypstate' is a structure that the generated +parser uses to store the parser's state. `yypstate_new' is the +function that will create a new parser instance. `yypstate_delete' +will free the resources associated with the corresponding parser +instance. Finally, `yypush_parse' is the function that should be +called whenever a token is available to provide the parser. A trivial +example of using a pure push parser would look like this: + + int status; + yypstate *ps = yypstate_new (); + do { + status = yypush_parse (ps, yylex (), NULL); + } while (status == YYPUSH_MORE); + yypstate_delete (ps); + + If the user decided to use an impure push parser, a few things about +the generated parser will change. The `yychar' variable becomes a +global variable instead of a variable in the `yypush_parse' function. +For this reason, the signature of the `yypush_parse' function is +changed to remove the token as a parameter. A nonreentrant push parser +example would thus look like this: + + extern int yychar; + int status; + yypstate *ps = yypstate_new (); + do { + yychar = yylex (); + status = yypush_parse (ps); + } while (status == YYPUSH_MORE); + yypstate_delete (ps); + + That's it. Notice the next token is put into the global variable +`yychar' for use by the next invocation of the `yypush_parse' function. + + Bison also supports both the push parser interface along with the +pull parser interface in the same generated parser. In order to get +this functionality, you should replace the `%define api.push_pull +"push"' declaration with the `%define api.push_pull "both"' +declaration. Doing this will create all of the symbols mentioned +earlier along with the two extra symbols, `yyparse' and `yypull_parse'. +`yyparse' can be used exactly as it normally would be used. However, +the user should note that it is implemented in the generated parser by +calling `yypull_parse'. This makes the `yyparse' function that is +generated with the `%define api.push_pull "both"' declaration slower +than the normal `yyparse' function. If the user calls the +`yypull_parse' function it will parse the rest of the input stream. It +is possible to `yypush_parse' tokens to select a subgrammar and then +`yypull_parse' the rest of the input stream. If you would like to +switch back and forth between between parsing styles, you would have to +write your own `yypull_parse' function that knows when to quit looking +for input. An example of using the `yypull_parse' function would look +like this: + + yypstate *ps = yypstate_new (); + yypull_parse (ps); /* Will call the lexer */ + yypstate_delete (ps); + + Adding the `%define api.pure' declaration does exactly the same +thing to the generated parser with `%define api.push_pull "both"' as it +did for `%define api.push_pull "push"'. + + +File: bison.info, Node: Decl Summary, Prev: Push Decl, Up: Declarations + +3.7.12 Bison Declaration Summary +-------------------------------- + +Here is a summary of the declarations used to define a grammar: + + -- Directive: %union + Declare the collection of data types that semantic values may have + (*note The Collection of Value Types: Union Decl.). + + -- Directive: %token + Declare a terminal symbol (token type name) with no precedence or + associativity specified (*note Token Type Names: Token Decl.). + + -- Directive: %right + Declare a terminal symbol (token type name) that is + right-associative (*note Operator Precedence: Precedence Decl.). + + -- Directive: %left + Declare a terminal symbol (token type name) that is + left-associative (*note Operator Precedence: Precedence Decl.). + + -- Directive: %nonassoc + Declare a terminal symbol (token type name) that is nonassociative + (*note Operator Precedence: Precedence Decl.). Using it in a way + that would be associative is a syntax error. + + -- Directive: %type + Declare the type of semantic values for a nonterminal symbol + (*note Nonterminal Symbols: Type Decl.). + + -- Directive: %start + Specify the grammar's start symbol (*note The Start-Symbol: Start + Decl.). + + -- Directive: %expect + Declare the expected number of shift-reduce conflicts (*note + Suppressing Conflict Warnings: Expect Decl.). + + +In order to change the behavior of `bison', use the following +directives: + + -- Directive: %code {CODE} + This is the unqualified form of the `%code' directive. It inserts + CODE verbatim at a language-dependent default location in the + output(1). + + For C/C++, the default location is the parser source code file + after the usual contents of the parser header file. Thus, `%code' + replaces the traditional Yacc prologue, `%{CODE%}', for most + purposes. For a detailed discussion, see *Note Prologue + Alternatives::. + + For Java, the default location is inside the parser class. + + (Like all the Yacc prologue alternatives, this directive is + experimental. More user feedback will help to determine whether + it should become a permanent feature.) + + -- Directive: %code QUALIFIER {CODE} + This is the qualified form of the `%code' directive. If you need + to specify location-sensitive verbatim CODE that does not belong + at the default location selected by the unqualified `%code' form, + use this form instead. + + QUALIFIER identifies the purpose of CODE and thus the location(s) + where Bison should generate it. Not all values of QUALIFIER are + available for all target languages: + + * requires + + * Language(s): C, C++ + + * Purpose: This is the best place to write dependency code + required for `YYSTYPE' and `YYLTYPE'. In other words, + it's the best place to define types referenced in + `%union' directives, and it's the best place to override + Bison's default `YYSTYPE' and `YYLTYPE' definitions. + + * Location(s): The parser header file and the parser + source code file before the Bison-generated `YYSTYPE' + and `YYLTYPE' definitions. + + * provides + + * Language(s): C, C++ + + * Purpose: This is the best place to write additional + definitions and declarations that should be provided to + other modules. + + * Location(s): The parser header file and the parser + source code file after the Bison-generated `YYSTYPE', + `YYLTYPE', and token definitions. + + * top + + * Language(s): C, C++ + + * Purpose: The unqualified `%code' or `%code requires' + should usually be more appropriate than `%code top'. + However, occasionally it is necessary to insert code + much nearer the top of the parser source code file. For + example: + + %code top { + #define _GNU_SOURCE + #include <stdio.h> + } + + * Location(s): Near the top of the parser source code file. + + * imports + + * Language(s): Java + + * Purpose: This is the best place to write Java import + directives. + + * Location(s): The parser Java file after any Java package + directive and before any class definitions. + + (Like all the Yacc prologue alternatives, this directive is + experimental. More user feedback will help to determine whether + it should become a permanent feature.) + + For a detailed discussion of how to use `%code' in place of the + traditional Yacc prologue for C/C++, see *Note Prologue + Alternatives::. + + -- Directive: %debug + In the parser file, define the macro `YYDEBUG' to 1 if it is not + already defined, so that the debugging facilities are compiled. + *Note Tracing Your Parser: Tracing. + + -- Directive: %define VARIABLE + -- Directive: %define VARIABLE "VALUE" + Define a variable to adjust Bison's behavior. The possible + choices for VARIABLE, as well as their meanings, depend on the + selected target language and/or the parser skeleton (*note + %language: Decl Summary, *note %skeleton: Decl Summary.). + + Bison will warn if a VARIABLE is defined multiple times. + + Omitting `"VALUE"' is always equivalent to specifying it as `""'. + + Some VARIABLEs may be used as Booleans. In this case, Bison will + complain if the variable definition does not meet one of the + following four conditions: + + 1. `"VALUE"' is `"true"' + + 2. `"VALUE"' is omitted (or is `""'). This is equivalent to + `"true"'. + + 3. `"VALUE"' is `"false"'. + + 4. VARIABLE is never defined. In this case, Bison selects a + default value, which may depend on the selected target + language and/or parser skeleton. + + Some of the accepted VARIABLEs are: + + * api.pure + + * Language(s): C + + * Purpose: Request a pure (reentrant) parser program. + *Note A Pure (Reentrant) Parser: Pure Decl. + + * Accepted Values: Boolean + + * Default Value: `"false"' + + * api.push_pull + + * Language(s): C (LALR(1) only) + + * Purpose: Requests a pull parser, a push parser, or both. + *Note A Push Parser: Push Decl. (The current push + parsing interface is experimental and may evolve. More + user feedback will help to stabilize it.) + + * Accepted Values: `"pull"', `"push"', `"both"' + + * Default Value: `"pull"' + + * lr.keep_unreachable_states + + * Language(s): all + + * Purpose: Requests that Bison allow unreachable parser + states to remain in the parser tables. Bison considers + a state to be unreachable if there exists no sequence of + transitions from the start state to that state. A state + can become unreachable during conflict resolution if + Bison disables a shift action leading to it from a + predecessor state. Keeping unreachable states is + sometimes useful for analysis purposes, but they are + useless in the generated parser. + + * Accepted Values: Boolean + + * Default Value: `"false"' + + * Caveats: + + * Unreachable states may contain conflicts and may + use rules not used in any other state. Thus, + keeping unreachable states may induce warnings that + are irrelevant to your parser's behavior, and it + may eliminate warnings that are relevant. Of + course, the change in warnings may actually be + relevant to a parser table analysis that wants to + keep unreachable states, so this behavior will + likely remain in future Bison releases. + + * While Bison is able to remove unreachable states, + it is not guaranteed to remove other kinds of + useless states. Specifically, when Bison disables + reduce actions during conflict resolution, some + goto actions may become useless, and thus some + additional states may become useless. If Bison + were to compute which goto actions were useless and + then disable those actions, it could identify such + states as unreachable and then remove those states. + However, Bison does not compute which goto actions + are useless. + + * namespace + + * Languages(s): C++ + + * Purpose: Specifies the namespace for the parser class. + For example, if you specify: + + %define namespace "foo::bar" + + Bison uses `foo::bar' verbatim in references such as: + + foo::bar::parser::semantic_type + + However, to open a namespace, Bison removes any leading + `::' and then splits on any remaining occurrences: + + namespace foo { namespace bar { + class position; + class location; + } } + + * Accepted Values: Any absolute or relative C++ namespace + reference without a trailing `"::"'. For example, + `"foo"' or `"::foo::bar"'. + + * Default Value: The value specified by `%name-prefix', + which defaults to `yy'. This usage of `%name-prefix' is + for backward compatibility and can be confusing since + `%name-prefix' also specifies the textual prefix for the + lexical analyzer function. Thus, if you specify + `%name-prefix', it is best to also specify `%define + namespace' so that `%name-prefix' _only_ affects the + lexical analyzer function. For example, if you specify: + + %define namespace "foo" + %name-prefix "bar::" + + The parser namespace is `foo' and `yylex' is referenced + as `bar::lex'. + + + -- Directive: %defines + Write a header file containing macro definitions for the token type + names defined in the grammar as well as a few other declarations. + If the parser output file is named `NAME.c' then this file is + named `NAME.h'. + + For C parsers, the output header declares `YYSTYPE' unless + `YYSTYPE' is already defined as a macro or you have used a + `<TYPE>' tag without using `%union'. Therefore, if you are using + a `%union' (*note More Than One Value Type: Multiple Types.) with + components that require other definitions, or if you have defined + a `YYSTYPE' macro or type definition (*note Data Types of Semantic + Values: Value Type.), you need to arrange for these definitions to + be propagated to all modules, e.g., by putting them in a + prerequisite header that is included both by your parser and by + any other module that needs `YYSTYPE'. + + Unless your parser is pure, the output header declares `yylval' as + an external variable. *Note A Pure (Reentrant) Parser: Pure Decl. + + If you have also used locations, the output header declares + `YYLTYPE' and `yylloc' using a protocol similar to that of the + `YYSTYPE' macro and `yylval'. *Note Tracking Locations: Locations. + + This output file is normally essential if you wish to put the + definition of `yylex' in a separate source file, because `yylex' + typically needs to be able to refer to the above-mentioned + declarations and to the token type codes. *Note Semantic Values + of Tokens: Token Values. + + If you have declared `%code requires' or `%code provides', the + output header also contains their code. *Note %code: Decl Summary. + + -- Directive: %defines DEFINES-FILE + Same as above, but save in the file DEFINES-FILE. + + -- Directive: %destructor + Specify how the parser should reclaim the memory associated to + discarded symbols. *Note Freeing Discarded Symbols: Destructor + Decl. + + -- Directive: %file-prefix "PREFIX" + Specify a prefix to use for all Bison output file names. The + names are chosen as if the input file were named `PREFIX.y'. + + -- Directive: %language "LANGUAGE" + Specify the programming language for the generated parser. + Currently supported languages include C, C++, and Java. LANGUAGE + is case-insensitive. + + This directive is experimental and its effect may be modified in + future releases. + + -- Directive: %locations + Generate the code processing the locations (*note Special Features + for Use in Actions: Action Features.). This mode is enabled as + soon as the grammar uses the special `@N' tokens, but if your + grammar does not use it, using `%locations' allows for more + accurate syntax error messages. + + -- Directive: %name-prefix "PREFIX" + Rename the external symbols used in the parser so that they start + with PREFIX instead of `yy'. The precise list of symbols renamed + in C parsers is `yyparse', `yylex', `yyerror', `yynerrs', + `yylval', `yychar', `yydebug', and (if locations are used) + `yylloc'. If you use a push parser, `yypush_parse', + `yypull_parse', `yypstate', `yypstate_new' and `yypstate_delete' + will also be renamed. For example, if you use `%name-prefix + "c_"', the names become `c_parse', `c_lex', and so on. For C++ + parsers, see the `%define namespace' documentation in this section. + *Note Multiple Parsers in the Same Program: Multiple Parsers. + + -- Directive: %no-lines + Don't generate any `#line' preprocessor commands in the parser + file. Ordinarily Bison writes these commands in the parser file + so that the C compiler and debuggers will associate errors and + object code with your source file (the grammar file). This + directive causes them to associate errors with the parser file, + treating it an independent source file in its own right. + + -- Directive: %output "FILE" + Specify FILE for the parser file. + + -- Directive: %pure-parser + Deprecated version of `%define api.pure' (*note %define: Decl + Summary.), for which Bison is more careful to warn about + unreasonable usage. + + -- Directive: %require "VERSION" + Require version VERSION or higher of Bison. *Note Require a + Version of Bison: Require Decl. + + -- Directive: %skeleton "FILE" + Specify the skeleton to use. + + If FILE does not contain a `/', FILE is the name of a skeleton + file in the Bison installation directory. If it does, FILE is an + absolute file name or a file name relative to the directory of the + grammar file. This is similar to how most shells resolve commands. + + -- Directive: %token-table + Generate an array of token names in the parser file. The name of + the array is `yytname'; `yytname[I]' is the name of the token + whose internal Bison token code number is I. The first three + elements of `yytname' correspond to the predefined tokens `"$end"', + `"error"', and `"$undefined"'; after these come the symbols + defined in the grammar file. + + The name in the table includes all the characters needed to + represent the token in Bison. For single-character literals and + literal strings, this includes the surrounding quoting characters + and any escape sequences. For example, the Bison single-character + literal `'+'' corresponds to a three-character name, represented + in C as `"'+'"'; and the Bison two-character literal string `"\\/"' + corresponds to a five-character name, represented in C as + `"\"\\\\/\""'. + + When you specify `%token-table', Bison also generates macro + definitions for macros `YYNTOKENS', `YYNNTS', and `YYNRULES', and + `YYNSTATES': + + `YYNTOKENS' + The highest token number, plus one. + + `YYNNTS' + The number of nonterminal symbols. + + `YYNRULES' + The number of grammar rules, + + `YYNSTATES' + The number of parser states (*note Parser States::). + + -- Directive: %verbose + Write an extra output file containing verbose descriptions of the + parser states and what is done for each type of lookahead token in + that state. *Note Understanding Your Parser: Understanding, for + more information. + + -- Directive: %yacc + Pretend the option `--yacc' was given, i.e., imitate Yacc, + including its naming conventions. *Note Bison Options::, for more. + + ---------- Footnotes ---------- + + (1) The default location is actually skeleton-dependent; writers +of non-standard skeletons however should choose the default location +consistently with the behavior of the standard Bison skeletons. + + +File: bison.info, Node: Multiple Parsers, Prev: Declarations, Up: Grammar File + +3.8 Multiple Parsers in the Same Program +======================================== + +Most programs that use Bison parse only one language and therefore +contain only one Bison parser. But what if you want to parse more than +one language with the same program? Then you need to avoid a name +conflict between different definitions of `yyparse', `yylval', and so +on. + + The easy way to do this is to use the option `-p PREFIX' (*note +Invoking Bison: Invocation.). This renames the interface functions and +variables of the Bison parser to start with PREFIX instead of `yy'. +You can use this to give each parser distinct names that do not +conflict. + + The precise list of symbols renamed is `yyparse', `yylex', +`yyerror', `yynerrs', `yylval', `yylloc', `yychar' and `yydebug'. If +you use a push parser, `yypush_parse', `yypull_parse', `yypstate', +`yypstate_new' and `yypstate_delete' will also be renamed. For +example, if you use `-p c', the names become `cparse', `clex', and so +on. + + *All the other variables and macros associated with Bison are not +renamed.* These others are not global; there is no conflict if the same +name is used in different parsers. For example, `YYSTYPE' is not +renamed, but defining this in different ways in different parsers causes +no trouble (*note Data Types of Semantic Values: Value Type.). + + The `-p' option works by adding macro definitions to the beginning +of the parser source file, defining `yyparse' as `PREFIXparse', and so +on. This effectively substitutes one name for the other in the entire +parser file. + + +File: bison.info, Node: Interface, Next: Algorithm, Prev: Grammar File, Up: Top + +4 Parser C-Language Interface +***************************** + +The Bison parser is actually a C function named `yyparse'. Here we +describe the interface conventions of `yyparse' and the other functions +that it needs to use. + + Keep in mind that the parser uses many C identifiers starting with +`yy' and `YY' for internal purposes. If you use such an identifier +(aside from those in this manual) in an action or in epilogue in the +grammar file, you are likely to run into trouble. + +* Menu: + +* Parser Function:: How to call `yyparse' and what it returns. +* Push Parser Function:: How to call `yypush_parse' and what it returns. +* Pull Parser Function:: How to call `yypull_parse' and what it returns. +* Parser Create Function:: How to call `yypstate_new' and what it returns. +* Parser Delete Function:: How to call `yypstate_delete' and what it returns. +* Lexical:: You must supply a function `yylex' + which reads tokens. +* Error Reporting:: You must supply a function `yyerror'. +* Action Features:: Special features for use in actions. +* Internationalization:: How to let the parser speak in the user's + native language. + + +File: bison.info, Node: Parser Function, Next: Push Parser Function, Up: Interface + +4.1 The Parser Function `yyparse' +================================= + +You call the function `yyparse' to cause parsing to occur. This +function reads tokens, executes actions, and ultimately returns when it +encounters end-of-input or an unrecoverable syntax error. You can also +write an action which directs `yyparse' to return immediately without +reading further. + + -- Function: int yyparse (void) + The value returned by `yyparse' is 0 if parsing was successful + (return is due to end-of-input). + + The value is 1 if parsing failed because of invalid input, i.e., + input that contains a syntax error or that causes `YYABORT' to be + invoked. + + The value is 2 if parsing failed due to memory exhaustion. + + In an action, you can cause immediate return from `yyparse' by using +these macros: + + -- Macro: YYACCEPT + Return immediately with value 0 (to report success). + + -- Macro: YYABORT + Return immediately with value 1 (to report failure). + + If you use a reentrant parser, you can optionally pass additional +parameter information to it in a reentrant way. To do so, use the +declaration `%parse-param': + + -- Directive: %parse-param {ARGUMENT-DECLARATION} + Declare that an argument declared by the braced-code + ARGUMENT-DECLARATION is an additional `yyparse' argument. The + ARGUMENT-DECLARATION is used when declaring functions or + prototypes. The last identifier in ARGUMENT-DECLARATION must be + the argument name. + + Here's an example. Write this in the parser: + + %parse-param {int *nastiness} + %parse-param {int *randomness} + +Then call the parser like this: + + { + int nastiness, randomness; + ... /* Store proper data in `nastiness' and `randomness'. */ + value = yyparse (&nastiness, &randomness); + ... + } + +In the grammar actions, use expressions like this to refer to the data: + + exp: ... { ...; *randomness += 1; ... } + + +File: bison.info, Node: Push Parser Function, Next: Pull Parser Function, Prev: Parser Function, Up: Interface + +4.2 The Push Parser Function `yypush_parse' +=========================================== + +(The current push parsing interface is experimental and may evolve. +More user feedback will help to stabilize it.) + + You call the function `yypush_parse' to parse a single token. This +function is available if either the `%define api.push_pull "push"' or +`%define api.push_pull "both"' declaration is used. *Note A Push +Parser: Push Decl. + + -- Function: int yypush_parse (yypstate *yyps) + The value returned by `yypush_parse' is the same as for yyparse + with the following exception. `yypush_parse' will return + YYPUSH_MORE if more input is required to finish parsing the + grammar. + + +File: bison.info, Node: Pull Parser Function, Next: Parser Create Function, Prev: Push Parser Function, Up: Interface + +4.3 The Pull Parser Function `yypull_parse' +=========================================== + +(The current push parsing interface is experimental and may evolve. +More user feedback will help to stabilize it.) + + You call the function `yypull_parse' to parse the rest of the input +stream. This function is available if the `%define api.push_pull +"both"' declaration is used. *Note A Push Parser: Push Decl. + + -- Function: int yypull_parse (yypstate *yyps) + The value returned by `yypull_parse' is the same as for `yyparse'. + + +File: bison.info, Node: Parser Create Function, Next: Parser Delete Function, Prev: Pull Parser Function, Up: Interface + +4.4 The Parser Create Function `yystate_new' +============================================ + +(The current push parsing interface is experimental and may evolve. +More user feedback will help to stabilize it.) + + You call the function `yypstate_new' to create a new parser instance. +This function is available if either the `%define api.push_pull "push"' +or `%define api.push_pull "both"' declaration is used. *Note A Push +Parser: Push Decl. + + -- Function: yypstate *yypstate_new (void) + The fuction will return a valid parser instance if there was + memory available or 0 if no memory was available. In impure mode, + it will also return 0 if a parser instance is currently allocated. + + +File: bison.info, Node: Parser Delete Function, Next: Lexical, Prev: Parser Create Function, Up: Interface + +4.5 The Parser Delete Function `yystate_delete' +=============================================== + +(The current push parsing interface is experimental and may evolve. +More user feedback will help to stabilize it.) + + You call the function `yypstate_delete' to delete a parser instance. +function is available if either the `%define api.push_pull "push"' or +`%define api.push_pull "both"' declaration is used. *Note A Push +Parser: Push Decl. + + -- Function: void yypstate_delete (yypstate *yyps) + This function will reclaim the memory associated with a parser + instance. After this call, you should no longer attempt to use + the parser instance. + + +File: bison.info, Node: Lexical, Next: Error Reporting, Prev: Parser Delete Function, Up: Interface + +4.6 The Lexical Analyzer Function `yylex' +========================================= + +The "lexical analyzer" function, `yylex', recognizes tokens from the +input stream and returns them to the parser. Bison does not create +this function automatically; you must write it so that `yyparse' can +call it. The function is sometimes referred to as a lexical scanner. + + In simple programs, `yylex' is often defined at the end of the Bison +grammar file. If `yylex' is defined in a separate source file, you +need to arrange for the token-type macro definitions to be available +there. To do this, use the `-d' option when you run Bison, so that it +will write these macro definitions into a separate header file +`NAME.tab.h' which you can include in the other source files that need +it. *Note Invoking Bison: Invocation. + +* Menu: + +* Calling Convention:: How `yyparse' calls `yylex'. +* Token Values:: How `yylex' must return the semantic value + of the token it has read. +* Token Locations:: How `yylex' must return the text location + (line number, etc.) of the token, if the + actions want that. +* Pure Calling:: How the calling convention differs in a pure parser + (*note A Pure (Reentrant) Parser: Pure Decl.). + + +File: bison.info, Node: Calling Convention, Next: Token Values, Up: Lexical + +4.6.1 Calling Convention for `yylex' +------------------------------------ + +The value that `yylex' returns must be the positive numeric code for +the type of token it has just found; a zero or negative value signifies +end-of-input. + + When a token is referred to in the grammar rules by a name, that name +in the parser file becomes a C macro whose definition is the proper +numeric code for that token type. So `yylex' can use the name to +indicate that type. *Note Symbols::. + + When a token is referred to in the grammar rules by a character +literal, the numeric code for that character is also the code for the +token type. So `yylex' can simply return that character code, possibly +converted to `unsigned char' to avoid sign-extension. The null +character must not be used this way, because its code is zero and that +signifies end-of-input. + + Here is an example showing these things: + + int + yylex (void) + { + ... + if (c == EOF) /* Detect end-of-input. */ + return 0; + ... + if (c == '+' || c == '-') + return c; /* Assume token type for `+' is '+'. */ + ... + return INT; /* Return the type of the token. */ + ... + } + +This interface has been designed so that the output from the `lex' +utility can be used without change as the definition of `yylex'. + + If the grammar uses literal string tokens, there are two ways that +`yylex' can determine the token type codes for them: + + * If the grammar defines symbolic token names as aliases for the + literal string tokens, `yylex' can use these symbolic names like + all others. In this case, the use of the literal string tokens in + the grammar file has no effect on `yylex'. + + * `yylex' can find the multicharacter token in the `yytname' table. + The index of the token in the table is the token type's code. The + name of a multicharacter token is recorded in `yytname' with a + double-quote, the token's characters, and another double-quote. + The token's characters are escaped as necessary to be suitable as + input to Bison. + + Here's code for looking up a multicharacter token in `yytname', + assuming that the characters of the token are stored in + `token_buffer', and assuming that the token does not contain any + characters like `"' that require escaping. + + for (i = 0; i < YYNTOKENS; i++) + { + if (yytname[i] != 0 + && yytname[i][0] == '"' + && ! strncmp (yytname[i] + 1, token_buffer, + strlen (token_buffer)) + && yytname[i][strlen (token_buffer) + 1] == '"' + && yytname[i][strlen (token_buffer) + 2] == 0) + break; + } + + The `yytname' table is generated only if you use the + `%token-table' declaration. *Note Decl Summary::. + + +File: bison.info, Node: Token Values, Next: Token Locations, Prev: Calling Convention, Up: Lexical + +4.6.2 Semantic Values of Tokens +------------------------------- + +In an ordinary (nonreentrant) parser, the semantic value of the token +must be stored into the global variable `yylval'. When you are using +just one data type for semantic values, `yylval' has that type. Thus, +if the type is `int' (the default), you might write this in `yylex': + + ... + yylval = value; /* Put value onto Bison stack. */ + return INT; /* Return the type of the token. */ + ... + + When you are using multiple data types, `yylval''s type is a union +made from the `%union' declaration (*note The Collection of Value +Types: Union Decl.). So when you store a token's value, you must use +the proper member of the union. If the `%union' declaration looks like +this: + + %union { + int intval; + double val; + symrec *tptr; + } + +then the code in `yylex' might look like this: + + ... + yylval.intval = value; /* Put value onto Bison stack. */ + return INT; /* Return the type of the token. */ + ... + + +File: bison.info, Node: Token Locations, Next: Pure Calling, Prev: Token Values, Up: Lexical + +4.6.3 Textual Locations of Tokens +--------------------------------- + +If you are using the `@N'-feature (*note Tracking Locations: +Locations.) in actions to keep track of the textual locations of tokens +and groupings, then you must provide this information in `yylex'. The +function `yyparse' expects to find the textual location of a token just +parsed in the global variable `yylloc'. So `yylex' must store the +proper data in that variable. + + By default, the value of `yylloc' is a structure and you need only +initialize the members that are going to be used by the actions. The +four members are called `first_line', `first_column', `last_line' and +`last_column'. Note that the use of this feature makes the parser +noticeably slower. + + The data type of `yylloc' has the name `YYLTYPE'. + + +File: bison.info, Node: Pure Calling, Prev: Token Locations, Up: Lexical + +4.6.4 Calling Conventions for Pure Parsers +------------------------------------------ + +When you use the Bison declaration `%define api.pure' to request a +pure, reentrant parser, the global communication variables `yylval' and +`yylloc' cannot be used. (*Note A Pure (Reentrant) Parser: Pure Decl.) +In such parsers the two global variables are replaced by pointers +passed as arguments to `yylex'. You must declare them as shown here, +and pass the information back by storing it through those pointers. + + int + yylex (YYSTYPE *lvalp, YYLTYPE *llocp) + { + ... + *lvalp = value; /* Put value onto Bison stack. */ + return INT; /* Return the type of the token. */ + ... + } + + If the grammar file does not use the `@' constructs to refer to +textual locations, then the type `YYLTYPE' will not be defined. In +this case, omit the second argument; `yylex' will be called with only +one argument. + + If you wish to pass the additional parameter data to `yylex', use +`%lex-param' just like `%parse-param' (*note Parser Function::). + + -- Directive: lex-param {ARGUMENT-DECLARATION} + Declare that the braced-code ARGUMENT-DECLARATION is an additional + `yylex' argument declaration. + + For instance: + + %parse-param {int *nastiness} + %lex-param {int *nastiness} + %parse-param {int *randomness} + +results in the following signature: + + int yylex (int *nastiness); + int yyparse (int *nastiness, int *randomness); + + If `%define api.pure' is added: + + int yylex (YYSTYPE *lvalp, int *nastiness); + int yyparse (int *nastiness, int *randomness); + +and finally, if both `%define api.pure' and `%locations' are used: + + int yylex (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness); + int yyparse (int *nastiness, int *randomness); + + +File: bison.info, Node: Error Reporting, Next: Action Features, Prev: Lexical, Up: Interface + +4.7 The Error Reporting Function `yyerror' +========================================== + +The Bison parser detects a "syntax error" or "parse error" whenever it +reads a token which cannot satisfy any syntax rule. An action in the +grammar can also explicitly proclaim an error, using the macro +`YYERROR' (*note Special Features for Use in Actions: Action Features.). + + The Bison parser expects to report the error by calling an error +reporting function named `yyerror', which you must supply. It is +called by `yyparse' whenever a syntax error is found, and it receives +one argument. For a syntax error, the string is normally +`"syntax error"'. + + If you invoke the directive `%error-verbose' in the Bison +declarations section (*note The Bison Declarations Section: Bison +Declarations.), then Bison provides a more verbose and specific error +message string instead of just plain `"syntax error"'. + + The parser can detect one other kind of error: memory exhaustion. +This can happen when the input contains constructions that are very +deeply nested. It isn't likely you will encounter this, since the Bison +parser normally extends its stack automatically up to a very large +limit. But if memory is exhausted, `yyparse' calls `yyerror' in the +usual fashion, except that the argument string is `"memory exhausted"'. + + In some cases diagnostics like `"syntax error"' are translated +automatically from English to some other language before they are +passed to `yyerror'. *Note Internationalization::. + + The following definition suffices in simple programs: + + void + yyerror (char const *s) + { + fprintf (stderr, "%s\n", s); + } + + After `yyerror' returns to `yyparse', the latter will attempt error +recovery if you have written suitable error recovery grammar rules +(*note Error Recovery::). If recovery is impossible, `yyparse' will +immediately return 1. + + Obviously, in location tracking pure parsers, `yyerror' should have +an access to the current location. This is indeed the case for the GLR +parsers, but not for the Yacc parser, for historical reasons. I.e., if +`%locations %define api.pure' is passed then the prototypes for +`yyerror' are: + + void yyerror (char const *msg); /* Yacc parsers. */ + void yyerror (YYLTYPE *locp, char const *msg); /* GLR parsers. */ + + If `%parse-param {int *nastiness}' is used, then: + + void yyerror (int *nastiness, char const *msg); /* Yacc parsers. */ + void yyerror (int *nastiness, char const *msg); /* GLR parsers. */ + + Finally, GLR and Yacc parsers share the same `yyerror' calling +convention for absolutely pure parsers, i.e., when the calling +convention of `yylex' _and_ the calling convention of `%define +api.pure' are pure. I.e.: + + /* Location tracking. */ + %locations + /* Pure yylex. */ + %define api.pure + %lex-param {int *nastiness} + /* Pure yyparse. */ + %parse-param {int *nastiness} + %parse-param {int *randomness} + +results in the following signatures for all the parser kinds: + + int yylex (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness); + int yyparse (int *nastiness, int *randomness); + void yyerror (YYLTYPE *locp, + int *nastiness, int *randomness, + char const *msg); + +The prototypes are only indications of how the code produced by Bison +uses `yyerror'. Bison-generated code always ignores the returned +value, so `yyerror' can return any type, including `void'. Also, +`yyerror' can be a variadic function; that is why the message is always +passed last. + + Traditionally `yyerror' returns an `int' that is always ignored, but +this is purely for historical reasons, and `void' is preferable since +it more accurately describes the return type for `yyerror'. + + The variable `yynerrs' contains the number of syntax errors reported +so far. Normally this variable is global; but if you request a pure +parser (*note A Pure (Reentrant) Parser: Pure Decl.) then it is a +local variable which only the actions can access. + + +File: bison.info, Node: Action Features, Next: Internationalization, Prev: Error Reporting, Up: Interface + +4.8 Special Features for Use in Actions +======================================= + +Here is a table of Bison constructs, variables and macros that are +useful in actions. + + -- Variable: $$ + Acts like a variable that contains the semantic value for the + grouping made by the current rule. *Note Actions::. + + -- Variable: $N + Acts like a variable that contains the semantic value for the Nth + component of the current rule. *Note Actions::. + + -- Variable: $<TYPEALT>$ + Like `$$' but specifies alternative TYPEALT in the union specified + by the `%union' declaration. *Note Data Types of Values in + Actions: Action Types. + + -- Variable: $<TYPEALT>N + Like `$N' but specifies alternative TYPEALT in the union specified + by the `%union' declaration. *Note Data Types of Values in + Actions: Action Types. + + -- Macro: YYABORT; + Return immediately from `yyparse', indicating failure. *Note The + Parser Function `yyparse': Parser Function. + + -- Macro: YYACCEPT; + Return immediately from `yyparse', indicating success. *Note The + Parser Function `yyparse': Parser Function. + + -- Macro: YYBACKUP (TOKEN, VALUE); + Unshift a token. This macro is allowed only for rules that reduce + a single value, and only when there is no lookahead token. It is + also disallowed in GLR parsers. It installs a lookahead token + with token type TOKEN and semantic value VALUE; then it discards + the value that was going to be reduced by this rule. + + If the macro is used when it is not valid, such as when there is a + lookahead token already, then it reports a syntax error with a + message `cannot back up' and performs ordinary error recovery. + + In either case, the rest of the action is not executed. + + -- Macro: YYEMPTY + Value stored in `yychar' when there is no lookahead token. + + -- Macro: YYEOF + Value stored in `yychar' when the lookahead is the end of the input + stream. + + -- Macro: YYERROR; + Cause an immediate syntax error. This statement initiates error + recovery just as if the parser itself had detected an error; + however, it does not call `yyerror', and does not print any + message. If you want to print an error message, call `yyerror' + explicitly before the `YYERROR;' statement. *Note Error + Recovery::. + + -- Macro: YYRECOVERING + The expression `YYRECOVERING ()' yields 1 when the parser is + recovering from a syntax error, and 0 otherwise. *Note Error + Recovery::. + + -- Variable: yychar + Variable containing either the lookahead token, or `YYEOF' when the + lookahead is the end of the input stream, or `YYEMPTY' when no + lookahead has been performed so the next token is not yet known. + Do not modify `yychar' in a deferred semantic action (*note GLR + Semantic Actions::). *Note Lookahead Tokens: Lookahead. + + -- Macro: yyclearin; + Discard the current lookahead token. This is useful primarily in + error rules. Do not invoke `yyclearin' in a deferred semantic + action (*note GLR Semantic Actions::). *Note Error Recovery::. + + -- Macro: yyerrok; + Resume generating error messages immediately for subsequent syntax + errors. This is useful primarily in error rules. *Note Error + Recovery::. + + -- Variable: yylloc + Variable containing the lookahead token location when `yychar' is + not set to `YYEMPTY' or `YYEOF'. Do not modify `yylloc' in a + deferred semantic action (*note GLR Semantic Actions::). *Note + Actions and Locations: Actions and Locations. + + -- Variable: yylval + Variable containing the lookahead token semantic value when + `yychar' is not set to `YYEMPTY' or `YYEOF'. Do not modify + `yylval' in a deferred semantic action (*note GLR Semantic + Actions::). *Note Actions: Actions. + + -- Value: @$ + Acts like a structure variable containing information on the + textual location of the grouping made by the current rule. *Note + Tracking Locations: Locations. + + + -- Value: @N + Acts like a structure variable containing information on the + textual location of the Nth component of the current rule. *Note + Tracking Locations: Locations. + + +File: bison.info, Node: Internationalization, Prev: Action Features, Up: Interface + +4.9 Parser Internationalization +=============================== + +A Bison-generated parser can print diagnostics, including error and +tracing messages. By default, they appear in English. However, Bison +also supports outputting diagnostics in the user's native language. To +make this work, the user should set the usual environment variables. +*Note The User's View: (gettext)Users. For example, the shell command +`export LC_ALL=fr_CA.UTF-8' might set the user's locale to French +Canadian using the UTF-8 encoding. The exact set of available locales +depends on the user's installation. + + The maintainer of a package that uses a Bison-generated parser +enables the internationalization of the parser's output through the +following steps. Here we assume a package that uses GNU Autoconf and +GNU Automake. + + 1. Into the directory containing the GNU Autoconf macros used by the + package--often called `m4'--copy the `bison-i18n.m4' file + installed by Bison under `share/aclocal/bison-i18n.m4' in Bison's + installation directory. For example: + + cp /usr/local/share/aclocal/bison-i18n.m4 m4/bison-i18n.m4 + + 2. In the top-level `configure.ac', after the `AM_GNU_GETTEXT' + invocation, add an invocation of `BISON_I18N'. This macro is + defined in the file `bison-i18n.m4' that you copied earlier. It + causes `configure' to find the value of the `BISON_LOCALEDIR' + variable, and it defines the source-language symbol `YYENABLE_NLS' + to enable translations in the Bison-generated parser. + + 3. In the `main' function of your program, designate the directory + containing Bison's runtime message catalog, through a call to + `bindtextdomain' with domain name `bison-runtime'. For example: + + bindtextdomain ("bison-runtime", BISON_LOCALEDIR); + + Typically this appears after any other call `bindtextdomain + (PACKAGE, LOCALEDIR)' that your package already has. Here we rely + on `BISON_LOCALEDIR' to be defined as a string through the + `Makefile'. + + 4. In the `Makefile.am' that controls the compilation of the `main' + function, make `BISON_LOCALEDIR' available as a C preprocessor + macro, either in `DEFS' or in `AM_CPPFLAGS'. For example: + + DEFS = @DEFS@ -DBISON_LOCALEDIR='"$(BISON_LOCALEDIR)"' + + or: + + AM_CPPFLAGS = -DBISON_LOCALEDIR='"$(BISON_LOCALEDIR)"' + + 5. Finally, invoke the command `autoreconf' to generate the build + infrastructure. + + +File: bison.info, Node: Algorithm, Next: Error Recovery, Prev: Interface, Up: Top + +5 The Bison Parser Algorithm +**************************** + +As Bison reads tokens, it pushes them onto a stack along with their +semantic values. The stack is called the "parser stack". Pushing a +token is traditionally called "shifting". + + For example, suppose the infix calculator has read `1 + 5 *', with a +`3' to come. The stack will have four elements, one for each token +that was shifted. + + But the stack does not always have an element for each token read. +When the last N tokens and groupings shifted match the components of a +grammar rule, they can be combined according to that rule. This is +called "reduction". Those tokens and groupings are replaced on the +stack by a single grouping whose symbol is the result (left hand side) +of that rule. Running the rule's action is part of the process of +reduction, because this is what computes the semantic value of the +resulting grouping. + + For example, if the infix calculator's parser stack contains this: + + 1 + 5 * 3 + +and the next input token is a newline character, then the last three +elements can be reduced to 15 via the rule: + + expr: expr '*' expr; + +Then the stack contains just these three elements: + + 1 + 15 + +At this point, another reduction can be made, resulting in the single +value 16. Then the newline token can be shifted. + + The parser tries, by shifts and reductions, to reduce the entire +input down to a single grouping whose symbol is the grammar's +start-symbol (*note Languages and Context-Free Grammars: Language and +Grammar.). + + This kind of parser is known in the literature as a bottom-up parser. + +* Menu: + +* Lookahead:: Parser looks one token ahead when deciding what to do. +* Shift/Reduce:: Conflicts: when either shifting or reduction is valid. +* Precedence:: Operator precedence works by resolving conflicts. +* Contextual Precedence:: When an operator's precedence depends on context. +* Parser States:: The parser is a finite-state-machine with stack. +* Reduce/Reduce:: When two rules are applicable in the same situation. +* Mystery Conflicts:: Reduce/reduce conflicts that look unjustified. +* Generalized LR Parsing:: Parsing arbitrary context-free grammars. +* Memory Management:: What happens when memory is exhausted. How to avoid it. + + +File: bison.info, Node: Lookahead, Next: Shift/Reduce, Up: Algorithm + +5.1 Lookahead Tokens +==================== + +The Bison parser does _not_ always reduce immediately as soon as the +last N tokens and groupings match a rule. This is because such a +simple strategy is inadequate to handle most languages. Instead, when a +reduction is possible, the parser sometimes "looks ahead" at the next +token in order to decide what to do. + + When a token is read, it is not immediately shifted; first it +becomes the "lookahead token", which is not on the stack. Now the +parser can perform one or more reductions of tokens and groupings on +the stack, while the lookahead token remains off to the side. When no +more reductions should take place, the lookahead token is shifted onto +the stack. This does not mean that all possible reductions have been +done; depending on the token type of the lookahead token, some rules +may choose to delay their application. + + Here is a simple case where lookahead is needed. These three rules +define expressions which contain binary addition operators and postfix +unary factorial operators (`!'), and allow parentheses for grouping. + + expr: term '+' expr + | term + ; + + term: '(' expr ')' + | term '!' + | NUMBER + ; + + Suppose that the tokens `1 + 2' have been read and shifted; what +should be done? If the following token is `)', then the first three +tokens must be reduced to form an `expr'. This is the only valid +course, because shifting the `)' would produce a sequence of symbols +`term ')'', and no rule allows this. + + If the following token is `!', then it must be shifted immediately so +that `2 !' can be reduced to make a `term'. If instead the parser were +to reduce before shifting, `1 + 2' would become an `expr'. It would +then be impossible to shift the `!' because doing so would produce on +the stack the sequence of symbols `expr '!''. No rule allows that +sequence. + + The lookahead token is stored in the variable `yychar'. Its +semantic value and location, if any, are stored in the variables +`yylval' and `yylloc'. *Note Special Features for Use in Actions: +Action Features. + + +File: bison.info, Node: Shift/Reduce, Next: Precedence, Prev: Lookahead, Up: Algorithm + +5.2 Shift/Reduce Conflicts +========================== + +Suppose we are parsing a language which has if-then and if-then-else +statements, with a pair of rules like this: + + if_stmt: + IF expr THEN stmt + | IF expr THEN stmt ELSE stmt + ; + +Here we assume that `IF', `THEN' and `ELSE' are terminal symbols for +specific keyword tokens. + + When the `ELSE' token is read and becomes the lookahead token, the +contents of the stack (assuming the input is valid) are just right for +reduction by the first rule. But it is also legitimate to shift the +`ELSE', because that would lead to eventual reduction by the second +rule. + + This situation, where either a shift or a reduction would be valid, +is called a "shift/reduce conflict". Bison is designed to resolve +these conflicts by choosing to shift, unless otherwise directed by +operator precedence declarations. To see the reason for this, let's +contrast it with the other alternative. + + Since the parser prefers to shift the `ELSE', the result is to attach +the else-clause to the innermost if-statement, making these two inputs +equivalent: + + if x then if y then win (); else lose; + + if x then do; if y then win (); else lose; end; + + But if the parser chose to reduce when possible rather than shift, +the result would be to attach the else-clause to the outermost +if-statement, making these two inputs equivalent: + + if x then if y then win (); else lose; + + if x then do; if y then win (); end; else lose; + + The conflict exists because the grammar as written is ambiguous: +either parsing of the simple nested if-statement is legitimate. The +established convention is that these ambiguities are resolved by +attaching the else-clause to the innermost if-statement; this is what +Bison accomplishes by choosing to shift rather than reduce. (It would +ideally be cleaner to write an unambiguous grammar, but that is very +hard to do in this case.) This particular ambiguity was first +encountered in the specifications of Algol 60 and is called the +"dangling `else'" ambiguity. + + To avoid warnings from Bison about predictable, legitimate +shift/reduce conflicts, use the `%expect N' declaration. There will be +no warning as long as the number of shift/reduce conflicts is exactly N. +*Note Suppressing Conflict Warnings: Expect Decl. + + The definition of `if_stmt' above is solely to blame for the +conflict, but the conflict does not actually appear without additional +rules. Here is a complete Bison input file that actually manifests the +conflict: + + %token IF THEN ELSE variable + %% + stmt: expr + | if_stmt + ; + + if_stmt: + IF expr THEN stmt + | IF expr THEN stmt ELSE stmt + ; + + expr: variable + ; + + +File: bison.info, Node: Precedence, Next: Contextual Precedence, Prev: Shift/Reduce, Up: Algorithm + +5.3 Operator Precedence +======================= + +Another situation where shift/reduce conflicts appear is in arithmetic +expressions. Here shifting is not always the preferred resolution; the +Bison declarations for operator precedence allow you to specify when to +shift and when to reduce. + +* Menu: + +* Why Precedence:: An example showing why precedence is needed. +* Using Precedence:: How to specify precedence in Bison grammars. +* Precedence Examples:: How these features are used in the previous example. +* How Precedence:: How they work. + + +File: bison.info, Node: Why Precedence, Next: Using Precedence, Up: Precedence + +5.3.1 When Precedence is Needed +------------------------------- + +Consider the following ambiguous grammar fragment (ambiguous because the +input `1 - 2 * 3' can be parsed in two different ways): + + expr: expr '-' expr + | expr '*' expr + | expr '<' expr + | '(' expr ')' + ... + ; + +Suppose the parser has seen the tokens `1', `-' and `2'; should it +reduce them via the rule for the subtraction operator? It depends on +the next token. Of course, if the next token is `)', we must reduce; +shifting is invalid because no single rule can reduce the token +sequence `- 2 )' or anything starting with that. But if the next token +is `*' or `<', we have a choice: either shifting or reduction would +allow the parse to complete, but with different results. + + To decide which one Bison should do, we must consider the results. +If the next operator token OP is shifted, then it must be reduced first +in order to permit another opportunity to reduce the difference. The +result is (in effect) `1 - (2 OP 3)'. On the other hand, if the +subtraction is reduced before shifting OP, the result is +`(1 - 2) OP 3'. Clearly, then, the choice of shift or reduce should +depend on the relative precedence of the operators `-' and OP: `*' +should be shifted first, but not `<'. + + What about input such as `1 - 2 - 5'; should this be `(1 - 2) - 5' +or should it be `1 - (2 - 5)'? For most operators we prefer the +former, which is called "left association". The latter alternative, +"right association", is desirable for assignment operators. The choice +of left or right association is a matter of whether the parser chooses +to shift or reduce when the stack contains `1 - 2' and the lookahead +token is `-': shifting makes right-associativity. + + +File: bison.info, Node: Using Precedence, Next: Precedence Examples, Prev: Why Precedence, Up: Precedence + +5.3.2 Specifying Operator Precedence +------------------------------------ + +Bison allows you to specify these choices with the operator precedence +declarations `%left' and `%right'. Each such declaration contains a +list of tokens, which are operators whose precedence and associativity +is being declared. The `%left' declaration makes all those operators +left-associative and the `%right' declaration makes them +right-associative. A third alternative is `%nonassoc', which declares +that it is a syntax error to find the same operator twice "in a row". + + The relative precedence of different operators is controlled by the +order in which they are declared. The first `%left' or `%right' +declaration in the file declares the operators whose precedence is +lowest, the next such declaration declares the operators whose +precedence is a little higher, and so on. + + +File: bison.info, Node: Precedence Examples, Next: How Precedence, Prev: Using Precedence, Up: Precedence + +5.3.3 Precedence Examples +------------------------- + +In our example, we would want the following declarations: + + %left '<' + %left '-' + %left '*' + + In a more complete example, which supports other operators as well, +we would declare them in groups of equal precedence. For example, +`'+'' is declared with `'-'': + + %left '<' '>' '=' NE LE GE + %left '+' '-' + %left '*' '/' + +(Here `NE' and so on stand for the operators for "not equal" and so on. +We assume that these tokens are more than one character long and +therefore are represented by names, not character literals.) + + +File: bison.info, Node: How Precedence, Prev: Precedence Examples, Up: Precedence + +5.3.4 How Precedence Works +-------------------------- + +The first effect of the precedence declarations is to assign precedence +levels to the terminal symbols declared. The second effect is to assign +precedence levels to certain rules: each rule gets its precedence from +the last terminal symbol mentioned in the components. (You can also +specify explicitly the precedence of a rule. *Note Context-Dependent +Precedence: Contextual Precedence.) + + Finally, the resolution of conflicts works by comparing the +precedence of the rule being considered with that of the lookahead +token. If the token's precedence is higher, the choice is to shift. +If the rule's precedence is higher, the choice is to reduce. If they +have equal precedence, the choice is made based on the associativity of +that precedence level. The verbose output file made by `-v' (*note +Invoking Bison: Invocation.) says how each conflict was resolved. + + Not all rules and not all tokens have precedence. If either the +rule or the lookahead token has no precedence, then the default is to +shift. + + +File: bison.info, Node: Contextual Precedence, Next: Parser States, Prev: Precedence, Up: Algorithm + +5.4 Context-Dependent Precedence +================================ + +Often the precedence of an operator depends on the context. This sounds +outlandish at first, but it is really very common. For example, a minus +sign typically has a very high precedence as a unary operator, and a +somewhat lower precedence (lower than multiplication) as a binary +operator. + + The Bison precedence declarations, `%left', `%right' and +`%nonassoc', can only be used once for a given token; so a token has +only one precedence declared in this way. For context-dependent +precedence, you need to use an additional mechanism: the `%prec' +modifier for rules. + + The `%prec' modifier declares the precedence of a particular rule by +specifying a terminal symbol whose precedence should be used for that +rule. It's not necessary for that symbol to appear otherwise in the +rule. The modifier's syntax is: + + %prec TERMINAL-SYMBOL + +and it is written after the components of the rule. Its effect is to +assign the rule the precedence of TERMINAL-SYMBOL, overriding the +precedence that would be deduced for it in the ordinary way. The +altered rule precedence then affects how conflicts involving that rule +are resolved (*note Operator Precedence: Precedence.). + + Here is how `%prec' solves the problem of unary minus. First, +declare a precedence for a fictitious terminal symbol named `UMINUS'. +There are no tokens of this type, but the symbol serves to stand for its +precedence: + + ... + %left '+' '-' + %left '*' + %left UMINUS + + Now the precedence of `UMINUS' can be used in specific rules: + + exp: ... + | exp '-' exp + ... + | '-' exp %prec UMINUS + + +File: bison.info, Node: Parser States, Next: Reduce/Reduce, Prev: Contextual Precedence, Up: Algorithm + +5.5 Parser States +================= + +The function `yyparse' is implemented using a finite-state machine. +The values pushed on the parser stack are not simply token type codes; +they represent the entire sequence of terminal and nonterminal symbols +at or near the top of the stack. The current state collects all the +information about previous input which is relevant to deciding what to +do next. + + Each time a lookahead token is read, the current parser state +together with the type of lookahead token are looked up in a table. +This table entry can say, "Shift the lookahead token." In this case, +it also specifies the new parser state, which is pushed onto the top of +the parser stack. Or it can say, "Reduce using rule number N." This +means that a certain number of tokens or groupings are taken off the +top of the stack, and replaced by one grouping. In other words, that +number of states are popped from the stack, and one new state is pushed. + + There is one other alternative: the table can say that the lookahead +token is erroneous in the current state. This causes error processing +to begin (*note Error Recovery::). + + +File: bison.info, Node: Reduce/Reduce, Next: Mystery Conflicts, Prev: Parser States, Up: Algorithm + +5.6 Reduce/Reduce Conflicts +=========================== + +A reduce/reduce conflict occurs if there are two or more rules that +apply to the same sequence of input. This usually indicates a serious +error in the grammar. + + For example, here is an erroneous attempt to define a sequence of +zero or more `word' groupings. + + sequence: /* empty */ + { printf ("empty sequence\n"); } + | maybeword + | sequence word + { printf ("added word %s\n", $2); } + ; + + maybeword: /* empty */ + { printf ("empty maybeword\n"); } + | word + { printf ("single word %s\n", $1); } + ; + +The error is an ambiguity: there is more than one way to parse a single +`word' into a `sequence'. It could be reduced to a `maybeword' and +then into a `sequence' via the second rule. Alternatively, +nothing-at-all could be reduced into a `sequence' via the first rule, +and this could be combined with the `word' using the third rule for +`sequence'. + + There is also more than one way to reduce nothing-at-all into a +`sequence'. This can be done directly via the first rule, or +indirectly via `maybeword' and then the second rule. + + You might think that this is a distinction without a difference, +because it does not change whether any particular input is valid or +not. But it does affect which actions are run. One parsing order runs +the second rule's action; the other runs the first rule's action and +the third rule's action. In this example, the output of the program +changes. + + Bison resolves a reduce/reduce conflict by choosing to use the rule +that appears first in the grammar, but it is very risky to rely on +this. Every reduce/reduce conflict must be studied and usually +eliminated. Here is the proper way to define `sequence': + + sequence: /* empty */ + { printf ("empty sequence\n"); } + | sequence word + { printf ("added word %s\n", $2); } + ; + + Here is another common error that yields a reduce/reduce conflict: + + sequence: /* empty */ + | sequence words + | sequence redirects + ; + + words: /* empty */ + | words word + ; + + redirects:/* empty */ + | redirects redirect + ; + +The intention here is to define a sequence which can contain either +`word' or `redirect' groupings. The individual definitions of +`sequence', `words' and `redirects' are error-free, but the three +together make a subtle ambiguity: even an empty input can be parsed in +infinitely many ways! + + Consider: nothing-at-all could be a `words'. Or it could be two +`words' in a row, or three, or any number. It could equally well be a +`redirects', or two, or any number. Or it could be a `words' followed +by three `redirects' and another `words'. And so on. + + Here are two ways to correct these rules. First, to make it a +single level of sequence: + + sequence: /* empty */ + | sequence word + | sequence redirect + ; + + Second, to prevent either a `words' or a `redirects' from being +empty: + + sequence: /* empty */ + | sequence words + | sequence redirects + ; + + words: word + | words word + ; + + redirects:redirect + | redirects redirect + ; + + +File: bison.info, Node: Mystery Conflicts, Next: Generalized LR Parsing, Prev: Reduce/Reduce, Up: Algorithm + +5.7 Mysterious Reduce/Reduce Conflicts +====================================== + +Sometimes reduce/reduce conflicts can occur that don't look warranted. +Here is an example: + + %token ID + + %% + def: param_spec return_spec ',' + ; + param_spec: + type + | name_list ':' type + ; + return_spec: + type + | name ':' type + ; + type: ID + ; + name: ID + ; + name_list: + name + | name ',' name_list + ; + + It would seem that this grammar can be parsed with only a single +token of lookahead: when a `param_spec' is being read, an `ID' is a +`name' if a comma or colon follows, or a `type' if another `ID' +follows. In other words, this grammar is LR(1). + + However, Bison, like most parser generators, cannot actually handle +all LR(1) grammars. In this grammar, two contexts, that after an `ID' +at the beginning of a `param_spec' and likewise at the beginning of a +`return_spec', are similar enough that Bison assumes they are the same. +They appear similar because the same set of rules would be active--the +rule for reducing to a `name' and that for reducing to a `type'. Bison +is unable to determine at that stage of processing that the rules would +require different lookahead tokens in the two contexts, so it makes a +single parser state for them both. Combining the two contexts causes a +conflict later. In parser terminology, this occurrence means that the +grammar is not LALR(1). + + In general, it is better to fix deficiencies than to document them. +But this particular deficiency is intrinsically hard to fix; parser +generators that can handle LR(1) grammars are hard to write and tend to +produce parsers that are very large. In practice, Bison is more useful +as it is now. + + When the problem arises, you can often fix it by identifying the two +parser states that are being confused, and adding something to make them +look distinct. In the above example, adding one rule to `return_spec' +as follows makes the problem go away: + + %token BOGUS + ... + %% + ... + return_spec: + type + | name ':' type + /* This rule is never used. */ + | ID BOGUS + ; + + This corrects the problem because it introduces the possibility of an +additional active rule in the context after the `ID' at the beginning of +`return_spec'. This rule is not active in the corresponding context in +a `param_spec', so the two contexts receive distinct parser states. As +long as the token `BOGUS' is never generated by `yylex', the added rule +cannot alter the way actual input is parsed. + + In this particular example, there is another way to solve the +problem: rewrite the rule for `return_spec' to use `ID' directly +instead of via `name'. This also causes the two confusing contexts to +have different sets of active rules, because the one for `return_spec' +activates the altered rule for `return_spec' rather than the one for +`name'. + + param_spec: + type + | name_list ':' type + ; + return_spec: + type + | ID ':' type + ; + + For a more detailed exposition of LALR(1) parsers and parser +generators, please see: Frank DeRemer and Thomas Pennello, Efficient +Computation of LALR(1) Look-Ahead Sets, `ACM Transactions on +Programming Languages and Systems', Vol. 4, No. 4 (October 1982), pp. +615-649 `http://doi.acm.org/10.1145/69622.357187'. + + +File: bison.info, Node: Generalized LR Parsing, Next: Memory Management, Prev: Mystery Conflicts, Up: Algorithm + +5.8 Generalized LR (GLR) Parsing +================================ + +Bison produces _deterministic_ parsers that choose uniquely when to +reduce and which reduction to apply based on a summary of the preceding +input and on one extra token of lookahead. As a result, normal Bison +handles a proper subset of the family of context-free languages. +Ambiguous grammars, since they have strings with more than one possible +sequence of reductions cannot have deterministic parsers in this sense. +The same is true of languages that require more than one symbol of +lookahead, since the parser lacks the information necessary to make a +decision at the point it must be made in a shift-reduce parser. +Finally, as previously mentioned (*note Mystery Conflicts::), there are +languages where Bison's particular choice of how to summarize the input +seen so far loses necessary information. + + When you use the `%glr-parser' declaration in your grammar file, +Bison generates a parser that uses a different algorithm, called +Generalized LR (or GLR). A Bison GLR parser uses the same basic +algorithm for parsing as an ordinary Bison parser, but behaves +differently in cases where there is a shift-reduce conflict that has not +been resolved by precedence rules (*note Precedence::) or a +reduce-reduce conflict. When a GLR parser encounters such a situation, +it effectively _splits_ into a several parsers, one for each possible +shift or reduction. These parsers then proceed as usual, consuming +tokens in lock-step. Some of the stacks may encounter other conflicts +and split further, with the result that instead of a sequence of states, +a Bison GLR parsing stack is what is in effect a tree of states. + + In effect, each stack represents a guess as to what the proper parse +is. Additional input may indicate that a guess was wrong, in which case +the appropriate stack silently disappears. Otherwise, the semantics +actions generated in each stack are saved, rather than being executed +immediately. When a stack disappears, its saved semantic actions never +get executed. When a reduction causes two stacks to become equivalent, +their sets of semantic actions are both saved with the state that +results from the reduction. We say that two stacks are equivalent when +they both represent the same sequence of states, and each pair of +corresponding states represents a grammar symbol that produces the same +segment of the input token stream. + + Whenever the parser makes a transition from having multiple states +to having one, it reverts to the normal LALR(1) parsing algorithm, +after resolving and executing the saved-up actions. At this +transition, some of the states on the stack will have semantic values +that are sets (actually multisets) of possible actions. The parser +tries to pick one of the actions by first finding one whose rule has +the highest dynamic precedence, as set by the `%dprec' declaration. +Otherwise, if the alternative actions are not ordered by precedence, +but there the same merging function is declared for both rules by the +`%merge' declaration, Bison resolves and evaluates both and then calls +the merge function on the result. Otherwise, it reports an ambiguity. + + It is possible to use a data structure for the GLR parsing tree that +permits the processing of any LALR(1) grammar in linear time (in the +size of the input), any unambiguous (not necessarily LALR(1)) grammar in +quadratic worst-case time, and any general (possibly ambiguous) +context-free grammar in cubic worst-case time. However, Bison currently +uses a simpler data structure that requires time proportional to the +length of the input times the maximum number of stacks required for any +prefix of the input. Thus, really ambiguous or nondeterministic +grammars can require exponential time and space to process. Such badly +behaving examples, however, are not generally of practical interest. +Usually, nondeterminism in a grammar is local--the parser is "in doubt" +only for a few tokens at a time. Therefore, the current data structure +should generally be adequate. On LALR(1) portions of a grammar, in +particular, it is only slightly slower than with the default Bison +parser. + + For a more detailed exposition of GLR parsers, please see: Elizabeth +Scott, Adrian Johnstone and Shamsa Sadaf Hussain, Tomita-Style +Generalised LR Parsers, Royal Holloway, University of London, +Department of Computer Science, TR-00-12, +`http://www.cs.rhul.ac.uk/research/languages/publications/tomita_style_1.ps', +(2000-12-24). + + +File: bison.info, Node: Memory Management, Prev: Generalized LR Parsing, Up: Algorithm + +5.9 Memory Management, and How to Avoid Memory Exhaustion +========================================================= + +The Bison parser stack can run out of memory if too many tokens are +shifted and not reduced. When this happens, the parser function +`yyparse' calls `yyerror' and then returns 2. + + Because Bison parsers have growing stacks, hitting the upper limit +usually results from using a right recursion instead of a left +recursion, *Note Recursive Rules: Recursion. + + By defining the macro `YYMAXDEPTH', you can control how deep the +parser stack can become before memory is exhausted. Define the macro +with a value that is an integer. This value is the maximum number of +tokens that can be shifted (and not reduced) before overflow. + + The stack space allowed is not necessarily allocated. If you +specify a large value for `YYMAXDEPTH', the parser normally allocates a +small stack at first, and then makes it bigger by stages as needed. +This increasing allocation happens automatically and silently. +Therefore, you do not need to make `YYMAXDEPTH' painfully small merely +to save space for ordinary inputs that do not need much stack. + + However, do not allow `YYMAXDEPTH' to be a value so large that +arithmetic overflow could occur when calculating the size of the stack +space. Also, do not allow `YYMAXDEPTH' to be less than `YYINITDEPTH'. + + The default value of `YYMAXDEPTH', if you do not define it, is 10000. + + You can control how much stack is allocated initially by defining the +macro `YYINITDEPTH' to a positive integer. For the C LALR(1) parser, +this value must be a compile-time constant unless you are assuming C99 +or some other target language or compiler that allows variable-length +arrays. The default is 200. + + Do not allow `YYINITDEPTH' to be greater than `YYMAXDEPTH'. + + Because of semantical differences between C and C++, the LALR(1) +parsers in C produced by Bison cannot grow when compiled by C++ +compilers. In this precise case (compiling a C parser as C++) you are +suggested to grow `YYINITDEPTH'. The Bison maintainers hope to fix +this deficiency in a future release. + + +File: bison.info, Node: Error Recovery, Next: Context Dependency, Prev: Algorithm, Up: Top + +6 Error Recovery +**************** + +It is not usually acceptable to have a program terminate on a syntax +error. For example, a compiler should recover sufficiently to parse the +rest of the input file and check it for errors; a calculator should +accept another expression. + + In a simple interactive command parser where each input is one line, +it may be sufficient to allow `yyparse' to return 1 on error and have +the caller ignore the rest of the input line when that happens (and +then call `yyparse' again). But this is inadequate for a compiler, +because it forgets all the syntactic context leading up to the error. +A syntax error deep within a function in the compiler input should not +cause the compiler to treat the following line like the beginning of a +source file. + + You can define how to recover from a syntax error by writing rules to +recognize the special token `error'. This is a terminal symbol that is +always defined (you need not declare it) and reserved for error +handling. The Bison parser generates an `error' token whenever a +syntax error happens; if you have provided a rule to recognize this +token in the current context, the parse can continue. + + For example: + + stmnts: /* empty string */ + | stmnts '\n' + | stmnts exp '\n' + | stmnts error '\n' + + The fourth rule in this example says that an error followed by a +newline makes a valid addition to any `stmnts'. + + What happens if a syntax error occurs in the middle of an `exp'? The +error recovery rule, interpreted strictly, applies to the precise +sequence of a `stmnts', an `error' and a newline. If an error occurs in +the middle of an `exp', there will probably be some additional tokens +and subexpressions on the stack after the last `stmnts', and there will +be tokens to read before the next newline. So the rule is not +applicable in the ordinary way. + + But Bison can force the situation to fit the rule, by discarding +part of the semantic context and part of the input. First it discards +states and objects from the stack until it gets back to a state in +which the `error' token is acceptable. (This means that the +subexpressions already parsed are discarded, back to the last complete +`stmnts'.) At this point the `error' token can be shifted. Then, if +the old lookahead token is not acceptable to be shifted next, the +parser reads tokens and discards them until it finds a token which is +acceptable. In this example, Bison reads and discards input until the +next newline so that the fourth rule can apply. Note that discarded +symbols are possible sources of memory leaks, see *Note Freeing +Discarded Symbols: Destructor Decl, for a means to reclaim this memory. + + The choice of error rules in the grammar is a choice of strategies +for error recovery. A simple and useful strategy is simply to skip the +rest of the current input line or current statement if an error is +detected: + + stmnt: error ';' /* On error, skip until ';' is read. */ + + It is also useful to recover to the matching close-delimiter of an +opening-delimiter that has already been parsed. Otherwise the +close-delimiter will probably appear to be unmatched, and generate +another, spurious error message: + + primary: '(' expr ')' + | '(' error ')' + ... + ; + + Error recovery strategies are necessarily guesses. When they guess +wrong, one syntax error often leads to another. In the above example, +the error recovery rule guesses that an error is due to bad input +within one `stmnt'. Suppose that instead a spurious semicolon is +inserted in the middle of a valid `stmnt'. After the error recovery +rule recovers from the first error, another syntax error will be found +straightaway, since the text following the spurious semicolon is also +an invalid `stmnt'. + + To prevent an outpouring of error messages, the parser will output +no error message for another syntax error that happens shortly after +the first; only after three consecutive input tokens have been +successfully shifted will error messages resume. + + Note that rules which accept the `error' token may have actions, just +as any other rules can. + + You can make error messages resume immediately by using the macro +`yyerrok' in an action. If you do this in the error rule's action, no +error messages will be suppressed. This macro requires no arguments; +`yyerrok;' is a valid C statement. + + The previous lookahead token is reanalyzed immediately after an +error. If this is unacceptable, then the macro `yyclearin' may be used +to clear this token. Write the statement `yyclearin;' in the error +rule's action. *Note Special Features for Use in Actions: Action +Features. + + For example, suppose that on a syntax error, an error handling +routine is called that advances the input stream to some point where +parsing should once again commence. The next symbol returned by the +lexical scanner is probably correct. The previous lookahead token +ought to be discarded with `yyclearin;'. + + The expression `YYRECOVERING ()' yields 1 when the parser is +recovering from a syntax error, and 0 otherwise. Syntax error +diagnostics are suppressed while recovering from a syntax error. + + +File: bison.info, Node: Context Dependency, Next: Debugging, Prev: Error Recovery, Up: Top + +7 Handling Context Dependencies +******************************* + +The Bison paradigm is to parse tokens first, then group them into larger +syntactic units. In many languages, the meaning of a token is affected +by its context. Although this violates the Bison paradigm, certain +techniques (known as "kludges") may enable you to write Bison parsers +for such languages. + +* Menu: + +* Semantic Tokens:: Token parsing can depend on the semantic context. +* Lexical Tie-ins:: Token parsing can depend on the syntactic context. +* Tie-in Recovery:: Lexical tie-ins have implications for how + error recovery rules must be written. + + (Actually, "kludge" means any technique that gets its job done but is +neither clean nor robust.) + + +File: bison.info, Node: Semantic Tokens, Next: Lexical Tie-ins, Up: Context Dependency + +7.1 Semantic Info in Token Types +================================ + +The C language has a context dependency: the way an identifier is used +depends on what its current meaning is. For example, consider this: + + foo (x); + + This looks like a function call statement, but if `foo' is a typedef +name, then this is actually a declaration of `x'. How can a Bison +parser for C decide how to parse this input? + + The method used in GNU C is to have two different token types, +`IDENTIFIER' and `TYPENAME'. When `yylex' finds an identifier, it +looks up the current declaration of the identifier in order to decide +which token type to return: `TYPENAME' if the identifier is declared as +a typedef, `IDENTIFIER' otherwise. + + The grammar rules can then express the context dependency by the +choice of token type to recognize. `IDENTIFIER' is accepted as an +expression, but `TYPENAME' is not. `TYPENAME' can start a declaration, +but `IDENTIFIER' cannot. In contexts where the meaning of the +identifier is _not_ significant, such as in declarations that can +shadow a typedef name, either `TYPENAME' or `IDENTIFIER' is +accepted--there is one rule for each of the two token types. + + This technique is simple to use if the decision of which kinds of +identifiers to allow is made at a place close to where the identifier is +parsed. But in C this is not always so: C allows a declaration to +redeclare a typedef name provided an explicit type has been specified +earlier: + + typedef int foo, bar; + int baz (void) + { + static bar (bar); /* redeclare `bar' as static variable */ + extern foo foo (foo); /* redeclare `foo' as function */ + return foo (bar); + } + + Unfortunately, the name being declared is separated from the +declaration construct itself by a complicated syntactic structure--the +"declarator". + + As a result, part of the Bison parser for C needs to be duplicated, +with all the nonterminal names changed: once for parsing a declaration +in which a typedef name can be redefined, and once for parsing a +declaration in which that can't be done. Here is a part of the +duplication, with actions omitted for brevity: + + initdcl: + declarator maybeasm '=' + init + | declarator maybeasm + ; + + notype_initdcl: + notype_declarator maybeasm '=' + init + | notype_declarator maybeasm + ; + +Here `initdcl' can redeclare a typedef name, but `notype_initdcl' +cannot. The distinction between `declarator' and `notype_declarator' +is the same sort of thing. + + There is some similarity between this technique and a lexical tie-in +(described next), in that information which alters the lexical analysis +is changed during parsing by other parts of the program. The +difference is here the information is global, and is used for other +purposes in the program. A true lexical tie-in has a special-purpose +flag controlled by the syntactic context. + + +File: bison.info, Node: Lexical Tie-ins, Next: Tie-in Recovery, Prev: Semantic Tokens, Up: Context Dependency + +7.2 Lexical Tie-ins +=================== + +One way to handle context-dependency is the "lexical tie-in": a flag +which is set by Bison actions, whose purpose is to alter the way tokens +are parsed. + + For example, suppose we have a language vaguely like C, but with a +special construct `hex (HEX-EXPR)'. After the keyword `hex' comes an +expression in parentheses in which all integers are hexadecimal. In +particular, the token `a1b' must be treated as an integer rather than +as an identifier if it appears in that context. Here is how you can do +it: + + %{ + int hexflag; + int yylex (void); + void yyerror (char const *); + %} + %% + ... + expr: IDENTIFIER + | constant + | HEX '(' + { hexflag = 1; } + expr ')' + { hexflag = 0; + $$ = $4; } + | expr '+' expr + { $$ = make_sum ($1, $3); } + ... + ; + + constant: + INTEGER + | STRING + ; + +Here we assume that `yylex' looks at the value of `hexflag'; when it is +nonzero, all integers are parsed in hexadecimal, and tokens starting +with letters are parsed as integers if possible. + + The declaration of `hexflag' shown in the prologue of the parser file +is needed to make it accessible to the actions (*note The Prologue: +Prologue.). You must also write the code in `yylex' to obey the flag. + + +File: bison.info, Node: Tie-in Recovery, Prev: Lexical Tie-ins, Up: Context Dependency + +7.3 Lexical Tie-ins and Error Recovery +====================================== + +Lexical tie-ins make strict demands on any error recovery rules you +have. *Note Error Recovery::. + + The reason for this is that the purpose of an error recovery rule is +to abort the parsing of one construct and resume in some larger +construct. For example, in C-like languages, a typical error recovery +rule is to skip tokens until the next semicolon, and then start a new +statement, like this: + + stmt: expr ';' + | IF '(' expr ')' stmt { ... } + ... + error ';' + { hexflag = 0; } + ; + + If there is a syntax error in the middle of a `hex (EXPR)' +construct, this error rule will apply, and then the action for the +completed `hex (EXPR)' will never run. So `hexflag' would remain set +for the entire rest of the input, or until the next `hex' keyword, +causing identifiers to be misinterpreted as integers. + + To avoid this problem the error recovery rule itself clears +`hexflag'. + + There may also be an error recovery rule that works within +expressions. For example, there could be a rule which applies within +parentheses and skips to the close-parenthesis: + + expr: ... + | '(' expr ')' + { $$ = $2; } + | '(' error ')' + ... + + If this rule acts within the `hex' construct, it is not going to +abort that construct (since it applies to an inner level of parentheses +within the construct). Therefore, it should not clear the flag: the +rest of the `hex' construct should be parsed with the flag still in +effect. + + What if there is an error recovery rule which might abort out of the +`hex' construct or might not, depending on circumstances? There is no +way you can write the action to determine whether a `hex' construct is +being aborted or not. So if you are using a lexical tie-in, you had +better make sure your error recovery rules are not of this kind. Each +rule must be such that you can be sure that it always will, or always +won't, have to clear the flag. + + +File: bison.info, Node: Debugging, Next: Invocation, Prev: Context Dependency, Up: Top + +8 Debugging Your Parser +*********************** + +Developing a parser can be a challenge, especially if you don't +understand the algorithm (*note The Bison Parser Algorithm: +Algorithm.). Even so, sometimes a detailed description of the automaton +can help (*note Understanding Your Parser: Understanding.), or tracing +the execution of the parser can give some insight on why it behaves +improperly (*note Tracing Your Parser: Tracing.). + +* Menu: + +* Understanding:: Understanding the structure of your parser. +* Tracing:: Tracing the execution of your parser. + + +File: bison.info, Node: Understanding, Next: Tracing, Up: Debugging + +8.1 Understanding Your Parser +============================= + +As documented elsewhere (*note The Bison Parser Algorithm: Algorithm.) +Bison parsers are "shift/reduce automata". In some cases (much more +frequent than one would hope), looking at this automaton is required to +tune or simply fix a parser. Bison provides two different +representation of it, either textually or graphically (as a DOT file). + + The textual file is generated when the options `--report' or +`--verbose' are specified, see *Note Invoking Bison: Invocation. Its +name is made by removing `.tab.c' or `.c' from the parser output file +name, and adding `.output' instead. Therefore, if the input file is +`foo.y', then the parser file is called `foo.tab.c' by default. As a +consequence, the verbose output file is called `foo.output'. + + The following grammar file, `calc.y', will be used in the sequel: + + %token NUM STR + %left '+' '-' + %left '*' + %% + exp: exp '+' exp + | exp '-' exp + | exp '*' exp + | exp '/' exp + | NUM + ; + useless: STR; + %% + + `bison' reports: + + calc.y: warning: 1 nonterminal and 1 rule useless in grammar + calc.y:11.1-7: warning: nonterminal useless in grammar: useless + calc.y:11.10-12: warning: rule useless in grammar: useless: STR + calc.y: conflicts: 7 shift/reduce + + When given `--report=state', in addition to `calc.tab.c', it creates +a file `calc.output' with contents detailed below. The order of the +output and the exact presentation might vary, but the interpretation is +the same. + + The first section includes details on conflicts that were solved +thanks to precedence and/or associativity: + + Conflict in state 8 between rule 2 and token '+' resolved as reduce. + Conflict in state 8 between rule 2 and token '-' resolved as reduce. + Conflict in state 8 between rule 2 and token '*' resolved as shift. +... + + +The next section lists states that still have conflicts. + + State 8 conflicts: 1 shift/reduce + State 9 conflicts: 1 shift/reduce + State 10 conflicts: 1 shift/reduce + State 11 conflicts: 4 shift/reduce + +The next section reports useless tokens, nonterminal and rules. Useless +nonterminals and rules are removed in order to produce a smaller parser, +but useless tokens are preserved, since they might be used by the +scanner (note the difference between "useless" and "unused" below): + + Nonterminals useless in grammar: + useless + + Terminals unused in grammar: + STR + + Rules useless in grammar: + #6 useless: STR; + +The next section reproduces the exact grammar that Bison used: + + Grammar + + Number, Line, Rule + 0 5 $accept -> exp $end + 1 5 exp -> exp '+' exp + 2 6 exp -> exp '-' exp + 3 7 exp -> exp '*' exp + 4 8 exp -> exp '/' exp + 5 9 exp -> NUM + +and reports the uses of the symbols: + + Terminals, with rules where they appear + + $end (0) 0 + '*' (42) 3 + '+' (43) 1 + '-' (45) 2 + '/' (47) 4 + error (256) + NUM (258) 5 + + Nonterminals, with rules where they appear + + $accept (8) + on left: 0 + exp (9) + on left: 1 2 3 4 5, on right: 0 1 2 3 4 + +Bison then proceeds onto the automaton itself, describing each state +with it set of "items", also known as "pointed rules". Each item is a +production rule together with a point (marked by `.') that the input +cursor. + + state 0 + + $accept -> . exp $ (rule 0) + + NUM shift, and go to state 1 + + exp go to state 2 + + This reads as follows: "state 0 corresponds to being at the very +beginning of the parsing, in the initial rule, right before the start +symbol (here, `exp'). When the parser returns to this state right +after having reduced a rule that produced an `exp', the control flow +jumps to state 2. If there is no such transition on a nonterminal +symbol, and the lookahead is a `NUM', then this token is shifted on the +parse stack, and the control flow jumps to state 1. Any other +lookahead triggers a syntax error." + + Even though the only active rule in state 0 seems to be rule 0, the +report lists `NUM' as a lookahead token because `NUM' can be at the +beginning of any rule deriving an `exp'. By default Bison reports the +so-called "core" or "kernel" of the item set, but if you want to see +more detail you can invoke `bison' with `--report=itemset' to list all +the items, include those that can be derived: + + state 0 + + $accept -> . exp $ (rule 0) + exp -> . exp '+' exp (rule 1) + exp -> . exp '-' exp (rule 2) + exp -> . exp '*' exp (rule 3) + exp -> . exp '/' exp (rule 4) + exp -> . NUM (rule 5) + + NUM shift, and go to state 1 + + exp go to state 2 + +In the state 1... + + state 1 + + exp -> NUM . (rule 5) + + $default reduce using rule 5 (exp) + +the rule 5, `exp: NUM;', is completed. Whatever the lookahead token +(`$default'), the parser will reduce it. If it was coming from state +0, then, after this reduction it will return to state 0, and will jump +to state 2 (`exp: go to state 2'). + + state 2 + + $accept -> exp . $ (rule 0) + exp -> exp . '+' exp (rule 1) + exp -> exp . '-' exp (rule 2) + exp -> exp . '*' exp (rule 3) + exp -> exp . '/' exp (rule 4) + + $ shift, and go to state 3 + '+' shift, and go to state 4 + '-' shift, and go to state 5 + '*' shift, and go to state 6 + '/' shift, and go to state 7 + +In state 2, the automaton can only shift a symbol. For instance, +because of the item `exp -> exp . '+' exp', if the lookahead if `+', it +will be shifted on the parse stack, and the automaton control will jump +to state 4, corresponding to the item `exp -> exp '+' . exp'. Since +there is no default action, any other token than those listed above +will trigger a syntax error. + + The state 3 is named the "final state", or the "accepting state": + + state 3 + + $accept -> exp $ . (rule 0) + + $default accept + +the initial rule is completed (the start symbol and the end of input +were read), the parsing exits successfully. + + The interpretation of states 4 to 7 is straightforward, and is left +to the reader. + + state 4 + + exp -> exp '+' . exp (rule 1) + + NUM shift, and go to state 1 + + exp go to state 8 + + state 5 + + exp -> exp '-' . exp (rule 2) + + NUM shift, and go to state 1 + + exp go to state 9 + + state 6 + + exp -> exp '*' . exp (rule 3) + + NUM shift, and go to state 1 + + exp go to state 10 + + state 7 + + exp -> exp '/' . exp (rule 4) + + NUM shift, and go to state 1 + + exp go to state 11 + + As was announced in beginning of the report, `State 8 conflicts: 1 +shift/reduce': + + state 8 + + exp -> exp . '+' exp (rule 1) + exp -> exp '+' exp . (rule 1) + exp -> exp . '-' exp (rule 2) + exp -> exp . '*' exp (rule 3) + exp -> exp . '/' exp (rule 4) + + '*' shift, and go to state 6 + '/' shift, and go to state 7 + + '/' [reduce using rule 1 (exp)] + $default reduce using rule 1 (exp) + + Indeed, there are two actions associated to the lookahead `/': +either shifting (and going to state 7), or reducing rule 1. The +conflict means that either the grammar is ambiguous, or the parser lacks +information to make the right decision. Indeed the grammar is +ambiguous, as, since we did not specify the precedence of `/', the +sentence `NUM + NUM / NUM' can be parsed as `NUM + (NUM / NUM)', which +corresponds to shifting `/', or as `(NUM + NUM) / NUM', which +corresponds to reducing rule 1. + + Because in LALR(1) parsing a single decision can be made, Bison +arbitrarily chose to disable the reduction, see *Note Shift/Reduce +Conflicts: Shift/Reduce. Discarded actions are reported in between +square brackets. + + Note that all the previous states had a single possible action: +either shifting the next token and going to the corresponding state, or +reducing a single rule. In the other cases, i.e., when shifting _and_ +reducing is possible or when _several_ reductions are possible, the +lookahead is required to select the action. State 8 is one such state: +if the lookahead is `*' or `/' then the action is shifting, otherwise +the action is reducing rule 1. In other words, the first two items, +corresponding to rule 1, are not eligible when the lookahead token is +`*', since we specified that `*' has higher precedence than `+'. More +generally, some items are eligible only with some set of possible +lookahead tokens. When run with `--report=lookahead', Bison specifies +these lookahead tokens: + + state 8 + + exp -> exp . '+' exp (rule 1) + exp -> exp '+' exp . [$, '+', '-', '/'] (rule 1) + exp -> exp . '-' exp (rule 2) + exp -> exp . '*' exp (rule 3) + exp -> exp . '/' exp (rule 4) + + '*' shift, and go to state 6 + '/' shift, and go to state 7 + + '/' [reduce using rule 1 (exp)] + $default reduce using rule 1 (exp) + + The remaining states are similar: + + state 9 + + exp -> exp . '+' exp (rule 1) + exp -> exp . '-' exp (rule 2) + exp -> exp '-' exp . (rule 2) + exp -> exp . '*' exp (rule 3) + exp -> exp . '/' exp (rule 4) + + '*' shift, and go to state 6 + '/' shift, and go to state 7 + + '/' [reduce using rule 2 (exp)] + $default reduce using rule 2 (exp) + + state 10 + + exp -> exp . '+' exp (rule 1) + exp -> exp . '-' exp (rule 2) + exp -> exp . '*' exp (rule 3) + exp -> exp '*' exp . (rule 3) + exp -> exp . '/' exp (rule 4) + + '/' shift, and go to state 7 + + '/' [reduce using rule 3 (exp)] + $default reduce using rule 3 (exp) + + state 11 + + exp -> exp . '+' exp (rule 1) + exp -> exp . '-' exp (rule 2) + exp -> exp . '*' exp (rule 3) + exp -> exp . '/' exp (rule 4) + exp -> exp '/' exp . (rule 4) + + '+' shift, and go to state 4 + '-' shift, and go to state 5 + '*' shift, and go to state 6 + '/' shift, and go to state 7 + + '+' [reduce using rule 4 (exp)] + '-' [reduce using rule 4 (exp)] + '*' [reduce using rule 4 (exp)] + '/' [reduce using rule 4 (exp)] + $default reduce using rule 4 (exp) + +Observe that state 11 contains conflicts not only due to the lack of +precedence of `/' with respect to `+', `-', and `*', but also because +the associativity of `/' is not specified. + + +File: bison.info, Node: Tracing, Prev: Understanding, Up: Debugging + +8.2 Tracing Your Parser +======================= + +If a Bison grammar compiles properly but doesn't do what you want when +it runs, the `yydebug' parser-trace feature can help you figure out why. + + There are several means to enable compilation of trace facilities: + +the macro `YYDEBUG' + Define the macro `YYDEBUG' to a nonzero value when you compile the + parser. This is compliant with POSIX Yacc. You could use + `-DYYDEBUG=1' as a compiler option or you could put `#define + YYDEBUG 1' in the prologue of the grammar file (*note The + Prologue: Prologue.). + +the option `-t', `--debug' + Use the `-t' option when you run Bison (*note Invoking Bison: + Invocation.). This is POSIX compliant too. + +the directive `%debug' + Add the `%debug' directive (*note Bison Declaration Summary: Decl + Summary.). This is a Bison extension, which will prove useful + when Bison will output parsers for languages that don't use a + preprocessor. Unless POSIX and Yacc portability matter to you, + this is the preferred solution. + + We suggest that you always enable the debug option so that debugging +is always possible. + + The trace facility outputs messages with macro calls of the form +`YYFPRINTF (stderr, FORMAT, ARGS)' where FORMAT and ARGS are the usual +`printf' format and variadic arguments. If you define `YYDEBUG' to a +nonzero value but do not define `YYFPRINTF', `<stdio.h>' is +automatically included and `YYFPRINTF' is defined to `fprintf'. + + Once you have compiled the program with trace facilities, the way to +request a trace is to store a nonzero value in the variable `yydebug'. +You can do this by making the C code do it (in `main', perhaps), or you +can alter the value with a C debugger. + + Each step taken by the parser when `yydebug' is nonzero produces a +line or two of trace information, written on `stderr'. The trace +messages tell you these things: + + * Each time the parser calls `yylex', what kind of token was read. + + * Each time a token is shifted, the depth and complete contents of + the state stack (*note Parser States::). + + * Each time a rule is reduced, which rule it is, and the complete + contents of the state stack afterward. + + To make sense of this information, it helps to refer to the listing +file produced by the Bison `-v' option (*note Invoking Bison: +Invocation.). This file shows the meaning of each state in terms of +positions in various rules, and also what each state will do with each +possible input token. As you read the successive trace messages, you +can see that the parser is functioning according to its specification in +the listing file. Eventually you will arrive at the place where +something undesirable happens, and you will see which parts of the +grammar are to blame. + + The parser file is a C program and you can use C debuggers on it, +but it's not easy to interpret what it is doing. The parser function +is a finite-state machine interpreter, and aside from the actions it +executes the same code over and over. Only the values of variables +show where in the grammar it is working. + + The debugging information normally gives the token type of each token +read, but not its semantic value. You can optionally define a macro +named `YYPRINT' to provide a way to print the value. If you define +`YYPRINT', it should take three arguments. The parser will pass a +standard I/O stream, the numeric code for the token type, and the token +value (from `yylval'). + + Here is an example of `YYPRINT' suitable for the multi-function +calculator (*note Declarations for `mfcalc': Mfcalc Declarations.): + + %{ + static void print_token_value (FILE *, int, YYSTYPE); + #define YYPRINT(file, type, value) print_token_value (file, type, value) + %} + + ... %% ... %% ... + + static void + print_token_value (FILE *file, int type, YYSTYPE value) + { + if (type == VAR) + fprintf (file, "%s", value.tptr->name); + else if (type == NUM) + fprintf (file, "%d", value.val); + } + + +File: bison.info, Node: Invocation, Next: Other Languages, Prev: Debugging, Up: Top + +9 Invoking Bison +**************** + +The usual way to invoke Bison is as follows: + + bison INFILE + + Here INFILE is the grammar file name, which usually ends in `.y'. +The parser file's name is made by replacing the `.y' with `.tab.c' and +removing any leading directory. Thus, the `bison foo.y' file name +yields `foo.tab.c', and the `bison hack/foo.y' file name yields +`foo.tab.c'. It's also possible, in case you are writing C++ code +instead of C in your grammar file, to name it `foo.ypp' or `foo.y++'. +Then, the output files will take an extension like the given one as +input (respectively `foo.tab.cpp' and `foo.tab.c++'). This feature +takes effect with all options that manipulate file names like `-o' or +`-d'. + + For example : + + bison -d INFILE.YXX + will produce `infile.tab.cxx' and `infile.tab.hxx', and + + bison -d -o OUTPUT.C++ INFILE.Y + will produce `output.c++' and `outfile.h++'. + + For compatibility with POSIX, the standard Bison distribution also +contains a shell script called `yacc' that invokes Bison with the `-y' +option. + +* Menu: + +* Bison Options:: All the options described in detail, + in alphabetical order by short options. +* Option Cross Key:: Alphabetical list of long options. +* Yacc Library:: Yacc-compatible `yylex' and `main'. + + +File: bison.info, Node: Bison Options, Next: Option Cross Key, Up: Invocation + +9.1 Bison Options +================= + +Bison supports both traditional single-letter options and mnemonic long +option names. Long option names are indicated with `--' instead of +`-'. Abbreviations for option names are allowed as long as they are +unique. When a long option takes an argument, like `--file-prefix', +connect the option name and the argument with `='. + + Here is a list of options that can be used with Bison, alphabetized +by short option. It is followed by a cross key alphabetized by long +option. + +Operations modes: +`-h' +`--help' + Print a summary of the command-line options to Bison and exit. + +`-V' +`--version' + Print the version number of Bison and exit. + +`--print-localedir' + Print the name of the directory containing locale-dependent data. + +`--print-datadir' + Print the name of the directory containing skeletons and XSLT. + +`-y' +`--yacc' + Act more like the traditional Yacc command. This can cause + different diagnostics to be generated, and may change behavior in + other minor ways. Most importantly, imitate Yacc's output file + name conventions, so that the parser output file is called + `y.tab.c', and the other outputs are called `y.output' and + `y.tab.h'. Also, if generating an LALR(1) parser in C, generate + `#define' statements in addition to an `enum' to associate token + numbers with token names. Thus, the following shell script can + substitute for Yacc, and the Bison distribution contains such a + script for compatibility with POSIX: + + #! /bin/sh + bison -y "$@" + + The `-y'/`--yacc' option is intended for use with traditional Yacc + grammars. If your grammar uses a Bison extension like + `%glr-parser', Bison might not be Yacc-compatible even if this + option is specified. + +`-W' +`--warnings' + Output warnings falling in CATEGORY. CATEGORY can be one of: + `midrule-values' + Warn about mid-rule values that are set but not used within + any of the actions of the parent rule. For example, warn + about unused `$2' in: + + exp: '1' { $$ = 1; } '+' exp { $$ = $1 + $4; }; + + Also warn about mid-rule values that are used but not set. + For example, warn about unset `$$' in the mid-rule action in: + + exp: '1' { $1 = 1; } '+' exp { $$ = $2 + $4; }; + + These warnings are not enabled by default since they + sometimes prove to be false alarms in existing grammars + employing the Yacc constructs `$0' or `$-N' (where N is some + positive integer). + + `yacc' + Incompatibilities with POSIX Yacc. + + `all' + All the warnings. + + `none' + Turn off all the warnings. + + `error' + Treat warnings as errors. + + A category can be turned off by prefixing its name with `no-'. For + instance, `-Wno-syntax' will hide the warnings about unused + variables. + +Tuning the parser: + +`-t' +`--debug' + In the parser file, define the macro `YYDEBUG' to 1 if it is not + already defined, so that the debugging facilities are compiled. + *Note Tracing Your Parser: Tracing. + +`-L LANGUAGE' +`--language=LANGUAGE' + Specify the programming language for the generated parser, as if + `%language' was specified (*note Bison Declaration Summary: Decl + Summary.). Currently supported languages include C, C++, and Java. + LANGUAGE is case-insensitive. + + This option is experimental and its effect may be modified in + future releases. + +`--locations' + Pretend that `%locations' was specified. *Note Decl Summary::. + +`-p PREFIX' +`--name-prefix=PREFIX' + Pretend that `%name-prefix "PREFIX"' was specified. *Note Decl + Summary::. + +`-l' +`--no-lines' + Don't put any `#line' preprocessor commands in the parser file. + Ordinarily Bison puts them in the parser file so that the C + compiler and debuggers will associate errors with your source + file, the grammar file. This option causes them to associate + errors with the parser file, treating it as an independent source + file in its own right. + +`-S FILE' +`--skeleton=FILE' + Specify the skeleton to use, similar to `%skeleton' (*note Bison + Declaration Summary: Decl Summary.). + + If FILE does not contain a `/', FILE is the name of a skeleton + file in the Bison installation directory. If it does, FILE is an + absolute file name or a file name relative to the current working + directory. This is similar to how most shells resolve commands. + +`-k' +`--token-table' + Pretend that `%token-table' was specified. *Note Decl Summary::. + +Adjust the output: + +`--defines[=FILE]' + Pretend that `%defines' was specified, i.e., write an extra output + file containing macro definitions for the token type names defined + in the grammar, as well as a few other declarations. *Note Decl + Summary::. + +`-d' + This is the same as `--defines' except `-d' does not accept a FILE + argument since POSIX Yacc requires that `-d' can be bundled with + other short options. + +`-b FILE-PREFIX' +`--file-prefix=PREFIX' + Pretend that `%file-prefix' was specified, i.e., specify prefix to + use for all Bison output file names. *Note Decl Summary::. + +`-r THINGS' +`--report=THINGS' + Write an extra output file containing verbose description of the + comma separated list of THINGS among: + + `state' + Description of the grammar, conflicts (resolved and + unresolved), and LALR automaton. + + `lookahead' + Implies `state' and augments the description of the automaton + with each rule's lookahead set. + + `itemset' + Implies `state' and augments the description of the automaton + with the full set of items for each state, instead of its + core only. + +`--report-file=FILE' + Specify the FILE for the verbose description. + +`-v' +`--verbose' + Pretend that `%verbose' was specified, i.e., write an extra output + file containing verbose descriptions of the grammar and parser. + *Note Decl Summary::. + +`-o FILE' +`--output=FILE' + Specify the FILE for the parser file. + + The other output files' names are constructed from FILE as + described under the `-v' and `-d' options. + +`-g[FILE]' +`--graph[=FILE]' + Output a graphical representation of the LALR(1) grammar automaton + computed by Bison, in Graphviz (http://www.graphviz.org/) DOT + (http://www.graphviz.org/doc/info/lang.html) format. `FILE' is + optional. If omitted and the grammar file is `foo.y', the output + file will be `foo.dot'. + +`-x[FILE]' +`--xml[=FILE]' + Output an XML report of the LALR(1) automaton computed by Bison. + `FILE' is optional. If omitted and the grammar file is `foo.y', + the output file will be `foo.xml'. (The current XML schema is + experimental and may evolve. More user feedback will help to + stabilize it.) + + +File: bison.info, Node: Option Cross Key, Next: Yacc Library, Prev: Bison Options, Up: Invocation + +9.2 Option Cross Key +==================== + +Here is a list of options, alphabetized by long option, to help you find +the corresponding short option. + +Long Option Short Option +------------------------------------------------- +`--debug' `-t' +`--defines=[FILE]' +`--file-prefix=PREFIX' `-b' PREFIX +`--graph=[FILE]' `-g' [FILE] +`--help' `-h' +`--language=LANGUAGE' `-L' LANGUAGE +`--locations' +`--name-prefix=PREFIX' `-p' PREFIX +`--no-lines' `-l' +`--output=FILE' `-o' FILE +`--print-datadir' +`--print-localedir' +`--report-file=FILE' +`--report=THINGS' `-r' THINGS +`--skeleton=FILE' `-S' FILE +`--token-table' `-k' +`--verbose' `-v' +`--version' `-V' +`--warnings' `-W' +`--xml=[FILE]' `-x' [FILE] +`--yacc' `-y' + + +File: bison.info, Node: Yacc Library, Prev: Option Cross Key, Up: Invocation + +9.3 Yacc Library +================ + +The Yacc library contains default implementations of the `yyerror' and +`main' functions. These default implementations are normally not +useful, but POSIX requires them. To use the Yacc library, link your +program with the `-ly' option. Note that Bison's implementation of the +Yacc library is distributed under the terms of the GNU General Public +License (*note Copying::). + + If you use the Yacc library's `yyerror' function, you should declare +`yyerror' as follows: + + int yyerror (char const *); + + Bison ignores the `int' value returned by this `yyerror'. If you +use the Yacc library's `main' function, your `yyparse' function should +have the following type signature: + + int yyparse (void); + + +File: bison.info, Node: Other Languages, Next: FAQ, Prev: Invocation, Up: Top + +10 Parsers Written In Other Languages +************************************* + +* Menu: + +* C++ Parsers:: The interface to generate C++ parser classes +* Java Parsers:: The interface to generate Java parser classes + + +File: bison.info, Node: C++ Parsers, Next: Java Parsers, Up: Other Languages + +10.1 C++ Parsers +================ + +* Menu: + +* C++ Bison Interface:: Asking for C++ parser generation +* C++ Semantic Values:: %union vs. C++ +* C++ Location Values:: The position and location classes +* C++ Parser Interface:: Instantiating and running the parser +* C++ Scanner Interface:: Exchanges between yylex and parse +* A Complete C++ Example:: Demonstrating their use + + +File: bison.info, Node: C++ Bison Interface, Next: C++ Semantic Values, Up: C++ Parsers + +10.1.1 C++ Bison Interface +-------------------------- + +The C++ LALR(1) parser is selected using the skeleton directive, +`%skeleton "lalr1.c"', or the synonymous command-line option +`--skeleton=lalr1.c'. *Note Decl Summary::. + + When run, `bison' will create several entities in the `yy' namespace. Use +the `%define namespace' directive to change the namespace name, see +*Note Decl Summary::. The various classes are generated in the +following files: + +`position.hh' +`location.hh' + The definition of the classes `position' and `location', used for + location tracking. *Note C++ Location Values::. + +`stack.hh' + An auxiliary class `stack' used by the parser. + +`FILE.hh' +`FILE.cc' + (Assuming the extension of the input file was `.yy'.) The + declaration and implementation of the C++ parser class. The + basename and extension of these two files follow the same rules as + with regular C parsers (*note Invocation::). + + The header is _mandatory_; you must either pass `-d'/`--defines' + to `bison', or use the `%defines' directive. + + All these files are documented using Doxygen; run `doxygen' for a +complete and accurate documentation. + + +File: bison.info, Node: C++ Semantic Values, Next: C++ Location Values, Prev: C++ Bison Interface, Up: C++ Parsers + +10.1.2 C++ Semantic Values +-------------------------- + +The `%union' directive works as for C, see *Note The Collection of +Value Types: Union Decl. In particular it produces a genuine +`union'(1), which have a few specific features in C++. + - The type `YYSTYPE' is defined but its use is discouraged: rather + you should refer to the parser's encapsulated type + `yy::parser::semantic_type'. + + - Non POD (Plain Old Data) types cannot be used. C++ forbids any + instance of classes with constructors in unions: only _pointers_ + to such objects are allowed. + + Because objects have to be stored via pointers, memory is not +reclaimed automatically: using the `%destructor' directive is the only +means to avoid leaks. *Note Freeing Discarded Symbols: Destructor Decl. + + ---------- Footnotes ---------- + + (1) In the future techniques to allow complex types within +pseudo-unions (similar to Boost variants) might be implemented to +alleviate these issues. + + +File: bison.info, Node: C++ Location Values, Next: C++ Parser Interface, Prev: C++ Semantic Values, Up: C++ Parsers + +10.1.3 C++ Location Values +-------------------------- + +When the directive `%locations' is used, the C++ parser supports +location tracking, see *Note Locations Overview: Locations. Two +auxiliary classes define a `position', a single point in a file, and a +`location', a range composed of a pair of `position's (possibly +spanning several files). + + -- Method on position: std::string* file + The name of the file. It will always be handled as a pointer, the + parser will never duplicate nor deallocate it. As an experimental + feature you may change it to `TYPE*' using `%define filename_type + "TYPE"'. + + -- Method on position: unsigned int line + The line, starting at 1. + + -- Method on position: unsigned int lines (int HEIGHT = 1) + Advance by HEIGHT lines, resetting the column number. + + -- Method on position: unsigned int column + The column, starting at 0. + + -- Method on position: unsigned int columns (int WIDTH = 1) + Advance by WIDTH columns, without changing the line number. + + -- Method on position: position& operator+= (position& POS, int WIDTH) + -- Method on position: position operator+ (const position& POS, int + WIDTH) + -- Method on position: position& operator-= (const position& POS, int + WIDTH) + -- Method on position: position operator- (position& POS, int WIDTH) + Various forms of syntactic sugar for `columns'. + + -- Method on position: position operator<< (std::ostream O, const + position& P) + Report P on O like this: `FILE:LINE.COLUMN', or `LINE.COLUMN' if + FILE is null. + + -- Method on location: position begin + -- Method on location: position end + The first, inclusive, position of the range, and the first beyond. + + -- Method on location: unsigned int columns (int WIDTH = 1) + -- Method on location: unsigned int lines (int HEIGHT = 1) + Advance the `end' position. + + -- Method on location: location operator+ (const location& BEGIN, + const location& END) + -- Method on location: location operator+ (const location& BEGIN, int + WIDTH) + -- Method on location: location operator+= (const location& LOC, int + WIDTH) + Various forms of syntactic sugar. + + -- Method on location: void step () + Move `begin' onto `end'. + + +File: bison.info, Node: C++ Parser Interface, Next: C++ Scanner Interface, Prev: C++ Location Values, Up: C++ Parsers + +10.1.4 C++ Parser Interface +--------------------------- + +The output files `OUTPUT.hh' and `OUTPUT.cc' declare and define the +parser class in the namespace `yy'. The class name defaults to +`parser', but may be changed using `%define parser_class_name "NAME"'. +The interface of this class is detailed below. It can be extended +using the `%parse-param' feature: its semantics is slightly changed +since it describes an additional member of the parser class, and an +additional argument for its constructor. + + -- Type of parser: semantic_value_type + -- Type of parser: location_value_type + The types for semantics value and locations. + + -- Method on parser: parser (TYPE1 ARG1, ...) + Build a new parser object. There are no arguments by default, + unless `%parse-param {TYPE1 ARG1}' was used. + + -- Method on parser: int parse () + Run the syntactic analysis, and return 0 on success, 1 otherwise. + + -- Method on parser: std::ostream& debug_stream () + -- Method on parser: void set_debug_stream (std::ostream& O) + Get or set the stream used for tracing the parsing. It defaults to + `std::cerr'. + + -- Method on parser: debug_level_type debug_level () + -- Method on parser: void set_debug_level (debug_level L) + Get or set the tracing level. Currently its value is either 0, no + trace, or nonzero, full tracing. + + -- Method on parser: void error (const location_type& L, const + std::string& M) + The definition for this member function must be supplied by the + user: the parser uses it to report a parser error occurring at L, + described by M. + + +File: bison.info, Node: C++ Scanner Interface, Next: A Complete C++ Example, Prev: C++ Parser Interface, Up: C++ Parsers + +10.1.5 C++ Scanner Interface +---------------------------- + +The parser invokes the scanner by calling `yylex'. Contrary to C +parsers, C++ parsers are always pure: there is no point in using the +`%define api.pure' directive. Therefore the interface is as follows. + + -- Method on parser: int yylex (semantic_value_type& YYLVAL, + location_type& YYLLOC, TYPE1 ARG1, ...) + Return the next token. Its type is the return value, its semantic + value and location being YYLVAL and YYLLOC. Invocations of + `%lex-param {TYPE1 ARG1}' yield additional arguments. + + +File: bison.info, Node: A Complete C++ Example, Prev: C++ Scanner Interface, Up: C++ Parsers + +10.1.6 A Complete C++ Example +----------------------------- + +This section demonstrates the use of a C++ parser with a simple but +complete example. This example should be available on your system, +ready to compile, in the directory "../bison/examples/calc++". It +focuses on the use of Bison, therefore the design of the various C++ +classes is very naive: no accessors, no encapsulation of members etc. +We will use a Lex scanner, and more precisely, a Flex scanner, to +demonstrate the various interaction. A hand written scanner is +actually easier to interface with. + +* Menu: + +* Calc++ --- C++ Calculator:: The specifications +* Calc++ Parsing Driver:: An active parsing context +* Calc++ Parser:: A parser class +* Calc++ Scanner:: A pure C++ Flex scanner +* Calc++ Top Level:: Conducting the band + + +File: bison.info, Node: Calc++ --- C++ Calculator, Next: Calc++ Parsing Driver, Up: A Complete C++ Example + +10.1.6.1 Calc++ -- C++ Calculator +................................. + +Of course the grammar is dedicated to arithmetics, a single expression, +possibly preceded by variable assignments. An environment containing +possibly predefined variables such as `one' and `two', is exchanged +with the parser. An example of valid input follows. + + three := 3 + seven := one + two * three + seven * seven + + +File: bison.info, Node: Calc++ Parsing Driver, Next: Calc++ Parser, Prev: Calc++ --- C++ Calculator, Up: A Complete C++ Example + +10.1.6.2 Calc++ Parsing Driver +.............................. + +To support a pure interface with the parser (and the scanner) the +technique of the "parsing context" is convenient: a structure +containing all the data to exchange. Since, in addition to simply +launch the parsing, there are several auxiliary tasks to execute (open +the file for parsing, instantiate the parser etc.), we recommend +transforming the simple parsing context structure into a fully blown +"parsing driver" class. + + The declaration of this driver class, `calc++-driver.hh', is as +follows. The first part includes the CPP guard and imports the +required standard library components, and the declaration of the parser +class. + + #ifndef CALCXX_DRIVER_HH + # define CALCXX_DRIVER_HH + # include <string> + # include <map> + # include "calc++-parser.hh" + +Then comes the declaration of the scanning function. Flex expects the +signature of `yylex' to be defined in the macro `YY_DECL', and the C++ +parser expects it to be declared. We can factor both as follows. + + // Tell Flex the lexer's prototype ... + # define YY_DECL \ + yy::calcxx_parser::token_type \ + yylex (yy::calcxx_parser::semantic_type* yylval, \ + yy::calcxx_parser::location_type* yylloc, \ + calcxx_driver& driver) + // ... and declare it for the parser's sake. + YY_DECL; + +The `calcxx_driver' class is then declared with its most obvious +members. + + // Conducting the whole scanning and parsing of Calc++. + class calcxx_driver + { + public: + calcxx_driver (); + virtual ~calcxx_driver (); + + std::map<std::string, int> variables; + + int result; + +To encapsulate the coordination with the Flex scanner, it is useful to +have two members function to open and close the scanning phase. + + // Handling the scanner. + void scan_begin (); + void scan_end (); + bool trace_scanning; + +Similarly for the parser itself. + + // Run the parser. Return 0 on success. + int parse (const std::string& f); + std::string file; + bool trace_parsing; + +To demonstrate pure handling of parse errors, instead of simply dumping +them on the standard error output, we will pass them to the compiler +driver using the following two member functions. Finally, we close the +class declaration and CPP guard. + + // Error handling. + void error (const yy::location& l, const std::string& m); + void error (const std::string& m); + }; + #endif // ! CALCXX_DRIVER_HH + + The implementation of the driver is straightforward. The `parse' +member function deserves some attention. The `error' functions are +simple stubs, they should actually register the located error messages +and set error state. + + #include "calc++-driver.hh" + #include "calc++-parser.hh" + + calcxx_driver::calcxx_driver () + : trace_scanning (false), trace_parsing (false) + { + variables["one"] = 1; + variables["two"] = 2; + } + + calcxx_driver::~calcxx_driver () + { + } + + int + calcxx_driver::parse (const std::string &f) + { + file = f; + scan_begin (); + yy::calcxx_parser parser (*this); + parser.set_debug_level (trace_parsing); + int res = parser.parse (); + scan_end (); + return res; + } + + void + calcxx_driver::error (const yy::location& l, const std::string& m) + { + std::cerr << l << ": " << m << std::endl; + } + + void + calcxx_driver::error (const std::string& m) + { + std::cerr << m << std::endl; + } + + +File: bison.info, Node: Calc++ Parser, Next: Calc++ Scanner, Prev: Calc++ Parsing Driver, Up: A Complete C++ Example + +10.1.6.3 Calc++ Parser +...................... + +The parser definition file `calc++-parser.yy' starts by asking for the +C++ LALR(1) skeleton, the creation of the parser header file, and +specifies the name of the parser class. Because the C++ skeleton +changed several times, it is safer to require the version you designed +the grammar for. + + %skeleton "lalr1.cc" /* -*- C++ -*- */ + %require "2.4.1" + %defines + %define parser_class_name "calcxx_parser" + +Then come the declarations/inclusions needed to define the `%union'. +Because the parser uses the parsing driver and reciprocally, both +cannot include the header of the other. Because the driver's header +needs detailed knowledge about the parser class (in particular its +inner types), it is the parser's header which will simply use a forward +declaration of the driver. *Note %code: Decl Summary. + + %code requires { + # include <string> + class calcxx_driver; + } + +The driver is passed by reference to the parser and to the scanner. +This provides a simple but effective pure interface, not relying on +global variables. + + // The parsing context. + %parse-param { calcxx_driver& driver } + %lex-param { calcxx_driver& driver } + +Then we request the location tracking feature, and initialize the first +location's file name. Afterwards new locations are computed relatively +to the previous locations: the file name will be automatically +propagated. + + %locations + %initial-action + { + // Initialize the initial location. + @$.begin.filename = @$.end.filename = &driver.file; + }; + +Use the two following directives to enable parser tracing and verbose +error messages. + + %debug + %error-verbose + +Semantic values cannot use "real" objects, but only pointers to them. + + // Symbols. + %union + { + int ival; + std::string *sval; + }; + +The code between `%code {' and `}' is output in the `*.cc' file; it +needs detailed knowledge about the driver. + + %code { + # include "calc++-driver.hh" + } + +The token numbered as 0 corresponds to end of file; the following line +allows for nicer error messages referring to "end of file" instead of +"$end". Similarly user friendly named are provided for each symbol. +Note that the tokens names are prefixed by `TOKEN_' to avoid name +clashes. + + %token END 0 "end of file" + %token ASSIGN ":=" + %token <sval> IDENTIFIER "identifier" + %token <ival> NUMBER "number" + %type <ival> exp + +To enable memory deallocation during error recovery, use `%destructor'. + + %printer { debug_stream () << *$$; } "identifier" + %destructor { delete $$; } "identifier" + + %printer { debug_stream () << $$; } <ival> + +The grammar itself is straightforward. + + %% + %start unit; + unit: assignments exp { driver.result = $2; }; + + assignments: assignments assignment {} + | /* Nothing. */ {}; + + assignment: + "identifier" ":=" exp + { driver.variables[*$1] = $3; delete $1; }; + + %left '+' '-'; + %left '*' '/'; + exp: exp '+' exp { $$ = $1 + $3; } + | exp '-' exp { $$ = $1 - $3; } + | exp '*' exp { $$ = $1 * $3; } + | exp '/' exp { $$ = $1 / $3; } + | "identifier" { $$ = driver.variables[*$1]; delete $1; } + | "number" { $$ = $1; }; + %% + +Finally the `error' member function registers the errors to the driver. + + void + yy::calcxx_parser::error (const yy::calcxx_parser::location_type& l, + const std::string& m) + { + driver.error (l, m); + } + + +File: bison.info, Node: Calc++ Scanner, Next: Calc++ Top Level, Prev: Calc++ Parser, Up: A Complete C++ Example + +10.1.6.4 Calc++ Scanner +....................... + +The Flex scanner first includes the driver declaration, then the +parser's to get the set of defined tokens. + + %{ /* -*- C++ -*- */ + # include <cstdlib> + # include <errno.h> + # include <limits.h> + # include <string> + # include "calc++-driver.hh" + # include "calc++-parser.hh" + + /* Work around an incompatibility in flex (at least versions + 2.5.31 through 2.5.33): it generates code that does + not conform to C89. See Debian bug 333231 + <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=333231>. */ + # undef yywrap + # define yywrap() 1 + + /* By default yylex returns int, we use token_type. + Unfortunately yyterminate by default returns 0, which is + not of token_type. */ + #define yyterminate() return token::END + %} + +Because there is no `#include'-like feature we don't need `yywrap', we +don't need `unput' either, and we parse an actual file, this is not an +interactive session with the user. Finally we enable the scanner +tracing features. + + %option noyywrap nounput batch debug + +Abbreviations allow for more readable rules. + + id [a-zA-Z][a-zA-Z_0-9]* + int [0-9]+ + blank [ \t] + +The following paragraph suffices to track locations accurately. Each +time `yylex' is invoked, the begin position is moved onto the end +position. Then when a pattern is matched, the end position is advanced +of its width. In case it matched ends of lines, the end cursor is +adjusted, and each time blanks are matched, the begin cursor is moved +onto the end cursor to effectively ignore the blanks preceding tokens. +Comments would be treated equally. + + %{ + # define YY_USER_ACTION yylloc->columns (yyleng); + %} + %% + %{ + yylloc->step (); + %} + {blank}+ yylloc->step (); + [\n]+ yylloc->lines (yyleng); yylloc->step (); + +The rules are simple, just note the use of the driver to report errors. +It is convenient to use a typedef to shorten +`yy::calcxx_parser::token::identifier' into `token::identifier' for +instance. + + %{ + typedef yy::calcxx_parser::token token; + %} + /* Convert ints to the actual type of tokens. */ + [-+*/] return yy::calcxx_parser::token_type (yytext[0]); + ":=" return token::ASSIGN; + {int} { + errno = 0; + long n = strtol (yytext, NULL, 10); + if (! (INT_MIN <= n && n <= INT_MAX && errno != ERANGE)) + driver.error (*yylloc, "integer is out of range"); + yylval->ival = n; + return token::NUMBER; + } + {id} yylval->sval = new std::string (yytext); return token::IDENTIFIER; + . driver.error (*yylloc, "invalid character"); + %% + +Finally, because the scanner related driver's member function depend on +the scanner's data, it is simpler to implement them in this file. + + void + calcxx_driver::scan_begin () + { + yy_flex_debug = trace_scanning; + if (file == "-") + yyin = stdin; + else if (!(yyin = fopen (file.c_str (), "r"))) + { + error (std::string ("cannot open ") + file); + exit (1); + } + } + + void + calcxx_driver::scan_end () + { + fclose (yyin); + } + + +File: bison.info, Node: Calc++ Top Level, Prev: Calc++ Scanner, Up: A Complete C++ Example + +10.1.6.5 Calc++ Top Level +......................... + +The top level file, `calc++.cc', poses no problem. + + #include <iostream> + #include "calc++-driver.hh" + + int + main (int argc, char *argv[]) + { + calcxx_driver driver; + for (++argv; argv[0]; ++argv) + if (*argv == std::string ("-p")) + driver.trace_parsing = true; + else if (*argv == std::string ("-s")) + driver.trace_scanning = true; + else if (!driver.parse (*argv)) + std::cout << driver.result << std::endl; + } + + +File: bison.info, Node: Java Parsers, Prev: C++ Parsers, Up: Other Languages + +10.2 Java Parsers +================= + +* Menu: + +* Java Bison Interface:: Asking for Java parser generation +* Java Semantic Values:: %type and %token vs. Java +* Java Location Values:: The position and location classes +* Java Parser Interface:: Instantiating and running the parser +* Java Scanner Interface:: Specifying the scanner for the parser +* Java Action Features:: Special features for use in actions +* Java Differences:: Differences between C/C++ and Java Grammars +* Java Declarations Summary:: List of Bison declarations used with Java + + +File: bison.info, Node: Java Bison Interface, Next: Java Semantic Values, Up: Java Parsers + +10.2.1 Java Bison Interface +--------------------------- + +(The current Java interface is experimental and may evolve. More user +feedback will help to stabilize it.) + + The Java parser skeletons are selected using the `%language "Java"' +directive or the `-L java'/`--language=java' option. + + When generating a Java parser, `bison BASENAME.y' will create a +single Java source file named `BASENAME.java'. Using an input file +without a `.y' suffix is currently broken. The basename of the output +file can be changed by the `%file-prefix' directive or the +`-p'/`--name-prefix' option. The entire output file name can be +changed by the `%output' directive or the `-o'/`--output' option. The +output file contains a single class for the parser. + + You can create documentation for generated parsers using Javadoc. + + Contrary to C parsers, Java parsers do not use global variables; the +state of the parser is always local to an instance of the parser class. +Therefore, all Java parsers are "pure", and the `%pure-parser' and +`%define api.pure' directives does not do anything when used in Java. + + Push parsers are currently unsupported in Java and `%define +api.push_pull' have no effect. + + GLR parsers are currently unsupported in Java. Do not use the +`glr-parser' directive. + + No header file can be generated for Java parsers. Do not use the +`%defines' directive or the `-d'/`--defines' options. + + Currently, support for debugging and verbose errors are always +compiled in. Thus the `%debug' and `%token-table' directives and the +`-t'/`--debug' and `-k'/`--token-table' options have no effect. This +may change in the future to eliminate unused code in the generated +parser, so use `%debug' and `%verbose-error' explicitly if needed. +Also, in the future the `%token-table' directive might enable a public +interface to access the token names and codes. + + +File: bison.info, Node: Java Semantic Values, Next: Java Location Values, Prev: Java Bison Interface, Up: Java Parsers + +10.2.2 Java Semantic Values +--------------------------- + +There is no `%union' directive in Java parsers. Instead, the semantic +values' types (class names) should be specified in the `%type' or +`%token' directive: + + %type <Expression> expr assignment_expr term factor + %type <Integer> number + + By default, the semantic stack is declared to have `Object' members, +which means that the class types you specify can be of any class. To +improve the type safety of the parser, you can declare the common +superclass of all the semantic values using the `%define stype' +directive. For example, after the following declaration: + + %define stype "ASTNode" + +any `%type' or `%token' specifying a semantic type which is not a +subclass of ASTNode, will cause a compile-time error. + + Types used in the directives may be qualified with a package name. +Primitive data types are accepted for Java version 1.5 or later. Note +that in this case the autoboxing feature of Java 1.5 will be used. +Generic types may not be used; this is due to a limitation in the +implementation of Bison, and may change in future releases. + + Java parsers do not support `%destructor', since the language adopts +garbage collection. The parser will try to hold references to semantic +values for as little time as needed. + + Java parsers do not support `%printer', as `toString()' can be used +to print the semantic values. This however may change (in a +backwards-compatible way) in future versions of Bison. + + +File: bison.info, Node: Java Location Values, Next: Java Parser Interface, Prev: Java Semantic Values, Up: Java Parsers + +10.2.3 Java Location Values +--------------------------- + +When the directive `%locations' is used, the Java parser supports +location tracking, see *Note Locations Overview: Locations. An +auxiliary user-defined class defines a "position", a single point in a +file; Bison itself defines a class representing a "location", a range +composed of a pair of positions (possibly spanning several files). The +location class is an inner class of the parser; the name is `Location' +by default, and may also be renamed using `%define location_type +"CLASS-NAME'. + + The location class treats the position as a completely opaque value. +By default, the class name is `Position', but this can be changed with +`%define position_type "CLASS-NAME"'. This class must be supplied by +the user. + + -- Instance Variable of Location: Position begin + -- Instance Variable of Location: Position end + The first, inclusive, position of the range, and the first beyond. + + -- Constructor on Location: Location (Position LOC) + Create a `Location' denoting an empty range located at a given + point. + + -- Constructor on Location: Location (Position BEGIN, Position END) + Create a `Location' from the endpoints of the range. + + -- Method on Location: String toString () + Prints the range represented by the location. For this to work + properly, the position class should override the `equals' and + `toString' methods appropriately. + + +File: bison.info, Node: Java Parser Interface, Next: Java Scanner Interface, Prev: Java Location Values, Up: Java Parsers + +10.2.4 Java Parser Interface +---------------------------- + +The name of the generated parser class defaults to `YYParser'. The +`YY' prefix may be changed using the `%name-prefix' directive or the +`-p'/`--name-prefix' option. Alternatively, use `%define +parser_class_name "NAME"' to give a custom name to the class. The +interface of this class is detailed below. + + By default, the parser class has package visibility. A declaration +`%define public' will change to public visibility. Remember that, +according to the Java language specification, the name of the `.java' +file should match the name of the class in this case. Similarly, you +can use `abstract', `final' and `strictfp' with the `%define' +declaration to add other modifiers to the parser class. + + The Java package name of the parser class can be specified using the +`%define package' directive. The superclass and the implemented +interfaces of the parser class can be specified with the `%define +extends' and `%define implements' directives. + + The parser class defines an inner class, `Location', that is used +for location tracking (see *Note Java Location Values::), and a inner +interface, `Lexer' (see *Note Java Scanner Interface::). Other than +these inner class/interface, and the members described in the interface +below, all the other members and fields are preceded with a `yy' or +`YY' prefix to avoid clashes with user code. + + The parser class can be extended using the `%parse-param' directive. +Each occurrence of the directive will add a `protected final' field to +the parser class, and an argument to its constructor, which initialize +them automatically. + + Token names defined by `%token' and the predefined `EOF' token name +are added as constant fields to the parser class. + + -- Constructor on YYParser: YYParser (LEX_PARAM, ..., PARSE_PARAM, + ...) + Build a new parser object with embedded `%code lexer'. There are + no parameters, unless `%parse-param's and/or `%lex-param's are + used. + + -- Constructor on YYParser: YYParser (Lexer LEXER, PARSE_PARAM, ...) + Build a new parser object using the specified scanner. There are + no additional parameters unless `%parse-param's are used. + + If the scanner is defined by `%code lexer', this constructor is + declared `protected' and is called automatically with a scanner + created with the correct `%lex-param's. + + -- Method on YYParser: boolean parse () + Run the syntactic analysis, and return `true' on success, `false' + otherwise. + + -- Method on YYParser: boolean recovering () + During the syntactic analysis, return `true' if recovering from a + syntax error. *Note Error Recovery::. + + -- Method on YYParser: java.io.PrintStream getDebugStream () + -- Method on YYParser: void setDebugStream (java.io.printStream O) + Get or set the stream used for tracing the parsing. It defaults to + `System.err'. + + -- Method on YYParser: int getDebugLevel () + -- Method on YYParser: void setDebugLevel (int L) + Get or set the tracing level. Currently its value is either 0, no + trace, or nonzero, full tracing. + + +File: bison.info, Node: Java Scanner Interface, Next: Java Action Features, Prev: Java Parser Interface, Up: Java Parsers + +10.2.5 Java Scanner Interface +----------------------------- + +There are two possible ways to interface a Bison-generated Java parser +with a scanner: the scanner may be defined by `%code lexer', or defined +elsewhere. In either case, the scanner has to implement the `Lexer' +inner interface of the parser class. + + In the first case, the body of the scanner class is placed in `%code +lexer' blocks. If you want to pass parameters from the parser +constructor to the scanner constructor, specify them with `%lex-param'; +they are passed before `%parse-param's to the constructor. + + In the second case, the scanner has to implement the `Lexer' +interface, which is defined within the parser class (e.g., +`YYParser.Lexer'). The constructor of the parser object will then +accept an object implementing the interface; `%lex-param' is not used +in this case. + + In both cases, the scanner has to implement the following methods. + + -- Method on Lexer: void yyerror (Location LOC, String MSG) + This method is defined by the user to emit an error message. The + first parameter is omitted if location tracking is not active. + Its type can be changed using `%define location_type "CLASS-NAME".' + + -- Method on Lexer: int yylex () + Return the next token. Its type is the return value, its semantic + value and location are saved and returned by the ther methods in + the interface. + + Use `%define lex_throws' to specify any uncaught exceptions. + Default is `java.io.IOException'. + + -- Method on Lexer: Position getStartPos () + -- Method on Lexer: Position getEndPos () + Return respectively the first position of the last token that + `yylex' returned, and the first position beyond it. These methods + are not needed unless location tracking is active. + + The return type can be changed using `%define position_type + "CLASS-NAME".' + + -- Method on Lexer: Object getLVal () + Return the semantical value of the last token that yylex returned. + + The return type can be changed using `%define stype "CLASS-NAME".' + + +File: bison.info, Node: Java Action Features, Next: Java Differences, Prev: Java Scanner Interface, Up: Java Parsers + +10.2.6 Special Features for Use in Java Actions +----------------------------------------------- + +The following special constructs can be uses in Java actions. Other +analogous C action features are currently unavailable for Java. + + Use `%define throws' to specify any uncaught exceptions from parser +actions, and initial actions specified by `%initial-action'. + + -- Variable: $N + The semantic value for the Nth component of the current rule. + This may not be assigned to. *Note Java Semantic Values::. + + -- Variable: $<TYPEALT>N + Like `$N' but specifies a alternative type TYPEALT. *Note Java + Semantic Values::. + + -- Variable: $$ + The semantic value for the grouping made by the current rule. As a + value, this is in the base type (`Object' or as specified by + `%define stype') as in not cast to the declared subtype because + casts are not allowed on the left-hand side of Java assignments. + Use an explicit Java cast if the correct subtype is needed. *Note + Java Semantic Values::. + + -- Variable: $<TYPEALT>$ + Same as `$$' since Java always allow assigning to the base type. + Perhaps we should use this and `$<>$' for the value and `$$' for + setting the value but there is currently no easy way to distinguish + these constructs. *Note Java Semantic Values::. + + -- Variable: @N + The location information of the Nth component of the current rule. + This may not be assigned to. *Note Java Location Values::. + + -- Variable: @$ + The location information of the grouping made by the current rule. + *Note Java Location Values::. + + -- Statement: return YYABORT; + Return immediately from the parser, indicating failure. *Note + Java Parser Interface::. + + -- Statement: return YYACCEPT; + Return immediately from the parser, indicating success. *Note + Java Parser Interface::. + + -- Statement: return YYERROR; + Start error recovery without printing an error message. *Note + Error Recovery::. + + -- Statement: return YYFAIL; + Print an error message and start error recovery. *Note Error + Recovery::. + + -- Function: boolean recovering () + Return whether error recovery is being done. In this state, the + parser reads token until it reaches a known state, and then + restarts normal operation. *Note Error Recovery::. + + -- Function: protected void yyerror (String msg) + -- Function: protected void yyerror (Position pos, String msg) + -- Function: protected void yyerror (Location loc, String msg) + Print an error message using the `yyerror' method of the scanner + instance in use. + + +File: bison.info, Node: Java Differences, Next: Java Declarations Summary, Prev: Java Action Features, Up: Java Parsers + +10.2.7 Differences between C/C++ and Java Grammars +-------------------------------------------------- + +The different structure of the Java language forces several differences +between C/C++ grammars, and grammars designed for Java parsers. This +section summarizes these differences. + + * Java lacks a preprocessor, so the `YYERROR', `YYACCEPT', `YYABORT' + symbols (*note Table of Symbols::) cannot obviously be macros. + Instead, they should be preceded by `return' when they appear in + an action. The actual definition of these symbols is opaque to + the Bison grammar, and it might change in the future. The only + meaningful operation that you can do, is to return them. See + *note Java Action Features::. + + Note that of these three symbols, only `YYACCEPT' and `YYABORT' + will cause a return from the `yyparse' method(1). + + * Java lacks unions, so `%union' has no effect. Instead, semantic + values have a common base type: `Object' or as specified by + `%define stype'. Angle backets on `%token', `type', `$N' and `$$' + specify subtypes rather than fields of an union. The type of + `$$', even with angle brackets, is the base type since Java casts + are not allow on the left-hand side of assignments. Also, `$N' + and `@N' are not allowed on the left-hand side of assignments. See + *note Java Semantic Values:: and *note Java Action Features::. + + * The prolog declarations have a different meaning than in C/C++ + code. + `%code imports' + blocks are placed at the beginning of the Java source code. + They may include copyright notices. For a `package' + declarations, it is suggested to use `%define package' + instead. + + unqualified `%code' + blocks are placed inside the parser class. + + `%code lexer' + blocks, if specified, should include the implementation of the + scanner. If there is no such block, the scanner can be any + class that implements the appropriate interface (see *note + Java Scanner Interface::). + + Other `%code' blocks are not supported in Java parsers. In + particular, `%{ ... %}' blocks should not be used and may give an + error in future versions of Bison. + + The epilogue has the same meaning as in C/C++ code and it can be + used to define other classes used by the parser _outside_ the + parser class. + + ---------- Footnotes ---------- + + (1) Java parsers include the actions in a separate method than +`yyparse' in order to have an intuitive syntax that corresponds to +these C macros. + + +File: bison.info, Node: Java Declarations Summary, Prev: Java Differences, Up: Java Parsers + +10.2.8 Java Declarations Summary +-------------------------------- + +This summary only include declarations specific to Java or have special +meaning when used in a Java parser. + + -- Directive: %language "Java" + Generate a Java class for the parser. + + -- Directive: %lex-param {TYPE NAME} + A parameter for the lexer class defined by `%code lexer' _only_, + added as parameters to the lexer constructor and the parser + constructor that _creates_ a lexer. Default is none. *Note Java + Scanner Interface::. + + -- Directive: %name-prefix "PREFIX" + The prefix of the parser class name `PREFIXParser' if `%define + parser_class_name' is not used. Default is `YY'. *Note Java + Bison Interface::. + + -- Directive: %parse-param {TYPE NAME} + A parameter for the parser class added as parameters to + constructor(s) and as fields initialized by the constructor(s). + Default is none. *Note Java Parser Interface::. + + -- Directive: %token <TYPE> TOKEN ... + Declare tokens. Note that the angle brackets enclose a Java + _type_. *Note Java Semantic Values::. + + -- Directive: %type <TYPE> NONTERMINAL ... + Declare the type of nonterminals. Note that the angle brackets + enclose a Java _type_. *Note Java Semantic Values::. + + -- Directive: %code { CODE ... } + Code appended to the inside of the parser class. *Note Java + Differences::. + + -- Directive: %code imports { CODE ... } + Code inserted just after the `package' declaration. *Note Java + Differences::. + + -- Directive: %code lexer { CODE ... } + Code added to the body of a inner lexer class within the parser + class. *Note Java Scanner Interface::. + + -- Directive: %% CODE ... + Code (after the second `%%') appended to the end of the file, + _outside_ the parser class. *Note Java Differences::. + + -- Directive: %{ CODE ... %} + Not supported. Use `%code import' instead. *Note Java + Differences::. + + -- Directive: %define abstract + Whether the parser class is declared `abstract'. Default is false. + *Note Java Bison Interface::. + + -- Directive: %define extends "SUPERCLASS" + The superclass of the parser class. Default is none. *Note Java + Bison Interface::. + + -- Directive: %define final + Whether the parser class is declared `final'. Default is false. + *Note Java Bison Interface::. + + -- Directive: %define implements "INTERFACES" + The implemented interfaces of the parser class, a comma-separated + list. Default is none. *Note Java Bison Interface::. + + -- Directive: %define lex_throws "EXCEPTIONS" + The exceptions thrown by the `yylex' method of the lexer, a + comma-separated list. Default is `java.io.IOException'. *Note + Java Scanner Interface::. + + -- Directive: %define location_type "CLASS" + The name of the class used for locations (a range between two + positions). This class is generated as an inner class of the + parser class by `bison'. Default is `Location'. *Note Java + Location Values::. + + -- Directive: %define package "PACKAGE" + The package to put the parser class in. Default is none. *Note + Java Bison Interface::. + + -- Directive: %define parser_class_name "NAME" + The name of the parser class. Default is `YYParser' or + `NAME-PREFIXParser'. *Note Java Bison Interface::. + + -- Directive: %define position_type "CLASS" + The name of the class used for positions. This class must be + supplied by the user. Default is `Position'. *Note Java Location + Values::. + + -- Directive: %define public + Whether the parser class is declared `public'. Default is false. + *Note Java Bison Interface::. + + -- Directive: %define stype "CLASS" + The base type of semantic values. Default is `Object'. *Note + Java Semantic Values::. + + -- Directive: %define strictfp + Whether the parser class is declared `strictfp'. Default is false. + *Note Java Bison Interface::. + + -- Directive: %define throws "EXCEPTIONS" + The exceptions thrown by user-supplied parser actions and + `%initial-action', a comma-separated list. Default is none. + *Note Java Parser Interface::. + + +File: bison.info, Node: FAQ, Next: Table of Symbols, Prev: Other Languages, Up: Top + +11 Frequently Asked Questions +***************************** + +Several questions about Bison come up occasionally. Here some of them +are addressed. + +* Menu: + +* Memory Exhausted:: Breaking the Stack Limits +* How Can I Reset the Parser:: `yyparse' Keeps some State +* Strings are Destroyed:: `yylval' Loses Track of Strings +* Implementing Gotos/Loops:: Control Flow in the Calculator +* Multiple start-symbols:: Factoring closely related grammars +* Secure? Conform?:: Is Bison POSIX safe? +* I can't build Bison:: Troubleshooting +* Where can I find help?:: Troubleshouting +* Bug Reports:: Troublereporting +* More Languages:: Parsers in C++, Java, and so on +* Beta Testing:: Experimenting development versions +* Mailing Lists:: Meeting other Bison users + + +File: bison.info, Node: Memory Exhausted, Next: How Can I Reset the Parser, Up: FAQ + +11.1 Memory Exhausted +===================== + + My parser returns with error with a `memory exhausted' + message. What can I do? + + This question is already addressed elsewhere, *Note Recursive Rules: +Recursion. + + +File: bison.info, Node: How Can I Reset the Parser, Next: Strings are Destroyed, Prev: Memory Exhausted, Up: FAQ + +11.2 How Can I Reset the Parser +=============================== + +The following phenomenon has several symptoms, resulting in the +following typical questions: + + I invoke `yyparse' several times, and on correct input it works + properly; but when a parse error is found, all the other calls fail + too. How can I reset the error flag of `yyparse'? + +or + + My parser includes support for an `#include'-like feature, in + which case I run `yyparse' from `yyparse'. This fails + although I did specify `%define api.pure'. + + These problems typically come not from Bison itself, but from +Lex-generated scanners. Because these scanners use large buffers for +speed, they might not notice a change of input file. As a +demonstration, consider the following source file, `first-line.l': + + +%{ +#include <stdio.h> +#include <stdlib.h> +%} +%% +.*\n ECHO; return 1; +%% +int +yyparse (char const *file) +{ + yyin = fopen (file, "r"); + if (!yyin) + exit (2); + /* One token only. */ + yylex (); + if (fclose (yyin) != 0) + exit (3); + return 0; +} + +int +main (void) +{ + yyparse ("input"); + yyparse ("input"); + return 0; +} + +If the file `input' contains + + +input:1: Hello, +input:2: World! + +then instead of getting the first line twice, you get: + + $ flex -ofirst-line.c first-line.l + $ gcc -ofirst-line first-line.c -ll + $ ./first-line + input:1: Hello, + input:2: World! + + Therefore, whenever you change `yyin', you must tell the +Lex-generated scanner to discard its current buffer and switch to the +new one. This depends upon your implementation of Lex; see its +documentation for more. For Flex, it suffices to call +`YY_FLUSH_BUFFER' after each change to `yyin'. If your Flex-generated +scanner needs to read from several input streams to handle features +like include files, you might consider using Flex functions like +`yy_switch_to_buffer' that manipulate multiple input buffers. + + If your Flex-generated scanner uses start conditions (*note Start +conditions: (flex)Start conditions.), you might also want to reset the +scanner's state, i.e., go back to the initial start condition, through +a call to `BEGIN (0)'. + + +File: bison.info, Node: Strings are Destroyed, Next: Implementing Gotos/Loops, Prev: How Can I Reset the Parser, Up: FAQ + +11.3 Strings are Destroyed +========================== + + My parser seems to destroy old strings, or maybe it loses track of + them. Instead of reporting `"foo", "bar"', it reports + `"bar", "bar"', or even `"foo\nbar", "bar"'. + + This error is probably the single most frequent "bug report" sent to +Bison lists, but is only concerned with a misunderstanding of the role +of the scanner. Consider the following Lex code: + + +%{ +#include <stdio.h> +char *yylval = NULL; +%} +%% +.* yylval = yytext; return 1; +\n /* IGNORE */ +%% +int +main () +{ + /* Similar to using $1, $2 in a Bison action. */ + char *fst = (yylex (), yylval); + char *snd = (yylex (), yylval); + printf ("\"%s\", \"%s\"\n", fst, snd); + return 0; +} + + If you compile and run this code, you get: + + $ flex -osplit-lines.c split-lines.l + $ gcc -osplit-lines split-lines.c -ll + $ printf 'one\ntwo\n' | ./split-lines + "one + two", "two" + +this is because `yytext' is a buffer provided for _reading_ in the +action, but if you want to keep it, you have to duplicate it (e.g., +using `strdup'). Note that the output may depend on how your +implementation of Lex handles `yytext'. For instance, when given the +Lex compatibility option `-l' (which triggers the option `%array') Flex +generates a different behavior: + + $ flex -l -osplit-lines.c split-lines.l + $ gcc -osplit-lines split-lines.c -ll + $ printf 'one\ntwo\n' | ./split-lines + "two", "two" + + +File: bison.info, Node: Implementing Gotos/Loops, Next: Multiple start-symbols, Prev: Strings are Destroyed, Up: FAQ + +11.4 Implementing Gotos/Loops +============================= + + My simple calculator supports variables, assignments, and functions, + but how can I implement gotos, or loops? + + Although very pedagogical, the examples included in the document blur +the distinction to make between the parser--whose job is to recover the +structure of a text and to transmit it to subsequent modules of the +program--and the processing (such as the execution) of this structure. +This works well with so called straight line programs, i.e., precisely +those that have a straightforward execution model: execute simple +instructions one after the others. + + If you want a richer model, you will probably need to use the parser +to construct a tree that does represent the structure it has recovered; +this tree is usually called the "abstract syntax tree", or "AST" for +short. Then, walking through this tree, traversing it in various ways, +will enable treatments such as its execution or its translation, which +will result in an interpreter or a compiler. + + This topic is way beyond the scope of this manual, and the reader is +invited to consult the dedicated literature. + + +File: bison.info, Node: Multiple start-symbols, Next: Secure? Conform?, Prev: Implementing Gotos/Loops, Up: FAQ + +11.5 Multiple start-symbols +=========================== + + I have several closely related grammars, and I would like to share their + implementations. In fact, I could use a single grammar but with + multiple entry points. + + Bison does not support multiple start-symbols, but there is a very +simple means to simulate them. If `foo' and `bar' are the two pseudo +start-symbols, then introduce two new tokens, say `START_FOO' and +`START_BAR', and use them as switches from the real start-symbol: + + %token START_FOO START_BAR; + %start start; + start: START_FOO foo + | START_BAR bar; + + These tokens prevents the introduction of new conflicts. As far as +the parser goes, that is all that is needed. + + Now the difficult part is ensuring that the scanner will send these +tokens first. If your scanner is hand-written, that should be +straightforward. If your scanner is generated by Lex, them there is +simple means to do it: recall that anything between `%{ ... %}' after +the first `%%' is copied verbatim in the top of the generated `yylex' +function. Make sure a variable `start_token' is available in the +scanner (e.g., a global variable or using `%lex-param' etc.), and use +the following: + + /* Prologue. */ + %% + %{ + if (start_token) + { + int t = start_token; + start_token = 0; + return t; + } + %} + /* The rules. */ + + +File: bison.info, Node: Secure? Conform?, Next: I can't build Bison, Prev: Multiple start-symbols, Up: FAQ + +11.6 Secure? Conform? +====================== + + Is Bison secure? Does it conform to POSIX? + + If you're looking for a guarantee or certification, we don't provide +it. However, Bison is intended to be a reliable program that conforms +to the POSIX specification for Yacc. If you run into problems, please +send us a bug report. + + +File: bison.info, Node: I can't build Bison, Next: Where can I find help?, Prev: Secure? Conform?, Up: FAQ + +11.7 I can't build Bison +======================== + + I can't build Bison because `make' complains that + `msgfmt' is not found. + What should I do? + + Like most GNU packages with internationalization support, that +feature is turned on by default. If you have problems building in the +`po' subdirectory, it indicates that your system's internationalization +support is lacking. You can re-configure Bison with `--disable-nls' to +turn off this support, or you can install GNU gettext from +`ftp://ftp.gnu.org/gnu/gettext/' and re-configure Bison. See the file +`ABOUT-NLS' for more information. + + +File: bison.info, Node: Where can I find help?, Next: Bug Reports, Prev: I can't build Bison, Up: FAQ + +11.8 Where can I find help? +=========================== + + I'm having trouble using Bison. Where can I find help? + + First, read this fine manual. Beyond that, you can send mail to +<help-bison@gnu.org>. This mailing list is intended to be populated +with people who are willing to answer questions about using and +installing Bison. Please keep in mind that (most of) the people on the +list have aspects of their lives which are not related to Bison (!), so +you may not receive an answer to your question right away. This can be +frustrating, but please try not to honk them off; remember that any +help they provide is purely voluntary and out of the kindness of their +hearts. + + +File: bison.info, Node: Bug Reports, Next: More Languages, Prev: Where can I find help?, Up: FAQ + +11.9 Bug Reports +================ + + I found a bug. What should I include in the bug report? + + Before you send a bug report, make sure you are using the latest +version. Check `ftp://ftp.gnu.org/pub/gnu/bison/' or one of its +mirrors. Be sure to include the version number in your bug report. If +the bug is present in the latest version but not in a previous version, +try to determine the most recent version which did not contain the bug. + + If the bug is parser-related, you should include the smallest grammar +you can which demonstrates the bug. The grammar file should also be +complete (i.e., I should be able to run it through Bison without having +to edit or add anything). The smaller and simpler the grammar, the +easier it will be to fix the bug. + + Include information about your compilation environment, including +your operating system's name and version and your compiler's name and +version. If you have trouble compiling, you should also include a +transcript of the build session, starting with the invocation of +`configure'. Depending on the nature of the bug, you may be asked to +send additional files as well (such as `config.h' or `config.cache'). + + Patches are most welcome, but not required. That is, do not +hesitate to send a bug report just because you can not provide a fix. + + Send bug reports to <bug-bison@gnu.org>. + + +File: bison.info, Node: More Languages, Next: Beta Testing, Prev: Bug Reports, Up: FAQ + +11.10 More Languages +==================== + + Will Bison ever have C++ and Java support? How about INSERT YOUR + FAVORITE LANGUAGE HERE? + + C++ and Java support is there now, and is documented. We'd love to +add other languages; contributions are welcome. + + +File: bison.info, Node: Beta Testing, Next: Mailing Lists, Prev: More Languages, Up: FAQ + +11.11 Beta Testing +================== + + What is involved in being a beta tester? + + It's not terribly involved. Basically, you would download a test +release, compile it, and use it to build and run a parser or two. After +that, you would submit either a bug report or a message saying that +everything is okay. It is important to report successes as well as +failures because test releases eventually become mainstream releases, +but only if they are adequately tested. If no one tests, development is +essentially halted. + + Beta testers are particularly needed for operating systems to which +the developers do not have easy access. They currently have easy +access to recent GNU/Linux and Solaris versions. Reports about other +operating systems are especially welcome. + + +File: bison.info, Node: Mailing Lists, Prev: Beta Testing, Up: FAQ + +11.12 Mailing Lists +=================== + + How do I join the help-bison and bug-bison mailing lists? + + See `http://lists.gnu.org/'. + + +File: bison.info, Node: Table of Symbols, Next: Glossary, Prev: FAQ, Up: Top + +Appendix A Bison Symbols +************************ + + -- Variable: @$ + In an action, the location of the left-hand side of the rule. + *Note Locations Overview: Locations. + + -- Variable: @N + In an action, the location of the N-th symbol of the right-hand + side of the rule. *Note Locations Overview: Locations. + + -- Variable: $$ + In an action, the semantic value of the left-hand side of the rule. + *Note Actions::. + + -- Variable: $N + In an action, the semantic value of the N-th symbol of the + right-hand side of the rule. *Note Actions::. + + -- Delimiter: %% + Delimiter used to separate the grammar rule section from the Bison + declarations section or the epilogue. *Note The Overall Layout of + a Bison Grammar: Grammar Layout. + + -- Delimiter: %{CODE%} + All code listed between `%{' and `%}' is copied directly to the + output file uninterpreted. Such code forms the prologue of the + input file. *Note Outline of a Bison Grammar: Grammar Outline. + + -- Construct: /*...*/ + Comment delimiters, as in C. + + -- Delimiter: : + Separates a rule's result from its components. *Note Syntax of + Grammar Rules: Rules. + + -- Delimiter: ; + Terminates a rule. *Note Syntax of Grammar Rules: Rules. + + -- Delimiter: | + Separates alternate rules for the same result nonterminal. *Note + Syntax of Grammar Rules: Rules. + + -- Directive: <*> + Used to define a default tagged `%destructor' or default tagged + `%printer'. + + This feature is experimental. More user feedback will help to + determine whether it should become a permanent feature. + + *Note Freeing Discarded Symbols: Destructor Decl. + + -- Directive: <> + Used to define a default tagless `%destructor' or default tagless + `%printer'. + + This feature is experimental. More user feedback will help to + determine whether it should become a permanent feature. + + *Note Freeing Discarded Symbols: Destructor Decl. + + -- Symbol: $accept + The predefined nonterminal whose only rule is `$accept: START + $end', where START is the start symbol. *Note The Start-Symbol: + Start Decl. It cannot be used in the grammar. + + -- Directive: %code {CODE} + -- Directive: %code QUALIFIER {CODE} + Insert CODE verbatim into output parser source. *Note %code: Decl + Summary. + + -- Directive: %debug + Equip the parser for debugging. *Note Decl Summary::. + + -- Directive: %debug + Equip the parser for debugging. *Note Decl Summary::. + + -- Directive: %define DEFINE-VARIABLE + -- Directive: %define DEFINE-VARIABLE VALUE + Define a variable to adjust Bison's behavior. *Note %define: Decl + Summary. + + -- Directive: %defines + Bison declaration to create a header file meant for the scanner. + *Note Decl Summary::. + + -- Directive: %defines DEFINES-FILE + Same as above, but save in the file DEFINES-FILE. *Note Decl + Summary::. + + -- Directive: %destructor + Specify how the parser should reclaim the memory associated to + discarded symbols. *Note Freeing Discarded Symbols: Destructor + Decl. + + -- Directive: %dprec + Bison declaration to assign a precedence to a rule that is used at + parse time to resolve reduce/reduce conflicts. *Note Writing GLR + Parsers: GLR Parsers. + + -- Symbol: $end + The predefined token marking the end of the token stream. It + cannot be used in the grammar. + + -- Symbol: error + A token name reserved for error recovery. This token may be used + in grammar rules so as to allow the Bison parser to recognize an + error in the grammar without halting the process. In effect, a + sentence containing an error may be recognized as valid. On a + syntax error, the token `error' becomes the current lookahead + token. Actions corresponding to `error' are then executed, and + the lookahead token is reset to the token that originally caused + the violation. *Note Error Recovery::. + + -- Directive: %error-verbose + Bison declaration to request verbose, specific error message + strings when `yyerror' is called. + + -- Directive: %file-prefix "PREFIX" + Bison declaration to set the prefix of the output files. *Note + Decl Summary::. + + -- Directive: %glr-parser + Bison declaration to produce a GLR parser. *Note Writing GLR + Parsers: GLR Parsers. + + -- Directive: %initial-action + Run user code before parsing. *Note Performing Actions before + Parsing: Initial Action Decl. + + -- Directive: %language + Specify the programming language for the generated parser. *Note + Decl Summary::. + + -- Directive: %left + Bison declaration to assign left associativity to token(s). *Note + Operator Precedence: Precedence Decl. + + -- Directive: %lex-param {ARGUMENT-DECLARATION} + Bison declaration to specifying an additional parameter that + `yylex' should accept. *Note Calling Conventions for Pure + Parsers: Pure Calling. + + -- Directive: %merge + Bison declaration to assign a merging function to a rule. If + there is a reduce/reduce conflict with a rule having the same + merging function, the function is applied to the two semantic + values to get a single result. *Note Writing GLR Parsers: GLR + Parsers. + + -- Directive: %name-prefix "PREFIX" + Bison declaration to rename the external symbols. *Note Decl + Summary::. + + -- Directive: %no-lines + Bison declaration to avoid generating `#line' directives in the + parser file. *Note Decl Summary::. + + -- Directive: %nonassoc + Bison declaration to assign nonassociativity to token(s). *Note + Operator Precedence: Precedence Decl. + + -- Directive: %output "FILE" + Bison declaration to set the name of the parser file. *Note Decl + Summary::. + + -- Directive: %parse-param {ARGUMENT-DECLARATION} + Bison declaration to specifying an additional parameter that + `yyparse' should accept. *Note The Parser Function `yyparse': + Parser Function. + + -- Directive: %prec + Bison declaration to assign a precedence to a specific rule. + *Note Context-Dependent Precedence: Contextual Precedence. + + -- Directive: %pure-parser + Deprecated version of `%define api.pure' (*note %define: Decl + Summary.), for which Bison is more careful to warn about + unreasonable usage. + + -- Directive: %require "VERSION" + Require version VERSION or higher of Bison. *Note Require a + Version of Bison: Require Decl. + + -- Directive: %right + Bison declaration to assign right associativity to token(s). + *Note Operator Precedence: Precedence Decl. + + -- Directive: %skeleton + Specify the skeleton to use; usually for development. *Note Decl + Summary::. + + -- Directive: %start + Bison declaration to specify the start symbol. *Note The + Start-Symbol: Start Decl. + + -- Directive: %token + Bison declaration to declare token(s) without specifying + precedence. *Note Token Type Names: Token Decl. + + -- Directive: %token-table + Bison declaration to include a token name table in the parser file. + *Note Decl Summary::. + + -- Directive: %type + Bison declaration to declare nonterminals. *Note Nonterminal + Symbols: Type Decl. + + -- Symbol: $undefined + The predefined token onto which all undefined values returned by + `yylex' are mapped. It cannot be used in the grammar, rather, use + `error'. + + -- Directive: %union + Bison declaration to specify several possible data types for + semantic values. *Note The Collection of Value Types: Union Decl. + + -- Macro: YYABORT + Macro to pretend that an unrecoverable syntax error has occurred, + by making `yyparse' return 1 immediately. The error reporting + function `yyerror' is not called. *Note The Parser Function + `yyparse': Parser Function. + + For Java parsers, this functionality is invoked using `return + YYABORT;' instead. + + -- Macro: YYACCEPT + Macro to pretend that a complete utterance of the language has been + read, by making `yyparse' return 0 immediately. *Note The Parser + Function `yyparse': Parser Function. + + For Java parsers, this functionality is invoked using `return + YYACCEPT;' instead. + + -- Macro: YYBACKUP + Macro to discard a value from the parser stack and fake a lookahead + token. *Note Special Features for Use in Actions: Action Features. + + -- Variable: yychar + External integer variable that contains the integer value of the + lookahead token. (In a pure parser, it is a local variable within + `yyparse'.) Error-recovery rule actions may examine this variable. + *Note Special Features for Use in Actions: Action Features. + + -- Variable: yyclearin + Macro used in error-recovery rule actions. It clears the previous + lookahead token. *Note Error Recovery::. + + -- Macro: YYDEBUG + Macro to define to equip the parser with tracing code. *Note + Tracing Your Parser: Tracing. + + -- Variable: yydebug + External integer variable set to zero by default. If `yydebug' is + given a nonzero value, the parser will output information on input + symbols and parser action. *Note Tracing Your Parser: Tracing. + + -- Macro: yyerrok + Macro to cause parser to recover immediately to its normal mode + after a syntax error. *Note Error Recovery::. + + -- Macro: YYERROR + Macro to pretend that a syntax error has just been detected: call + `yyerror' and then perform normal error recovery if possible + (*note Error Recovery::), or (if recovery is impossible) make + `yyparse' return 1. *Note Error Recovery::. + + For Java parsers, this functionality is invoked using `return + YYERROR;' instead. + + -- Function: yyerror + User-supplied function to be called by `yyparse' on error. *Note + The Error Reporting Function `yyerror': Error Reporting. + + -- Macro: YYERROR_VERBOSE + An obsolete macro that you define with `#define' in the prologue + to request verbose, specific error message strings when `yyerror' + is called. It doesn't matter what definition you use for + `YYERROR_VERBOSE', just whether you define it. Using + `%error-verbose' is preferred. + + -- Macro: YYINITDEPTH + Macro for specifying the initial size of the parser stack. *Note + Memory Management::. + + -- Function: yylex + User-supplied lexical analyzer function, called with no arguments + to get the next token. *Note The Lexical Analyzer Function + `yylex': Lexical. + + -- Macro: YYLEX_PARAM + An obsolete macro for specifying an extra argument (or list of + extra arguments) for `yyparse' to pass to `yylex'. The use of this + macro is deprecated, and is supported only for Yacc like parsers. + *Note Calling Conventions for Pure Parsers: Pure Calling. + + -- Variable: yylloc + External variable in which `yylex' should place the line and column + numbers associated with a token. (In a pure parser, it is a local + variable within `yyparse', and its address is passed to `yylex'.) + You can ignore this variable if you don't use the `@' feature in + the grammar actions. *Note Textual Locations of Tokens: Token + Locations. In semantic actions, it stores the location of the + lookahead token. *Note Actions and Locations: Actions and + Locations. + + -- Type: YYLTYPE + Data type of `yylloc'; by default, a structure with four members. + *Note Data Types of Locations: Location Type. + + -- Variable: yylval + External variable in which `yylex' should place the semantic value + associated with a token. (In a pure parser, it is a local + variable within `yyparse', and its address is passed to `yylex'.) + *Note Semantic Values of Tokens: Token Values. In semantic + actions, it stores the semantic value of the lookahead token. + *Note Actions: Actions. + + -- Macro: YYMAXDEPTH + Macro for specifying the maximum size of the parser stack. *Note + Memory Management::. + + -- Variable: yynerrs + Global variable which Bison increments each time it reports a + syntax error. (In a pure parser, it is a local variable within + `yyparse'. In a pure push parser, it is a member of yypstate.) + *Note The Error Reporting Function `yyerror': Error Reporting. + + -- Function: yyparse + The parser function produced by Bison; call this function to start + parsing. *Note The Parser Function `yyparse': Parser Function. + + -- Function: yypstate_delete + The function to delete a parser instance, produced by Bison in + push mode; call this function to delete the memory associated with + a parser. *Note The Parser Delete Function `yypstate_delete': + Parser Delete Function. (The current push parsing interface is + experimental and may evolve. More user feedback will help to + stabilize it.) + + -- Function: yypstate_new + The function to create a parser instance, produced by Bison in + push mode; call this function to create a new parser. *Note The + Parser Create Function `yypstate_new': Parser Create Function. + (The current push parsing interface is experimental and may evolve. + More user feedback will help to stabilize it.) + + -- Function: yypull_parse + The parser function produced by Bison in push mode; call this + function to parse the rest of the input stream. *Note The Pull + Parser Function `yypull_parse': Pull Parser Function. (The + current push parsing interface is experimental and may evolve. + More user feedback will help to stabilize it.) + + -- Function: yypush_parse + The parser function produced by Bison in push mode; call this + function to parse a single token. *Note The Push Parser Function + `yypush_parse': Push Parser Function. (The current push parsing + interface is experimental and may evolve. More user feedback will + help to stabilize it.) + + -- Macro: YYPARSE_PARAM + An obsolete macro for specifying the name of a parameter that + `yyparse' should accept. The use of this macro is deprecated, and + is supported only for Yacc like parsers. *Note Calling + Conventions for Pure Parsers: Pure Calling. + + -- Macro: YYRECOVERING + The expression `YYRECOVERING ()' yields 1 when the parser is + recovering from a syntax error, and 0 otherwise. *Note Special + Features for Use in Actions: Action Features. + + -- Macro: YYSTACK_USE_ALLOCA + Macro used to control the use of `alloca' when the C LALR(1) + parser needs to extend its stacks. If defined to 0, the parser + will use `malloc' to extend its stacks. If defined to 1, the + parser will use `alloca'. Values other than 0 and 1 are reserved + for future Bison extensions. If not defined, `YYSTACK_USE_ALLOCA' + defaults to 0. + + In the all-too-common case where your code may run on a host with a + limited stack and with unreliable stack-overflow checking, you + should set `YYMAXDEPTH' to a value that cannot possibly result in + unchecked stack overflow on any of your target hosts when `alloca' + is called. You can inspect the code that Bison generates in order + to determine the proper numeric values. This will require some + expertise in low-level implementation details. + + -- Type: YYSTYPE + Data type of semantic values; `int' by default. *Note Data Types + of Semantic Values: Value Type. + + +File: bison.info, Node: Glossary, Next: Copying This Manual, Prev: Table of Symbols, Up: Top + +Appendix B Glossary +******************* + +Backus-Naur Form (BNF; also called "Backus Normal Form") + Formal method of specifying context-free grammars originally + proposed by John Backus, and slightly improved by Peter Naur in + his 1960-01-02 committee document contributing to what became the + Algol 60 report. *Note Languages and Context-Free Grammars: + Language and Grammar. + +Context-free grammars + Grammars specified as rules that can be applied regardless of + context. Thus, if there is a rule which says that an integer can + be used as an expression, integers are allowed _anywhere_ an + expression is permitted. *Note Languages and Context-Free + Grammars: Language and Grammar. + +Dynamic allocation + Allocation of memory that occurs during execution, rather than at + compile time or on entry to a function. + +Empty string + Analogous to the empty set in set theory, the empty string is a + character string of length zero. + +Finite-state stack machine + A "machine" that has discrete states in which it is said to exist + at each instant in time. As input to the machine is processed, the + machine moves from state to state as specified by the logic of the + machine. In the case of the parser, the input is the language + being parsed, and the states correspond to various stages in the + grammar rules. *Note The Bison Parser Algorithm: Algorithm. + +Generalized LR (GLR) + A parsing algorithm that can handle all context-free grammars, + including those that are not LALR(1). It resolves situations that + Bison's usual LALR(1) algorithm cannot by effectively splitting + off multiple parsers, trying all possible parsers, and discarding + those that fail in the light of additional right context. *Note + Generalized LR Parsing: Generalized LR Parsing. + +Grouping + A language construct that is (in general) grammatically divisible; + for example, `expression' or `declaration' in C. *Note Languages + and Context-Free Grammars: Language and Grammar. + +Infix operator + An arithmetic operator that is placed between the operands on + which it performs some operation. + +Input stream + A continuous flow of data between devices or programs. + +Language construct + One of the typical usage schemas of the language. For example, + one of the constructs of the C language is the `if' statement. + *Note Languages and Context-Free Grammars: Language and Grammar. + +Left associativity + Operators having left associativity are analyzed from left to + right: `a+b+c' first computes `a+b' and then combines with `c'. + *Note Operator Precedence: Precedence. + +Left recursion + A rule whose result symbol is also its first component symbol; for + example, `expseq1 : expseq1 ',' exp;'. *Note Recursive Rules: + Recursion. + +Left-to-right parsing + Parsing a sentence of a language by analyzing it token by token + from left to right. *Note The Bison Parser Algorithm: Algorithm. + +Lexical analyzer (scanner) + A function that reads an input stream and returns tokens one by + one. *Note The Lexical Analyzer Function `yylex': Lexical. + +Lexical tie-in + A flag, set by actions in the grammar rules, which alters the way + tokens are parsed. *Note Lexical Tie-ins::. + +Literal string token + A token which consists of two or more fixed characters. *Note + Symbols::. + +Lookahead token + A token already read but not yet shifted. *Note Lookahead Tokens: + Lookahead. + +LALR(1) + The class of context-free grammars that Bison (like most other + parser generators) can handle; a subset of LR(1). *Note + Mysterious Reduce/Reduce Conflicts: Mystery Conflicts. + +LR(1) + The class of context-free grammars in which at most one token of + lookahead is needed to disambiguate the parsing of any piece of + input. + +Nonterminal symbol + A grammar symbol standing for a grammatical construct that can be + expressed through rules in terms of smaller constructs; in other + words, a construct that is not a token. *Note Symbols::. + +Parser + A function that recognizes valid sentences of a language by + analyzing the syntax structure of a set of tokens passed to it + from a lexical analyzer. + +Postfix operator + An arithmetic operator that is placed after the operands upon + which it performs some operation. + +Reduction + Replacing a string of nonterminals and/or terminals with a single + nonterminal, according to a grammar rule. *Note The Bison Parser + Algorithm: Algorithm. + +Reentrant + A reentrant subprogram is a subprogram which can be in invoked any + number of times in parallel, without interference between the + various invocations. *Note A Pure (Reentrant) Parser: Pure Decl. + +Reverse polish notation + A language in which all operators are postfix operators. + +Right recursion + A rule whose result symbol is also its last component symbol; for + example, `expseq1: exp ',' expseq1;'. *Note Recursive Rules: + Recursion. + +Semantics + In computer languages, the semantics are specified by the actions + taken for each instance of the language, i.e., the meaning of each + statement. *Note Defining Language Semantics: Semantics. + +Shift + A parser is said to shift when it makes the choice of analyzing + further input from the stream rather than reducing immediately some + already-recognized rule. *Note The Bison Parser Algorithm: + Algorithm. + +Single-character literal + A single character that is recognized and interpreted as is. + *Note From Formal Rules to Bison Input: Grammar in Bison. + +Start symbol + The nonterminal symbol that stands for a complete valid utterance + in the language being parsed. The start symbol is usually listed + as the first nonterminal symbol in a language specification. + *Note The Start-Symbol: Start Decl. + +Symbol table + A data structure where symbol names and associated data are stored + during parsing to allow for recognition and use of existing + information in repeated uses of a symbol. *Note Multi-function + Calc::. + +Syntax error + An error encountered during parsing of an input stream due to + invalid syntax. *Note Error Recovery::. + +Token + A basic, grammatically indivisible unit of a language. The symbol + that describes a token in the grammar is a terminal symbol. The + input of the Bison parser is a stream of tokens which comes from + the lexical analyzer. *Note Symbols::. + +Terminal symbol + A grammar symbol that has no rules in the grammar and therefore is + grammatically indivisible. The piece of text it represents is a + token. *Note Languages and Context-Free Grammars: Language and + Grammar. + + +File: bison.info, Node: Copying This Manual, Next: Index, Prev: Glossary, Up: Top + +Appendix C Copying This Manual +****************************** + + Version 1.2, November 2002 + + Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. + We recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it + can be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You + accept the license if you copy, modify or distribute the work in a + way requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in + the notice that says that the Document is released under this + License. If a section does not fit the above definition of + Secondary then it is not allowed to be designated as Invariant. + The Document may contain zero Invariant Sections. If the Document + does not identify any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images + composed of pixels) generic paint programs or (for drawings) some + widely available drawing editor, and that is suitable for input to + text formatters or for automatic translation to a variety of + formats suitable for input to text formatters. A copy made in an + otherwise Transparent file format whose markup, or absence of + markup, has been arranged to thwart or discourage subsequent + modification by readers is not Transparent. An image format is + not Transparent if used for any substantial amount of text. A + copy that is not "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and + standard-conforming simple HTML, PostScript or PDF designed for + human modification. Examples of transparent image formats include + PNG, XCF and JPG. Opaque formats include proprietary formats that + can be read and edited only by proprietary word processors, SGML or + XML for which the DTD and/or processing tools are not generally + available, and the machine-generated HTML, PostScript or PDF + produced by some word processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow + the conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the + title equally prominent and visible. You may add other material + on the covers in addition. Copying with changes limited to the + covers, as long as they preserve the title of the Document and + satisfy these conditions, can be treated as verbatim copying in + other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a + machine-readable Transparent copy along with each Opaque copy, or + state in or with each Opaque copy a computer-network location from + which the general network-using public has access to download + using public-standard network protocols a complete Transparent + copy of the Document, free of added material. If you use the + latter option, you must take reasonably prudent steps, when you + begin distribution of Opaque copies in quantity, to ensure that + this Transparent copy will remain thus accessible at the stated + location until at least one year after the last time you + distribute an Opaque copy (directly or through your agents or + retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of + copies, to give them a chance to provide you with an updated + version of the Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with + the Modified Version filling the role of the Document, thus + licensing distribution and modification of the Modified Version to + whoever possesses a copy of it. In addition, you must do these + things in the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of + previous versions (which should, if there were any, be listed + in the History section of the Document). You may use the + same title as a previous version if the original publisher of + that version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on + the Title Page. If there is no section Entitled "History" in + the Document, create one stating the title, year, authors, + and publisher of the Document as given on its Title Page, + then add an item describing the Modified Version as stated in + the previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in + the "History" section. You may omit a network location for a + work that was published at least four years before the + Document itself, or if the original publisher of the version + it refers to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the + section all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section + titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option + designate some or all of these sections as invariant. To do this, + add their titles to the list of Invariant Sections in the Modified + Version's license notice. These titles must be distinct from any + other section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end + of the list of Cover Texts in the Modified Version. Only one + passage of Front-Cover Text and one of Back-Cover Text may be + added by (or through arrangements made by) any one entity. If the + Document already includes a cover text for the same cover, + previously added by you or by arrangement made by the same entity + you are acting on behalf of, you may not add another; but you may + replace the old one, on explicit permission from the previous + publisher that added the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination + all of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the + documents in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow + this License in all other respects regarding verbatim copying of + that document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of + a storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided for under this License. Any other + attempt to copy, modify, sublicense or distribute the Document is + void, and will automatically terminate your rights under this + License. However, parties who have received copies, or rights, + from you under this License will not have their licenses + terminated so long as such parties remain in full compliance. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + `http://www.gnu.org/copyleft/'. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If + the Document does not specify a version number of this License, + you may choose any version ever published (not as a draft) by the + Free Software Foundation. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, to +permit their use in free software. + + +File: bison.info, Node: Index, Prev: Copying This Manual, Up: Top + +Index +***** + + +* Menu: + +* $ <1>: Table of Symbols. (line 19) +* $ <2>: Action Features. (line 14) +* $: Java Action Features. + (line 13) +* $$ <1>: Action Features. (line 10) +* $$ <2>: Java Action Features. + (line 21) +* $$ <3>: Actions. (line 6) +* $$: Table of Symbols. (line 15) +* $< <1>: Java Action Features. + (line 17) +* $< <2>: Action Features. (line 23) +* $< <3>: Java Action Features. + (line 29) +* $<: Action Features. (line 18) +* $accept: Table of Symbols. (line 65) +* $end: Table of Symbols. (line 104) +* $N: Actions. (line 6) +* $undefined: Table of Symbols. (line 212) +* % <1>: Java Declarations Summary. + (line 53) +* %: Table of Symbols. (line 28) +* %% <1>: Table of Symbols. (line 23) +* %%: Java Declarations Summary. + (line 49) +* %code <1>: Table of Symbols. (line 71) +* %code <2>: Prologue Alternatives. + (line 6) +* %code <3>: Java Declarations Summary. + (line 37) +* %code <4>: Calc++ Parser. (line 64) +* %code: Decl Summary. (line 63) +* %code imports <1>: Java Declarations Summary. + (line 41) +* %code imports: Decl Summary. (line 115) +* %code lexer: Java Declarations Summary. + (line 45) +* %code provides <1>: Prologue Alternatives. + (line 6) +* %code provides: Decl Summary. (line 303) +* %code requires <1>: Decl Summary. (line 72) +* %code requires <2>: Calc++ Parser. (line 17) +* %code requires: Prologue Alternatives. + (line 6) +* %code top <1>: Decl Summary. (line 98) +* %code top: Prologue Alternatives. + (line 6) +* %debug <1>: Table of Symbols. (line 78) +* %debug <2>: Tracing. (line 23) +* %debug <3>: Decl Summary. (line 134) +* %debug: Table of Symbols. (line 75) +* %define <1>: Table of Symbols. (line 81) +* %define <2>: Decl Summary. (line 140) +* %define: Table of Symbols. (line 82) +* %define abstract: Java Declarations Summary. + (line 57) +* %define api.pure <1>: Decl Summary. (line 166) +* %define api.pure: Pure Decl. (line 6) +* %define api.push_pull <1>: Push Decl. (line 6) +* %define api.push_pull: Decl Summary. (line 177) +* %define extends: Java Declarations Summary. + (line 61) +* %define final: Java Declarations Summary. + (line 65) +* %define implements: Java Declarations Summary. + (line 69) +* %define lex_throws: Java Declarations Summary. + (line 73) +* %define location_type: Java Declarations Summary. + (line 78) +* %define lr.keep_unreachable_states: Decl Summary. (line 190) +* %define namespace <1>: Decl Summary. (line 232) +* %define namespace: C++ Bison Interface. (line 10) +* %define package: Java Declarations Summary. + (line 84) +* %define parser_class_name: Java Declarations Summary. + (line 88) +* %define position_type: Java Declarations Summary. + (line 92) +* %define public: Java Declarations Summary. + (line 97) +* %define strictfp: Java Declarations Summary. + (line 105) +* %define stype: Java Declarations Summary. + (line 101) +* %define throws: Java Declarations Summary. + (line 109) +* %defines <1>: Table of Symbols. (line 90) +* %defines <2>: Decl Summary. (line 307) +* %defines: Table of Symbols. (line 86) +* %destructor <1>: Destructor Decl. (line 22) +* %destructor <2>: Decl Summary. (line 310) +* %destructor <3>: Destructor Decl. (line 6) +* %destructor <4>: Mid-Rule Actions. (line 59) +* %destructor <5>: Table of Symbols. (line 94) +* %destructor: Destructor Decl. (line 22) +* %dprec <1>: Table of Symbols. (line 99) +* %dprec: Merging GLR Parses. (line 6) +* %error-verbose <1>: Table of Symbols. (line 118) +* %error-verbose: Error Reporting. (line 17) +* %expect <1>: Decl Summary. (line 38) +* %expect: Expect Decl. (line 6) +* %expect-rr <1>: Expect Decl. (line 6) +* %expect-rr: Simple GLR Parsers. (line 6) +* %file-prefix <1>: Decl Summary. (line 315) +* %file-prefix: Table of Symbols. (line 122) +* %glr-parser <1>: Simple GLR Parsers. (line 6) +* %glr-parser <2>: Table of Symbols. (line 126) +* %glr-parser: GLR Parsers. (line 6) +* %initial-action <1>: Table of Symbols. (line 130) +* %initial-action: Initial Action Decl. (line 11) +* %language <1>: Decl Summary. (line 319) +* %language: Table of Symbols. (line 134) +* %language "Java": Java Declarations Summary. + (line 10) +* %left <1>: Using Precedence. (line 6) +* %left <2>: Decl Summary. (line 21) +* %left: Table of Symbols. (line 138) +* %lex-param <1>: Table of Symbols. (line 142) +* %lex-param <2>: Pure Calling. (line 31) +* %lex-param: Java Declarations Summary. + (line 13) +* %locations: Decl Summary. (line 327) +* %merge <1>: Merging GLR Parses. (line 6) +* %merge: Table of Symbols. (line 147) +* %name-prefix <1>: Java Declarations Summary. + (line 19) +* %name-prefix <2>: Decl Summary. (line 334) +* %name-prefix: Table of Symbols. (line 154) +* %no-lines <1>: Decl Summary. (line 346) +* %no-lines: Table of Symbols. (line 158) +* %nonassoc <1>: Table of Symbols. (line 162) +* %nonassoc <2>: Using Precedence. (line 6) +* %nonassoc: Decl Summary. (line 25) +* %output <1>: Decl Summary. (line 354) +* %output: Table of Symbols. (line 166) +* %parse-param <1>: Java Declarations Summary. + (line 24) +* %parse-param <2>: Parser Function. (line 36) +* %parse-param <3>: Table of Symbols. (line 170) +* %parse-param: Parser Function. (line 36) +* %prec <1>: Table of Symbols. (line 175) +* %prec: Contextual Precedence. + (line 6) +* %pure-parser <1>: Table of Symbols. (line 179) +* %pure-parser: Decl Summary. (line 357) +* %require <1>: Table of Symbols. (line 184) +* %require <2>: Require Decl. (line 6) +* %require: Decl Summary. (line 362) +* %right <1>: Using Precedence. (line 6) +* %right <2>: Decl Summary. (line 17) +* %right: Table of Symbols. (line 188) +* %skeleton <1>: Decl Summary. (line 366) +* %skeleton: Table of Symbols. (line 192) +* %start <1>: Table of Symbols. (line 196) +* %start <2>: Decl Summary. (line 34) +* %start: Start Decl. (line 6) +* %token <1>: Decl Summary. (line 13) +* %token <2>: Token Decl. (line 6) +* %token <3>: Java Declarations Summary. + (line 29) +* %token: Table of Symbols. (line 200) +* %token-table <1>: Decl Summary. (line 374) +* %token-table: Table of Symbols. (line 204) +* %type <1>: Java Declarations Summary. + (line 33) +* %type <2>: Type Decl. (line 6) +* %type <3>: Table of Symbols. (line 208) +* %type: Decl Summary. (line 30) +* %union <1>: Decl Summary. (line 9) +* %union <2>: Union Decl. (line 6) +* %union: Table of Symbols. (line 217) +* %verbose: Decl Summary. (line 407) +* %yacc: Decl Summary. (line 413) +* *yypstate_new: Parser Create Function. + (line 15) +* /*: Table of Symbols. (line 33) +* :: Table of Symbols. (line 36) +* ;: Table of Symbols. (line 40) +* <*> <1>: Destructor Decl. (line 6) +* <*>: Table of Symbols. (line 47) +* <> <1>: Destructor Decl. (line 6) +* <>: Table of Symbols. (line 56) +* @$ <1>: Action Features. (line 98) +* @$ <2>: Java Action Features. + (line 39) +* @$ <3>: Table of Symbols. (line 7) +* @$: Actions and Locations. + (line 6) +* @N <1>: Action Features. (line 104) +* @N <2>: Actions and Locations. + (line 6) +* @N <3>: Table of Symbols. (line 11) +* @N <4>: Action Features. (line 104) +* @N: Java Action Features. + (line 35) +* abstract syntax tree: Implementing Gotos/Loops. + (line 17) +* action: Actions. (line 6) +* action data types: Action Types. (line 6) +* action features summary: Action Features. (line 6) +* actions in mid-rule <1>: Mid-Rule Actions. (line 6) +* actions in mid-rule: Destructor Decl. (line 88) +* actions, location: Actions and Locations. + (line 6) +* actions, semantic: Semantic Actions. (line 6) +* additional C code section: Epilogue. (line 6) +* algorithm of parser: Algorithm. (line 6) +* ambiguous grammars <1>: Generalized LR Parsing. + (line 6) +* ambiguous grammars: Language and Grammar. + (line 33) +* associativity: Why Precedence. (line 33) +* AST: Implementing Gotos/Loops. + (line 17) +* Backus-Naur form: Language and Grammar. + (line 16) +* begin of Location: Java Location Values. + (line 21) +* begin on location: C++ Location Values. (line 44) +* Bison declaration summary: Decl Summary. (line 6) +* Bison declarations: Declarations. (line 6) +* Bison declarations (introduction): Bison Declarations. (line 6) +* Bison grammar: Grammar in Bison. (line 6) +* Bison invocation: Invocation. (line 6) +* Bison parser: Bison Parser. (line 6) +* Bison parser algorithm: Algorithm. (line 6) +* Bison symbols, table of: Table of Symbols. (line 6) +* Bison utility: Bison Parser. (line 6) +* bison-i18n.m4: Internationalization. + (line 20) +* bison-po: Internationalization. + (line 6) +* BISON_I18N: Internationalization. + (line 27) +* BISON_LOCALEDIR: Internationalization. + (line 27) +* BNF: Language and Grammar. + (line 16) +* braced code: Rules. (line 31) +* C code, section for additional: Epilogue. (line 6) +* C-language interface: Interface. (line 6) +* calc: Infix Calc. (line 6) +* calculator, infix notation: Infix Calc. (line 6) +* calculator, location tracking: Location Tracking Calc. + (line 6) +* calculator, multi-function: Multi-function Calc. (line 6) +* calculator, simple: RPN Calc. (line 6) +* character token: Symbols. (line 31) +* column on position: C++ Location Values. (line 25) +* columns on location: C++ Location Values. (line 48) +* columns on position: C++ Location Values. (line 28) +* compiling the parser: Rpcalc Compile. (line 6) +* conflicts <1>: Shift/Reduce. (line 6) +* conflicts <2>: Merging GLR Parses. (line 6) +* conflicts <3>: GLR Parsers. (line 6) +* conflicts: Simple GLR Parsers. (line 6) +* conflicts, reduce/reduce: Reduce/Reduce. (line 6) +* conflicts, suppressing warnings of: Expect Decl. (line 6) +* context-dependent precedence: Contextual Precedence. + (line 6) +* context-free grammar: Language and Grammar. + (line 6) +* controlling function: Rpcalc Main. (line 6) +* core, item set: Understanding. (line 129) +* dangling else: Shift/Reduce. (line 6) +* data type of locations: Location Type. (line 6) +* data types in actions: Action Types. (line 6) +* data types of semantic values: Value Type. (line 6) +* debug_level on parser: C++ Parser Interface. + (line 31) +* debug_stream on parser: C++ Parser Interface. + (line 26) +* debugging: Tracing. (line 6) +* declaration summary: Decl Summary. (line 6) +* declarations: Prologue. (line 6) +* declarations section: Prologue. (line 6) +* declarations, Bison: Declarations. (line 6) +* declarations, Bison (introduction): Bison Declarations. (line 6) +* declaring literal string tokens: Token Decl. (line 6) +* declaring operator precedence: Precedence Decl. (line 6) +* declaring the start symbol: Start Decl. (line 6) +* declaring token type names: Token Decl. (line 6) +* declaring value types: Union Decl. (line 6) +* declaring value types, nonterminals: Type Decl. (line 6) +* default action: Actions. (line 50) +* default data type: Value Type. (line 6) +* default location type: Location Type. (line 6) +* default stack limit: Memory Management. (line 30) +* default start symbol: Start Decl. (line 6) +* deferred semantic actions: GLR Semantic Actions. + (line 6) +* defining language semantics: Semantics. (line 6) +* discarded symbols: Destructor Decl. (line 98) +* discarded symbols, mid-rule actions: Mid-Rule Actions. (line 59) +* else, dangling: Shift/Reduce. (line 6) +* end of Location: Java Location Values. + (line 22) +* end on location: C++ Location Values. (line 45) +* epilogue: Epilogue. (line 6) +* error <1>: Error Recovery. (line 20) +* error: Table of Symbols. (line 108) +* error on parser: C++ Parser Interface. + (line 37) +* error recovery: Error Recovery. (line 6) +* error recovery, mid-rule actions: Mid-Rule Actions. (line 59) +* error recovery, simple: Simple Error Recovery. + (line 6) +* error reporting function: Error Reporting. (line 6) +* error reporting routine: Rpcalc Error. (line 6) +* examples, simple: Examples. (line 6) +* exercises: Exercises. (line 6) +* file format: Grammar Layout. (line 6) +* file on position: C++ Location Values. (line 13) +* finite-state machine: Parser States. (line 6) +* formal grammar: Grammar in Bison. (line 6) +* format of grammar file: Grammar Layout. (line 6) +* freeing discarded symbols: Destructor Decl. (line 6) +* frequently asked questions: FAQ. (line 6) +* generalized LR (GLR) parsing <1>: Generalized LR Parsing. + (line 6) +* generalized LR (GLR) parsing <2>: Language and Grammar. + (line 33) +* generalized LR (GLR) parsing: GLR Parsers. (line 6) +* generalized LR (GLR) parsing, ambiguous grammars: Merging GLR Parses. + (line 6) +* generalized LR (GLR) parsing, unambiguous grammars: Simple GLR Parsers. + (line 6) +* getDebugLevel on YYParser: Java Parser Interface. + (line 67) +* getDebugStream on YYParser: Java Parser Interface. + (line 62) +* getEndPos on Lexer: Java Scanner Interface. + (line 39) +* getLVal on Lexer: Java Scanner Interface. + (line 47) +* getStartPos on Lexer: Java Scanner Interface. + (line 38) +* gettext: Internationalization. + (line 6) +* glossary: Glossary. (line 6) +* GLR parsers and inline: Compiler Requirements. + (line 6) +* GLR parsers and yychar: GLR Semantic Actions. + (line 10) +* GLR parsers and yyclearin: GLR Semantic Actions. + (line 18) +* GLR parsers and YYERROR: GLR Semantic Actions. + (line 28) +* GLR parsers and yylloc: GLR Semantic Actions. + (line 10) +* GLR parsers and YYLLOC_DEFAULT: Location Default Action. + (line 6) +* GLR parsers and yylval: GLR Semantic Actions. + (line 10) +* GLR parsing <1>: Language and Grammar. + (line 33) +* GLR parsing <2>: Generalized LR Parsing. + (line 6) +* GLR parsing: GLR Parsers. (line 6) +* GLR parsing, ambiguous grammars: Merging GLR Parses. (line 6) +* GLR parsing, unambiguous grammars: Simple GLR Parsers. (line 6) +* grammar file: Grammar Layout. (line 6) +* grammar rule syntax: Rules. (line 6) +* grammar rules section: Grammar Rules. (line 6) +* grammar, Bison: Grammar in Bison. (line 6) +* grammar, context-free: Language and Grammar. + (line 6) +* grouping, syntactic: Language and Grammar. + (line 47) +* i18n: Internationalization. + (line 6) +* infix notation calculator: Infix Calc. (line 6) +* inline: Compiler Requirements. + (line 6) +* interface: Interface. (line 6) +* internationalization: Internationalization. + (line 6) +* introduction: Introduction. (line 6) +* invoking Bison: Invocation. (line 6) +* item: Understanding. (line 107) +* item set core: Understanding. (line 129) +* kernel, item set: Understanding. (line 129) +* LALR(1): Mystery Conflicts. (line 36) +* LALR(1) grammars: Language and Grammar. + (line 22) +* language semantics, defining: Semantics. (line 6) +* layout of Bison grammar: Grammar Layout. (line 6) +* left recursion: Recursion. (line 16) +* lex-param: Pure Calling. (line 31) +* lexical analyzer: Lexical. (line 6) +* lexical analyzer, purpose: Bison Parser. (line 6) +* lexical analyzer, writing: Rpcalc Lexer. (line 6) +* lexical tie-in: Lexical Tie-ins. (line 6) +* line on position: C++ Location Values. (line 19) +* lines on location: C++ Location Values. (line 49) +* lines on position: C++ Location Values. (line 22) +* literal string token: Symbols. (line 53) +* literal token: Symbols. (line 31) +* location <1>: Locations Overview. (line 6) +* location: Locations. (line 6) +* location actions: Actions and Locations. + (line 6) +* Location on Location: Java Location Values. + (line 25) +* location tracking calculator: Location Tracking Calc. + (line 6) +* location, textual <1>: Locations. (line 6) +* location, textual: Locations Overview. (line 6) +* location_value_type: C++ Parser Interface. + (line 16) +* lookahead token: Lookahead. (line 6) +* LR(1): Mystery Conflicts. (line 36) +* LR(1) grammars: Language and Grammar. + (line 22) +* ltcalc: Location Tracking Calc. + (line 6) +* main function in simple example: Rpcalc Main. (line 6) +* memory exhaustion: Memory Management. (line 6) +* memory management: Memory Management. (line 6) +* mfcalc: Multi-function Calc. (line 6) +* mid-rule actions <1>: Destructor Decl. (line 88) +* mid-rule actions: Mid-Rule Actions. (line 6) +* multi-function calculator: Multi-function Calc. (line 6) +* multicharacter literal: Symbols. (line 53) +* mutual recursion: Recursion. (line 32) +* NLS: Internationalization. + (line 6) +* nondeterministic parsing <1>: Generalized LR Parsing. + (line 6) +* nondeterministic parsing: Language and Grammar. + (line 33) +* nonterminal symbol: Symbols. (line 6) +* nonterminal, useless: Understanding. (line 62) +* operator precedence: Precedence. (line 6) +* operator precedence, declaring: Precedence Decl. (line 6) +* operator+ on location: C++ Location Values. (line 53) +* operator+ on position: C++ Location Values. (line 33) +* operator+= on location: C++ Location Values. (line 57) +* operator+= on position: C++ Location Values. (line 31) +* operator- on position: C++ Location Values. (line 36) +* operator-= on position: C++ Location Values. (line 35) +* operator<< on position: C++ Location Values. (line 40) +* options for invoking Bison: Invocation. (line 6) +* overflow of parser stack: Memory Management. (line 6) +* parse error: Error Reporting. (line 6) +* parse on parser: C++ Parser Interface. + (line 23) +* parse on YYParser: Java Parser Interface. + (line 54) +* parser: Bison Parser. (line 6) +* parser on parser: C++ Parser Interface. + (line 19) +* parser stack: Algorithm. (line 6) +* parser stack overflow: Memory Management. (line 6) +* parser state: Parser States. (line 6) +* pointed rule: Understanding. (line 107) +* polish notation calculator: RPN Calc. (line 6) +* precedence declarations: Precedence Decl. (line 6) +* precedence of operators: Precedence. (line 6) +* precedence, context-dependent: Contextual Precedence. + (line 6) +* precedence, unary operator: Contextual Precedence. + (line 6) +* preventing warnings about conflicts: Expect Decl. (line 6) +* Prologue <1>: Decl Summary. (line 129) +* Prologue <2>: Prologue. (line 6) +* Prologue: Decl Summary. (line 50) +* Prologue Alternatives: Prologue Alternatives. + (line 6) +* pure parser: Pure Decl. (line 6) +* push parser: Push Decl. (line 6) +* questions: FAQ. (line 6) +* recovering: Java Action Features. + (line 59) +* recovering on YYParser: Java Parser Interface. + (line 58) +* recovery from errors: Error Recovery. (line 6) +* recursive rule: Recursion. (line 6) +* reduce/reduce conflict: Reduce/Reduce. (line 6) +* reduce/reduce conflicts <1>: GLR Parsers. (line 6) +* reduce/reduce conflicts <2>: Simple GLR Parsers. (line 6) +* reduce/reduce conflicts: Merging GLR Parses. (line 6) +* reduction: Algorithm. (line 6) +* reentrant parser: Pure Decl. (line 6) +* requiring a version of Bison: Require Decl. (line 6) +* return YYABORT;: Java Action Features. + (line 43) +* return YYACCEPT;: Java Action Features. + (line 47) +* return YYERROR;: Java Action Features. + (line 51) +* return YYFAIL;: Java Action Features. + (line 55) +* reverse polish notation: RPN Calc. (line 6) +* right recursion: Recursion. (line 16) +* rpcalc: RPN Calc. (line 6) +* rule syntax: Rules. (line 6) +* rule, pointed: Understanding. (line 107) +* rule, useless: Understanding. (line 62) +* rules section for grammar: Grammar Rules. (line 6) +* running Bison (introduction): Rpcalc Generate. (line 6) +* semantic actions: Semantic Actions. (line 6) +* semantic value: Semantic Values. (line 6) +* semantic value type: Value Type. (line 6) +* semantic_value_type: C++ Parser Interface. + (line 15) +* set_debug_level on parser: C++ Parser Interface. + (line 32) +* set_debug_stream on parser: C++ Parser Interface. + (line 27) +* setDebugLevel on YYParser: Java Parser Interface. + (line 68) +* setDebugStream on YYParser: Java Parser Interface. + (line 63) +* shift/reduce conflicts <1>: Simple GLR Parsers. (line 6) +* shift/reduce conflicts <2>: Shift/Reduce. (line 6) +* shift/reduce conflicts: GLR Parsers. (line 6) +* shifting: Algorithm. (line 6) +* simple examples: Examples. (line 6) +* single-character literal: Symbols. (line 31) +* stack overflow: Memory Management. (line 6) +* stack, parser: Algorithm. (line 6) +* stages in using Bison: Stages. (line 6) +* start symbol: Language and Grammar. + (line 96) +* start symbol, declaring: Start Decl. (line 6) +* state (of parser): Parser States. (line 6) +* step on location: C++ Location Values. (line 60) +* string token: Symbols. (line 53) +* summary, action features: Action Features. (line 6) +* summary, Bison declaration: Decl Summary. (line 6) +* suppressing conflict warnings: Expect Decl. (line 6) +* symbol: Symbols. (line 6) +* symbol table example: Mfcalc Symbol Table. (line 6) +* symbols (abstract): Language and Grammar. + (line 47) +* symbols in Bison, table of: Table of Symbols. (line 6) +* syntactic grouping: Language and Grammar. + (line 47) +* syntax error: Error Reporting. (line 6) +* syntax of grammar rules: Rules. (line 6) +* terminal symbol: Symbols. (line 6) +* textual location <1>: Locations Overview. (line 6) +* textual location: Locations. (line 6) +* token: Language and Grammar. + (line 47) +* token type: Symbols. (line 6) +* token type names, declaring: Token Decl. (line 6) +* token, useless: Understanding. (line 62) +* toString on Location: Java Location Values. + (line 32) +* tracing the parser: Tracing. (line 6) +* unary operator precedence: Contextual Precedence. + (line 6) +* useless nonterminal: Understanding. (line 62) +* useless rule: Understanding. (line 62) +* useless token: Understanding. (line 62) +* using Bison: Stages. (line 6) +* value type, semantic: Value Type. (line 6) +* value types, declaring: Union Decl. (line 6) +* value types, nonterminals, declaring: Type Decl. (line 6) +* value, semantic: Semantic Values. (line 6) +* version requirement: Require Decl. (line 6) +* warnings, preventing: Expect Decl. (line 6) +* writing a lexical analyzer: Rpcalc Lexer. (line 6) +* YYABORT <1>: Table of Symbols. (line 221) +* YYABORT: Parser Function. (line 29) +* YYABORT;: Action Features. (line 28) +* YYACCEPT <1>: Table of Symbols. (line 230) +* YYACCEPT: Parser Function. (line 26) +* YYACCEPT;: Action Features. (line 32) +* YYBACKUP <1>: Table of Symbols. (line 238) +* YYBACKUP: Action Features. (line 36) +* yychar <1>: Action Features. (line 69) +* yychar <2>: Lookahead. (line 47) +* yychar <3>: Table of Symbols. (line 242) +* yychar: GLR Semantic Actions. + (line 10) +* yyclearin <1>: GLR Semantic Actions. + (line 18) +* yyclearin <2>: Table of Symbols. (line 248) +* yyclearin: Error Recovery. (line 97) +* yyclearin;: Action Features. (line 76) +* yydebug <1>: Tracing. (line 6) +* yydebug: Table of Symbols. (line 256) +* YYDEBUG <1>: Table of Symbols. (line 252) +* YYDEBUG: Tracing. (line 12) +* YYEMPTY: Action Features. (line 49) +* YYENABLE_NLS: Internationalization. + (line 27) +* YYEOF: Action Features. (line 52) +* yyerrok <1>: Table of Symbols. (line 261) +* yyerrok: Error Recovery. (line 92) +* yyerrok;: Action Features. (line 81) +* YYERROR: Action Features. (line 56) +* yyerror: Java Action Features. + (line 64) +* YYERROR: Table of Symbols. (line 265) +* yyerror <1>: Table of Symbols. (line 274) +* yyerror: Error Reporting. (line 6) +* YYERROR: GLR Semantic Actions. + (line 28) +* yyerror on Lexer: Java Scanner Interface. + (line 25) +* YYERROR;: Action Features. (line 56) +* YYERROR_VERBOSE: Table of Symbols. (line 278) +* YYINITDEPTH <1>: Table of Symbols. (line 285) +* YYINITDEPTH: Memory Management. (line 32) +* yylex <1>: Table of Symbols. (line 289) +* yylex: Lexical. (line 6) +* yylex on Lexer: Java Scanner Interface. + (line 30) +* yylex on parser: C++ Scanner Interface. + (line 12) +* YYLEX_PARAM: Table of Symbols. (line 294) +* yylloc <1>: Token Locations. (line 6) +* yylloc <2>: Table of Symbols. (line 300) +* yylloc <3>: GLR Semantic Actions. + (line 10) +* yylloc <4>: Action Features. (line 86) +* yylloc <5>: Lookahead. (line 47) +* yylloc: Actions and Locations. + (line 60) +* YYLLOC_DEFAULT: Location Default Action. + (line 6) +* YYLTYPE <1>: Table of Symbols. (line 310) +* YYLTYPE: Token Locations. (line 19) +* yylval <1>: Actions. (line 74) +* yylval <2>: Action Features. (line 92) +* yylval <3>: Table of Symbols. (line 314) +* yylval <4>: GLR Semantic Actions. + (line 10) +* yylval <5>: Lookahead. (line 47) +* yylval: Token Values. (line 6) +* YYMAXDEPTH <1>: Table of Symbols. (line 322) +* YYMAXDEPTH: Memory Management. (line 14) +* yynerrs <1>: Error Reporting. (line 92) +* yynerrs: Table of Symbols. (line 326) +* yyparse <1>: Table of Symbols. (line 332) +* yyparse: Parser Function. (line 6) +* YYPARSE_PARAM: Table of Symbols. (line 365) +* YYParser on YYParser: Java Parser Interface. + (line 41) +* YYPRINT: Tracing. (line 71) +* yypstate_delete <1>: Table of Symbols. (line 336) +* yypstate_delete: Parser Delete Function. + (line 6) +* yypstate_new <1>: Parser Create Function. + (line 6) +* yypstate_new: Table of Symbols. (line 344) +* yypull_parse <1>: Pull Parser Function. + (line 6) +* yypull_parse <2>: Table of Symbols. (line 351) +* yypull_parse: Pull Parser Function. + (line 14) +* yypush_parse <1>: Push Parser Function. + (line 15) +* yypush_parse: Table of Symbols. (line 358) +* YYRECOVERING <1>: Action Features. (line 64) +* YYRECOVERING <2>: Error Recovery. (line 109) +* YYRECOVERING <3>: Action Features. (line 64) +* YYRECOVERING: Table of Symbols. (line 371) +* YYSTACK_USE_ALLOCA: Table of Symbols. (line 376) +* YYSTYPE: Table of Symbols. (line 392) +* | <1>: Table of Symbols. (line 43) +* |: Rules. (line 49) + + + +Tag Table: +Node: Top1174 +Node: Introduction13739 +Node: Conditions15002 +Node: Copying16893 +Node: Concepts54431 +Node: Language and Grammar55612 +Node: Grammar in Bison61501 +Node: Semantic Values63430 +Node: Semantic Actions65536 +Node: GLR Parsers66723 +Node: Simple GLR Parsers69470 +Node: Merging GLR Parses76122 +Node: GLR Semantic Actions80691 +Node: Compiler Requirements82581 +Node: Locations Overview83317 +Node: Bison Parser84770 +Node: Stages87710 +Node: Grammar Layout88998 +Node: Examples90330 +Node: RPN Calc91533 +Node: Rpcalc Declarations92533 +Node: Rpcalc Rules94461 +Node: Rpcalc Input96277 +Node: Rpcalc Line97752 +Node: Rpcalc Expr98880 +Node: Rpcalc Lexer100847 +Node: Rpcalc Main103441 +Node: Rpcalc Error103848 +Node: Rpcalc Generate104881 +Node: Rpcalc Compile106016 +Node: Infix Calc106895 +Node: Simple Error Recovery109658 +Node: Location Tracking Calc111553 +Node: Ltcalc Declarations112249 +Node: Ltcalc Rules113338 +Node: Ltcalc Lexer115354 +Node: Multi-function Calc117677 +Node: Mfcalc Declarations119253 +Node: Mfcalc Rules121300 +Node: Mfcalc Symbol Table122695 +Node: Exercises128871 +Node: Grammar File129385 +Node: Grammar Outline130234 +Node: Prologue131084 +Node: Prologue Alternatives132873 +Node: Bison Declarations142558 +Node: Grammar Rules142986 +Node: Epilogue143457 +Node: Symbols144473 +Node: Rules151176 +Node: Recursion153655 +Node: Semantics155373 +Node: Value Type156472 +Node: Multiple Types157307 +Node: Actions158474 +Node: Action Types161889 +Node: Mid-Rule Actions163201 +Node: Locations169666 +Node: Location Type170317 +Node: Actions and Locations171103 +Node: Location Default Action173564 +Node: Declarations177284 +Node: Require Decl178811 +Node: Token Decl179130 +Node: Precedence Decl181556 +Node: Union Decl183566 +Node: Type Decl185340 +Node: Initial Action Decl186266 +Node: Destructor Decl187037 +Node: Expect Decl192501 +Node: Start Decl194494 +Node: Pure Decl194882 +Node: Push Decl196632 +Node: Decl Summary201131 +Ref: Decl Summary-Footnote-1218017 +Node: Multiple Parsers218221 +Node: Interface219860 +Node: Parser Function221178 +Node: Push Parser Function223194 +Node: Pull Parser Function224004 +Node: Parser Create Function224655 +Node: Parser Delete Function225478 +Node: Lexical226249 +Node: Calling Convention227681 +Node: Token Values230641 +Node: Token Locations231805 +Node: Pure Calling232699 +Node: Error Reporting234580 +Node: Action Features238710 +Node: Internationalization243012 +Node: Algorithm245553 +Node: Lookahead247919 +Node: Shift/Reduce250128 +Node: Precedence253023 +Node: Why Precedence253679 +Node: Using Precedence255552 +Node: Precedence Examples256529 +Node: How Precedence257239 +Node: Contextual Precedence258396 +Node: Parser States260192 +Node: Reduce/Reduce261436 +Node: Mystery Conflicts264977 +Node: Generalized LR Parsing268684 +Node: Memory Management273303 +Node: Error Recovery275516 +Node: Context Dependency280819 +Node: Semantic Tokens281668 +Node: Lexical Tie-ins284738 +Node: Tie-in Recovery286315 +Node: Debugging288492 +Node: Understanding289158 +Node: Tracing300317 +Node: Invocation304419 +Node: Bison Options305818 +Node: Option Cross Key312822 +Node: Yacc Library313874 +Node: Other Languages314699 +Node: C++ Parsers315026 +Node: C++ Bison Interface315523 +Node: C++ Semantic Values316791 +Ref: C++ Semantic Values-Footnote-1317733 +Node: C++ Location Values317886 +Node: C++ Parser Interface320259 +Node: C++ Scanner Interface321976 +Node: A Complete C++ Example322678 +Node: Calc++ --- C++ Calculator323620 +Node: Calc++ Parsing Driver324134 +Node: Calc++ Parser327915 +Node: Calc++ Scanner331705 +Node: Calc++ Top Level335131 +Node: Java Parsers335780 +Node: Java Bison Interface336457 +Node: Java Semantic Values338420 +Node: Java Location Values340034 +Node: Java Parser Interface341590 +Node: Java Scanner Interface344828 +Node: Java Action Features347013 +Node: Java Differences349740 +Ref: Java Differences-Footnote-1352315 +Node: Java Declarations Summary352465 +Node: FAQ356713 +Node: Memory Exhausted357660 +Node: How Can I Reset the Parser357970 +Node: Strings are Destroyed360239 +Node: Implementing Gotos/Loops361828 +Node: Multiple start-symbols363111 +Node: Secure? Conform?364656 +Node: I can't build Bison365104 +Node: Where can I find help?365822 +Node: Bug Reports366615 +Node: More Languages368076 +Node: Beta Testing368434 +Node: Mailing Lists369308 +Node: Table of Symbols369519 +Node: Glossary384901 +Node: Copying This Manual391798 +Node: Index414191 + +End Tag Table |