]> git.saurik.com Git - bison.git/blobdiff - doc/bison.texinfo
* doc/bison.texinfo (Bison Options): Add entry for --print-datadir.
[bison.git] / doc / bison.texinfo
index 28bbc8c25ef2c299107030d52ca67ea02dbe1392..4b49c8113370810f784ad85fe73423cd774b9aed 100644 (file)
@@ -224,6 +224,7 @@ Bison Declarations
 * 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
@@ -333,7 +334,7 @@ Frequently Asked Questions
 
 Copying This Manual
 
-* GNU Free Documentation License::  License for copying this manual.
+* Copying This Manual::        License for copying this manual.
 
 @end detailmenu
 @end menu
@@ -401,7 +402,9 @@ inspecting the file for text beginning with ``As a special
 exception@dots{}''.  The text spells out the exact terms of the
 exception.
 
-@include gpl.texi
+@node Copying
+@unnumbered GNU GENERAL PUBLIC LICENSE
+@include gpl-3.0.texi
 
 @node Concepts
 @chapter The Concepts of Bison
@@ -2956,6 +2959,8 @@ type:
 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 @code{%union}) in the
 definitions section is going to adversely affect their functionality in some
 counter-intuitive manner just because it comes first.
@@ -3976,6 +3981,7 @@ Grammars}).
 * 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
 
@@ -4396,7 +4402,7 @@ The parser can @dfn{return immediately} because of an explicit call to
 @code{YYABORT} or @code{YYACCEPT}, or failed error recovery, or memory
 exhaustion.
 
-Right-hand size symbols of a rule that explicitly triggers a syntax
+Right-hand side symbols of a rule that explicitly triggers a syntax
 error via @code{YYERROR} are not discarded automatically.  As a rule
 of thumb, destructors are invoked only when user actions cannot manage
 the memory.
@@ -4508,8 +4514,9 @@ The result is that the communication variables @code{yylval} and
 @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.
 
@@ -4517,6 +4524,113 @@ 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.
 
