public abstract class AnnotatedAst extends antlr.CommonAST implements Aast
setHidden(boolean)
flag can optionally be honored during
the walk, to bypass child nodes marked as hidden
. See
iterator(int,AstWalkListener,boolean)
.
Modifier and Type | Field and Description |
---|---|
private java.util.Map<java.lang.String,java.lang.Object> |
annotations
Map of annotation objects, indexed by name
|
private int |
column
Source file column number associated with this AST
|
private boolean |
hidden
Hidden mode which can be used to modify iterator based walking.
|
private java.lang.Long |
id
Unique, persistent identifier
|
private int |
line
Source file line number associated with this AST
|
private TreeLocal |
local
Tree-specific data (data that is shared by all nodes of a tree.
|
private Aast |
parent
Parent node to this node
|
private AnnotatedAst |
tail
Right-most child node, if any
|
Constructor and Description |
---|
AnnotatedAst()
Default constructor.
|
AnnotatedAst(antlr.Token token)
Constructor which accepts and wrappers token.
|
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.
|
void |
addChild(antlr.collections.AST node)
Add a child to the list of this node's children.
|
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 |
brainwash(java.lang.String filename,
boolean shadow)
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. |
private AnnotatedAst |
createNode(antlr.Token token,
Aast parent)
Create a new AST node of the same sub-class as the current node and
initialize it using the given token.
|
private void |
createShadowNodes(java.lang.Long fileId)
Check the annotations for the special
hidden-before and
hidden-after hidden token objects and create shadow nodes
from these tokens if they exist. |
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.
|
private void |
driveFixups(Aast child)
Kickoff the fixup process on a specific child to set IDs and ensure
that all parent linkages are correct.
|
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.
|
private void |
duplicateImpl(AnnotatedAst original,
java.util.Map<java.lang.Long,Aast> idMap)
Worker method to handle the core implementation of the 'deep copying'
in the copy rather than in the original AST.
|
private void |
extractTokenData(antlr.Token token)
Extract line number, column number and hidden previous/next token data
from the input token and store this information as member data.
|
void |
fixupParent(Aast parent)
Fixup the parent references for this tree.
|
void |
fixups(Aast parent,
java.lang.Long fileId)
Assigns parent nodes throughout the AST hierarchy of which this AST is
the root.
|
void |
fixups(Aast parent,
java.lang.Long fileId,
boolean shadow)
Assigns parent nodes throughout the AST hierarchy of which this AST is
the root.
|
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.
|
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 |
getColumn()
Get the source code column number which designates where in the source
code file the token wrappered by this node was found.
|
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 source code filename associated with the current node.
|
private Aast |
getFirstChild(boolean honorHidden)
Returns the first child (hidden or not) if the
honorHidden
flag is false , or the first non-hidden child if the
honorHidden flag is true . |
java.lang.Long |
getId()
Retrieve this AST's unique, persistent identifier.
|
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 |
getLeftShadowNode()
Access a shadow node that exists to the left of the current node.
|
int |
getLine()
Get the source code line number which designates where in the source
code file the token wrappered by this node was found.
|
TreeLocal |
getLocal()
Access the tree-local data directly.
|
private Aast |
getNextSibling(boolean honorHidden)
Returns the next sibling (hidden or not) if the
honorHidden
flag is false , or the next non-hidden sibling if the
honorHidden flag is true . |
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 Aast's parent node, if any.
|
private Aast[] |
getParentChain(Aast node)
Get chain of parent nodes starting from root to this node.
|
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.
|
private java.lang.String |
getPath(int max)
Return a string representing the path of this AST from an ancestor (possibly the root) AST,
in terms of the token type of each element from the ancestor 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 |
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.
|
abstract 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 |
initialize(antlr.collections.AST ast)
Initialize this node with the specified AST.
|
void |
initialize(antlr.Token token)
Initialize this node with the specified token.
|
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 |
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.
|
abstract java.lang.String |
lookupTokenName(int type)
Translates an integer value of a token type into the associated
human readable text representation.
|
abstract 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.
|
private void |
putAnnotationImpl(java.lang.String key,
java.lang.Object annotation)
Stores an annotation object under a unique key, creating the map of
annotations first, if necessary.
|
private boolean |
putAnnotationImpl(java.lang.String key,
java.lang.Object annotation,
int index)
Stores an annotation object in an array annotation under a unique key, creating both the
array itself and the map of annotations first, if necessary.
|
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 |
removeChildren()
Remove all child nodes.
|
private boolean |
searchDown(java.lang.String[] list,
int index)
Worker to recursively search down the descendant tree to match the
passed-in list of token names.
|
private boolean |
searchUp(java.lang.String source,
java.lang.String target)
Worker to compare the given source path (from root to a given node) to
the expected path to the target and return the comparison results.
|
void |
setColumn(int column)
Set the source file column number for this node.
|
void |
setFirstChild(antlr.collections.AST node)
Set the first child node of this AST.
|
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 |
setNextSibling(antlr.collections.AST node)
Set the next sibling to the right of this AST, replacing any such node already present
though fixups are not performed.
|
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 |
toString()
Create a string representation of this AST.
|
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.
|
decode, encode, equals, equalsList, equalsListPartial, equalsTree, equalsTreePartial, findAll, findAllPartial, getFirstChild, getNextSibling, getNumberOfChildren, getTokenNames, setVerboseStringConversion, toStringList, toStringTree, xmlSerialize, xmlSerializeNode, xmlSerializeRootClose, xmlSerializeRootOpen
private java.lang.Long id
private int line
private int column
private Aast parent
private AnnotatedAst tail
private boolean hidden
private java.util.Map<java.lang.String,java.lang.Object> annotations
private TreeLocal local
public AnnotatedAst()
public AnnotatedAst(antlr.Token token)
token
- Token upon which this node is based.public abstract int lookupTokenType(java.lang.String tokenName)
lookupTokenType
in interface Aast
tokenName
- The text representation of the token type.public abstract java.lang.String lookupTokenName(int type)
lookupTokenName
in interface Aast
type
- The integer token type.null
if
no match was found.public void removeChildren()
removeChildren
in class antlr.BaseAST
public void addChild(antlr.collections.AST node)
addChild
in interface antlr.collections.AST
addChild
in class antlr.BaseAST
node
- Child node to add to the end of the list of child nodes. If null
, the
method does nothing. If not null
, this object must be of type
AnnotatedAst
.public void setFirstChild(antlr.collections.AST node)
setFirstChild
in interface antlr.collections.AST
setFirstChild
in class antlr.BaseAST
node
- Child node to set as the first child of this AST. If null
, any existing
list of child nodes is removed. If not null
, this object must be of type
AnnotatedAst
.public void setNextSibling(antlr.collections.AST node)
setNextSibling
in interface antlr.collections.AST
setNextSibling
in class antlr.BaseAST
node
- Child node to set as the next sibling. If null
, any existing sibling
nodes to the right of this node are removed. If not null
, this object must
be of type AnnotatedAst
.public void setLine(int line)
public void setColumn(int column)
public 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.
All necessary parent and ID fixups are performed on the copy to
integrate it with its new parent tree.
The line and column numbers will be preserved in the duplicated tree.
graftCopyTo
in interface Aast
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.public 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.graftCopyTo
in interface Aast
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.public void graft(Aast child) throws AstException
graft
in interface Aast
child
- AST subtree to add as a child of this node.AstException
- if any error occurs registering the grafted node with the AST
registry.public void graftAt(Aast child, int index) throws AstException
graftAt
in interface Aast
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.public Aast duplicate()
public Aast duplicate(java.util.Map<java.lang.Long,Aast> idMap)
public Aast duplicateFresh()
All unique IDs of this new sub-tree are cleared before this method
returns (see clearIds()
).
duplicateFresh
in interface Aast
null
if there is any
exception during the copy.public 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()
).
duplicateFresh
in interface Aast
idMap
- Map of IDs to ASTs. May be null
.null
if there is any
exception during the copy.public 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!public 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.
No shadow nodes will be created using this version of the method. All hidden tokens will be dropped.
brainwash
in interface Aast
filename
- New filename under which the AST is registered.AstException
- if any error occurs registering AST or applying fixups.public void brainwash(java.lang.String filename, boolean shadow) 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.shadow
- true
to create shadow nodes from hidden tokens.
false
to drop hidden tokens without creating any
shadow nodes.AstException
- if any error occurs registering AST or applying fixups.public java.lang.Long getId()
null
return from this method generally indicates an
invalid AST.public boolean isRoot()
null
parent. Note that this will create false positives for an AST which
has not yet had its initial "fix-up" performed.public boolean isLeaf()
public 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.
public 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.
public int getDepth()
0
indicates the root, and a positive number indicates
generations from the root.public int getNumImmediateChildren()
getNumImmediateChildren
in interface Aast
public int getNumImmediateChildren(int type)
getNumImmediateChildren
in interface Aast
type
- The token type of the child nodes to search for.public int getNumChildren()
getNumChildren
in interface Aast
public void initialize(antlr.collections.AST ast)
ast
.initialize
in interface antlr.collections.AST
initialize
in class antlr.CommonAST
ast
- AST upon which this node is based. Expected to be an instance
of Aast
.public void initialize(antlr.Token token)
token
for later use in
line number and column queries.initialize
in interface antlr.collections.AST
initialize
in class antlr.CommonAST
token
- Token upon which this node is based.public Aast getParent()
public void setParent(Aast parent)
public boolean isHidden()
public void setHidden(boolean hide)
public int getIndexPos()
getIndexPos
in interface Aast
public 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.
getPrevSibling
in interface Aast
null
if this node is the
first child (or has no parent).public Aast getAncestor(int level)
getAncestor
in interface Aast
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).public Aast getAncestor(int level, int type)
getAncestor
in interface Aast
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
- The token type of the ancestor to find.null
if no such node exists (if level
specified is
greater than depth of the tree).public 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.getAncestor
in interface Aast
level
- Number of generations up the tree to walk to obtain the ancestor. Set to -1
to go up to the tree root, 0
only the current node, 1
is the
parent, 2
is the 'grandparent' and so forth.type
- The token type of the ancestor to find. Use 0
as wildcard to match all
nodes. In this case the key/value
combination will be used for filtering.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).public boolean ancestor(int level, int type)
ancestor
in interface Aast
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
.public boolean ancestor(int level, int lower, int upper)
ancestor
in interface Aast
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
.public boolean ancestor(int level, int[] types)
ancestor
in interface Aast
level
- Maximum number of generations up the tree to search for an
ancestor. Set to -1
to search up to the tree
root, 1
to search up to the parent, 2
2
to search up to 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
.public boolean descendant(int level, int type)
descendant
in interface Aast
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
.public boolean descendant(int level, int lower, int upper)
descendant
in interface Aast
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
.public boolean descendant(int level, int lower, int upper, java.lang.String key, java.lang.Object match, java.lang.Integer index)
descendant
in interface Aast
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
.public boolean descendant(int level, int[] types)
descendant
in interface Aast
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
.public boolean descendant(int level, int[] types, java.lang.String key, java.lang.Object match, java.lang.Integer index)
descendant
in interface Aast
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
.public 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.matchAnnotation
in interface Aast
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
.public boolean sibling(long type)
public int getNumLeftSiblings()
getIndexPos()
.getNumLeftSiblings
in interface Aast
public int getNumRightSiblings()
getNumRightSiblings
in interface Aast
public boolean isAncestorOf(int level, Aast other)
isAncestorOf
in interface Aast
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
, else false
. Returns
false
if this == other
.public boolean absolutePath(java.lang.String path)
absolutePath
in interface Aast
path
- Root-to-current path, formatted as described in
getPath()
.true
if specified path matches this node's path
exactly, else false
.public 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.
relativePath
in interface Aast
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
.public 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)
.
public 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.
public Aast nearestEnclosing(Aast other)
nearestEnclosing
in interface Aast
other
- Another reference node in the same tree.null
if
the two AST nodes are not in the same tree. If the two
references are identical (they are the same node), the
parent node will be returned (even if this is
null
due to the given node being the tree
root). Finally, if one node encloses the other, the
enclosing node will be returned.public Aast getChildAt(int index)
null
.getChildAt
in interface Aast
index
- The 0-based index at which to search.null
if no
such index exists.public Aast getImmediateChild(int type, Aast start)
null
, then the search will start with the first
child.getImmediateChild
in interface Aast
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.public 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.getImmediateChild
in interface Aast
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.public Aast getLastImmediateChild(int type)
getLastImmediateChild
in interface Aast
type
- The token type of the child for which to search.null
if no match was found.public void remove()
This method has no effect if invoked on the root node of an AST.
public 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.
move
in interface Aast
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
- if any error occurs registering the grafted node with the AST
registry.public java.lang.String getFilename()
AstManager
by this AST's
ID.getFilename
in interface Aast
null
if the ID is null
or invalid.public int getLine()
0
for an artificially manufactured AST (i.e., one
not generated by a parser).getLine
in interface antlr.collections.AST
getLine
in class antlr.BaseAST
0
for an artificial AST.getColumn()
public int getColumn()
0
for an artificially manufactured AST (i.e., one
not generated by a parser).getColumn
in interface antlr.collections.AST
getColumn
in class antlr.BaseAST
0
for an artificial AST.getLine()
public abstract java.lang.String getSymbolicTokenType()
getSymbolicTokenType
in interface Aast
public java.lang.String getDescriptiveTokenText()
getDescriptiveTokenText
in interface Aast
public 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. EXCEPTION: shadow nodes are NOT included in any tree walks and will NOT be returned by this iterator.
public 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. EXCEPTION: shadow nodes are NOT included in any tree walks and will NOT be returned by this iterator.
iterator
in interface Aast
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.public 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.
EXCEPTION: shadow nodes are NOT included in any tree walks and will NOT be returned by this iterator.
iterator
in interface Aast
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.public boolean isAnnotation(java.lang.String key)
String
,
Double
, Long
, Boolean
or
List
value, indexed by an arbitrary key.isAnnotation
in interface Aast
key
- Key under which the annotation is stored.true
if an annotation exists mapped by that key.public int annotationSize(java.lang.String key)
annotationSize
in interface Aast
key
- Key under which the annotation is stored.public int annotationCount(java.lang.String key, java.lang.Object value)
Object
.annotationCount
in interface Aast
key
- Key under which the annotation is stored.value
- Object
to compare with.public 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.getAnnotation
in interface Aast
key
- Key under which the annotation is stored.null
if none exists.public java.lang.Object getAnnotation(java.lang.String key, int index)
String
, Double
, Long
, or
Boolean
value.getAnnotation
in interface Aast
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.public java.util.List<java.lang.Object> getAnnotationList(java.lang.String key)
getAnnotationList
in interface Aast
key
- Key under which the annotation is stored.null
if no such
annotation exists.public void putAnnotation(java.lang.String key, java.lang.String annotation)
This is just a thin wrapper to ensure annotation type safety, since
annotations are stored in a Map
as Object
s.
putAnnotation
in interface Aast
key
- Key under which to store the annotation.annotation
- Arbitrary text.public void putAnnotation(java.lang.String key, java.lang.String annotation, int index)
putAnnotation
in interface Aast
key
- Key under which to store the annotation.annotation
- Arbitrary text.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.public void putAnnotation(java.lang.String key, java.lang.Double annotation)
This is just a thin wrapper to ensure annotation type safety, since
annotations are stored in a Map
as Object
s.
putAnnotation
in interface Aast
key
- Key under which to store the annotation.annotation
- Arbitrary floating point numeric value.public void putAnnotation(java.lang.String key, java.lang.Double annotation, int index)
putAnnotation
in interface Aast
key
- Key under which to store the annotation.annotation
- Arbitrary floating point numeric value.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.public void putAnnotation(java.lang.String key, java.lang.Long annotation)
This is just a thin wrapper to ensure annotation type safety, since
annotations are stored in a Map
as Object
s.
putAnnotation
in interface Aast
key
- Key under which to store the annotation.annotation
- Arbitrary integral numeric value.public void putAnnotation(java.lang.String key, java.lang.Long annotation, int index)
putAnnotation
in interface Aast
key
- Key under which to store the annotation.annotation
- Arbitrary integral numeric value.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.public void putAnnotation(java.lang.String key, java.lang.Boolean annotation)
This is just a thin wrapper to ensure annotation type safety, since
annotations are stored in a Map
as Object
s.
putAnnotation
in interface Aast
key
- Key under which to store the annotation.annotation
- Arbitrary boolean value.public void putAnnotation(java.lang.String key, java.lang.Boolean annotation, int index)
putAnnotation
in interface Aast
key
- Key under which to store the annotation.annotation
- Arbitrary boolean value.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.public void putAnnotation(java.lang.String key, java.util.List<java.lang.Object> annotation)
String
Double
Long
Boolean
putAnnotation
in interface Aast
key
- Key under which to store the annotation.annotation
- list of annotations of the same, supported type.public void putAnnotationObject(java.lang.String key, java.lang.Object annotation)
InMemoryRegistryPlugin
since this is the only plugin
that does not truly serialize the nodes. The other plugins require the the annotation
objects to be serializable so only a small set of objects are supported.putAnnotationObject
in interface Aast
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.public java.lang.Object removeAnnotation(java.lang.String key)
List
) or it may be a
scalar value.removeAnnotation
in interface Aast
key
- Key under which the annotation is stored.null
if none was found.public java.lang.Object removeAnnotation(java.lang.String key, int index)
removeAnnotation
in interface Aast
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.public void clearAnnotations()
clearAnnotations
in interface Aast
public java.util.Iterator<java.lang.String> annotationKeys()
annotationKeys
in interface Aast
null
.public void fixups(Aast parent, java.lang.Long fileId) throws AstException
If the current node's ID is null
, then this method will
use the AstManager.getNextNodeId(long)
to obtain a valid ID that
will uniquely identify this node. This can only be done if the passed
in file ID is valid and not null
.
No shadow nodes will be created using this version of the method. All hidden tokens will be dropped.
parent
- Parent AST node to be assigned to the current node.fileId
- The file ID of the source file.AstException
public void fixups(Aast parent, java.lang.Long fileId, boolean shadow) throws AstException
If the current node's ID is null
, then this method will
use the AstManager.getNextNodeId(long)
to obtain a valid ID that
will uniquely identify this node. This can only be done if the passed
in file ID is valid and not null
.
parent
- Parent AST node to be assigned to the current node.fileId
- The file ID of the source file.shadow
- true
to create shadow nodes from hidden tokens.
false
to drop hidden tokens without creating any
shadow nodes.AstException
public void fixupParent(Aast parent)
parent
- The parent for this node.public 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.
public java.lang.String toString()
toString
in interface antlr.collections.AST
toString
in class antlr.BaseAST
public java.lang.String toStringVerbose()
toStringVerbose
in interface Aast
public java.lang.String dumpTree()
public java.lang.String dumpTree(boolean annotations)
public Aast getLeftShadowNode()
getLeftShadowNode
in interface Aast
null
if no such node exists.public Aast getRightShadowNode()
getRightShadowNode
in interface Aast
null
if no such node exists.public java.util.Iterator<ShadowNode> getShadowNodeList()
getShadowNodeList
in interface Aast
null
if none exist.public TreeLocal getLocal()
public void setLocal(TreeLocal local)
public 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 are
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 is case sensitive. For a case insensitive
comparison, use the compareWith(Aast,boolean)
method variant.
compareWith
in interface Aast
other
- The subtree to compare with.true
if subtrees are identical and
false
otherwise.public 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 are
considered identical if their type and text are identical. The order of
subtrees is defined by iterator provided by iterator() method.compareWith
in interface Aast
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.private AnnotatedAst createNode(antlr.Token token, Aast parent)
token
- The data with which to populate the node.parent
- The parent for the newly created node.null
if there is an
error.private Aast[] getParentChain(Aast node)
node
- The root node to get parent chain.private void createShadowNodes(java.lang.Long fileId)
hidden-before
and
hidden-after
hidden token objects and create shadow nodes
from these tokens if they exist. The entire chain of hidden tokens will
be walked and created. Each shadow node will have a valid ID and will
have the left and right IDs set as appropriate. Then the cached
annotations will be removed so that there is never an attempt to persist
those to file.
Both the parent and the ID must be assigned before this method is called.
fileId
- The file ID of the source file.private java.lang.String getPath(int max)
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 ancestor node, but is not necessarily unique when traversed from the ancestor to this node. How far up the tree we travel is determined by the
max
parameter.max
- The maximum number of characters to be included in the returned path, or a
non-positive integer to indicate that all nodes up to and including the root
should be included in the path.max > 0
, as much of that
path that can fit within max
characters.private Aast getFirstChild(boolean honorHidden)
honorHidden
flag is false
, or the first non-hidden child if the
honorHidden
flag is true
.honorHidden
- If true
, the hidden
attribute of
the node will be honored. This means that the node will not
be returned and instead the first non-hidden sibling will be
returned.honorHidden
mode),
or otherwise the first child. Returns null
if no
non-hidden children exist (in honorHidden
mode)
or whenever no children of any kind exist.private Aast getNextSibling(boolean honorHidden)
honorHidden
flag is false
, or the next non-hidden sibling if the
honorHidden
flag is true
.honorHidden
- If true
, the hidden
attribute of
the node will be honored. This means that the node will not
be returned and instead the next non-hidden sibling will be
returned.honorHidden
mode),
or otherwise the next child. Returns null
if no
non-hidden siblings exist (in honorHidden
mode)
or whenever no siblings of any kind exist.private boolean searchDown(java.lang.String[] list, int index)
list
- The list of token names in order from ancestor (leftmost)
to descendant (rightmost).index
- The current segment of the path which must be tested.true
.private boolean searchUp(java.lang.String source, java.lang.String target)
source
- The actual path upward.target
- The comparison path.true
if the source path ends with the target
path.private void driveFixups(Aast child) throws AstException
child
- The child node to fixup.AstException
private void duplicateImpl(AnnotatedAst original, java.util.Map<java.lang.Long,Aast> idMap)
original
- AST to be copied.idMap
- Map of IDs to ASTs. May be null
.private void putAnnotationImpl(java.lang.String key, java.lang.Object annotation)
key
- Key under which to store the annotation.annotation
- Arbitrary annotation value.private boolean putAnnotationImpl(java.lang.String key, java.lang.Object annotation, int index)
key
- Key under which to store the annotation.annotation
- Arbitrary annotation value.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. Any element at that
location will be replaced.true
if the element was added.private void extractTokenData(antlr.Token token)
CommonHiddenStreamToken
. Otherwise, that data will
be ignored.
The hidden previous/next token data will be temporarily stored using
the annotations hidden-before
and hidden-after
before being moved into true shadow nodes by the brainwashing process.
This is a hack but it is the simplest and cleanest approach available
until better hooks exist for processing IDs and parent linkages during
node creation. Since the shadow nodes cannot be fully processed until
the node IDs are assigned, the hidden token data must be cached with the
node until that time. Then the temporary annotations will be removed
and the shadow nodes will be created and stored in the tree-local data
store. These temporary annotations will never be persisted to disk.
token
- Token from which information is to be extracted.