/projects/javacc-5.0/www/doc/apiroutines.html
HTML | 552 lines | 473 code | 48 blank | 31 comment | 0 complexity | 24ef648269074348f145dea63daeb19f MD5 | raw file
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
- <html xmlns="http://www.w3.org/1999/xhtml">
- <!--
- Copyright (c) 2006, Sun Microsystems, Inc.
- All rights reserved.
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions are met:
- * Redistributions of source code must retain the above copyright notice,
- this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions and the following disclaimer in the
- documentation and/or other materials provided with the distribution.
- * Neither the name of the Sun Microsystems, Inc. nor the names of its
- contributors may be used to endorse or promote products derived from
- this software without specific prior written permission.
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
- AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
- LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
- CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
- SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
- INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
- CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
- ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
- THE POSSIBILITY OF SUCH DAMAGE.
- -->
- <head>
- <title>JavaCC API Documentation</title>
- <!-- Changed by: Michael Van De Vanter, 14-Jan-2003 -->
- </head>
- <body bgcolor="#FFFFFF" >
- <h1>JavaCC [tm]: API Routines</h1>
- <p>
- This web page is a comprehensive list of all classes, methods,
- and variables available for use by a JavaCC [tm] user. These classes,
- methods, and variables are typically used from the actions that
- are embedded in a JavaCC grammar. In the sample code used below,
- it is assumed that the name of the generated parser is "TheParser".
- </p>
- <h3>Non-Terminals in the Input Grammar</h3>
- <p>
- For each non-terminal NT in the input grammar file, the following method
- is generated into the parser class:
- </p>
- <ul>
- <li>
- <strong><em>returntype</em> NT(<em>parameters</em>) throws ParseException;</strong>
- </li>
- </ul>
- <p>
- Here, <em>returntype</em> and <em>parameters</em> are what were specified
- in the JavaCC input file in the definition of NT (where NT occurred on the
- left-hand side).
- </p>
- <p>
- When this method is called, the input stream is parsed to match this non-terminal.
- On a successful parse, this method returns normally. On detection of a parse
- error, an error message is displayed and the method returns by throwing an exception
- of the type ParseException.
- </p>
- <p>
- <em>Note that all non-terminals in a JavaCC input grammar have equal status;
- it is possible to parse to any non-terminal by calling the non-terminal's method.
- </em>
- </p>
- <h3>API for Parser Actions</h3>
- <ul>
- <li><strong> Token token;</strong>
- <br />
- This variable holds the last token consumed by the parser and can be used
- in parser actions. This is <em>exactly</em> the same as the token returned by
- <em>getToken(0)</em>.
- </li>
- </ul>
- <p>
- In addition, the two methods - <em><a href="#getToken">getToken(int i)</a></em> and
- <em><a href="#getNextToken">getNextToken()</a></em> can also be used in
- actions to traverse the token list.
- </p>
- <h3>The Token Manager Interface</h3>
- <p>
- Typically, the token manager interface is not to be used. Instead all access
- must be made through the parser interface. However, in certain situations -
- such as if you are not building a parser and building only the token manager -
- the token manager interface is useful.
- The token manager provides the following routine:
- </p>
- <ul>
- <li>
- <strong>Token getNextToken() throws ParseError;</strong>
- </li>
- </ul>
- <p>
- Each call to this method returns the next token in the input stream. This
- method throws a ParseError exception when there is a lexical error, i.e.,
- it could not find a match for any of the specified tokens from the input
- stream. The type Token is described later.
- </p>
- <h3>Constructors and Other Initialization Routines</h3>
- <ul>
- <li>
- <strong>TheParser.TheParser(java.io.InputStream stream)</strong>
- <br />
- This creates a new parser object, which in turn creates a new token manager object
- that reads its tokens from "stream". This constructor is available only
- when both the options USER_TOKEN_MANAGER and USER_CHAR_STREAM are false.
- If the option STATIC is true, this constructor (along with other constructors)
- can be called exactly once to create a single parser object.
- </li>
- <li>
- <strong>TheParser.TheParser(CharStream stream)</strong>
- <br />
- Similar to the previous constructor, except that this one is available only
- when the option USER_TOKEN_MANAGER is false and USER_CHAR_STREAM is true.
- </li>
- <li>
- <strong>void TheParser.ReInit(java.io.InputStream stream)</strong>
- <br />
- This reinitializes an existing parser object. In addition, it also reinitializes
- the existing token manager object that corresponds to this parser object. The result
- is a parser object with the exact same functionality as one that was created
- with the constructor above. The only difference is that new objects are not
- created. This method is available only
- when both the options USER_TOKEN_MANAGER and USER_CHAR_STREAM are false.
- If the option STATIC is true, this (along with the other ReInit methods)
- is the only way to restart a parse operation
- for there is only one parser and all one can do is reinitialize it.
- </li>
- <li>
- <strong>void TheParser.ReInit(CharStream stream)</strong>
- <br />
- Similar to the previous method, except that this one is available only
- when the option USER_TOKEN_MANAGER is false and USER_CHAR_STREAM is true.
- </li>
- <li>
- <strong>TheParser(TheParserTokenManager tm)</strong>
- This creates a new parser object which uses an already created token manager object "tm" as
- its token manager. This constructor is only available if option USER_TOKEN_MANAGER is
- false. If the option STATIC is true, this constructor (along with other constructors)
- can be called exactly once to create a single parser object.
- </li>
- <li>
- <strong>TheParser(TokenManager tm)</strong>
- <br />
- Similar to the previous constructor, except that this one is available only
- when the option USER_TOKEN_MANAGER is true.
- </li>
- <li>
- <strong>void TheParser.ReInit(TheParserTokenManager tm)</strong>
- <br />
- This reinitializes an existing parser object with the token manager object "tm" as its
- new token manager. This method is only available if option USER_TOKEN_MANAGER is
- false. If the option STATIC is true, this (along with the other ReInit methods)
- is the only way to restart a parse operation
- for there is only one parser and all one can do is reinitialize it.
- </li>
- <li>
- <strong>void TheParser.ReInit(TokenManager tm)</strong>
- <br />
- Similar to the previous method, except that this one is available only
- when the option USER_TOKEN_MANAGER is true.
- </li>
- <li>
- <strong>TheParserTokenManager.TheParserTokenManager(CharStream stream)</strong>
- <br />
- Creates a new token manager object initialized to read input from "stream". When
- the option STATIC is true, this constructor may be called only once.
- This is available only when USER_TOKEN_MANAGER is false and USER_CHAR_STREAM
- is true. When USER_TOKEN_MANAGER is false and USER_CHAR_STREAM is false (the default situation),
- a constructor similar to the one above is available with the type CharStream
- replaced as follows:
- <ul>
- <li>
- When JAVA_UNICODE_ESCAPE is false and UNICODE_INPUT is false, CharStream is
- replaced by ASCII_CharStream.
- </li>
- <li>
- When JAVA_UNICODE_ESCAPE is false and UNICODE_INPUT is true, CharStream is
- replaced by UCode_CharStream.
- </li>
- <li>
- When JAVA_UNICODE_ESCAPE is true and UNICODE_INPUT is false, CharStream is
- replaced by ASCII_UCodeESC_CharStream.
- </li>
- <li>
- When JAVA_UNICODE_ESCAPE is true and UNICODE_INPUT is true, CharStream is
- replaced by UCode_UCodeESC_CharStream.
- </li>
- </ul>
- </li>
- <li>
- <strong>void TheParserTokenManager.ReInit(CharStream stream)</strong>
- <br />
- Reinitializes the current token manager object to read input from "stream". When
- the option STATIC is true, this is the only way to restart a token manager operation.
- This is available only when USER_TOKEN_MANAGER is false and USER_CHAR_STREAM
- is true. When USER_TOKEN_MANAGER is false and USER_CHAR_STREAM is false (the default situation),
- a constructor similar to the one above is available with the type CharStream
- replaced as follows:
- <ul>
- <li>
- When JAVA_UNICODE_ESCAPE is false and UNICODE_INPUT is false, CharStream is
- replaced by ASCII_CharStream.
- </li>
- <li>
- When JAVA_UNICODE_ESCAPE is false and UNICODE_INPUT is true, CharStream is
- replaced by UCode_CharStream.
- </li>
- <li>
- When JAVA_UNICODE_ESCAPE is true and UNICODE_INPUT is false, CharStream is
- replaced by ASCII_UCodeESC_CharStream.
- </li>
- <li>
- When JAVA_UNICODE_ESCAPE is true and UNICODE_INPUT is true, CharStream is
- replaced by UCode_UCodeESC_CharStream.
- </li>
- </ul>
- </li>
- </ul>
- <h3>The Token Class</h3>
- <p>
- The Token class is the type of token objects that are created by the token manager
- after a successful scanning of the token stream. These token objects are then
- passed to the parser and are accessible to the actions in a JavaCC grammar usually
- by grabbing the return value of a token. The methods getToken and getNextToken
- described below also give access to objects of this type.
- </p>
- <p>
- Each Token object has the following fields and methods:
- </p>
- <ul>
- <li>
- <strong>int kind;</strong>
- <br />
- This is the index for this kind of token in the internal representation scheme
- of JavaCC. When tokens in the JavaCC input file are given labels, these labels
- are used to generate "int" constants that can be used in actions.
- The value 0 is always used to represent the predefined token <EOF>. A
- constant "EOF" is generated for convenience in the ...Constants file.
- </li>
- <li>
- <strong>int beginLine, beginColumn, endLine, endColumn;</strong>
- <br />
- These indicate the beginning and ending positions of the token as it appeared
- in the input stream.
- </li>
- <li>
- <strong>String image;</strong>
- <br />
- This represents the image of the token as it appeared in the input stream.
- </li>
- <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.
- <br />
- <br />
- 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.
- <br />
- <br />
- 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>.
- </li>
- <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.
- </li>
- <li>
- <strong>public Object getValue();</strong>
- <br />
- An optional attribute value of the Token.
- <br />
- Tokens which are not used as syntactic sugar will often contain
- meaningful values that will be used later on by the compiler or
- interpreter. This attribute value is often different from the image.
- Any subclass of Token that actually wants to return a non-null value can
- override this method as appropriate.
- </li>
- <li>
- <strong>static final Token newToken(int ofKind);</strong>
- <br />
- <strong>static final Token newToken(int ofKind, String image);</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).
- </li>
- </ul>
- <h3>Reading Tokens from the Input Stream</h3>
- <p>
- There are two methods available for this purpose:
- </p>
- <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.
- </li>
- <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>.
- </li>
- </ul>
- <h3>Working with Debugger Tracing</h3>
- <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>
- </li>
- <li>
- <strong>void TheParser.disable_tracing()</strong>
- </li>
- </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>
- <h3>Customizing Error Messages</h3>
- <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>
- <p>
- The parser contains the following method definition:
- </p>
- <ul>
- <li>
- <strong>protected void token_error() { ... }</strong>
- </li>
- </ul>
- 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:
- <ul>
- <li>
- <strong>protected int error_line, error_column;</strong>
- <br />
- The line and column where the error was detected.
- </li>
- <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.
- </li>
- <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.
- </li>
- </ul>
- <p>
- The lexer contains the following method definition:
- </p>
- <ul>
- <li>
- <strong>protected void LexicalError() { ... }</strong>
- </li>
- </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.
- </li>
- <li>
- <strong>protected String error_after;</strong>
- <br />
- The partial string that has been read since the last successful token
- match was performed.
- </li>
- <li>
- <strong>protected char curChar;</strong>
- <br />
- The offending character.
- </li>
- </ul>
- <hr />
- <h1>JavaCC [tm]: JJTree</h1>
- <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>