+@node Push Decl
+@subsection A Push Parser
+@cindex push parser
+@cindex 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 
+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 (@pxref{Decl Summary,,%define push_pull}):
+
+@example
+%define push_pull "push"
+@end 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:
+
+@example
+%pure-parser
+%define push_pull "push"
+@end 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:
+
+@example
+int status;
+yypstate *ps = yypstate_new ();
+do @{
+  status = yypush_parse (ps, yylex (), NULL);
+@} while (status == YYPUSH_MORE);
+yypstate_delete (ps);
+@end 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:
+
+@example
+extern int yychar;
+int status;
+yypstate *ps = yypstate_new ();
+do @{
+  yychar = yylex ();
+  status = yypush_parse (ps);
+@} while (status == YYPUSH_MORE);
+yypstate_delete (ps);
+@end 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{%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 
+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 
+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:
+
+@example
+yypstate *ps = yypstate_new ();
+yypull_parse (ps); /* Will call the lexer */
+yypstate_delete (ps);
+@end example
+
+Adding the @code{%pure-parser} declaration does exactly the same thing to the 
+generated parser with @code{%define push_pull "both"} as it did for 
+@code{%define push_pull "push"}.
+
 @node Decl Summary
 @subsection Bison Declaration Summary
 @cindex Bison declaration summary
@@ -4612,8 +4726,8 @@ where Bison should generate it.
 Not all values of @var{qualifier} are available for all target languages:
 
 @itemize @bullet
-@findex %code requires
 @item requires
+@findex %code requires
 
 @itemize @bullet
 @item Language(s): C, C++
@@ -4691,15 +4805,105 @@ already defined, so that the debugging facilities are compiled.
 @end deffn
 @xref{Tracing, ,Tracing Your Parser}.
 
-@deffn {Directive} %define @var{define-variable}
-@deffnx {Directive} %define @var{define-variable} @var{value}
+@deffn {Directive} %define @var{variable}
+@deffnx {Directive} %define @var{variable} "@var{value}"
 Define a variable to adjust Bison's behavior.
-The list of available variables and their meanings depends on the selected
-target language and/or the parser skeleton (@pxref{Decl Summary,,%language}).
-The @var{value} can be omitted for boolean variables; for
-boolean variables, the skeletons will treat a @var{value} of @samp{0}
-or @samp{false} as the boolean variable being false, and anything else
-as true.
+The possible choices for @var{variable}, as well as their meanings, depend on
+the selected target language and/or the parser skeleton (@pxref{Decl
+Summary,,%language}).
+
+Bison will warn if a @var{variable} is defined multiple times.
+
+Omitting @code{"@var{value}"} is always equivalent to specifying it as
+@code{""}.
+
+Some @var{variable}s may be used as Booleans.
+In this case, Bison will complain if the variable definition does not meet one
+of the following four conditions:
+
+@enumerate
+@item @code{"@var{value}"} is @code{"true"}
+
+@item @code{"@var{value}"} is omitted (or is @code{""}).
+This is equivalent to @code{"true"}.
+
+@item @code{"@var{value}"} is @code{"false"}.
+
+@item @var{variable} is never defined.
+In this case, Bison selects a default value, which may depend on the selected
+target language and/or parser skeleton.
+@end enumerate
+
+Some of the accepted @var{variable}s are:
+
+@itemize @bullet
+@item push_pull
+@findex %define push_pull
+
+@itemize @bullet
+@item Language(s): C (LALR(1) only)
+
+@item Purpose: Requests a pull parser, a push parser, or both.
+@xref{Push Decl, ,A Push Parser}.
+
+@item Accepted Values: @code{"pull"}, @code{"push"}, @code{"both"}
+
+@item Default Value: @code{"pull"}
+@end itemize
+
+@item namespace
+@findex %define namespace
+
+@itemize
+@item Languages(s): C++
+
+@item Purpose: Specifies the namespace for the parser class.
+For example, if you specify:
+
+@smallexample
+%define namespace "foo::bar"
+@end smallexample
+
+Bison uses @code{foo::bar} verbatim in references such as:
+
+@smallexample
+foo::bar::parser::semantic_type
+@end smallexample
+
+However, to open a namespace, Bison removes any leading @code{::} and then
+splits on any remaining occurrences:
+
+@smallexample
+namespace foo @{ namespace bar @{
+  class position;
+  class location;
+@} @}
+@end smallexample
+
+@item Accepted Values: Any absolute or relative C++ namespace reference without
+a trailing @code{"::"}.
+For example, @code{"foo"} or @code{"::foo::bar"}.
+
+@item Default Value: The value specified by @code{%name-prefix}, which defaults
+to @code{yy}.
+This usage of @code{%name-prefix} is for backward compatibility and can be
+confusing since @code{%name-prefix} also specifies the textual prefix for the
+lexical analyzer function.
+Thus, if you specify @code{%name-prefix}, it is best to also specify
+@code{%define namespace} so that @code{%name-prefix} @emph{only} affects the
+lexical analyzer function.
+For example, if you specify:
+
+@smallexample
+%define namespace "foo"
+%name-prefix "bar::"
+@end smallexample
+
+The parser namespace is @code{foo} and @code{yylex} is referenced as
+@code{bar::lex}.
+@end itemize
+@end itemize
+
 @end deffn
 
 @deffn {Directive} %defines
@@ -4776,10 +4980,13 @@ Rename the external symbols used in the parser so that they start with
 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
-@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}.
+(if locations are used) @code{yylloc}.  If you use a push parser, 
+@code{yypush_parse}, @code{yypull_parse}, @code{yypstate}, 
+@code{yypstate_new} 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.
+For C++ parsers, see the @code{%define namespace} documentation in this
+section.
 @xref{Multiple Parsers, ,Multiple Parsers in the Same Program}.
 @end deffn
 
@@ -4791,16 +4998,6 @@ Precedence}).
 @end deffn
 @end ifset
 
