%define lr.type: make values lowercase IDs.

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index b09cf842a8ff22cf3f4e04fd07fd49bb52577683..6dd6037fc8a83581c0559fb04be7b0f9b9bc132e 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -3806,8 +3806,11 @@ typedef struct YYLTYPE
 @} YYLTYPE;
 @end example
 
 @} YYLTYPE;
 @end example
 

-At the beginning of the parsing, Bison initializes all these fields to 1
-for @code{yylloc}.
+When @code{YYLTYPE} is not defined, at the beginning of the parsing, Bison
+initializes all these fields to 1 for @code{yylloc}.  To initialize
+@code{yylloc} with a custom location type (or to chose a different
+initialization), use the @code{%initial-action} directive.  @xref{Initial
+Action Decl, , Performing Actions before Parsing}.

 
 @node Actions and Locations
 @subsection Actions and Locations
 
 @node Actions and Locations
 @subsection Actions and Locations


@@ -4541,7 +4544,7 @@ statically allocated variables for communication with @code{yylex},
 including @code{yylval} and @code{yylloc}.)
 
 Alternatively, you can generate a pure, reentrant parser.  The Bison
 including @code{yylval} and @code{yylloc}.)
 
 Alternatively, you can generate a pure, reentrant parser.  The Bison

-declaration @code{%define api.pure} says that you want the parser to be
+declaration @samp{%define api.pure} says that you want the parser to be

 reentrant.  It looks like this:
 
 @example
 reentrant.  It looks like this:
 
 @example


@@ -4645,14 +4648,14 @@ 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{%define api.push-pull "push"} declaration with the
-@code{%define api.push-pull "both"} declaration.  Doing this will create all of
+you should replace the @samp{%define api.push-pull "push"} declaration with the
+@samp{%define api.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
 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 api.push-pull "both"} declaration slower than the normal
+@samp{%define api.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
 @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


@@ -4668,9 +4671,9 @@ yypull_parse (ps); /* Will call the lexer */
 yypstate_delete (ps);
 @end example
 
 yypstate_delete (ps);
 @end example
 

-Adding the @code{%define api.pure} declaration does exactly the same thing to
-the generated parser with @code{%define api.push-pull "both"} as it did for
-@code{%define api.push-pull "push"}.
+Adding the @samp{%define api.pure} declaration does exactly the same thing to
+the generated parser with @samp{%define api.push-pull "both"} as it did for
+@samp{%define api.push-pull "push"}.

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


@@ -4845,7 +4848,8 @@ 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}, @pxref{Decl Summary,,%skeleton}).
 
 the selected target language and/or the parser skeleton (@pxref{Decl
 Summary,,%language}, @pxref{Decl Summary,,%skeleton}).
 

-Bison will warn if a @var{variable} is defined multiple times.
+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}]}.

 
 Omitting @code{"@var{value}"} is always equivalent to specifying it as
 @code{""}.
 
 Omitting @code{"@var{value}"} is always equivalent to specifying it as
 @code{""}.


@@ -4870,6 +4874,61 @@ target language and/or parser skeleton.
 Some of the accepted @var{variable}s are:
 
 @table @code
 Some of the accepted @var{variable}s are:
 
 @table @code

+@c ================================================== namespace
+@item api.namespace
+@findex %define api.namespace
+@itemize
+@item Languages(s): C++
+
+@item Purpose: Specifies the namespace for the parser class.
+For example, if you specify:
+
+@smallexample
+%define api.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 @samp{%define
+api.namespace} so that @code{%name-prefix} @emph{only} affects the
+lexical analyzer function.  For example, if you specify:
+
+@smallexample
+%define api.namespace "foo"
+%name-prefix "bar::"
+@end smallexample
+
+The parser namespace is @code{foo} and @code{yylex} is referenced as
+@code{bar::lex}.
+@end itemize
+@c namespace
+
+
+
+@c ================================================== api.pure

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


@@ -4885,6 +4944,9 @@ Some of the accepted @var{variable}s are:
 @end itemize
 @c api.pure
 
 @end itemize
 @c api.pure
 

+
+
+@c ================================================== api.push-pull

 @item api.push-pull
 @findex %define api.push-pull
 
 @item api.push-pull
 @findex %define api.push-pull
 


@@ -4902,21 +4964,41 @@ More user feedback will help to stabilize it.)
 @end itemize
 @c api.push-pull
 
 @end itemize
 @c api.push-pull
 

-@item error-verbose
-@findex %define error-verbose
+@item api.tokens.prefix
+@findex %define api.tokens.prefix
+

 @itemize
 @itemize

-@item Languages(s):
-all.
+@item Languages(s): all
+

 @item Purpose:
 @item Purpose:

