xtc.tree
Class Node

java.lang.Object
  xtc.tree.Node

All Implemented Interfaces:

java.lang.Iterable<java.lang.Object>, Locatable

Direct Known Subclasses:

Annotation, GNode, Token

public abstract class Node
extends java.lang.Object
implements java.lang.Iterable<java.lang.Object>, Locatable

A node in an abstract syntax tree.

Subclasses may optionally support two features. First, a subclass may support generic tree traversal. Such a class must override hasTraversal() to return true and must provide meaningful implementations for size(), get(int), and set(int,Object). Second, a subclass may support a variable number of children. Such a class must override hasVariable() to return true and must provide meaningful implementations for add(Object), add(int,Object), and remove(int).

Version:

$Revision: 1.55 $

Author:

Robert Grimm

Constructor Summary

Node()
Create a new node.

Node(Location location)
Create a new node.

Method Summary

Node	add(int index, java.lang.Object o) Add the specified object as a child at the specified index.
Node	add(java.lang.Object o) Add the specified object as a child.
Node	addAll(java.util.Collection<?> c) Add all values in the specified collection as children.
Node	addAll(int index, java.util.Collection<?> c) Add all values in the specified collection as children at the specified index.
Node	addAll(int index, Pair<?> p) Add all values in the list starting with the specified pair as children at the specified index.
Node	addAll(Pair<?> p) Add all values in the list starting with the specified pair as children.
void	addAllTo(java.util.Collection<java.lang.Object> c) Add all of this node's children to the specified collection.
Node	addNode(Node node) Add the specified node as a child.
boolean	contains(java.lang.Object o) Determine whether this node has the specified object as a child.
java.lang.Object	get(int index) Get the child at the specified index.
boolean	getBoolean(int index) Get the boolean child at the specified index.
boolean	getBooleanProperty(java.lang.String name) Get a property value as a boolean.
GNode	getGeneric(int index) Get the generic node child at the specified index.
<T> Pair<T>	getList(int index) Get the list child at the specified index.
Location	getLocation() Get this object's location.
java.lang.String	getName() Get the name of this node.
Node	getNode(int index) Get the node child at the specified index.
java.lang.Object	getProperty(java.lang.String name) Get a property value.
java.lang.String	getString(int index) Get the string child at the specified index.
java.lang.String	getStringProperty(java.lang.String name) Get a property value as a string.
java.lang.String	getTokenText() Treat this node as a token and get its text.
boolean	hasLocation() Determine whether this object has a location.
boolean	hasName(java.lang.String name) Determine whether this node's name is the same as the specified name.
boolean	hasProperty(java.lang.String name) Test if this node has a property.
boolean	hasTraversal() Determine whether this node supports generic traversal of its children.
boolean	hasVariable() Determine whether this node supports a variable number of children.
int	indexOf(java.lang.Object o) Determine the index of the specified object.
boolean	isAnnotation() Determine whether this node is an annotation.
boolean	isEmpty() Determine whether this node has no children.
boolean	isGeneric() Determine whether this node is a generic node.
static boolean	isList(java.lang.Object o) Determine whether the specified object is a list of nodes.
boolean	isToken() Determine whether this node is a token.
java.util.Iterator<java.lang.Object>	iterator() Get an iterator over this node's children.
int	lastIndexOf(java.lang.Object o) Determine the last index of the specified object.
java.util.Set<java.lang.String>	properties() Get the set of property names.
java.lang.Object	remove(int index) Remove the child at the specified index.
java.lang.Object	removeProperty(java.lang.String name) Remove a property.
java.lang.Object	set(int index, java.lang.Object value) Set the child at the specified index to the specified value.
void	setLocation(Locatable locatable) Set this object's location to the specified locatable's location.
void	setLocation(Location location) Set this object's location.
java.lang.Object	setProperty(java.lang.String name, java.lang.Object value) Set the value of a property.
int	size() Get the number of children.
Node	strip() Strip any annotations.
Annotation	toAnnotation() Get this node as an annotation.
static Pair<Node>	toList(java.lang.Object o) Convert the specified object to a list of nodes.
java.lang.String	toString() Return a human readable representation of this node.
Token	toToken() Get this node as a token.
void	write(java.lang.Appendable out) Write a human readable representation to the specified appendable.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Node

public Node()

Create a new node.

Node

public Node(Location location)

Create a new node.

Parameters:

location - The source location for the new node.

