Index: doc/bison.texinfo
===================================================================
RCS file: /sources/bison/bison/doc/bison.texinfo,v
retrieving revision 1.233
diff -u -r1.233 bison.texinfo
--- doc/bison.texinfo	12 Aug 2007 02:12:29 -0000	1.233
+++ doc/bison.texinfo	13 Aug 2007 01:56:22 -0000
@@ -224,6 +224,7 @@
 * 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
@@ -3978,6 +3979,7 @@
 * 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.
 @end menu
 
@@ -4510,8 +4512,9 @@
 @code{yylloc} become local variables in @code{yyparse}, and a different
 calling convention is used for the lexical analyzer function
 @code{yylex}.  @xref{Pure Calling, ,Calling Conventions for Pure
-Parsers}, for the details of this.  The variable @code{yynerrs} also
-becomes local in @code{yyparse} (@pxref{Error Reporting, ,The Error
+Parsers}, for the details of this.  The variable @code{yynerrs} 
+becomes local in @code{yyparse} in pull mode but it becomes a member 
+of yypstate in push mode.  (@pxref{Error Reporting, ,The Error
 Reporting Function @code{yyerror}}).  The convention for calling
 @code{yyparse} itself is unchanged.
 
@@ -4519,6 +4522,112 @@
 You can generate either a pure parser or a nonreentrant parser from any
 valid grammar.
 
address@hidden Push Decl
address@hidden A Push Parser
address@hidden push parser
address@hidden push parser
address@hidden %push-parser
+
+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 Bison declaration 
address@hidden says that you want the parser to be a push parser.
+It looks like this:
+
address@hidden
+%push-parser
address@hidden example
+
+In almost all cases, you want to ensure that your push parser is also
+a pure parser (@pxref{Pure Decl, ,A Pure (Reentrant) Parser}).  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:
+
address@hidden
+%pure-parser
+%push-parser
address@hidden example
+
+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.  @code{yypstate} is a structure that the generated 
+parser uses to store the parser's state.  @code{yypstate_new} is the 
+function that will create a new parser instance.  @code{yypstate_delete}
+will free the resources associated with the corresponding parser instance.
+Finally, @code{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:
+
address@hidden
+int status;
+yypstate *ps = yypstate_new ();
+do @{
+  status = yypush_parse (ps, yylex (), NULL);
address@hidden while (status == YYPUSH_MORE);
+yypstate_delete (ps);
address@hidden example
+
+If the user decided to use an impure push parser, a few things about
+the generated parser will change.  The @code{yychar} variable becomes 
+a global variable instead of a variable in the @code{yypush_parse} function.
+For this reason, the signature of the @code{yypush_parse} function is
+changed to remove the token as a parameter.  A nonreentrant push parser 
+example would thus look like this:
+
address@hidden
+extern int yychar;
+int status;
+yypstate *ps = yypstate_new ();
+do @{
+  yychar = yylex ();
+  status = yypush_parse (ps);
address@hidden while (status == YYPUSH_MORE);
+yypstate_delete (ps);
address@hidden example
+
+That's it. Notice the next token is put into the global variable @code{yychar} 
+for use by the next invocation of the @code{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 @code{%push-parser} declaration with the 
address@hidden declaration.  Doing this will create all of the 
+symbols mentioned earlier along with the two extra symbols, @code{yyparse} 
+and @code{yypull_parse}.  @code{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 @code{yypull_parse}.  This makes the 
address@hidden function that is generated with the @code{%push-pull-parser} 
+declaration slower than the normal @code{yyparse} function.  If the user 
+calls the @code{yypull_parse} function it will parse the rest of the input 
+stream.  It is possible to @code{yypush_parse} tokens to select a subgrammar 
+and then @code{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 @code{yypull_parse} function that knows when to quit looking 
+for input.  An example of using the @code{yypull_parse} function would look 
+like this:
+
address@hidden
+yypstate *ps = yypstate_new ();
+yypull_parse (ps); /* Will call the lexer */
+yypstate_delete (ps);
address@hidden example
+
+Adding the @code{%pure-parser} declaration does exactly the same thing to the 
+generated parser with @code{%push-pull-parser} as it did for 
address@hidden
+
 @node Decl Summary
 @subsection Bison Declaration Summary
 @cindex Bison declaration summary
@@ -4797,10 +4906,13 @@
 in C parsers
 is @code{yyparse}, @code{yylex}, @code{yyerror}, @code{yynerrs},
 @code{yylval}, @code{yychar}, @code{yydebug}, and
-(if locations are used) @code{yylloc}.  For example, if you use
address@hidden "c_"}, the names become @code{c_parse}, @code{c_lex},
-and so on.  In C++ parsers, it is only the surrounding namespace which is
-named @var{prefix} instead of @samp{yy}.
+(if locations are used) @code{yylloc}.  If you use a push parser, 
address@hidden, @code{yypull_parse}, @code{yypstate}, 
address@hidden and @code{yypstate_delete} will 
+also be renamed.  For example, if you use @samp{%name-prefix "c_"}, the 
+names become @code{c_parse}, @code{c_lex}, and so on.  In C++ parsers, 
+it is only the surrounding namespace which is named @var{prefix} instead 
+of @samp{yy}.
 @xref{Multiple Parsers, ,Multiple Parsers in the Same Program}.
 @end deffn
 
@@ -4830,6 +4942,16 @@
 (Reentrant) Parser}).
 @end deffn
 
address@hidden {Directive} %push-parser
+Bison declaration to request a push parser.
address@hidden Decl, ,A Push Parser}.
address@hidden deffn
+
address@hidden {Directive} %push-pull-parser
+Bison declaration to request a push and a pull parser.
address@hidden Decl, ,A Push Parser}.
address@hidden deffn
+
 @deffn {Directive} %require "@var{version}"
 Require version @var{version} or higher of Bison.  @xref{Require Decl, ,
 Require a Version of Bison}.
@@ -4913,8 +5035,11 @@
 
 The precise list of symbols renamed is @code{yyparse}, @code{yylex},
 @code{yyerror}, @code{yynerrs}, @code{yylval}, @code{yylloc},
address@hidden and @code{yydebug}.  For example, if you use @samp{-p c},
-the names become @code{cparse}, @code{clex}, and so on.
address@hidden and @code{yydebug}.  If you use a push parser, 
address@hidden, @code{yypull_parse}, @code{yypstate}, 
address@hidden and @code{yypstate_delete} will also be renamed.
+For example, if you use @samp{-p c}, the names become @code{cparse}, 
address@hidden, and so on.
 
 @strong{All the other variables and macros associated with Bison are not
 renamed.} These others are not global; there is no conflict if the same
@@ -4943,6 +5068,12 @@
 
 @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}.
@@ -5025,6 +5156,61 @@
 exp: @dots{}    @{ @dots{}; *randomness += 1; @dots{} @}
 @end example
 
address@hidden Push Parser Function
address@hidden The Push Parser Function @code{yypush_parse}
address@hidden yypush_parse
+
+You call the function @code{yypush_parse} to parse a single token.  This 
+function is available if either the @code{%push-parser} or 
address@hidden declaration is used.  
address@hidden Decl, ,A Push Parser}.
+
address@hidden int yypush_parse (yypstate *yyps)
+The value returned by @code{yypush_parse} is the same as for yyparse with the 
+following exception.  @code{yypush_parse} will return YYPUSH_MORE if more input
+is required to finish parsing the grammar.
address@hidden deftypefun
+
address@hidden Pull Parser Function
address@hidden The Pull Parser Function @code{yypull_parse}
address@hidden yypull_parse
+
+You call the function @code{yypull_parse} to parse the rest of the input 
+stream.  This function is available if the @code{%push-pull-parser} 
+declaration is used.  
address@hidden Decl, ,A Push Parser}.
+
address@hidden int yypull_parse (yypstate *yyps)
+The value returned by @code{yypull_parse} is the same as for @code{yyparse}.
address@hidden deftypefun
+
address@hidden Parser Create Function
address@hidden The Parser Create Function @code{yystate_new}
address@hidden yypstate_new
+
+You call the function @code{yypstate_new} to create a new parser instance.  
+This function is available if either the @code{%push-parser} or 
address@hidden declaration is used.  
address@hidden Decl, ,A Push Parser}.
+
address@hidden yypstate *yypstate_new (void)
+The fuction will return a valid parser instance if there was memory available
+or NULL if no memory was available.
address@hidden deftypefun
+
address@hidden Parser Delete Function
address@hidden The Parser Delete Function @code{yystate_delete}
address@hidden yypstate_delete
+
+You call the function @code{yypstate_delete} to delete a parser instance.
+This function is available if either the @code{%push-parser} or 
address@hidden declaration is used.  
address@hidden Decl, ,A Push Parser}.
+
address@hidden 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.
address@hidden deftypefun
 
 @node Lexical
 @section The Lexical Analyzer Function @code{yylex}
