Parsing Engine

danbikel.lisp
Class SexpList

java.lang.Object
  extended by danbikel.lisp.Sexp
      extended by danbikel.lisp.SexpList
All Implemented Interfaces:
Externalizable, Serializable
Direct Known Subclasses:
SexpList.HashCache, SubcatList

public class SexpList
extends Sexp
implements Externalizable

Stores a list of Sexp objects, which are either symbols or themselves lists.

See Also:
Serialized Form

Nested Class Summary
static class SexpList.HashCache
          A subclass of SexpList where a precomputed, cached hash value is stored with every instance.
 
Field Summary
static SexpList emptyList
          An immutable object to represent the empty list.
 
Constructor Summary
SexpList()
          Constructs a SexpList with the default initial capacity.
SexpList(int initialCapacity)
          Constructs a SexpList with the specified initial capacity.
SexpList(List initialElements)
          Constructs a SexpList whose initial elements are those of initialElements.
SexpList(SexpList initialElements)
          Constructs a SexpList whose initial elements are those of initialElements.
 
Method Summary
 SexpList add(int index, Sexp sexp)
          Adds sexp at position index, shifting all elements to the right by one position to make room (an O(n) operation).
 SexpList add(Sexp sexp)
          Appends sexp to the end of this list.
 boolean addAll(int index, SexpList elementsToAdd)
          Adds all the elements in elementsToAdd to this list at the specified index.
 boolean addAll(SexpList elementsToAdd)
          Appends all the elements in elementsToAdd to the end of this list.
 void clear()
          Removes all elements from this list.
 boolean contains(Sexp toFind)
          Returns whether the specified S-expression is an element of this list.
 Sexp deepCopy()
          Returns a deep copy of this list, which means that a full copy of the tree of S-expressions held by this list is returned.
 void ensureCapacity(int minCapacity)
          Increases the number of elements that this list can hold, if necessary, to be at least minCapacity.
 boolean equals(Object o)
          Returns true if the specified object is not null and is an instance of SexpList where the underlying lists are of the same size and contain Sexp objects that are equal.
 Sexp first()
          Returns the first element of this list (identical to calling get(0)).
 Sexp get(int index)
          Gets the Sexp at the specified index.
static SexpList getCanonical(SexpList list)
          A simple canonicalization method that returns the unique object representing the empty list if the specified list contains no elements.
 Symbol getChildLabel(int index)
          This convenience method gets the symbol that is the first element of the list that is the element at index.
 int hashCode()
          Returns the hash code value for this list.
 int indexOf(Sexp toFind)
          Finds the index of the specified S-expresion.
 boolean isAllSymbols()
          Returns true if and only if all the elements of this list are Symbol objects.
 boolean isList()
          Returns true, because this class and any of its subclasses represent lists.
 boolean isSymbol()
          Returns false, because this class and any of its subclasses represent lists, not symbols.
 Iterator iterator()
          Returns a read-only iterator for the elements of this list.
 Sexp last()
          Returns the last element of this list (identical to calling get(size() - 1)).
 int length()
          Returns the number of elements in this list.
 SexpList listAt(int index)
          Returns the list at the specified index.
 void readExternal(ObjectInput in)
          Reads this object from an ObjectInput instance.
 Sexp remove(int index)
          Removes the element at index.
 SexpList reverse()
          Performs an in-place reversal of the elements in this list.
 Sexp set(int index, Sexp element)
          Replaces the element at index with element.
 void setChildLabel(int index, Symbol newLabel)
          This convenience method replaces the first element of the list that is the element at index to be the symbol newLabel.
 int size()
          Returns the number of elements in this list.
 Symbol symbolAt(int index)
          Returns the symbol at the specified index.
 String toString()
          Returns a string representation of this S-expression, consisting of an open parenthesis, a space-separated string representation of the elements of this list and a close parenthesis.
 void trimToSize()
          Causes the capacity of this list to be its size.
 void trimToSizeRecursive()
          Invokes trimToSize not only on this list, but recursively invokes this method on all elements of this list, thereby trimming every list in the implicit tree of this list.
 void writeExternal(ObjectOutput out)
          Writes this object to an ObjectOutput instance.
 
Methods inherited from class danbikel.lisp.Sexp
getCanonical, list, main, read, read, read, symbol
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

emptyList

public static final SexpList emptyList
An immutable object to represent the empty list.

