javaccgrm.html

This a JavaCC documentation.

<TD ALIGN=LEFT VALIGN=BASELINE>"LOOKAHEAD" "(" [ <EM>java_integer_literal</EM> ] [ "," ] [ <A HREF="#prod16">expansion_choices</A> ] [ "," ] [ "{" <EM>java_expression</EM> "}" ] ")"</TD>
</TR>
</TABLE>
<P>

A local lookahead specification is used to influence the way the generated
parser makes choices at the various
<A HREF="lookahead.html">choice points</A>
in the grammar.  A local lookahead specification starts with the reserved
word "LOOKAHEAD" followed by a set of lookahead constraints within parentheses.
There are three different kinds of lookahead constraints - a lookahead limit
(the integer literal), a syntactic lookahead (the expansion choices), and
a semantic lookahead (the expression within braces).  At least one lookahead
constraint must be present.  If more than one lookahead constraint is present,
they must be separated by commas.
<P>
For a detailed description of how lookahead works, please
<A HREF="lookahead.html">click here to visit the minitutorial on LOOKAHEAD</A>.
A brief description of each kind of lookahead constraint is given below:
<P>
<UL>
<LI>
<STRONG>Lookahead Limit:</STRONG>
This is the maximum number of tokens of lookahead that may be used for choice
determination purposes.  This overrides the default value which is specified
by the <A HREF="#prod2">LOOKAHEAD option</A>.  This lookahead limit applies
only to the <A HREF="lookahead.html">choice point</A>
at the location of the local lookahead specification.
If the local lookahead specification is not at a choice point, the lookahead
limit (if any) is ignored.
<P>
<LI>
<STRONG>Syntactic Lookahead:</STRONG>
This is an expansion (or expansion choices) that is used for the purpose of
determining whether or not the particular choice that this local lookahead
specification applies to is to be taken.  If this was not provided, the parser
uses the expansion to be selected during lookahead determination.
If the local lookahead specification is not at a
<A HREF="lookahead.html">choice point</A>, the syntactic
lookahead (if any) is ignored.
<P>
<LI>
<STRONG>Semantic Lookahead:</STRONG>
This is a boolean expression that is evaluated whenever the parser crosses this
point during parsing.  If the expression evaluates to true, the parsing
continues normally.  If the expression evaluates to false and the local
lookahead specification is at a <A HREF="lookahead.html">choice point</A>,
the current choice is not taken and the next choice is considered.
If the expression evaluates to false and the local lookahead specification
is <EM>not</EM> at a choice point, then parsing aborts with a parse error.
Unlike the other two lookahead constraints that are ignored at non-choice
points, semantic lookahead is always evaluated.  In fact, semantic lookahead
is even evaluated if it is encountered during the evaluation of some other
syntactic lookahead check (for more details
<A HREF="lookahead.html">click here to visit the minitutorial on LOOKAHEAD</A>).
</UL>
<P>
<STRONG>Default values for lookahead constraints:</STRONG>
If a local lookahead specification has been provided, but not all lookahead
constraints have been included, then the missing ones are assigned default
values as follows:
<P>
<UL>
<LI>
If the lookahead limit is not provided and if the syntactic lookahead is
provided, then the lookahead limit defaults to the largest integer value
(2147483647).  This essentially implements "infinite lookahead" - namely,
look ahead as many tokens as necessary to match the syntactic lookahead that
has been provided.
<P>
<LI>
If neither the lookahead limit nor the syntactic lookahead has been
provided (which means the semantic lookahead is provided), the lookahead
limit defaults to 0.  This means that syntactic lookahead is not performed
(it passes trivially), and only semantic lookahead is performed.
<P>
<LI>
If the syntactic lookahead is not provided, it defaults to the choice
to which the local lookahead specification applies.  If the local lookahead
specification is not at a choice point, then the syntactic lookahead is
ignored - hence a default value is not relevant.
<P>
<LI>
If the semantic lookahead is not provided, it defaults to the boolean
expression "true".  That is, it trivially passes.
</UL>
<P>
<HR>
<P>

<TABLE>
<TR>
<TD ALIGN=RIGHT VALIGN=BASELINE><A NAME="prod19">regular_expression</A></TD>
<TD ALIGN=CENTER VALIGN=BASELINE>::=</TD>
<TD ALIGN=LEFT VALIGN=BASELINE><EM>java_string_literal</EM></TD>
</TR>
<TR>
<TD ALIGN=RIGHT VALIGN=BASELINE></TD>
<TD ALIGN=CENTER VALIGN=BASELINE>|</TD>
<TD ALIGN=LEFT VALIGN=BASELINE>"&lt;" [ [ "#" ] <EM>java_identifier</EM> ":" ] <A HREF="#prod29">complex_regular_expression_choices</A> "&gt;"</TD>
</TR>
<TR>
<TD ALIGN=RIGHT VALIGN=BASELINE></TD>
<TD ALIGN=CENTER VALIGN=BASELINE>|</TD>
<TD ALIGN=LEFT VALIGN=BASELINE>"&lt;" <EM>java_identifier</EM> "&gt;"</TD>
</TR>
<TR>
<TD ALIGN=RIGHT VALIGN=BASELINE></TD>
<TD ALIGN=CENTER VALIGN=BASELINE>|</TD>
<TD ALIGN=LEFT VALIGN=BASELINE>"&lt;" "EOF" "&gt;"</TD>
</TR>
</TABLE>
<P>