-Enable the generation of more verbose error messages than a instead of
-just plain @w{@code{"syntax error"}}.  @xref{Error Reporting, ,The Error
-Reporting Function @code{yyerror}}.
+Add a prefix to the token names when generating their definition in the
+target language.  For instance
+
+@example
+%token FILE for ERROR
+%define api.tokens.prefix "TOK_"
+%%
+start: FILE for ERROR;
+@end example
+
+@noindent
+generates the definition of the symbols @code{TOK_FILE}, @code{TOK_for},
+and @code{TOK_ERROR} in the generated source files.  In particular, the
+scanner must use these prefixed token names, while the grammar itself
+may still use the short names (as in the sample rule given above).  The
+generated informational files (@file{*.output}, @file{*.xml},
+@file{*.dot}) are not modified by this prefix.  See @ref{Calc++ Parser}
+and @ref{Calc++ Scanner}, for a complete example.
+

 @item Accepted Values:
 @item Accepted Values:

-Boolean
+Any string.  Should be a valid identifier prefix in the target language,
+in other words, it should typically be an identifier itself (sequence of
+letters, underscores, and ---not at the beginning--- digits).
+

 @item Default Value:
 @item Default Value:

-@code{false}
+empty

 @end itemize
 @end itemize

-@c error-verbose
+@c api.tokens.prefix

 
 
 @item lr.default-reductions
 
 
 @item lr.default-reductions


@@ -4979,7 +5061,7 @@ without performing any extra reductions.
 
 @item Default Value:
 @itemize
 
 @item Default Value:
 @itemize

-@item @code{"accepting"} if @code{lr.type} is @code{"canonical LR"}.
+@item @code{"accepting"} if @code{lr.type} is @code{"canonical-lr"}.

 @item @code{"all"} otherwise.
 @end itemize
 @end itemize
 @item @code{"all"} otherwise.
 @end itemize
 @end itemize


@@ -5044,7 +5126,7 @@ More user feedback will help to stabilize it.)
 
 @item Accepted Values:
 @itemize
 
 @item Accepted Values:
 @itemize

-@item @code{"LALR"}.
+@item @code{"lalr"}.

 While Bison generates @acronym{LALR} parser tables by default for
 historical reasons, @acronym{IELR} or canonical @acronym{LR} is almost
 always preferable for deterministic parsers.
 While Bison generates @acronym{LALR} parser tables by default for
 historical reasons, @acronym{IELR} or canonical @acronym{LR} is almost
 always preferable for deterministic parsers.


@@ -5073,7 +5155,7 @@ investigate such problems while ignoring the more subtle differences
 from @acronym{IELR} and canonical @acronym{LR}.
 @end itemize
 
 from @acronym{IELR} and canonical @acronym{LR}.
 @end itemize
 

-@item @code{"IELR"}.
+@item @code{"ielr"}.

 @acronym{IELR} is a minimal @acronym{LR} algorithm.
 That is, given any grammar (@acronym{LR} or non-@acronym{LR}),
 @acronym{IELR} and canonical @acronym{LR} always accept exactly the same
 @acronym{IELR} is a minimal @acronym{LR} algorithm.
 That is, given any grammar (@acronym{LR} or non-@acronym{LR}),
 @acronym{IELR} and canonical @acronym{LR} always accept exactly the same


@@ -5087,7 +5169,7 @@ grammars, the number of conflicts for @acronym{IELR} is often an order
 of magnitude less as well.
 This can significantly reduce the complexity of developing of a grammar.
 
 of magnitude less as well.
 This can significantly reduce the complexity of developing of a grammar.
 

-@item @code{"canonical LR"}.
+@item @code{"canonical-lr"}.

 @cindex delayed syntax errors
 @cindex syntax errors delayed
 The only advantage of canonical @acronym{LR} over @acronym{IELR} is
 @cindex delayed syntax errors
 @cindex syntax errors delayed
 The only advantage of canonical @acronym{LR} over @acronym{IELR} is


@@ -5103,62 +5185,18 @@ Even when canonical @acronym{LR} behavior is ultimately desired,
 facilitate the development of a grammar.
 @end itemize
 
 facilitate the development of a grammar.
 @end itemize
 

-@item Default Value: @code{"LALR"}
+@item Default Value: @code{"lalr"}

 @end itemize
 
 @end itemize
 

+
+@c ================================================== namespace

 @item namespace
 @findex %define namespace
 @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
+Obsoleted by @code{api.namespace}

 @c namespace
 
 @c namespace
 

+
+@c ================================================== parse.assert

 @item parse.assert
 @findex %define parse.assert
 
 @item parse.assert
 @findex %define parse.assert
 


@@ -5175,6 +5213,34 @@ destroyed properly.  This option checks these constraints.
 @end itemize
 @c parse.assert
 
 @end itemize
 @c parse.assert
 

