A visitor for abstract syntax trees.
For each different concrete AST node type T there are a pair of methods:
public boolean visit(T node) - Visits the given node to perform some arbitrary operation. If true is returned, the given node's child nodes will be visited next; however, if false is returned, the given node's child nodes will not be visited. The default implementation provided by this class does nothing and returns true (with the exception of {@link #visit(Javadoc) ASTVisitor.visit(Javadoc)}). Subclasses may reimplement this method as needed.public void endVisit(T node) - Visits the given node to perform some arbitrary operation. When used in the conventional way, this method is called after all of the given node's children have been visited (or immediately, if visit returned false). The default implementation provided by this class does nothing. Subclasses may reimplement this method as needed.
In addition, there are a pair of methods for visiting AST nodes in the abstract, regardless of node type:
public void preVisit(ASTNode node) - Visits the given node to perform some arbitrary operation. This method is invoked prior to the appropriate type-specific visit method. The default implementation of this method does nothing. Subclasses may reimplement this method as needed.public void postVisit(ASTNode node) - Visits the given node to perform some arbitrary operation. This method is invoked after the appropriate type-specific endVisit method. The default implementation of this method does nothing. Subclasses may reimplement this method as needed.
For nodes with list-valued properties, the child nodes within the list are visited in order. For nodes with multiple properties, the child nodes are visited in the order that most closely corresponds to the lexical reading order of the source program. For instance, for a type declaration node, the child ordering is: name, superclass, superinterfaces, and body declarations.
While it is possible to modify the tree in the visitor, care is required to ensure that the consequences are as expected and desirable. During the course of an ordinary visit starting at a given node, every node in the subtree is visited exactly twice, first with visit and then with endVisit. During a traversal of a stationary tree, each node is either behind (after endVisit), ahead (before visit), or in progress (between visit and the matching endVisit). Changes to the "behind" region of the tree are of no consequence to the visit in progress. Changes to the "ahead" region will be taken in stride. Changes to the "in progress" portion are the more interesting cases. With a node, the various properties are arranged in a linear list, with a cursor that separates the properties that have been visited from the ones that are still to be visited (the cursor is between the elements, rather than on an element). The cursor moves from the head to the tail of this list, advancing to the next position just before visit if called for that child. After the child subtree has been completely visited, the visit moves on the child immediately after the cursor. Removing a child while it is being visited does not alter the course of the visit. But any children added at positions after the cursor are considered in the "ahead" portion and will be visited.
Cases to watch out for:
- Moving a child node further down the list. This could result in the child subtree being visited multiple times; these visits are sequential.
- Moving a child node up into an ancestor. If the new home for the node is in the "ahead" portion, the subtree will be visited a second time; again, these visits are sequential.
- Moving a node down into a child. If the new home for the node is in the "ahead" portion, the subtree will be visited a second time; in this case, the visits will be nested. In some cases, this can lead to a stack overflow or out of memory condition.
Note that {@link LineComment} and {@link BlockComment} nodes arenot normally visited in an AST because they are not considered part of main structure of the AST. Use {@link CompilationUnit#getCommentList()} to find these additionalcomments nodes.
@see org.eclipse.jdt.core.dom.ASTNode#accept(ASTVisitor)