X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/07e65a77aa7b9ae259f6fcf16e8f322f4814ee39..baa423bd59767a687ad742adc66a5b7428a41dee:/doc/bison.texi diff --git a/doc/bison.texi b/doc/bison.texi index c36e2e27..737a119c 100644 --- a/doc/bison.texi +++ b/doc/bison.texi @@ -1,6 +1,8 @@ \input texinfo @c -*-texinfo-*- @comment %**start of header @setfilename bison.info +@documentencoding UTF-8 +@documentlanguage en @include version.texi @settitle Bison @value{VERSION} @setchapternewpage odd @@ -33,7 +35,7 @@ This manual (@value{UPDATED}) is for GNU Bison (version @value{VERSION}), the GNU parser generator. -Copyright @copyright{} 1988-1993, 1995, 1998-2013 Free Software +Copyright @copyright{} 1988-1993, 1995, 1998-2015 Free Software Foundation, Inc. @quotation @@ -366,6 +368,7 @@ Java Parsers * Java Parser Interface:: Instantiating and running the parser * Java Scanner Interface:: Specifying the scanner for the parser * Java Action Features:: Special features for use in actions +* Java Push Parser Interface:: Instantiating and running the a push parser * Java Differences:: Differences between C/C++ and Java Grammars * Java Declarations Summary:: List of Bison declarations used with Java @@ -2160,7 +2163,7 @@ the same as the declarations for the infix notation calculator. %@} /* Bison declarations. */ -%define api.value.type int +%define api.value.type @{int@} %token NUM %left '-' '+' @@ -3848,7 +3851,7 @@ example: @noindent specifies the union tag @code{value}, so the corresponding C type is @code{union value}. If you do not specify a tag, it defaults to -@code{YYSTYPE}. +@code{YYSTYPE} (@pxref{%define Summary,,api.value.union.name}). As another extension to POSIX, you may specify multiple @code{%union} declarations; their contents are concatenated. However, only the first @@ -3885,7 +3888,7 @@ and then your grammar can use the following instead of @code{%union}: %@{ #include "parser.h" %@} -%define api.value.type "union YYSTYPE" +%define api.value.type @{union YYSTYPE@} %type expr %token ID @end group @@ -5142,7 +5145,9 @@ value by default. However, when the parser displays a @code{STRING1} or a @code{string1}, it formats it as a string in double quotes. It performs only the second @code{%printer} in this case, so it prints only once. Finally, the parser print @samp{<>} for any symbol, such as @code{TAGLESS}, -that has no semantic type tag. See also +that has no semantic type tag. @xref{Mfcalc Traces, ,Enabling Debug Traces +for @code{mfcalc}}, for a complete example. + @node Expect Decl @@ -5450,6 +5455,7 @@ parse.trace}. @deffn {Directive} %define @var{variable} @deffnx {Directive} %define @var{variable} @var{value} +@deffnx {Directive} %define @var{variable} @{@var{value}@} @deffnx {Directive} %define @var{variable} "@var{value}" Define a variable to adjust Bison's behavior. @xref{%define Summary}. @end deffn @@ -5499,7 +5505,7 @@ preprocessor guard: @samp{YY_@var{PREFIX}_@var{FILE}_INCLUDED}, where uppercase, with each series of non alphanumerical characters converted to a single underscore. -For instance with @samp{%define api.prefix "calc"} and @samp{%defines +For instance with @samp{%define api.prefix @{calc@}} and @samp{%defines "lib/parse.h"}, the header will be guarded as follows. @example #ifndef YY_CALC_LIB_PARSE_H_INCLUDED @@ -5661,17 +5667,17 @@ features are associated with variables, which are assigned by the @deffn {Directive} %define @var{variable} @deffnx {Directive} %define @var{variable} @var{value} +@deffnx {Directive} %define @var{variable} @{@var{value}@} @deffnx {Directive} %define @var{variable} "@var{value}" Define @var{variable} to @var{value}. -@var{value} must be placed in quotation marks if it contains any -character other than a letter, underscore, period, or non-initial dash -or digit. Omitting @code{"@var{value}"} entirely is always equivalent -to specifying @code{""}. +The type of the values depend on the syntax. Braces denote value in the +target language (e.g., a namespace, a type, etc.). Keyword values (no +delimiters) denote finite choice (e.g., a variation of a feature). String +values denote remaining cases (e.g., a file name). -It is an error if a @var{variable} is defined by @code{%define} -multiple times, but see @ref{Bison Options,,-D -@var{name}[=@var{value}]}. +It is an error if a @var{variable} is defined by @code{%define} multiple +times, but see @ref{Bison Options,,-D @var{name}[=@var{value}]}. @end deffn The rest of this section summarizes variables and values that @@ -5753,7 +5759,7 @@ The parser namespace is @code{foo} and @code{yylex} is referenced as @c api.namespace @c ================================================== api.location.type -@deffn {Directive} {%define api.location.type} @var{type} +@deffn {Directive} {%define api.location.type} @{@var{type}@} @itemize @bullet @item Language(s): C++, Java @@ -5772,7 +5778,7 @@ Introduced in Bison 2.7 for C, C++ and Java. Introduced under the name @end deffn @c ================================================== api.prefix -@deffn {Directive} {%define api.prefix} @var{prefix} +@deffn {Directive} {%define api.prefix} @{@var{prefix}@} @itemize @bullet @item Language(s): All @@ -5789,7 +5795,7 @@ Introduced in Bison 2.7 for C, C++ and Java. Introduced under the name @end deffn @c ================================================== api.pure -@deffn Directive {%define api.pure} +@deffn Directive {%define api.pure} @var{purity} @itemize @bullet @item Language(s): C @@ -5877,7 +5883,7 @@ Boolean. @item Default Value: @code{false} @item History: -introduced in Bison 2.8 +introduced in Bison 3.0 @end itemize @end deffn @c api.token.constructor @@ -5929,7 +5935,8 @@ introduced in Bison 3.0 @c ================================================== api.value.type -@deffn Directive {%define api.value.type} @var{type} +@deffn Directive {%define api.value.type} @var{support} +@deffnx Directive {%define api.value.type} @{@var{type}@} @itemize @bullet @item Language(s): all @@ -5939,16 +5946,16 @@ The type for semantic values. @item Accepted Values: @table @asis -@item @code{""} +@item @samp{@{@}} This grammar has no semantic value at all. This is not properly supported yet. -@item @code{%union} (C, C++) +@item @samp{union-directive} (C, C++) The type is defined thanks to the @code{%union} directive. You don't have to define @code{api.value.type} in that case, using @code{%union} suffices. @xref{Union Decl, ,The Union Declaration}. For instance: @example -%define api.value.type "%union" +%define api.value.type union-directive %union @{ int ival; @@ -5958,30 +5965,30 @@ For instance: %token STR "string" @end example -@item @code{union} (C, C++) +@item @samp{union} (C, C++) The symbols are defined with type names, from which Bison will generate a @code{union}. For instance: @example -%define api.value.type "union" +%define api.value.type union %token INT "integer" %token STR "string" @end example This feature needs user feedback to stabilize. Note that most C++ objects cannot be stored in a @code{union}. -@item @code{variant} (C++) +@item @samp{variant} (C++) This is similar to @code{union}, but special storage techniques are used to allow any kind of C++ object to be used. For instance: @example -%define api.value.type "variant" +%define api.value.type variant %token INT "integer" %token STR "string" @end example This feature needs user feedback to stabilize. @xref{C++ Variants}. -@item any other identifier -Use this name as semantic value. +@item @samp{@{@var{type}@}} +Use this @var{type} as semantic value. @example %code requires @{ @@ -5998,7 +6005,7 @@ Use this name as semantic value. @} u; @}; @} -%define api.value.type "struct my_value" +%define api.value.type @{struct my_value@} %token INT "integer" %token STR "string" @end example @@ -6007,22 +6014,46 @@ Use this name as semantic value. @item Default Value: @itemize @minus @item -@code{%union} if @code{%union} is used, otherwise @dots{} +@code{union-directive} if @code{%union} is used, otherwise @dots{} @item @code{int} if type tags are used (i.e., @samp{%token <@var{type}>@dots{}} or -@samp{%token <@var{type}>@dots{}} is used), otherwise @dots{} +@samp{%type <@var{type}>@dots{}} is used), otherwise @dots{} @item -@code{""} +undefined. @end itemize @item History: -introduced in Bison 2.8. Was introduced for Java only in 2.3b as +introduced in Bison 3.0. Was introduced for Java only in 2.3b as @code{stype}. @end itemize @end deffn @c api.value.type +@c ================================================== api.value.union.name +@deffn Directive {%define api.value.union.name} @var{name} +@itemize @bullet +@item Language(s): +C + +@item Purpose: +The tag of the generated @code{union} (@emph{not} the name of the +@code{typedef}). This variable is set to @code{@var{id}} when @samp{%union +@var{id}} is used. There is no clear reason to give this union a name. + +@item Accepted Values: +Any valid identifier. + +@item Default Value: +@code{YYSTYPE}. + +@item History: +Introduced in Bison 3.0.3. +@end itemize +@end deffn +@c api.value.type + + @c ================================================== location_type @deffn Directive {%define location_type} Obsoleted by @code{api.location.type} since Bison 2.7. @@ -6048,8 +6079,8 @@ feedback will help to stabilize it.) @item @code{most} otherwise. @end itemize @item History: -introduced as @code{lr.default-reduction} in 2.5, renamed as -@code{lr.default-reduction} in 2.8. +introduced as @code{lr.default-reductions} in 2.5, renamed as +@code{lr.default-reduction} in 3.0. @end itemize @end deffn @@ -6066,7 +6097,7 @@ remain in the parser tables. @xref{Unreachable States}. @item History: introduced as @code{lr.keep_unreachable_states} in 2.3b, renamed as @code{lr.keep-unreachable-states} in 2.5, and as -@code{lr.keep-unreachable-state} in 2.8. +@code{lr.keep-unreachable-state} in 3.0. @end itemize @end deffn @c lr.keep-unreachable-state @@ -6114,7 +6145,7 @@ destroyed properly. This option checks these constraints. @c ================================================== parse.error -@deffn Directive {%define parse.error} +@deffn Directive {%define parse.error} @var{verbosity} @itemize @item Languages(s): all @@ -6141,7 +6172,7 @@ However, this report can often be incorrect when LAC is not enabled @c ================================================== parse.lac -@deffn Directive {%define parse.lac} +@deffn Directive {%define parse.lac} @var{when} @itemize @item Languages(s): C (deterministic parsers only) @@ -6164,7 +6195,7 @@ syntax error handling. @xref{LAC}. @xref{Tracing, ,Tracing Your Parser}. In C/C++, define the macro @code{YYDEBUG} (or @code{@var{prefix}DEBUG} with -@samp{%define api.prefix @var{prefix}}), see @ref{Multiple Parsers, +@samp{%define api.prefix @{@var{prefix}@}}), see @ref{Multiple Parsers, ,Multiple Parsers in the Same Program}) to 1 in the parser implementation file if it is not already defined, so that the debugging facilities are compiled. @@ -6307,7 +6338,7 @@ The easy way to do this is to define the @code{%define} variable @code{api.prefix}. With different @code{api.prefix}s it is guaranteed that headers do not conflict when included together, and that compiled objects can be linked together too. Specifying @samp{%define api.prefix -@var{prefix}} (or passing the option @samp{-Dapi.prefix=@var{prefix}}, see +@{@var{prefix}@}} (or passing the option @samp{-Dapi.prefix=@{@var{prefix}@}}, see @ref{Invocation, ,Invoking Bison}) renames the interface functions and variables of the Bison parser to start with @var{prefix} instead of @samp{yy}, and all the macros to start by @var{PREFIX} (i.e., @var{prefix} @@ -6321,7 +6352,7 @@ The renamed symbols include @code{yyparse}, @code{yylex}, @code{yyerror}, @code{YYSTYPE}, @code{YYLTYPE}, and @code{YYDEBUG}, which is treated specifically --- more about this below. -For example, if you use @samp{%define api.prefix c}, the names become +For example, if you use @samp{%define api.prefix @{c@}}, the names become @code{cparse}, @code{clex}, @dots{}, @code{CSTYPE}, @code{CLTYPE}, and so on. @@ -7519,7 +7550,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 traditionally +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 @@ -9554,7 +9585,7 @@ enabled if and only if @code{YYDEBUG} is nonzero. @item the option @option{-t} (POSIX Yacc compliant) @itemx the option @option{--debug} (Bison extension) Use the @samp{-t} option when you run Bison (@pxref{Invocation, ,Invoking -Bison}). With @samp{%define api.prefix c}, it defines @code{CDEBUG} to 1, +Bison}). With @samp{%define api.prefix @{c@}}, it defines @code{CDEBUG} to 1, otherwise it defines @code{YYDEBUG} to 1. @item the directive @samp{%debug} @@ -10062,18 +10093,16 @@ A category can be turned off by prefixing its name with @samp{no-}. For instance, @option{-Wno-yacc} will hide the warnings about POSIX Yacc incompatibilities. -@item -Werror[=@var{category}] -@itemx -Wno-error[=@var{category}] -Enable warnings falling in @var{category}, and treat them as errors. If no -@var{category} is given, it defaults to making all enabled warnings into errors. +@item -Werror +Turn enabled warnings for every @var{category} into errors, unless they are +explicitly disabled by @option{-Wno-error=@var{category}}. + +@item -Werror=@var{category} +Enable warnings falling in @var{category}, and treat them as errors. @var{category} is the same as for @option{--warnings}, with the exception that it may not be prefixed with @samp{no-} (see above). -Prefixed with @samp{no}, it deactivates the error treatment for this -@var{category}. However, the warning itself won't be disabled, or enabled, by -this option. - Note that the precedence of the @samp{=} and @samp{,} operators is such that the following commands are @emph{not} equivalent, as the first will not treat S/R conflicts as errors. @@ -10083,6 +10112,14 @@ $ bison -Werror=yacc,conflicts-sr input.y $ bison -Werror=yacc,error=conflicts-sr input.y @end example +@item -Wno-error +Do not turn enabled warnings for every @var{category} into errors, unless +they are explicitly enabled by @option{-Werror=@var{category}}. + +@item -Wno-error=@var{category} +Deactivate the error treatment for this @var{category}. However, the warning +itself won't be disabled, or enabled, by this option. + @item -f [@var{feature}] @itemx --feature[=@var{feature}] Activate miscellaneous @var{feature}. @var{feature} can be one of: @@ -10345,9 +10382,23 @@ declare @code{yyerror} as follows: int yyerror (char const *); @end example -Bison ignores the @code{int} value returned by this @code{yyerror}. -If you use the Yacc library's @code{main} function, your -@code{yyparse} function should have the following type signature: +@noindent +The @code{int} value returned by this @code{yyerror} is ignored. + +The implementation of Yacc library's @code{main} function is: + +@example +int main (void) +@{ + setlocale (LC_ALL, ""); + return yyparse (); +@} +@end example + +@noindent +so if you use it, the internationalization support is enabled (e.g., error +messages are translated), and your @code{yyparse} function should have the +following type signature: @example int yyparse (void); @@ -10649,12 +10700,17 @@ The first, inclusive, position of the range, and the first beyond. Forwarded to the @code{end} position. @end deftypemethod -@deftypemethod {location} {location} operator+ (const location& @var{end}) -@deftypemethodx {location} {location} operator+ (int @var{width}) +@deftypemethod {location} {location} operator+ (int @var{width}) @deftypemethodx {location} {location} operator+= (int @var{width}) -@deftypemethodx {location} {location} operator- (int @var{width}) +@deftypemethodx {location} {location} operator- (int @var{width}) @deftypemethodx {location} {location} operator-= (int @var{width}) -Various forms of syntactic sugar. +Various forms of syntactic sugar for @code{columns}. +@end deftypemethod + +@deftypemethod {location} {location} operator+ (const location& @var{end}) +@deftypemethodx {location} {location} operator+= (const location& @var{end}) +Join two locations: starts at the position of the first one, and ends at the +position of the second. @end deftypemethod @deftypemethod {location} {void} step () @@ -10680,7 +10736,7 @@ Instead of using the built-in types you may use the @code{%define} variable @code{api.location.type} to specify your own type: @example -%define api.location.type @var{LocationType} +%define api.location.type @{@var{LocationType}@} @end example The requirements over your @var{LocationType} are: @@ -10692,8 +10748,8 @@ it must be copyable; in order to compute the (default) value of @code{@@$} in a reduction, the parser basically runs @example -@@$.begin = @@$1.begin; -@@$.end = @@$@var{N}.end; // The location of last right-hand side symbol. +@@$.begin = @@1.begin; +@@$.end = @@@var{N}.end; // The location of last right-hand side symbol. @end example @noindent so there must be copyable @code{begin} and @code{end} members; @@ -10717,7 +10773,7 @@ parser @file{master/parser.yy} might use: @example %defines %locations -%define namespace "master::" +%define api.namespace @{master::@} @end example @noindent @@ -10725,7 +10781,7 @@ to generate the @file{master/position.hh} and @file{master/location.hh} files, reused by other parsers as follows: @example -%define api.location.type "master::location" +%define api.location.type @{master::location@} %code requires @{ #include @} @end example @@ -10740,7 +10796,7 @@ files, reused by other parsers as follows: The output files @file{@var{output}.hh} and @file{@var{output}.cc} declare and define the parser class in the namespace @code{yy}. The class name defaults to @code{parser}, but may be changed using -@samp{%define parser_class_name "@var{name}"}. The interface of +@samp{%define parser_class_name @{@var{name}@}}. The interface of this class is detailed below. It can be extended using the @code{%parse-param} feature: its semantics is slightly changed since it describes an additional member of the parser class, and an @@ -10845,12 +10901,12 @@ Regular union-based code in Lex scanner typically look like: @example [0-9]+ @{ - yylval.ival = text_to_int (yytext); - return yy::parser::INTEGER; + yylval->ival = text_to_int (yytext); + return yy::parser::token::INTEGER; @} [a-z]+ @{ - yylval.sval = new std::string (yytext); - return yy::parser::IDENTIFIER; + yylval->sval = new std::string (yytext); + return yy::parser::token::IDENTIFIER; @} @end example @@ -10859,12 +10915,12 @@ initialized. So the code would look like: @example [0-9]+ @{ - yylval.build() = text_to_int (yytext); - return yy::parser::INTEGER; + yylval->build () = text_to_int (yytext); + return yy::parser::token::INTEGER; @} [a-z]+ @{ - yylval.build = yytext; - return yy::parser::IDENTIFIER; + yylval->build () = yytext; + return yy::parser::token::IDENTIFIER; @} @end example @@ -10873,12 +10929,12 @@ or @example [0-9]+ @{ - yylval.build(text_to_int (yytext)); - return yy::parser::INTEGER; + yylval->build (text_to_int (yytext)); + return yy::parser::token::INTEGER; @} [a-z]+ @{ - yylval.build(yytext); - return yy::parser::IDENTIFIER; + yylval->build (yytext); + return yy::parser::token::IDENTIFIER; @} @end example @@ -10906,8 +10962,8 @@ 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}) +@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.token.prefix}) whose possible semantic value is @var{value} of adequate @var{value_type}. If location tracking is enabled, @@ -10927,20 +10983,18 @@ For instance, given the following declarations: 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); +symbol_type make_IDENTIFIER (const std::string&, const location_type&); +symbol_type make_INTEGER (const int&, const location_type&); +symbol_type make_COLON (const location_type&); @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); +[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 @@ -11145,7 +11199,7 @@ the grammar for. %skeleton "lalr1.cc" /* -*- C++ -*- */ %require "@value{VERSION}" %defines -%define parser_class_name "calcxx_parser" +%define parser_class_name @{calcxx_parser@} @end example @noindent @@ -11281,7 +11335,7 @@ regular destructors. All the values are printed using their @noindent The grammar itself is straightforward (@pxref{Location Tracking Calc, , -Location Tracking Calculator: @code{ltcalc}}). +Location Tracking Calculator - @code{ltcalc}}). @comment file: calc++-parser.yy @example @@ -11405,13 +11459,13 @@ The rules are simple. The driver is used to report errors. @comment file: calc++-scanner.ll @example -"-" 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); +"-" 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); @group @{int@} @{ @@ -11419,12 +11473,12 @@ The rules are simple. The driver is used to report errors. long n = strtol (yytext, NULL, 10); if (! (INT_MIN <= n && n <= INT_MAX && errno != ERANGE)) driver.error (loc, "integer is out of range"); - return yy::calcxx_parser::make_NUMBER(n, loc); + return yy::calcxx_parser::make_NUMBER (n, loc); @} @end group -@{id@} return yy::calcxx_parser::make_IDENTIFIER(yytext, loc); +@{id@} return yy::calcxx_parser::make_IDENTIFIER (yytext, loc); . driver.error (loc, "invalid character"); -<> return yy::calcxx_parser::make_END(loc); +<> return yy::calcxx_parser::make_END (loc); %% @end example @@ -11498,6 +11552,7 @@ main (int argc, char *argv[]) * Java Parser Interface:: Instantiating and running the parser * Java Scanner Interface:: Specifying the scanner for the parser * Java Action Features:: Special features for use in actions +* Java Push Parser Interface:: Instantiating and running the a push parser * Java Differences:: Differences between C/C++ and Java Grammars * Java Declarations Summary:: List of Bison declarations used with Java @end menu @@ -11579,7 +11634,7 @@ superclass of all the semantic values using the @samp{%define api.value.type} directive. For example, after the following declaration: @example -%define api.value.type "ASTNode" +%define api.value.type @{ASTNode@} @end example @noindent @@ -11614,11 +11669,11 @@ class defines a @dfn{position}, a single point in a file; Bison itself defines a class representing a @dfn{location}, a range composed of a pair of positions (possibly spanning several files). The location class is an inner class of the parser; the name is @code{Location} by default, and may also be -renamed using @code{%define api.location.type "@var{class-name}"}. +renamed using @code{%define api.location.type @{@var{class-name}@}}. The location class treats the position as a completely opaque value. By default, the class name is @code{Position}, but this can be changed -with @code{%define api.position.type "@var{class-name}"}. This class must +with @code{%define api.position.type @{@var{class-name}@}}. This class must be supplied by the user. @@ -11653,7 +11708,7 @@ properly, the position class should override the @code{equals} and The name of the generated parser class defaults to @code{YYParser}. The @code{YY} prefix may be changed using the @code{%name-prefix} directive or the @option{-p}/@option{--name-prefix} option. Alternatively, use -@samp{%define parser_class_name "@var{name}"} to give a custom name to +@samp{%define parser_class_name @{@var{name}@}} to give a custom name to the class. The interface of this class is detailed below. By default, the parser class has package visibility. A declaration @@ -11662,7 +11717,7 @@ according to the Java language specification, the name of the @file{.java} file should match the name of the class in this case. Similarly, you can use @code{abstract}, @code{final} and @code{strictfp} with the @code{%define} declaration to add other modifiers to the parser class. -A single @samp{%define annotations "@var{annotations}"} directive can +A single @samp{%define annotations @{@var{annotations}@}} directive can be used to add any number of annotations to the parser class. The Java package name of the parser class can be specified using the @@ -11780,7 +11835,7 @@ In both cases, the scanner has to implement the following methods. @deftypemethod {Lexer} {void} yyerror (Location @var{loc}, String @var{msg}) This method is defined by the user to emit an error message. The first parameter is omitted if location tracking is not active. Its type can be -changed using @code{%define api.location.type "@var{class-name}".} +changed using @code{%define api.location.type @{@var{class-name}@}}. @end deftypemethod @deftypemethod {Lexer} {int} yylex () @@ -11799,17 +11854,16 @@ Return respectively the first position of the last token that methods are not needed unless location tracking is active. The return type can be changed using @code{%define api.position.type -"@var{class-name}".} +@{@var{class-name}@}}. @end deftypemethod @deftypemethod {Lexer} {Object} getLVal () Return the semantic value of the last token that yylex returned. The return type can be changed using @samp{%define api.value.type -"@var{class-name}".} +@{@var{class-name}@}}. @end deftypemethod - @node Java Action Features @subsection Special Features for Use in Java Actions @@ -11888,6 +11942,73 @@ instance in use. The @code{Location} and @code{Position} parameters are available only if location tracking is active. @end deftypefn +@node Java Push Parser Interface +@subsection Java Push Parser Interface +@c - define push_parse +@findex %define api.push-pull + +(The current push parsing interface is experimental and may evolve. More +user feedback will help to stabilize it.) + +Normally, Bison generates a pull parser for Java. +The following Bison declaration says that you want the parser to be a push +parser (@pxref{%define Summary,,api.push-pull}): + +@example +%define api.push-pull push +@end example + +Most of the discussion about the Java pull Parser Interface, (@pxref{Java +Parser Interface}) applies to the push parser interface as well. + +When generating a push parser, the method @code{push_parse} is created with +the following signature (depending on if locations are enabled). + +@deftypemethod {YYParser} {void} push_parse ({int} @var{token}, {Object} @var{yylval}) +@deftypemethodx {YYParser} {void} push_parse ({int} @var{token}, {Object} @var{yylval}, {Location} @var{yyloc}) +@deftypemethodx {YYParser} {void} push_parse ({int} @var{token}, {Object} @var{yylval}, {Position} @var{yypos}) +@end deftypemethod + +The primary difference with respect to a pull parser is that the parser +method @code{push_parse} is invoked repeatedly to parse each token. This +function is available if either the "%define api.push-pull push" or "%define +api.push-pull both" declaration is used (@pxref{%define +Summary,,api.push-pull}). The @code{Location} and @code{Position} +parameters are available only if location tracking is active. + +The value returned by the @code{push_parse} method is one of the following +four constants: @code{YYABORT}, @code{YYACCEPT}, @code{YYERROR}, or +@code{YYPUSH_MORE}. This new value, @code{YYPUSH_MORE}, may be returned if +more input is required to finish parsing the grammar. + +If api.push-pull is declared as @code{both}, then the generated parser class +will also implement the @code{parse} method. This method's body is a loop +that repeatedly invokes the scanner and then passes the values obtained from +the scanner to the @code{push_parse} method. + +There is one additional complication. Technically, the push parser does not +need to know about the scanner (i.e. an object implementing the +@code{YYParser.Lexer} interface), but it does need access to the +@code{yyerror} method. Currently, the @code{yyerror} method is defined in +the @code{YYParser.Lexer} interface. Hence, an implementation of that +interface is still required in order to provide an implementation of +@code{yyerror}. The current approach (and subject to change) is to require +the @code{YYParser} constructor to be given an object implementing the +@code{YYParser.Lexer} interface. This object need only implement the +@code{yyerror} method; the other methods can be stubbed since they will +never be invoked. The simplest way to do this is to add a trivial scanner +implementation to your grammar file using whatever implementation of +@code{yyerror} is desired. The following code sample shows a simple way to +accomplish this. + +@example +%code lexer +@{ + public Object getLVal () @{return null;@} + public int yylex () @{return 0;@} + public void yyerror (String s) @{System.err.println(s);@} +@} +@end example @node Java Differences @subsection Differences between C/C++ and Java Grammars @@ -12027,12 +12148,12 @@ Whether the parser class is declared @code{abstract}. Default is false. @xref{Java Bison Interface}. @end deffn -@deffn {Directive} {%define annotations} "@var{annotations}" +@deffn {Directive} {%define annotations} @{@var{annotations}@} The Java annotations for the parser class. Default is none. @xref{Java Bison Interface}. @end deffn -@deffn {Directive} {%define extends} "@var{superclass}" +@deffn {Directive} {%define extends} @{@var{superclass}@} The superclass of the parser class. Default is none. @xref{Java Bison Interface}. @end deffn @@ -12042,25 +12163,25 @@ Whether the parser class is declared @code{final}. Default is false. @xref{Java Bison Interface}. @end deffn -@deffn {Directive} {%define implements} "@var{interfaces}" +@deffn {Directive} {%define implements} @{@var{interfaces}@} The implemented interfaces of the parser class, a comma-separated list. Default is none. @xref{Java Bison Interface}. @end deffn -@deffn {Directive} {%define init_throws} "@var{exceptions}" +@deffn {Directive} {%define init_throws} @{@var{exceptions}@} The exceptions thrown by @code{%code init} from the parser class constructor. Default is none. @xref{Java Parser Interface}. @end deffn -@deffn {Directive} {%define lex_throws} "@var{exceptions}" +@deffn {Directive} {%define lex_throws} @{@var{exceptions}@} The exceptions thrown by the @code{yylex} method of the lexer, a comma-separated list. Default is @code{java.io.IOException}. @xref{Java Scanner Interface}. @end deffn -@deffn {Directive} {%define api.location.type} "@var{class}" +@deffn {Directive} {%define api.location.type} @{@var{class}@} The name of the class used for locations (a range between two positions). This class is generated as an inner class of the parser class by @command{bison}. Default is @code{Location}. @@ -12068,18 +12189,18 @@ Formerly named @code{location_type}. @xref{Java Location Values}. @end deffn -@deffn {Directive} {%define package} "@var{package}" +@deffn {Directive} {%define package} @{@var{package}@} The package to put the parser class in. Default is none. @xref{Java Bison Interface}. @end deffn -@deffn {Directive} {%define parser_class_name} "@var{name}" +@deffn {Directive} {%define parser_class_name} @{@var{name}@} The name of the parser class. Default is @code{YYParser} or @code{@var{name-prefix}Parser}. @xref{Java Bison Interface}. @end deffn -@deffn {Directive} {%define api.position.type} "@var{class}" +@deffn {Directive} {%define api.position.type} @{@var{class}@} The name of the class used for positions. This class must be supplied by the user. Default is @code{Position}. Formerly named @code{position_type}. @@ -12091,7 +12212,7 @@ Whether the parser class is declared @code{public}. Default is false. @xref{Java Bison Interface}. @end deffn -@deffn {Directive} {%define api.value.type} "@var{class}" +@deffn {Directive} {%define api.value.type} @{@var{class}@} The base type of semantic values. Default is @code{Object}. @xref{Java Semantic Values}. @end deffn @@ -12101,7 +12222,7 @@ Whether the parser class is declared @code{strictfp}. Default is false. @xref{Java Bison Interface}. @end deffn -@deffn {Directive} {%define throws} "@var{exceptions}" +@deffn {Directive} {%define throws} @{@var{exceptions}@} The exceptions thrown by user-supplied parser actions and @code{%initial-action}, a comma-separated list. Default is none. @xref{Java Parser Interface}. @@ -12655,6 +12776,7 @@ Precedence}. @deffn {Directive} %define @var{variable} @deffnx {Directive} %define @var{variable} @var{value} +@deffnx {Directive} %define @var{variable} @{@var{value}@} @deffnx {Directive} %define @var{variable} "@var{value}" Define a variable to adjust Bison's behavior. @xref{%define Summary}. @end deffn