c++: comment and style changes

[bison.git] / doc / bison.texi

diff --git a/doc/bison.texi b/doc/bison.texi
index 58a14f8bc2fc3a9ee35c440b91ea666f135cc110..d40221593d002078936592c5bf7f82f16f3b2e97 100644 (file)
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -1,6 +1,8 @@
 \input texinfo @c -*-texinfo-*-
 @comment %**start of header
 @setfilename bison.info
 \input texinfo @c -*-texinfo-*-
 @comment %**start of header
 @setfilename bison.info

+@documentencoding UTF-8
+@documentlanguage en

 @include version.texi
 @settitle Bison @value{VERSION}
 @setchapternewpage odd
 @include version.texi
 @settitle Bison @value{VERSION}
 @setchapternewpage odd


@@ -33,7 +35,7 @@
 This manual (@value{UPDATED}) is for GNU Bison (version
 @value{VERSION}), the GNU parser generator.
 
 This manual (@value{UPDATED}) is for GNU Bison (version
 @value{VERSION}), the GNU parser generator.
 

-Copyright @copyright{} 1988-1993, 1995, 1998-2013 Free Software
+Copyright @copyright{} 1988-1993, 1995, 1998-2015 Free Software

 Foundation, Inc.
 
 @quotation
 Foundation, Inc.
 
 @quotation


@@ -366,6 +368,7 @@ Java Parsers
 * 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 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 Push Parser Interface::  Instantiating and running the a push parser

 * Java Differences::            Differences between C/C++ and Java Grammars
 * Java Declarations Summary::   List of Bison declarations used with Java
 
 * Java Differences::            Differences between C/C++ and Java Grammars
 * Java Declarations Summary::   List of Bison declarations used with Java
 


@@ -2160,7 +2163,7 @@ the same as the declarations for the infix notation calculator.
 %@}
 
 /* Bison declarations.  */
 %@}
 
 /* Bison declarations.  */

-%define api.value.type int
+%define api.value.type @{int@}

 %token NUM
 
 %left '-' '+'
 %token NUM
 
 %left '-' '+'


@@ -3848,7 +3851,7 @@ example:
 @noindent
 specifies the union tag @code{value}, so the corresponding C type is
 @code{union value}.  If you do not specify a tag, it defaults to
 @noindent
 specifies the union tag @code{value}, so the corresponding C type is
 @code{union value}.  If you do not specify a tag, it defaults to

-@code{YYSTYPE}.
+@code{YYSTYPE} (@pxref{%define Summary,,api.value.union.name}).

 
 As another extension to POSIX, you may specify multiple @code{%union}
 declarations; their contents are concatenated.  However, only the first
 
 As another extension to POSIX, you may specify multiple @code{%union}
 declarations; their contents are concatenated.  However, only the first


@@ -3885,7 +3888,7 @@ and then your grammar can use the following instead of @code{%union}:
 %@{
 #include "parser.h"
 %@}
 %@{
 #include "parser.h"
 %@}

-%define api.value.type "union YYSTYPE"
+%define api.value.type @{union YYSTYPE@}

 %type <val> expr
 %token <tptr> ID
 @end group
 %type <val> expr
 %token <tptr> ID
 @end group


@@ -5142,7 +5145,9 @@ value by default.  However, when the parser displays a @code{STRING1} or a
 @code{string1}, it formats it as a string in double quotes.  It performs
 only the second @code{%printer} in this case, so it prints only once.
 Finally, the parser print @samp{<>} for any symbol, such as @code{TAGLESS},
 @code{string1}, it formats it as a string in double quotes.  It performs
 only the second @code{%printer} in this case, so it prints only once.
 Finally, the parser print @samp{<>} for any symbol, such as @code{TAGLESS},

-that has no semantic type tag.  See also
+that has no semantic type tag.  @xref{Mfcalc Traces, ,Enabling Debug Traces
+for @code{mfcalc}}, for a complete example.
+

 
 
 @node Expect Decl
 
 
 @node Expect Decl


@@ -5450,6 +5455,7 @@ parse.trace}.
 
 @deffn {Directive} %define @var{variable}
 @deffnx {Directive} %define @var{variable} @var{value}
 
 @deffn {Directive} %define @var{variable}
 @deffnx {Directive} %define @var{variable} @var{value}

+@deffnx {Directive} %define @var{variable} @{@var{value}@}

 @deffnx {Directive} %define @var{variable} "@var{value}"
 Define a variable to adjust Bison's behavior.  @xref{%define Summary}.
 @end deffn
 @deffnx {Directive} %define @var{variable} "@var{value}"
 Define a variable to adjust Bison's behavior.  @xref{%define Summary}.
 @end deffn


@@ -5499,7 +5505,7 @@ preprocessor guard: @samp{YY_@var{PREFIX}_@var{FILE}_INCLUDED}, where
 uppercase, with each series of non alphanumerical characters converted to a
 single underscore.
 
 uppercase, with each series of non alphanumerical characters converted to a
 single underscore.
 

-For instance with @samp{%define api.prefix "calc"} and @samp{%defines
+For instance with @samp{%define api.prefix @{calc@}} and @samp{%defines

 "lib/parse.h"}, the header will be guarded as follows.
 @example
 #ifndef YY_CALC_LIB_PARSE_H_INCLUDED
 "lib/parse.h"}, the header will be guarded as follows.
 @example
 #ifndef YY_CALC_LIB_PARSE_H_INCLUDED