-@deffn {Directive} %no-parser
-Do not include any C code in the parser file; generate tables only.  The
-parser file contains just @code{#define} directives and static variable
-declarations.
-
-This option also tells Bison to write the C code for the grammar actions
-into a file named @file{@var{file}.act}, in the form of a
-brace-surrounded body fit for a @code{switch} statement.
-@end deffn
-
 @deffn {Directive} %no-lines
 Don't generate any @code{#line} preprocessor commands in the parser
 file.  Ordinarily Bison writes these commands in the parser file so that
@@ -4902,8 +5099,11 @@ names that do not conflict.
 
 The precise list of symbols renamed is @code{yyparse}, @code{yylex},
 @code{yyerror}, @code{yynerrs}, @code{yylval}, @code{yylloc},
-@code{yychar} and @code{yydebug}.  For example, if you use @samp{-p c},
-the names become @code{cparse}, @code{clex}, and so on.
+@code{yychar} and @code{yydebug}.  If you use a push parser, 
+@code{yypush_parse}, @code{yypull_parse}, @code{yypstate}, 
+@code{yypstate_new} and @code{yypstate_delete} will also be renamed.
+For example, if you use @samp{-p c}, the names become @code{cparse}, 
+@code{clex}, 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
@@ -4932,6 +5132,12 @@ 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}.
@@ -5014,6 +5220,61 @@ In the grammar actions, use expressions like this to refer to the data:
 exp: @dots{}    @{ @dots{}; *randomness += 1; @dots{} @}
 @end example
 
+@node Push Parser Function
+@section The Push Parser Function @code{yypush_parse}
+@findex yypush_parse
+
+You call the function @code{yypush_parse} to parse a single token.  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 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.
+@end deftypefun
+
+@node Pull Parser Function
+@section The Pull Parser Function @code{yypull_parse}
+@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{%define push_pull "both"} 
+declaration is used.  
+@xref{Push Decl, ,A Push Parser}.
+
+@deftypefun int yypull_parse (yypstate *yyps)
+The value returned by @code{yypull_parse} is the same as for @code{yyparse}.
+@end deftypefun
+
+@node Parser Create Function
+@section The Parser Create Function @code{yystate_new}
+@findex yypstate_new
+
+You call the function @code{yypstate_new} to create a new parser instance.  
+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)
+The fuction will return a valid parser instance if there was memory available
+or NULL if no memory was available.
+@end deftypefun
+
+@node Parser Delete Function
+@section The Parser Delete Function @code{yystate_delete}
+@findex yypstate_delete
+
+You call the function @code{yypstate_delete} to delete a parser instance.
+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)
+This function will reclaim the memory associated with a parser instance.
+After this call, you should no longer attempt to use the parser instance.
+@end deftypefun
 
 @node Lexical
 @section The Lexical Analyzer Function @code{yylex}
@@ -7235,7 +7496,7 @@ always possible.
 
 The trace facility outputs messages with macro calls of the form
 @code{YYFPRINTF (stderr, @var{format}, @var{args})} where
-@var{format} and @var{args} are the usual @code{printf} format and
+@var{format} and @var{args} are the usual @code{printf} format and variadic
 arguments.  If you define @code{YYDEBUG} to a nonzero value but do not
 define @code{YYFPRINTF}, @code{<stdio.h>} is automatically included
 and @code{YYFPRINTF} is defined to @code{fprintf}.
@@ -7388,6 +7649,9 @@ Print the version number of Bison and exit.
 @item --print-localedir
 Print the name of the directory containing locale-dependent data.
 
+@item --print-datadir
+Print the name of the directory containing skeletons and XSLT.
+
 @item -y
 @itemx --yacc
 Act more like the traditional Yacc command.  This can cause
@@ -7447,10 +7711,6 @@ 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.
 
-@item -n
-@itemx --no-parser
-Pretend that @code{%no-parser} was specified.  @xref{Decl Summary}.
-
 @item -S @var{file}
 @itemx --skeleton=@var{file}
 Specify the skeleton to use, similar to @code{%skeleton}
@@ -7551,9 +7811,9 @@ the corresponding short option.
 @item @option{--help}                       @tab @option{-h}
 @item @option{--name-prefix=@var{prefix}}   @tab @option{-p @var{name-prefix}}
 @item @option{--no-lines}                   @tab @option{-l}
-@item @option{--no-parser}                  @tab @option{-n}
 @item @option{--output=@var{outfile}}       @tab @option{-o @var{outfile}}
 @item @option{--print-localedir}            @tab
+@item @option{--print-datadir}              @tab
 @item @option{--token-table}                @tab @option{-k}
 @item @option{--verbose}                    @tab @option{-v}
 @item @option{--version}                    @tab @option{-V}
@@ -7619,10 +7879,12 @@ The C++ @acronym{LALR}(1) parser is selected using the language directive,
 @option{--language=c++}.
 @xref{Decl Summary}.
 
