* NEWS (2.3b+): New section, empty for now.

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 9d0da773eb75ebef0bc91b66f03ade79f5beddf0..b6a98f9db3c2fb7a0ed58a97950c7a3200a43d6e 100644 (file)
--- 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,
 @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
 
 @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) 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
 
 @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
 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
 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}).
 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
 
 @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.
 
 @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
 @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
 
 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
 @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
 
 @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.
 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}.
 
 @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"}
 
 
 @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
 
 @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
 
 @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
 
 @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.
 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
 
 @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.
 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
 
 @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.
 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
 
 @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
 
 @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.
 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
 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
 below):
 
 @example

-Useless nonterminals:
+Nonterminals useless in grammar:

    useless
 
    useless
 

-Terminals which are not used:
+Terminals unused in grammar:

    STR
 
 Rules useless 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.
 
 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
 @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
 @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
 @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
 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}.
 
 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}
 
 @item -b @var{file-prefix}
 @itemx --file-prefix=@var{prefix}


@@ -7843,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.
 
 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.
 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
 @end table
 
 @node Option Cross Key


@@ -8644,6 +8733,9 @@ main (int argc, char *argv[])
 @c - %language "Java"
 @c - initial action
 
 @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}.
 The Java parser skeletons are selected using a language directive,
 @samp{%language "Java"}, or the synonymous command-line option
 @option{--language=java}.


@@ -8655,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
 
 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
 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.
 
 Parser Interface}, all the other members and fields are preceded
 with a @code{yy} prefix to avoid clashes with user code.
 


@@ -8812,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.
 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.
 
 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.
 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.


@@ -8825,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.
 
 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
 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


@@ -8858,8 +8955,7 @@ The return type can be changed using @samp{%define "position_type"
 @end deftypemethod
 
 @deftypemethod {Lexer} {Object} getLVal ()
 @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}".}
 
 The return type can be changed using @samp{%define "stype"
 "@var{class-name}".}


@@ -8871,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})
 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}".}
 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}".}


@@ -9756,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}}.
 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
 @end deffn
 
 @deffn {Function} yypstate_new


@@ -9763,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}}.
 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
 @end deffn
 
 @deffn {Function} yypull_parse


@@ -9770,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}}.
 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}}.
 @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
 @end deffn
 
 @deffn {Macro} YYPARSE_PARAM