X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/de5ab9400a4aaeb9ea63b489118e7dd2b30873f2..f50bfcd6a1750507926dd33bdd37baa8e0eda16d:/doc/bison.texinfo diff --git a/doc/bison.texinfo b/doc/bison.texinfo index 45a6075e..adfd7f4b 100644 --- a/doc/bison.texinfo +++ b/doc/bison.texinfo @@ -3806,8 +3806,11 @@ typedef struct YYLTYPE @} 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 @@ -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 -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 @@ -4585,7 +4588,7 @@ The following Bison declaration says that you want the parser to be a push parser (@pxref{Decl Summary,,%define api.push-pull}): @example -%define api.push-pull "push" +%define api.push-pull push @end example In almost all cases, you want to ensure that your push parser is also @@ -4596,7 +4599,7 @@ what you are doing, your declarations should look like this: @example %define api.pure -%define api.push-pull "push" +%define api.push-pull push @end example There is a major notable functional difference between the pure push parser @@ -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, -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 -@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 @@ -4668,9 +4671,9 @@ yypull_parse (ps); /* Will call the lexer */ 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 @@ -4760,7 +4763,9 @@ use this form instead. @var{qualifier} identifies the purpose of @var{code} and thus the location(s) where Bison should generate it. -Not all values of @var{qualifier} are available for all target languages: +Not all @var{qualifier}s are accepted for all target languages. +Unaccepted @var{qualifier}s produce an error. +Some of the accepted @var{qualifier}s are: @itemize @bullet @item requires @@ -4839,38 +4844,99 @@ parse.trace}. @end deffn @deffn {Directive} %define @var{variable} +@deffnx {Directive} %define @var{variable} @var{value} @deffnx {Directive} %define @var{variable} "@var{value}" Define a variable to adjust Bison's behavior. -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}). -Bison will warn if a @var{variable} is defined by @code{%define} -multiple times, but @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}]}. -Omitting @code{"@var{value}"} is always equivalent to specifying it as +@var{value} must be placed in quotation marks if it contains any +character other than a letter, underscore, period, dash, or non-initial +digit. + +Omitting @code{"@var{value}"} entirely is always equivalent to specifying @code{""}. -Some @var{variable}s may be used as Booleans. +Some @var{variable}s take Boolean values. 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 @code{true} -@item @code{"@var{value}"} is omitted (or is @code{""}). -This is equivalent to @code{"true"}. +@item @code{@var{value}} is omitted (or @code{""} is specified). +This is equivalent to @code{true}. -@item @code{"@var{value}"} is @code{"false"}. +@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. +In this case, Bison selects a default value. @end enumerate +What @var{variable}s are accepted, as well as their meanings and default +values, depend on the selected target language and/or the parser +skeleton (@pxref{Decl Summary,,%language}, @pxref{Decl +Summary,,%skeleton}). +Unaccepted @var{variable}s produce an error. Some of the accepted @var{variable}s are: @table @code +@c ================================================== api.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 @@ -4882,10 +4948,13 @@ Some of the accepted @var{variable}s are: @item Accepted Values: Boolean -@item Default Value: @code{"false"} +@item Default Value: @code{false} @end itemize @c api.pure + + +@c ================================================== api.push-pull @item api.push-pull @findex %define api.push-pull @@ -4897,12 +4966,15 @@ Some of the accepted @var{variable}s are: (The current push parsing interface is experimental and may evolve. More user feedback will help to stabilize it.) -@item Accepted Values: @code{"pull"}, @code{"push"}, @code{"both"} +@item Accepted Values: @code{pull}, @code{push}, @code{both} -@item Default Value: @code{"pull"} +@item Default Value: @code{pull} @end itemize @c api.push-pull + + +@c ================================================== api.tokens.prefix @item api.tokens.prefix @findex %define api.tokens.prefix @@ -4940,22 +5012,7 @@ empty @c api.tokens.prefix -@item error-verbose -@findex %define error-verbose -@itemize -@item Languages(s): -all. -@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}}. -@item Accepted Values: -Boolean -@item Default Value: -@code{false} -@end itemize -@c error-verbose - +@c ================================================== lr.default-reductions @item lr.default-reductions @cindex default reductions @@ -4981,7 +5038,7 @@ More user feedback will help to stabilize it.) @item Accepted Values: @itemize -@item @code{"all"}. +@item @code{all}. For @acronym{LALR} and @acronym{IELR} parsers (@pxref{Decl Summary,,lr.type}) by default, all states are permitted to contain default reductions. @@ -4993,7 +5050,7 @@ That is, unlike in a canonical @acronym{LR} state, the lookahead sets of reductions in an @acronym{LALR} or @acronym{IELR} state can contain tokens that are syntactically incorrect for some left contexts. -@item @code{"consistent"}. +@item @code{consistent}. @cindex consistent states A consistent state is a state that has only one possible action. If that action is a reduction, then the parser does not need to request @@ -5005,7 +5062,7 @@ states, then a canonical @acronym{LR} parser reports a syntax error as soon as it @emph{needs} the syntactically unacceptable token from the scanner. -@item @code{"accepting"}. +@item @code{accepting}. @cindex accepting state By default, the only default reduction permitted in a canonical @acronym{LR} parser is the accept action in the accepting state, which @@ -5017,11 +5074,13 @@ without performing any extra reductions. @item Default Value: @itemize -@item @code{"accepting"} if @code{lr.type} is @code{"canonical LR"}. -@item @code{"all"} otherwise. +@item @code{accepting} if @code{lr.type} is @code{canonical-lr}. +@item @code{all} otherwise. @end itemize @end itemize +@c ============================================ lr.keep-unreachable-states + @item lr.keep-unreachable-states @findex %define lr.keep-unreachable-states @@ -5039,7 +5098,7 @@ are useless in the generated parser. @item Accepted Values: Boolean -@item Default Value: @code{"false"} +@item Default Value: @code{false} @item Caveats: @@ -5066,6 +5125,8 @@ However, Bison does not compute which goto actions are useless. @end itemize @c lr.keep-unreachable-states +@c ================================================== lr.type + @item lr.type @findex %define lr.type @cindex @acronym{LALR} @@ -5082,7 +5143,7 @@ More user feedback will help to stabilize it.) @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. @@ -5111,7 +5172,7 @@ investigate such problems while ignoring the more subtle differences 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 @@ -5125,7 +5186,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. -@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 @@ -5141,62 +5202,18 @@ Even when canonical @acronym{LR} behavior is ultimately desired, facilitate the development of a grammar. @end itemize -@item Default Value: @code{"LALR"} +@item Default Value: @code{lalr} @end itemize + +@c ================================================== 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 ================================================== parse.assert @item parse.assert @findex %define parse.assert @@ -5213,6 +5230,34 @@ destroyed properly. This option checks these constraints. @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 @@ -5316,7 +5361,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. -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 @@ -5343,7 +5388,7 @@ Specify @var{file} for the parser file. @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 @@ -5514,10 +5559,10 @@ If you use a reentrant parser, you can optionally pass additional parameter information to it in a reentrant way. To do so, use the declaration @code{%parse-param}: -@deffn {Directive} %parse-param @{@var{argument-declaration}@} +@deffn {Directive} %parse-param @{@var{argument-declaration}@} @dots{} @findex %parse-param -Declare that an argument declared by the braced-code -@var{argument-declaration} is an additional @code{yyparse} argument. +Declare that one or more +@var{argument-declaration} are additional @code{yyparse} arguments. The @var{argument-declaration} is used when declaring functions or prototypes. The last identifier in @var{argument-declaration} must be the argument name. @@ -5526,8 +5571,7 @@ functions or prototypes. The last identifier in Here's an example. Write this in the parser: @example -%parse-param @{int *nastiness@} -%parse-param @{int *randomness@} +%parse-param @{int *nastiness@} @{int *randomness@} @end example @noindent @@ -5557,8 +5601,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 -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) @@ -5575,7 +5619,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 -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}. @@ -5591,12 +5635,12 @@ 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. -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) -The fuction will return a valid parser instance if there was memory available +The function will return a valid parser instance if there was memory available or 0 if no memory was available. In impure mode, it will also return 0 if a parser instance is currently allocated. @@ -5610,8 +5654,8 @@ allocated. 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) @@ -5799,7 +5843,7 @@ The data type of @code{yylloc} has the name @code{YYLTYPE}. @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 @@ -5823,46 +5867,57 @@ textual locations, then the type @code{YYLTYPE} will not be defined. In this case, omit the second argument; @code{yylex} will be called with only one argument. - -If you wish to pass the additional parameter data to @code{yylex}, use +If you wish to pass additional arguments to @code{yylex}, use @code{%lex-param} just like @code{%parse-param} (@pxref{Parser -Function}). +Function}). To pass additional arguments to both @code{yylex} and +@code{yyparse}, use @code{%param}. -@deffn {Directive} lex-param @{@var{argument-declaration}@} +@deffn {Directive} %lex-param @{@var{argument-declaration}@} @dots{} @findex %lex-param -Declare that the braced-code @var{argument-declaration} is an -additional @code{yylex} argument declaration. +Specify that @var{argument-declaration} are additional @code{yylex} argument +declarations. You may pass one or more such declarations, which is +equivalent to repeating @code{%lex-param}. +@end deffn + +@deffn {Directive} %param @{@var{argument-declaration}@} @dots{} +@findex %param +Specify that @var{argument-declaration} are additional +@code{yylex}/@code{yyparse} argument declaration. This is equivalent to +@samp{%lex-param @{@var{argument-declaration}@} @dots{} %parse-param +@{@var{argument-declaration}@} @dots{}}. You may pass one or more +declarations, which is equivalent to repeating @code{%param}. @end deffn For instance: @example -%parse-param @{int *nastiness@} -%lex-param @{int *nastiness@} -%parse-param @{int *randomness@} +%lex-param @{scanner_mode *mode@} +%parse-param @{parser_mode *mode@} +%param @{environment_type *env@} @end example @noindent results in the following signature: @example -int yylex (int *nastiness); -int yyparse (int *nastiness, int *randomness); +int yylex (scanner_mode *mode, environment_type *env); +int yyparse (parser_mode *mode, environment_type *env); @end example -If @code{%define api.pure} is added: +If @samp{%define api.pure} is added: @example -int yylex (YYSTYPE *lvalp, int *nastiness); -int yyparse (int *nastiness, int *randomness); +int yylex (YYSTYPE *lvalp, scanner_mode *mode, environment_type *env); +int yyparse (parser_mode *mode, environment_type *env); @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); -int yyparse (int *nastiness, int *randomness); +int yylex (YYSTYPE *lvalp, YYLTYPE *llocp, + scanner_mode *mode, environment_type *env); +int yyparse (parser_mode *mode, environment_type *env); @end example @node Error Reporting @@ -5872,7 +5927,7 @@ int yyparse (int *nastiness, int *randomness); @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 @@ -5884,8 +5939,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"}}. -@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"}}. @@ -5942,7 +5997,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 -@code{%define api.pure} are pure. +@samp{%define api.pure} are pure. I.e.: @example @@ -6556,7 +6611,7 @@ conflict, precedence suffices. In such a case, using @code{%left}, related) conflicts that would remain hidden. The dangling @code{else} ambiguity (@pxref{Shift/Reduce, , Shift/Reduce -Conflicts}) can be solved explictly. This shift/reduce conflicts occurs +Conflicts}) can be solved explicitly. This shift/reduce conflicts occurs in the following situation, where the period denotes the current parsing state: @@ -6579,7 +6634,7 @@ in an associativity related conflict, which can be specified as follows. The unary-minus is another typical example where associativity is usually over-specified, see @ref{Infix Calc, , Infix Notation -Calculator: @code{calc}}. The @code{%left} directive is traditionaly +Calculator: @code{calc}}. The @code{%left} directive is traditionally used to declare the precedence of @code{NEG}, which is more than needed since it also defines its associativity. While this is harmless in the traditional example, who knows how @code{NEG} might be used in future @@ -7112,7 +7167,7 @@ that allows variable-length arrays. The default is 200. Do not allow @code{YYINITDEPTH} to be greater than @code{YYMAXDEPTH}. @c FIXME: C++ output. -Because of semantical differences between C and C++, the deterministic +Because of semantic differences between C and C++, the deterministic parsers in C produced by Bison cannot grow when compiled by C++ compilers. In this precise case (compiling a C parser as C++) you are suggested to grow @code{YYINITDEPTH}. The Bison maintainers hope to fix @@ -8141,7 +8196,7 @@ already defined, so that the debugging facilities are compiled. @item -D @var{name}[=@var{value}] @itemx --define=@var{name}[=@var{value}] -@item -F @var{name}[=@var{value}] +@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 @@ -8149,16 +8204,19 @@ definitions for the same @var{name} as follows: @itemize @item -Bison processes all command-line definitions in order and then processes -all @code{%define} definitions in order. +Bison quietly ignores all command-line definitions for @var{name} except +the last. @item -Later definitions override earlier definitions except that Bison quietly -ignores all @code{%define} definitions if the last command-line -definition is specified by @code{-F} or @code{--force-define}. +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 -Bison never warns when a command-line definition overrides another -definition, but Bison always warns when a @code{%define} definition -overrides a command-line or @code{%define} definition. +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 @@ -8357,8 +8415,9 @@ The C++ deterministic parser is selected using the skeleton directive, 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: @@ -8542,7 +8601,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 -@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 @@ -8778,15 +8837,14 @@ global variables. @comment file: calc++-parser.yy @example // The parsing context. -%parse-param @{ calcxx_driver& driver @} -%lex-param @{ calcxx_driver& driver @} +%param @{ calcxx_driver& driver @} @end example @noindent -Then we request the location tracking feature, and initialize the -first location's file name. Afterwards new locations are computed +Then we request location tracking, and initialize the +first location's file name. Afterward new locations are computed relatively to the previous locations: the file name will be -automatically propagated. +propagated. @comment file: calc++-parser.yy @example @@ -8799,13 +8857,13 @@ automatically propagated. @end example @noindent -Use the two following directives to enable parser tracing and verbose +Use the following two directives to enable parser tracing and verbose error messages. @comment file: calc++-parser.yy @example %define parse.trace -%define error-verbose +%define parse.error verbose @end example @noindent @@ -9106,7 +9164,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} -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 @@ -9131,7 +9189,7 @@ if needed. Also, in the future the access the token names and codes. Getting a ``code too large'' error from the Java compiler means the code -hit the 64KB bytecode per method limination of the Java class file. +hit the 64KB bytecode per method limitation of the Java class file. Try reducing the amount of code in actions and static initializers; otherwise, report a bug so that the parser skeleton will be improved. @@ -9154,7 +9212,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 -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 @@ -9194,11 +9252,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 -@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 -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. @@ -9233,22 +9291,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 -@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 -@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. -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 -@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 -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 @@ -9264,25 +9322,26 @@ which initialize them automatically. @deftypeop {Constructor} {YYParser} {} YYParser (@var{lex_param}, @dots{}, @var{parse_param}, @dots{}) Build a new parser object with embedded @code{%code lexer}. There are -no parameters, unless @code{%parse-param}s and/or @code{%lex-param}s are -used. +no parameters, unless @code{%param}s and/or @code{%parse-param}s and/or +@code{%lex-param}s are used. 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 uncaught exceptions. @end deftypeop @deftypeop {Constructor} {YYParser} {} YYParser (Lexer @var{lexer}, @var{parse_param}, @dots{}) Build a new parser object using the specified scanner. There are no -additional parameters unless @code{%parse-param}s are used. +additional parameters unless @code{%param}s and/or @code{%parse-param}s are +used. If the scanner is defined by @code{%code lexer}, this constructor is declared @code{protected} and is called automatically with a scanner -created with the correct @code{%lex-param}s. +created with the correct @code{%param}s and/or @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 -@code{%define init_throws} to specify any uncatch exceptions. +@samp{%define init_throws} to specify any uncatch exceptions. @end deftypeop @deftypemethod {YYParser} {boolean} parse () @@ -9293,7 +9352,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 -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 @@ -9359,15 +9418,15 @@ 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 -changed using @code{%define location_type "@var{class-name}".} +changed using @samp{%define location_type "@var{class-name}".} @end deftypemethod @deftypemethod {Lexer} {int} yylex () 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 +value and location are saved and returned by the their 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 @@ -9377,14 +9436,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. -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. +Return the semantic 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 @@ -9395,7 +9454,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. -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} @@ -9412,7 +9471,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 -@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}. @@ -9499,7 +9558,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 -@code{%define stype}. Angle backets on @code{%token}, @code{type}, +@samp{%define stype}. Angle brackets 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. @@ -9508,12 +9567,12 @@ left-hand side of assignments. See @pxref{Java Semantic Values} and @pxref{Java Action Features}. @item -The prolog declarations have a different meaning than in C/C++ code. +The prologue declarations have a different meaning than in C/C++ code. @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. +suggested to use @samp{%define package} instead. @item unqualified @code{%code} blocks are placed inside the parser class. @@ -9554,7 +9613,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 -@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 @@ -9744,7 +9803,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 -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 @@ -10180,6 +10239,7 @@ Precedence}. @deffn {Directive} %define @var{define-variable} @deffnx {Directive} %define @var{define-variable} @var{value} +@deffnx {Directive} %define @var{define-variable} "@var{value}" Define a variable to adjust Bison's behavior. @xref{Decl Summary,,%define}. @end deffn @@ -10222,7 +10282,7 @@ token is reset to the token that originally caused the violation. @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}" @@ -10249,8 +10309,8 @@ Bison declaration to assign precedence and left associativity to token(s). @xref{Precedence Decl, ,Operator Precedence}. @end deffn -@deffn {Directive} %lex-param @{@var{argument-declaration}@} -Bison declaration to specifying an additional parameter that +@deffn {Directive} %lex-param @{@var{argument-declaration}@} @dots{} +Bison declaration to specifying additional arguments that @code{yylex} should accept. @xref{Pure Calling,, Calling Conventions for Pure Parsers}. @end deffn @@ -10289,10 +10349,15 @@ Bison declaration to set the name of the parser file. @xref{Decl Summary}. @end deffn -@deffn {Directive} %parse-param @{@var{argument-declaration}@} -Bison declaration to specifying an additional parameter that -@code{yyparse} should accept. @xref{Parser Function,, The Parser -Function @code{yyparse}}. +@deffn {Directive} %param @{@var{argument-declaration}@} @dots{} +Bison declaration to specify additional arguments that both +@code{yylex} and @code{yyparse} should accept. @xref{Parser Function,, The +Parser Function @code{yyparse}}. +@end deffn + +@deffn {Directive} %parse-param @{@var{argument-declaration}@} @dots{} +Bison declaration to specify additional arguments that @code{yyparse} +should accept. @xref{Parser Function,, The Parser Function @code{yyparse}}. @end deffn @deffn {Directive} %prec @@ -10306,7 +10371,7 @@ Bison declaration to assign precedence to token(s), but no associativity @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 @@ -10428,8 +10493,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 -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 @@ -10777,32 +10842,59 @@ grammatically indivisible. The piece of text it represents is a token. @bye -@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: ifset vskip pt filll insertcopying sp ISBN Etienne Suvasa -@c LocalWords: ifnottex yyparse detailmenu GLR RPN Calc var Decls Rpcalc -@c LocalWords: rpcalc Lexer Expr ltcalc mfcalc yylex -@c LocalWords: yyerror pxref LR yylval cindex dfn LALR samp gpl BNF xref -@c LocalWords: const int paren ifnotinfo AC noindent emph expr stmt findex -@c LocalWords: glr YYSTYPE TYPENAME prog dprec printf decl init stmtMerge -@c LocalWords: pre STDC GNUC endif yy YY alloca lf stddef stdlib YYDEBUG -@c LocalWords: NUM exp subsubsection kbd Ctrl ctype EOF getchar isdigit -@c LocalWords: ungetc stdin scanf sc calc ulator ls lm cc NEG prec yyerrok -@c LocalWords: longjmp fprintf stderr yylloc YYLTYPE cos ln -@c LocalWords: smallexample symrec val tptr FNCT fnctptr func struct sym -@c LocalWords: fnct putsym getsym fname arith fncts atan ptr malloc sizeof -@c LocalWords: strlen strcpy fctn strcmp isalpha symbuf realloc isalnum -@c LocalWords: ptypes itype YYPRINT trigraphs yytname expseq vindex dtype -@c LocalWords: Rhs YYRHSLOC LE nonassoc op deffn typeless yynerrs -@c LocalWords: yychar yydebug msg YYNTOKENS YYNNTS YYNRULES YYNSTATES -@c LocalWords: cparse clex deftypefun NE defmac YYACCEPT YYABORT param -@c LocalWords: strncmp intval tindex lvalp locp llocp typealt YYBACKUP -@c LocalWords: YYEMPTY YYEOF YYRECOVERING yyclearin GE def UMINUS maybeword -@c LocalWords: Johnstone Shamsa Sadaf Hussain Tomita TR uref YYMAXDEPTH -@c LocalWords: YYINITDEPTH stmnts ref stmnt initdcl maybeasm notype -@c LocalWords: hexflag STR exdent itemset asis DYYDEBUG YYFPRINTF args -@c LocalWords: infile ypp yxx outfile itemx tex leaderfill -@c LocalWords: hbox hss hfill tt ly yyin fopen fclose ofirst gcc ll -@c LocalWords: nbar yytext fst snd osplit ntwo strdup AST -@c LocalWords: YYSTACK DVI fdl printindex IELR +@c Local Variables: +@c fill-column: 76 +@c End: + +@c LocalWords: texinfo setfilename settitle setchapternewpage finalout texi FSF +@c LocalWords: ifinfo smallbook shorttitlepage titlepage GPL FIXME iftex FSF's +@c LocalWords: akim fn cp syncodeindex vr tp synindex dircategory direntry Naur +@c LocalWords: ifset vskip pt filll insertcopying sp ISBN Etienne Suvasa Multi +@c LocalWords: ifnottex yyparse detailmenu GLR RPN Calc var Decls Rpcalc multi +@c LocalWords: rpcalc Lexer Expr ltcalc mfcalc yylex defaultprec Donnelly Gotos +@c LocalWords: yyerror pxref LR yylval cindex dfn LALR samp gpl BNF xref yypush +@c LocalWords: const int paren ifnotinfo AC noindent emph expr stmt findex lr +@c LocalWords: glr YYSTYPE TYPENAME prog dprec printf decl init stmtMerge POSIX +@c LocalWords: pre STDC GNUC endif yy YY alloca lf stddef stdlib YYDEBUG yypull +@c LocalWords: NUM exp subsubsection kbd Ctrl ctype EOF getchar isdigit nonfree +@c LocalWords: ungetc stdin scanf sc calc ulator ls lm cc NEG prec yyerrok rr +@c LocalWords: longjmp fprintf stderr yylloc YYLTYPE cos ln Stallman Destructor +@c LocalWords: smallexample symrec val tptr FNCT fnctptr func struct sym enum +@c LocalWords: fnct putsym getsym fname arith fncts atan ptr malloc sizeof Lex +@c LocalWords: strlen strcpy fctn strcmp isalpha symbuf realloc isalnum DOTDOT +@c LocalWords: ptypes itype YYPRINT trigraphs yytname expseq vindex dtype Unary +@c LocalWords: Rhs YYRHSLOC LE nonassoc op deffn typeless yynerrs nonterminal +@c LocalWords: yychar yydebug msg YYNTOKENS YYNNTS YYNRULES YYNSTATES reentrant +@c LocalWords: cparse clex deftypefun NE defmac YYACCEPT YYABORT param yypstate +@c LocalWords: strncmp intval tindex lvalp locp llocp typealt YYBACKUP subrange +@c LocalWords: YYEMPTY YYEOF YYRECOVERING yyclearin GE def UMINUS maybeword loc +@c LocalWords: Johnstone Shamsa Sadaf Hussain Tomita TR uref YYMAXDEPTH inline +@c LocalWords: YYINITDEPTH stmnts ref stmnt initdcl maybeasm notype Lookahead +@c LocalWords: hexflag STR exdent itemset asis DYYDEBUG YYFPRINTF args Autoconf +@c LocalWords: infile ypp yxx outfile itemx tex leaderfill Troubleshouting sqrt +@c LocalWords: hbox hss hfill tt ly yyin fopen fclose ofirst gcc ll lookahead +@c LocalWords: nbar yytext fst snd osplit ntwo strdup AST Troublereporting th +@c LocalWords: YYSTACK DVI fdl printindex IELR nondeterministic nonterminals ps +@c LocalWords: subexpressions declarator nondeferred config libintl postfix +@c LocalWords: preprocessor nonpositive unary nonnumeric typedef extern rhs +@c LocalWords: yytokentype filename destructor multicharacter nonnull EBCDIC +@c LocalWords: lvalue nonnegative XNUM CHR chr TAGLESS tagless stdout api TOK +@c LocalWords: destructors Reentrancy nonreentrant subgrammar nonassociative +@c LocalWords: deffnx namespace xml goto lalr ielr runtime lex yacc yyps env +@c LocalWords: yystate variadic Unshift NLS gettext po UTF Automake LOCALEDIR +@c LocalWords: YYENABLE bindtextdomain Makefile DEFS CPPFLAGS DBISON DeRemer +@c LocalWords: autoreconf Pennello multisets nondeterminism Generalised baz +@c LocalWords: redeclare automata Dparse localedir datadir XSLT midrule Wno +@c LocalWords: makefiles Graphviz multitable headitem hh basename Doxygen fno +@c LocalWords: doxygen ival sval deftypemethod deallocate pos deftypemethodx +@c LocalWords: Ctor defcv defcvx arg accessors arithmetics CPP ifndef CALCXX +@c LocalWords: lexer's calcxx bool LPAREN RPAREN deallocation cerrno climits +@c LocalWords: cstdlib Debian undef yywrap unput noyywrap nounput zA yyleng +@c LocalWords: errno strtol ERANGE str strerror iostream argc argv Javadoc +@c LocalWords: bytecode initializers superclass stype ASTNode autoboxing nls +@c LocalWords: toString deftypeivar deftypeivarx deftypeop YYParser strictfp +@c LocalWords: superclasses boolean getErrorVerbose setErrorVerbose deftypecv +@c LocalWords: getDebugStream setDebugStream getDebugLevel setDebugLevel url +@c LocalWords: bisonVersion deftypecvx bisonSkeleton getStartPos getEndPos +@c LocalWords: getLVal defvar YYFAIL deftypefn deftypefnx gotos msgfmt +@c LocalWords: subdirectory Solaris nonassociativity