Index: bison/src/bison/2.4.1/bison-2.4.1-src/doc/bison.info |
=================================================================== |
--- bison/src/bison/2.4.1/bison-2.4.1-src/doc/bison.info (revision 0) |
+++ bison/src/bison/2.4.1/bison-2.4.1-src/doc/bison.info (revision 0) |
@@ -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 |
+***** |
+ |
+ [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 |