+
+@c ================================================== parse.error
+@item parse.error
+@findex %define parse.error
+@itemize
+@item Languages(s):
+all.
+@item Purpose:
+Control the kind of error messages passed to the error reporting
+function.  @xref{Error Reporting, ,The Error Reporting Function
+@code{yyerror}}.
+@item Accepted Values:
+@itemize
+@item @code{"simple"}
+Error messages passed to @code{yyerror} are simply @w{@code{"syntax
+error"}}.
+@item @code{"verbose"}
+Error messages report the unexpected token, and possibly the expected
+ones.
+@end itemize
+
+@item Default Value:
+@code{simple}
+@end itemize
+@c parse.error
+
+
+@c ================================================== parse.trace

 @item parse.trace
 @findex %define parse.trace
 
 @item parse.trace
 @findex %define parse.trace
 


@@ -5190,10 +5256,11 @@ is not already defined, so that the debugging facilities are compiled.
 
 @item Default Value: @code{false}
 @end itemize
 
 @item Default Value: @code{false}
 @end itemize

-@end table

 @c parse.trace
 @c parse.trace

+
+@end table

 @end deffn
 @end deffn

-@c %define
+@c ----------------------------------------------------------   %define

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


@@ -5277,7 +5344,7 @@ is @code{yyparse}, @code{yylex}, @code{yyerror}, @code{yynerrs},
 @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.
 @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
+For C++ parsers, see the @samp{%define api.namespace} documentation in this

 section.
 @xref{Multiple Parsers, ,Multiple Parsers in the Same Program}.
 @end deffn
 section.
 @xref{Multiple Parsers, ,Multiple Parsers in the Same Program}.
 @end deffn


@@ -5304,7 +5371,7 @@ Specify @var{file} for the parser file.
 @end deffn
 
 @deffn {Directive} %pure-parser
 @end deffn
 
 @deffn {Directive} %pure-parser

-Deprecated version of @code{%define api.pure} (@pxref{Decl Summary, ,%define}),
+Deprecated version of @samp{%define api.pure} (@pxref{Decl Summary, ,%define}),

 for which Bison is more careful to warn about unreasonable usage.
 @end deffn
 
 for which Bison is more careful to warn about unreasonable usage.
 @end deffn
 


@@ -5518,8 +5585,8 @@ exp: @dots{}    @{ @dots{}; *randomness += 1; @dots{} @}
 More user feedback will help to stabilize it.)
 
 You call the function @code{yypush_parse} to parse a single token.  This
 More user feedback will help to stabilize it.)
 
 You call the function @code{yypush_parse} to parse a single token.  This

-function is available if either the @code{%define api.push-pull "push"} or
-@code{%define api.push-pull "both"} declaration is used.
+function is available if either the @samp{%define api.push-pull "push"} or
+@samp{%define api.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)


@@ -5536,7 +5603,7 @@ is required to finish parsing the grammar.
 More user feedback will help to stabilize it.)
 
 You call the function @code{yypull_parse} to parse the rest of the input
 More user feedback will help to stabilize it.)
 
 You call the function @code{yypull_parse} to parse the rest of the input

-stream.  This function is available if the @code{%define api.push-pull "both"}
+stream.  This function is available if the @samp{%define api.push-pull "both"}

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


@@ -5552,8 +5619,8 @@ The value returned by @code{yypull_parse} is the same as for @code{yyparse}.
 More user feedback will help to stabilize it.)
 
 You call the function @code{yypstate_new} to create a new parser instance.
 More user feedback will help to stabilize it.)
 
 You call the function @code{yypstate_new} to create a new parser instance.

-This function is available if either the @code{%define api.push-pull "push"} or
-@code{%define api.push-pull "both"} declaration is used.
+This function is available if either the @samp{%define api.push-pull "push"} or
+@samp{%define api.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)


@@ -5571,8 +5638,8 @@ allocated.
 More user feedback will help to stabilize it.)
 
 You call the function @code{yypstate_delete} to delete a parser instance.
 More user feedback will help to stabilize it.)
 
 You call the function @code{yypstate_delete} to delete a parser instance.

-function is available if either the @code{%define api.push-pull "push"} or
-@code{%define api.push-pull "both"} declaration is used.
+function is available if either the @samp{%define api.push-pull "push"} or
+@samp{%define api.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)


@@ -5760,7 +5827,7 @@ The data type of @code{yylloc} has the name @code{YYLTYPE}.
 @node Pure Calling
 @subsection Calling Conventions for Pure Parsers
 
 @node Pure Calling
 @subsection Calling Conventions for Pure Parsers
 

-When you use the Bison declaration @code{%define api.pure} to request a
+When you use the Bison declaration @samp{%define api.pure} to request a

 pure, reentrant parser, the global communication variables @code{yylval}
 and @code{yylloc} cannot be used.  (@xref{Pure Decl, ,A Pure (Reentrant)
 Parser}.)  In such parsers the two global variables are replaced by
 pure, reentrant parser, the global communication variables @code{yylval}
 and @code{yylloc} cannot be used.  (@xref{Pure Decl, ,A Pure (Reentrant)
 Parser}.)  In such parsers the two global variables are replaced by


@@ -5811,7 +5878,7 @@ int yylex   (int *nastiness);
 int yyparse (int *nastiness, int *randomness);
 @end example
 
 int yyparse (int *nastiness, int *randomness);
 @end example
 

-If @code{%define api.pure} is added:
+If @samp{%define api.pure} is added:

 
 @example
 int yylex   (YYSTYPE *lvalp, int *nastiness);
 
 @example
 int yylex   (YYSTYPE *lvalp, int *nastiness);


@@ -5819,7 +5886,7 @@ int yyparse (int *nastiness, int *randomness);
 @end example
 
 @noindent
 @end example
 
 @noindent

