JJTree Reference DocumentationIntroductionJJTree is a preprocessor for JavaCC that inserts parse tree building actions at various places in the JavaCC source. The output of JJTree is run through JavaCC to create the parser. This document describes how to use JJTree, and how you can interface your parser to it. By default JJTree generates code to construct parse tree nodes for each nonterminal in the language. This behaviour can be modified so that some nonterminals do not have nodes generated, or so that a node is generated for a part of a production's expansion. JJTree defines a Java interface Node that all parse tree nodes must implement. The interface provides methods for operations such as setting the parent of the node, and for adding children and retrieving them. JJTree operates in one of two modes, simple and multi (for want of better terms). In simple mode each parse tree node is of concrete type SimpleNode; in multi mode the type of the parse tree node is derived from the name of the node. If you don't provide implementations for the node classes JJTree will generate sample implementations based on SimpleNode for you. You can then modify the implementations to suit. Although JavaCC is a top-down parser, JJTree constructs the parse tree from the bottom up. To do this it uses a stack where it pushes nodes after they have been created. When it finds a parent for them, it pops the children from the stack and adds them to the parent, and finally pushes the new parent node itself. The stack is open, which means that you have access to it from within grammar actions: you can push, pop and otherwise manipulate its contents however you feel appropriate. See Node Scopes and User Actions below for more important information. JJTree provides decorations for two basic varieties of nodes, and some syntactic shorthand to make their use convenient.
WARNING: node descriptor expression should not have side-effects. JJTree doesn't specify how many times the expression will be evaluated. By default JJTree treats each nonterminal as an indefinite node and derives the name of the node from the name of its production. You can give it a different name with the following syntax:
void P1() #MyNode : { ... } { ... }
When the parser recognizes a If you want to suppress the creation of a node for a production you can use the following syntax:
void P2() #void : { ... } { ... }
Now any parse tree nodes pushed by nonterminals in the
expansion of
void P3() : {}
{
P4() ( P5() )+ P6()
}
In this example, an indefinite node
void P3() : {}
{
P4() ( P5() )+ #ListOfP5s P6()
}
Now the Node Scopes and User ActionsEach node is associated with a node scope. User actions within
this scope can access the node under construction by using the
special identifier A scope is the expansion unit immediately preceding the node decoration. This can be a parenthesized expression. When the production signature is decorated (perhaps implicitly with the default node), the scope is the entire right hand side of the production including its declaration block. You can also use an expression involving
... ( jjtThis.my_foo = foo() ) #Baz ...
Here The final user action in a node scope is different from all the
others. When the code within it executes, the node's children
have already been popped from the stack and added to the node,
which has itself been pushed onto the stack. The children can
now be accessed via the node's methods such as
User actions other than the final one can only access the children on the stack. They have not yet been added to the node, so they aren't available via the node's methods. A conditional node that has a node descriptor expression that
evaluates to false will not get added to the stack, nor have
children added to it. The final user action within a
conditional node scope can determine whether the node was
created or not by calling the Exception handlingAn exception thrown by an expansion within a node scope that is not caught within the node scope is caught by JJTree itself. When this occurs, any nodes that have been pushed on to the node stack within the node scope are popped and thrown away. Then the exception is rethrown. The intention is to make it possible for parsers to implement error recovery and continue with the node stack in a known state. WARNING: JJTree currently cannot detect whether exceptions are thrown from user actions within a node scope. Such an exception will probably be handled incorrectly. Node Scope HooksIf the
void jjtreeOpenNodeScope(Node n)
void jjtreeCloseNodeScope(Node n)
If the parser is One use for these functions is to store the node's first and last tokens so that the input can be easily reproduced again. For example:
void jjtreeOpenNodeScope(Node n)
{
((MySimpleNode)n).first_token = getToken(1);
}
void jjtreeCloseNodeScope(Node n)
{
((MySimpleNode)n).last_token = getToken(0);
}
where
Token first_token, last_token;
Another use might be to store the parser object itself in the node so that state that should be shared by all nodes produced by that parser can be provided. For example, the parser might maintain a symbol table. The Life Cycle of a NodeA node goes through a well determined sequence of steps as it is built. This is that sequence viewed from the perspective of the node itself:
Visitor SupportJJTree provides some basic support for the visitor design
pattern. If the The name of the visitor interface is constructed by appending
OptionsJJTree supports the following options on the command line and in the JavaCC options statement:
JJTree stateJJTree keeps its state in a parser class field called
final class JJTreeState {
/* Call this to reinitialize the node stack. */
void reset();
/* Return the root node of the AST. */
Node rootNode();
/* Determine whether the current node was actually closed and
pushed */
boolean nodeCreated();
/* Return the number of nodes currently pushed on the node
stack in the current node scope. */
int arity();
/* Push a node on to the stack. */
void pushNode(Node n);
/* Return the node on the top of the stack, and remove it from the
stack. */
Node popNode();
/* Return the node currently on the top of the stack. */
Node peekNode();
}
Node Objects
/* All AST nodes must implement this interface. It provides basic
machinery for constructing the parent and child relationships
between nodes. */
public interface Node {
/** This method is called after the node has been made the current
node. It indicates that child nodes can now be added to it. */
public void jjtOpen();
/** This method is called after all the child nodes have been
added. */
public void jjtClose();
/** This pair of methods are used to inform the node of its
parent. */
public void jjtSetParent(Node n);
public Node jjtGetParent();
/** This method tells the node to add its argument to the node's
list of children. */
public void jjtAddChild(Node n, int i);
/** This method returns a child node. The children are numbered
from zero, left to right. */
public Node jjtGetChild(int i);
/** Return the number of children the node has. */
int jjtGetNumChildren();
}
The class
{
((SimpleNode)jjtree.rootNode()).dump(">");
}
The Another utility method is generated if the VISITOR options is set:
{
public void childrenAccept(MyParserVisitor visitor);
}
This walks over the node's children in turn, asking them to accept the visitor. This can be useful when implementing preorder and postorder traversals. ExamplesJJTree is distributed with some simple examples
containing a grammar that parses arithmetic expressions. See
the file There is also an interpreter for a simple language that uses
JJTree to build the program represention. See the file
A grammar for HTML 3.2 is also included in the distribution.
See Information about an example using the visitor support is in
|