Constructor Detail

SexpList

public SexpList()
Constructs a SexpList with the default initial capacity.


SexpList

public SexpList(int initialCapacity)
Constructs a SexpList with the specified initial capacity.

Parameters:
initialCapacity - the initial capacity of this list

SexpList

public SexpList(SexpList initialElements)
Constructs a SexpList whose initial elements are those of initialElements. The initial capacity of this newly-constructed list will be exactly that of the specified list. Note that the elements of initialElements are not cloned.

Parameters:
initialElements - a list of the initial elements of this new list

SexpList

public SexpList(List initialElements)
Constructs a SexpList whose initial elements are those of initialElements. Note that the elements of initialElements are not cloned. It is the responsibility of the caller that initialElements only contain objects of type Sexp.

Parameters:
initialElements - a list of the initial elements of this new list
Method Detail

getCanonical

public static final SexpList getCanonical(SexpList list)
A simple canonicalization method that returns the unique object representing the empty list if the specified list contains no elements.

Parameters:
list - the list to be canonicalized, if it is the empty list
Returns:
a canonical version of the specified list, if the specified list is the empty list

isList

public final boolean isList()
Returns true, because this class and any of its subclasses represent lists.

Specified by:
isList in class Sexp
Returns:
true

isSymbol

public final boolean isSymbol()
Returns false, because this class and any of its subclasses represent lists, not symbols.

Specified by:
isSymbol in class Sexp
Returns:
false

add

public SexpList add(Sexp sexp)
Appends sexp to the end of this list.

Parameters:
sexp - the S-expression to append
Returns:
this SexpList object

add

public SexpList add(int index,
                    Sexp sexp)
Adds sexp at position index, shifting all elements to the right by one position to make room (an O(n) operation).

Parameters:
index - the index at which to add the specified S-expression
sexp - the S-expression to add
Returns:
this SexpList object

addAll

public boolean addAll(SexpList elementsToAdd)
Appends all the elements in elementsToAdd to the end of this list.

Parameters:
elementsToAdd - the elements to be added at the end of this list
Returns:
whether this list was modified

addAll

public boolean addAll(int index,
                      SexpList elementsToAdd)
Adds all the elements in elementsToAdd to this list at the specified index.

Parameters:
index - the index at which to add all the elements of elementsToAdd
elementsToAdd - the elements to add at index
Returns:
whether this list was modified

get

public Sexp get(int index)
Gets the Sexp at the specified index.

Parameters:
index - the index of the list element to be retrieved
Returns:
the Sexp at the specified index.

set

public Sexp set(int index,
                Sexp element)
Replaces the element at index with element.

Parameters:
index - the index of this list to be set with the specified Sexp
element - the element to be set at the specified index of this list
Returns:
the value of the element that used to be at the specified index

remove

public Sexp remove(int index)
Removes the element at index.

Parameters:
index - the index at which to remove an element from this list
Returns:
the element that was removed from the list
Throws:
IndexOutOfBoundsException - if the index is out of range ((index < 0 || index >= size()))

clear

public void clear()
Removes all elements from this list.


ensureCapacity

public void ensureCapacity(int minCapacity)
Increases the number of elements that this list can hold, if necessary, to be at least minCapacity.

Parameters:
minCapacity - the minimum size of the storage capacity of this list after invocation of this method

trimToSize

public void trimToSize()
Causes the capacity of this list to be its size. An application can use this method to reduce the memory footprint of SexpList objects.


trimToSizeRecursive

public void trimToSizeRecursive()
Invokes trimToSize not only on this list, but recursively invokes this method on all elements of this list, thereby trimming every list in the implicit tree of this list. This method will never return if this list represents a cyclic graph rather than a tree.


length

public int length()
Returns the number of elements in this list.

Returns:
the number of elements in this list.

size

public int size()
Returns the number of elements in this list.

Returns:
the number of elements in this list.

first

public Sexp first()
Returns the first element of this list (identical to calling get(0)).

Returns:
the first element of this list

last

public Sexp last()
Returns the last element of this list (identical to calling get(size() - 1)).

Returns:
the last element of this list

indexOf

public int indexOf(Sexp toFind)
Finds the index of the specified S-expresion.

Parameters:
toFind - the S-expression to find in this list
Returns:
the index of toFind in this list, or -1 if it does not appear in this list