Method Detail

isToken

public boolean isToken()

Determine whether this node is a token. User-specified classes must not override this method.

Returns:

true if this node is a token.

See Also:

Token

toToken

public Token toToken()

Get this node as a token. User-specified classes must not override this method.

Returns:

This node as a token.

Throws:

java.lang.ClassCastException - Signals that this node is not a token.

getTokenText

public java.lang.String getTokenText()

Treat this node as a token and get its text. This method strips away any annotations, treats the resulting node as a token, and returns its text. User-specified classes must not override this method.

Returns:

The token's text.

Throws:

java.lang.ClassCastException - Signals that this node is not a token.

See Also:

strip()

isAnnotation

public boolean isAnnotation()

Determine whether this node is an annotation. User-specified classes must not override this method.

Returns:

true if this node is an annotation.

See Also:

Annotation

toAnnotation

public Annotation toAnnotation()

Get this node as an annotation. User-specified classes must not override this method.

Returns:

This node as an annotation.

Throws:

java.lang.ClassCastException - Signals that this node is not an annotation.

isGeneric

public boolean isGeneric()

Determine whether this node is a generic node. User-specified classes must not override this method.

Returns:

true if this node is a generic node.

See Also:

GNode

getName

public java.lang.String getName()

Get the name of this node. For strongly typed nodes, the name is implicitly specified by the node's class. For generic nodes, the name is the generic node's explicit name. The default implementation returns the node's class name.

User-specified classes must not override this method.

Returns:

The name.

hasName

public boolean hasName(java.lang.String name)

Determine whether this node's name is the same as the specified name.

User-specified classes must not override this method.

Parameters:

name - The name.

Returns:

true if this node's name equals the specified name.

setProperty

public java.lang.Object setProperty(java.lang.String name,
                                    java.lang.Object value)

Set the value of a property.

Parameters:

name - The property name.

value - The new property value.

Returns:

The property's old value or null if the property didn't have a value.

hasProperty

public boolean hasProperty(java.lang.String name)

Test if this node has a property.

Parameters:

name - The property name.

Returns:

true if this node has a property with the specified name.

getProperty

public java.lang.Object getProperty(java.lang.String name)

Get a property value.

Parameters:

name - The property name.

Returns:

The property's value or null if the property doesn't have a value.

getBooleanProperty

public boolean getBooleanProperty(java.lang.String name)

Get a property value as a boolean. If this node does not have a property with the specified name, this method returns false.

Parameters:

name - The property name.

Returns:

The property's value as a boolean.

getStringProperty

public java.lang.String getStringProperty(java.lang.String name)

Get a property value as a string.

Parameters:

name - The property name.

Returns:

The property's value as a string.

removeProperty

public java.lang.Object removeProperty(java.lang.String name)

Remove a property.

Parameters:

name - The property name.

Returns:

The property's old value or null if the property didn't have a value.

properties

public java.util.Set<java.lang.String> properties()

Get the set of property names.

Returns:

The set of property names.

hasLocation

public boolean hasLocation()

Description copied from interface: Locatable

Determine whether this object has a location.

Specified by:

hasLocation in interface Locatable

Returns:

true if this object has a location.

getLocation

public Location getLocation()

Description copied from interface: Locatable

Get this object's location.

Specified by:

getLocation in interface Locatable

Returns:

This object's location or null if it does not have a location.

setLocation

public void setLocation(Location location)

Description copied from interface: Locatable

Set this object's location.

Specified by:

setLocation in interface Locatable

Parameters:

location - This object's location.

setLocation

public void setLocation(Locatable locatable)

Description copied from interface: Locatable

Set this object's location to the specified locatable's location.

Specified by:

setLocation in interface Locatable

Parameters:

locatable - The locatable object.

hasTraversal

public boolean hasTraversal()

Determine whether this node supports generic traversal of its children. The default implementation returns false.

Returns:

true if this node supports generic traversal of its children.

isEmpty

public boolean isEmpty()

Determine whether this node has no children.

Returns:

true if this node has no children.

Throws:

java.lang.UnsupportedOperationException - Signals that this node does not support generic traversal.

iterator

public java.util.Iterator<java.lang.Object> iterator()

Get an iterator over this node's children.

Note that instance tests on the iterator's objects may not behave as expected. Notably, any node may be wrapped in annotations. Furthermore, any string may be wrapped in a token (and, recursively, in annotations).

Specified by:

