X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/333e670c857bff3b9354f61a572edaa0e25ac695..7bd1665a866352f3c1ef800e907e5357f72ff94a:/doc/bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index d513b555..b6a98f9d 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -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