variables: use `parse.assert' instead of `assert'.

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 70f62672a223abf88609df4c6e4280426568554a..fbe9ac9d35990e45af2de3fc9391d551b0a6d27b 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -34,8 +34,8 @@ This manual (@value{UPDATED}) is for @acronym{GNU} Bison (version
 @value{VERSION}), the @acronym{GNU} parser generator.
 
 Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998,
 @value{VERSION}), the @acronym{GNU} parser generator.
 
 Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998,

-1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software
-Foundation, Inc.
+1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free
+Software Foundation, Inc.

 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document


@@ -89,76 +89,76 @@ Cover art by Etienne Suvasa.
 @menu
 * Introduction::
 * Conditions::
 @menu
 * Introduction::
 * Conditions::

-* Copying::           The @acronym{GNU} General Public License says
-                        how you can copy and share Bison
+* Copying::             The @acronym{GNU} General Public License says
+                          how you can copy and share Bison.

 
 Tutorial sections:
 
 Tutorial sections:

-* Concepts::          Basic concepts for understanding Bison.
-* Examples::          Three simple explained examples of using Bison.
+* Concepts::            Basic concepts for understanding Bison.
+* Examples::            Three simple explained examples of using Bison.

 
 Reference sections:
 
 Reference sections:

-* Grammar File::      Writing Bison declarations and rules.
-* Interface::         C-language interface to the parser function @code{yyparse}.
-* Algorithm::         How the Bison parser works at run-time.
-* Error Recovery::    Writing rules for error recovery.
+* Grammar File::        Writing Bison declarations and rules.
+* Interface::           C-language interface to the parser function @code{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
 * 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.
+                          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.

 
 @detailmenu
  --- The Detailed Node Listing ---
 
 The Concepts of Bison
 
 
 @detailmenu
  --- 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.
+* 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 @acronym{GLR} Parsers
 
 
 Writing @acronym{GLR} Parsers
 

-* Simple GLR Parsers::      Using @acronym{GLR} parsers on unambiguous grammars.
-* Merging GLR Parses::      Using @acronym{GLR} parsers to resolve ambiguities.
-* GLR Semantic Actions::    Deferred semantic actions have special concerns.
-* Compiler Requirements::   @acronym{GLR} parsers require a modern C compiler.
+* Simple GLR Parsers::     Using @acronym{GLR} parsers on unambiguous grammars.
+* Merging GLR Parses::     Using @acronym{GLR} parsers to resolve ambiguities.
+* GLR Semantic Actions::   Deferred semantic actions have special concerns.
+* Compiler Requirements::  @acronym{GLR} parsers require a modern C compiler.

 
 Examples
 
 
 Examples
 

-* RPN Calc::          Reverse polish notation calculator;
-                        a first example with no operator precedence.
-* Infix Calc::        Infix (algebraic) notation calculator.
-                        Operator precedence is introduced.
+* 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 @@@var{n} and @@$.
 * Simple Error Recovery::  Continuing after syntax errors.
 * Location Tracking Calc:: Demonstrating the use of @@@var{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.
+* 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
 
 
 Reverse Polish Notation Calculator
 

-* Decls: Rpcalc Decls.  Prologue (declarations) for rpcalc.
-* Rules: Rpcalc Rules.  Grammar Rules for rpcalc, with explanation.
-* Lexer: Rpcalc Lexer.  The lexical analyzer.
-* Main: Rpcalc Main.    The controlling function.
-* Error: Rpcalc Error.  The error reporting function.
-* Gen: Rpcalc Gen.      Running Bison on the grammar file.
-* Comp: Rpcalc Compile. Run the C compiler on the output code.
+* 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 @code{rpcalc}
 
 
 Grammar Rules for @code{rpcalc}
 


@@ -168,15 +168,15 @@ Grammar Rules for @code{rpcalc}
 
 Location Tracking Calculator: @code{ltcalc}
 
 
 Location Tracking Calculator: @code{ltcalc}
 

-* Decls: Ltcalc Decls.  Bison and C declarations for ltcalc.
-* Rules: Ltcalc Rules.  Grammar rules for ltcalc, with explanations.
-* Lexer: Ltcalc Lexer.  The lexical analyzer.
+* Ltcalc Declarations::    Bison and C declarations for ltcalc.
+* Ltcalc Rules::           Grammar rules for ltcalc, with explanations.
+* Ltcalc Lexer::           The lexical analyzer.

 
 Multi-Function Calculator: @code{mfcalc}
 
 
 Multi-Function Calculator: @code{mfcalc}
 

-* Decl: Mfcalc Decl.      Bison declarations for multi-function calculator.
-* Rules: Mfcalc Rules.    Grammar rules for the calculator.
-* Symtab: Mfcalc Symtab.  Symbol table management subroutines.
+* 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
 
 
 Bison Grammar Files
 


@@ -191,11 +191,11 @@ Bison Grammar Files
 
 Outline of a Bison Grammar
 
 
 Outline of a Bison Grammar
 

-* Prologue::          Syntax and usage of the prologue.
+* Prologue::              Syntax and usage of the prologue.

 * Prologue Alternatives:: Syntax and usage of alternatives to 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.
+* 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
 
 
 Defining Language Semantics
 


@@ -230,24 +230,28 @@ Bison Declarations
 
 Parser C-Language Interface
 
 
 Parser C-Language Interface
 

-* Parser Function::   How to call @code{yyparse} and what it returns.
-* Lexical::           You must supply a function @code{yylex}
-                        which reads tokens.
-* Error Reporting::   You must supply a function @code{yyerror}.
-* Action Features::   Special features for use in actions.
-* Internationalization::  How to let the parser speak in the user's
-                        native language.
+* Parser Function::         How to call @code{yyparse} and what it returns.
+* Push Parser Function::    How to call @code{yypush_parse} and what it returns.
+* Pull Parser Function::    How to call @code{yypull_parse} and what it returns.
+* Parser Create Function::  How to call @code{yypstate_new} and what it returns.
+* Parser Delete Function::  How to call @code{yypstate_delete} and what it returns.
+* Lexical::                 You must supply a function @code{yylex}
+                              which reads tokens.
+* Error Reporting::         You must supply a function @code{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 @code{yylex}
 
 * Calling Convention::  How @code{yyparse} calls @code{yylex}.
 
 The Lexical Analyzer Function @code{yylex}
 
 * Calling Convention::  How @code{yyparse} calls @code{yylex}.

-* Token Values::      How @code{yylex} must return the semantic value
-                        of the token it has read.
-* Token Locations::   How @code{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 (@pxref{Pure Decl, ,A Pure (Reentrant) Parser}).
+* Token Values::        How @code{yylex} must return the semantic value
+                          of the token it has read.
+* Token Locations::     How @code{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
+                          (@pxref{Pure Decl, ,A Pure (Reentrant) Parser}).

 
 The Bison Parser Algorithm
 
 
 The Bison Parser Algorithm
 


@@ -257,7 +261,7 @@ The Bison Parser Algorithm
 * 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.
 * 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.
+* 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.
 
 * Generalized LR Parsing::  Parsing arbitrary context-free grammars.
 * Memory Management:: What happens when memory is exhausted.  How to avoid it.
 


@@ -312,33 +316,33 @@ A Complete C++ Example
 
 Java Parsers
 
 
 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
+* 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
 
 
 Frequently Asked Questions
 

-* Memory Exhausted::           Breaking the Stack Limits
-* How Can I Reset the Parser:: @code{yyparse} Keeps some State
-* Strings are Destroyed::      @code{yylval} Loses Track of Strings
-* Implementing Gotos/Loops::   Control Flow in the Calculator
-* Multiple start-symbols::     Factoring closely related grammars
-* Secure?  Conform?::          Is Bison @acronym{POSIX} safe?
-* I can't build Bison::        Troubleshooting
-* Where can I find help?::     Troubleshouting
-* Bug Reports::                Troublereporting
-* Other Languages::            Parsers in Java and others
-* Beta Testing::               Experimenting development versions
-* Mailing Lists::              Meeting other Bison users
+* Memory Exhausted::            Breaking the Stack Limits
+* How Can I Reset the Parser::  @code{yyparse} Keeps some State
+* Strings are Destroyed::       @code{yylval} Loses Track of Strings
+* Implementing Gotos/Loops::    Control Flow in the Calculator
+* Multiple start-symbols::      Factoring closely related grammars
+* Secure?  Conform?::           Is Bison @acronym{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
 

-* Copying This Manual::        License for copying this manual.
+* Copying This Manual::         License for copying this manual.

 
 @end detailmenu
 @end menu
 
 @end detailmenu
 @end menu


@@ -418,19 +422,19 @@ 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
 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.
+* 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.

 @end menu
 
 @node Language and Grammar
 @end menu
 
 @node Language and Grammar


@@ -746,10 +750,10 @@ user-defined function on the resulting values to produce an arbitrary
 merged result.
 
 @menu
 merged result.
 
 @menu

-* Simple GLR Parsers::      Using @acronym{GLR} parsers on unambiguous grammars.
-* Merging GLR Parses::      Using @acronym{GLR} parsers to resolve ambiguities.
-* GLR Semantic Actions::    Deferred semantic actions have special concerns.
-* Compiler Requirements::   @acronym{GLR} parsers require a modern C compiler.
+* Simple GLR Parsers::     Using @acronym{GLR} parsers on unambiguous grammars.
+* Merging GLR Parses::     Using @acronym{GLR} parsers to resolve ambiguities.
+* GLR Semantic Actions::   Deferred semantic actions have special concerns.
+* Compiler Requirements::  @acronym{GLR} parsers require a modern C compiler.

 @end menu
 
 @node Simple GLR Parsers
 @end menu
 
 @node Simple GLR Parsers


@@ -1377,15 +1381,15 @@ languages are written the same way.  You can copy these examples into a
 source file to try them.
 
 @menu
 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.
+* 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 @@@var{n} and @@$.
 * Simple Error Recovery::  Continuing after syntax errors.
 * Location Tracking Calc:: Demonstrating the use of @@@var{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.
+* 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.

 @end menu
 
 @node RPN Calc
 @end menu
 
 @node RPN Calc


@@ -1404,16 +1408,16 @@ The source code for this calculator is named @file{rpcalc.y}.  The
 @samp{.y} extension is a convention used for Bison input files.
 
 @menu
 @samp{.y} extension is a convention used for Bison input files.
 
 @menu

-* Decls: Rpcalc Decls.  Prologue (declarations) for rpcalc.
-* Rules: Rpcalc Rules.  Grammar Rules for rpcalc, with explanation.
-* Lexer: Rpcalc Lexer.  The lexical analyzer.
-* Main: Rpcalc Main.    The controlling function.
-* Error: Rpcalc Error.  The error reporting function.
-* Gen: Rpcalc Gen.      Running Bison on the grammar file.
-* Comp: Rpcalc Compile. Run the C compiler on the output code.
+* 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.

 @end menu
 
 @end menu
 

-@node Rpcalc Decls
+@node Rpcalc Declarations

 @subsection Declarations for @code{rpcalc}
 
 Here are the C and Bison declarations for the reverse polish notation
 @subsection Declarations for @code{rpcalc}
 
 Here are the C and Bison declarations for the reverse polish notation


@@ -1663,7 +1667,7 @@ therefore, @code{NUM} becomes a macro for @code{yylex} to use.
 The semantic value of the token (if it has one) is stored into the
 global variable @code{yylval}, which is where the Bison parser will look
 for it.  (The C data type of @code{yylval} is @code{YYSTYPE}, which was
 The semantic value of the token (if it has one) is stored into the
 global variable @code{yylval}, which is where the Bison parser will look
 for it.  (The C data type of @code{yylval} is @code{YYSTYPE}, which was

-defined at the beginning of the grammar; @pxref{Rpcalc Decls,
+defined at the beginning of the grammar; @pxref{Rpcalc Declarations,

 ,Declarations for @code{rpcalc}}.)
 
 A token type code of zero is returned if the end-of-input is encountered.
 ,Declarations for @code{rpcalc}}.)
 
 A token type code of zero is returned if the end-of-input is encountered.


@@ -1759,7 +1763,7 @@ 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.
 
 cause the calculator program to exit.  This is not clean behavior for a
 real calculator, but it is adequate for the first example.
 

-@node Rpcalc Gen
+@node Rpcalc Generate

 @subsection Running Bison to Make the Parser
 @cindex running Bison (introduction)
 
 @subsection Running Bison to Make the Parser
 @cindex running Bison (introduction)
 


@@ -1979,12 +1983,12 @@ most of the work needed to use locations will be done in the lexical
 analyzer.
 
 @menu
 analyzer.
 
 @menu

-* Decls: Ltcalc Decls.  Bison and C declarations for ltcalc.
-* Rules: Ltcalc Rules.  Grammar rules for ltcalc, with explanations.
-* Lexer: Ltcalc Lexer.  The lexical analyzer.
+* Ltcalc Declarations::    Bison and C declarations for ltcalc.
+* Ltcalc Rules::           Grammar rules for ltcalc, with explanations.
+* Ltcalc Lexer::           The lexical analyzer.

 @end menu
 
 @end menu
 

-@node Ltcalc Decls
+@node Ltcalc Declarations

 @subsection Declarations for @code{ltcalc}
 
 The C and Bison declarations for the location tracking calculator are
 @subsection Declarations for @code{ltcalc}
 
 The C and Bison declarations for the location tracking calculator are


@@ -2220,12 +2224,12 @@ $
 Note that multiple assignment and nested function calls are permitted.
 
 @menu
 Note that multiple assignment and nested function calls are permitted.
 
 @menu

-* Decl: Mfcalc Decl.      Bison declarations for multi-function calculator.
-* Rules: Mfcalc Rules.    Grammar rules for the calculator.
-* Symtab: Mfcalc Symtab.  Symbol table management subroutines.
+* Mfcalc Declarations::    Bison declarations for multi-function calculator.
+* Mfcalc Rules::           Grammar rules for the calculator.
+* Mfcalc Symbol Table::    Symbol table management subroutines.

 @end menu
 
 @end menu
 

-@node Mfcalc Decl
+@node Mfcalc Declarations

 @subsection Declarations for @code{mfcalc}
 
 Here are the C and Bison declarations for the multi-function calculator.
 @subsection Declarations for @code{mfcalc}
 
 Here are the C and Bison declarations for the multi-function calculator.


@@ -2321,7 +2325,7 @@ exp:      NUM                @{ $$ = $1;                         @}
 %%
 @end smallexample
 
 %%
 @end smallexample
 

-@node Mfcalc Symtab
+@node Mfcalc Symbol Table

 @subsection The @code{mfcalc} Symbol Table
 @cindex symbol table example
 
 @subsection The @code{mfcalc} Symbol Table
 @cindex symbol table example
 


@@ -2634,11 +2638,11 @@ As a @acronym{GNU} extension, @samp{//} introduces a comment that
 continues until end of line.
 
 @menu
 continues until end of line.
 
 @menu

-* Prologue::          Syntax and usage of the prologue.
+* Prologue::              Syntax and usage of the prologue.

 * Prologue Alternatives:: Syntax and usage of alternatives to 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.
+* 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.

 @end menu
 
 @node Prologue
 @end menu
 
 @node Prologue


@@ -4836,10 +4840,10 @@ traditional Yacc prologue for C/C++, see @ref{Prologue Alternatives}.
 @end deffn
 
 @deffn {Directive} %debug
 @end deffn
 
 @deffn {Directive} %debug

-In the parser file, define the macro @code{YYDEBUG} to 1 if it is not
-already defined, so that the debugging facilities are compiled.
-@end deffn
+Instrument the output parser for traces.  Obsoleted by @samp{%define
+parse.trace}.

 @xref{Tracing, ,Tracing Your Parser}.
 @xref{Tracing, ,Tracing Your Parser}.

+@end deffn

 
 @deffn {Directive} %define @var{variable}
 @deffnx {Directive} %define @var{variable} "@var{value}"
 
 @deffn {Directive} %define @var{variable}
 @deffnx {Directive} %define @var{variable} "@var{value}"


@@ -4872,7 +4876,7 @@ target language and/or parser skeleton.
 
 Some of the accepted @var{variable}s are:
 
 
 Some of the accepted @var{variable}s are:
 

-@itemize @bullet
+@table @code

 @item api.pure
 @findex %define api.pure
 
 @item api.pure
 @findex %define api.pure
 


@@ -4997,9 +5001,43 @@ For example, if you specify:
 The parser namespace is @code{foo} and @code{yylex} is referenced as
 @code{bar::lex}.
 @end itemize
 The parser namespace is @code{foo} and @code{yylex} is referenced as
 @code{bar::lex}.
 @end itemize

+@c namespace
+
+@item parse.assert
+@findex %define parse.assert
+
+@itemize
+@item Languages(s): C++
+
+@item Purpose: Issue runtime assertions to catch invalid uses.
+In C++, when variants are used, symbols must be constructed and
+destroyed properly.  This option checks these constraints.
+
+@item Accepted Values: Boolean
+
+@item Default Value: @code{false}

 @end itemize
 @end itemize

+@c parse.assert
+
+@item parse.trace
+@findex %define parse.trace

 
 

+@itemize
+@item Languages(s): C, C++
+
+@item Purpose: Require parser instrumentation for tracing.
+In C/C++, define the macro @code{YYDEBUG} to 1 in the parser file if it
+is not already defined, so that the debugging facilities are compiled.
+@xref{Tracing, ,Tracing Your Parser}.
+
+@item Accepted Values: Boolean
+
+@item Default Value: @code{false}
+@end itemize
+@end table
+@c parse.trace

 @end deffn
 @end deffn

+@c %define

 
 @deffn {Directive} %defines
 Write a header file containing macro definitions for the token type
 
 @deffn {Directive} %defines
 Write a header file containing macro definitions for the token type


@@ -5229,19 +5267,17 @@ 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
 in the grammar file, you are likely to run into trouble.
 
 @menu

-* Parser Function::   How to call @code{yyparse} and what it returns.
-* Push Parser Function::  How to call @code{yypush_parse} and what it returns.
-* Pull Parser Function::  How to call @code{yypull_parse} and what it returns.
-* Parser Create Function::  How to call @code{yypstate_new} and what it
-                        returns.
-* Parser Delete Function::  How to call @code{yypstate_delete} and what it
-                        returns.
-* Lexical::           You must supply a function @code{yylex}
-                        which reads tokens.
-* Error Reporting::   You must supply a function @code{yyerror}.
-* Action Features::   Special features for use in actions.
-* Internationalization::  How to let the parser speak in the user's
-                        native language.
+* Parser Function::         How to call @code{yyparse} and what it returns.
+* Push Parser Function::    How to call @code{yypush_parse} and what it returns.
+* Pull Parser Function::    How to call @code{yypull_parse} and what it returns.
+* Parser Create Function::  How to call @code{yypstate_new} and what it returns.
+* Parser Delete Function::  How to call @code{yypstate_delete} and what it returns.
+* Lexical::                 You must supply a function @code{yylex}
+                              which reads tokens.
+* Error Reporting::         You must supply a function @code{yyerror}.
+* Action Features::         Special features for use in actions.
+* Internationalization::    How to let the parser speak in the user's
+                              native language.

 @end menu
 
 @node Parser Function
 @end menu
 
 @node Parser Function


@@ -5408,13 +5444,13 @@ that need it.  @xref{Invocation, ,Invoking Bison}.
 
 @menu
 * Calling Convention::  How @code{yyparse} calls @code{yylex}.
 
 @menu
 * Calling Convention::  How @code{yyparse} calls @code{yylex}.

-* Token Values::      How @code{yylex} must return the semantic value
-                        of the token it has read.
-* Token Locations::   How @code{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 (@pxref{Pure Decl, ,A Pure (Reentrant) Parser}).
+* Token Values::        How @code{yylex} must return the semantic value
+                          of the token it has read.
+* Token Locations::     How @code{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
+                          (@pxref{Pure Decl, ,A Pure (Reentrant) Parser}).

 @end menu
 
 @node Calling Convention
 @end menu
 
 @node Calling Convention


@@ -6057,7 +6093,7 @@ This kind of parser is known in the literature as a bottom-up parser.
 * 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.
 * 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.
+* 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.
 @end menu
 * Generalized LR Parsing::  Parsing arbitrary context-free grammars.
 * Memory Management:: What happens when memory is exhausted.  How to avoid it.
 @end menu


@@ -7648,15 +7684,21 @@ Use the @samp{-t} option when you run Bison (@pxref{Invocation,
 
 @item the directive @samp{%debug}
 @findex %debug
 
 @item the directive @samp{%debug}
 @findex %debug

-Add the @code{%debug} directive (@pxref{Decl Summary, ,Bison
-Declaration Summary}).  This is a Bison extension, which will prove
-useful when Bison will output parsers for languages that don't use a
-preprocessor.  Unless @acronym{POSIX} and Yacc portability matter to
-you, this is
-the preferred solution.
+Add the @code{%debug} directive (@pxref{Decl Summary, ,Bison Declaration
+Summary}).  This Bison extension is maintained for backward
+compatibility with previous versions of Bison.
+
+@item the variable @samp{parse.trace}
+@findex %define parse.trace
+Add the @samp{%define parse.trace} directive (@pxref{Decl Summary,
+,Bison Declaration Summary}), or pass the @option{-Dparse.trace} option
+(@pxref{Bison Options}).  This is a Bison extension, which is especially
+useful for languages that don't use a preprocessor.  Unless
+@acronym{POSIX} and Yacc portability matter to you, this is the
+preferred solution.

 @end table
 
 @end table
 

-We suggest that you always enable the debug option so that debugging is
+We suggest that you always enable the trace option so that debugging is

 always possible.
 
 The trace facility outputs messages with macro calls of the form
 always possible.
 
 The trace facility outputs messages with macro calls of the form


@@ -7713,7 +7755,7 @@ standard I/O stream, the numeric code for the token type, and the token
 value (from @code{yylval}).
 
 Here is an example of @code{YYPRINT} suitable for the multi-function
 value (from @code{yylval}).
 
 Here is an example of @code{YYPRINT} suitable for the multi-function

-calculator (@pxref{Mfcalc Decl, ,Declarations for @code{mfcalc}}):
+calculator (@pxref{Mfcalc Declarations, ,Declarations for @code{mfcalc}}):

 
 @smallexample
 %@{
 
 @smallexample
 %@{


@@ -7841,8 +7883,8 @@ traditional Yacc grammars.  If your grammar uses a Bison extension
 like @samp{%glr-parser}, Bison might not be Yacc-compatible even if
 this option is specified.
 
 like @samp{%glr-parser}, Bison might not be Yacc-compatible even if
 this option is specified.
 

-@item -W
-@itemx --warnings
+@item -W [@var{category}]
+@itemx --warnings[=@var{category}]

 Output warnings falling in @var{category}.  @var{category} can be one
 of:
 @table @code
 Output warnings falling in @var{category}.  @var{category} can be one
 of:
 @table @code


@@ -7999,7 +8041,7 @@ Specify the @var{file} for the parser file.
 The other output files' names are constructed from @var{file} as
 described under the @samp{-v} and @samp{-d} options.
 
 The other output files' names are constructed from @var{file} as
 described under the @samp{-v} and @samp{-d} options.
 

-@item -g[@var{file}]
+@item -g [@var{file}]

 @itemx --graph[=@var{file}]
 Output a graphical representation of the @acronym{LALR}(1) grammar
 automaton computed by Bison, in @uref{http://www.graphviz.org/, Graphviz}
 @itemx --graph[=@var{file}]
 Output a graphical representation of the @acronym{LALR}(1) grammar
 automaton computed by Bison, in @uref{http://www.graphviz.org/, Graphviz}


@@ -8008,7 +8050,7 @@ automaton computed by Bison, in @uref{http://www.graphviz.org/, Graphviz}
 If omitted and the grammar file is @file{foo.y}, the output file will be
 @file{foo.dot}.
 
 If omitted and the grammar file is @file{foo.y}, the output file will be
 @file{foo.dot}.
 

-@item -x[@var{file}]
+@item -x [@var{file}]

 @itemx --xml[=@var{file}]
 Output an XML report of the @acronym{LALR}(1) automaton computed by Bison.
 @code{@var{file}} is optional.
 @itemx --xml[=@var{file}]
 Output an XML report of the @acronym{LALR}(1) automaton computed by Bison.
 @code{@var{file}} is optional.


@@ -8021,12 +8063,11 @@ More user feedback will help to stabilize it.)
 @node Option Cross Key
 @section Option Cross Key
 
 @node Option Cross Key
 @section Option Cross Key
 

-@c FIXME: How about putting the directives too?

 Here is a list of options, alphabetized by long option, to help you find
 the corresponding short option.
 
 Here is a list of options, alphabetized by long option, to help you find
 the corresponding short option.
 

-@multitable {@option{--defines=@var{defines-file}}} {@option{-b @var{file-prefix}XXX}}
-@headitem Long Option @tab Short Option
+@multitable {@option{--defines=@var{defines-file}}} {@option{-D @var{name}[=@var{value}]}} {@code{%nondeterministic-parser}}
+@headitem Long Option @tab Short Option @tab Bison Directive

 @include cross-options.texi
 @end multitable
 
 @include cross-options.texi
 @end multitable
 


@@ -8538,7 +8579,7 @@ error messages.
 
 @comment file: calc++-parser.yy
 @example
 
 @comment file: calc++-parser.yy
 @example

-%debug
+%define parse.trace

 %error-verbose
 @end example
 
 %error-verbose
 @end example
 


@@ -8798,14 +8839,14 @@ main (int argc, char *argv[])
 @section Java Parsers
 
 @menu
 @section 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
+* 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

 @end menu
 
 @node Java Bison Interface
 @end menu
 
 @node Java Bison Interface


@@ -8846,11 +8887,13 @@ No header file can be generated for Java parsers.  Do not use the
 @code{%defines} directive or the @option{-d}/@option{--defines} options.
 
 @c FIXME: Possible code change.
 @code{%defines} directive or the @option{-d}/@option{--defines} options.
 
 @c FIXME: Possible code change.

-Currently, support for debugging is always compiled
-in.  Thus the @code{%debug} and @code{%token-table} directives and the
+Currently, support for tracing is always compiled
+in.  Thus the @samp{%define parse.trace} and @samp{%token-table}
+directives and the

 @option{-t}/@option{--debug} and @option{-k}/@option{--token-table}
 options have no effect.  This may change in the future to eliminate
 @option{-t}/@option{--debug} and @option{-k}/@option{--token-table}
 options have no effect.  This may change in the future to eliminate

-unused code in the generated parser, so use @code{%debug} explicitly
+unused code in the generated parser, so use @samp{%define parse.trace}
+explicitly

 if needed.  Also, in the future the
 @code{%token-table} directive might enable a public interface to
 access the token names and codes.
 if needed.  Also, in the future the
 @code{%token-table} directive might enable a public interface to
 access the token names and codes.


@@ -8933,7 +8976,7 @@ The first, inclusive, position of the range, and the first beyond.
 @end deftypeivar
 
 @deftypeop {Constructor} {Location} {} Location (Position @var{loc})
 @end deftypeivar
 
 @deftypeop {Constructor} {Location} {} Location (Position @var{loc})

-Create a @code{Location} denoting an empty range located at a given point. 
+Create a @code{Location} denoting an empty range located at a given point.

 @end deftypeop
 
 @deftypeop {Constructor} {Location} {} Location (Position @var{begin}, Position @var{end})
 @end deftypeop
 
 @deftypeop {Constructor} {Location} {} Location (Position @var{begin}, Position @var{end})


@@ -9173,12 +9216,12 @@ Return immediately from the parser, indicating success.
 @end deffn
 
 @deffn {Statement} {return YYERROR;}
 @end deffn
 
 @deffn {Statement} {return YYERROR;}

-Start error recovery without printing an error message. 
+Start error recovery without printing an error message.

 @xref{Error Recovery}.
 @end deffn
 
 @deffn {Statement} {return YYFAIL;}
 @xref{Error Recovery}.
 @end deffn
 
 @deffn {Statement} {return YYFAIL;}

-Print an error message and start error recovery. 
+Print an error message and start error recovery.

 @xref{Error Recovery}.
 @end deffn
 
 @xref{Error Recovery}.
 @end deffn
 


@@ -9895,10 +9938,6 @@ Insert @var{code} verbatim into output parser source.
 Equip the parser for debugging.  @xref{Decl Summary}.
 @end deffn
 
 Equip the parser for debugging.  @xref{Decl Summary}.
 @end deffn
 

-@deffn {Directive} %debug
-Equip the parser for debugging.  @xref{Decl Summary}.
-@end deffn
-

 @ifset defaultprec
 @deffn {Directive} %default-prec
 Assign a precedence to rules that lack an explicit @samp{%prec}
 @ifset defaultprec
 @deffn {Directive} %default-prec
 Assign a precedence to rules that lack an explicit @samp{%prec}


@@ -10481,7 +10520,7 @@ grammatically indivisible.  The piece of text it represents is a token.
 @c LocalWords: akim fn cp syncodeindex vr tp synindex dircategory direntry
 @c LocalWords: ifset vskip pt filll insertcopying sp ISBN Etienne Suvasa
 @c LocalWords: ifnottex yyparse detailmenu GLR RPN Calc var Decls Rpcalc
 @c LocalWords: akim fn cp syncodeindex vr tp synindex dircategory direntry
 @c LocalWords: ifset vskip pt filll insertcopying sp ISBN Etienne Suvasa
 @c LocalWords: ifnottex yyparse detailmenu GLR RPN Calc var Decls Rpcalc

-@c LocalWords: rpcalc Lexer Gen Comp Expr ltcalc mfcalc Decl Symtab yylex
+@c LocalWords: rpcalc Lexer Expr ltcalc mfcalc yylex

 @c LocalWords: yyerror pxref LR yylval cindex dfn LALR samp gpl BNF xref
 @c LocalWords: const int paren ifnotinfo AC noindent emph expr stmt findex
 @c LocalWords: glr YYSTYPE TYPENAME prog dprec printf decl init stmtMerge
 @c LocalWords: yyerror pxref LR yylval cindex dfn LALR samp gpl BNF xref
 @c LocalWords: const int paren ifnotinfo AC noindent emph expr stmt findex
 @c LocalWords: glr YYSTYPE TYPENAME prog dprec printf decl init stmtMerge