iterator in interface java.lang.Iterable<java.lang.Object>

Returns:

An iterator over the children.

See Also:

Token.test(Object), Token.cast(Object), GNode.test(Object), GNode.cast(Object)

size

public int size()

Get the number of children. The default implementation signals an unsupported operation exception.

Returns:

The number of children.

Throws:

java.lang.UnsupportedOperationException - Signals that this node does not support generic traversal.

get

public java.lang.Object get(int index)

Get the child at the specified index. The default implementation signals an unsupported operation exception.

Note that instance tests on the returned object may not behave as expected. Notably, any node may be wrapped in annotations. Furthermore, any string may be wrapped in a token (and, recursively, in annotations).

Parameters:

index - The index.

Returns:

The child at that positioin.

Throws:

java.lang.IndexOutOfBoundsException - Signals that the index is out of range.

java.lang.UnsupportedOperationException - Signals that this node does not support generic traversal.

See Also:

Token.test(Object), Token.cast(Object), GNode.test(Object), GNode.cast(Object)

getBoolean

public boolean getBoolean(int index)

Get the boolean child at the specified index.

Parameters:

index - The index.

Returns:

The child at that position as a boolean.

Throws:

java.lang.IndexOutOfBoundsException - Signals that the index is out of range.

java.lang.ClassCastException - Signals that the child is not a boolean.

java.lang.UnsupportedOperationException - Signals that this node does not support generic traversal.

getString

public java.lang.String getString(int index)

Get the string child at the specified index. If the child at the specified index is a string, this method returns it. Otherwise, it casts the child to a node, strips any annotations, and returns the text of the annotated token.

Parameters:

index - The index.

Returns:

The child at that position as a string.

Throws:

java.lang.IndexOutOfBoundsException - Signals that the index is out of range.

java.lang.ClassCastException - Signals that the child is not a string nor an annotated token.

java.lang.UnsupportedOperationException - Signals that this node does not support generic traversal.

getNode

public Node getNode(int index)

Get the node child at the specified index.

Parameters:

index - The index.

Returns:

The child at that position as a node.

Throws:

java.lang.IndexOutOfBoundsException - Signals that the index is out of range.

java.lang.ClassCastException - Signals that the child is not a node.

java.lang.UnsupportedOperationException - Signals that this node does not support generic traversal.

getGeneric

public GNode getGeneric(int index)

Get the generic node child at the specified index. If the specified child has any annotations, they are stripped before returning the child as a generic node.

Parameters:

index - The index.

Returns:

The child at that position as a stripped generic node.

Throws:

java.lang.IndexOutOfBoundsException - Signals that the index is out of range.

java.lang.ClassCastException - Signals that the child is not a node.

java.lang.UnsupportedOperationException - Signals that this node does not support generic traversal.

getList

public <T> Pair<T> getList(int index)

Get the list child at the specified index.

Parameters:

index - The index.

Returns:

The list child at that position as a list.

Throws:

java.lang.IndexOutOfBoundsException - Signals that the index is out of range.

java.lang.ClassCastException - Signals that the child is not a list.

java.lang.UnsupportedOperationException - Signals that this node does not support generic traversal.

set

public java.lang.Object set(int index,
                            java.lang.Object value)

Set the child at the specified index to the specified value. The default implementation signals an unsupported operation exception.

Parameters:

index - The index.

value - The new value.

Returns:

The old value.

Throws:

java.lang.IllegalStateException - Signals that this node is immutable.

java.lang.IndexOutOfBoundsException - Signals that the index is out of range.

java.lang.ClassCastException - Signals that the value is not of the necessary type.

java.lang.UnsupportedOperationException - Signals that this node does not support generic traversal.

indexOf

public int indexOf(java.lang.Object o)

Determine the index of the specified object.

Parameters:

o - The object.

Returns:

The first index of the child equal to the specified object or -1 if this node does not have the object as a child.

Throws:

java.lang.UnsupportedOperationException - Signals that this node does not support generic traversal.

lastIndexOf

public int lastIndexOf(java.lang.Object o)

Determine the last index of the specified object.

Parameters:

o - The object.

Returns:

The last index of the child equal to the specified object or -1 if this node does not have the object as a child.

Throws:

java.lang.UnsupportedOperationException - Signals that this node does not support generic traversal.

contains

public boolean contains(java.lang.Object o)

Determine whether this node has the specified object as a child.

Parameters:

