@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
(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
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
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
@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
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
@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.
@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"}
@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
@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.
@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.
@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.
@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.
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:
@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
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
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.
+
+@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
@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}.
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
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
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
projects / bison.git / blobdiff