X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/4c6622c2dd5e9383c89565ff3d9eadeeafc064f4..a6ca4ce2292277b4af21b5069bded9c73341d23a:/doc/bison.texinfo diff --git a/doc/bison.texinfo b/doc/bison.texinfo index 744641a0..8f40afbe 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,37 +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 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 +@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 @@ -4881,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 @@ -4896,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 @@ -4939,22 +5012,29 @@ empty @c api.tokens.prefix -@item error-verbose -@findex %define error-verbose -@itemize -@item Languages(s): -all. +@c ================================================== lex_symbol +@item variant +@findex %define lex_symbol + +@itemize @bullet +@item Language(s): +C++ + @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}}. +When variant-based semantic values are enabled (@pxref{C++ Variants}), +request that symbols be handled as a whole (type, value, and possibly +location) in the scanner. @xref{Complete Symbols}, for details. + @item Accepted Values: -Boolean +Boolean. + @item Default Value: @code{false} @end itemize -@c error-verbose +@c lex_symbol + +@c ================================================== lr.default-reductions @item lr.default-reductions @cindex default reductions @@ -4980,7 +5060,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. @@ -4992,7 +5072,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 @@ -5004,7 +5084,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 @@ -5016,11 +5096,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 @@ -5038,7 +5120,7 @@ are useless in the generated parser. @item Accepted Values: Boolean -@item Default Value: @code{"false"} +@item Default Value: @code{false} @item Caveats: @@ -5065,6 +5147,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} @@ -5081,7 +5165,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. @@ -5110,7 +5194,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 @@ -5124,7 +5208,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 @@ -5140,62 +5224,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 @@ -5203,7 +5243,8 @@ The parser namespace is @code{foo} and @code{yylex} is referenced as @item Languages(s): C++ @item Purpose: Issue runtime assertions to catch invalid uses. -In C++, when variants are used, symbols must be constructed and +In C++, when variants are used (@pxref{C++ Variants}), symbols must be +constructed and destroyed properly. This option checks these constraints. @item Accepted Values: Boolean @@ -5212,6 +5253,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 @@ -5229,6 +5298,27 @@ is not already defined, so that the debugging facilities are compiled. @end itemize @c parse.trace +@c ================================================== variant +@item variant +@findex %define variant + +@itemize @bullet +@item Language(s): +C++ + +@item Purpose: +Requests variant-based semantic values. +@xref{C++ Variants}. + +@item Accepted Values: +Boolean. + +@item Default Value: +@code{false} +@end itemize +@c variant + + @end table @end deffn @c ---------------------------------------------------------- %define @@ -5315,7 +5405,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 @@ -5342,7 +5432,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 @@ -5513,10 +5603,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. @@ -5525,8 +5615,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 @@ -5556,8 +5645,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) @@ -5574,7 +5663,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}. @@ -5590,12 +5679,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. @@ -5609,8 +5698,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) @@ -5798,7 +5887,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 @@ -5822,46 +5911,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 @@ -5871,7 +5971,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 @@ -5883,8 +5983,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"}}. @@ -5941,7 +6041,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 @@ -6555,7 +6655,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: @@ -6578,7 +6678,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 @@ -7111,7 +7211,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 @@ -8140,8 +8240,32 @@ already defined, so that the debugging facilities are compiled. @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} @@ -8267,9 +8391,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 -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 @@ -8335,8 +8459,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: @@ -8344,7 +8469,7 @@ The various classes are generated in the following files: @item position.hh @itemx location.hh The definition of the classes @code{position} and @code{location}, -used for location tracking. @xref{C++ Location Values}. +used for location tracking when enabled. @xref{C++ Location Values}. @item stack.hh An auxiliary class @code{stack} used by the parser. @@ -8370,11 +8495,22 @@ for a complete and accurate documentation. @c - YYSTYPE @c - Printer and destructor +Bison supports two different means to handle semantic values in C++. One is +alike the C interface, and relies on unions (@pxref{C++ Unions}). As C++ +practitioners know, unions are inconvenient in C++, therefore another +approach is provided, based on variants (@pxref{C++ Variants}). + +@menu +* C++ Unions:: Semantic values cannot be objects +* C++ Variants:: Using objects as semantic values +@end menu + +@node C++ Unions +@subsubsection C++ Unions + The @code{%union} directive works as for C, see @ref{Union Decl, ,The Collection of Value Types}. In particular it produces a genuine -@code{union}@footnote{In the future techniques to allow complex types -within pseudo-unions (similar to Boost variants) might be implemented to -alleviate these issues.}, which have a few specific features in C++. +@code{union}, which have a few specific features in C++. @itemize @minus @item The type @code{YYSTYPE} is defined but its use is discouraged: rather @@ -8391,6 +8527,98 @@ reclaimed automatically: using the @code{%destructor} directive is the only means to avoid leaks. @xref{Destructor Decl, , Freeing Discarded Symbols}. +@node C++ Variants +@subsubsection C++ Variants + +Starting with version 2.6, Bison provides a @emph{variant} based +implementation of semantic values for C++. This alleviates all the +limitations reported in the previous section, and in particular, object +types can be used without pointers. + +To enable variant-based semantic values, set @code{%define} variable +@code{variant} (@pxref{Decl Summary, , variant}). Once this defined, +@code{%union} is ignored, and instead of using the name of the fields of the +@code{%union} to ``type'' the symbols, use genuine types. + +For instance, instead of + +@example +%union +@{ + int ival; + std::string* sval; +@} +%token NUMBER; +%token STRING; +@end example + +@noindent +write + +@example +%token NUMBER; +%token STRING; +@end example + +@code{STRING} is no longer a pointer, which should fairly simplify the user +actions in the grammar and in the scanner (in particular the memory +management). + +Since C++ features destructors, and since it is customary to specialize +@code{operator<<} to support uniform printing of values, variants also +typically simplify Bison printers and destructors. + +Variants are stricter than unions. When based on unions, you may play any +dirty game with @code{yylval}, say storing an @code{int}, reading a +@code{char*}, and then storing a @code{double} in it. This is no longer +possible with variants: they must be initialized, then assigned to, and +eventually, destroyed. + +@deftypemethod {semantic_type} {T&} build () +Initialize, but leave empty. Returns the address where the actual value may +be stored. Requires that the variant was not initialized yet. +@end deftypemethod + +@deftypemethod {semantic_type} {T&} build (const T& @var{t}) +Initialize, and copy-construct from @var{t}. +@end deftypemethod + + +@strong{Warning}: We do not use Boost.Variant, for two reasons. First, it +appeared unacceptable to require Boost on the user's machine (i.e., the +machine on which the generated parser will be compiled, not the machine on +which @command{bison} was run). Second, for each possible semantic value, +Boost.Variant not only stores the value, but also a tag specifying its +type. But the parser already ``knows'' the type of the semantic value, so +that would be duplicating the information. + +Therefore we developed light-weight variants whose type tag is external (so +they are really like @code{unions} for C++ actually). But our code is much +less mature that Boost.Variant. So there is a number of limitations in +(the current implementation of) variants: +@itemize +@item +Alignment must be enforced: values should be aligned in memory according to +the most demanding type. Computing the smallest alignment possible requires +meta-programming techniques that are not currently implemented in Bison, and +therefore, since, as far as we know, @code{double} is the most demanding +type on all platforms, alignments are enforced for @code{double} whatever +types are actually used. This may waste space in some cases. + +@item +Our implementation is not conforming with strict aliasing rules. Alias +analysis is a technique used in optimizing compilers to detect when two +pointers are disjoint (they cannot ``meet''). Our implementation breaks +some of the rules that G++ 4.4 uses in its alias analysis, so @emph{strict +alias analysis must be disabled}. Use the option +@option{-fno-strict-aliasing} to compile the generated parser. + +@item +There might be portability issues we are not aware of. +@end itemize + +As far as we know, these limitations @emph{can} be alleviated. All it takes +is some time and/or some talented C++ hacker willing to contribute to Bison. @node C++ Location Values @subsection C++ Location Values @@ -8479,9 +8707,19 @@ this class is detailed below. It can be extended using the it describes an additional member of the parser class, and an additional argument for its constructor. -@defcv {Type} {parser} {semantic_value_type} -@defcvx {Type} {parser} {location_value_type} -The types for semantics value and locations. +@defcv {Type} {parser} {semantic_type} +@defcvx {Type} {parser} {location_type} +The types for semantic values and locations (if enabled). +@end defcv + +@defcv {Type} {parser} {syntax_error} +This class derives from @code{std::runtime_error}. Throw instances of it +from user actions to raise parse errors. This is equivalent with first +invoking @code{error} to report the location and message of the syntax +error, and then to invoke @code{YYERROR} to enter the error-recovery mode. +But contrary to @code{YYERROR} which can only be invoked from user actions +(i.e., written in the action itself), the exception can be thrown from +function invoked from the user action. @end defcv @deftypemethod {parser} {} parser (@var{type1} @var{arg1}, ...) @@ -8489,6 +8727,11 @@ Build a new parser object. There are no arguments by default, unless @samp{%parse-param @{@var{type1} @var{arg1}@}} was used. @end deftypemethod +@deftypemethod {syntax_error} {} syntax_error (const location_type& @var{l}, const std::string& @var{m}) +@deftypemethodx {syntax_error} {} syntax_error (const std::string& @var{m}) +Instantiate a syntax-error exception. +@end deftypemethod + @deftypemethod {parser} {int} parse () Run the syntactic analysis, and return 0 on success, 1 otherwise. @end deftypemethod @@ -8506,9 +8749,11 @@ or nonzero, full tracing. @end deftypemethod @deftypemethod {parser} {void} error (const location_type& @var{l}, const std::string& @var{m}) +@deftypemethodx {parser} {void} error (const std::string& @var{m}) The definition for this member function must be supplied by the user: the parser uses it to report a parser error occurring at @var{l}, -described by @var{m}. +described by @var{m}. If location tracking is not enabled, the second +signature is used. @end deftypemethod @@ -8520,25 +8765,143 @@ 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. The actual interface with @code{yylex} +depends whether you use unions, or variants. -@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 -value and location being @var{yylval} and @var{yylloc}. Invocations of +@menu +* Split Symbols:: Passing symbols as two/three components +* Complete Symbols:: Making symbols a whole +@end menu + +@node Split Symbols +@subsubsection Split Symbols + +Therefore the interface is as follows. + +@deftypemethod {parser} {int} yylex (semantic_type& @var{yylval}, location_type& @var{yylloc}, @var{type1} @var{arg1}, ...) +@deftypemethodx {parser} {int} yylex (semantic_type& @var{yylval}, @var{type1} @var{arg1}, ...) +Return the next token. Its type is the return value, its semantic value and +location (if enabled) being @var{yylval} and @var{yylloc}. Invocations of @samp{%lex-param @{@var{type1} @var{arg1}@}} yield additional arguments. @end deftypemethod +Note that when using variants, the interface for @code{yylex} is the same, +but @code{yylval} is handled differently. + +Regular union-based code in Lex scanner typically look like: + +@example +[0-9]+ @{ + yylval.ival = text_to_int (yytext); + return yy::parser::INTEGER; + @} +[a-z]+ @{ + yylval.sval = new std::string (yytext); + return yy::parser::IDENTIFIER; + @} +@end example + +Using variants, @code{yylval} is already constructed, but it is not +initialized. So the code would look like: + +@example +[0-9]+ @{ + yylval.build() = text_to_int (yytext); + return yy::parser::INTEGER; + @} +[a-z]+ @{ + yylval.build = yytext; + return yy::parser::IDENTIFIER; + @} +@end example + +@noindent +or + +@example +[0-9]+ @{ + yylval.build(text_to_int (yytext)); + return yy::parser::INTEGER; + @} +[a-z]+ @{ + yylval.build(yytext); + return yy::parser::IDENTIFIER; + @} +@end example + + +@node Complete Symbols +@subsubsection Complete Symbols + +If you specified both @code{%define variant} and @code{%define lex_symbol}, +the @code{parser} class also defines the class @code{parser::symbol_type} +which defines a @emph{complete} symbol, aggregating its type (i.e., the +traditional value returned by @code{yylex}), its semantic value (i.e., the +value passed in @code{yylval}, and possibly its location (@code{yylloc}). + +@deftypemethod {symbol_type} {} symbol_type (token_type @var{type}, const semantic_type& @var{value}, const location_type& @var{location}) +Build a complete terminal symbol which token type is @var{type}, and which +semantic value is @var{value}. If location tracking is enabled, also pass +the @var{location}. +@end deftypemethod + +This interface is low-level and should not be used for two reasons. First, +it is inconvenient, as you still have to build the semantic value, which is +a variant, and second, because consistency is not enforced: as with unions, +it is still possible to give an integer as semantic value for a string. + +So for each token type, Bison generates named constructors as follows. + +@deftypemethod {symbol_type} {} make_@var{token} (const @var{value_type}& @var{value}, const location_type& @var{location}) +@deftypemethodx {symbol_type} {} make_@var{token} (const location_type& @var{location}) +Build a complete terminal symbol for the token type @var{token} (not +including the @code{api.tokens.prefix}) whose possible semantic value is +@var{value} of adequate @var{value_type}. If location tracking is enabled, +also pass the @var{location}. +@end deftypemethod + +For instance, given the following declarations: + +@example +%define api.tokens.prefix "TOK_" +%token IDENTIFIER; +%token INTEGER; +%token COLON; +@end example + +@noindent +Bison generates the following functions: + +@example +symbol_type make_IDENTIFIER(const std::string& v, + const location_type& l); +symbol_type make_INTEGER(const int& v, + const location_type& loc); +symbol_type make_COLON(const location_type& loc); +@end example + +@noindent +which should be used in a Lex-scanner as follows. + +@example +[0-9]+ return yy::parser::make_INTEGER(text_to_int (yytext), loc); +[a-z]+ return yy::parser::make_IDENTIFIER(yytext, loc); +":" return yy::parser::make_COLON(loc); +@end example + +Tokens that do not have an identifier are not accessible: you cannot simply +use characters such as @code{':'}, they must be declared with @code{%token}. @node A Complete C++ Example @subsection A Complete C++ Example This section demonstrates the use of a C++ parser with a simple but complete example. This example should be available on your system, -ready to compile, in the directory @dfn{../bison/examples/calc++}. It +ready to compile, in the directory @dfn{.../bison/examples/calc++}. It focuses on the use of Bison, therefore the design of the various C++ classes is very naive: no accessors, no encapsulation of members etc. We will use a Lex scanner, and more precisely, a Flex scanner, to -demonstrate the various interaction. A hand written scanner is +demonstrate the various interactions. A hand-written scanner is actually easier to interface with. @menu @@ -8602,11 +8965,8 @@ factor both as follows. @comment file: calc++-driver.hh @example // Tell Flex the lexer's prototype ... -# define YY_DECL \ - yy::calcxx_parser::token_type \ - yylex (yy::calcxx_parser::semantic_type* yylval, \ - yy::calcxx_parser::location_type* yylloc, \ - calcxx_driver& driver) +# define YY_DECL \ + yy::calcxx_parser::symbol_type yylex (calcxx_driver& driver) // ... and declare it for the parser's sake. YY_DECL; @end example @@ -8630,8 +8990,8 @@ public: @end example @noindent -To encapsulate the coordination with the Flex scanner, it is useful to -have two members function to open and close the scanning phase. +To encapsulate the coordination with the Flex scanner, it is useful to have +member functions to open and close the scanning phase. @comment file: calc++-driver.hh @example @@ -8646,9 +9006,13 @@ Similarly for the parser itself. @comment file: calc++-driver.hh @example - // Run the parser. Return 0 on success. + // Run the parser on file F. + // Return 0 on success. int parse (const std::string& f); + // The name of the file being parsed. + // Used later to pass the file name to the location tracker. std::string file; + // Whether parser traces should be generated. bool trace_parsing; @end example @@ -8730,19 +9094,35 @@ the version you designed the grammar for. %define parser_class_name "calcxx_parser" @end example +@noindent +@findex %define variant +@findex %define lex_symbol +This example will use genuine C++ objects as semantic values, therefore, we +require the variant-based interface. To make sure we properly use it, we +enable assertions. To fully benefit from type-safety and more natural +definition of ``symbol'', we enable @code{lex_symbol}. + +@comment file: calc++-parser.yy +@example +%define variant +%define parse.assert +%define lex_symbol +@end example + @noindent @findex %code requires -Then come the declarations/inclusions needed to define the -@code{%union}. Because the parser uses the parsing driver and -reciprocally, both cannot include the header of the other. Because the +Then come the declarations/inclusions needed by the semantic values. +Because the parser uses the parsing driver and reciprocally, both would like +to include the header of the other, which is, of course, insane. This +mutual dependency will be broken using forward declarations. Because the driver's header needs detailed knowledge about the parser class (in -particular its inner types), it is the parser's header which will simply -use a forward declaration of the driver. -@xref{Decl Summary, ,%code}. +particular its inner types), it is the parser's header which will use a +forward declaration of the driver. @xref{Decl Summary, ,%code}. @comment file: calc++-parser.yy @example -%code requires @{ +%code requires +@{ # include class calcxx_driver; @} @@ -8756,15 +9136,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 @@ -8777,27 +9156,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 -@end example - -@noindent -Semantic values cannot use ``real'' objects, but only pointers to -them. - -@comment file: calc++-parser.yy -@example -// Symbols. -%union -@{ - int ival; - std::string *sval; -@}; +%define parse.error verbose @end example @noindent @@ -8807,7 +9172,8 @@ The code between @samp{%code @{} and @samp{@}} is output in the @comment file: calc++-parser.yy @example -%code @{ +%code +@{ # include "calc++-driver.hh" @} @end example @@ -8823,28 +9189,45 @@ prefix tokens with @code{TOK_} (@pxref{Decl Summary,, api.tokens.prefix}). @comment file: calc++-parser.yy @example %define api.tokens.prefix "TOK_" -%token END 0 "end of file" -%token ASSIGN ":=" -%token IDENTIFIER "identifier" -%token NUMBER "number" -%type exp +%token + END 0 "end of file" + ASSIGN ":=" + MINUS "-" + PLUS "+" + STAR "*" + SLASH "/" + LPAREN "(" + RPAREN ")" +; @end example @noindent -To enable memory deallocation during error recovery, use -@code{%destructor}. +Since we use variant-based semantic values, @code{%union} is not used, and +both @code{%type} and @code{%token} expect genuine types, as opposed to type +tags. -@c FIXME: Document %printer, and mention that it takes a braced-code operand. @comment file: calc++-parser.yy @example -%printer @{ debug_stream () << *$$; @} "identifier" -%destructor @{ delete $$; @} "identifier" +%token IDENTIFIER "identifier" +%token NUMBER "number" +%type exp +@end example -%printer @{ debug_stream () << $$; @} +@noindent +No @code{%destructor} is needed to enable memory deallocation during error +recovery; the memory, for strings for instance, will be reclaimed by the +regular destructors. All the values are printed using their +@code{operator<<}. + +@c FIXME: Document %printer, and mention that it takes a braced-code operand. +@comment file: calc++-parser.yy +@example +%printer @{ debug_stream () << $$; @} <*>; @end example @noindent -The grammar itself is straightforward. +The grammar itself is straightforward (@pxref{Location Tracking Calc, , +Location Tracking Calculator: @code{ltcalc}}). @comment file: calc++-parser.yy @example @@ -8857,19 +9240,18 @@ assignments: | /* Nothing. */ @{@}; assignment: - "identifier" ":=" exp - @{ driver.variables[*$1] = $3; delete $1; @}; + "identifier" ":=" exp @{ driver.variables[$1] = $3; @}; -%left '+' '-'; -%left '*' '/'; +%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 @{ $$ = $1 + $3; @} +| exp "-" exp @{ $$ = $1 - $3; @} +| exp "*" exp @{ $$ = $1 * $3; @} +| exp "/" exp @{ $$ = $1 / $3; @} +| "(" exp ")" @{ std::swap($$, $2); @} +| "identifier" @{ $$ = driver.variables[$1]; @} +| "number" @{ std::swap($$, $1); @}; %% @end example @@ -8880,7 +9262,7 @@ driver. @comment file: calc++-parser.yy @example void -yy::calcxx_parser::error (const yy::calcxx_parser::location_type& l, +yy::calcxx_parser::error (const location_type& l, const std::string& m) @{ driver.error (l, m); @@ -8896,24 +9278,22 @@ parser's to get the set of defined tokens. @comment file: calc++-scanner.ll @example %@{ /* -*- C++ -*- */ -# include # include # include +# include # include # include "calc++-driver.hh" # include "calc++-parser.hh" -/* Work around an incompatibility in flex (at least versions - 2.5.31 through 2.5.33): it generates code that does - not conform to C89. See Debian bug 333231 - . */ +// Work around an incompatibility in flex (at least versions +// 2.5.31 through 2.5.33): it generates code that does +// not conform to C89. See Debian bug 333231 +// . # undef yywrap # define yywrap() 1 -/* By default yylex returns an int; we use token_type. - The default yyterminate implementation returns 0, which is - not of token_type. */ -#define yyterminate() return TOKEN(END) +// The location of the current token. +static yy::location loc; %@} @end example @@ -8921,7 +9301,7 @@ parser's to get the set of defined tokens. Because there is no @code{#include}-like feature we don't need @code{yywrap}, we don't need @code{unput} either, and we parse an actual file, this is not an interactive session with the user. -Finally we enable the scanner tracing features. +Finally, we enable scanner tracing. @comment file: calc++-scanner.ll @example @@ -8941,8 +9321,8 @@ blank [ \t] @noindent The following paragraph suffices to track locations accurately. Each time @code{yylex} is invoked, the begin position is moved onto the end -position. Then when a pattern is matched, the end position is -advanced of its width. In case it matched ends of lines, the end +position. Then when a pattern is matched, its width is added to the end +column. When matching ends of lines, the end cursor is adjusted, and each time blanks are matched, the begin cursor is moved onto the end cursor to effectively ignore the blanks preceding tokens. Comments would be treated equally. @@ -8950,49 +9330,46 @@ preceding tokens. Comments would be treated equally. @comment file: calc++-scanner.ll @example %@{ -# define YY_USER_ACTION yylloc->columns (yyleng); + // Code run each time a pattern is matched. + # define YY_USER_ACTION loc.columns (yyleng); %@} %% %@{ - yylloc->step (); + // Code run each time yylex is called. + loc.step (); %@} -@{blank@}+ yylloc->step (); -[\n]+ yylloc->lines (yyleng); yylloc->step (); +@{blank@}+ loc.step (); +[\n]+ loc.lines (yyleng); loc.step (); @end example @noindent -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_}. +The rules are simple. The driver is used to report errors. @comment file: calc++-scanner.ll @example -%@{ -# 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]); -":=" return TOKEN(ASSIGN); +"-" return yy::calcxx_parser::make_MINUS(loc); +"+" return yy::calcxx_parser::make_PLUS(loc); +"*" return yy::calcxx_parser::make_STAR(loc); +"/" return yy::calcxx_parser::make_SLASH(loc); +"(" return yy::calcxx_parser::make_LPAREN(loc); +")" return yy::calcxx_parser::make_RPAREN(loc); +":=" return yy::calcxx_parser::make_ASSIGN(loc); + @{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); + driver.error (loc, "integer is out of range"); + return yy::calcxx_parser::make_NUMBER(n, loc); @} -@{id@} @{ - yylval->sval = new std::string (yytext); - return TOKEN(IDENTIFIER); -@} -. driver.error (*yylloc, "invalid character"); +@{id@} return yy::calcxx_parser::make_IDENTIFIER(yytext, loc); +. driver.error (loc, "invalid character"); +<> return yy::calcxx_parser::make_END(loc); %% @end example @noindent -Finally, because the scanner related driver's member function depend +Finally, because the scanner-related driver's member-functions depend on the scanner's data, it is simpler to implement them in this file. @comment file: calc++-scanner.ll @@ -9005,7 +9382,7 @@ calcxx_driver::scan_begin () yyin = stdin; else if (!(yyin = fopen (file.c_str (), "r"))) @{ - error (std::string ("cannot open ") + file); + error (std::string ("cannot open ") + file + ": " + strerror(errno)); exit (1); @} @} @@ -9084,7 +9461,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 @@ -9109,7 +9486,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. @@ -9132,7 +9509,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 @@ -9172,11 +9549,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. @@ -9211,22 +9588,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 @@ -9242,25 +9619,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 () @@ -9271,7 +9649,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 @@ -9337,15 +9715,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 @@ -9355,14 +9733,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 @@ -9373,7 +9751,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} @@ -9390,7 +9768,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}. @@ -9477,7 +9855,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. @@ -9486,12 +9864,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. @@ -9532,7 +9910,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 @@ -9722,7 +10100,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 @@ -10158,6 +10536,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 @@ -10200,7 +10579,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}" @@ -10227,8 +10606,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 @@ -10267,10 +10646,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 @@ -10284,7 +10668,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 @@ -10406,8 +10790,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 @@ -10755,32 +11139,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