X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/333e670c857bff3b9354f61a572edaa0e25ac695..cae5057f472945d5947cffbc39d56ee7c6995357:/doc/bison.texinfo diff --git a/doc/bison.texinfo b/doc/bison.texinfo index d513b555..5b023fa9 100644 --- a/doc/bison.texinfo +++ b/doc/bison.texinfo @@ -30,8 +30,8 @@ @copying -This manual is for @acronym{GNU} Bison (version @value{VERSION}, -@value{UPDATED}), the @acronym{GNU} parser generator. +This manual (@value{UPDATED}) is for @acronym{GNU} Bison (version +@value{VERSION}), the @acronym{GNU} parser generator. Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software @@ -4553,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. @@ -4882,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"} @@ -5042,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 @@ -5304,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. @@ -5319,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. @@ -5332,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. @@ -5348,6 +5362,9 @@ allocated. @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. @@ -7759,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 @@ -7775,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 @@ -7819,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} @@ -7868,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 @@ -8669,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}. @@ -8680,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. @@ -8837,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. @@ -8850,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 @@ -8883,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}".} @@ -8896,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}".} @@ -9781,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 @@ -9788,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 @@ -9795,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