+/* 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 + ": " + strerror(errno));
+ exit (EXIT_FAILURE);
+ @}
+@}
+
+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}
+containing the parser implementation. Using a grammar file without a
+@file{.y} suffix is currently broken. The basename of the parser
+implementation file can be changed by the @code{%file-prefix}
+directive or the @option{-p}/@option{--name-prefix} option. The
+entire parser implementation file name can be changed by the
+@code{%output} directive or the @option{-o}/@option{--output} option.
+The parser implementation 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.
+
+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{Tracking Locations}. 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 their 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 semantic 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
+
+@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
+@samp{%define stype}. Angle brackets 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 prologue 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
projects / bison.git / blobdiff