-When run, @command{bison} will create several
-entities in the @samp{yy} namespace.  Use the @samp{%name-prefix}
-directive to change the namespace name, see @ref{Decl Summary}.  The
-various classes are generated in the following files:
+When run, @command{bison} will create several entities in the @samp{yy}
+namespace.
+@findex %define namespace
+Use the @samp{%define namespace} directive to change the namespace name, see
+@ref{Decl Summary}.
+The various classes are generated in the following files:
 
 @table @file
 @item position.hh
@@ -8361,7 +8623,10 @@ Remember that, according to the Java language specification, the name
 of the @file{.java} file should match the name of the class in this
 case.
 
-All these files are documented using Javadoc.
+Similarly, a declaration @samp{%define "abstract"} will make your
+class abstract.
+
+You can create documentation for generated parsers using Javadoc.
 
 @node Java Semantic Values
 @subsection Java Semantic Values
@@ -8385,7 +8650,7 @@ superclass of all the semantic values using the @samp{%define} directive.
 For example, after the following declaration:
 
 @example
-%define "union_name" "ASTNode"
+%define "stype" "ASTNode"
 @end example
 
 @noindent
@@ -8464,7 +8729,7 @@ Run the syntactic analysis, and return @code{true} on success,
 @code{false} otherwise.
 @end deftypemethod
 
-@deftypemethod {YYParser} {boolean} yyrecovering ()
+@deftypemethod {YYParser} {boolean} recovering ()
 During the syntactic analysis, return @code{true} if recovering
 from a syntax error.  @xref{Error Recovery}.
 @end deftypemethod
@@ -8491,33 +8756,39 @@ Interface}); the parser uses it to report a parser error occurring at
 
 @node Java Scanner Interface
 @subsection Java Scanner Interface
-@c - prefix for yylex.
-@c - Pure interface to yylex
+@c - %code lexer
 @c - %lex-param
+@c - Lexer interface
 
-There are two possible ways to interface a Bison-generated Java parser
-with a scanner.
-
-@cindex pure parser, in Java
 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'' in the C sense.  The