o - The object.

Returns:

true if this node has the specified object as a child.

Throws:

java.lang.UnsupportedOperationException - Signals that this node does not support generic traversal.

addAllTo

public void addAllTo(java.util.Collection<java.lang.Object> c)

Add all of this node's children to the specified collection.

Parameters:

c - The collection.

Throws:

java.lang.UnsupportedOperationException - Signals that this node does not support generic traversal.

hasVariable

public boolean hasVariable()

Determine whether this node supports a variable number of children. Any variable-sized node should also support generic traversal. The default implementation returns false.

Returns:

true if this node supports a variable number of children.

See Also:

hasTraversal()

add

public Node add(java.lang.Object o)

Add the specified object as a child. The default implementation signals an unsupported operation exception.

Parameters:

o - The object.

Returns:

This node.

Throws:

java.lang.UnsupportedOperationException - Signals that this node does not support a variable number of children.

addNode

public Node addNode(Node node)

Add the specified node as a child. For nodes that are not annotations supporting a variable number of children, this method is semantically equivalent to add(Object). For annotations supporting a variable number of children, this method adds the annotated node. Any previously added children precede that node and any children added after the call to this method succeed that node.

Parameters:

node - The node.

Returns:

This node.

Throws:

java.lang.IllegalStateException - Signals that this method has already been invoked on an annotation supporting a variable number of children.

java.lang.UnsupportedOperationException - Signals that this node does not support a variable number of children.

add

public Node add(int index,
                java.lang.Object o)

Add the specified object as a child at the specified index. The default implementation signals an unsupported operation exception.

Parameters:

index - The index.

o - The object.

Returns:

This node.

Throws:

java.lang.UnsupportedOperationException - Signals that this node does not support a variable number of children.

addAll

public Node addAll(Pair<?> p)

Add all values in the list starting with the specified pair as children.

Parameters:

p - The pair.

Returns:

This node.

Throws:

java.lang.UnsupportedOperationException - Signals that this node does not support a variable number of children.

addAll

public Node addAll(int index,
                   Pair<?> p)

Add all values in the list starting with the specified pair as children at the specified index.

Parameters:

index - The index.

p - The pair.

Returns:

This node.

Throws:

java.lang.UnsupportedOperationException - Signals that this node does not support a variable number of children.

addAll

public Node addAll(java.util.Collection<?> c)

Add all values in the specified collection as children.

Parameters:

c - The collection.

Returns:

This node.

Throws:

java.lang.UnsupportedOperationException - Signals that this node does not support a variable number of children.

addAll

public Node addAll(int index,
                   java.util.Collection<?> c)

Add all values in the specified collection as children at the specified index.

Parameters:

index - The index.

c - The collection.

Returns:

This node.

Throws:

java.lang.UnsupportedOperationException - Signals that this node does not support a variable number of children.

remove

public java.lang.Object remove(int index)

Remove the child at the specified index. The default implementation signals an unsupported operation exception.

Parameters:

index - The index.

Returns:

The removed child.

Throws:

java.lang.IndexOutOfBoundsException - Signals that the index is out of range.

java.lang.UnsupportedOperationException - Signals that this node does not support a variable number of children.

strip

public Node strip()

Strip any annotations. This method removes any annotations starting with this node. The default implementation returns this node.

Returns:

The node without annotations.

See Also:

Annotation

write

public void write(java.lang.Appendable out)
           throws java.io.IOException

Write a human readable representation to the specified appendable. If this node supports generic traversal, the default implementation writes this node in algebraic term-format; otherwise, it writes the string returned by Object.toString().

Parameters:

out - The appendable.

Throws:

java.io.IOException - Signals an I/O error.

toString

public java.lang.String toString()

Return a human readable representation of this node. The default implementation creates a new string builder, writes this node to the builder, and then returns the corresponding string. Subclasses should typically override write(Appendable).

Overrides:

toString in class java.lang.Object

Returns:

A human readable representation.

isList

public static final boolean isList(java.lang.Object o)

Determine whether the specified object is a list of nodes.

Parameters:

o - The object.

Returns:

true if the specified object is a list of nodes.

toList

public static final Pair<Node> toList(java.lang.Object o)

Convert the specified object to a list of nodes.

Parameters:

o - The object, which must be a list of nodes.

Returns:

The object as a list of nodes.

Throws:

java.lang.ClassCastException - Signals that the object is not a list of nodes.