X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/6ce4b4ff1b761a0408cf94abb308fac9b55edd3d..baa423bd59767a687ad742adc66a5b7428a41dee:/doc/bison.texi?ds=sidebyside diff --git a/doc/bison.texi b/doc/bison.texi index 4a4bd600..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 @@ -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 @@ -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 @@ -6009,12 +6014,12 @@ Use this @var{type} 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: @@ -6025,6 +6030,30 @@ introduced in Bison 3.0. Was introduced for Java only in 2.3b as @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. @@ -7521,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 @@ -10064,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. @@ -10085,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: @@ -10347,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); @@ -10651,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 () @@ -10694,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; @@ -10847,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 @@ -10861,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 @@ -10875,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 @@ -10908,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, @@ -10929,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 @@ -11283,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 @@ -11407,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@} @{ @@ -11421,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 @@ -11500,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 @@ -11811,7 +11864,6 @@ The return type can be changed using @samp{%define api.value.type @{@var{class-name}@}}. @end deftypemethod - @node Java Action Features @subsection Special Features for Use in Java Actions @@ -11890,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