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
#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
LineComment and
BlockComment nodes are
not normally visited in an AST because they are not considered
part of main structure of the AST. Use
CompilationUnit#getCommentList() to find these additional
comments nodes.