+int
+calcxx_driver::parse (const std::string &f)
+@{
+ file = f;
+ scan_begin ();
+ yy::calcxx_parser parser (*this);
+ parser.set_debug_level (trace_parsing);
+ int res = parser.parse ();
+ scan_end ();
+ return res;
+@}
+
+void
+calcxx_driver::error (const yy::location& l, const std::string& m)
+@{
+ std::cerr << l << ": " << m << std::endl;
+@}
+
+void
+calcxx_driver::error (const std::string& m)
+@{
+ std::cerr << m << std::endl;
+@}
+@end example
+
+@node Calc++ Parser
+@subsubsection Calc++ Parser
+
+The parser definition file @file{calc++-parser.yy} starts by asking for
+the C++ LALR(1) skeleton, the creation of the parser header file, and
+specifies the name of the parser class. Because the C++ skeleton
+changed several times, it is safer to require the version you designed
+the grammar for.
+
+@comment file: calc++-parser.yy
+@example
+%skeleton "lalr1.cc" /* -*- C++ -*- */
+%require "@value{VERSION}"
+%defines
+%define parser_class_name "calcxx_parser"
+@end example
+
+@noindent
+@findex %code requires
+Then come the declarations/inclusions needed to define the
+@code{%union}. Because the parser uses the parsing driver and
+reciprocally, both cannot include the header of the other. Because the
+driver's header needs detailed knowledge about the parser class (in
+particular its inner types), it is the parser's header which will simply
+use a forward declaration of the driver.
+@xref{Decl Summary, ,%code}.
+
+@comment file: calc++-parser.yy
+@example
+%code requires @{
+# include <string>
+class calcxx_driver;
+@}
+@end example
+
+@noindent
+The driver is passed by reference to the parser and to the scanner.
+This provides a simple but effective pure interface, not relying on
+global variables.
+
+@comment file: calc++-parser.yy
+@example
+// The parsing context.
+%parse-param @{ calcxx_driver& driver @}
+%lex-param @{ calcxx_driver& driver @}
+@end example
+
+@noindent
+Then we request the location tracking feature, and initialize the
+first location's file name. Afterwards new locations are computed
+relatively to the previous locations: the file name will be
+automatically propagated.
+
+@comment file: calc++-parser.yy
+@example
+%locations
+%initial-action
+@{
+ // Initialize the initial location.
+ @@$.begin.filename = @@$.end.filename = &driver.file;
+@};
+@end example
+
+@noindent
+Use the two following directives to enable parser tracing and verbose
+error messages.
+
+@comment file: calc++-parser.yy
+@example
+%debug
+%error-verbose
+@end example
+
+@noindent
+Semantic values cannot use ``real'' objects, but only pointers to
+them.
+
+@comment file: calc++-parser.yy
+@example
+// Symbols.
+%union
+@{
+ int ival;
+ std::string *sval;
+@};
+@end example
+
+@noindent
+@findex %code
+The code between @samp{%code @{} and @samp{@}} is output in the
+@file{*.cc} file; it needs detailed knowledge about the driver.
+
+@comment file: calc++-parser.yy
+@example
+%code @{
+# include "calc++-driver.hh"
+@}
+@end example
+
+
+@noindent
+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''. Similarly user friendly named are provided for each
+symbol. Note that the tokens names are prefixed by @code{TOKEN_} to
+avoid name clashes.
+
+@comment file: calc++-parser.yy
+@example
+%token END 0 "end of file"
+%token ASSIGN ":="
+%token <sval> IDENTIFIER "identifier"
+%token <ival> NUMBER "number"
+%type <ival> exp
+@end example
+
+@noindent
+To enable memory deallocation during error recovery, use
+@code{%destructor}.
+
+@c FIXME: Document %printer, and mention that it takes a braced-code operand.
+@comment file: calc++-parser.yy
+@example
+%printer @{ debug_stream () << *$$; @} "identifier"
+%destructor @{ delete $$; @} "identifier"
+
+%printer @{ debug_stream () << $$; @} <ival>
+@end example
+
+@noindent
+The grammar itself is straightforward.
+
+@comment file: calc++-parser.yy
+@example
+%%
+%start unit;
+unit: assignments exp @{ driver.result = $2; @};
+
+assignments: assignments assignment @{@}
+ | /* Nothing. */ @{@};
+
+assignment:
+ "identifier" ":=" exp
+ @{ driver.variables[*$1] = $3; delete $1; @};
+
+%left '+' '-';
+%left '*' '/';
+exp: exp '+' exp @{ $$ = $1 + $3; @}
+ | exp '-' exp @{ $$ = $1 - $3; @}
+ | exp '*' exp @{ $$ = $1 * $3; @}
+ | exp '/' exp @{ $$ = $1 / $3; @}
+ | "identifier" @{ $$ = driver.variables[*$1]; delete $1; @}
+ | "number" @{ $$ = $1; @};
+%%
+@end example
+
+@noindent
+Finally the @code{error} member function registers the errors to the
+driver.
+
+@comment file: calc++-parser.yy
+@example
+void
+yy::calcxx_parser::error (const yy::calcxx_parser::location_type& l,
+ const std::string& m)
+@{
+ driver.error (l, m);
+@}
+@end example
+
+@node Calc++ Scanner
+@subsubsection Calc++ Scanner
+
+The Flex scanner first includes the driver declaration, then the
+parser's to get the set of defined tokens.
+
+@comment file: calc++-scanner.ll
+@example
+%@{ /* -*- C++ -*- */
+# include <cstdlib>
+# include <errno.h>
+# include <limits.h>
+# include <string>
+# include "calc++-driver.hh"
+# include "calc++-parser.hh"
+
+/* Work around an incompatibility in flex (at least versions
+ 2.5.31 through 2.5.33): it generates code that does
+ not conform to C89. See Debian bug 333231
+ <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=333231>. */
+# undef yywrap
+# define yywrap() 1
+
+/* By default yylex returns int, we use token_type.
+ Unfortunately yyterminate by default returns 0, which is
+ not of token_type. */
+#define yyterminate() return token::END
+%@}
+@end example
+
+@noindent
+Because there is no @code{#include}-like feature we don't need
+@code{yywrap}, we don't need @code{unput} either, and we parse an
+actual file, this is not an interactive session with the user.
+Finally we enable the scanner tracing features.
+
+@comment file: calc++-scanner.ll
+@example
+%option noyywrap nounput batch debug
+@end example
+
+@noindent
+Abbreviations allow for more readable rules.
+
+@comment file: calc++-scanner.ll
+@example
+id [a-zA-Z][a-zA-Z_0-9]*
+int [0-9]+
+blank [ \t]
+@end example
+
+@noindent
+The following paragraph suffices to track locations accurately. Each
+time @code{yylex} is invoked, the begin position is moved onto the end
+position. Then when a pattern is matched, the end position is
+advanced of its width. In case it matched ends of lines, the end
+cursor is adjusted, and each time blanks are matched, the begin cursor
+is moved onto the end cursor to effectively ignore the blanks
+preceding tokens. Comments would be treated equally.
+
+@comment file: calc++-scanner.ll
+@example
+%@{
+# define YY_USER_ACTION yylloc->columns (yyleng);
+%@}
+%%
+%@{
+ yylloc->step ();
+%@}
+@{blank@}+ yylloc->step ();
+[\n]+ yylloc->lines (yyleng); yylloc->step ();
+@end example
+
+@noindent
+The rules are simple, just note the use of the driver to report errors.
+It is convenient to use a typedef to shorten
+@code{yy::calcxx_parser::token::identifier} into
+@code{token::identifier} for instance.
+
+@comment file: calc++-scanner.ll
+@example
+%@{
+ typedef yy::calcxx_parser::token token;
+%@}
+ /* Convert ints to the actual type of tokens. */
+[-+*/] return yy::calcxx_parser::token_type (yytext[0]);
+":=" return token::ASSIGN;
+@{int@} @{
+ errno = 0;
+ long n = strtol (yytext, NULL, 10);
+ if (! (INT_MIN <= n && n <= INT_MAX && errno != ERANGE))
+ driver.error (*yylloc, "integer is out of range");
+ yylval->ival = n;
+ return token::NUMBER;
+@}
+@{id@} yylval->sval = new std::string (yytext); return token::IDENTIFIER;
+. driver.error (*yylloc, "invalid character");
+%%
+@end example
+
+@noindent
+Finally, because the scanner related driver's member function depend
+on the scanner's data, it is simpler to implement them in this file.
+
+@comment file: calc++-scanner.ll
+@example
+void
+calcxx_driver::scan_begin ()
+@{
+ yy_flex_debug = trace_scanning;
+ if (file == "-")
+ yyin = stdin;
+ else if (!(yyin = fopen (file.c_str (), "r")))
+ @{
+ error (std::string ("cannot open ") + file);
+ exit (1);
+ @}
+@}
+
+void
+calcxx_driver::scan_end ()
+@{
+ fclose (yyin);
+@}
+@end example
+
+@node Calc++ Top Level
+@subsubsection Calc++ Top Level
+
+The top level file, @file{calc++.cc}, poses no problem.
+
+@comment file: calc++.cc
+@example
+#include <iostream>
+#include "calc++-driver.hh"
+
+int
+main (int argc, char *argv[])
+@{
+ calcxx_driver driver;
+ for (++argv; argv[0]; ++argv)
+ if (*argv == std::string ("-p"))
+ driver.trace_parsing = true;
+ else if (*argv == std::string ("-s"))
+ driver.trace_scanning = true;
+ else if (!driver.parse (*argv))
+ std::cout << driver.result << std::endl;
+@}
+@end example
+
+@node Java Parsers
+@section Java Parsers
+
+@menu
+* Java Bison Interface:: Asking for Java parser generation
+* Java Semantic Values:: %type and %token vs. Java
+* Java Location Values:: The position and location classes
+* Java Parser Interface:: Instantiating and running the parser
+* Java Scanner Interface:: Specifying the scanner for the parser
+* Java Action Features:: Special features for use in actions.
+* Java Differences:: Differences between C/C++ and Java Grammars
+* Java Declarations Summary:: List of Bison declarations used with Java
+@end menu
+
+@node Java Bison Interface
+@subsection Java Bison Interface
+@c - %language "Java"
+
+(The current Java interface is experimental and may evolve.
+More user feedback will help to stabilize it.)
+
+The Java parser skeletons are selected using the @code{%language "Java"}
+directive or the @option{-L java}/@option{--language=java} option.
+
+@c FIXME: Documented bug.
+When generating a Java parser, @code{bison @var{basename}.y} will create
+a single Java source file named @file{@var{basename}.java}. Using an
+input file without a @file{.y} suffix is currently broken. The basename
+of the output file can be changed by the @code{%file-prefix} directive
+or the @option{-p}/@option{--name-prefix} option. The entire output file
+name can be changed by the @code{%output} directive or the
+@option{-o}/@option{--output} option. The output file contains a single
+class for the parser.
+
+You can create documentation for generated parsers using Javadoc.
+
+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}
+and @code{%define api.pure} directives does not do anything when used in
+Java.
+
+Push parsers are currently unsupported in Java and @code{%define
+api.push_pull} have no effect.
+
+@acronym{GLR} parsers are currently unsupported in Java. Do not use the
+@code{glr-parser} directive.
+
+No header file can be generated for Java parsers. Do not use the
+@code{%defines} directive or the @option{-d}/@option{--defines} options.
+
+@c FIXME: Possible code change.
+Currently, support for debugging and verbose errors are always compiled
+in. Thus the @code{%debug} and @code{%token-table} directives and the
+@option{-t}/@option{--debug} and @option{-k}/@option{--token-table}
+options have no effect. This may change in the future to eliminate
+unused code in the generated parser, so use @code{%debug} and
+@code{%verbose-error} explicitly if needed. Also, in the future the
+@code{%token-table} directive might enable a public interface to
+access the token names and codes.
+
+@node Java Semantic Values
+@subsection Java Semantic Values
+@c - No %union, specify type in %type/%token.
+@c - YYSTYPE
+@c - Printer and destructor
+
+There is no @code{%union} directive in Java parsers. Instead, the
+semantic values' types (class names) should be specified in the
+@code{%type} or @code{%token} directive:
+
+@example
+%type <Expression> expr assignment_expr term factor
+%type <Integer> number
+@end example
+
+By default, the semantic stack is declared to have @code{Object} members,
+which means that the class types you specify can be of any class.
+To improve the type safety of the parser, you can declare the common
+superclass of all the semantic values using the @code{%define stype}
+directive. For example, after the following declaration:
+
+@example
+%define stype "ASTNode"
+@end example
+
+@noindent
+any @code{%type} or @code{%token} specifying a semantic type which
+is not a subclass of ASTNode, will cause a compile-time error.
+
+@c FIXME: Documented bug.
+Types used in the directives may be qualified with a package name.
+Primitive data types are accepted for Java version 1.5 or later. Note
+that in this case the autoboxing feature of Java 1.5 will be used.
+Generic types may not be used; this is due to a limitation in the
+implementation of Bison, and may change in future releases.
+
+Java parsers do not support @code{%destructor}, since the language
+adopts garbage collection. The parser will try to hold references
+to semantic values for as little time as needed.
+
+Java parsers do not support @code{%printer}, as @code{toString()}
+can be used to print the semantic values. This however may change
+(in a backwards-compatible way) in future versions of Bison.
+
+
+@node Java Location Values
+@subsection Java Location Values
+@c - %locations
+@c - class Position
+@c - class Location
+
+When the directive @code{%locations} is used, the Java parser
+supports location tracking, see @ref{Locations, , Locations Overview}.
+An auxiliary user-defined class defines a @dfn{position}, a single point
+in a file; Bison itself defines a class representing a @dfn{location},
+a range composed of a pair of positions (possibly spanning several
+files). The location class is an inner class of the parser; the name
+is @code{Location} by default, and may also be renamed using
+@code{%define location_type "@var{class-name}}.
+
+The location class treats the position as a completely opaque value.
+By default, the class name is @code{Position}, but this can be changed
+with @code{%define position_type "@var{class-name}"}. This class must
+be supplied by the user.
+
+
+@deftypeivar {Location} {Position} begin
+@deftypeivarx {Location} {Position} end
+The first, inclusive, position of the range, and the first beyond.
+@end deftypeivar
+
+@deftypeop {Constructor} {Location} {} Location (Position @var{loc})
+Create a @code{Location} denoting an empty range located at a given point.
+@end deftypeop
+
+@deftypeop {Constructor} {Location} {} Location (Position @var{begin}, Position @var{end})
+Create a @code{Location} from the endpoints of the range.
+@end deftypeop
+
+@deftypemethod {Location} {String} toString ()
+Prints the range represented by the location. For this to work
+properly, the position class should override the @code{equals} and
+@code{toString} methods appropriately.
+@end deftypemethod
+
+
+@node Java Parser Interface
+@subsection Java Parser Interface
+@c - define parser_class_name
+@c - Ctor
+@c - parse, error, set_debug_level, debug_level, set_debug_stream,
+@c debug_stream.
+@c - Reporting errors
+
+The name of the generated parser class defaults to @code{YYParser}. The
+@code{YY} prefix may be changed using the @code{%name-prefix} directive
+or the @option{-p}/@option{--name-prefix} option. Alternatively, use
+@code{%define parser_class_name "@var{name}"} to give a custom name to
+the class. The interface of this class is detailed below.
+
+By default, the parser class has package visibility. A declaration
+@code{%define public} will change to public visibility. Remember that,
+according to the Java language specification, the name of the @file{.java}
+file should match the name of the class in this case. Similarly, you can
+use @code{abstract}, @code{final} and @code{strictfp} with the
+@code{%define} declaration to add other modifiers to the parser class.
+
+The Java package name of the parser class can be specified using the
+@code{%define package} directive. The superclass and the implemented
+interfaces of the parser class can be specified with the @code{%define
+extends} and @code{%define implements} directives.
+
+The parser class defines an inner class, @code{Location}, that is used
+for location tracking (see @ref{Java Location Values}), and a inner
+interface, @code{Lexer} (see @ref{Java Scanner Interface}). Other than
+these inner class/interface, and the members described in the interface
+below, all the other members and fields are preceded with a @code{yy} or
+@code{YY} prefix to avoid clashes with user code.
+
+@c FIXME: The following constants and variables are still undocumented:
+@c @code{bisonVersion}, @code{bisonSkeleton} and @code{errorVerbose}.
+
+The parser class can be extended using the @code{%parse-param}
+directive. Each occurrence of the directive will add a @code{protected
+final} field to the parser class, and an argument to its constructor,
+which initialize them automatically.
+
+Token names defined by @code{%token} and the predefined @code{EOF} token
+name are added as constant fields to the parser class.
+
+@deftypeop {Constructor} {YYParser} {} YYParser (@var{lex_param}, @dots{}, @var{parse_param}, @dots{})
+Build a new parser object with embedded @code{%code lexer}. There are
+no parameters, unless @code{%parse-param}s and/or @code{%lex-param}s are
+used.
+@end deftypeop
+
+@deftypeop {Constructor} {YYParser} {} YYParser (Lexer @var{lexer}, @var{parse_param}, @dots{})
+Build a new parser object using the specified scanner. There are no
+additional parameters unless @code{%parse-param}s are used.
+
+If the scanner is defined by @code{%code lexer}, this constructor is
+declared @code{protected} and is called automatically with a scanner
+created with the correct @code{%lex-param}s.
+@end deftypeop
+
+@deftypemethod {YYParser} {boolean} parse ()
+Run the syntactic analysis, and return @code{true} on success,
+@code{false} otherwise.
+@end deftypemethod
+
+@deftypemethod {YYParser} {boolean} recovering ()
+During the syntactic analysis, return @code{true} if recovering
+from a syntax error.
+@xref{Error Recovery}.
+@end deftypemethod
+
+@deftypemethod {YYParser} {java.io.PrintStream} getDebugStream ()
+@deftypemethodx {YYParser} {void} setDebugStream (java.io.printStream @var{o})
+Get or set the stream used for tracing the parsing. It defaults to
+@code{System.err}.
+@end deftypemethod
+
+@deftypemethod {YYParser} {int} getDebugLevel ()
+@deftypemethodx {YYParser} {void} setDebugLevel (int @var{l})
+Get or set the tracing level. Currently its value is either 0, no trace,
+or nonzero, full tracing.
+@end deftypemethod
+
+
+@node Java Scanner Interface
+@subsection Java Scanner Interface
+@c - %code lexer
+@c - %lex-param
+@c - Lexer interface
+
+There are two possible ways to interface a Bison-generated Java parser
+with a scanner: the scanner may be defined by @code{%code lexer}, or
+defined elsewhere. In either case, the scanner has to implement the
+@code{Lexer} inner interface of the parser class.
+
+In the first case, the body of the scanner class is placed in
+@code{%code lexer} blocks. If you want 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 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
+case.
+
+In both cases, the scanner has to implement the following methods.
+
+@deftypemethod {Lexer} {void} yyerror (Location @var{loc}, String @var{msg})
+This method is defined by the user to emit an error message. The first
+parameter is omitted if location tracking is not active. Its type can be
+changed using @code{%define location_type "@var{class-name}".}
+@end deftypemethod
+
+@deftypemethod {Lexer} {int} yylex ()
+Return the next token. Its type is the return value, its semantic
+value and location are saved and returned by the ther methods in the
+interface.
+
+Use @code{%define lex_throws} to specify any uncaught exceptions.
+Default is @code{java.io.IOException}.
+@end deftypemethod
+
+@deftypemethod {Lexer} {Position} getStartPos ()
+@deftypemethodx {Lexer} {Position} getEndPos ()
+Return respectively the first position of the last token that
+@code{yylex} returned, and the first position beyond it. These
+methods are not needed unless location tracking is active.
+
+The return type can be changed using @code{%define position_type
+"@var{class-name}".}
+@end deftypemethod
+
+@deftypemethod {Lexer} {Object} getLVal ()
+Return the semantical value of the last token that yylex returned.
+
+The return type can be changed using @code{%define stype
+"@var{class-name}".}
+@end deftypemethod
+
+
+@node Java Action Features
+@subsection Special Features for Use in Java Actions
+
+The following special constructs can be uses in Java actions.
+Other analogous C action features are currently unavailable for Java.
+
+Use @code{%define throws} to specify any uncaught exceptions from parser
+actions, and initial actions specified by @code{%initial-action}.
+
+@defvar $@var{n}
+The semantic value for the @var{n}th component of the current rule.
+This may not be assigned to.
+@xref{Java Semantic Values}.
+@end defvar
+
+@defvar $<@var{typealt}>@var{n}
+Like @code{$@var{n}} but specifies a alternative type @var{typealt}.
+@xref{Java Semantic Values}.
+@end defvar
+
+@defvar $$
+The semantic value for the grouping made by the current rule. As a
+value, this is in the base type (@code{Object} or as specified by
+@code{%define stype}) as in not cast to the declared subtype because
+casts are not allowed on the left-hand side of Java assignments.
+Use an explicit Java cast if the correct subtype is needed.
+@xref{Java Semantic Values}.
+@end defvar
+
+@defvar $<@var{typealt}>$
+Same as @code{$$} since Java always allow assigning to the base type.
+Perhaps we should use this and @code{$<>$} for the value and @code{$$}
+for setting the value but there is currently no easy way to distinguish
+these constructs.
+@xref{Java Semantic Values}.
+@end defvar
+
+@defvar @@@var{n}
+The location information of the @var{n}th component of the current rule.
+This may not be assigned to.
+@xref{Java Location Values}.
+@end defvar
+
+@defvar @@$
+The location information of the grouping made by the current rule.
+@xref{Java Location Values}.
+@end defvar
+
+@deffn {Statement} {return YYABORT;}
+Return immediately from the parser, indicating failure.
+@xref{Java Parser Interface}.
+@end deffn
+
+@deffn {Statement} {return YYACCEPT;}
+Return immediately from the parser, indicating success.
+@xref{Java Parser Interface}.
+@end deffn
+
+@deffn {Statement} {return YYERROR;}
+Start error recovery without printing an error message.
+@xref{Error Recovery}.
+@end deffn
+
+@deffn {Statement} {return YYFAIL;}
+Print an error message and start error recovery.
+@xref{Error Recovery}.
+@end deffn
+
+@deftypefn {Function} {boolean} recovering ()
+Return whether error recovery is being done. In this state, the parser
+reads token until it reaches a known state, and then restarts normal
+operation.
+@xref{Error Recovery}.
+@end deftypefn
+
+@deftypefn {Function} {protected void} yyerror (String msg)
+@deftypefnx {Function} {protected void} yyerror (Position pos, String msg)
+@deftypefnx {Function} {protected void} yyerror (Location loc, String msg)
+Print an error message using the @code{yyerror} method of the scanner
+instance in use.
+@end deftypefn
+
+
+@node Java Differences
+@subsection Differences between C/C++ and Java Grammars
+
+The different structure of the Java language forces several differences
+between C/C++ grammars, and grammars designed for Java parsers. This
+section summarizes these differences.
+
+@itemize
+@item
+Java lacks a preprocessor, so the @code{YYERROR}, @code{YYACCEPT},
+@code{YYABORT} symbols (@pxref{Table of Symbols}) cannot obviously be
+macros. Instead, they should be preceded by @code{return} when they
+appear in an action. The actual definition of these symbols is
+opaque to the Bison grammar, and it might change in the future. The
+only meaningful operation that you can do, is to return them.
+See @pxref{Java Action Features}.
+
+Note that of these three symbols, only @code{YYACCEPT} and
+@code{YYABORT} will cause a return from the @code{yyparse}
+method@footnote{Java parsers include the actions in a separate
+method than @code{yyparse} in order to have an intuitive syntax that
+corresponds to these C macros.}.
+
+@item
+Java lacks unions, so @code{%union} has no effect. Instead, semantic
+values have a common base type: @code{Object} or as specified by
+@code{%define stype}. Angle backets on @code{%token}, @code{type},
+@code{$@var{n}} and @code{$$} specify subtypes rather than fields of
+an union. The type of @code{$$}, even with angle brackets, is the base
+type since Java casts are not allow on the left-hand side of assignments.
+Also, @code{$@var{n}} and @code{@@@var{n}} are not allowed on the
+left-hand side of assignments. See @pxref{Java Semantic Values} and
+@pxref{Java Action Features}.
+
+@item
+The prolog declarations have a different meaning than in C/C++ code.
+@table @asis
+@item @code{%code imports}
+blocks are placed at the beginning of the Java source code. They may
+include copyright notices. For a @code{package} declarations, it is
+suggested to use @code{%define package} instead.
+
+@item unqualified @code{%code}
+blocks are placed inside the parser class.
+
+@item @code{%code lexer}
+blocks, if specified, should include the implementation of the
+scanner. If there is no such block, the scanner can be any class
+that implements the appropriate interface (see @pxref{Java Scanner
+Interface}).
+@end table
+
+Other @code{%code} blocks are not supported in Java parsers.
+In particular, @code{%@{ @dots{} %@}} blocks should not be used
+and may give an error in future versions of Bison.
+
+The epilogue has the same meaning as in C/C++ code and it can
+be used to define other classes used by the parser @emph{outside}
+the parser class.
+@end itemize
+
+
+@node Java Declarations Summary
+@subsection Java Declarations Summary
+
+This summary only include declarations specific to Java or have special
+meaning when used in a Java parser.
+
+@deffn {Directive} {%language "Java"}
+Generate a Java class for the parser.
+@end deffn
+
+@deffn {Directive} %lex-param @{@var{type} @var{name}@}
+A parameter for the lexer class defined by @code{%code lexer}
+@emph{only}, added as parameters to the lexer constructor and the parser
+constructor that @emph{creates} a lexer. Default is none.
+@xref{Java Scanner Interface}.
+@end deffn
+
+@deffn {Directive} %name-prefix "@var{prefix}"
+The prefix of the parser class name @code{@var{prefix}Parser} if
+@code{%define parser_class_name} is not used. Default is @code{YY}.
+@xref{Java Bison Interface}.
+@end deffn
+
+@deffn {Directive} %parse-param @{@var{type} @var{name}@}
+A parameter for the parser class added as parameters to constructor(s)
+and as fields initialized by the constructor(s). Default is none.
+@xref{Java Parser Interface}.
+@end deffn
+
+@deffn {Directive} %token <@var{type}> @var{token} @dots{}
+Declare tokens. Note that the angle brackets enclose a Java @emph{type}.
+@xref{Java Semantic Values}.
+@end deffn
+
+@deffn {Directive} %type <@var{type}> @var{nonterminal} @dots{}
+Declare the type of nonterminals. Note that the angle brackets enclose
+a Java @emph{type}.
+@xref{Java Semantic Values}.
+@end deffn
+
+@deffn {Directive} %code @{ @var{code} @dots{} @}
+Code appended to the inside of the parser class.
+@xref{Java Differences}.
+@end deffn
+
+@deffn {Directive} {%code imports} @{ @var{code} @dots{} @}
+Code inserted just after the @code{package} declaration.
+@xref{Java Differences}.
+@end deffn
+
+@deffn {Directive} {%code lexer} @{ @var{code} @dots{} @}
+Code added to the body of a inner lexer class within the parser class.
+@xref{Java Scanner Interface}.
+@end deffn
+
+@deffn {Directive} %% @var{code} @dots{}
+Code (after the second @code{%%}) appended to the end of the file,
+@emph{outside} the parser class.
+@xref{Java Differences}.
+@end deffn
+
+@deffn {Directive} %@{ @var{code} @dots{} %@}
+Not supported. Use @code{%code import} instead.
+@xref{Java Differences}.
+@end deffn
+
+@deffn {Directive} {%define abstract}
+Whether the parser class is declared @code{abstract}. Default is false.
+@xref{Java Bison Interface}.
+@end deffn
+
+@deffn {Directive} {%define extends} "@var{superclass}"
+The superclass of the parser class. Default is none.
+@xref{Java Bison Interface}.
+@end deffn
+
+@deffn {Directive} {%define final}
+Whether the parser class is declared @code{final}. Default is false.
+@xref{Java Bison Interface}.
+@end deffn
+
+@deffn {Directive} {%define implements} "@var{interfaces}"
+The implemented interfaces of the parser class, a comma-separated list.
+Default is none.
+@xref{Java Bison Interface}.
+@end deffn
+
+@deffn {Directive} {%define lex_throws} "@var{exceptions}"
+The exceptions thrown by the @code{yylex} method of the lexer, a
+comma-separated list. Default is @code{java.io.IOException}.
+@xref{Java Scanner Interface}.
+@end deffn
+
+@deffn {Directive} {%define location_type} "@var{class}"
+The name of the class used for locations (a range between two
+positions). This class is generated as an inner class of the parser
+class by @command{bison}. Default is @code{Location}.
+@xref{Java Location Values}.
+@end deffn
+
+@deffn {Directive} {%define package} "@var{package}"
+The package to put the parser class in. Default is none.
+@xref{Java Bison Interface}.
+@end deffn
+
+@deffn {Directive} {%define parser_class_name} "@var{name}"
+The name of the parser class. Default is @code{YYParser} or
+@code{@var{name-prefix}Parser}.
+@xref{Java Bison Interface}.
+@end deffn
+
+@deffn {Directive} {%define position_type} "@var{class}"
+The name of the class used for positions. This class must be supplied by
+the user. Default is @code{Position}.
+@xref{Java Location Values}.
+@end deffn
+
+@deffn {Directive} {%define public}
+Whether the parser class is declared @code{public}. Default is false.
+@xref{Java Bison Interface}.
+@end deffn
+
+@deffn {Directive} {%define stype} "@var{class}"
+The base type of semantic values. Default is @code{Object}.
+@xref{Java Semantic Values}.
+@end deffn
+
+@deffn {Directive} {%define strictfp}
+Whether the parser class is declared @code{strictfp}. Default is false.
+@xref{Java Bison Interface}.
+@end deffn
+
+@deffn {Directive} {%define throws} "@var{exceptions}"
+The exceptions thrown by user-supplied parser actions and
+@code{%initial-action}, a comma-separated list. Default is none.
+@xref{Java Parser Interface}.
+@end deffn
+
+
+@c ================================================= FAQ
+
+@node FAQ
+@chapter Frequently Asked Questions
+@cindex frequently asked questions
+@cindex questions
+
+Several questions about Bison come up occasionally. Here some of them
+are addressed.
+
+@menu
+* Memory Exhausted:: Breaking the Stack Limits
+* How Can I Reset the Parser:: @code{yyparse} Keeps some State
+* Strings are Destroyed:: @code{yylval} Loses Track of Strings
+* Implementing Gotos/Loops:: Control Flow in the Calculator
+* Multiple start-symbols:: Factoring closely related grammars
+* Secure? Conform?:: Is Bison @acronym{POSIX} safe?
+* I can't build Bison:: Troubleshooting
+* Where can I find help?:: Troubleshouting
+* Bug Reports:: Troublereporting
+* More Languages:: Parsers in C++, Java, and so on
+* Beta Testing:: Experimenting development versions
+* Mailing Lists:: Meeting other Bison users
+@end menu
+
+@node Memory Exhausted
+@section Memory Exhausted
+
+@display
+My parser returns with error with a @samp{memory exhausted}
+message. What can I do?
+@end display
+
+This question is already addressed elsewhere, @xref{Recursion,
+,Recursive Rules}.
+
+@node How Can I Reset the Parser
+@section How Can I Reset the Parser
+
+The following phenomenon has several symptoms, resulting in the
+following typical questions:
+
+@display
+I invoke @code{yyparse} several times, and on correct input it works
+properly; but when a parse error is found, all the other calls fail
+too. How can I reset the error flag of @code{yyparse}?
+@end display
+
+@noindent
+or
+
+@display
+My parser includes support for an @samp{#include}-like feature, in
+which case I run @code{yyparse} from @code{yyparse}. This fails
+although I did specify @code{%define api.pure}.
+@end display
+
+These problems typically come not from Bison itself, but from
+Lex-generated scanners. Because these scanners use large buffers for
+speed, they might not notice a change of input file. As a
+demonstration, consider the following source file,
+@file{first-line.l}:
+
+@verbatim
+%{
+#include <stdio.h>
+#include <stdlib.h>
+%}
+%%
+.*\n ECHO; return 1;
+%%
+int
+yyparse (char const *file)
+{
+ yyin = fopen (file, "r");
+ if (!yyin)
+ exit (2);
+ /* One token only. */
+ yylex ();
+ if (fclose (yyin) != 0)
+ exit (3);
+ return 0;
+}
+
+int
+main (void)
+{
+ yyparse ("input");
+ yyparse ("input");
+ return 0;
+}
+@end verbatim
+
+@noindent
+If the file @file{input} contains
+
+@verbatim
+input:1: Hello,
+input:2: World!
+@end verbatim
+
+@noindent
+then instead of getting the first line twice, you get:
+
+@example
+$ @kbd{flex -ofirst-line.c first-line.l}
+$ @kbd{gcc -ofirst-line first-line.c -ll}
+$ @kbd{./first-line}
+input:1: Hello,
+input:2: World!
+@end example
+
+Therefore, whenever you change @code{yyin}, you must tell the
+Lex-generated scanner to discard its current buffer and switch to the
+new one. This depends upon your implementation of Lex; see its
+documentation for more. For Flex, it suffices to call
+@samp{YY_FLUSH_BUFFER} after each change to @code{yyin}. If your
+Flex-generated scanner needs to read from several input streams to
+handle features like include files, you might consider using Flex
+functions like @samp{yy_switch_to_buffer} that manipulate multiple
+input buffers.
+
+If your Flex-generated scanner uses start conditions (@pxref{Start
+conditions, , Start conditions, flex, The Flex Manual}), you might
+also want to reset the scanner's state, i.e., go back to the initial
+start condition, through a call to @samp{BEGIN (0)}.
+
+@node Strings are Destroyed
+@section Strings are Destroyed
+
+@display
+My parser seems to destroy old strings, or maybe it loses track of
+them. Instead of reporting @samp{"foo", "bar"}, it reports
+@samp{"bar", "bar"}, or even @samp{"foo\nbar", "bar"}.
+@end display
+
+This error is probably the single most frequent ``bug report'' sent to
+Bison lists, but is only concerned with a misunderstanding of the role
+of the scanner. Consider the following Lex code:
+
+@verbatim
+%{
+#include <stdio.h>
+char *yylval = NULL;
+%}
+%%
+.* yylval = yytext; return 1;
+\n /* IGNORE */
+%%
+int
+main ()
+{
+ /* Similar to using $1, $2 in a Bison action. */
+ char *fst = (yylex (), yylval);
+ char *snd = (yylex (), yylval);
+ printf ("\"%s\", \"%s\"\n", fst, snd);
+ return 0;
+}
+@end verbatim
+
+If you compile and run this code, you get:
+
+@example
+$ @kbd{flex -osplit-lines.c split-lines.l}
+$ @kbd{gcc -osplit-lines split-lines.c -ll}
+$ @kbd{printf 'one\ntwo\n' | ./split-lines}
+"one
+two", "two"
+@end example
+
+@noindent
+this is because @code{yytext} is a buffer provided for @emph{reading}
+in the action, but if you want to keep it, you have to duplicate it
+(e.g., using @code{strdup}). Note that the output may depend on how
+your implementation of Lex handles @code{yytext}. For instance, when
+given the Lex compatibility option @option{-l} (which triggers the
+option @samp{%array}) Flex generates a different behavior:
+
+@example
+$ @kbd{flex -l -osplit-lines.c split-lines.l}
+$ @kbd{gcc -osplit-lines split-lines.c -ll}
+$ @kbd{printf 'one\ntwo\n' | ./split-lines}
+"two", "two"
+@end example
+
+
+@node Implementing Gotos/Loops
+@section Implementing Gotos/Loops
+
+@display
+My simple calculator supports variables, assignments, and functions,
+but how can I implement gotos, or loops?
+@end display
+
+Although very pedagogical, the examples included in the document blur
+the distinction to make between the parser---whose job is to recover
+the structure of a text and to transmit it to subsequent modules of
+the program---and the processing (such as the execution) of this
+structure. This works well with so called straight line programs,
+i.e., precisely those that have a straightforward execution model:
+execute simple instructions one after the others.
+
+@cindex abstract syntax tree
+@cindex @acronym{AST}
+If you want a richer model, you will probably need to use the parser
+to construct a tree that does represent the structure it has
+recovered; this tree is usually called the @dfn{abstract syntax tree},
+or @dfn{@acronym{AST}} for short. Then, walking through this tree,
+traversing it in various ways, will enable treatments such as its
+execution or its translation, which will result in an interpreter or a
+compiler.
+
+This topic is way beyond the scope of this manual, and the reader is
+invited to consult the dedicated literature.
+
+
+@node Multiple start-symbols
+@section Multiple start-symbols
+
+@display
+I have several closely related grammars, and I would like to share their
+implementations. In fact, I could use a single grammar but with
+multiple entry points.
+@end display
+
+Bison does not support multiple start-symbols, but there is a very
+simple means to simulate them. If @code{foo} and @code{bar} are the two
+pseudo start-symbols, then introduce two new tokens, say
+@code{START_FOO} and @code{START_BAR}, and use them as switches from the
+real start-symbol:
+
+@example
+%token START_FOO START_BAR;
+%start start;
+start: START_FOO foo
+ | START_BAR bar;
+@end example
+
+These tokens prevents the introduction of new conflicts. As far as the
+parser goes, that is all that is needed.
+
+Now the difficult part is ensuring that the scanner will send these
+tokens first. If your scanner is hand-written, that should be
+straightforward. If your scanner is generated by Lex, them there is
+simple means to do it: recall that anything between @samp{%@{ ... %@}}
+after the first @code{%%} is copied verbatim in the top of the generated
+@code{yylex} function. Make sure a variable @code{start_token} is
+available in the scanner (e.g., a global variable or using
+@code{%lex-param} etc.), and use the following:
+
+@example
+ /* @r{Prologue.} */
+%%
+%@{
+ if (start_token)
+ @{
+ int t = start_token;
+ start_token = 0;
+ return t;
+ @}
+%@}
+ /* @r{The rules.} */
+@end example
+
+
+@node Secure? Conform?
+@section Secure? Conform?
+
+@display
+Is Bison secure? Does it conform to POSIX?
+@end display
+
+If you're looking for a guarantee or certification, we don't provide it.
+However, Bison is intended to be a reliable program that conforms to the
+@acronym{POSIX} specification for Yacc. If you run into problems,
+please send us a bug report.
+
+@node I can't build Bison
+@section I can't build Bison
+
+@display
+I can't build Bison because @command{make} complains that
+@code{msgfmt} is not found.
+What should I do?
+@end display
+
+Like most GNU packages with internationalization support, that feature
+is turned on by default. If you have problems building in the @file{po}
+subdirectory, it indicates that your system's internationalization
+support is lacking. You can re-configure Bison with
+@option{--disable-nls} to turn off this support, or you can install GNU
+gettext from @url{ftp://ftp.gnu.org/gnu/gettext/} and re-configure
+Bison. See the file @file{ABOUT-NLS} for more information.
+
+
+@node Where can I find help?
+@section Where can I find help?
+
+@display
+I'm having trouble using Bison. Where can I find help?
+@end display
+
+First, read this fine manual. Beyond that, you can send mail to
+@email{help-bison@@gnu.org}. This mailing list is intended to be
+populated with people who are willing to answer questions about using
+and installing Bison. Please keep in mind that (most of) the people on
+the list have aspects of their lives which are not related to Bison (!),
+so you may not receive an answer to your question right away. This can
+be frustrating, but please try not to honk them off; remember that any
+help they provide is purely voluntary and out of the kindness of their
+hearts.
+
+@node Bug Reports
+@section Bug Reports
+
+@display
+I found a bug. What should I include in the bug report?
+@end display
+
+Before you send a bug report, make sure you are using the latest
+version. Check @url{ftp://ftp.gnu.org/pub/gnu/bison/} or one of its
+mirrors. Be sure to include the version number in your bug report. If
+the bug is present in the latest version but not in a previous version,
+try to determine the most recent version which did not contain the bug.
+
+If the bug is parser-related, you should include the smallest grammar
+you can which demonstrates the bug. The grammar file should also be
+complete (i.e., I should be able to run it through Bison without having
+to edit or add anything). The smaller and simpler the grammar, the
+easier it will be to fix the bug.
+
+Include information about your compilation environment, including your
+operating system's name and version and your compiler's name and
+version. If you have trouble compiling, you should also include a
+transcript of the build session, starting with the invocation of
+`configure'. Depending on the nature of the bug, you may be asked to
+send additional files as well (such as `config.h' or `config.cache').
+
+Patches are most welcome, but not required. That is, do not hesitate to
+send a bug report just because you can not provide a fix.
+
+Send bug reports to @email{bug-bison@@gnu.org}.
+
+@node More Languages
+@section More Languages
+
+@display
+Will Bison ever have C++ and Java support? How about @var{insert your
+favorite language here}?
+@end display
+
+C++ and Java support is there now, and is documented. We'd love to add other
+languages; contributions are welcome.
+
+@node Beta Testing
+@section Beta Testing
+
+@display
+What is involved in being a beta tester?
+@end display
+
+It's not terribly involved. Basically, you would download a test
+release, compile it, and use it to build and run a parser or two. After
+that, you would submit either a bug report or a message saying that
+everything is okay. It is important to report successes as well as
+failures because test releases eventually become mainstream releases,
+but only if they are adequately tested. If no one tests, development is
+essentially halted.
+
+Beta testers are particularly needed for operating systems to which the
+developers do not have easy access. They currently have easy access to
+recent GNU/Linux and Solaris versions. Reports about other operating
+systems are especially welcome.
+
+@node Mailing Lists
+@section Mailing Lists
+
+@display
+How do I join the help-bison and bug-bison mailing lists?
+@end display
+
+See @url{http://lists.gnu.org/}.
+
+@c ================================================= Table of Symbols
+
+@node Table of Symbols
+@appendix Bison Symbols
+@cindex Bison symbols, table of
+@cindex symbols in Bison, table of
+
+@deffn {Variable} @@$
+In an action, the location of the left-hand side of the rule.
+@xref{Locations, , Locations Overview}.
+@end deffn
+
+@deffn {Variable} @@@var{n}
+In an action, the location of the @var{n}-th symbol of the right-hand
+side of the rule. @xref{Locations, , Locations Overview}.
+@end deffn
+
+@deffn {Variable} $$
+In an action, the semantic value of the left-hand side of the rule.
+@xref{Actions}.
+@end deffn
+
+@deffn {Variable} $@var{n}
+In an action, the semantic value of the @var{n}-th symbol of the
+right-hand side of the rule. @xref{Actions}.
projects / bison.git / blobdiff