* NEWS (2.3a+): Don't say %language is experimental. Mention Java and

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 8268783f5dbcce0b50ca2fa924a0522cc1358cc3..1f15f825b71ae2fcfba85c5521bf8fde3ce16529 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:


@@ -7750,7 +7792,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


@@ -7827,6 +7869,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
 
 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
 @item -v
 @itemx --verbose
 Pretend that @code{%verbose} was specified, i.e., write an extra output


@@ -7848,9 +7893,18 @@ If the grammar file is @file{foo.y}, the output file will
 be @file{foo.dot}.
 
 @item --graph=@var{graph-file}
 be @file{foo.dot}.
 
 @item --graph=@var{graph-file}

-The behavior of @var{--graph} is the same than @samp{-g}.  The only
+The behavior of @var{--graph} is the same as @samp{-g}.  The only

 difference is that it has an optional argument which is the name of
 the output graph file.
 difference is that it has an optional argument which is the name of
 the output graph file.

+
+@item -x
+@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


@@ -8641,6 +8695,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}.


@@ -9753,6 +9810,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


@@ -9760,6 +9819,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


@@ -9767,12 +9828,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