@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"}
@item Caveats:
@itemize @bullet
-@item Unreachable states may contain conflicts and may reduce rules not
-reduced in any other state.
+
+@item Unreachable states may contain conflicts and may use rules not used in
+any other state.
Thus, keeping unreachable states may induce warnings that are irrelevant to
your parser's behavior, and it may eliminate warnings that are relevant.
Of course, the change in warnings may actually be relevant to a parser table
@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.
@command{bison} reports:
@example
-calc.y: warning: 1 useless nonterminal and 1 useless rule
-calc.y:11.1-7: warning: useless nonterminal: useless
-calc.y:11.10-12: warning: useless rule: useless: STR
+calc.y: warning: 1 nonterminal and 1 rule useless in grammar
+calc.y:11.1-7: warning: nonterminal useless in grammar: useless
+calc.y:11.10-12: warning: rule useless in grammar: useless: STR
calc.y: conflicts: 7 shift/reduce
@end example
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
-Useless rules:
+Rules useless in grammar:
#6 useless: STR;
@end example
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
@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
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}
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
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
@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 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.
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.
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
@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 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}".}
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