javaccgrm.html

This a JavaCC documentation.

<STRONG>STATIC:</STRONG>
This is a boolean option whose default value is true.  If
true, all methods and class variables are specified as static in the
generated parser and token manager.  This allows only one parser object to be present,
but it improves the performance of the parser.  To perform multiple
parses during one run of your Java program, you will have to call the
<A HREF="apiroutines.html">ReInit()</A>
method to reinitialize your parser if it is static.
If the parser is non-static, you may use the "new" operator to
construct as many parsers as you wish.  These can all be used
simultaneously from different threads.
<LI>
<STRONG>DEBUG_PARSER:</STRONG>
This is a boolean option whose default value is false.  This
option is used to obtain debugging information from the generated
parser.  Setting this option to true causes the parser to generate
a trace of its actions.  Tracing may be disabled by
calling the method <A HREF="apiroutines.html">disable_tracing()</A>
in the generated parser class.  Tracing may be subsequently enabled
by calling the method <A HREF="apiroutines.html">enable_tracing()</A>
in the generated parser class.
<LI>
<STRONG>DEBUG_LOOKAHEAD:</STRONG>
This is a boolean option whose default value is false.  Setting this
option to true causes the parser to generate all the tracing information
it does when the option DEBUG_PARSER is true, and in addition, also
causes it to generated a trace of actions performed during
<A HREF="lookahead.html">lookahead operation</A>.
<LI>
<STRONG>DEBUG_TOKEN_MANAGER:</STRONG>
This is a boolean option whose default value is false.  This
option is used to obtain debugging information from the generated
token manager.  Setting this option to true causes the token manager to generate
a trace of its actions.  This trace is rather large and should only
be used when you have a lexical error that has been reported to you
and you cannot understand why.  Typically, in this situation, you
can determine the problem by looking at the last few lines of this trace.
<LI>
<STRONG>ERROR_REPORTING:</STRONG>
This is a boolean option whose default value is
true.  Setting it to false causes errors due to parse errors to be
reported in somewhat less detail.  The only reason to set this
option to false is to improve performance.
<LI>
<STRONG>JAVA_UNICODE_ESCAPE:</STRONG>
This is a boolean option whose default value is
false.  When set to true, the generated parser uses
an input stream object that processes Java Unicode escapes
(\u...) before sending characters to the token manager.  By
default, Java Unicode escapes are not processed.
<BR>
This option is ignored if either of options USER_TOKEN_MANAGER,
USER_CHAR_STREAM is set to true.
<LI>
<STRONG>UNICODE_INPUT:</STRONG>
This is a boolean option whose default value is
false.  When set to true, the generated parser uses
uses an input stream object that reads Unicode files.  By default,
ASCII files are assumed.
<BR>
This option is ignored if either of
options USER_TOKEN_MANAGER, USER_CHAR_STREAM is set to true.
<LI>
<STRONG><A NAME="IGNORE_CASE">IGNORE_CASE:</A></STRONG>
This is a boolean option whose default value is false.
Setting this option to true causes the generated token manager to ignore
case in the token specifications and the input files.  This is useful
for writing grammars for languages such as HTML.  It is also possible
to localize the effect of IGNORE_CASE by using
<A HREF="#prod10">an alternate mechanism described later</A>.
<LI>
<STRONG>USER_TOKEN_MANAGER:</STRONG>
This is a boolean option whose default value is
false.  The default action is to generate a token manager
that works on the specified grammar tokens.  If this
option is set to true, then the parser is generated to accept tokens
from any token manager of type "TokenManager" - this interface
is generated into the generated parser directory.
<LI>
<STRONG>USER_CHAR_STREAM:</STRONG>
This is a boolean option whose default value is
false.  The default action is to generate a character stream reader
as specified by the options JAVA_UNICODE_ESCAPE and UNICODE_INPUT.
The generated token manager receives characters
from this stream reader.  If this option is set to true, then the
token manager is generated to read characters from any character
stream reader of type "CharStream.java".  This file is generated
into the generated parser directory.
<BR>
This option is ignored if USER_TOKEN_MANAGER is set to true.
<LI>
<STRONG>BUILD_PARSER:</STRONG>
This is a boolean option whose default value is true.
The default action is to generate the parser file ("MyParser.java"
in the above example).  When set to false, the parser file is
not generated.  Typically, this option is set to false when
you wish to generate only the token manager and use it without
the associated parser.
<LI>
<STRONG>BUILD_TOKEN_MANAGER:</STRONG>
This is a boolean option whose default value is true.
The default action is to generate the token manager file
("MyParserTokenManager.java" in the above example).  When set to
false the token manager file is not generated.  The only reason
to set this option to false is to save some time during parser
generation when you fix problems in the parser part of the grammar
file and leave the lexical specifications untouched.
<LI>
<STRONG>TOKEN_MANAGER_USES_PARSER:</STRONG>
This is a boolean option whose default value is false.
When set to true, the generated token manager will include a field 
called <CODE>parser</CODE> that references the instantiating parser 
instance (of type <CODE>MyParser</CODE> in the above example).
The main reason for having a parser in a token manager is using
some of its logic in lexical actions.
This option has no effect if the STATIC option is set to true.
<LI>
<STRONG>SANITY_CHECK:</STRONG>
This is a boolean option whose default value is true.
JavaCC performs many syntactic and semantic checks on the grammar
file during parser generation.  Some checks such as detection of
left recursion, detection of ambiguity, and bad usage of empty
expansions may be suppressed for faster parser generation by
setting this option to false.  Note that the presence of these
errors (even if they are not detected and reported by setting this
option to false) can cause unexpected behavior from the generated
parser.
<LI>
<STRONG>FORCE_LA_CHECK:</STRONG>
This is a boolean option whose default value is false.
This option setting controls lookahead ambiguity checking performed
by JavaCC.  By default (when this option is false), lookahead
ambiguity checking is performed for all choice points where the
default lookahead of 1 is used.  Lookahead ambiguity checking is
not performed at choice points where there is an
<A HREF="lookahead.html">explicit lookahead specification</A>,
or if the option LOOKAHEAD is set to something other than 1.
Setting this option to true performs lookahead ambiguity checking
at <EM>all</EM> choice points regardless of the lookahead specifications
in the grammar file.
<LI>
<STRONG>COMMON_TOKEN_ACTION:</STRONG>
This is a boolean option whose default value is false.
When set to true, every call to the token manager's method
"getNextToken" (<A HREF="apiroutines.html">see the description of the
Java Compiler Compiler API</A>) will cause a call to a used defined
method "CommonTokenAction" after the token has been scanned in by the
token manager.  The user must define this method within the
<A HREF="#prod12">TOKEN_MGR_DECLS</A> section.
The signature of this method is:
<P>
<PRE>
    void CommonTokenAction(Token t)