@@ -9264,6 +9450,16 @@
 @xref{Pure Decl, ,A Pure (Reentrant) Parser}.
 @end deffn
 
address@hidden {Directive} %push-parser
+Bison declaration to request a push parser.
address@hidden Decl, ,A Push Parser}.
address@hidden deffn
+
address@hidden {Directive} %push-pull-parser
+Bison declaration to request a push and a pull parser.
address@hidden Decl, ,A Push Parser}.
address@hidden deffn
+
 @deffn {Directive} %require "@var{version}"
 Require version @var{version} or higher of Bison.  @xref{Require Decl, ,
 Require a Version of Bison}.
@@ -9438,7 +9634,8 @@
 
 @deffn {Variable} yynerrs
 Global variable which Bison increments each time it reports a syntax error.
-(In a pure parser, it is a local variable within @code{yyparse}.)
+(In a pure parser, it is a local variable within @code{yyparse}. In a 
+pure push parser, it is a member of yypstate.)
 @xref{Error Reporting, ,The Error Reporting Function @code{yyerror}}.
 @end deffn
 
@@ -9447,6 +9644,33 @@
 parsing.  @xref{Parser Function, ,The Parser Function @code{yyparse}}.
 @end deffn
 
address@hidden {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.
address@hidden Delete Function, ,The Parser Delete Function 
address@hidden
address@hidden deffn
+
address@hidden {Function} yypstate_new
+The function to create a parser instance, produced by Bison in push mode; 
+call this function to create a new parser.
address@hidden Create Function, ,The Parser Create Function 
address@hidden
address@hidden deffn
+
address@hidden {Function} yypull_parse
+The parser function produced by Bison in push mode; call this function to 
+parse the rest of the input stream.  
address@hidden Parser Function, ,The Pull Parser Function 
address@hidden
address@hidden deffn
+
address@hidden {Function} yypush_parse
+The parser function produced by Bison in push mode; call this function to 
+parse a single token.  @xref{Push Parser Function, ,The Push Parser Function 
address@hidden
address@hidden deffn
+
 @deffn {Macro} YYPARSE_PARAM
 An obsolete macro for specifying the name of a parameter that
 @code{yyparse} should accept.  The use of this macro is deprecated, and