@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 Free Software Foundation, Inc.
+1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
messy for Bison to handle straightforwardly.
* Debugging:: Understanding or debugging Bison parsers.
* Invocation:: How to run Bison (to produce the parser source file).
-* C++ Language Interface:: Creating C++ parser objects.
+* Other Languages:: Creating C++ and Java parsers.
* FAQ:: Frequently Asked Questions
* Table of Symbols:: All the keywords of the Bison language are explained.
* Glossary:: Basic concepts are explained.
* Option Cross Key:: Alphabetical list of long options.
* Yacc Library:: Yacc-compatible @code{yylex} and @code{main}.
-C++ Language Interface
+Parsers Written In Other Languages
* C++ Parsers:: The interface to generate C++ parser classes
-* A Complete C++ Example:: Demonstrating their use
+* Java Parsers:: The interface to generate Java parser classes
C++ Parsers
* C++ Location Values:: The position and location classes
* C++ Parser Interface:: Instantiating and running the parser
* C++ Scanner Interface:: Exchanges between yylex and parse
+* A Complete C++ Example:: Demonstrating their use
A Complete C++ Example
* Calc++ Scanner:: A pure C++ Flex scanner
* Calc++ Top Level:: Conducting the band
+Java Parsers
+
+* 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:: Java scanners, and pure parsers
+* Java Differences:: Differences between C/C++ and Java Grammars
+
Frequently Asked Questions
* Memory Exhausted:: Breaking the Stack Limits
@cindex Prologue Alternatives
@findex %code
-@findex %requires
-@findex %provides
-@findex %code-top
+@findex %code requires
+@findex %code provides
+@findex %code top
(The prologue alternatives described here are experimental.
More user feedback will help to determine whether they should become permanent
features.)
The functionality of @var{Prologue} sections can often be subtle and
inflexible.
-As an alternative, Bison provides a set of more explicit directives:
-@code{%code}, @code{%requires}, @code{%provides}, and @code{%code-top}.
-@xref{Table of Symbols,,Bison Symbols}.
+As an alternative, Bison provides a %code directive with an explicit qualifier
+field, which identifies the purpose of the code and thus the location(s) where
+Bison should generate it.
+For C/C++, the qualifier can be omitted for the default location, or it can be
+one of @code{requires}, @code{provides}, @code{top}.
+@xref{Decl Summary,,%code}.
Look again at the example of the previous section:
@code{YYLTYPE}, in which @var{Prologue} section should you write your new
definition?
You should write it in the first since Bison will insert that code into the
-parser code file @emph{before} the default @code{YYLTYPE} definition.
+parser source code file @emph{before} the default @code{YYLTYPE} definition.
In which @var{Prologue} section should you prototype an internal function,
@code{trace_token}, that accepts @code{YYLTYPE} and @code{yytokentype} as
arguments?
In that case, the second kind of @var{Prologue} section is not available.
This behavior is not intuitive.
-To avoid this subtle @code{%union} dependency, rewrite the example using
-@code{%code-top} and @code{%code}.
+To avoid this subtle @code{%union} dependency, rewrite the example using a
+@code{%code top} and an unqualified @code{%code}.
Let's go ahead and add the new @code{YYLTYPE} definition and the
@code{trace_token} prototype at the same time:
@smallexample
-%code-top @{
+%code top @{
#define _GNU_SOURCE
#include <stdio.h>
- /* The following code really belongs in a %requires; see below. */
+
+ /* WARNING: The following code really belongs
+ * in a `%code requires'; see below. */
+
#include "ptypes.h"
#define YYLTYPE YYLTYPE
typedef struct YYLTYPE
@end smallexample
@noindent
-In this way, @code{%code-top} and @code{%code} achieve the same functionality
-as the two kinds of @var{Prologue} sections, but it's always explicit which
-kind you intend.
+In this way, @code{%code top} and the unqualified @code{%code} achieve the same
+functionality as the two kinds of @var{Prologue} sections, but it's always
+explicit which kind you intend.
Moreover, both kinds are always available even in the absence of @code{%union}.
-The @code{%code-top} block above logically contains two parts.
-The first two lines need to appear in the parser code file.
-The fourth line is required by @code{YYSTYPE} and thus also needs to appear in
-the parser code file.
+The @code{%code top} block above logically contains two parts.
+The first two lines before the warning need to appear near the top of the
+parser source code file.
+The first line after the warning is required by @code{YYSTYPE} and thus also
+needs to appear in the parser source code file.
However, if you've instructed Bison to generate a parser header file
-(@pxref{Table of Symbols, ,%defines}), you probably want the fourth line to
-appear before the @code{YYSTYPE} definition in that header file as well.
-Also, the @code{YYLTYPE} definition should appear in the parser header file to
+(@pxref{Decl Summary, ,%defines}), you probably want that line to appear before
+the @code{YYSTYPE} definition in that header file as well.
+The @code{YYLTYPE} definition should also appear in the parser header file to
override the default @code{YYLTYPE} definition there.
-In other words, in the @code{%code-top} block above, all but the first two
-lines are dependency code for externally exposed definitions (@code{YYSTYPE}
-and @code{YYLTYPE}) required by Bison.
-Thus, they belong in one or more @code{%requires}:
+In other words, in the @code{%code top} block above, all but the first two
+lines are dependency code required by the @code{YYSTYPE} and @code{YYLTYPE}
+definitions.
+Thus, they belong in one or more @code{%code requires}:
@smallexample
-%code-top @{
+%code top @{
#define _GNU_SOURCE
#include <stdio.h>
@}
-%requires @{
+%code requires @{
#include "ptypes.h"
@}
%union @{
tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */
@}
-%requires @{
+%code requires @{
#define YYLTYPE YYLTYPE
typedef struct YYLTYPE
@{
@noindent
Now Bison will insert @code{#include "ptypes.h"} and the new @code{YYLTYPE}
definition before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE}
-definitions in both the parser code file and the parser header file.
-(By the same reasoning, @code{%requires} would also be the appropriate place to
-write your own definition for @code{YYSTYPE}.)
+definitions in both the parser source code file and the parser header file.
+(By the same reasoning, @code{%code requires} would also be the appropriate
+place to write your own definition for @code{YYSTYPE}.)
When you are writing dependency code for @code{YYSTYPE} and @code{YYLTYPE}, you
-should prefer @code{%requires} over @code{%code-top} regardless of whether you
-instruct Bison to generate a parser header file.
+should prefer @code{%code requires} over @code{%code top} regardless of whether
+you instruct Bison to generate a parser header file.
When you are writing code that you need Bison to insert only into the parser
-code file and that has no special need to appear at the top of the code file,
-you should prefer @code{%code} over @code{%code-top}.
+source code file and that has no special need to appear at the top of that
+file, you should prefer the unqualified @code{%code} over @code{%code top}.
These practices will make the purpose of each block of your code explicit to
Bison and to other developers reading your grammar file.
-Following these practices, we expect @code{%code} and @code{%requires} to be
-the most important of the four @var{Prologue} alternative directives discussed
-in this section.
+Following these practices, we expect the unqualified @code{%code} and
+@code{%code requires} to be the most important of the four @var{Prologue}
+alternatives.
At some point while developing your parser, you might decide to provide
@code{trace_token} to modules that are external to your parser.
Thus, you might wish for Bison to insert the prototype into both the parser
-header file and the parser code file.
-Since this function is not a dependency of any Bison-required definition (such
-as @code{YYSTYPE}), it doesn't make sense to move its prototype to a
-@code{%requires}.
+header file and the parser source code file.
+Since this function is not a dependency required by @code{YYSTYPE} or
+@code{YYLTYPE}, it doesn't make sense to move its prototype to a
+@code{%code requires}.
More importantly, since it depends upon @code{YYLTYPE} and @code{yytokentype},
-@code{%requires} is not sufficient.
-Instead, move its prototype from the @code{%code} to a @code{%provides}:
+@code{%code requires} is not sufficient.
+Instead, move its prototype from the unqualified @code{%code} to a
+@code{%code provides}:
@smallexample
-%code-top @{
+%code top @{
#define _GNU_SOURCE
#include <stdio.h>
@}
-%requires @{
+%code requires @{
#include "ptypes.h"
@}
%union @{
tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */
@}
-%requires @{
+%code requires @{
#define YYLTYPE YYLTYPE
typedef struct YYLTYPE
@{
@} YYLTYPE;
@}
-%provides @{
+%code provides @{
void trace_token (enum yytokentype token, YYLTYPE loc);
@}
@noindent
Bison will insert the @code{trace_token} prototype into both the parser header
-file and the parser code file after the definitions for @code{yytokentype},
-@code{YYLTYPE}, and @code{YYSTYPE}.
+file and the parser source code file after the definitions for
+@code{yytokentype}, @code{YYLTYPE}, and @code{YYSTYPE}.
The above examples are careful to write directives in an order that reflects
-the layout of the generated parser code and header files:
-@code{%code-top}, @code{%requires}, @code{%provides}, and then @code{%code}.
+the layout of the generated parser source code and header files:
+@code{%code top}, @code{%code requires}, @code{%code provides}, and then
+@code{%code}.
While your grammar files may generally be easier to read if you also follow
this order, Bison does not require it.
Instead, Bison lets you choose an organization that makes sense to you.
type:
@smallexample
-%requires @{ #include "type1.h" @}
+%code requires @{ #include "type1.h" @}
%union @{ type1 field1; @}
%destructor @{ type1_free ($$); @} <field1>
%printer @{ type1_print ($$); @} <field1>
-%requires @{ #include "type2.h" @}
+%code requires @{ #include "type2.h" @}
%union @{ type2 field2; @}
%destructor @{ type2_free ($$); @} <field2>
%printer @{ type2_print ($$); @} <field2>
Such an organization is not possible using @var{Prologue} sections.
This section has been concerned with explaining the advantages of the four
-@var{Prologue} alternative directives over the original Yacc @var{Prologue}.
+@var{Prologue} alternatives over the original Yacc @var{Prologue}.
However, in most cases when using these directives, you shouldn't need to
think about all the low-level ordering issues discussed here.
Instead, you should simply use these directives to label each block of your
code according to its purpose and let Bison handle the ordering.
@code{%code} is the most generic label.
-Move code to @code{%requires}, @code{%provides}, or @code{%code-top} as needed.
+Move code to @code{%code requires}, @code{%code provides}, or @code{%code top}
+as needed.
@node Bison Declarations
@subsection The Bison Declarations Section
In order to change the behavior of @command{bison}, use the following
directives:
+@deffn {Directive} %code @{@var{code}@}
+@findex %code
+This is the unqualified form of the @code{%code} directive.
+It inserts @var{code} verbatim at a language-dependent default location in the
+output@footnote{The default location is actually skeleton-dependent;
+ writers of non-standard skeletons however should choose the default location
+ consistently with the behavior of the standard Bison skeletons.}.
+
+@cindex Prologue
+For C/C++, the default location is the parser source code
+file after the usual contents of the parser header file.
+Thus, @code{%code} replaces the traditional Yacc prologue,
+@code{%@{@var{code}%@}}, for most purposes.
+For a detailed discussion, see @ref{Prologue Alternatives}.
+
+For Java, the default location is inside the parser class.
+
+(Like all the Yacc prologue alternatives, this directive is experimental.
+More user feedback will help to determine whether it should become a permanent
+feature.)
+@end deffn
+
+@deffn {Directive} %code @var{qualifier} @{@var{code}@}
+This is the qualified form of the @code{%code} directive.
+If you need to specify location-sensitive verbatim @var{code} that does not
+belong at the default location selected by the unqualified @code{%code} form,
+use this form instead.
+
+@var{qualifier} identifies the purpose of @var{code} and thus the location(s)
+where Bison should generate it.
+Not all values of @var{qualifier} are available for all target languages:
+
+@itemize @bullet
+@findex %code requires
+@item requires
+
+@itemize @bullet
+@item Language(s): C, C++
+
+@item Purpose: This is the best place to write dependency code required for
+@code{YYSTYPE} and @code{YYLTYPE}.
+In other words, it's the best place to define types referenced in @code{%union}
+directives, and it's the best place to override Bison's default @code{YYSTYPE}
+and @code{YYLTYPE} definitions.
+
+@item Location(s): The parser header file and the parser source code file
+before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE} definitions.
+@end itemize
+
+@item provides
+@findex %code provides
+
+@itemize @bullet
+@item Language(s): C, C++
+
+@item Purpose: This is the best place to write additional definitions and
+declarations that should be provided to other modules.
+
+@item Location(s): The parser header file and the parser source code file after
+the Bison-generated @code{YYSTYPE}, @code{YYLTYPE}, and token definitions.
+@end itemize
+
+@item top
+@findex %code top
+
+@itemize @bullet
+@item Language(s): C, C++
+
+@item Purpose: The unqualified @code{%code} or @code{%code requires} should
+usually be more appropriate than @code{%code top}.
+However, occasionally it is necessary to insert code much nearer the top of the
+parser source code file.
+For example:
+
+@smallexample
+%code top @{
+ #define _GNU_SOURCE
+ #include <stdio.h>
+@}
+@end smallexample
+
+@item Location(s): Near the top of the parser source code file.
+@end itemize
+
+@item imports
+@findex %code imports
+
+@itemize @bullet
+@item Language(s): Java
+
+@item Purpose: This is the best place to write Java import directives.
+
+@item Location(s): The parser Java file after any Java package directive and
+before any class definitions.
+@end itemize
+@end itemize
+
+(Like all the Yacc prologue alternatives, this directive is experimental.
+More user feedback will help to determine whether it should become a permanent
+feature.)
+
+@cindex Prologue
+For a detailed discussion of how to use @code{%code} in place of the
+traditional Yacc prologue for C/C++, see @ref{Prologue Alternatives}.
+@end deffn
+
@deffn {Directive} %debug
In the parser file, define the macro @code{YYDEBUG} to 1 if it is not
already defined, so that the debugging facilities are compiled.
@end deffn
@xref{Tracing, ,Tracing Your Parser}.
+@deffn {Directive} %define @var{variable}
+@deffnx {Directive} %define @var{variable} "@var{value}"
+Define a variable to adjust Bison's behavior. The possible choices for
+@var{variable}, as well as their meanings, depend on the selected target
+language and/or the parser skeleton (@pxref{Decl Summary,,%language}).
+
+Some @var{variable}s may be used as boolean values: in this case, the
+skeleton will conventionally treat a @var{value} of @samp{false} as the
+boolean variable being false; a @var{value} of @samp{true}, or @var{value}
+being omitted altogether, will conversely define the variable as true.
+@end deffn
+
@deffn {Directive} %defines
Write a header file containing macro definitions for the token type
names defined in the grammar as well as a few other declarations.
and to the token type codes. @xref{Token Values, ,Semantic Values of
Tokens}.
-@findex %requires
-@findex %provides
-If you have declared @code{%requires} or @code{%provides}, the output
+@findex %code requires
+@findex %code provides
+If you have declared @code{%code requires} or @code{%code provides}, the output
header also contains their code.
-@xref{Table of Symbols, ,%requires}.
+@xref{Decl Summary, ,%code}.
@end deffn
@deffn {Directive} %defines @var{defines-file}
chosen as if the input file were named @file{@var{prefix}.y}.
@end deffn
+@deffn {Directive} %language "@var{language}"
+Specify the programming language for the generated parser. Currently
+supported languages include C and C++.
+@var{language} is case-insensitive.
+@end deffn
+
@deffn {Directive} %locations
Generate the code processing the locations (@pxref{Action Features,
,Special Features for Use in Actions}). This mode is enabled as soon as
Require a Version of Bison}.
@end deffn
+@deffn {Directive} %skeleton "@var{file}"
+Specify the skeleton to use.
+
+You probably don't need this option unless you are developing Bison.
+You should use @code{%language} if you want to specify the skeleton for a
+different language, because it is clearer and because it will always choose the
+correct skeleton for non-deterministic or push parsers.
+
+If @var{file} does not contain a @code{/}, @var{file} is the name of a skeleton
+file in the Bison installation directory.
+If it does, @var{file} is an absolute file name or a file name relative to the
+directory of the grammar file.
+This is similar to how most shells resolve commands.
+@end deffn
+
@deffn {Directive} %token-table
Generate an array of token names in the parser file. The name of the
array is @code{yytname}; @code{yytname[@var{i}]} is the name of the
Tuning the parser:
@table @option
-@item -S @var{file}
-@itemx --skeleton=@var{file}
-Specify the skeleton to use. You probably don't need this option unless
-you are developing Bison.
-
@item -t
@itemx --debug
In the parser file, define the macro @code{YYDEBUG} to 1 if it is not
already defined, so that the debugging facilities are compiled.
@xref{Tracing, ,Tracing Your Parser}.
+@item -L @var{language}
+@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++.
+@var{language} is case-insensitive.
+
@item --locations
Pretend that @code{%locations} was specified. @xref{Decl Summary}.
@itemx --no-parser
Pretend that @code{%no-parser} was specified. @xref{Decl Summary}.
+@item -S @var{file}
+@itemx --skeleton=@var{file}
+Specify the skeleton to use, similar to @code{%skeleton}
+(@pxref{Decl Summary, , Bison Declaration Summary}).
+
+You probably don't need this option unless you are developing Bison.
+You should use @option{--language} if you want to specify the skeleton for a
+different language, because it is clearer and because it will always
+choose the correct skeleton for non-deterministic or push parsers.
+
+If @var{file} does not contain a @code{/}, @var{file} is the name of a skeleton
+file in the Bison installation directory.
+If it does, @var{file} is an absolute file name or a file name relative to the
+current working directory.
+This is similar to how most shells resolve commands.
+
@item -k
@itemx --token-table
Pretend that @code{%token-table} was specified. @xref{Decl Summary}.
@c ================================================= C++ Bison
-@node C++ Language Interface
-@chapter C++ Language Interface
+@node Other Languages
+@chapter Parsers Written In Other Languages
@menu
* C++ Parsers:: The interface to generate C++ parser classes
-* A Complete C++ Example:: Demonstrating their use
+* Java Parsers:: The interface to generate Java parser classes
@end menu
@node C++ Parsers
* C++ Location Values:: The position and location classes
* C++ Parser Interface:: Instantiating and running the parser
* C++ Scanner Interface:: Exchanges between yylex and parse
+* A Complete C++ Example:: Demonstrating their use
@end menu
@node C++ Bison Interface
@subsection C++ Bison Interface
-@c - %skeleton "lalr1.cc"
+@c - %language "C++"
@c - Always pure
@c - initial action
-The C++ parser @acronym{LALR}(1) skeleton is named @file{lalr1.cc}. To
-select it, you may either pass the option @option{--skeleton=lalr1.cc}
-to Bison, or include the directive @samp{%skeleton "lalr1.cc"} in the
-grammar preamble. When run, @command{bison} will create several
+The C++ @acronym{LALR}(1) parser is selected using the language directive,
+@samp{%language "C++"}, or the synonymous command-line option
+@option{--language=c++}.
+@xref{Decl Summary}.
+
+When run, @command{bison} will create several
entities in the @samp{yy} namespace. Use the @samp{%name-prefix}
directive to change the namespace name, see @ref{Decl Summary}. The
various classes are generated in the following files:
@c - %locations
@c - class Position
@c - class Location
-@c - %define "filename_type" "const symbol::Symbol"
+@c - %define filename_type "const symbol::Symbol"
When the directive @code{%locations} is used, the C++ parser supports
location tracking, see @ref{Locations, , Locations Overview}. Two
The name of the file. It will always be handled as a pointer, the
parser will never duplicate nor deallocate it. As an experimental
feature you may change it to @samp{@var{type}*} using @samp{%define
-"filename_type" "@var{type}"}.
+filename_type "@var{type}"}.
@end deftypemethod
@deftypemethod {position} {unsigned int} line
The output files @file{@var{output}.hh} and @file{@var{output}.cc}
declare and define the parser class in the namespace @code{yy}. The
class name defaults to @code{parser}, but may be changed using
-@samp{%define "parser_class_name" "@var{name}"}. The interface of
+@samp{%define parser_class_name "@var{name}"}. The interface of
this class is detailed below. It can be extended using the
@code{%parse-param} feature: its semantics is slightly changed since
it describes an additional member of the parser class, and an
@node A Complete C++ Example
-@section A Complete C++ Example
+@subsection A Complete C++ Example
This section demonstrates the use of a C++ parser with a simple but
complete example. This example should be available on your system,
@end menu
@node Calc++ --- C++ Calculator
-@subsection Calc++ --- C++ Calculator
+@subsubsection Calc++ --- C++ Calculator
Of course the grammar is dedicated to arithmetics, a single
expression, possibly preceded by variable assignments. An
@end example
@node Calc++ Parsing Driver
-@subsection Calc++ Parsing Driver
+@subsubsection Calc++ Parsing Driver
@c - An env
@c - A place to store error messages
@c - A place for the result
@comment file: calc++-driver.hh
@example
- // Handling the parser.
- void parse (const std::string& f);
+ // Run the parser. Return 0 on success.
+ int parse (const std::string& f);
std::string file;
bool trace_parsing;
@end example
@{
@}
-void
+int
calcxx_driver::parse (const std::string &f)
@{
file = f;
scan_begin ();
yy::calcxx_parser parser (*this);
parser.set_debug_level (trace_parsing);
- parser.parse ();
+ int res = parser.parse ();
scan_end ();
+ return res;
@}
void
@end example
@node Calc++ Parser
-@subsection 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
@comment file: calc++-parser.yy
@example
-%skeleton "lalr1.cc" /* -*- C++ -*- */
-%require "2.1a"
+%language "C++" /* -*- C++ -*- */
+%require "@value{VERSION}"
%defines
-%define "parser_class_name" "calcxx_parser"
+%define parser_class_name "calcxx_parser"
@end example
@noindent
-@findex %requires
+@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{Table of Symbols, ,%requires}.
+@xref{Decl Summary, ,%code}.
@comment file: calc++-parser.yy
@example
-%requires @{
+%code requires @{
# include <string>
class calcxx_driver;
@}
%token ASSIGN ":="
%token <sval> IDENTIFIER "identifier"
%token <ival> NUMBER "number"
-%type <ival> exp "expression"
+%type <ival> exp
@end example
@noindent
%printer @{ debug_stream () << *$$; @} "identifier"
%destructor @{ delete $$; @} "identifier"
-%printer @{ debug_stream () << $$; @} "number" "expression"
+%printer @{ debug_stream () << $$; @} <ival>
@end example
@noindent
@end example
@node Calc++ Scanner
-@subsection Calc++ Scanner
+@subsubsection Calc++ Scanner
The Flex scanner first includes the driver declaration, then the
parser's to get the set of defined tokens.
calcxx_driver::scan_begin ()
@{
yy_flex_debug = trace_scanning;
- if (!(yyin = fopen (file.c_str (), "r")))
- error (std::string ("cannot open ") + file);
+ if (file == "-")
+ yyin = stdin;
+ else if (!(yyin = fopen (file.c_str (), "r")))
+ @{
+ error (std::string ("cannot open ") + file);
+ exit (1);
+ @}
@}
void
@end example
@node Calc++ Top Level
-@subsection Calc++ Top Level
+@subsubsection Calc++ Top Level
The top level file, @file{calc++.cc}, poses no problem.
driver.trace_parsing = true;
else if (*argv == std::string ("-s"))
driver.trace_scanning = true;
- else
- @{
- driver.parse (*argv);
- std::cout << driver.result << std::endl;
- @}
+ 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:: Java scanners, and pure parsers
+* Java Differences:: Differences between C/C++ and Java Grammars
+@end menu
+
+@node Java Bison Interface
+@subsection Java Bison Interface
+@c - %language "Java"
+@c - initial action
+
+The Java parser skeletons are selected using a language directive,
+@samp{%language "Java"}, or the synonymous command-line option
+@option{--language=java}.
+
+When run, @command{bison} will create several entities whose name
+starts with @samp{YY}. Use the @samp{%name-prefix} directive to
+change the prefix, see @ref{Decl Summary}; classes can be placed
+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
+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
+Parser Interface}, all the other members and fields are preceded
+with a @code{yy} prefix to avoid clashes with user code.
+
+No header file can be generated for Java parsers; you must not pass
+@option{-d}/@option{--defines} to @command{bison}, nor use the
+@samp{%defines} directive.
+
+By default, the @samp{YYParser} class has package visibility. A
+declaration @samp{%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.
+
+All these files are documented using Javadoc.
+
+@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 @samp{%define} directive.
+For example, after the following declaration:
+
+@example
+%define "union_name" "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.
+
+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.
+
+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, 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}"}.
+
+
+@deftypemethod {Location} {Position} begin
+@deftypemethodx {Location} {Position} end
+The first, inclusive, position of the range, and the first beyond.
+@end deftypemethod
+
+@deftypemethod {Location} {void} 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 output file defines the parser class in the package optionally
+indicated in the @code{%define package} section. The class name defaults
+to @code{YYParser}. The @code{YY} prefix may be changed using
+@samp{%name-prefix}; alternatively, you can use @samp{%define
+"parser_class_name" "@var{name}"} to give a custom name to the class.
+The interface of this class is detailed below. It can be extended using
+the @code{%parse-param} directive; each occurrence of the directive will
+add a field to the parser class, and an argument to its constructor.
+
+@deftypemethod {YYParser} {} YYParser (@var{type1} @var{arg1}, ...)
+Build a new parser object. There are no arguments by default, unless
+@samp{%parse-param @{@var{type1} @var{arg1}@}} was used.
+@end deftypemethod
+
+@deftypemethod {YYParser} {boolean} parse ()
+Run the syntactic analysis, and return @code{true} on success,
+@code{false} otherwise.
+@end deftypemethod
+
+@deftypemethod {YYParser} {boolean} yyrecovering ()
+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
+
+@deftypemethod {YYParser} {void} error (Location @var{l}, String @var{m})
+The definition for this member function must be supplied by the user
+in the same way as the scanner interface (@pxref{Java Scanner
+Interface}); the parser uses it to report a parser error occurring at
+@var{l}, described by @var{m}.
+@end deftypemethod
+
+
+@node Java Scanner Interface
+@subsection Java Scanner Interface
+@c - prefix for yylex.
+@c - Pure interface to yylex
+@c - %lex-param
+
+There are two possible ways to interface a Bison-generated Java parser
+with a scanner.
+
+@cindex pure parser, in Java
+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'' in the C sense. The
+@code{%pure-parser} directive can still be used in Java, and it
+will control whether the lexer resides in a separate class than the
+Bison-generated parser (therefore, Bison generates a class that is
+``purely'' a parser), or in the same class. The interface to the scanner
+is similar, though the two cases present a slightly different naming.
+
+For the @code{%pure-parser} case, the scanner implements an interface
+called @code{Lexer} and defined within the parser class (e.g.,
+@code{YYParser.Lexer}. The constructor of the parser object accepts
+an object implementing the interface. The interface specifies
+the following methods.
+
+@deftypemethod {Lexer} {void} error (Location @var{l}, String @var{m})
+As explained in @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}".}
+@end deftypemethod
+
+@deftypemethod {Lexer} {int} yylex (@var{type1} @var{arg1}, ...)
+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. Invocations of @samp{%lex-param @{@var{type1}
+@var{arg1}@}} yield additional arguments.
+@end deftypemethod
+
+@deftypemethod {Lexer} {Position} getStartPos ()
+@deftypemethodx {Lexer} {Position} getEndPos ()
+Return respectively the first position of the last token that 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 @samp{%define "position_type"
+"@var{class-name}".}
+@end deftypemethod
+
+@deftypemethod {Lexer} {Object} getLVal ()
+Return respectively the first position of the last token that yylex
+returned, and the first position beyond it.
+
+The return type can be changed using @samp{%define "union_name"
+"@var{class-name}".}
+@end deftypemethod
+
+
+If @code{%pure-parser} is not specified, the lexer interface
+resides in the same class (@code{YYParser}) as the 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})
+As explained in @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}".}
+@end deftypemethod
+
+@deftypemethod {YYParser} {int} yylex (@var{type1} @var{arg1}, ...)
+Return the next token. Its type is the return value, its semantic
+value and location are saved into @code{yylval}, @code{yystartpos},
+@code{yyendpos}. Invocations of @samp{%lex-param @{@var{type1}
+@var{arg1}@}} yield additional arguments.
+@end deftypemethod
+
+@deftypecv {Field} {YYParser} Position yystartpos
+@deftypecvx {Field} {YYParser} Position yyendpos
+Contain respectively the first position of the last token that yylex
+returned, and the first position beyond it. These methods are not
+needed unless location tracking is active.
+
+The field's type can be changed using @samp{%define "position_type"
+"@var{class-name}".}
+@end deftypecv
+
+@deftypecv {Field} {YYParser} Object yylval
+Return respectively the first position of the last token that yylex
+returned, and the first position beyond it.
+
+The field's type can be changed using @samp{%define "union_name"
+"@var{class-name}".}
+@end deftypecv
+
+By default the class generated for a non-pure Java parser is abstract,
+and the methods @code{yylex} and @code{yyerror} shall be placed in a
+subclass (possibly defined in the additional code section). It is
+also possible, using the @code{%define "single_class"} declaration, to
+define the scanner in the same class as the parser; when this
+declaration is present, the class is not declared as abstract.
+In order to place the declarations for the scanner inside the
+parser class, you should use @code{%code} sections.
+
+@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 this differences.
+
+@itemize
+@item
+Since Java lacks a preprocessor, the @code{YYERROR}, @code{YYACCEPT},
+@code{YYABORT} symbols (@pxref{Table of Symbols}) cannot obviously be
+macros. Instead, they should be preceded in an action with
+@code{return}. The actual definition of these symbols should be
+opaque to the Bison grammar, and it might change in the future. The
+only meaningful operation that you can do, is to return them.
+
+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
+The prolog declarations have a different meaning than in C/C++ code.
+@table @code
+@item %code
+@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.
+
+@code{%code} blocks are placed inside the parser class. If @code{%define
+single_class} is being used, the definitions of @code{yylex} and
+@code{yyerror} should be placed here. Subroutines for the parser actions
+may be included in this kind of block.
+
+Other @code{%code} blocks are not supported in Java parsers.
+@end table
+@end itemize
+
@c ================================================= FAQ
@node FAQ
* I can't build Bison:: Troubleshooting
* Where can I find help?:: Troubleshouting
* Bug Reports:: Troublereporting
-* Other Languages:: Parsers in Java and others
+* More Languages:: Parsers in C++, Java, and so on
* Beta Testing:: Experimenting development versions
* Mailing Lists:: Meeting other Bison users
@end menu
Send bug reports to @email{bug-bison@@gnu.org}.
-@node Other Languages
-@section Other Languages
+@node More Languages
+@section More Languages
@display
-Will Bison ever have C++ support? How about Java or @var{insert your
+Will Bison ever have C++ and Java support? How about @var{insert your
favorite language here}?
@end display
-C++ support is there now, and is documented. We'd love to add other
+C++ and Java support is there now, and is documented. We'd love to add other
languages; contributions are welcome.
@node Beta Testing
@end deffn
@deffn {Directive} %code @{@var{code}@}
-Other than semantic actions, this is probably the most common place you should
-write verbatim code for the parser implementation.
-It replaces the traditional Yacc prologue,
-@comment For C/C++, it replaces the traditional Yacc prologue,
-@code{%@{@var{code}%@}}, for most purposes.
-@comment For Java, it inserts code into the parser class.
-
-@cindex Prologue
-@findex %union
-Compare with @code{%@{@var{code}%@}} (@pxref{Prologue, ,The Prologue})
-appearing after the first @code{%union @{@var{code}@}} in a C/C++ based grammar
-file.
-While Bison will continue to support @code{%@{@var{code}%@}} for backward
-compatibility, @code{%code @{@var{code}@}} is cleaner as its functionality does
-not depend on its position in the grammar file relative to any
-@code{%union @{@var{code}@}}.
-Specifically, @code{%code @{@var{code}@}} always inserts your @var{code} into
-the parser code file after the usual contents of the parser header file.
-
-(Like all the Yacc prologue alternative directives, this directive is
-experimental.
-More user feedback will help to determine whether it should become a permanent
-feature.)
-
-@xref{Prologue Alternatives}.
-@end deffn
-
-@deffn {Directive} %code-top @{@var{code}@}
-Occasionally it is desirable to insert code near the top of the
-@comment Occasionally for C/C++ it is desirable to insert code near the top of the
-parser code file.
-For example:
-
-@smallexample
-%code-top @{
- #define _GNU_SOURCE
- #include <stdio.h>
-@}
-@end smallexample
-
-@comment @noindent
-@comment For Java, @code{%code-top @{@var{code}@}} is currently unused.
-
-@cindex Prologue
-@findex %union
-Compare with @code{%@{@var{code}%@}} appearing before the first
-@code{%union @{@var{code}@}} in a C/C++ based grammar file.
-@code{%code-top @{@var{code}@}} is cleaner as its functionality does not depend
-on its position in the grammar file relative to any
-@code{%union @{@var{code}@}}.
-
-(Like all the Yacc prologue alternative directives, this directive is
-experimental.
-More user feedback will help to determine whether it should become a permanent
-feature.)
-
-@xref{Prologue Alternatives}.
+@deffnx {Directive} %code @var{qualifier} @{@var{code}@}
+Insert @var{code} verbatim into output parser source.
+@xref{Decl Summary,,%code}.
@end deffn
@deffn {Directive} %debug
@end deffn
@end ifset
+@deffn {Directive} %define @var{define-variable}
+@deffnx {Directive} %define @var{define-variable} @var{value}
+Define a variable to adjust Bison's behavior.
+@xref{Decl Summary,,%define}.
+@end deffn
+
@deffn {Directive} %defines
Bison declaration to create a header file meant for the scanner.
@xref{Decl Summary}.
Run user code before parsing. @xref{Initial Action Decl, , Performing Actions before Parsing}.
@end deffn
+@deffn {Directive} %language
+Specify the programming language for the generated parser.
+@xref{Decl Summary}.
+@end deffn
+
@deffn {Directive} %left
Bison declaration to assign left associativity to token(s).
@xref{Precedence Decl, ,Operator Precedence}.
@xref{Contextual Precedence, ,Context-Dependent Precedence}.
@end deffn
-@deffn {Directive} %provides @{@var{code}@}
-This is the right place to write additional definitions you would like Bison to
-expose externally.
-That is, this directive inserts your @var{code} both into the parser header
-@comment For C/C++, this directive inserts your @var{code} both into the parser header
-file (if generated; @pxref{Table of Symbols, ,%defines}) and into the parser
-code file after Bison's required definitions.
-@comment For Java, it inserts your @var{code} into the parser java file after the parser
-@comment class.
-
-(Like all the Yacc prologue alternative directives, this directive is
-experimental.
-More user feedback will help to determine whether it should become a permanent
-feature.)
-
-@xref{Prologue Alternatives}.
-@end deffn
-
@deffn {Directive} %pure-parser
Bison declaration to request a pure (reentrant) parser.
@xref{Pure Decl, ,A Pure (Reentrant) Parser}.
Require a Version of Bison}.
@end deffn
-@deffn {Directive} %requires @{@var{code}@}
-This is the right place to write dependency code for externally exposed
-definitions required by Bison.
-Such exposed definitions are those usually appearing in the parser
-@comment For C/C++, such exposed definitions are those usually appearing in the parser
-header file.
-Thus, this is the right place to define types referenced in
-@code{%union @{@var{code}@}} directives, and it is the right place to override
-Bison's default @code{YYSTYPE} and @code{YYLTYPE} definitions.
-@comment For Java, this is the right place to write import directives.
-
-@cindex Prologue
-@findex %union
-Compare with @code{%@{@var{code}%@}} (@pxref{Prologue, ,The Prologue})
-appearing before the first @code{%union @{@var{code}@}} in a C/C++ based
-grammar file.
-Unlike @code{%@{@var{code}%@}}, @code{%requires @{@var{code}@}} inserts your
-@var{code} both into the parser code file and into the parser header file (if
-generated; @pxref{Table of Symbols, ,%defines}) since Bison's required
-definitions should depend on it in both places.
-
-(Like all the Yacc prologue alternative directives, this directive is
-experimental.
-More user feedback will help to determine whether it should become a permanent
-feature.)
-
-@xref{Prologue Alternatives}.
-@end deffn
-
@deffn {Directive} %right
Bison declaration to assign right associativity to token(s).
@xref{Precedence Decl, ,Operator Precedence}.
@end deffn
+@deffn {Directive} %skeleton
+Specify the skeleton to use; usually for development.
+@xref{Decl Summary}.
+@end deffn
+
@deffn {Directive} %start
Bison declaration to specify the start symbol. @xref{Start Decl, ,The
Start-Symbol}.
making @code{yyparse} return 1 immediately. The error reporting
function @code{yyerror} is not called. @xref{Parser Function, ,The
Parser Function @code{yyparse}}.
+
+For Java parsers, this functionality is invoked using @code{return YYABORT;}
+instead.
@end deffn
@deffn {Macro} YYACCEPT
Macro to pretend that a complete utterance of the language has been
read, by making @code{yyparse} return 0 immediately.
@xref{Parser Function, ,The Parser Function @code{yyparse}}.
+
+For Java parsers, this functionality is invoked using @code{return YYACCEPT;}
+instead.
@end deffn
@deffn {Macro} YYBACKUP
@code{yyerror} and then perform normal error recovery if possible
(@pxref{Error Recovery}), or (if recovery is impossible) make
@code{yyparse} return 1. @xref{Error Recovery}.
+
+For Java parsers, this functionality is invoked using @code{return YYERROR;}
+instead.
@end deffn
@deffn {Function} yyerror
projects / bison.git / blobdiff