There are two places in a grammar files where regular expressions may be
written:
<UL>
<LI>
Within a <A HREF="#prod18">regular expression specification</A>
(part of a <A HREF="#prod10">regular expression production</A>),
<P>
<LI>
As an <A HREF="#prod22">expansion unit</A> with an <A HREF="#prod20">expansion</A>.
When a regular expression is used in this manner, it is as if the regular expression
were defined in the following manner at this location and then referred to by its
label from the expansion unit:
<P>
<PRE>
    &lt;DEFAULT&gt; TOKEN :
    {
      regular expression
    }
</PRE>
<P>
That is, this usage of regular expression can be rewritten using the other
kind of usage.
</UL>
<P>
The complete details of regular expression matching by the token manager is
available in
<A HREF="tokenmanager.html">the minitutorial on the token manager</A>.  The
description of the syntactic constructs follows.
<P>
The first kind of regular expression is a string literal.  The input being
parsed matches this regular expression if the token manager is in a
<A HREF="#prod10">lexical state</A> for which this regular expression applies
and the next set of characters in the input stream is the same (possibly with
case ignored) as this string literal.
<P>
A regular expression may also be a more <A HREF="#prod29">complex regular expression</A>
using which more involved regular expression (than string literals can be defined).
Such a regular expression is placed within angular brackets "&lt;...&gt;", and
may be labeled optionally with an identifier.  This label may be used to refer
to this regular expression from
<A HREF="#prod22">expansion units</A>
or from within other regular expressions.
If the label is preceded by a "#", then this regular expression may not be
referred to from expansion units, but only from within other regular expressions.
When the "#" is present, the regular expression is referred to as a
"private regular expression".
<P>
A regular expression may be a reference to some other labeled regular expression
in which case it is written as the label enclosed in angular brackets "&lt;...&gt;".
<P>
Finally, a regular expression may be a reference to the predefined regular
expression "&lt;EOF&gt;" which is matched by the end of file.
<P>
Private regular expressions are not matched as tokens by the token manager.
Their purpose is solely to facilitate the definition of other more complex
regular expressions.
<P>
Consider the following example defining Java floating point literals:
<P>
<PRE>
TOKEN :
{
  < FLOATING_POINT_LITERAL:
        (["0"-"9"])+ "." (["0"-"9"])* (&lt;EXPONENT>)? (["f","F","d","D"])?
      | "." (["0"-"9"])+ (&lt;EXPONENT>)? (["f","F","d","D"])?
      | (["0"-"9"])+ &lt;EXPONENT> (["f","F","d","D"])?
      | (["0"-"9"])+ (&lt;EXPONENT>)? ["f","F","d","D"]
  >
|
  < #EXPONENT: ["e","E"] (["+","-"])? (["0"-"9"])+ >
}
</PRE>
<P>
In this example, the token FLOATING_POINT_LITERAL is defined using the
definition of another token, namely, EXPONENT.  The "#" before the label
EXPONENT indicates that this exists solely for the purpose of defining other
tokens (FLOATING_POINT_LITERAL in this case).  The definition of
FLOATING_POINT_LITERAL is not affected by the presence or absence of the "#".
However, the token manager's behavior is.  If the "#" is omitted, the
token manager will
erroneously recognize a string like E123 as a legal token of kind EXPONENT
(instead of IDENTIFIER in the Java grammar).

<P>
<HR>
<P>

<TABLE>
<TR>
<TD ALIGN=RIGHT VALIGN=BASELINE><A NAME="prod29">complex_regular_expression_choices</A></TD>
<TD ALIGN=CENTER VALIGN=BASELINE>::=</TD>
<TD ALIGN=LEFT VALIGN=BASELINE><A HREF="#prod30">complex_regular_expression</A> ( "|" <A HREF="#prod30">complex_regular_expression</A> )*</TD>
</TR>
</TABLE>
<P>

Complex regular expression choices is made up of a list of one or more
<A HREF="#prod30">complex regular expressions</A> separated by "|"s.
A match for a complex regular expression choice is a match of any of its
constituent complex regular expressions.

<P>
<HR>
<P>

