polyglot.visit
Class NodeVisitor

java.lang.Object
  extended by polyglot.visit.NodeVisitor
Direct Known Subclasses:
AlphaRenamer, ClassSerializer, CodeCleaner, ConstantFolder, DumpAst, FlattenVisitor, HaltingVisitor, NodeScrambler, NodeScrambler.FirstPass

public abstract class NodeVisitor
extends java.lang.Object

The NodeVisitor represents an implementation of the "Visitor" style of tree traversal. There is a convention among polyglot visitors which states that traversals will lazily reconstruct the tree. That is, the AST is functionally "modified" by creating new nodes on each traversal, but only when necessary-- only when nodes (or their children) are actually changed. Up to three seperate calls into the visitor may be invoked for each AST node. override allows the visitor to redefine the entire traversal for a particular subtree. enter notifies the visitor that traversal of a particular subtree has begun. leave informs the visitor that traversal is finishing a particular subtree.

See Also:
Node.visit(polyglot.visit.NodeVisitor), Node

Constructor Summary
NodeVisitor()
           
 
Method Summary
 NodeVisitor begin()
          The begin method is called before the entire tree is visited.
 NodeVisitor enter(Node n)
          Begin normal traversal of a subtree rooted at n.
 NodeVisitor enter(Node parent, Node n)
          Begin normal traversal of a subtree rooted at n.
 void finish()
          The finish method is called after the entire tree has been visited.
 void finish(Node ast)
           
 Node leave(Node parent, Node old, Node n, NodeVisitor v)
          This method is called after all of the children of n have been visited.
 Node leave(Node old, Node n, NodeVisitor v)
          This method is called after all of the children of n have been visited.
 Node override(Node n)
          Given a tree rooted at n, the visitor has the option of overriding all traversal of the children of n.
 Node override(Node parent, Node n)
          Given a tree rooted at n, the visitor has the option of overriding all traversal of the children of n.
 java.lang.String toString()
           
 Node visitEdge(Node parent, Node child)
          Visit the edge between the parent node parent, and child node child.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

NodeVisitor

public NodeVisitor()
Method Detail

override

public Node override(Node parent,
                     Node n)
Given a tree rooted at n, the visitor has the option of overriding all traversal of the children of n. If no changes were made to n and the visitor wishes to prevent further traversal of the tree, then it should return n. If changes were made to the subtree, then the visitor should return a copy of n with appropriate changes. Finally, if the visitor does not wish to override traversal of the subtree rooted at n, then it should return null.

The default implementation of this method is to call override(n), as most subclasses do not need to know the parent of the node n.

Parameters:
parent - The parent of n, null if n has no parent.
n - The root of the subtree to be traversed.
Returns:
A node if normal traversal is to stop, null if it is to continue.

override

public Node override(Node n)
Given a tree rooted at n, the visitor has the option of overriding all traversal of the children of n. If no changes were made to n and the visitor wishes to prevent further traversal of the tree, then it should return n. If changes were made to the subtree, then the visitor should return a copy of n with appropriate changes. Finally, if the visitor does not wish to override traversal of the subtree rooted at n, then it should return null.

This method is typically called by the method override(parent, n). If a subclass overrides the method override(parent, n) then this method may not be called.

Parameters:
n - The root of the subtree to be traversed.
Returns:
A node if normal traversal is to stop, null if it is to continue.

enter

public NodeVisitor enter(Node parent,
                         Node n)
Begin normal traversal of a subtree rooted at n. This gives the visitor the option of changing internal state or returning a new visitor which will be used to visit the children of n.

The default implementation of this method is to call enter(n), as most subclasses do not need to know the parent of the node n.

Parameters:
parent - The parent of n, null if n has no parent.
n - The root of the subtree to be traversed.
Returns:
The NodeVisitor which should be used to visit the children of n.

enter

public NodeVisitor enter(Node n)
Begin normal traversal of a subtree rooted at n. This gives the visitor the option of changing internal state or returning a new visitor which will be used to visit the children of n.

This method is typically called by the method enter(parent, n). If a subclass overrides the method enter(parent, n) then this method may not be called.

Parameters:
n - The root of the subtree to be traversed.
Returns:
The NodeVisitor which should be used to visit the children of n.

leave

public Node leave(Node parent,
                  Node old,
                  Node n,
                  NodeVisitor v)
This method is called after all of the children of n have been visited. In this case, these children were visited by the visitor v. This is the last chance for the visitor to modify the tree rooted at n. This method will be called exactly the same number of times as entry is called. That is, for each node that is not overriden, enter and leave are each called exactly once.

Note that if old == n then the vistior should make a copy of n before modifying it. It should then return the modified copy.

The default implementation of this method is to call leave(old, n, v), as most subclasses do not need to know the parent of the node n.

Parameters:
parent - The parent of old, null if old has no parent.
old - The original state of root of the current subtree.
n - The current state of the root of the current subtree.
v - The NodeVisitor object used to visit the children.
Returns:
The final result of the traversal of the tree rooted at n.

leave

public Node leave(Node old,
                  Node n,
                  NodeVisitor v)
This method is called after all of the children of n have been visited. In this case, these children were visited by the visitor v. This is the last chance for the visitor to modify the tree rooted at n. This method will be called exactly the same number of times as entry is called. That is, for each node that is not overriden, enter and leave are each called exactly once.

Note that if old == n then the vistior should make a copy of n before modifying it. It should then return the modified copy.

This method is typically called by the method leave(parent, old, n v). If a subclass overrides the method leave(parent, old, n v) then this method may not be called.

Parameters:
old - The original state of root of the current subtree.
n - The current state of the root of the current subtree.
v - The NodeVisitor object used to visit the children.
Returns:
The final result of the traversal of the tree rooted at n.

begin

public NodeVisitor begin()
The begin method is called before the entire tree is visited. This method allows the visitor to perform any initialization that cannot be done when the visitor is created. If null is returned, the ast is not traversed.

Returns:
the NodeVisitor to traverse the ast with. If null is returned, the ast is not traversed.

finish

public void finish()
The finish method is called after the entire tree has been visited. This method allows the visitor to perform any last minute cleanup, including flushing buffers and I/O connections.


finish

public void finish(Node ast)

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

visitEdge

public Node visitEdge(Node parent,
                      Node child)
Visit the edge between the parent node parent, and child node child. This method recursively visits the subtree rooted at child.

Parameters:
parent - the parent node of child, null if child was visited by calling polyglot.ast.Node.visit(NodeVisitor) instead of Node.visitChild(Node, NodeVisitor).
child - the child node of parent to be visited.
Returns:
the (possibly new) version of child after the subtree rooted at child has been recursively visited.