-@code{%pure-parser} directive can still be used in Java, and it
-will control whether the lexer resides in a separate class than the
-Bison-generated parser (therefore, Bison generates a class that is
-``purely'' a parser), or in the same class.  The interface to the scanner
-is similar, though the two cases present a slightly different naming.
-
-For the @code{%pure-parser} case, the scanner implements an interface
-called @code{Lexer} and defined within the parser class (e.g.,
-@code{YYParser.Lexer}.  The constructor of the parser object accepts
-an object implementing the interface.  The interface specifies
-the following methods.
-
-@deftypemethod {Lexer} {void} error (Location @var{l}, String @var{m})
+Therefore, all Java parsers are ``pure'', and the @code{%pure-parser}
+directive does not do anything when used in Java.
+
+The scanner always resides in a separate class than the parser.
+Still, Java also two possible ways to interface a Bison-generated Java
+parser with a scanner, that is, the scanner may reside in a separate file
+than the Bison grammar, or in the same file.  The interface
+to the scanner is similar in the two cases.
+
+In the first case, where the scanner in the same file as the grammar, the
+scanner code has to be placed in @code{%code lexer} blocks.  If you want
+to pass parameters from the parser constructor to the scanner constructor,
+specify them with @code{%lex-param}; they are passed before
+@code{%parse-param}s to the constructor.
+
+In the second case, the scanner has to implement interface @code{Lexer},
+which is defined within the parser class (e.g., @code{YYParser.Lexer}).
+The constructor of the parser object will then accept an object
+implementing the interface; @code{%lex-param} is not used in this
+case.
+
+In both cases, the scanner has to implement the following methods.
+
+@deftypemethod {Lexer} {void} yyerror (Location @var{l}, String @var{m})
 As explained in @pxref{Java Parser Interface}, this method is defined
-by the user to emit an error message.  The first parameter is not used
-unless location tracking is active.  Its type can be changed using
+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
 @samp{%define "location_type" "@var{class-name}".}
 @end deftypemethod
 
@@ -8530,9 +8801,9 @@ interface.  Invocations of @samp{%lex-param @{@var{type1}
 
 @deftypemethod {Lexer} {Position} getStartPos ()
 @deftypemethodx {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.
+Return respectively the first position of the last token that
+@code{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 @samp{%define "position_type"
 "@var{class-name}".}
@@ -8542,7 +8813,7 @@ The return type can be changed using @samp{%define "position_type"
 Return respectively the first position of the last token that yylex
 returned, and the first position beyond it.
 
-The return type can be changed using @samp{%define "union_name"
+The return type can be changed using @samp{%define "stype"
 "@var{class-name}".}
 @end deftypemethod
 
@@ -8580,32 +8851,23 @@ The field's type can be changed using @samp{%define "position_type"
 Return respectively the first position of the last token that yylex
 returned, and the first position beyond it.
 
-The field's type can be changed using @samp{%define "union_name"
+The field's type can be changed using @samp{%define "stype"
 "@var{class-name}".}
 @end deftypecv
 
-By default the class generated for a non-pure Java parser is abstract,
-and the methods @code{yylex} and @code{yyerror} shall be placed in a
-subclass (possibly defined in the additional code section).  It is
-also possible, using the @code{%define "single_class"} declaration, to
-define the scanner in the same class as the parser; when this
-declaration is present, the class is not declared as abstract.
-In order to place the declarations for the scanner inside the
-parser class, you should use @code{%code} sections.
-
 @node Java Differences
 @subsection 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 this differences.
+section summarizes these differences.
 
 @itemize
 @item
-Since Java lacks a preprocessor, the @code{YYERROR}, @code{YYACCEPT},
+Java lacks a preprocessor, so the @code{YYERROR}, @code{YYACCEPT},
 @code{YYABORT} symbols (@pxref{Table of Symbols}) cannot obviously be
-macros.  Instead, they should be preceded in an action with
-@code{return}.  The actual definition of these symbols should be
+macros.  Instead, they should be preceded by @code{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.
 
@@ -8617,19 +8879,25 @@ corresponds to these C macros.}.
 
 @item
 The prolog declarations have a different meaning than in C/C++ code.
-@table @code
-@item %code
-@code{%code imports} blocks are placed at the beginning of the Java
-source code.  They may include copyright notices.  For a @code{package}
-declarations, it is suggested to use @code{%define package} instead.
-
-@code{%code} blocks are placed inside the parser class.  If @code{%define
-single_class} is being used, the definitions of @code{yylex} and
-@code{yyerror} should be placed here.  Subroutines for the parser actions
-may be included in this kind of block.
+@table @asis
+@item @code{%code imports}
+blocks are placed at the beginning of the Java source code.  They may
+include copyright notices.  For a @code{package} declarations, it is
+suggested to use @code{%define package} instead.
+
+@item unqualified @code{%code}
+blocks are placed inside the parser class.
+
+@item @code{%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 @pxref{Java Scanner
+Interface}).
+@end table
 
 Other @code{%code} blocks are not supported in Java parsers.
-@end table
+The epilogue has the same meaning as in C/C++ code and it can
+be used to define other classes used by the parser.
 @end itemize
 
 @c ================================================= FAQ
@@ -9426,7 +9694,8 @@ Management}.
 
 @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
 
@@ -9435,6 +9704,33 @@ The parser function produced by Bison; call this function to start
 parsing.  @xref{Parser Function, ,The Parser Function @code{yyparse}}.
 @end deffn
 
+@deffn {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.
+@xref{Parser Delete Function, ,The Parser Delete Function 
+@code{yypstate_delete}}.
+@end deffn
+
+@deffn {Function} yypstate_new
+The function to create a parser instance, produced by Bison in push mode; 
+call this function to create a new parser.
+@xref{Parser Create Function, ,The Parser Create Function 
+@code{yypstate_new}}.
+@end deffn
+
+@deffn {Function} yypull_parse
+The parser function produced by Bison in push mode; call this function to 
+parse the rest of the input stream.  
+@xref{Pull Parser Function, ,The Pull Parser Function 
+@code{yypull_parse}}.
+@end deffn
+
+@deffn {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 
+@code{yypush_parse}}.
+@end 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
@@ -9643,11 +9939,6 @@ grammatically indivisible.  The piece of text it represents is a token.
 
 @node Copying This Manual
 @appendix Copying This Manual
-
-@menu
-* GNU Free Documentation License::  License for copying this manual.
-@end menu
-
 @include fdl.texi
 
 @node Index