apiroutines.html

This a JavaCC documentation.

<P>
<LI>
<STRONG>Token next;</STRONG>
<BR>
A reference to the next regular (non-special) token from the input
stream.  If this is the last token from the input stream, or if the
token manager has not read tokens beyond this one, this field is
set to null.
<P>
The description in the above paragraph holds only if this token is also a regular
token.  Otherwise, see below for a description of the contents of
this field.
<P>
Note: There are two kinds of tokens - regular and special.  Regular tokens are
the normal tokens that are fed to the parser.  Special tokens are other useful
tokens (like comments) that are not discarded (like white space).  For more
information on the different kinds of tokens
<a href="tokenmanager.html">please see the minitutorial on the token manager</a>.
<P>
<LI>
<STRONG>Token specialToken;</STRONG>
<BR>
This field is used to access special tokens that occur prior to this
token, but after the immediately preceding regular (non-special) token.
If there are no such special tokens, this field is set to null.
When there are more than one such special token, this field refers
to the last of these special tokens, which in turn refers to the next
previous special token through its specialToken field, and so on
until the first special token (whose specialToken field is null).
The next fields of special tokens refer to other special tokens that
immediately follow it (without an intervening regular token).  If there
is no such token, this field is null.
<P>
<LI>
<STRONG>static final Token newToken(int ofKind);</STRONG>
<BR>
Returns a new token object as its default behavior.  If you wish to
perform special actions when a token is constructed or create subclasses
of class Token and instantiate them instead, you can redefine this method
appropriately.  The only constraint is that this method returns a <EM>new</EM>
object of type Token (or a subclass of Token).
</UL>

<P>
<HR>
<P>
<CENTER>
<H3>Reading Tokens from the Input Stream</H3>
</CENTER>
<P>
<HR>
<P>

There are two methods available for this purpose:
<UL>
<LI>
<STRONG><A name="getNextToken">Token TheParser.getNextToken() throws ParseError</a></STRONG>
<BR>
This method returns the next available token in the input stream and moves
the token pointer one step in the input stream (i.e., this changes the state
of the input stream).  If there are no more tokens available in the input
stream, the exception ParseError is thrown.  Care must be taken when calling
this method since it can interfere with the parser's knowledge of the state
of the input stream, current token, etc.
<P>
<LI>
<STRONG><A name="getToken">Token TheParser.getToken(int index) throws ParseError</a></STRONG>
<BR>
This method returns the index-th token from the current token ahead in the
token stream.  If index is 0, it returns the current token (the last token
returned by getNextToken or consumed by the parser); if index is 1, it returns
the next token (the next token that will be returned by getNextToken of consumed
by the parser) and so on.  The index parameter cannot be negative.  This method
does not change the input stream pointer (i.e., it does not change the
state of the input stream).  If an attempt is made to access a token beyond the
last available token, the exception ParseError is thrown.
If this method is called from a semantic lookahead specification, which in turn
is called during a lookahead determination process, the current token is temporarily
adjusted to be the token currently being inspected by the lookahead process.
For more details,
<a href="lookahead.html">please see the minitutorial on using lookahead</a>.
</UL>

<P>
<HR>
<P>
<CENTER>
<H3>Working with Debugger Tracing</H3>
</CENTER>
<P>
<HR>
<P>

