Improve display of directives.

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index ebb37ca6c1c4c9e841ec324d54886c25c1d512e0..ae3dc4b014d55f104072a921aa4f36561717a5f2 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -8845,15 +8845,21 @@ 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.
 @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
+Currently, support for debugging is 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
 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
+unused code in the generated parser, so use @code{%debug} explicitly
+if needed.  Also, in the future the

 @code{%token-table} directive might enable a public interface to
 access the token names and codes.
 
 @code{%token-table} directive might enable a public interface to
 access the token names and codes.
 

+Getting a ``code too large'' error from the Java compiler means the code
+hit the 64KB bytecode per method limination of the Java class file.
+Try reducing the amount of code in actions and static initializers;
+otherwise, report a bug so that the parser skeleton will be improved.
+
+

 @node Java Semantic Values
 @subsection Java Semantic Values
 @c - No %union, specify type in %type/%token.
 @node Java Semantic Values
 @subsection Java Semantic Values
 @c - No %union, specify type in %type/%token.


@@ -8960,6 +8966,8 @@ 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.
 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.

+A single @code{%define annotations "@var{annotations}"} directive can
+be used to add any number of annotations 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
 
 The Java package name of the parser class can be specified using the
 @code{%define package} directive.  The superclass and the implemented


@@ -8973,21 +8981,19 @@ 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.
 
 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.
 
 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.
 @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.

+
+Use @code{%code init} for code added to the start of the constructor
+body. This is especially useful to initialize superclasses. Use
+@code{%define init_throws} to specify any uncatch exceptions.

 @end deftypeop
 
 @deftypeop {Constructor} {YYParser} {} YYParser (Lexer @var{lexer}, @var{parse_param}, @dots{})
 @end deftypeop
 
 @deftypeop {Constructor} {YYParser} {} YYParser (Lexer @var{lexer}, @var{parse_param}, @dots{})


@@ -8997,6 +9003,10 @@ 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.
 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.

+
+Use @code{%code init} for code added to the start of the constructor
+body. This is especially useful to initialize superclasses. Use
+@code{%define init_throws} to specify any uncatch exceptions.

 @end deftypeop
 
 @deftypemethod {YYParser} {boolean} parse ()
 @end deftypeop
 
 @deftypemethod {YYParser} {boolean} parse ()


@@ -9004,6 +9014,21 @@ Run the syntactic analysis, and return @code{true} on success,
 @code{false} otherwise.
 @end deftypemethod
 
 @code{false} otherwise.
 @end deftypemethod
 

+@deftypemethod {YYParser} {boolean} getErrorVerbose ()
+@deftypemethodx {YYParser} {void} setErrorVerbose (boolean @var{verbose})
+Get or set the option to produce verbose error messages.  These are only
+available with the @code{%error-verbose} directive, which also turn on
+verbose error messages.
+@end deftypemethod
+
+@deftypemethod {YYParser} {void} yyerror (String @var{msg})
+@deftypemethodx {YYParser} {void} yyerror (Position @var{pos}, String @var{msg})
+@deftypemethodx {YYParser} {void} yyerror (Location @var{loc}, String @var{msg})
+Print an error message using the @code{yyerror} method of the scanner
+instance in use. The @code{Location} and @code{Position} parameters are
+available only if location tracking is active.
+@end deftypemethod
+

 @deftypemethod {YYParser} {boolean} recovering ()
 During the syntactic analysis, return @code{true} if recovering
 from a syntax error.
 @deftypemethod {YYParser} {boolean} recovering ()
 During the syntactic analysis, return @code{true} if recovering
 from a syntax error.


@@ -9022,6 +9047,11 @@ Get or set the tracing level.  Currently its value is either 0, no trace,
 or nonzero, full tracing.
 @end deftypemethod
 
 or nonzero, full tracing.
 @end deftypemethod
 

+@deftypecv {Constant} {YYParser} {String} {bisonVersion}
+@deftypecvx {Constant} {YYParser} {String} {bisonSkeleton}
+Identify the Bison version and skeleton used to generate this parser.
+@end deftypecv
+

 
 @node Java Scanner Interface
 @subsection Java Scanner Interface
 
 @node Java Scanner Interface
 @subsection Java Scanner Interface


@@ -9032,7 +9062,9 @@ or nonzero, full tracing.
 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
 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.
+@code{Lexer} inner interface of the parser class.  This interface also
+contain constants for all user-defined token names and the predefined
+@code{EOF} token.

 
 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
 
 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


@@ -9156,11 +9188,12 @@ operation.
 @xref{Error Recovery}.
 @end deftypefn
 
 @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)
+@deftypefn  {Function} {void} yyerror (String @var{msg})
+@deftypefnx {Function} {void} yyerror (Position @var{loc}, String @var{msg})
+@deftypefnx {Function} {void} yyerror (Location @var{loc}, String @var{msg})

 Print an error message using the @code{yyerror} method of the scanner
 Print an error message using the @code{yyerror} method of the scanner

-instance in use.
+instance in use. The @code{Location} and @code{Position} parameters are
+available only if location tracking is active.

 @end deftypefn
 
 
 @end deftypefn
 
 


@@ -9276,6 +9309,11 @@ Code inserted just after the @code{package} declaration.
 @xref{Java Differences}.
 @end deffn
 
 @xref{Java Differences}.
 @end deffn
 

+@deffn {Directive} {%code init} @{ @var{code} @dots{} @}
+Code inserted at the beginning of the parser constructor body.
+@xref{Java Parser Interface}.
+@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}.
 @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}.


@@ -9288,7 +9326,7 @@ Code (after the second @code{%%}) appended to the end of the file,
 @end deffn
 
 @deffn {Directive} %@{ @var{code} @dots{} %@}
 @end deffn
 
 @deffn {Directive} %@{ @var{code} @dots{} %@}

-Not supported.  Use @code{%code import} instead.
+Not supported.  Use @code{%code imports} instead.

 @xref{Java Differences}.
 @end deffn
 
 @xref{Java Differences}.
 @end deffn
 


@@ -9297,6 +9335,11 @@ Whether the parser class is declared @code{abstract}.  Default is false.
 @xref{Java Bison Interface}.
 @end deffn
 
 @xref{Java Bison Interface}.
 @end deffn
 

+@deffn {Directive} {%define annotations} "@var{annotations}"
+The Java annotations for the parser class.  Default is none.
+@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}.
 @deffn {Directive} {%define extends} "@var{superclass}"
 The superclass of the parser class.  Default is none.
 @xref{Java Bison Interface}.


@@ -9313,6 +9356,12 @@ Default is none.
 @xref{Java Bison Interface}.
 @end deffn
 
 @xref{Java Bison Interface}.
 @end deffn
 

+@deffn {Directive} {%define init_throws} "@var{exceptions}"
+The exceptions thrown by @code{%code init} from the parser class
+constructor.  Default is none.
+@xref{Java Parser 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}.
 @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}.