<TABLE>
<TR>
<TD ALIGN=RIGHT VALIGN=BASELINE><A NAME="prod30">complex_regular_expression</A></TD>
<TD ALIGN=CENTER VALIGN=BASELINE>::=</TD>
<TD ALIGN=LEFT VALIGN=BASELINE>( <A HREF="#prod31">complex_regular_expression_unit</A> )*</TD>
</TR>
</TABLE>
<P>

A complex regular expression is a sequence of complex regular expression units.
A match for a complex regular expression is a concatenation of matches to
the complex regular expression units.

<P>
<HR>
<P>

<TABLE>
<TR>
<TD ALIGN=RIGHT VALIGN=BASELINE><A NAME="prod31">complex_regular_expression_unit</A></TD>
<TD ALIGN=CENTER VALIGN=BASELINE>::=</TD>
<TD ALIGN=LEFT VALIGN=BASELINE><EM>java_string_literal</EM></TD>
</TR>
<TR>
<TD ALIGN=RIGHT VALIGN=BASELINE></TD>
<TD ALIGN=CENTER VALIGN=BASELINE>|</TD>
<TD ALIGN=LEFT VALIGN=BASELINE>"&lt;" <EM>java_identifier</EM> "&gt;"</TD>
</TR>
<TR>
<TD ALIGN=RIGHT VALIGN=BASELINE></TD>
<TD ALIGN=CENTER VALIGN=BASELINE>|</TD>
<TD ALIGN=LEFT VALIGN=BASELINE><A HREF="#prod32">character_list</A></TD>
</TR>
<TR>
<TD ALIGN=RIGHT VALIGN=BASELINE></TD>
<TD ALIGN=CENTER VALIGN=BASELINE>|</TD>
<TD ALIGN=LEFT VALIGN=BASELINE>"(" <A HREF="#prod29">complex_regular_expression_choices</A> ")" [ "+" | "*" | "?" ]</TD>
</TR>
</TABLE>
<P>

A complex regular expression unit can be a string literal,  in which case
there is exactly one match for this unit, namely, the string literal itself.
<P>
A complex regular expression unit can be a reference to another regular
expression.  The other regular expression has to be labeled so that it
can be referenced.  The matches of this unit are all the matches of this
other regular expression.  Such references in regular expressions cannot
introduce loops in the dependency between tokens.
<P>
A complex regular expression unit can be a <A HREF="#prod32">character list</A>.
A character list is a way of defining a set of characters.  A match for this
kind of complex regular expression unit is any character that is allowed
by the character list.
<P>
A complex regular expression unit can be a parenthesized set of
complex regular expression choices.  In this case, a legal match of
the unit is any legal match of the nested choices.  The parenthesized
set of choices can be suffixed (optionally) by:
<UL>
<LI>
<STRONG>"+":</STRONG>
Then any legal match of the unit is one or more
repetitions of a legal match of the parenthesized set of
choices.
<LI>
<STRONG>"*":</STRONG>
Then any legal match of the unit is zero or more
repetitions of a legal match of the parenthesized set of
choices.
<LI>
<STRONG>"?":</STRONG>
Then a legal match of the unit is either the
empty string or any legal match of the nested choices.
</UL>
Note that unlike the BNF <A HREF="#prod20">expansions</A>,
the regular expression "[...]" is not equivalent
to the regular expression "(...)?".  This is because the [...]
construct is used to describe <A HREF="#prod32">character lists</A>
in regular expressions.

<P>
<HR>
<P>

<TABLE>
<TR>
<TD ALIGN=RIGHT VALIGN=BASELINE><A NAME="prod32">character_list</A></TD>
<TD ALIGN=CENTER VALIGN=BASELINE>::=</TD>
<TD ALIGN=LEFT VALIGN=BASELINE>[ "~" ] "[" [ <A HREF="#prod33">character_descriptor</A> ( "," <A HREF="#prod33">character_descriptor</A> )* ] "]"</TD>
</TR>
</TABLE>
<P>

A character list describes a set of characters.  A legal match for a
character list is any character in this set.  A character list is a list
of character descriptors separated by commas within square brackets.
Each character descriptor describes a single character or a range of characters
(see <A HREF="#prod33">character descriptor</A> below),
and this is added to the set of characters of the character
list.  If the character list is prefixed by the "~" symbol, the set of
characters it represents is any UNICODE character not in the specified set.

<P>
<HR>
<P>

<TABLE>
<TR>
<TD ALIGN=RIGHT VALIGN=BASELINE><A NAME="prod33">character_descriptor</A></TD>
<TD ALIGN=CENTER VALIGN=BASELINE>::=</TD>
<TD ALIGN=LEFT VALIGN=BASELINE><EM>java_string_literal</EM> [ "-" <EM>java_string_literal</EM> ]</TD>
</TR>
</TABLE>
<P>

A character descriptor can be a single character string literal, in which
case it describes a singleton set containing that character; or it is
two single character string literals separated by a "-", in which case, it
describes the set of all characters in the range between and including these
two characters.

<P>

</BODY>
</HTML>