@@ -5661,17 +5667,17 @@ features are associated with variables, which are assigned by the
 
 @deffn {Directive} %define @var{variable}
 @deffnx {Directive} %define @var{variable} @var{value}
 
 @deffn {Directive} %define @var{variable}
 @deffnx {Directive} %define @var{variable} @var{value}

+@deffnx {Directive} %define @var{variable} @{@var{value}@}

 @deffnx {Directive} %define @var{variable} "@var{value}"
 Define @var{variable} to @var{value}.
 
 @deffnx {Directive} %define @var{variable} "@var{value}"
 Define @var{variable} to @var{value}.
 

-@var{value} must be placed in quotation marks if it contains any
-character other than a letter, underscore, period, or non-initial dash
-or digit.  Omitting @code{"@var{value}"} entirely is always equivalent
-to specifying @code{""}.
+The type of the values depend on the syntax.  Braces denote value in the
+target language (e.g., a namespace, a type, etc.).  Keyword values (no
+delimiters) denote finite choice (e.g., a variation of a feature).  String
+values denote remaining cases (e.g., a file name).

 
 

-It is an error if a @var{variable} is defined by @code{%define}
-multiple times, but see @ref{Bison Options,,-D
-@var{name}[=@var{value}]}.
+It is an error if a @var{variable} is defined by @code{%define} multiple
+times, but see @ref{Bison Options,,-D @var{name}[=@var{value}]}.

 @end deffn
 
 The rest of this section summarizes variables and values that
 @end deffn
 
 The rest of this section summarizes variables and values that


@@ -5753,7 +5759,7 @@ The parser namespace is @code{foo} and @code{yylex} is referenced as
 @c api.namespace
 
 @c ================================================== api.location.type
 @c api.namespace
 
 @c ================================================== api.location.type

-@deffn {Directive} {%define api.location.type} @var{type}
+@deffn {Directive} {%define api.location.type} @{@var{type}@}

 
 @itemize @bullet
 @item Language(s): C++, Java
 
 @itemize @bullet
 @item Language(s): C++, Java


@@ -5772,7 +5778,7 @@ Introduced in Bison 2.7 for C, C++ and Java.  Introduced under the name
 @end deffn
 
 @c ================================================== api.prefix
 @end deffn
 
 @c ================================================== api.prefix

-@deffn {Directive} {%define api.prefix} @var{prefix}
+@deffn {Directive} {%define api.prefix} @{@var{prefix}@}

 
 @itemize @bullet
 @item Language(s): All
 
 @itemize @bullet
 @item Language(s): All


@@ -5789,7 +5795,7 @@ Introduced in Bison 2.7 for C, C++ and Java.  Introduced under the name
 @end deffn
 
 @c ================================================== api.pure
 @end deffn
 
 @c ================================================== api.pure

-@deffn Directive {%define api.pure}
+@deffn Directive {%define api.pure} @var{purity}

 
 @itemize @bullet
 @item Language(s): C
 
 @itemize @bullet
 @item Language(s): C


@@ -5877,7 +5883,7 @@ Boolean.
 @item Default Value:
 @code{false}
 @item History:
 @item Default Value:
 @code{false}
 @item History:

-introduced in Bison 2.8
+introduced in Bison 3.0

 @end itemize
 @end deffn
 @c api.token.constructor
 @end itemize
 @end deffn
 @c api.token.constructor


@@ -5929,7 +5935,8 @@ introduced in Bison 3.0
 
 
 @c ================================================== api.value.type
 
 
 @c ================================================== api.value.type

-@deffn Directive {%define api.value.type} @var{type}
+@deffn Directive {%define api.value.type} @var{support}
+@deffnx Directive {%define api.value.type} @{@var{type}@}

 @itemize @bullet
 @item Language(s):
 all
 @itemize @bullet
 @item Language(s):
 all


@@ -5939,16 +5946,16 @@ The type for semantic values.
 
 @item Accepted Values:
 @table @asis
 
 @item Accepted Values:
 @table @asis

-@item @code{""}
+@item @samp{@{@}}

 This grammar has no semantic value at all.  This is not properly supported
 yet.
 This grammar has no semantic value at all.  This is not properly supported
 yet.

-@item @code{%union} (C, C++)
+@item @samp{union-directive} (C, C++)

 The type is defined thanks to the @code{%union} directive.  You don't have
 to define @code{api.value.type} in that case, using @code{%union} suffices.
 @xref{Union Decl, ,The Union Declaration}.
 For instance:
 @example
 The type is defined thanks to the @code{%union} directive.  You don't have
 to define @code{api.value.type} in that case, using @code{%union} suffices.
 @xref{Union Decl, ,The Union Declaration}.
 For instance:
 @example

