Replace `%push-parser' and `%push-pull-parser' with

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 675c27c2445d9738742819b764b8b253f6eed52e..ccec0d4502171c6b35ce1132af8e0a603790fead 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -4528,7 +4528,7 @@ valid grammar.
 @subsection A Push Parser
 @cindex push parser
 @cindex push parser
 @subsection A Push Parser
 @cindex push parser
 @cindex push parser

-@findex %push-parser
+@findex %define push_pull

 
 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 
 
 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 


@@ -4539,12 +4539,12 @@ 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.  
 
 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 
-@code{%push-parser} says that you want the parser to be a push parser.
-It looks like this:
+Normally, Bison generates a pull parser.
+The following Bison declaration says that you want the parser to be a push
+parser (@pxref{Decl Summary,,%define push_pull}):

 
 @example
 
 @example

-%push-parser
+%define push_pull "push"

 @end example
 
 In almost all cases, you want to ensure that your push parser is also
 @end example
 
 In almost all cases, you want to ensure that your push parser is also


@@ -4555,7 +4555,7 @@ what you are doing, your declarations should look like this:
 
 @example
 %pure-parser
 
 @example
 %pure-parser

-%push-parser
+%define push_pull "push"

 @end example
 
 There is a major notable functional difference between the pure push parser 
 @end example
 
 There is a major notable functional difference between the pure push parser 


@@ -4604,15 +4604,16 @@ 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,
 
 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 
-@code{%push-pull-parser} declaration.  Doing this will create all of the 
+you should replace the @code{%define push_pull "push"} declaration with the 
+@code{%define push_pull "both"} 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 
 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 
-@code{yyparse} 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 
+generated parser by calling @code{yypull_parse}.
+This makes the @code{yyparse} function that is generated with the
+@code{%define push_pull "both"} 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 
 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 


@@ -4627,8 +4628,8 @@ yypstate_delete (ps);
 @end example
 
 Adding the @code{%pure-parser} declaration does exactly the same thing to the 
 @end 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 
-@code{%push-parser}.
+generated parser with @code{%define push_pull "both"} as it did for 
+@code{%define push_pull "push"}.

 
 @node Decl Summary
 @subsection Bison Declaration Summary
 
 @node Decl Summary
 @subsection Bison Declaration Summary


@@ -4834,6 +4835,14 @@ target language and/or parser skeleton.
 @end enumerate
 @end deffn
 
 @end enumerate
 @end deffn
 

+@deffn {Directive} %define push_pull "@var{value}"
+Bison declaration to request a @code{"pull"} parser, a @code{"push"} parser, or
+@code{"both"}.
+The default @code{"@var{value}"} is @code{"pull"}.
+This directive is currently only available for LALR(1) parsers in C.
+@xref{Push Decl, ,A Push Parser}.
+@end deffn
+

 @deffn {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.
 @deffn {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.


@@ -4944,16 +4953,6 @@ Request a pure (reentrant) parser program (@pxref{Pure Decl, ,A Pure
 (Reentrant) Parser}).
 @end deffn
 
 (Reentrant) Parser}).
 @end deffn
 

-@deffn {Directive} %push-parser
-Bison declaration to request a push parser.
-@xref{Push Decl, ,A Push Parser}.
-@end deffn
-
-@deffn {Directive} %push-pull-parser
-Bison declaration to request a push and a pull parser.
-@xref{Push Decl, ,A Push Parser}.
-@end deffn
-

 @deffn {Directive} %require "@var{version}"
 Require version @var{version} or higher of Bison.  @xref{Require Decl, ,
 Require a Version of Bison}.
 @deffn {Directive} %require "@var{version}"
 Require version @var{version} or higher of Bison.  @xref{Require Decl, ,
 Require a Version of Bison}.


@@ -5163,8 +5162,8 @@ exp: @dots{}    @{ @dots{}; *randomness += 1; @dots{} @}
 @findex yypush_parse
 
 You call the function @code{yypush_parse} to parse a single token.  This 
 @findex 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 