</PRE>
<P>
<LI>
<STRONG>CACHE_TOKENS:</STRONG>
This is a boolean option whose default value is false.
Setting this option to true causes the generated parser to lookahead for
extra tokens ahead of time.  This facilitates some performance improvements.
However, in this case (when the option is true), interactive
applications may not work since the parser needs to work synchronously
with the availability of tokens from the input stream.  In such cases,
it's best to leave this option at its default value.
<LI>
<STRONG>OUTPUT_DIRECTORY:</STRONG>
This is a string valued option whose default value is the current
directory.  This controls where output files are generated.
</UL>

<P>
<HR>
<P>

<TABLE>
<TR>
<TD ALIGN=RIGHT VALIGN=BASELINE><A NAME="prod5">production</A></TD>
<TD ALIGN=CENTER VALIGN=BASELINE>::=</TD>
<TD ALIGN=LEFT VALIGN=BASELINE><A HREF="#prod9">javacode_production</A></TD>
</TR>
<TR>
<TD ALIGN=RIGHT VALIGN=BASELINE></TD>
<TD ALIGN=CENTER VALIGN=BASELINE>|</TD>
<TD ALIGN=LEFT VALIGN=BASELINE><A HREF="#prod10">regular_expr_production</A></TD>
</TR>
<TR>
<TD ALIGN=RIGHT VALIGN=BASELINE></TD>
<TD ALIGN=CENTER VALIGN=BASELINE>|</TD>
<TD ALIGN=LEFT VALIGN=BASELINE><A HREF="#prod11">bnf_production</A></TD>
</TR>
<TR>
<TD ALIGN=RIGHT VALIGN=BASELINE></TD>
<TD ALIGN=CENTER VALIGN=BASELINE>|</TD>
<TD ALIGN=LEFT VALIGN=BASELINE><A HREF="#prod12">token_manager_decls</A></TD>
</TR>
</TABLE>
<P>

There are four kinds of productions in JavaCC.
<A HREF="#prod9">javacode_production</A> and <A HREF="#prod11">bnf_production</A>
are used to define the grammar from which the parser is generated.
<A HREF="#prod10">regular_expr_production</A> is used to define the grammar
tokens - the token manager is generated from this information (as well as from
inline token specifications in the parser grammar).
<A HREF="#prod12">token_manager_decls</A> is used to introduce declarations
that get inserted into the generated token manager.

<P>
<HR>
<P>