-%define api.value.type "%union"
+%define api.value.type union-directive

 %union
 @{
   int ival;
 %union
 @{
   int ival;


@@ -5958,30 +5965,30 @@ For instance:
 %token <sval> STR "string"
 @end example
 
 %token <sval> STR "string"
 @end example
 

-@item @code{union} (C, C++)
+@item @samp{union} (C, C++)

 The symbols are defined with type names, from which Bison will generate a
 @code{union}.  For instance:
 @example
 The symbols are defined with type names, from which Bison will generate a
 @code{union}.  For instance:
 @example

-%define api.value.type "union"
+%define api.value.type union

 %token <int> INT "integer"
 %token <char *> STR "string"
 @end example
 This feature needs user feedback to stabilize.  Note that most C++ objects
 cannot be stored in a @code{union}.
 
 %token <int> INT "integer"
 %token <char *> STR "string"
 @end example
 This feature needs user feedback to stabilize.  Note that most C++ objects
 cannot be stored in a @code{union}.
 

-@item @code{variant} (C++)
+@item @samp{variant} (C++)

 This is similar to @code{union}, but special storage techniques are used to
 allow any kind of C++ object to be used. For instance:
 @example
 This is similar to @code{union}, but special storage techniques are used to
 allow any kind of C++ object to be used. For instance:
 @example

-%define api.value.type "variant"
+%define api.value.type variant

 %token <int> INT "integer"
 %token <std::string> STR "string"
 @end example
 This feature needs user feedback to stabilize.
 @xref{C++ Variants}.
 
 %token <int> INT "integer"
 %token <std::string> STR "string"
 @end example
 This feature needs user feedback to stabilize.
 @xref{C++ Variants}.
 

-@item any other identifier
-Use this name as semantic value.
+@item @samp{@{@var{type}@}}
+Use this @var{type} as semantic value.

 @example
 %code requires
 @{
 @example
 %code requires
 @{


@@ -5998,7 +6005,7 @@ Use this name as semantic value.
     @} u;
   @};
 @}
     @} u;
   @};
 @}

-%define api.value.type "struct my_value"
+%define api.value.type @{struct my_value@}

 %token <u.ival> INT "integer"
 %token <u.sval> STR "string"
 @end example
 %token <u.ival> INT "integer"
 %token <u.sval> STR "string"
 @end example


@@ -6007,22 +6014,46 @@ Use this name as semantic value.
 @item Default Value:
 @itemize @minus
 @item
 @item Default Value:
 @itemize @minus
 @item

-@code{%union} if @code{%union} is used, otherwise @dots{}
+@code{union-directive} if @code{%union} is used, otherwise @dots{}

 @item
 @code{int} if type tags are used (i.e., @samp{%token <@var{type}>@dots{}} or
 @item
 @code{int} if type tags are used (i.e., @samp{%token <@var{type}>@dots{}} or

-@samp{%token <@var{type}>@dots{}} is used), otherwise @dots{}
+@samp{%type <@var{type}>@dots{}} is used), otherwise @dots{}

 @item
 @item

-@code{""}
+undefined.

 @end itemize
 
 @item History:
 @end itemize
 
 @item History:

-introduced in Bison 2.8.  Was introduced for Java only in 2.3b as
+introduced in Bison 3.0.  Was introduced for Java only in 2.3b as

 @code{stype}.
 @end itemize
 @end deffn
 @c api.value.type
 
 
 @code{stype}.
 @end itemize
 @end deffn
 @c api.value.type
 
 

+@c ================================================== api.value.union.name
+@deffn Directive {%define api.value.union.name} @var{name}
+@itemize @bullet
+@item Language(s):
+C
+
+@item Purpose:
+The tag of the generated @code{union} (@emph{not} the name of the
+@code{typedef}).  This variable is set to @code{@var{id}} when @samp{%union
+@var{id}} is used.  There is no clear reason to give this union a name.
+
+@item Accepted Values:
+Any valid identifier.
+
+@item Default Value:
+@code{YYSTYPE}.
+
+@item History:
+Introduced in Bison 3.0.3.
+@end itemize
+@end deffn
+@c api.value.type
+
+

 @c ================================================== location_type
 @deffn Directive {%define location_type}
 Obsoleted by @code{api.location.type} since Bison 2.7.
 @c ================================================== location_type
 @deffn Directive {%define location_type}
 Obsoleted by @code{api.location.type} since Bison 2.7.


@@ -6048,8 +6079,8 @@ feedback will help to stabilize it.)
 @item @code{most} otherwise.
 @end itemize
 @item History:
 @item @code{most} otherwise.
 @end itemize
 @item History:

-introduced as @code{lr.default-reduction} in 2.5, renamed as
-@code{lr.default-reduction} in 2.8.
+introduced as @code{lr.default-reductions} in 2.5, renamed as
+@code{lr.default-reduction} in 3.0.

 @end itemize
 @end deffn
 
 @end itemize
 @end deffn
 


@@ -6066,7 +6097,7 @@ remain in the parser tables.  @xref{Unreachable States}.
 @item History:
 introduced as @code{lr.keep_unreachable_states} in 2.3b, renamed as
 @code{lr.keep-unreachable-states} in 2.5, and as
 @item History:
 introduced as @code{lr.keep_unreachable_states} in 2.3b, renamed as
 @code{lr.keep-unreachable-states} in 2.5, and as

-@code{lr.keep-unreachable-state} in 2.8.
+@code{lr.keep-unreachable-state} in 3.0.

 @end itemize
 @end deffn
 @c lr.keep-unreachable-state
 @end itemize
 @end deffn
 @c lr.keep-unreachable-state