contains

public boolean contains(Sexp toFind)
Returns whether the specified S-expression is an element of this list.

Parameters:
toFind - the S-expression to find in this list
Returns:
whether the specified S-expression is an element of this list.

reverse

public SexpList reverse()
Performs an in-place reversal of the elements in this list.

Returns:
this SexpList object, having been reversed

symbolAt

public Symbol symbolAt(int index)
Returns the symbol at the specified index. Calling this method is equivalent to calling
get(index).symbol()

Parameters:
index - the index of the symbol to retrieve
Returns:
the symbol at index
Throws:
ClassCastException - if the element at index is not of type Symbol

listAt

public SexpList listAt(int index)
Returns the list at the specified index. Calling this method is equivalent to calling
get(index).list()

Parameters:
index - the index of the symbol to retrieve
Returns:
the symbol at index
Throws:
ClassCastException - if the element at index is not of type SexpList

getChildLabel

public Symbol getChildLabel(int index)
This convenience method gets the symbol that is the first element of the list that is the element at index. Invoking this method is equivalent to the following:
 get(index).list().get(0).symbol(); 
This method is useful for when Sexps are used to represent labeled trees, where the first element of a list represents a node label and subsequent elements represent the children of the node with that label.

Parameters:
index - the index of the element whose first symbol this method retrieves
Returns:
the label of the first element of the list at the specified index
Throws:
ClassCastException - if the element at index is not a list or if the first element of the list at index is not of type Symbol
IndexOutOfBoundsException - if this list has no element at the specified index, or if the list that is the element at index has no elements

setChildLabel

public void setChildLabel(int index,
                          Symbol newLabel)
This convenience method replaces the first element of the list that is the element at index to be the symbol newLabel. Invoking this method is equivalent to the following:
 get(index).list().set(0, newLabel); 
This method is useful for when Sexps are used to represent labeled trees, where the first element of a list represents a node label and subsequent elements represent the children of the node with that label.

Parameters:
index - the index of the element whose first element is to be replaced
newLabel - the label to be set as the first element of the list at the specified index
Throws:
ClassCastException - if the element at index is not a list
IndexOutOfBoundsException - if this list has no element at the specified index, or if the list that is the element at index has no elements

deepCopy

public final Sexp deepCopy()
Returns a deep copy of this list, which means that a full copy of the tree of S-expressions held by this list is returned.

Specified by:
deepCopy in class Sexp
Returns:
a deep copy of this list

isAllSymbols

public boolean isAllSymbols()
Returns true if and only if all the elements of this list are Symbol objects.

Returns:
true if and only if all the elements of this list are Symbol objects.

equals

public boolean equals(Object o)
Returns true if the specified object is not null and is an instance of SexpList where the underlying lists are of the same size and contain Sexp objects that are equal. List equality is determined via the implementation of the equals method in AbstractList. Note that two SexpList objects may be print-equal but not equal via this method, which checks for symbol equality (a StringSymbol and an IntSymbol may have the same string representation but can never be the same symbol).

Overrides:
equals in class Object
Parameters:
o - the object to test for equality with this list
Returns:
whether the specified object is equal to this list
See Also:
AbstractList.equals(java.lang.Object)

hashCode

public int hashCode()
Returns the hash code value for this list.

Overrides:
hashCode in class Object
Returns:
the hash code value for this list

toString

public String toString()
Returns a string representation of this S-expression, consisting of an open parenthesis, a space-separated string representation of the elements of this list and a close parenthesis.

Overrides:
toString in class Object
Returns:
a string representation of this list

iterator

public Iterator iterator()
Returns a read-only iterator for the elements of this list.

Returns:
a read-only iterator for the elements of this list.

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException
Writes this object to an ObjectOutput instance.

Specified by:
writeExternal in interface Externalizable
Specified by:
writeExternal in class Sexp
Parameters:
out - the object stream to which to write an object of this class
Throws:
IOException - if the underlying write operation throws an IOException

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException
Reads this object from an ObjectInput instance.

Specified by:
readExternal in interface Externalizable
Specified by:
readExternal in class Sexp
Parameters:
in - the object stream from which to read objects of this class
Throws:
IOException - if the underlying read operation throws an IOException
ClassNotFoundException - if the underlying read operation throws an ClassNotFoundException

Parsing Engine

Author: Dan Bikel.