Documentation for JTB 1.0

Introduction

If you are converting to a newer version of JTB, please see the release notes for the new version.
 

Overview of Generated Files

• The file jtb.out.jj, the original grammar file, now with syntax tree building actions inserted.
• The subdirectory/package syntaxtree which contains a java class for each production in the grammar.
• The subdirectory/package visitor which contains Visitor.java, the default visitor superclass.

Let's take a look at all the files and directories JTB generates.
 

jtb.out.jj

syntaxtree

Let's examine one of the classes generated from a production.  Take, for example, the following production (from the Java1.1.jj grammar):
 

void ImportDeclaration() :
{}
{
  "import" Name() [ "." "*" ] ";"
}

 

//
// Generated by JTB 0.9.0a
//

//
// Grammar production:
// f0 -> "import"
// f1 -> Name()
// f2 -> [ "." "*" ]
// f3 -> ";"
//
package syntaxtree;

public class ImportDeclaration implements Node {
   public NodeToken f0;
   public Name f1;
   public NodeOptional f2;
   public NodeToken f3;

   public ImportDeclaration(NodeToken n0, Name n1,
   NodeOptional n2, NodeToken n3) {
      f0 = n0;
      f1 = n1;
      f2 = n2;
      f3 = n3;
   }

   public void accept(visitor.Visitor v) {
      v.visit(this);
   }
}

The first set of comments obviously shows which version of JTB created this file.  The second group of comments is for your benefit, showing the names of the fields of this class (the children of the node), and what parts of the original production they represent.   All parts of a production are represented in the tree, including tokens.

Notice the that this class is in the package "syntaxtree".  The purpose of separating the generated tree node classes into their own package is that it greatly simplifies file organization, particularly when the grammar contains a large number of productions.  If the grammar is stable and not subject to change, once these classes are generated and compiled, it's not necessary to pay them any more attention.  All of the work is to done to the visitor classes.

Next you'll note that this class implements an interface named Node.  This is one of seven tree node classes automatically generated for every grammar.  These classes are as follows:
 

Next comes the member variables of the ImportDeclaration class.  These are generated based on the RHS of the production.  Their type depends on the various items in the RHS and their names begin with f0 and work their way up.  You may be wondering why these variables are declared as public.  Since the visitors which must access these fields reside in a different package than the syntax tree nodes, package visibility cannot be used.  We decided that breaking encapsulation was a necessary evil in this case.

The next portion of the generated class is the constructor.  It is called from the tree-building actions in the annotated grammar so you will probably not need to use it.

Last is the accept() method.  This method is the way in which visitors interact with the class.
 

visitor

Our intent is for the programmer to only have to override those methods for which specific actions must be performed.  For example, in a visitor which simply counts the number of assignment statments in a Java source file, only the overloaded method visit(Assignment n) would need to be modified.

Continuing our above example is the visit(ImportDeclaration n) method of class Visitor:

//
// f0 -> "import"
// f1 -> Name()
// f2 -> [ "." "*" ]
// f3 -> ";"
//
public void visit(ImportDeclaration n) {
   n.f0.accept(this);
   n.f1.accept(this);
   n.f2.accept(this);
   n.f3.accept(this);
}

The Automatically Generated Classes

Node

public interface Node {
   public void accept(visitor.Visitor v);
}

NodeChoice

( "abstract" | "final" | "public" )

void ResultType() : {}
{
  "void" | Type()
}

public class NodeChoice implements Node {
   public NodeChoice(Node node, int whichChoice);
   public void accept(visitor.Visitor v);

   public Node choice;
   public int which;
}

NodeList

( "[" Expression() "]" )+

void ArrayDimensions() :
{}
{
  ( "[" Expression() "]" )+ ( "[" "]" )*
}

public class NodeList implements Node {
   public NodeList();
   public void addNode(Node n);
   public Enumeration elements();
   public Node elementAt(int i);
   public int size();
   public void accept(visitor.Visitor v);

   public Vector nodes;
}

• addNode() is used by the tree-building code to add nodes to the list.
• elements() is similar to the method of the same name in Vector, returning an Enumeration of the elements in the list.
• elementAt() returns the node at the ith position in the list (starting at 0, naturally).
• size() returns the number of elements in the list.

NodeListOptional

( ImportDeclaration() )*

public class NodeListOptional implements Node {
   public NodeListOptional();
   public void addNode(Node n);
   public Enumeration elements();
   public Node elementAt(int i);
   public int size();
   public boolean present();
   public void accept(visitor.Visitor v);

   public Vector nodes;
}

NodeOptional

[ "." "*" ]

void ImportDeclaration() : {}
{
  "import" Name() [ "." "*" ] ";"
}

public class NodeOptional implements Node {
   public NodeOptional();
   public void addNode(Node n);
   public void accept(visitor.Visitor v);
   public boolean present();

   public Node node;
}

NodeSequence

[ "extends" Name() ]

public class NodeSequence implements Node {
   public NodeSequence();
   public void addNode(Node n);
   public Node elementAt(int i);
   public Enumeration elements();
   public int size();
   public void accept(visitor.Visitor v);

   public Vector nodes;
}

NodeToken

public class NodeToken implements Node {
   public NodeToken(String s);
   public String toString();
   public void accept(visitor.Visitor v);

   public String tokenImage;
}

JTB Command-Line Options

Still have questions?  Suggestions on improving this document?  Feel free to mail Wanjun Wang or Jens Palsberg.

Back