@@ -6114,7 +6145,7 @@ destroyed properly.  This option checks these constraints.
 
 
 @c ================================================== parse.error
 
 
 @c ================================================== parse.error

-@deffn Directive {%define parse.error}
+@deffn Directive {%define parse.error} @var{verbosity}

 @itemize
 @item Languages(s):
 all
 @itemize
 @item Languages(s):
 all


@@ -6141,7 +6172,7 @@ However, this report can often be incorrect when LAC is not enabled
 
 
 @c ================================================== parse.lac
 
 
 @c ================================================== parse.lac

-@deffn Directive {%define parse.lac}
+@deffn Directive {%define parse.lac} @var{when}

 
 @itemize
 @item Languages(s): C (deterministic parsers only)
 
 @itemize
 @item Languages(s): C (deterministic parsers only)


@@ -6164,7 +6195,7 @@ syntax error handling.  @xref{LAC}.
 @xref{Tracing, ,Tracing Your Parser}.
 
 In C/C++, define the macro @code{YYDEBUG} (or @code{@var{prefix}DEBUG} with
 @xref{Tracing, ,Tracing Your Parser}.
 
 In C/C++, define the macro @code{YYDEBUG} (or @code{@var{prefix}DEBUG} with

-@samp{%define api.prefix @var{prefix}}), see @ref{Multiple Parsers,
+@samp{%define api.prefix @{@var{prefix}@}}), see @ref{Multiple Parsers,

 ,Multiple Parsers in the Same Program}) to 1 in the parser implementation
 file if it is not already defined, so that the debugging facilities are
 compiled.
 ,Multiple Parsers in the Same Program}) to 1 in the parser implementation
 file if it is not already defined, so that the debugging facilities are
 compiled.


