jjtree.html

This a JavaCC documentation.

      maintain a symbol table.</p>

    <h3>The Life Cycle of a Node</h3>

    <p>A 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:</p>

    <ol>
      <li>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 <i>parser</i>TreeConstants.java that 
	declares valid constants.  The names of constants are derived
	by prepending JJT to the uppercase names of nodes, with dot 
	symbols (&quot;.&quot;) replaced by underscore symbols 
	(&quot;_&quot;).  For convenience, an array of <code>String</code>s 
	called <code>jjtNodeName[]</code> that maps the constants to the 
	unmodified names of nodes is maintained in the same file.</li>

      <li>the node's <code>jjtOpen()</code> method is called.</li>

      <li>if the option <code>NODE_SCOPE_HOOK</code> is set, the
	user-defined parser method <code>openNodeScope()</code> 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.</li>

      <li>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 <code>closeNodeHook()</code> will not be called
	with it as a parameter.</li>

      <li>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
	<code>closeNodeHook()</code> might be called with it as a
	parameter.</li>

      <li>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.</li>

      <li>the node's <code>jjtClose()</code> method is called.</li>

      <li>the node is pushed on the stack.</li>

      <li>if the option <code>NODE_SCOPE_HOOK</code> is set, the
	user-defined parser method <code>closenNodeScope()</code> is
	called and passed the node as its parameter.</li>

      <li>if the node is not the root node, it is added as a child of
	another node and its <code>jjtSetParent()</code> method is
	called.</li>
    </ol>

    <h3>Visitor Support</h3>

    <p>JJTree provides some basic support for the visitor design
      pattern.  If the <code>VISITOR</code> option is set to true
      JJTree will insert an <code>jjtAccept()</code> 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.</p>

    <p>The name of the visitor interface is constructed by appending
      <code>Visitor</code> 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.</p>


    <h3>Options</h3>

    <p>JJTree supports the following options on the command
      line and in the JavaCC options statement:</p>

    <dl>
      <dt><code>BUILD_NODE_FILES</code> (default:
	<code>true</code>)</dt>
      <dd>Generate sample implementations for SimpleNode and any other
	nodes used in the grammar.</dd>

      <dt><code>MULTI</code> (default: <code>false</code>)</dt>
      <dd> Generate a multi mode parse tree.  The default for this is
	false, generating a simple mode parse tree.</dd>

      <dt><code>NODE_DEFAULT_VOID</code> (default:
	<code>false</code>)</dt>
      <dd>Instead of making each non-decorated production an
	indefinite node, make it void instead.</dd>

      <dt><code>NODE_FACTORY</code> (default: <code>false</code>)</dt>

      <dd>Use a factory method with following signature to construct
	nodes:

	<br><code>public static Node jjtCreate(int id)</code>
      </dd>

      <dt><code>NODE_PACKAGE</code> (default: <code>""</code>)</dt>

      <dd> The package to generate the node classes into.  The default
	for this is the parser package.</dd>

      <dt><code>NODE_PREFIX</code> (default: <code>"AST"</code>)</dt>

      <dd>The prefix used to construct node class names from node
	identifiers in multi mode.  The default for this is AST.</dd>

      <dt><code>NODE_SCOPE_HOOK</code> (default:
	<code>false</code>)</dt>

      <dd>Insert calls to user-defined parser methods on entry and
	exit of every node scope.  See <a href="#hooks">Node Scope
	  Hooks above</a>.</dd>
      
      <dt><code>NODE_USES_PARSER</code> (default:
	<code>false</code>)</dt>

      <dd>JJTree will use an alternate form of the node construction
	routines where it passes the parser object in.  For example,
	<pre> public static Node MyNode.jjtCreate(MyParser p, int id);
	  MyNode(MyParser p, int id); </pre>
      </dd>

      <dt><code>STATIC</code> (default: <code>true</code>)</dt>

      <dd>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.</dd>

      <dt><code>VISITOR</code> (default: <code>false</code>)</dt>

      <dd>Insert a <code>jjtAccept()</code> method in the node
	classes, and generate a visitor implementation with an entry
	for every node type used in the grammar.</dd>

      <dt><code>VISITOR_EXCEPTION</code> (default:
	<code>""</code>)</dt>

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

      <dt><code>JJTREE_OUTPUT_DIRECTORY</code> (default:
	use value of <code>OUTPUT_DIRECTORY</code>)</dt>

      <dd>By default, JJTree generates its output in the directory
      specified in the global <code>OUTPUT_DIRECTORY</code> setting.
      Explicitly setting this option allows the user to separate the
      parser from the tree files.</dd>
    </dl>


    <h3>JJTree state</h3>

    <p>JJTree keeps its state in a parser class field called
      <code>jjtree</code>.  You can use methods in this member to
      manipulate the node stack.</p>
    
    <pre>
    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();
    }
    </pre>


    <h3>Node Objects</h3>

    <pre>
    /* 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();
    }
    </pre>

    <p>The class <code>SimpleNode</code> implements the
      <code>Node</code> 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.  <code>SimpleNode</code> additionally
      provides a rudimentary mechanism for recursively dumping the
      node and its children.  You might use this is in action like
      this:</p>

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

    </pre>

    <p>The <code>String</code> parameter to <code>dump()</code> is
      used as padding to indicate the tree hierarchy.</p>

    <p>Another utility method is generated if the VISITOR options is set:</p>
    <pre>
    {
        public void childrenAccept(MyParserVisitor visitor);
    }
    </pre>

    <p>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.</p>

    <h3>Examples</h3>

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

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

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

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

</BODY>
</HTML>