<TABLE>
<TR>
<TD ALIGN=RIGHT VALIGN=BASELINE><A NAME="prod9">javacode_production</A></TD>
<TD ALIGN=CENTER VALIGN=BASELINE>::=</TD>
<TD ALIGN=LEFT VALIGN=BASELINE>"<A NAME="JAVACODE">JAVACODE</A>"</TD>
</TR>
<TR>
<TD></TD><TD></TD>
<TD ALIGN=LEFT VALIGN=BASELINE><EM>java_access_modifier</EM> <EM>java_return_type</EM> <EM>java_identifier</EM> "(" <EM>java_parameter_list</EM> ")"</TD>
</TR>
<TR>
<TD></TD><TD></TD>
<TD ALIGN=LEFT VALIGN=BASELINE><EM>java_block</EM>
</TR>
</TABLE>
<P>

The JAVACODE production is a way to write Java code for some
productions instead of the usual EBNF expansion.  This is useful when
there is the need to recognize something that is not context-free
or for whatever reason is very difficult to write a grammar for.
An example of the use of JAVACODE is shown below.  In this example,
the non-terminal "skip_to_matching_brace" consumes tokens in the input
stream all the way up to a matching closing brace (the opening brace
is assumed to have been just scanned):
<P>
<PRE>
    JAVACODE
    void skip_to_matching_brace() {
      <A HREF="apiroutines.html">Token</A> tok;
      int nesting = 1;
      while (true) {
        tok = <A HREF="apiroutines.html">getToken</A>(1);
        if (tok.kind == LBRACE) nesting++;
        if (tok.kind == RBRACE) {
          nesting--;
          if (nesting == 0) break;
        }
        tok = <A HREF="apiroutines.html">getNextToken</A>();
      }
    }
</PRE>
<P>
Care must be taken when using JAVACODE productions.  While you can
say pretty much what you want with these productions, JavaCC simply
considers it a black box (that somehow performs its parsing task).
This becomes a problem when JAVACODE productions appear at
<A HREF="lookahead.html">choice points</A>.  For example, if the
above JAVACODE production was referred to from the following production:
<P>
<PRE>
  void NT() :
  {}
  {
    skip_to_matching_brace()
  |
    some_other_production()
  }
</PRE>
<P>
Then JavaCC would not know how to choose between the two choices.
On the other hand, if the JAVACODE production is used at a non-choice
point as in the following example, there is no problem:
<P>
<PRE>
  void NT() :
  {}
  {
    "{" skip_to_matching_brace()
  |
    "(" parameter_list() ")"
  }
</PRE>
<P>
When JAVACODE productions are used at choice points, JavaCC will
print a warning message stating this fact.  You will then have to
insert some explicit LOOKAHEAD specifications to help JavaCC.  See
<A HREF="lookahead.html">the minitutorial on LOOKAHEAD</A> for a
detailed guide on such issues.
<P>
The default access modifier for JAVACODE productions is package private.

<P>
<HR>
<P>

<TABLE>
<TR>
<TD ALIGN=RIGHT VALIGN=BASELINE><A NAME="prod11">bnf_production</A></TD>
<TD ALIGN=CENTER VALIGN=BASELINE>::=</TD>
<TD ALIGN=LEFT VALIGN=BASELINE><EM>java_access_modifier</EM> <EM>java_return_type</EM> <EM>java_identifier</EM> "(" <EM>java_parameter_list</EM> ")" ":"</TD>
</TR>
<TR>
<TD></TD><TD></TD>
<TD ALIGN=LEFT VALIGN=BASELINE><EM>java_block</EM>
</TR>
<TR>
<TD></TD><TD></TD>
<TD ALIGN=LEFT VALIGN=BASELINE>"{" <A HREF="#prod16">expansion_choices</A> "}"</TD>
</TR>
</TABLE>
<P>

The BNF production is the standard production used
in specifying JavaCC grammars.  Each BNF production has a left hand
side which is a non-terminal specification.  The BNF production then
defines this non-terminal in terms of BNF expansions on the right hand
side.  The non-terminal is written exactly like a declared Java method.
Since each non-terminal is translated into a method
in the generated parser, this style of writing the non-terminal makes
this association obvious.  The name of the non-terminal is the name of
the method, and the parameters and return value declared are the means
to pass values up and down the parse tree.  As will be seen later,
non-terminals on the right hand sides of productions are written as
method calls, so the passing of values up and down the tree are done
using exactly the same paradigm as method call and return.
The default access modifier for BNF productions is public.
<P>
There are two parts on the right hand side of an BNF production.  The
first part is a set of arbitrary Java declarations and code (the Java
block).  This code is generated at the beginning
of the method generated for the Java non-terminal.  Hence, every time
this non-terminal is used in the parsing process, these declarations and
code are executed.  The declarations in this part are visible to all Java
code in actions in the BNF expansions.  JavaCC does not do any processing
of these declarations and code, except to skip to the matching ending
brace, collecting all text encountered on the way.  Hence, a Java compiler
can detect errors in this code that has been processed by JavaCC.
<P>
The second part of the right hand side are the BNF expansions.  This
is described <A NAME="prod16">later</A>.

<P>
<HR>
<P>