When you generate parsers with the options DEBUG_PARSER or DEBUG_LOOKAHEAD, these
parsers produce a trace of their activity which is printed to the user console.
You can insert calls to the following methods to control this tracing activity:
<P>
<UL>
<LI>
<STRONG>void TheParser.enable_tracing()</STRONG>
<P>
<LI>
<STRONG>void TheParser.disable_tracing()</STRONG>
<P>
</UL>
<P>
For convenience, these methods are available even when you build parsers without
the debug options.  In this case, these methods are no-ops.  Hence you can
permanently leave these methods in your code and they automatically kick in when
you use the debug options.
<P>
<HR>
<P>
<CENTER>
<H3>Customizing Error Messages</H3>
</CENTER>
<P>
<HR>
<P>
To help the user in customizing error messages generated by the parser and lexer, the
user is offered the facilities described in this section.  In the case of the
parser, these facilities are only available if the option ERROR_REPORTING is
true, while in the case of the lexer, these facilities are always available.
<P>
The parser contains the following method definition:
<UL>
<LI>
<STRONG>protected void token_error() { ... }</STRONG>
</UL>
<P>
To customize error reporting by the parser, the parser class must be subclassed
and this method redefined in the subclass.  To help with creating your
error reporting scheme, the following variables are available:
<P>
<UL>
<LI>
<STRONG>protected int error_line, error_column;</STRONG>
<BR>
The line and column where the error was detected.
<P>
<LI>
<STRONG>protected String error_string;</STRONG>
<BR>
The image of the offending token or set of tokens.  When a lookahead of more
than 1 is used, more than one token may be present here.
<P>
<LI>
<STRONG>protected String[] expected_tokens;</STRONG>
<BR>
An array of images of legitimate token sequences.  Here again, each legitimate
token sequence may be more than just one token when a lookahead of more than
1 is used.
</UL>
<P>
The lexer contains the following method definition:
<UL>
<LI>
<STRONG>protected void LexicalError() { ... }</STRONG>
</UL>
<P>
To customize error reporting by the lexer, the lexer class must be subclassed
and this method redefined in the subclass.  To help with creating your
error reporting scheme, the following variables are available:
<P>
<UL>
<LI>
<STRONG>protected int error_line, error_column;</STRONG>
<BR>
The line and column where the error was detected.
<P>
<LI>
<STRONG>protected String error_after;</STRONG>
<BR>
The partial string that has been read since the last successful token
match was performed.
<P>
<LI>
<STRONG>protected char curChar;</STRONG>
<BR>
The offending character.
</UL>

<hr>
<h1>JavaCC [tm]: JJTree</h1>
<hr>

<p>JJTree has two APIs: it adds some <a href="#jjtree-state">parser
methods</a>; and it requires all node objects to implement the <a
href="#jjtree-node">Node</a> interface.</p>

<h2><a name="jjtree-state">JJTree parser methods</a></h2>

<p>JJTree maintains some state in the parser object itself.  It
encapsulates all this state with an object that can be referred to via
the <code>jjtree</code> field.</p>

<p>The parser state implements an open stack where nodes are held
until they can be added to their parent node.  The <code>jjtree</code>
state object provides methods for you to manipulate the contents of
the stack in your actions if the basic JJTree mechanisms are not
sufficient.</p>

<dl>
      <dt><strong><code>void reset()</code></strong></dt>
      
      <dd>Call this to reinitialize the node stack.  All nodes
      currently on the stack are thrown away.  Don't call this from
      within a node scope, or terrible things will surely happen.</dd>

      <dt><strong><code>Node rootNode();</code></strong></dt>

      <dd>Returns the root node of the AST.  Since JJTree operates
      bottom-up, the root node is only defined after the parse has
      finished.</dd>

      <dt><strong><code>boolean nodeCreated();</code></strong></dt>

      <dd>Determines whether the current node was actually closed and
      pushed.  Call this in the final action within a conditional node
      scope.</dd>

      <dt><strong><code>int arity();</code></strong></dt>

      <dd>Returns the number of nodes currently pushed on the node
      stack in the current node scope.</dd>

      <dt><strong><code>void pushNode(Node n);</code></strong></dt>

      <dd>Pushes a node on to the stack.</dd>

      <dt><strong><code>Node popNode();</code></strong></dt>

      <dd>Returns the node on the top of the stack, and removes it from
      the stack.</dd>

      <dt><strong><code>Node peekNode();</code></strong></dt>

      <dd>Returns the node currently on the top of the stack.</dd>
    </dl>

<hr>

<h2>The <strong><code><a name="jjtree-node">Node</a></code></strong> interface</h2>

<p>All AST nodes must implement this interface.  It provides basic
machinery for constructing the parent and child relationships between
nodes.</p>

<dl>
      <dt><strong><code>public void jjtOpen();</code></strong></dt>

      <dd>This method is called after the node has been made the
      current node.  It indicates that child nodes can now be added to
      it.</dd>

      <dt><strong><code>public void jjtClose();</code></strong></dt>

      <dd>This method is called after all the child nodes have been
	added.</dd>

      <dt><strong><code>public void jjtSetParent(Node n);</code><br><code>public Node jjtGetParent();</code></strong></dt>

      <dd>This pair of methods is used to inform the node of its
      parent.</dd>

      <dt><strong><code>public void jjtAddChild(Node n, int i);</code></strong></dt>

      <dd>This method tells the node to add its argument to the node's
	list of children.</dd>

      <dt><strong><code>public Node jjtGetChild(int i);</code></strong></dt>

      <dd>This method returns a child node.  The children are numbered
	 from zero, left to right.</dd>

      <dt><strong><code>int jjtGetNumChildren();</code></strong></dt>

      <dd>Return the number of children the node has.</dd>

</dl>

</BODY>
</HTML>