-@code{%push-pull-parser} declaration is used.  
+function is available if either the @code{%define push_pull "push"} or 
+@code{%define push_pull "both"} declaration is used.  

 @xref{Push Decl, ,A Push Parser}.
 
 @deftypefun int yypush_parse (yypstate *yyps)
 @xref{Push Decl, ,A Push Parser}.
 
 @deftypefun int yypush_parse (yypstate *yyps)


@@ -5178,7 +5177,7 @@ is required to finish parsing the grammar.
 @findex yypull_parse
 
 You call the function @code{yypull_parse} to parse the rest of the input 
 @findex 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} 
+stream.  This function is available if the @code{%define push_pull "both"} 

 declaration is used.  
 @xref{Push Decl, ,A Push Parser}.
 
 declaration is used.  
 @xref{Push Decl, ,A Push Parser}.
 


@@ -5191,8 +5190,8 @@ The value returned by @code{yypull_parse} is the same as for @code{yyparse}.
 @findex yypstate_new
 
 You call the function @code{yypstate_new} to create a new parser instance.  
 @findex 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 
-@code{%push-pull-parser} declaration is used.  
+This function is available if either the @code{%define push_pull "push"} or 
+@code{%define push_pull "both"} declaration is used.  

 @xref{Push Decl, ,A Push Parser}.
 
 @deftypefun yypstate *yypstate_new (void)
 @xref{Push Decl, ,A Push Parser}.
 
 @deftypefun yypstate *yypstate_new (void)


@@ -5205,8 +5204,8 @@ or NULL if no memory was available.
 @findex yypstate_delete
 
 You call the function @code{yypstate_delete} to delete a parser instance.
 @findex 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 
-@code{%push-pull-parser} declaration is used.  
+function is available if either the @code{%define push_pull "push"} or 
+@code{%define push_pull "both"} declaration is used.  

 @xref{Push Decl, ,A Push Parser}.
 
 @deftypefun void yypstate_delete (yypstate *yyps)
 @xref{Push Decl, ,A Push Parser}.
 
 @deftypefun void yypstate_delete (yypstate *yyps)


@@ -9330,6 +9329,12 @@ Define a variable to adjust Bison's behavior.
 @xref{Decl Summary,,%define}.
 @end deffn
 
 @xref{Decl Summary,,%define}.
 @end deffn
 

+@deffn {Directive} %define push_pull "@var{value}"
+Bison declaration to request a @code{"pull"} parser, a @code{"push"} parser, or
+@code{"both"}.
+@xref{Decl Summary,,%define push_pull}.
+@end deffn
+

 @deffn {Directive} %defines
 Bison declaration to create a header file meant for the scanner.
 @xref{Decl Summary}.
 @deffn {Directive} %defines
 Bison declaration to create a header file meant for the scanner.
 @xref{Decl Summary}.


@@ -9452,16 +9457,6 @@ Bison declaration to request a pure (reentrant) parser.
 @xref{Pure Decl, ,A Pure (Reentrant) Parser}.
 @end deffn
 
 @xref{Pure Decl, ,A Pure (Reentrant) Parser}.
 @end deffn
 

-@deffn {Directive} %push-parser
-Bison declaration to request a push parser.
-@xref{Push Decl, ,A Push Parser}.
-@end deffn
-
-@deffn {Directive} %push-pull-parser
-Bison declaration to request a push and a pull parser.
-@xref{Push Decl, ,A Push Parser}.
-@end deffn
-

 @deffn {Directive} %require "@var{version}"
 Require version @var{version} or higher of Bison.  @xref{Require Decl, ,
 Require a Version of Bison}.
 @deffn {Directive} %require "@var{version}"
 Require version @var{version} or higher of Bison.  @xref{Require Decl, ,
 Require a Version of Bison}.