X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/cff03fb2b92a05f61c142783dd3b2e0103782869..8fa369111fcc3d06a0c9fc278f063b8033dac094:/doc/bison.texinfo diff --git a/doc/bison.texinfo b/doc/bison.texinfo index 8268783f..b6a98f9d 100644 --- a/doc/bison.texinfo +++ b/doc/bison.texinfo @@ -34,7 +34,8 @@ This manual is for @acronym{GNU} Bison (version @value{VERSION}, @value{UPDATED}), the @acronym{GNU} parser generator. Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998, -1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software +Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -45,10 +46,10 @@ being ``A @acronym{GNU} Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled ``@acronym{GNU} Free Documentation License.'' -(a) The @acronym{FSF}'s Back-Cover Text is: ``You have freedom to copy -and modify this @acronym{GNU} Manual, like @acronym{GNU} software. -Copies published by the Free Software Foundation raise funds for -@acronym{GNU} development.'' +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this @acronym{GNU} manual. Buying copies from the @acronym{FSF} +supports it in developing @acronym{GNU} and promoting software +freedom.'' @end quotation @end copying @@ -4022,7 +4023,7 @@ associativity and precedence. @xref{Precedence Decl, ,Operator Precedence}. You can explicitly specify the numeric code for a token type by appending -a decimal or hexadecimal integer value in the field immediately +a nonnegative decimal or hexadecimal integer value in the field immediately following the token name: @example @@ -4075,6 +4076,16 @@ Once you equate the literal string and the token name, you can use them interchangeably in further declarations or the grammar rules. The @code{yylex} function can use the token name or the literal string to obtain the token type code number (@pxref{Calling Convention}). +Syntax error messages passed to @code{yyerror} from the parser will reference +the literal string instead of the token name. + +The token numbered as 0 corresponds to end of file; the following line +allows for nicer error messages referring to ``end of file'' instead +of ``$end'': + +@example +%token END 0 "end of file" +@end example @node Precedence Decl @subsection Operator Precedence @@ -4088,7 +4099,7 @@ once. These are called @dfn{precedence declarations}. @xref{Precedence, ,Operator Precedence}, for general information on operator precedence. -The syntax of a precedence declaration is the same as that of +The syntax of a precedence declaration is nearly the same as that of @code{%token}: either @example @@ -4126,6 +4137,18 @@ When two tokens declared in different precedence declarations associate, the one declared later has the higher precedence and is grouped first. @end itemize +For backward compatibility, there is a confusing difference between the +argument lists of @code{%token} and precedence declarations. +Only a @code{%token} can associate a literal string with a token type name. +A precedence declaration always interprets a literal string as a reference to a +separate token. +For example: + +@example +%left OR "<=" // Does not declare an alias. +%left OR 134 "<=" 135 // Declares 134 for OR and 135 for "<=". +@end example + @node Union Decl @subsection The Collection of Value Types @cindex declaring value types @@ -4530,6 +4553,9 @@ valid grammar. @cindex push parser @findex %define api.push_pull +(The current push parsing interface is experimental and may evolve. +More user feedback will help to stabilize it.) + A pull parser is called once and it takes control until all its input is completely parsed. A push parser, on the other hand, is called each time a new token is made available. @@ -4859,6 +4885,8 @@ Some of the accepted @var{variable}s are: @item Purpose: Requests a pull parser, a push parser, or both. @xref{Push Decl, ,A Push Parser}. +(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"} @@ -5019,7 +5047,7 @@ chosen as if the input file were named @file{@var{prefix}.y}. @deffn {Directive} %language "@var{language}" Specify the programming language for the generated parser. Currently -supported languages include C and C++. +supported languages include C, C++, and Java. @var{language} is case-insensitive. @end deffn @@ -5281,6 +5309,9 @@ exp: @dots{} @{ @dots{}; *randomness += 1; @dots{} @} @section The Push Parser Function @code{yypush_parse} @findex yypush_parse +(The current push parsing interface is experimental and may evolve. +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. @@ -5296,6 +5327,9 @@ is required to finish parsing the grammar. @section The Pull Parser Function @code{yypull_parse} @findex yypull_parse +(The current push parsing interface is experimental and may evolve. +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"} declaration is used. @@ -5309,6 +5343,9 @@ The value returned by @code{yypull_parse} is the same as for @code{yyparse}. @section The Parser Create Function @code{yystate_new} @findex yypstate_new +(The current push parsing interface is experimental and may evolve. +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. @@ -5316,13 +5353,18 @@ This function is available if either the @code{%define api.push_pull "push"} or @deftypefun yypstate *yypstate_new (void) The fuction will return a valid parser instance if there was memory available -or NULL if no memory was available. +or 0 if no memory was available. +In impure mode, it will also return 0 if a parser instance is currently +allocated. @end deftypefun @node Parser Delete Function @section The Parser Delete Function @code{yystate_delete} @findex yypstate_delete +(The current push parsing interface is experimental and may evolve. +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. @@ -7197,14 +7239,14 @@ State 11 conflicts: 4 shift/reduce The next section reports useless tokens, nonterminal and rules. Useless nonterminals and rules are removed in order to produce a smaller parser, but useless tokens are preserved, since they might be used by the -scanner (note the difference between ``useless'' and ``not used'' +scanner (note the difference between ``useless'' and ``unused'' below): @example -Useless nonterminals: +Nonterminals useless in grammar: useless -Terminals which are not used: +Terminals unused in grammar: STR Rules useless in grammar: @@ -7734,6 +7776,46 @@ traditional Yacc grammars. If your grammar uses a Bison extension like @samp{%glr-parser}, Bison might not be Yacc-compatible even if this option is specified. +@item -W +@itemx --warnings +Output warnings falling in @var{category}. @var{category} can be one +of: +@table @code +@item midrule-values +Warn about mid-rule values that are set but not used within any of the actions +of the parent rule. +For example, warn about unused @code{$2} in: + +@example +exp: '1' @{ $$ = 1; @} '+' exp @{ $$ = $1 + $4; @}; +@end example + +Also warn about mid-rule values that are used but not set. +For example, warn about unset @code{$$} in the mid-rule action in: + +@example + exp: '1' @{ $1 = 1; @} '+' exp @{ $$ = $2 + $4; @}; +@end example + +These warnings are not enabled by default since they sometimes prove to +be false alarms in existing grammars employing the Yacc constructs +@code{$0} or @code{$-@var{n}} (where @var{n} is some positive integer). + + +@item yacc +Incompatibilities with @acronym{POSIX} Yacc. + +@item all +All the warnings. +@item none +Turn off all the warnings. +@item error +Treat warnings as errors. +@end table + +A category can be turned off by prefixing its name with @samp{no-}. For +instance, @option{-Wno-syntax} will hide the warnings about unused +variables. @end table @noindent @@ -7750,7 +7832,7 @@ already defined, so that the debugging facilities are compiled. @itemx --language=@var{language} Specify the programming language for the generated parser, as if @code{%language} was specified (@pxref{Decl Summary, , Bison Declaration -Summary}). Currently supported languages include C and C++. +Summary}). Currently supported languages include C, C++, and Java. @var{language} is case-insensitive. @item --locations @@ -7794,14 +7876,15 @@ Pretend that @code{%token-table} was specified. @xref{Decl Summary}. Adjust the output: @table @option -@item -d -@itemx --defines +@item --defines[=@var{file}] Pretend that @code{%defines} was specified, i.e., write an extra output file containing macro definitions for the token type names defined in the grammar, as well as a few other declarations. @xref{Decl Summary}. -@item --defines=@var{defines-file} -Same as above, but save in the file @var{defines-file}. +@item -d +This is the same as @code{--defines} except @code{-d} does not accept a +@var{file} argument since POSIX Yacc requires that @code{-d} can be bundled +with other short options. @item -b @var{file-prefix} @itemx --file-prefix=@var{prefix} @@ -7827,6 +7910,9 @@ Implies @code{state} and augments the description of the automaton with the full set of items for each state, instead of its core only. @end table +@item --report-file=@var{file} +Specify the @var{file} for the verbose description. + @item -v @itemx --verbose Pretend that @code{%verbose} was specified, i.e., write an extra output @@ -7840,17 +7926,23 @@ Specify the @var{file} for the parser file. The other output files' names are constructed from @var{file} as described under the @samp{-v} and @samp{-d} options. -@item -g +@item -g[@var{file}] +@itemx --graph[=@var{file}] Output a graphical representation of the @acronym{LALR}(1) grammar automaton computed by Bison, in @uref{http://www.graphviz.org/, Graphviz} @uref{http://www.graphviz.org/doc/info/lang.html, @acronym{DOT}} format. -If the grammar file is @file{foo.y}, the output file will -be @file{foo.dot}. - -@item --graph=@var{graph-file} -The behavior of @var{--graph} is the same than @samp{-g}. The only -difference is that it has an optional argument which is the name of -the output graph file. +@code{@var{file}} is optional. +If omitted and the grammar file is @file{foo.y}, the output file will be +@file{foo.dot}. + +@item -x[@var{file}] +@itemx --xml[=@var{file}] +Output an XML report of the @acronym{LALR}(1) automaton computed by Bison. +@code{@var{file}} is optional. +If omitted and the grammar file is @file{foo.y}, the output file will be +@file{foo.xml}. +(The current XML schema is experimental and may evolve. +More user feedback will help to stabilize it.) @end table @node Option Cross Key @@ -8641,6 +8733,9 @@ main (int argc, char *argv[]) @c - %language "Java" @c - initial action +(The current Java interface is experimental and may evolve. +More user feedback will help to stabilize it.) + The Java parser skeletons are selected using a language directive, @samp{%language "Java"}, or the synonymous command-line option @option{--language=java}. @@ -8652,9 +8747,9 @@ in an arbitrary Java package using a @samp{%define package} section. The parser class defines an inner class, @code{Location}, that is used for location tracking. If the parser is pure, it also defines an -inner interface, @code{Lexer}; see~@ref{Java Scanner Interface} for the +inner interface, @code{Lexer}; see @ref{Java Scanner Interface} for the meaning of pure parsers when the Java language is chosen. Other than -these inner class/interface, and the members described in~@ref{Java +these inner class/interface, and the members described in @ref{Java Parser Interface}, all the other members and fields are preceded with a @code{yy} prefix to avoid clashes with user code. @@ -8809,9 +8904,14 @@ 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} directive does not do anything when used in Java. +@c FIXME: But a bit farther it is stated that +@c If @code{%pure-parser} is not specified, the lexer interface +@c resides in the same class (@code{YYParser}) as the Bison-generated +@c parser. The fields and methods that are provided to +@c this end are as follows. The scanner always resides in a separate class than the parser. -Still, Java also two possible ways to interface a Bison-generated Java +Still, there are two possible ways to interface a Bison-generated Java parser with a scanner, that is, the scanner may reside in a separate file than the Bison grammar, or in the same file. The interface to the scanner is similar in the two cases. @@ -8822,7 +8922,7 @@ to pass parameters from the parser constructor to the scanner constructor, specify them with @code{%lex-param}; they are passed before @code{%parse-param}s to the constructor. -In the second case, the scanner has to implement interface @code{Lexer}, +In the second case, the scanner has to implement the @code{Lexer} interface, which is defined within the parser class (e.g., @code{YYParser.Lexer}). The constructor of the parser object will then accept an object implementing the interface; @code{%lex-param} is not used in this @@ -8855,8 +8955,7 @@ The return type can be changed using @samp{%define "position_type" @end deftypemethod @deftypemethod {Lexer} {Object} getLVal () -Return respectively the first position of the last token that yylex -returned, and the first position beyond it. +Return the semantical value of the last token that yylex returned. The return type can be changed using @samp{%define "stype" "@var{class-name}".} @@ -8868,7 +8967,7 @@ Bison-generated parser. The fields and methods that are provided to this end are as follows. @deftypemethod {YYParser} {void} error (Location @var{l}, String @var{m}) -As explained in @pxref{Java Parser Interface}, this method is defined +As already explained (@pxref{Java Parser Interface}), this method is defined by the user to emit an error message. The first parameter is not used unless location tracking is active. Its type can be changed using @samp{%define "location_type" "@var{class-name}".} @@ -9753,6 +9852,8 @@ The function to delete a parser instance, produced by Bison in push mode; call this function to delete the memory associated with a parser. @xref{Parser Delete Function, ,The Parser Delete Function @code{yypstate_delete}}. +(The current push parsing interface is experimental and may evolve. +More user feedback will help to stabilize it.) @end deffn @deffn {Function} yypstate_new @@ -9760,6 +9861,8 @@ The function to create a parser instance, produced by Bison in push mode; call this function to create a new parser. @xref{Parser Create Function, ,The Parser Create Function @code{yypstate_new}}. +(The current push parsing interface is experimental and may evolve. +More user feedback will help to stabilize it.) @end deffn @deffn {Function} yypull_parse @@ -9767,12 +9870,16 @@ The parser function produced by Bison in push mode; call this function to parse the rest of the input stream. @xref{Pull Parser Function, ,The Pull Parser Function @code{yypull_parse}}. +(The current push parsing interface is experimental and may evolve. +More user feedback will help to stabilize it.) @end deffn @deffn {Function} yypush_parse The parser function produced by Bison in push mode; call this function to parse a single token. @xref{Push Parser Function, ,The Push Parser Function @code{yypush_parse}}. +(The current push parsing interface is experimental and may evolve. +More user feedback will help to stabilize it.) @end deffn @deffn {Macro} YYPARSE_PARAM