jjtreeintro.html

This a JavaCC documentation.

    void jjtreeCloseNodeScope(Node n)
    {
      ((MySimpleNode)n).last_token = getToken(0);
    }

where MySimpleNode is based on SimpleNode and has the following additional
fields:


    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 Node

A node goes through a well determined sequence of steps as it is built. The
following
is that sequence viewed from the perspective of the node itself:
     1. the node's constructor is called with a unique integer parameter. This
        parameter identifies the kind of node and is especially useful in
        simple mode. JJTree automatically generates a file called
        parserTreeConstants.java and declares Java constants for the node
        identifiers. It also declares an array of Strings called jjtNodeName[]
        which maps the identifier integers to the names of the nodes.
     2. the node's jjtOpen() method is called.
     3. if the option NODE_SCOPE_HOOK is set, the user-defined parser method
        openNodeScope() is called and passed the node as its parameter. This
        method can initialize fields in the node or call its methods. For
        example, it might store the node's first token in the node.
     4. if an unhandled exception is thrown while the node is being parsed
        then the node is abandoned. JJTree will never refer to it again. It
        will not be closed, and the user-defined node scope hook
        closeNodeHook() will not be called with it as a parameter.
     5. otherwise, if the node is conditional and its conditional expression
        evaluates to false then the node is abandoned. It will not be closed,
        although the user-defined node scope hook closeNodeHook() might be
        called with it as a parameter.
     6. otherwise, all of the children of the node as specified by the integer
        expression of a definite node, or all the nodes that were pushed on
        the stack within a conditional node scope are added to the node. The
        order they are added is not specified.
     7. the node's jjtClose() method is called.
     8. the node is pushed on the stack.
     9. if the option NODE_SCOPE_HOOK is set, the user-defined parser method
        closenNodeScope() is called and passed the node as its parameter.
    10. if the node is not the root node, it is added as a child of another
        node and its jjtSetParent() method is called.

Visitor Support

JJTree provides some basic support for the visitor design pattern. If the
VISITOR option is set to true, JJTree will insert an jjtAccept() method into
all of the node classes it generates, and also generate a visitor interface
that can be implemented and passed to the nodes to accept.

The name of the visitor interface is constructed by appending Visitor to the
name of the parser. The interface is regenerated every time that JJTree is
run, so that it accurately represents the set of nodes used by the
parser. This will cause compile time errors if the implementation class has
not been updated for the new nodes. This is a feature.

Options

JJTree 0.3pre4 supports the following options on the command line and in the
JavaCC options statement:

    BUILD_NODE_FILES (default: true)
      Generate sample implementations for SimpleNode and any other nodes used
      in the grammar.

    MULTI (default: false)
      Generate a multi mode parse tree. The default for this is false,
      generating a simple mode parse tree.

    NODE_DEFAULT_VOID (default: false)
      Instead of making each non-decorated production an indefinite node, make
      it void instead.

    NODE_FACTORY (default: false)
      Use a factory method with following signature to construct nodes:
      public static Node jjtCreate(int id)

    NODE_PACKAGE (default: "")
      The package to generate the node classes into. The default for this is
      the parser package.

    NODE_PREFIX (default: "AST")
      The prefix used to construct node class names from node identifiers in
      multi mode. The default for this is AST.

    NODE_SCOPE_HOOK (default: false)
      Insert calls to user-defined parser methods on entry and exit of every
      node scope. See Node Scope Hooks above.

    NODE_USES_PARSER (default: false)
      JJTree will use an alternate form of the node construction routines
      where it passes the parser object in. For example,

      public static Node MyNode.jjtCreate(MyParser p, int id);
      MyNode(MyParser p, int id);

    STATIC (default: true)
      Generate code for a static parser. The default for this is true. This
      must be used consistently with the equivalent JavaCC options. The value
      of this option is emitted in the JavaCC source.

    VISITOR (default: false)
      Insert a jjtAccept() method in the node classes, and generate a visitor
      implementation with an entry for every node type used in the grammar.

    VISITOR_EXCEPTION (default: "")
      If this option is set, it is used in the signature of the generated
      jjtAccept() methods and the visit() methods. Note: this option will be
      removed in a later version of JJTree. Don't use it if that bothers you.

JJTree state

JJTree keeps its state in a parser class field called jjtree. You can use
methods in this member to manipulate the node stack.


    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 implements the Node interface, and is automatically
generated by JJTree if it doesn't already exist. You can use this class as a
template or superclass for your node implementations, or you can modify it to
suit. SimpleNode additionally provides a rudimentary mechanism for recursively
dumping the node and its children. You might use this is in action like this:


    {
        ((SimpleNode)jjtree.rootNode()).dump(">");
    }

The String parameter to dump() is used as padding to indicate the tree
hierarchy.

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.

More Documentation

Jocelyn Paine has contributed a very nice introduction to JJTree where he
describes how he has used it to develop an extension to HTML for interactive
web pages: http://users.ox.ac.uk/~popx/jjtree.html

Examples

JJTree 0.3pre3 is distributed with some simple examples containing a grammar
that parses arithmetic expressions. See the file
examples/JJTreeExamples/README for further details.

There is also an interpreter for a simple language that uses JJTree to build
the program representation. See the file examples/Interpreter/README for more
information.

A grammar for HTML 3.2 is also included in the distribution. See
examples/HTMLGrammars/RobsHTML/README to find out more.

Information about an example using the visitor support is in
examples/VTransformer/README.
</pre>

</BODY>
</HTML>