-and finally, if both @code{%define api.pure} and @code{%locations} are used:
+and finally, if both @samp{%define api.pure} and @code{%locations} are used:

 
 @example
 int yylex   (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness);
 
 @example
 int yylex   (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness);


@@ -5833,7 +5900,7 @@ int yyparse (int *nastiness, int *randomness);
 @cindex parse error
 @cindex syntax error
 
 @cindex parse error
 @cindex syntax error
 

-The Bison parser detects a @dfn{syntax error} or @dfn{parse error}
+The Bison parser detects a @dfn{syntax error} (or @dfn{parse error})

 whenever it reads a token which cannot satisfy any syntax rule.  An
 action in the grammar can also explicitly proclaim an error, using the
 macro @code{YYERROR} (@pxref{Action Features, ,Special Features for Use
 whenever it reads a token which cannot satisfy any syntax rule.  An
 action in the grammar can also explicitly proclaim an error, using the
 macro @code{YYERROR} (@pxref{Action Features, ,Special Features for Use


@@ -5845,8 +5912,8 @@ called by @code{yyparse} whenever a syntax error is found, and it
 receives one argument.  For a syntax error, the string is normally
 @w{@code{"syntax error"}}.
 
 receives one argument.  For a syntax error, the string is normally
 @w{@code{"syntax error"}}.
 

-@findex %define error-verbose
-If you invoke the directive @code{%define error-verbose} in the Bison
+@findex %define parse.error
+If you invoke @samp{%define parse.error "verbose"} in the Bison

 declarations section (@pxref{Bison Declarations, ,The Bison Declarations
 Section}), then Bison provides a more verbose and specific error message
 string instead of just plain @w{@code{"syntax error"}}.
 declarations section (@pxref{Bison Declarations, ,The Bison Declarations
 Section}), then Bison provides a more verbose and specific error message
 string instead of just plain @w{@code{"syntax error"}}.


@@ -5903,7 +5970,7 @@ void yyerror (int *nastiness, char const *msg);  /* GLR parsers.   */
 Finally, @acronym{GLR} and Yacc parsers share the same @code{yyerror} calling
 convention for absolutely pure parsers, i.e., when the calling
 convention of @code{yylex} @emph{and} the calling convention of
 Finally, @acronym{GLR} and Yacc parsers share the same @code{yyerror} calling
 convention for absolutely pure parsers, i.e., when the calling
 convention of @code{yylex} @emph{and} the calling convention of

-@code{%define api.pure} are pure.
+@samp{%define api.pure} are pure.

 I.e.:
 
 @example
 I.e.:
 
 @example


@@ -8102,8 +8169,32 @@ already defined, so that the debugging facilities are compiled.
 
 @item -D @var{name}[=@var{value}]
 @itemx --define=@var{name}[=@var{value}]
 
 @item -D @var{name}[=@var{value}]
 @itemx --define=@var{name}[=@var{value}]

-Same as running @samp{%define @var{name} "@var{value}"} (@pxref{Decl
-Summary, ,%define}).
+@itemx -F @var{name}[=@var{value}]
+@itemx --force-define=@var{name}[=@var{value}]
+Each of these is equivalent to @samp{%define @var{name} "@var{value}"}
+(@pxref{Decl Summary, ,%define}) except that Bison processes multiple
+definitions for the same @var{name} as follows:
+
+@itemize
+@item
+Bison quietly ignores all command-line definitions for @var{name} except
+the last.
+@item
+If that command-line definition is specified by a @code{-D} or
+@code{--define}, Bison reports an error for any @code{%define}
+definition for @var{name}.
+@item
+If that command-line definition is specified by a @code{-F} or
+@code{--force-define} instead, Bison quietly ignores all @code{%define}
+definitions for @var{name}.
+@item
+Otherwise, Bison reports an error if there are multiple @code{%define}
+definitions for @var{name}.
+@end itemize
+
+You should avoid using @code{-F} and @code{--force-define} in your
+makefiles unless you are confident that it is safe to quietly ignore any
+conflicting @code{%define} that may be added to the grammar file.

 
 @item -L @var{language}
 @itemx --language=@var{language}
 
 @item -L @var{language}
 @itemx --language=@var{language}


@@ -8229,9 +8320,9 @@ More user feedback will help to stabilize it.)
 @section Option Cross Key
 
 Here is a list of options, alphabetized by long option, to help you find
 @section Option Cross Key
 
 Here is a list of options, alphabetized by long option, to help you find

-the corresponding short option.
+the corresponding short option and directive.

 
 

-@multitable {@option{--defines=@var{defines-file}}} {@option{-D @var{name}[=@var{value}]}} {@code{%nondeterministic-parser}}
+@multitable {@option{--force-define=@var{name}[=@var{value}]}} {@option{-F @var{name}[=@var{value}]}} {@code{%nondeterministic-parser}}

 @headitem Long Option @tab Short Option @tab Bison Directive
 @include cross-options.texi
 @end multitable
 @headitem Long Option @tab Short Option @tab Bison Directive
 @include cross-options.texi
 @end multitable


@@ -8297,8 +8388,9 @@ The C++ deterministic parser is selected using the skeleton directive,
 
 When run, @command{bison} will create several entities in the @samp{yy}
 namespace.
 
 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
+@findex %define api.namespace
+Use the @samp{%define api.namespace} directive to change the namespace
+name, see

 @ref{Decl Summary}.
 The various classes are generated in the following files:
 
 @ref{Decl Summary}.
 The various classes are generated in the following files:
 


@@ -8482,7 +8574,7 @@ described by @var{m}.
 
 The parser invokes the scanner by calling @code{yylex}.  Contrary to C
 parsers, C++ parsers are always pure: there is no point in using the
 
 The parser invokes the scanner by calling @code{yylex}.  Contrary to C
 parsers, C++ parsers are always pure: there is no point in using the

-@code{%define api.pure} directive.  Therefore the interface is as follows.
+@samp{%define api.pure} directive.  Therefore the interface is as follows.

 
 @deftypemethod {parser} {int} yylex (semantic_value_type& @var{yylval}, location_type& @var{yylloc}, @var{type1} @var{arg1}, ...)
 Return the next token.  Its type is the return value, its semantic
 
 @deftypemethod {parser} {int} yylex (semantic_value_type& @var{yylval}, location_type& @var{yylloc}, @var{type1} @var{arg1}, ...)
 Return the next token.  Its type is the return value, its semantic


@@ -8745,7 +8837,7 @@ error messages.
 @comment file: calc++-parser.yy
 @example
 %define parse.trace
 @comment file: calc++-parser.yy
 @example
 %define parse.trace

-%define error-verbose
+%define parse.error "verbose"

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -8777,13 +8869,14 @@ The code between @samp{%code @{} and @samp{@}} is output in the
 
 @noindent
 The token numbered as 0 corresponds to end of file; the following line
 
 @noindent
 The token numbered as 0 corresponds to end of file; the following line

-allows for nicer error messages referring to ``end of file'' instead
-of ``$end''.  Similarly user friendly named are provided for each
-symbol.  Note that the tokens names are prefixed by @code{TOKEN_} to
-avoid name clashes.
+allows for nicer error messages referring to ``end of file'' instead of
+``$end''.  Similarly user friendly names are provided for each symbol.
+To avoid name clashes in the generated files (@pxref{Calc++ Scanner}),
+prefix tokens with @code{TOK_} (@pxref{Decl Summary,, api.tokens.prefix}).

 
 @comment file: calc++-parser.yy
 @example
 
 @comment file: calc++-parser.yy
 @example

+%define api.tokens.prefix "TOK_"

 %token        END      0 "end of file"
 %token        ASSIGN     ":="
 %token <sval> IDENTIFIER "identifier"
 %token        END      0 "end of file"
 %token        ASSIGN     ":="
 %token <sval> IDENTIFIER "identifier"


@@ -8813,22 +8906,24 @@ The grammar itself is straightforward.
 %start unit;
 unit: assignments exp  @{ driver.result = $2; @};
 
 %start unit;
 unit: assignments exp  @{ driver.result = $2; @};
 

-assignments: assignments assignment @{@}
-           | /* Nothing.  */        @{@};
+assignments:
+  assignments assignment @{@}
+| /* Nothing.  */        @{@};

 
 assignment:
 
 assignment:

-     "identifier" ":=" exp
+  "identifier" ":=" exp

        @{ driver.variables[*$1] = $3; delete $1; @};
 
 %left '+' '-';
 %left '*' '/';
        @{ driver.variables[*$1] = $3; delete $1; @};
 
 %left '+' '-';
 %left '*' '/';

-exp: exp '+' exp   @{ $$ = $1 + $3; @}
-   | exp '-' exp   @{ $$ = $1 - $3; @}
-   | exp '*' exp   @{ $$ = $1 * $3; @}
-   | exp '/' exp   @{ $$ = $1 / $3; @}
-   | '(' exp ')'   @{ $$ = $2; @}
-   | "identifier"  @{ $$ = driver.variables[*$1]; delete $1; @}
-   | "number"      @{ $$ = $1; @};
+exp:
+  exp '+' exp   @{ $$ = $1 + $3; @}
+| exp '-' exp   @{ $$ = $1 - $3; @}
+| exp '*' exp   @{ $$ = $1 * $3; @}
+| exp '/' exp   @{ $$ = $1 / $3; @}
+| '(' exp ')'   @{ $$ = $2; @}
+| "identifier"  @{ $$ = driver.variables[*$1]; delete $1; @}
+| "number"      @{ $$ = $1; @};

 %%
 @end example
 
 %%
 @end example
 


@@ -8856,8 +8951,8 @@ parser's to get the set of defined tokens.
 @example
 %@{                                            /* -*- C++ -*- */
 # include <cstdlib>
 @example
 %@{                                            /* -*- C++ -*- */
 # include <cstdlib>

-# include <errno.h>
-# include <limits.h>
+# include <cerrno>
+# include <climits>

 # include <string>
 # include "calc++-driver.hh"
 # include "calc++-parser.hh"
 # include <string>
 # include "calc++-driver.hh"
 # include "calc++-parser.hh"


@@ -8869,10 +8964,10 @@ parser's to get the set of defined tokens.
 # undef yywrap
 # define yywrap() 1
 
 # undef yywrap
 # define yywrap() 1
 

-/* By default yylex returns int, we use token_type.
-   Unfortunately yyterminate by default returns 0, which is
+/* By default yylex returns an int; we use token_type.
+   The default yyterminate implementation returns 0, which is

    not of token_type.  */
    not of token_type.  */

-#define yyterminate() return token::END
+#define yyterminate() return TOKEN(END)

 %@}
 @end example
 
 %@}
 @end example
 


@@ -8920,28 +9015,32 @@ preceding tokens.  Comments would be treated equally.
 @end example
 
 @noindent
 @end example
 
 @noindent

-The rules are simple, just note the use of the driver to report errors.
-It is convenient to use a typedef to shorten
-@code{yy::calcxx_parser::token::identifier} into
-@code{token::identifier} for instance.
+The rules are simple.  The driver is used to report errors.  It is
+convenient to use a macro to shorten
+@code{yy::calcxx_parser::token::TOK_@var{Name}} into
+@code{TOKEN(@var{Name})}; note the token prefix, @code{TOK_}.

 
 @comment file: calc++-scanner.ll
 @example
 %@{
 
 @comment file: calc++-scanner.ll
 @example
 %@{

-  typedef yy::calcxx_parser::token token;
+# define TOKEN(Name)                          \
+  yy::calcxx_parser::token::TOK_ ## Name

 %@}
            /* Convert ints to the actual type of tokens.  */
 [-+*/()]   return yy::calcxx_parser::token_type (yytext[0]);
 %@}
            /* Convert ints to the actual type of tokens.  */
 [-+*/()]   return yy::calcxx_parser::token_type (yytext[0]);

-":="       return token::ASSIGN;
+":="       return TOKEN(ASSIGN);

 @{int@}      @{
   errno = 0;
   long n = strtol (yytext, NULL, 10);
   if (! (INT_MIN <= n && n <= INT_MAX && errno != ERANGE))
     driver.error (*yylloc, "integer is out of range");
   yylval->ival = n;
 @{int@}      @{
   errno = 0;
   long n = strtol (yytext, NULL, 10);
   if (! (INT_MIN <= n && n <= INT_MAX && errno != ERANGE))
     driver.error (*yylloc, "integer is out of range");
   yylval->ival = n;

-  return token::NUMBER;
+  return TOKEN(NUMBER);
+@}
+@{id@}       @{
+  yylval->sval = new std::string (yytext);
+  return TOKEN(IDENTIFIER);

 @}
 @}

-@{id@}       yylval->sval = new std::string (yytext); return token::IDENTIFIER;

 .          driver.error (*yylloc, "invalid character");
 %%
 @end example
 .          driver.error (*yylloc, "invalid character");
 %%
 @end example


@@ -9039,7 +9138,7 @@ You can create documentation for generated parsers using Javadoc.
 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'', and the @code{%pure-parser}
 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'', and the @code{%pure-parser}

-and @code{%define api.pure} directives does not do anything when used in
+and @samp{%define api.pure} directives does not do anything when used in

 Java.
 
 Push parsers are currently unsupported in Java and @code{%define
 Java.
 
 Push parsers are currently unsupported in Java and @code{%define


@@ -9087,7 +9186,7 @@ semantic values' types (class names) should be specified in the
 By default, the semantic stack is declared to have @code{Object} members,
 which means that the class types you specify can be of any class.
 To improve the type safety of the parser, you can declare the common
 By default, the semantic stack is declared to have @code{Object} members,
 which means that the class types you specify can be of any class.
 To improve the type safety of the parser, you can declare the common

-superclass of all the semantic values using the @code{%define stype}
+superclass of all the semantic values using the @samp{%define stype}

 directive.  For example, after the following declaration:
 
 @example
 directive.  For example, after the following declaration:
 
 @example


@@ -9127,11 +9226,11 @@ 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 renamed using
 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 location_type "@var{class-name}}.
+@samp{%define 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 position_type "@var{class-name}"}.  This class must
+with @samp{%define position_type "@var{class-name}"}.  This class must

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


@@ -9166,22 +9265,22 @@ 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

-@code{%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

-@code{%define public} will change to public visibility.  Remember that,
+@samp{%define public} will change to public visibility.  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.  Similarly, you can
 use @code{abstract}, @code{final} and @code{strictfp} with the
 @code{%define} declaration to add other modifiers to the parser class.
 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.

-A single @code{%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

-@code{%define package} directive.  The superclass and the implemented
+@samp{%define package} directive.  The superclass and the implemented

 interfaces of the parser class can be specified with the @code{%define
 interfaces of the parser class can be specified with the @code{%define

-extends} and @code{%define implements} directives.
+extends} and @samp{%define implements} directives.

 
 The parser class defines an inner class, @code{Location}, that is used
 for location tracking (see @ref{Java Location Values}), and a inner
 
 The parser class defines an inner class, @code{Location}, that is used
 for location tracking (see @ref{Java Location Values}), and a inner


@@ -9202,7 +9301,7 @@ used.
 
 Use @code{%code init} for code added to the start of the constructor
 body. This is especially useful to initialize superclasses. Use
 
 Use @code{%code init} for code added to the start of the constructor
 body. This is especially useful to initialize superclasses. Use

-@code{%define init_throws} to specify any uncatch exceptions.
+@samp{%define init_throws} to specify any uncatch exceptions.

 @end deftypeop
 
 @deftypeop {Constructor} {YYParser} {} YYParser (Lexer @var{lexer}, @var{parse_param}, @dots{})
 @end deftypeop
 
 @deftypeop {Constructor} {YYParser} {} YYParser (Lexer @var{lexer}, @var{parse_param}, @dots{})


@@ -9215,7 +9314,7 @@ created with the correct @code{%lex-param}s.
 
 Use @code{%code init} for code added to the start of the constructor
 body. This is especially useful to initialize superclasses. Use
 
 Use @code{%code init} for code added to the start of the constructor
 body. This is especially useful to initialize superclasses. Use

-@code{%define init_throws} to specify any uncatch exceptions.
+@samp{%define init_throws} to specify any uncatch exceptions.

 @end deftypeop
 
 @deftypemethod {YYParser} {boolean} parse ()
 @end deftypeop
 
 @deftypemethod {YYParser} {boolean} parse ()


@@ -9226,7 +9325,7 @@ Run the syntactic analysis, and return @code{true} on success,
 @deftypemethod {YYParser} {boolean} getErrorVerbose ()
 @deftypemethodx {YYParser} {void} setErrorVerbose (boolean @var{verbose})
 Get or set the option to produce verbose error messages.  These are only
 @deftypemethod {YYParser} {boolean} getErrorVerbose ()
 @deftypemethodx {YYParser} {void} setErrorVerbose (boolean @var{verbose})
 Get or set the option to produce verbose error messages.  These are only

-available with the @code{%define error-verbose} directive, which also turn on
+available with @samp{%define parse.error "verbose"}, which also turns on

 verbose error messages.
 @end deftypemethod
 
 verbose error messages.
 @end deftypemethod
 


@@ -9292,7 +9391,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 location_type "@var{class-name}".}
+changed using @samp{%define location_type "@var{class-name}".}

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


@@ -9300,7 +9399,7 @@ Return the next token.  Its type is the return value, its semantic
 value and location are saved and returned by the ther methods in the
 interface.
 
 value and location are saved and returned by the ther methods in the
 interface.
 

-Use @code{%define lex_throws} to specify any uncaught exceptions.
+Use @samp{%define lex_throws} to specify any uncaught exceptions.

 Default is @code{java.io.IOException}.
 @end deftypemethod
 
 Default is @code{java.io.IOException}.
 @end deftypemethod
 


@@ -9310,14 +9409,14 @@ 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.
 
 @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 @code{%define position_type
+The return type can be changed using @samp{%define position_type

 "@var{class-name}".}
 @end deftypemethod
 
 @deftypemethod {Lexer} {Object} getLVal ()
 Return the semantical value of the last token that yylex returned.
 
 "@var{class-name}".}
 @end deftypemethod
 
 @deftypemethod {Lexer} {Object} getLVal ()
 Return the semantical value of the last token that yylex returned.
 

-The return type can be changed using @code{%define stype
+The return type can be changed using @samp{%define stype

 "@var{class-name}".}
 @end deftypemethod
 
 "@var{class-name}".}
 @end deftypemethod
 


@@ -9328,7 +9427,7 @@ The return type can be changed using @code{%define stype
 The following special constructs can be uses in Java actions.
 Other analogous C action features are currently unavailable for Java.
 
 The following special constructs can be uses in Java actions.
 Other analogous C action features are currently unavailable for Java.
 

-Use @code{%define throws} to specify any uncaught exceptions from parser
+Use @samp{%define throws} to specify any uncaught exceptions from parser

 actions, and initial actions specified by @code{%initial-action}.
 
 @defvar $@var{n}
 actions, and initial actions specified by @code{%initial-action}.
 
 @defvar $@var{n}


@@ -9345,7 +9444,7 @@ Like @code{$@var{n}} but specifies a alternative type @var{typealt}.
 @defvar $$
 The semantic value for the grouping made by the current rule.  As a
 value, this is in the base type (@code{Object} or as specified by
 @defvar $$
 The semantic value for the grouping made by the current rule.  As a
 value, this is in the base type (@code{Object} or as specified by

-@code{%define stype}) as in not cast to the declared subtype because
+@samp{%define stype}) as in not cast to the declared subtype because

 casts are not allowed on the left-hand side of Java assignments.
 Use an explicit Java cast if the correct subtype is needed.
 @xref{Java Semantic Values}.
 casts are not allowed on the left-hand side of Java assignments.
 Use an explicit Java cast if the correct subtype is needed.
 @xref{Java Semantic Values}.


@@ -9432,7 +9531,7 @@ corresponds to these C macros.}.
 @item
 Java lacks unions, so @code{%union} has no effect.  Instead, semantic
 values have a common base type: @code{Object} or as specified by
 @item
 Java lacks unions, so @code{%union} has no effect.  Instead, semantic
 values have a common base type: @code{Object} or as specified by

-@code{%define stype}.  Angle backets on @code{%token}, @code{type},
+@samp{%define stype}.  Angle backets on @code{%token}, @code{type},

 @code{$@var{n}} and @code{$$} specify subtypes rather than fields of
 an union.  The type of @code{$$}, even with angle brackets, is the base
 type since Java casts are not allow on the left-hand side of assignments.
 @code{$@var{n}} and @code{$$} specify subtypes rather than fields of
 an union.  The type of @code{$$}, even with angle brackets, is the base
 type since Java casts are not allow on the left-hand side of assignments.


@@ -9446,7 +9545,7 @@ The prolog declarations have a different meaning than in C/C++ code.
 @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
 @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.
+suggested to use @samp{%define package} instead.

 
 @item unqualified @code{%code}
 blocks are placed inside the parser class.
 
 @item unqualified @code{%code}
 blocks are placed inside the parser class.


@@ -9487,7 +9586,7 @@ constructor that @emph{creates} a lexer.  Default is none.
 
 @deffn {Directive} %name-prefix "@var{prefix}"
 The prefix of the parser class name @code{@var{prefix}Parser} if
 
 @deffn {Directive} %name-prefix "@var{prefix}"
 The prefix of the parser class name @code{@var{prefix}Parser} if

-@code{%define parser_class_name} is not used.  Default is @code{YY}.
+@samp{%define parser_class_name} is not used.  Default is @code{YY}.

 @xref{Java Bison Interface}.
 @end deffn
 
 @xref{Java Bison Interface}.
 @end deffn
 


@@ -9677,7 +9776,7 @@ or
 @display
 My parser includes support for an @samp{#include}-like feature, in
 which case I run @code{yyparse} from @code{yyparse}.  This fails
 @display
 My parser includes support for an @samp{#include}-like feature, in
 which case I run @code{yyparse} from @code{yyparse}.  This fails

-although I did specify @code{%define api.pure}.
+although I did specify @samp{%define api.pure}.

 @end display
 
 These problems typically come not from Bison itself, but from
 @end display
 
 These problems typically come not from Bison itself, but from


@@ -10155,7 +10254,7 @@ token is reset to the token that originally caused the violation.
 @end deffn
 
 @deffn {Directive} %error-verbose
 @end deffn
 
 @deffn {Directive} %error-verbose

-An obsolete directive standing for @samp{%define error-verbose}.
+An obsolete directive standing for @samp{%define parse.error "verbose"}.

 @end deffn
 
 @deffn {Directive} %file-prefix "@var{prefix}"
 @end deffn
 
 @deffn {Directive} %file-prefix "@var{prefix}"


@@ -10239,7 +10338,7 @@ Bison declaration to assign precedence to token(s), but no associativity
 @end deffn
 
 @deffn {Directive} %pure-parser
 @end deffn
 
 @deffn {Directive} %pure-parser

-Deprecated version of @code{%define api.pure} (@pxref{Decl Summary, ,%define}),
+Deprecated version of @samp{%define api.pure} (@pxref{Decl Summary, ,%define}),

 for which Bison is more careful to warn about unreasonable usage.
 @end deffn
 
 for which Bison is more careful to warn about unreasonable usage.
 @end deffn
 


@@ -10361,8 +10460,8 @@ An obsolete macro used in the @file{yacc.c} skeleton, that you define
 with @code{#define} in the prologue to request verbose, specific error
 message strings when @code{yyerror} is called.  It doesn't matter what
 definition you use for @code{YYERROR_VERBOSE}, just whether you define
 with @code{#define} in the prologue to request verbose, specific error
 message strings when @code{yyerror} is called.  It doesn't matter what
 definition you use for @code{YYERROR_VERBOSE}, just whether you define

-it.  Using @code{%define error-verbose} is preferred (@pxref{Error
-Reporting, ,The Error Reporting Function @code{yyerror}}).
+it.  Using @samp{%define parse.error "verbose"} is preferred
+(@pxref{Error Reporting, ,The Error Reporting Function @code{yyerror}}).

 @end deffn
 
 @deffn {Macro} YYINITDEPTH
 @end deffn
 
 @deffn {Macro} YYINITDEPTH


@@ -10710,6 +10809,10 @@ grammatically indivisible.  The piece of text it represents is a token.
 
 @bye
 
 
 @bye
 

+@c Local Variables:
+@c fill-column: 76
+@c End:
+

 @c LocalWords: texinfo setfilename settitle setchapternewpage finalout
 @c LocalWords: ifinfo smallbook shorttitlepage titlepage GPL FIXME iftex
 @c LocalWords: akim fn cp syncodeindex vr tp synindex dircategory direntry
 @c LocalWords: texinfo setfilename settitle setchapternewpage finalout
 @c LocalWords: ifinfo smallbook shorttitlepage titlepage GPL FIXME iftex
 @c LocalWords: akim fn cp syncodeindex vr tp synindex dircategory direntry