@@ -6307,7 +6338,7 @@ The easy way to do this is to define the @code{%define} variable
 @code{api.prefix}.  With different @code{api.prefix}s it is guaranteed that
 headers do not conflict when included together, and that compiled objects
 can be linked together too.  Specifying @samp{%define api.prefix
 @code{api.prefix}.  With different @code{api.prefix}s it is guaranteed that
 headers do not conflict when included together, and that compiled objects
 can be linked together too.  Specifying @samp{%define api.prefix

-@var{prefix}} (or passing the option @samp{-Dapi.prefix=@var{prefix}}, see
+@{@var{prefix}@}} (or passing the option @samp{-Dapi.prefix=@{@var{prefix}@}}, see

 @ref{Invocation, ,Invoking Bison}) renames the interface functions and
 variables of the Bison parser to start with @var{prefix} instead of
 @samp{yy}, and all the macros to start by @var{PREFIX} (i.e., @var{prefix}
 @ref{Invocation, ,Invoking Bison}) renames the interface functions and
 variables of the Bison parser to start with @var{prefix} instead of
 @samp{yy}, and all the macros to start by @var{PREFIX} (i.e., @var{prefix}


@@ -6321,7 +6352,7 @@ The renamed symbols include @code{yyparse}, @code{yylex}, @code{yyerror},
 @code{YYSTYPE}, @code{YYLTYPE}, and @code{YYDEBUG}, which is treated
 specifically --- more about this below.
 
 @code{YYSTYPE}, @code{YYLTYPE}, and @code{YYDEBUG}, which is treated
 specifically --- more about this below.
 

-For example, if you use @samp{%define api.prefix c}, the names become
+For example, if you use @samp{%define api.prefix @{c@}}, the names become

 @code{cparse}, @code{clex}, @dots{}, @code{CSTYPE}, @code{CLTYPE}, and so
 on.
 
 @code{cparse}, @code{clex}, @dots{}, @code{CSTYPE}, @code{CLTYPE}, and so
 on.
 


@@ -9554,7 +9585,7 @@ enabled if and only if @code{YYDEBUG} is nonzero.
 @item the option @option{-t} (POSIX Yacc compliant)
 @itemx the option @option{--debug} (Bison extension)
 Use the @samp{-t} option when you run Bison (@pxref{Invocation, ,Invoking
 @item the option @option{-t} (POSIX Yacc compliant)
 @itemx the option @option{--debug} (Bison extension)
 Use the @samp{-t} option when you run Bison (@pxref{Invocation, ,Invoking

-Bison}).  With @samp{%define api.prefix c}, it defines @code{CDEBUG} to 1,
+Bison}).  With @samp{%define api.prefix @{c@}}, it defines @code{CDEBUG} to 1,

 otherwise it defines @code{YYDEBUG} to 1.
 
 @item the directive @samp{%debug}
 otherwise it defines @code{YYDEBUG} to 1.
 
 @item the directive @samp{%debug}


@@ -10062,18 +10093,16 @@ A category can be turned off by prefixing its name with @samp{no-}.  For
 instance, @option{-Wno-yacc} will hide the warnings about
 POSIX Yacc incompatibilities.
 
 instance, @option{-Wno-yacc} will hide the warnings about
 POSIX Yacc incompatibilities.
 

-@item -Werror[=@var{category}]
-@itemx -Wno-error[=@var{category}]
-Enable warnings falling in @var{category}, and treat them as errors.  If no
-@var{category} is given, it defaults to making all enabled warnings into errors.
+@item -Werror
+Turn enabled warnings for every @var{category} into errors, unless they are
+explicitly disabled by @option{-Wno-error=@var{category}}.
+
+@item -Werror=@var{category}
+Enable warnings falling in @var{category}, and treat them as errors.

 
 @var{category} is the same as for @option{--warnings}, with the exception that
 it may not be prefixed with @samp{no-} (see above).
 
 
 @var{category} is the same as for @option{--warnings}, with the exception that
 it may not be prefixed with @samp{no-} (see above).
 

-Prefixed with @samp{no}, it deactivates the error treatment for this
-@var{category}. However, the warning itself won't be disabled, or enabled, by
-this option.
-

 Note that the precedence of the @samp{=} and @samp{,} operators is such that
 the following commands are @emph{not} equivalent, as the first will not treat
 S/R conflicts as errors.
 Note that the precedence of the @samp{=} and @samp{,} operators is such that
 the following commands are @emph{not} equivalent, as the first will not treat
 S/R conflicts as errors.


@@ -10083,6 +10112,14 @@ $ bison -Werror=yacc,conflicts-sr input.y
 $ bison -Werror=yacc,error=conflicts-sr input.y
 @end example
 
 $ bison -Werror=yacc,error=conflicts-sr input.y
 @end example
 

+@item -Wno-error
+Do not turn enabled warnings for every @var{category} into errors, unless
+they are explicitly enabled by @option{-Werror=@var{category}}.
+
+@item -Wno-error=@var{category}
+Deactivate the error treatment for this @var{category}. However, the warning
+itself won't be disabled, or enabled, by this option.
+

 @item -f [@var{feature}]
 @itemx --feature[=@var{feature}]
 Activate miscellaneous @var{feature}. @var{feature} can be one of:
 @item -f [@var{feature}]
 @itemx --feature[=@var{feature}]
 Activate miscellaneous @var{feature}. @var{feature} can be one of:


@@ -10649,12 +10686,17 @@ The first, inclusive, position of the range, and the first beyond.
 Forwarded to the @code{end} position.
 @end deftypemethod
 
 Forwarded to the @code{end} position.
 @end deftypemethod
 

-@deftypemethod {location} {location} operator+ (const location& @var{end})
-@deftypemethodx {location} {location} operator+ (int @var{width})
+@deftypemethod  {location} {location} operator+  (int @var{width})

 @deftypemethodx {location} {location} operator+= (int @var{width})
 @deftypemethodx {location} {location} operator+= (int @var{width})

-@deftypemethodx {location} {location} operator- (int @var{width})
+@deftypemethodx {location} {location} operator-  (int @var{width})

 @deftypemethodx {location} {location} operator-= (int @var{width})
 @deftypemethodx {location} {location} operator-= (int @var{width})

-Various forms of syntactic sugar.
+Various forms of syntactic sugar for @code{columns}.
+@end deftypemethod
+
+@deftypemethod {location} {location} operator+ (const location& @var{end})
+@deftypemethodx {location} {location} operator+= (const location& @var{end})
+Join two locations: starts at the position of the first one, and ends at the
+position of the second.

 @end deftypemethod
 
 @deftypemethod {location} {void} step ()
 @end deftypemethod
 
 @deftypemethod {location} {void} step ()


@@ -10680,7 +10722,7 @@ Instead of using the built-in types you may use the @code{%define} variable
 @code{api.location.type} to specify your own type:
 
 @example
 @code{api.location.type} to specify your own type:
 
 @example

-%define api.location.type @var{LocationType}
+%define api.location.type @{@var{LocationType}@}

 @end example
 
 The requirements over your @var{LocationType} are:
 @end example
 
 The requirements over your @var{LocationType} are:


@@ -10717,7 +10759,7 @@ parser @file{master/parser.yy} might use:
 @example
 %defines
 %locations
 @example
 %defines
 %locations

-%define namespace "master::"
+%define api.namespace @{master::@}

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -10725,7 +10767,7 @@ to generate the @file{master/position.hh} and @file{master/location.hh}
 files, reused by other parsers as follows:
 
 @example
 files, reused by other parsers as follows:
 
 @example

-%define api.location.type "master::location"
+%define api.location.type @{master::location@}

 %code requires @{ #include <master/location.hh> @}
 @end example
 
 %code requires @{ #include <master/location.hh> @}
 @end example
 


@@ -10740,7 +10782,7 @@ files, reused by other parsers as follows:
 The output files @file{@var{output}.hh} and @file{@var{output}.cc}
 declare and define the parser class in the namespace @code{yy}.  The
 class name defaults to @code{parser}, but may be changed using
 The output files @file{@var{output}.hh} and @file{@var{output}.cc}
 declare and define the parser class in the namespace @code{yy}.  The
 class name defaults to @code{parser}, but may be changed using

-@samp{%define parser_class_name "@var{name}"}.  The interface of
+@samp{%define parser_class_name @{@var{name}@}}.  The interface of

 this class is detailed below.  It can be extended using the
 @code{%parse-param} feature: its semantics is slightly changed since
 it describes an additional member of the parser class, and an
 this class is detailed below.  It can be extended using the
 @code{%parse-param} feature: its semantics is slightly changed since
 it describes an additional member of the parser class, and an


@@ -11145,7 +11187,7 @@ the grammar for.
 %skeleton "lalr1.cc" /* -*- C++ -*- */
 %require "@value{VERSION}"
 %defines
 %skeleton "lalr1.cc" /* -*- C++ -*- */
 %require "@value{VERSION}"
 %defines

-%define parser_class_name "calcxx_parser"
+%define parser_class_name @{calcxx_parser@}

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -11498,6 +11540,7 @@ main (int argc, char *argv[])
 * 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 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 Push Parser Interface::  Instantiating and running the a push parser

 * Java Differences::            Differences between C/C++ and Java Grammars
 * Java Declarations Summary::   List of Bison declarations used with Java
 @end menu
 * Java Differences::            Differences between C/C++ and Java Grammars
 * Java Declarations Summary::   List of Bison declarations used with Java
 @end menu


@@ -11579,7 +11622,7 @@ superclass of all the semantic values using the @samp{%define api.value.type}
 directive.  For example, after the following declaration:
 
 @example
 directive.  For example, after the following declaration:
 
 @example

-%define api.value.type "ASTNode"
+%define api.value.type @{ASTNode@}

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -11614,11 +11657,11 @@ class defines a @dfn{position}, a single point in a file; Bison itself
 defines a class representing a @dfn{location}, a range composed of a pair of
 positions (possibly spanning several files).  The location class is an inner
 class of the parser; the name is @code{Location} by default, and may also be
 defines a class representing a @dfn{location}, a range composed of a pair of
 positions (possibly spanning several files).  The location class is an inner
 class of the parser; the name is @code{Location} by default, and may also be

-renamed using @code{%define api.location.type "@var{class-name}"}.
+renamed using @code{%define api.location.type @{@var{class-name}@}}.

 
 The location class treats the position as a completely opaque value.
 By default, the class name is @code{Position}, but this can be changed
 
 The location class treats the position as a completely opaque value.
 By default, the class name is @code{Position}, but this can be changed

-with @code{%define api.position.type "@var{class-name}"}.  This class must
+with @code{%define api.position.type @{@var{class-name}@}}.  This class must

 be supplied by the user.
 
 
 be supplied by the user.
 
 


@@ -11653,7 +11696,7 @@ properly, the position class should override the @code{equals} and
 The name of the generated parser class defaults to @code{YYParser}.  The
 @code{YY} prefix may be changed using the @code{%name-prefix} directive
 or the @option{-p}/@option{--name-prefix} option.  Alternatively, use
 The name of the generated parser class defaults to @code{YYParser}.  The
 @code{YY} prefix may be changed using the @code{%name-prefix} directive
 or the @option{-p}/@option{--name-prefix} option.  Alternatively, use

-@samp{%define parser_class_name "@var{name}"} to give a custom name to
+@samp{%define parser_class_name @{@var{name}@}} to give a custom name to

 the class.  The interface of this class is detailed below.
 
 By default, the parser class has package visibility.  A declaration
 the class.  The interface of this class is detailed below.
 
 By default, the parser class has package visibility.  A declaration


@@ -11662,7 +11705,7 @@ according to the Java language specification, the name of the @file{.java}
 file should match the name of the class in this case.  Similarly, you can
 use @code{abstract}, @code{final} and @code{strictfp} with the
 @code{%define} declaration to add other modifiers to the parser class.
 file should match the name of the class in this case.  Similarly, you can
 use @code{abstract}, @code{final} and @code{strictfp} with the
 @code{%define} declaration to add other modifiers to the parser class.

-A single @samp{%define annotations "@var{annotations}"} directive can
+A single @samp{%define annotations @{@var{annotations}@}} directive can

 be used to add any number of annotations to the parser class.
 
 The Java package name of the parser class can be specified using the
 be used to add any number of annotations to the parser class.
 
 The Java package name of the parser class can be specified using the


@@ -11780,7 +11823,7 @@ In both cases, the scanner has to implement the following methods.
 @deftypemethod {Lexer} {void} yyerror (Location @var{loc}, String @var{msg})
 This method is defined by the user to emit an error message.  The first
 parameter is omitted if location tracking is not active.  Its type can be
 @deftypemethod {Lexer} {void} yyerror (Location @var{loc}, String @var{msg})
 This method is defined by the user to emit an error message.  The first
 parameter is omitted if location tracking is not active.  Its type can be

-changed using @code{%define api.location.type "@var{class-name}".}
+changed using @code{%define api.location.type @{@var{class-name}@}}.

 @end deftypemethod
 
 @deftypemethod {Lexer} {int} yylex ()
 @end deftypemethod
 
 @deftypemethod {Lexer} {int} yylex ()


@@ -11799,17 +11842,16 @@ Return respectively the first position of the last token that
 methods are not needed unless location tracking is active.
 
 The return type can be changed using @code{%define api.position.type
 methods are not needed unless location tracking is active.
 
 The return type can be changed using @code{%define api.position.type

-"@var{class-name}".}
+@{@var{class-name}@}}.

 @end deftypemethod
 
 @deftypemethod {Lexer} {Object} getLVal ()
 Return the semantic value of the last token that yylex returned.
 
 The return type can be changed using @samp{%define api.value.type
 @end deftypemethod
 
 @deftypemethod {Lexer} {Object} getLVal ()
 Return the semantic value of the last token that yylex returned.
 
 The return type can be changed using @samp{%define api.value.type

-"@var{class-name}".}
+@{@var{class-name}@}}.

 @end deftypemethod
 
 @end deftypemethod
 

-

 @node Java Action Features
 @subsection Special Features for Use in Java Actions
 
 @node Java Action Features
 @subsection Special Features for Use in Java Actions
 


@@ -11888,6 +11930,73 @@ instance in use. The @code{Location} and @code{Position} parameters are
 available only if location tracking is active.
 @end deftypefn
 
 available only if location tracking is active.
 @end deftypefn
 

+@node Java Push Parser Interface
+@subsection Java Push Parser Interface
+@c - define push_parse
+@findex %define api.push-pull
+
+(The current push parsing interface is experimental and may evolve. More
+user feedback will help to stabilize it.)
+
+Normally, Bison generates a pull parser for Java.
+The following Bison declaration says that you want the parser to be a push
+parser (@pxref{%define Summary,,api.push-pull}):
+
+@example
+%define api.push-pull push
+@end example
+
+Most of the discussion about the Java pull Parser Interface, (@pxref{Java
+Parser Interface}) applies to the push parser interface as well.
+
+When generating a push parser, the method @code{push_parse} is created with
+the following signature (depending on if locations are enabled).
+
+@deftypemethod {YYParser} {void} push_parse ({int} @var{token}, {Object} @var{yylval})
+@deftypemethodx {YYParser} {void} push_parse ({int} @var{token}, {Object} @var{yylval}, {Location} @var{yyloc})
+@deftypemethodx {YYParser} {void} push_parse ({int} @var{token}, {Object} @var{yylval}, {Position} @var{yypos})
+@end deftypemethod
+
+The primary difference with respect to a pull parser is that the parser
+method @code{push_parse} is invoked repeatedly to parse each token.  This
+function is available if either the "%define api.push-pull push" or "%define
+api.push-pull both" declaration is used (@pxref{%define
+Summary,,api.push-pull}).  The @code{Location} and @code{Position}
+parameters are available only if location tracking is active.
+
+The value returned by the @code{push_parse} method is one of the following
+four constants: @code{YYABORT}, @code{YYACCEPT}, @code{YYERROR}, or
+@code{YYPUSH_MORE}.  This new value, @code{YYPUSH_MORE}, may be returned if
+more input is required to finish parsing the grammar.
+
+If api.push-pull is declared as @code{both}, then the generated parser class
+will also implement the @code{parse} method. This method's body is a loop
+that repeatedly invokes the scanner and then passes the values obtained from
+the scanner to the @code{push_parse} method.
+
+There is one additional complication.  Technically, the push parser does not
+need to know about the scanner (i.e. an object implementing the
+@code{YYParser.Lexer} interface), but it does need access to the
+@code{yyerror} method.  Currently, the @code{yyerror} method is defined in
+the @code{YYParser.Lexer} interface. Hence, an implementation of that
+interface is still required in order to provide an implementation of
+@code{yyerror}.  The current approach (and subject to change) is to require
+the @code{YYParser} constructor to be given an object implementing the
+@code{YYParser.Lexer} interface. This object need only implement the
+@code{yyerror} method; the other methods can be stubbed since they will
+never be invoked.  The simplest way to do this is to add a trivial scanner
+implementation to your grammar file using whatever implementation of
+@code{yyerror} is desired. The following code sample shows a simple way to
+accomplish this.
+
+@example
+%code lexer
+@{
+  public Object getLVal () @{return null;@}
+  public int yylex () @{return 0;@}
+  public void yyerror (String s) @{System.err.println(s);@}
+@}
+@end example

 
 @node Java Differences
 @subsection Differences between C/C++ and Java Grammars
 
 @node Java Differences
 @subsection Differences between C/C++ and Java Grammars


@@ -12027,12 +12136,12 @@ Whether the parser class is declared @code{abstract}.  Default is false.
 @xref{Java Bison Interface}.
 @end deffn
 
 @xref{Java Bison Interface}.
 @end deffn
 

-@deffn {Directive} {%define annotations} "@var{annotations}"
+@deffn {Directive} {%define annotations} @{@var{annotations}@}

 The Java annotations for the parser class.  Default is none.
 @xref{Java Bison Interface}.
 @end deffn
 
 The Java annotations for the parser class.  Default is none.
 @xref{Java Bison Interface}.
 @end deffn
 

-@deffn {Directive} {%define extends} "@var{superclass}"
+@deffn {Directive} {%define extends} @{@var{superclass}@}

 The superclass of the parser class.  Default is none.
 @xref{Java Bison Interface}.
 @end deffn
 The superclass of the parser class.  Default is none.
 @xref{Java Bison Interface}.
 @end deffn


@@ -12042,25 +12151,25 @@ Whether the parser class is declared @code{final}.  Default is false.
 @xref{Java Bison Interface}.
 @end deffn
 
 @xref{Java Bison Interface}.
 @end deffn
 

-@deffn {Directive} {%define implements} "@var{interfaces}"
+@deffn {Directive} {%define implements} @{@var{interfaces}@}

 The implemented interfaces of the parser class, a comma-separated list.
 Default is none.
 @xref{Java Bison Interface}.
 @end deffn
 
 The implemented interfaces of the parser class, a comma-separated list.
 Default is none.
 @xref{Java Bison Interface}.
 @end deffn
 

-@deffn {Directive} {%define init_throws} "@var{exceptions}"
+@deffn {Directive} {%define init_throws} @{@var{exceptions}@}

 The exceptions thrown by @code{%code init} from the parser class
 constructor.  Default is none.
 @xref{Java Parser Interface}.
 @end deffn
 
 The exceptions thrown by @code{%code init} from the parser class
 constructor.  Default is none.
 @xref{Java Parser Interface}.
 @end deffn
 

-@deffn {Directive} {%define lex_throws} "@var{exceptions}"
+@deffn {Directive} {%define lex_throws} @{@var{exceptions}@}

 The exceptions thrown by the @code{yylex} method of the lexer, a
 comma-separated list.  Default is @code{java.io.IOException}.
 @xref{Java Scanner Interface}.
 @end deffn
 
 The exceptions thrown by the @code{yylex} method of the lexer, a
 comma-separated list.  Default is @code{java.io.IOException}.
 @xref{Java Scanner Interface}.
 @end deffn
 

-@deffn {Directive} {%define api.location.type} "@var{class}"
+@deffn {Directive} {%define api.location.type} @{@var{class}@}

 The name of the class used for locations (a range between two
 positions).  This class is generated as an inner class of the parser
 class by @command{bison}.  Default is @code{Location}.
 The name of the class used for locations (a range between two
 positions).  This class is generated as an inner class of the parser
 class by @command{bison}.  Default is @code{Location}.


@@ -12068,18 +12177,18 @@ Formerly named @code{location_type}.
 @xref{Java Location Values}.
 @end deffn
 
 @xref{Java Location Values}.
 @end deffn
 

-@deffn {Directive} {%define package} "@var{package}"
+@deffn {Directive} {%define package} @{@var{package}@}

 The package to put the parser class in.  Default is none.
 @xref{Java Bison Interface}.
 @end deffn
 
 The package to put the parser class in.  Default is none.
 @xref{Java Bison Interface}.
 @end deffn
 

-@deffn {Directive} {%define parser_class_name} "@var{name}"
+@deffn {Directive} {%define parser_class_name} @{@var{name}@}

 The name of the parser class.  Default is @code{YYParser} or
 @code{@var{name-prefix}Parser}.
 @xref{Java Bison Interface}.
 @end deffn
 
 The name of the parser class.  Default is @code{YYParser} or
 @code{@var{name-prefix}Parser}.
 @xref{Java Bison Interface}.
 @end deffn
 

-@deffn {Directive} {%define api.position.type} "@var{class}"
+@deffn {Directive} {%define api.position.type} @{@var{class}@}

 The name of the class used for positions. This class must be supplied by
 the user.  Default is @code{Position}.
 Formerly named @code{position_type}.
 The name of the class used for positions. This class must be supplied by
 the user.  Default is @code{Position}.
 Formerly named @code{position_type}.


@@ -12091,7 +12200,7 @@ Whether the parser class is declared @code{public}.  Default is false.
 @xref{Java Bison Interface}.
 @end deffn
 
 @xref{Java Bison Interface}.
 @end deffn
 

-@deffn {Directive} {%define api.value.type} "@var{class}"
+@deffn {Directive} {%define api.value.type} @{@var{class}@}

 The base type of semantic values.  Default is @code{Object}.
 @xref{Java Semantic Values}.
 @end deffn
 The base type of semantic values.  Default is @code{Object}.
 @xref{Java Semantic Values}.
 @end deffn


@@ -12101,7 +12210,7 @@ Whether the parser class is declared @code{strictfp}.  Default is false.
 @xref{Java Bison Interface}.
 @end deffn
 
 @xref{Java Bison Interface}.
 @end deffn
 

-@deffn {Directive} {%define throws} "@var{exceptions}"
+@deffn {Directive} {%define throws} @{@var{exceptions}@}

 The exceptions thrown by user-supplied parser actions and
 @code{%initial-action}, a comma-separated list.  Default is none.
 @xref{Java Parser Interface}.
 The exceptions thrown by user-supplied parser actions and
 @code{%initial-action}, a comma-separated list.  Default is none.
 @xref{Java Parser Interface}.


@@ -12655,6 +12764,7 @@ Precedence}.
 
 @deffn {Directive} %define @var{variable}
 @deffnx {Directive} %define @var{variable} @var{value}
 
 @deffn {Directive} %define @var{variable}
 @deffnx {Directive} %define @var{variable} @var{value}

+@deffnx {Directive} %define @var{variable} @{@var{value}@}

 @deffnx {Directive} %define @var{variable} "@var{value}"
 Define a variable to adjust Bison's behavior.  @xref{%define Summary}.
 @end deffn
 @deffnx {Directive} %define @var{variable} "@var{value}"
 Define a variable to adjust Bison's behavior.  @xref{%define Summary}.
 @end deffn


@@ -12758,7 +12868,7 @@ 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{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.
+@code{%define api.namespace} documentation in this section.

 @end deffn
 
 
 @end deffn