public interface Aast
extends antlr.collections.AST
Modifier and Type | Method and Description |
---|---|
boolean |
absolutePath(java.lang.String path)
Compares this node's complete path from the root node (down to and
including the current node) with the specified path.
|
boolean |
ancestor(int level,
int type)
Searches the AST's ancestors for an exact token type match.
|
boolean |
ancestor(int level,
int[] types)
Searches the AST's ancestors for a token type that matches any of a
given list of token types.
|
boolean |
ancestor(int level,
int lower,
int upper)
Searches the AST's ancestors for a token type that matches a given
range of token types (inclusively).
|
int |
annotationCount(java.lang.String key,
java.lang.Object value)
Returns the number of annotation objects of an array annotation that are
equal to the specified
Object . |
java.util.Iterator<java.lang.String> |
annotationKeys()
Get an iterator on the keys for all annotations (if any) stored in this
AST.
|
int |
annotationSize(java.lang.String key)
Returns the size of an array annotation as indexed by an arbitrary key.
|
void |
brainwash(java.lang.String filename)
Clear all IDs of an AST and register it under a new filename.
|
void |
clearAnnotations()
Removes ALL annotations from this AST.
|
void |
clearIds()
Clears (sets to
null ) the unique ID of this node and all
descendant nodes using recursion. |
boolean |
compareWith(Aast other)
Compare subtree starting from
this node as a root and
compare it with given subtree. |
boolean |
compareWith(Aast other,
boolean ignoreCase)
Compare subtree starting from
this node as a root and
compare it with given subtree. |
boolean |
descendant(int level,
int type)
Searches the AST's descendants for an exact token type match.
|
boolean |
descendant(int level,
int[] types)
Searches the AST's descendants for a token type that matches any of a
given list of token types.
|
boolean |
descendant(int level,
int[] types,
java.lang.String key,
java.lang.Object match,
java.lang.Integer index)
Searches the AST's descendants for a token type that matches any of a given list of token
types and for each found, matches the given value for an annotation.
|
boolean |
descendant(int level,
int lower,
int upper)
Searches the AST's descendants for a token type that matches a given
range of token types (inclusively).
|
boolean |
descendant(int level,
int lower,
int upper,
java.lang.String key,
java.lang.Object match,
java.lang.Integer index)
Searches the AST's descendants for a token type that matches a given range of token types
(inclusively), and for each found, matches the given value for an annotation.
|
boolean |
downPath(java.lang.String path)
Determines if this node's path downward matches the specified
path, on a case-insensitive basis.
|
java.lang.String |
dumpTree()
Create a human readable text representation of the tree rooted at this
AST.
|
java.lang.String |
dumpTree(boolean annotations)
Create a human readable text representation of the tree rooted at this AST.
|
Aast |
duplicate()
Creates a deep copy of the original, including all descendant ASTs.
|
Aast |
duplicate(java.util.Map<java.lang.Long,Aast> idMap)
Creates a deep copy of the original, including all descendant ASTs.
|
Aast |
duplicateFresh()
Creates a deep copy of the original, including all descendant ASTs.
|
Aast |
duplicateFresh(java.util.Map<java.lang.Long,Aast> idMap)
Creates a deep copy of the original, including all descendant ASTs.
|
Aast |
getAncestor(int level)
Get the ancestor node at the specified number of levels of ancestry,
if it exists.
|
Aast |
getAncestor(int level,
int type)
Get the first ancestor node of a specified type found in a walk up to
the maximum specified number of levels of ancestry, if such a node
exists.
|
Aast |
getAncestor(int level,
int type,
java.lang.String key,
java.lang.Object value)
Get the first ancestor node of the specified type which also has a
particular annotation with the specified value.
|
Aast |
getAncestor(int level,
java.util.List<java.lang.Integer> types)
Get the first ancestor node of the specified types found in a walk up to the maximum
specified number of levels of ancestry, if such a node exists.
|
java.lang.Object |
getAnnotation(java.lang.String key)
Retrieve an annotation.
|
java.lang.Object |
getAnnotation(java.lang.String key,
int index)
Retrieve an element in an array annotation using the specified key as
a unique identifier and an index to specify the location in the array
from which to read the element.
|
java.util.List<java.lang.Object> |
getAnnotationList(java.lang.String key)
Retrieve an unmodifiable list view of an array annotation.
|
Aast |
getChildAt(int index)
Search the immediate children for the one at the specified index.
|
int |
getDepth()
Get the level of nesting of this AST from the root AST, where
0 indicates the root, and a positive number indicates
generations from the root. |
java.lang.String |
getDescriptiveTokenText()
Returns a descriptive string for the current node.
|
java.lang.String |
getFilename()
Get the name of the source file associated with this AST
|
java.lang.Long |
getId()
Retrieve this AST's unique, persistent identifier.
|
default Aast |
getImmediateChild(Aast start,
java.lang.Integer... types)
Search the immediate children for one that matches any token type in
the specified Collection of types.
|
Aast |
getImmediateChild(java.util.Collection<java.lang.Integer> types,
Aast start)
Search the immediate children for one that matches any token type in
the specified Collection of types.
|
Aast |
getImmediateChild(int type,
Aast start)
Search the immediate children for one that matches a specific token
type.
|
int |
getIndexPos()
Returns the index position of this instance in the array of children
of its parent.
|
Aast |
getLastImmediateChild(int type)
Search the immediate children for last child that matches a specific
token type.
|
Aast |
getLeftAdjacent()
Search the tree to return the AST node that exists nearest on the left (in line/column).
|
Aast |
getLeftmost()
Search the sub-tree rooted at this node to return the AST node that exists farthest to the
left (in line/column).
|
ShadowNode |
getLeftmostShadow()
Access a shadow node that exists farthest to the left of the current node.
|
ShadowNode |
getLeftShadow()
Access a shadow node that exists to the left of the current node.
|
Aast |
getLeftShadowNode()
Access a shadow node that exists to the left of the current node.
|
TreeLocal |
getLocal()
Access the tree-local data directly.
|
int |
getNumChildren()
Get the total number of all descendants of this AST.
|
int |
getNumImmediateChildren()
Get the number of immediate child nodes of this AST.
|
int |
getNumImmediateChildren(int type)
Get the number of immediate child nodes of this AST that match a
specific token type.
|
int |
getNumLeftSiblings()
Returns the number of siblings to this node's left (before this node
in a tree walk).
|
int |
getNumRightSiblings()
Returns the number of siblings to this node's right (after this node
in a tree walk).
|
Aast |
getParent()
Get this AST's parent node, if any.
|
java.lang.String |
getPath()
Return a string representing the path of this AST from the root AST,
in terms of the token type of each element from the root to this AST.
|
Aast |
getPrevSibling()
Returns the sibling to the left of this node in the tree or
null if this instance is the first child of its parent. |
Aast |
getRightAdjacent()
Search the tree to return the AST node that exists nearest on the right (in line/column).
|
Aast |
getRightmost()
Search the sub-tree rooted at this node to return the AST node that exists farthest to the
right (in line/column).
|
ShadowNode |
getRightmostShadow()
Access a shadow node that exists farthest to the right of the current node.
|
ShadowNode |
getRightShadow()
Access a shadow node that exists to the right of the current node.
|
Aast |
getRightShadowNode()
Access a shadow node that exists to the right of the current node.
|
java.util.Iterator<ShadowNode> |
getShadowNodeList()
Access the list of all shadow nodes.
|
java.lang.String |
getSymbolicTokenType()
Returns the symbolic representation of this AST's token type.
|
void |
graft(Aast child)
Grafts a new child subtree onto this AST.
|
void |
graftAt(Aast child,
int index)
Grafts a new child subtree onto this AST at a specific 0-based child
index.
|
Aast |
graftCopyTo(Aast parent,
int[] validTokens)
Grafts a copy of this AST node onto the specified parent AST.
|
Aast |
graftCopyTo(Aast parent,
int[] validTokens,
boolean preserve)
Grafts a copy of this AST node onto the specified parent AST.
|
void |
intern()
Walk the tree formed by this node and all of its descendants, interning all strings stored
in the AST's text and annotation values which are
String objects. |
boolean |
isAncestorOf(int level,
Aast other)
Report whether this node is an ancestor of the given node.
|
boolean |
isAnnotation(java.lang.String key)
Determines if an annotation exists of any
String ,
Double , Long , Boolean or
List value, indexed by an arbitrary key. |
boolean |
isArtificial()
Reports on a node that was not generated by parsing text, but was created for some
structural purpose by the parser or by post-processing code.
|
boolean |
isHidden()
Get this AST's hidden status.
|
boolean |
isLeaf()
Indicate whether this AST node represents a leaf node in the tree (a
node with no children).
|
boolean |
isRoot()
Indicate whether this AST node represents the root of its hierarchy.
|
java.util.Iterator<Aast> |
iterator()
Return an iterator to walk this AST recursively in a depth-first
traversal.
|
java.util.Iterator<Aast> |
iterator(int maxLevels,
AstWalkListener listener)
Return an iterator to walk this AST recursively in a depth-first
traversal.
|
java.util.Iterator<Aast> |
iterator(int maxLevels,
AstWalkListener listener,
boolean honorHidden)
Return an iterator to walk this AST recursively in a depth-first
traversal.
|
java.lang.String |
lookupTokenName(int type)
Translates an integer value of a token type into the associated
human readable text representation.
|
int |
lookupTokenType(java.lang.String tokenName)
Translates a text representation of a token type into the
actual integer value.
|
boolean |
matchAnnotation(java.lang.String key,
java.lang.Object match,
java.lang.Integer index)
Indicate whether this AST has an annotation which matches the specified conditions.
|
void |
move(Aast parent,
int index)
Move the node from one location to another.
|
Aast |
nearestEnclosing(Aast other)
Find and return the nearest ancestor of the current instance which also
encloses the node passed as a parameter.
|
void |
putAnnotation(java.lang.String key,
java.lang.Boolean annotation)
Store a boolean annotation using the specified key as a unique
identifier.
|
void |
putAnnotation(java.lang.String key,
java.lang.Boolean annotation,
int index)
Store a boolean element in an array annotation using the
specified key as a unique identifier and an index to specify the
location in which to insert.
|
void |
putAnnotation(java.lang.String key,
java.lang.Double annotation)
Store a floating point numeric annotation using the specified key as a
unique identifier.
|
void |
putAnnotation(java.lang.String key,
java.lang.Double annotation,
int index)
Store a floating point numeric element in an array annotation using the
specified key as a unique identifier and an index to specify the
location in which to insert.
|
void |
putAnnotation(java.lang.String key,
java.util.List<java.lang.Object> annotation)
Store a list of annotations at once using the specified key as a unique
identifier.
|
void |
putAnnotation(java.lang.String key,
java.lang.Long annotation)
Store an integral numeric annotation using the specified key as a
unique identifier.
|
void |
putAnnotation(java.lang.String key,
java.lang.Long annotation,
int index)
Store an integral numeric element in an array annotation using the
specified key as a unique identifier and an index to specify the
location in which to insert.
|
void |
putAnnotation(java.lang.String key,
java.lang.String annotation)
Store a text annotation using the specified key as a unique identifier.
|
void |
putAnnotation(java.lang.String key,
java.lang.String annotation,
int index)
Store a text element in an array annotation using the specified key as
a unique identifier and an index to specify the location in which to
insert.
|
void |
putAnnotationObject(java.lang.String key,
java.lang.Object annotation)
Store any object as annotation for this node.
|
boolean |
relativePath(java.lang.String path)
Determines if this node's path from the root ends with the
specified path, on a case-insensitive basis.
|
void |
remove()
Remove this AST (and the entire sub-tree rooted at this node) from its
parent's collection of children.
|
java.lang.Object |
removeAnnotation(java.lang.String key)
Remove a specific annotation from this AST.
|
java.lang.Object |
removeAnnotation(java.lang.String key,
int index)
Remove a specific element from the array annotation in this AST.
|
void |
setColumn(int column)
Set the source file column number for this node.
|
void |
setHidden(boolean hide)
Set this AST's hidden status.
|
boolean |
setId(java.lang.Long id)
Set this AST's unique, persistent identifier.
|
void |
setLine(int line)
Set the source file line number for this node.
|
void |
setLocal(TreeLocal local)
Set the tree-local data directly.
|
void |
setParent(Aast parent)
Set this Aast's parent node.
|
boolean |
sibling(long type)
Test whether any of this node's siblings has the given token type.
|
java.lang.String |
toStringVerbose()
Create a verbose string representation of this AST.
|
boolean |
upPath(java.lang.String path)
Determines if this node's path upward matches the specified
path, on a case-insensitive basis.
|
addChild, equals, equalsList, equalsListPartial, equalsTree, equalsTreePartial, findAll, findAllPartial, getColumn, getFirstChild, getLine, getNextSibling, getNumberOfChildren, getText, getType, initialize, initialize, initialize, setFirstChild, setNextSibling, setText, setType, toString, toStringList, toStringTree
void setLine(int line)
line
- New line number to associate with this node.void setColumn(int column)
column
- New column number to associate with this node.int lookupTokenType(java.lang.String tokenName)
tokenName
- The text representation of the token type.java.lang.String lookupTokenName(int type)
type
- The integer token type.null
if
no match was found.Aast graftCopyTo(Aast parent, int[] validTokens, boolean preserve) throws AstException
validTokens
), all
child nodes of the copy which do not match a valid token type
are removed from the copy node, before it is grafted onto the parent.
All necessary parent and ID fixups are performed on the copy to
integrate it with its new parent tree.parent
- AST node which will become the direct parent of the grafted
copy of this node.validTokens
- Optional array of valid token types. If not null
,
only those children of the copy node which match a valid token
type are allowed to remain. All other child nodes are removed
from the copy.preserve
- true
to preserve line and column information in
the duplicated tree.AstException
- if any error occurs registering the grafted node with the AST
registry.Aast graftCopyTo(Aast parent, int[] validTokens) throws AstException
validTokens
), all
child nodes of the copy which do not match a valid token type
are removed from the copy node, before it is grafted onto the parent.parent
- AST node which will become the direct parent of the grafted
copy of this node.validTokens
- Optional array of valid token types. If not null
,
only those children of the copy node which match a valid token
type are allowed to remain. All other child nodes are removed
from the copy.AstException
- if any error occurs registering the grafted node with the AST
registry.void graft(Aast child) throws AstException
child
- AST subtree to add as a child of this node.AstException
- if any error occurs registering the grafted node with the AST
registry.void graftAt(Aast child, int index) throws AstException
child
- AST subtree to add as a child of this node.index
- 0 to insert as the first child, -1 to insert as the last
child or a 0-based index to specify an exact child index
at which to insert the new child. All current children at
that index or at a greater index, are moved right. If the
index is greater than the current number of children, the
new child will be added at the end.AstException
- if any error occurs registering the grafted node with the AST
registry.Aast duplicate()
null
if there is any
exception during the copy.Aast duplicate(java.util.Map<java.lang.Long,Aast> idMap)
idMap
- Map of IDs to ASTs. May be null
.Aast duplicateFresh()
All unique IDs of this new sub-tree are cleared before this method
returns (see clearIds()
).
null
if there is any
exception during the copy.Aast duplicateFresh(java.util.Map<java.lang.Long,Aast> idMap)
All unique IDs of this new sub-tree are cleared before this method
returns (see clearIds()
).
idMap
- Map of IDs to ASTs. May be null
.null
if there is any
exception during the copy.void clearIds()
null
) the unique ID of this node and all
descendant nodes using recursion. Warning: this is very dangerous so
you have better know what you are doing!void brainwash(java.lang.String filename) throws AstException
This would be done in order to safely save a copy AST under a different filename than the source AST. It is necessary in order to avoid having two ASTs registered to the same filename and ID in the AST registry.
filename
- New filename under which the AST is registered.AstException
- if any error occurs registering AST or applying fixups.boolean compareWith(Aast other)
this
node as a root and
compare it with given subtree. Subtrees considered identical if both
contain identical nodes organized in the same order. Two nodes
considered identical if their type and text are identical. The order of
subtrees is defined by iterator provided by iterator() method.
The comparison of token text should be case sensitive. For a case
insensitive comparison, use the compareWith(Aast,boolean)
method variant.
other
- The subtree to compare with.true
if subtrees are identical and
false
otherwise.boolean compareWith(Aast other, boolean ignoreCase)
this
node as a root and
compare it with given subtree. Subtrees considered identical if both
contain identical nodes organized in the same order. Two nodes
considered identical if their type and text are identical. The order of
subtrees is defined by iterator provided by iterator() method.other
- The subtree to compare with.ignoreCase
- true
to ignore case in the token text comparison;
false
for a case sensitive comparison.true
if subtrees are identical and
false
otherwise.java.lang.Long getId()
null
return from this method generally indicates an
invalid AST.null
if no ID has been assigned.boolean setId(java.lang.Long id)
Normally, it would be better to set this value during construction. However, we do not have control over the construction process when this AST is instantiated by ANTLR during parsing, so it is done early in post-processing instead.
id
- This AST's assigned ID.true
if the ID was set; false
if it
could not be set because it had previously been set.boolean isRoot()
true
if this node is the tree root, else
false
.boolean isLeaf()
true
if this node has no children, else
false
.boolean isArtificial()
true
if this is an artificial node.Aast getParent()
null
if this node represents the
root of a hierarchy.void setParent(Aast parent)
parent
- Parent Aast node.boolean isHidden()
true
if this node should be hidden during
iterator based walks (in which the iterator is specified to
honor the hidden mode).void setHidden(boolean hide)
hide
- true
if this node should be hidden during
iterator based walks (in which the iterator is specified to
honor the hidden mode).int getIndexPos()
Aast getPrevSibling()
null
if this instance is the first child of its parent.
This method is much slower than its counterpart
getNextSibling
since each node does not maintain a
reference back to the previous node. Thus, the parent node must
be involved and this extra processing slows the resulting
implementation.
null
if this node is the
first child (or has no parent).Aast getAncestor(int level)
level
- Number of generations up the tree to walk to obtain the
ancestor. Set to -1
to obtain the tree root,
0
is the current node, 1
is the
parent, 2
is the 'grandparent' and so forth.null
if no such node exists (if level
specified is
greater than depth of the tree).Aast getAncestor(int level, int type)
level
- Number of generations up the tree to walk to obtain the
ancestor. Set to -1
to obtain the tree root,
0
is the current node, 1
is the
parent, 2
is the 'grandparent' and so forth.type
- The token type of the ancestor to find.null
if no such node exists (if level
specified is
greater than depth of the tree).Aast getAncestor(int level, java.util.List<java.lang.Integer> types)
level
- Maximum number of generations up the tree to search for an ancestor. Set to
-1
to search up to the tree root, 0
for the current node, 1
for the parent, 2
for the 'grandparent' and so forth.types
- The token types of the ancestor to find.null
if no such node exists (if
level
specified is greater than depth of the tree).Aast getAncestor(int level, int type, java.lang.String key, java.lang.Object value)
null
value is provided, then the existence alone of an annotation with the
specified key is considered a match. The search walks up the tree from
this node to the maximum specified number of levels of ancestry.level
- Number of generations up the tree to walk to obtain the
ancestor. Set to -1
to obtain the tree root,
0
is the current node, 1
is the
parent, 2
is the 'grandparent' and so forth.type
- The token type of the ancestor to find.key
- Annotation key to match.value
- Annotation value to match. null
to match any
node which has an annotation with the specified key,
regardless of its value.null
if no such node exists (if level
specified is
greater than depth of the tree).boolean ancestor(int level, int type)
level
- Maximum number of generations up the tree to search for an
ancestor. Set to -1
to search up to the tree
root, 0
for the current node, 1
for
the parent, 2
for the 'grandparent' and so forth.type
- Token type to be matched.true
if type
was found as a
ancestor's token type within level
generations, else false
.boolean ancestor(int level, int lower, int upper)
level
- Maximum number of generations up the tree to search for an
ancestor. Set to -1
to search up to the tree
root, 0
for the current node, 1
for
the parent, 2
for the 'grandparent' and so forth.lower
- Lower boundary of the token type range.upper
- Upper boundary of the token type range.true
if a ancestor's token type was found to
match a range of types within level
generations,
else false
.boolean ancestor(int level, int[] types)
level
- Maximum number of generations up the tree to search for an
ancestor. Set to -1
to search up to the tree
root, 0
for the current node, 1
for
the parent, 2
for the 'grandparent' and so forth.types
- The list of token types for which to search.true
if a ancestor's token type was found to
match any of the given list of types within level
generations, else false
.boolean descendant(int level, int type)
level
- Number of generations to search before abandoning the test.
Set to 0
to search exhaustively.type
- Token type to be matched.true
if type
was found as a
descendant's token type within level
generations, else false
.boolean descendant(int level, int lower, int upper)
level
- Number of generations to search before abandoning the test.
Set to 0
to search exhaustively.lower
- Lower boundary of the token type range.upper
- Upper boundary of the token type range.true
if a descendant's token type was found to
match a range of types within level
generations,
else false
.boolean descendant(int level, int lower, int upper, java.lang.String key, java.lang.Object match, java.lang.Integer index)
level
- Number of generations to search before abandoning the test. Set to 0
to
search exhaustively.lower
- Lower boundary of the token type range.upper
- Upper boundary of the token type range.key
- Key of the annotation to match. If null
, only the token types are used as
match criteria.match
- Value of the annotation to match. Ignored if key
is null
. Must be
the same data type as the annotation being searched.index
- Zero-based index of the annotation, if the annotation is part of a list.
Set to -1
to test all elements of an annotation list.
Set to null
for a scalar annotation.true
if a descendant's token type was found to match a range of types
and an optional annotation was found to match within level
generations,
else false
.boolean descendant(int level, int[] types)
level
- Number of generations to search before abandoning the test.
Set to 0
to search exhaustively.types
- The list of token types for which to search.true
if a descendant's token type was found to
match any of the given list of types within level
generations, else false
.boolean descendant(int level, int[] types, java.lang.String key, java.lang.Object match, java.lang.Integer index)
level
- Number of generations to search before abandoning the test.
Set to 0
to search exhaustively.types
- The list of token types for which to search.key
- Key of the annotation to match. If null
, only the token types are used as
match criteria.match
- Value of the annotation to match. Ignored if key
is null
. Must be
the same data type as the annotation being searched.index
- Zero-based index of the annotation, if the annotation is part of a list.
Set to -1
to test all elements of an annotation list.
Set to null
for a scalar annotation.true
if a descendant's token type was found to match any of the given
list of types and an optional annotation was matched within level
generations, else false
.boolean matchAnnotation(java.lang.String key, java.lang.Object match, java.lang.Integer index)
The match succeeds if an annotation exists with the given key
and match
value. If index
is not null
, the annotation must exist in an annotation
list and the annotation element at the given index
must match the given match
value.
The match fails under the following conditions without raising an error:
key
;key
, but it does not match the given
value
;index
is a positive value that is out-of-bounds for the annotation list;index
is not null
and the annotation is scalar.key
- The key under which to check for an annotation. May not be null
.match
- An object to match as the annotation's value. Must be the same data type as the
annotation, such that a comparison using equals
will determine whether
the annotation matches. May not be null
.index
- Non-negative, zero-based index of the annotation, if it is part of a list.
Set to null
for a scalar annotation.
Set to -1
to check all elements of a list for a match.true
if a matching annotation exists, else false
.boolean sibling(long type)
type
- Token type to match.true
if any of this node's siblings match, else
false
.int getNumLeftSiblings()
getIndexPos()
.int getNumRightSiblings()
boolean isAncestorOf(int level, Aast other)
level
- The number of generations to search before abandoning the test.
Set to 0
to search exhaustively.other
- The node whose ancestry will be tested.true
if this node is an ancestor of
other
.boolean absolutePath(java.lang.String path)
path
- Root-to-current path, formatted as described in
getPath()
.true
if specified path matches this node's path
exactly, else false
.boolean relativePath(java.lang.String path)
This node's type IS included in this path, which is different from the
upPath(java.lang.String)
which compares paths upward starting at the parent
node.
path
- Partial path from this node up to an arbitrary number of
parent nodes, formatted as described in getPath()
.true
if specified path matches the end of this
node's path exactly, else false
.boolean upPath(java.lang.String path)
The type of the current node is NOT included in the up path. This
is the only difference between this method and relativePath(java.lang.String)
.
path
- Partial path from this node's parent upward to an arbitrary
number of ancestor nodes, formatted as described in
getPath()
.true
if specified path exactly matches the
upward path from this node's parent, else false
.boolean downPath(java.lang.String path)
true
.
The format of the 'segments' of the down path starts with the immediate child's type and each subsequent segment must be the type of the next child down in the hierarchy. The type of the current node is NOT included in the down path.
path
- Partial path from this node down to an arbitrary number
of descendant nodes, formatted as described in getPath()
.true
if specified path exactly matches the
downward path from this node, else false
.Aast nearestEnclosing(Aast other)
other
- Another reference node in the same tree.null
if
the two AST nodes are not in the same tree.Aast getImmediateChild(int type, Aast start)
null
, then the search will start with the first
child.type
- The token type of the child for which to search.start
- The child from which to start the search or null
if the search is to start with the first child.null
if no match was found.Aast getImmediateChild(java.util.Collection<java.lang.Integer> types, Aast start)
types
collection.
An optional starting child AST can be provided which allows a search
to be made for matches subsequent to the first, if the start AST is
null
, then the search will start with the first child.types
- Collection of token types of the child for which to search.start
- The child from which to start the search or null
if the search is to start with the first child.null
if no match was found.default Aast getImmediateChild(Aast start, java.lang.Integer... types)
types
collection.
An optional starting child AST can be provided which allows a search
to be made for matches subsequent to the first, if the start AST is
null
, then the search will start with the first child.types
- Collection of token types of the child for which to search.start
- The child from which to start the search or null
if the search is to start with the first child.null
if no match was found.Aast getChildAt(int index)
null
.index
- The 0-based index at which to search.null
if no
such index exists.void remove()
This method has no effect if invoked on the root node of an AST.
void move(Aast parent, int index) throws AstException
Aast
nodes must be the same
between the current node and the parent node, otherwise the results
will be undefined.
If the given parent node is null
and the current parent
node of this instance is null
, this method returns
immediately since there is nothing to do.
parent
- The parent node which is the target of the move operation or
null
if the move is only affecting the index
position of this node (a move of the child to a different
index in the same parent).index
- 0 to insert as the first child, -1 to insert as the last
child or a 0-based index to specify an exact child index
at which to insert the new child. All current nodes at
that index or at a greater index, are moved right. If the
index is greater than the current number of nodes, the node
will be added at the end.AstException
int getDepth()
0
indicates the root, and a positive number indicates
generations from the root.int getNumImmediateChildren()
int getNumImmediateChildren(int type)
type
- The token type of the child nodes to search for.Aast getLastImmediateChild(int type)
type
- The token type of the child for which to search.null
if no match was found.int getNumChildren()
java.lang.String getFilename()
null
if no name has yet
been assigned.java.lang.String getPath()
BLOCK/STATEMENT/KW_IF/represents the following path:
ROOT [type=BLOCK] | NODE A [type=STATEMENT] | NODE B [type=KW_IF]The string uniquely identifies the path from this node back to the root, but is not necessarily unique when traversed from the root to this node.
java.lang.String getSymbolicTokenType()
java.lang.String getDescriptiveTokenText()
java.lang.String dumpTree()
java.lang.String dumpTree(boolean annotations)
annotations
- Verbose mode. If true
dump the annotations along with node name and type.Aast getLeftmost()
this
if there are
no children.Aast getRightmost()
this
if there are
no children.Aast getLeftAdjacent()
null
if there are
no nodes on the left.Aast getRightAdjacent()
null
if there are
no nodes on the right.Aast getLeftShadowNode()
null
if no such node exists.Aast getRightShadowNode()
null
if no such node exists.ShadowNode getLeftShadow()
null
if no such node exists.ShadowNode getRightShadow()
null
if no such node exists.ShadowNode getLeftmostShadow()
null
if no such node exists.ShadowNode getRightmostShadow()
null
if no such node exists.java.util.Iterator<ShadowNode> getShadowNodeList()
null
if none exist.TreeLocal getLocal()
null
if there is no
tree-local data.void setLocal(TreeLocal local)
local
- The tree-local data or null
if there is no
tree-local data.java.util.Iterator<Aast> iterator()
This iterator will not support any "non-visiting" events (descent, ascent and next-child). In addition, all nodes will be returned, regardless of hidden status.
java.util.Iterator<Aast> iterator(int maxLevels, AstWalkListener listener)
The iterator will walk at most to a node depth of maxLevels
relative to this node. A maxLevels
value of 0
indicates that the full tree beneath this node should be walked, down
to every leaf, regardless of its depth.
If a listener
is specified, it will be notified when the
tree walk transitions between nesting levels. The notifications occur
during processing of the iterator's next
method. In each
case (whether the transition represents a descent to a lower tree level
or an ascent to a higher tree level), the parent of the parent/child
link being traversed will be sent with the notification. No more than
a single descent notification will ever be sent during a single
invocation of the iterator's next
method. However,
multiple ascent notifications may be sent, since the tree walk may
proceed directly from a deeply nested node to the next sibling of a
distant ancestor node. In such a case, one call to the listener's
AstWalkListener.ascent(com.goldencode.ast.Aast)
method will be made for each upward
step from child to parent, until an ancestor with an unvisited sibling
is found, or the walk ends.
This iterator will return all nodes in the tree, regardless of hidden status.
maxLevels
- Maximum number of levels or generations to visit relative to
the root defined by ast
. If the tree contains
more levels than maxLevels
, the levels beyond a
relative depth of maxLevels
will be ignored. Set
to 0
to disable this restriction. Set to
1
for immediate children only, etc.listener
- An optional listener which is notified of significant events
during the tree walk, such as descents to lower nesting levels,
moves between children (next-child events) and ascents back up
to higher nesting levels. This may be null
if
these "non-visiting" events are not needed.java.util.Iterator<Aast> iterator(int maxLevels, AstWalkListener listener, boolean honorHidden)
The iterator will walk at most to a node depth of maxLevels
relative to this node. A maxLevels
value of 0
indicates that the full tree beneath this node should be walked, down
to every leaf, regardless of its depth.
If a listener
is specified, it will be notified when the
tree walk transitions between nesting levels. The notifications occur
during processing of the iterator's next
method. In each
case (whether the transition represents a descent to a lower tree level
or an ascent to a higher tree level), the parent of the parent/child
link being traversed will be sent with the notification. No more than
a single descent notification will ever be sent during a single
invocation of the iterator's next
method. However,
multiple ascent notifications may be sent, since the tree walk may
proceed directly from a deeply nested node to the next sibling of a
distant ancestor node. In such a case, one call to the listener's
AstWalkListener.ascent(com.goldencode.ast.Aast)
method will be made for each upward
step from child to parent, until an ancestor with an unvisited sibling
is found, or the walk ends.
Optionally, the returned iterator can omit nodes in which the hidden
status is enabled (see isHidden()
and setHidden(boolean)
).
Please note that if the root node (the instance upon which this method
is called) is set as hidden
, this setting will
not
be honored. The hidden
mode is only
honored on child nodes that have this mode set.
maxLevels
- Maximum number of levels or generations to visit relative to
the root defined by ast
. If the tree contains
more levels than maxLevels
, the levels beyond a
relative depth of maxLevels
will be ignored. Set
to 0
to disable this restriction. Set to
1
for immediate children only, etc.listener
- An optional listener which is notified of significant events
during the tree walk, such as descents to lower nesting levels,
moves between children (next-child events) and ascents back up
to higher nesting levels. This may be null
if
these "non-visiting" events are not needed.honorHidden
- If true
, the hidden
attribute of
the node will be honored. This means that the node will not
appear in the iterator nor will any "non-visiting" events be
triggered for such nodes.boolean isAnnotation(java.lang.String key)
String
,
Double
, Long
, Boolean
or
List
value, indexed by an arbitrary key.key
- Key under which the annotation is stored.true
if an annotation exists mapped by that key.int annotationSize(java.lang.String key)
key
- Key under which the annotation is stored.int annotationCount(java.lang.String key, java.lang.Object value)
Object
.key
- Key under which the annotation is stored.value
- Object
to compare with.java.lang.Object getAnnotation(java.lang.String key)
String
,
Double
, Long
, or Boolean
value,
indexed by an arbitrary key. Note that it is possible to obtain the
entire array if the annotation is an array type. This would be a
List
of objects of the above mentioned types.key
- Key under which the annotation is stored.null
if none exists.java.lang.Object getAnnotation(java.lang.String key, int index)
String
, Double
, Long
, or
Boolean
value.key
- Key under which the annotation is stored.index
- The index of -1 indicates the last element of the array.
Otherwise this is the explicit zero-based index at which to
find the annotation.null
if the annotation
doesn't exist, if the annotation is not an array or if no
element exists at the given index.java.util.List<java.lang.Object> getAnnotationList(java.lang.String key)
key
- Key under which the annotation is stored.null
if no such
annotation exists.void putAnnotation(java.lang.String key, java.lang.String annotation)
key
- Key under which to store the annotation.annotation
- Arbitrary text.void putAnnotation(java.lang.String key, java.lang.String annotation, int index)
key
- Key under which to store the annotation.index
- The index of -1 indicates an addition to the end of the array.
Otherwise this is the explicit zero-based index at which to
add the annotation.annotation
- Arbitrary text.void putAnnotation(java.lang.String key, java.lang.Double annotation)
key
- Key under which to store the annotation.annotation
- Arbitrary floating point numeric value.void putAnnotation(java.lang.String key, java.lang.Double annotation, int index)
key
- Key under which to store the annotation.index
- The index of -1 indicates an addition to the end of the array.
Otherwise this is the explicit zero-based index at which to
add the annotation.annotation
- Arbitrary floating point numeric value.void putAnnotation(java.lang.String key, java.lang.Long annotation)
key
- Key under which to store the annotation.annotation
- Arbitrary integral numeric value.void putAnnotation(java.lang.String key, java.lang.Long annotation, int index)
key
- Key under which to store the annotation.index
- The index of -1 indicates an addition to the end of the array.
Otherwise this is the explicit zero-based index at which to
add the annotation.annotation
- Arbitrary integral numeric value.void putAnnotation(java.lang.String key, java.lang.Boolean annotation)
key
- Key under which to store the annotation.annotation
- Arbitrary boolean value.void putAnnotation(java.lang.String key, java.lang.Boolean annotation, int index)
key
- Key under which to store the annotation.index
- The index of -1 indicates an addition to the end of the array.
Otherwise this is the explicit zero-based index at which to
add the annotation.annotation
- Arbitrary boolean value.void putAnnotation(java.lang.String key, java.util.List<java.lang.Object> annotation)
String
Double
Long
Boolean
key
- Key under which to store the annotation.annotation
- list of annotations of the same, supported type.void putAnnotationObject(java.lang.String key, java.lang.Object annotation)
InMemoryRegistryPlugin
since this is the only plugin that does not truly
serialize the nodes.key
- The name of the annotation.annotation
- The value for the annotation. Any type of object can be stored as long it is not
required to be saved.java.lang.Object removeAnnotation(java.lang.String key)
List
) or it may be a
scalar value.key
- Key under which the annotation is stored.null
if none
was found.java.lang.Object removeAnnotation(java.lang.String key, int index)
key
- Key under which the annotation is stored.index
- The index of -1 indicates an addition to the end of the array.
Otherwise this is the explicit zero-based index at which to
add the annotation.null
if the
annotation doesn't exist, if the annotation is not an array or
if no element exists at the given index.void clearAnnotations()
java.util.Iterator<java.lang.String> annotationKeys()
null
.void intern()
String
objects.
Since all these objects must be retrieved and re-stored, this method will be expensive for a large tree. It should only be invoked on trees which will remain in long term memory.
java.lang.String toStringVerbose()