org.opencyc.cycobject
Class CycList

java.lang.Object
  |
  +--java.util.AbstractCollection
        |
        +--java.util.AbstractList
              |
              +--java.util.ArrayList
                    |
                    +--org.opencyc.cycobject.CycList
All Implemented Interfaces:
java.lang.Cloneable, java.util.Collection, java.util.List, java.io.Serializable

public class CycList
extends java.util.ArrayList

Provides the behavior and attributes of an OpenCyc list, typically used to represent assertions in their external (EL) form.

Author:
Stephen L. Reed

Copyright 2001 Cycorp, Inc., license is open source GNU LGPL.

the license

www.opencyc.org

OpenCyc at SourceForge

THIS SOFTWARE AND KNOWLEDGE BASE CONTENT ARE PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OPENCYC ORGANIZATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE AND KNOWLEDGE BASE CONTENT, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

See Also:
Serialized Form

Field Summary
static java.lang.String cycListXMLTag
          XML serialization tags.
static java.lang.String dottedElementXMLTag
           
static java.lang.String doubleXMLTag
           
static int indentLength
          XML serialization indentation.
static java.lang.String integerXMLTag
           
static java.lang.String stringXMLTag
           
 
Fields inherited from class java.util.AbstractList
modCount
 
Constructor Summary
CycList()
          Constructs a new empty CycList object.
CycList(java.util.Collection c)
          Constructs a new CycList object, containing the elements of the specified collection, in the order they are returned by the collection's iterator.
CycList(java.lang.Object element)
          Constructs a new CycList object, containing as its sole element element
CycList(java.lang.Object firstElement, java.util.Collection remainingElements)
          Constructs a new CycList object, containing as its first element firstElement, and containing as its remaining elements the contents of the Collection remaining elements.
CycList(java.lang.Object element1, java.lang.Object element2)
          Constructs a new CycList object, containing as its first element element1, and element2 as its second element.
 
Method Summary
 void addAllNew(java.util.Collection objects)
          Adds the given elements to this list if they are not already contained.
 void addNew(java.lang.Object object)
          Adds the given element to this list if it is not already contained.
 void addQuoted(java.lang.Object object)
          Forms a quote expression for the given object and adds it to the list.
 java.lang.Object clone()
          Creates and returns a copy of this CycList.
 CycList combinationsOf(int n)
          Returns a CycList of the length N combinations of sublists from this object.
static CycList construct(java.lang.Object object1, java.lang.Object object2)
          Constructs a CycList using the semantics of Lisp symbolic expressions.
1.
 boolean containsDuplicates()
          Returns true iff this list contains duplicate elements.
 java.lang.String cyclify()
          Returns a cyclified string representation of the OpenCyc CycList.
 java.lang.Object cycListApiValue()
          Returns this object in a form suitable for use as an CycList api expression value.
 CycListVisitor cycListVisitor()
          Returns a CycListVisitor enumeration of the non-CycList and non-nil elements.
 CycList deepCopy()
          Creates and returns a deep copy of this CycList.
 boolean doesElementPrecedeOthers(java.lang.Object element, CycList otherElements)
          Returns true if the element is a member of this CycList and no element in CycList otherElements precede it.
 java.lang.Object first()
          Returns the first element of the CycList.
 java.lang.Object fourth()
          Returns the fourth element of the CycList.
 java.lang.Object getDottedElement()
          Gets the dotted element.
 java.lang.Object getValueForKeyword(CycSymbol keyword)
          Gets the value following the given keyword symbol.
 boolean isProperList()
          Returns true if this is a proper list.
 boolean isValid()
          Answers true iff the CycList contains valid elements.
 java.lang.Object last()
          Returns the last element of the CycList.
static CycList list(java.lang.Object element)
          Creates a new CycList containing the given element.
static CycList list(java.lang.Object element1, java.lang.Object element2)
          Creates a new CycList containing the given two elements.
static CycList list(java.lang.Object element1, java.lang.Object element2, java.lang.Object element3)
          Creates a new CycList containing the given three elements.
 CycList randomPermutation()
          Returns a random ordering of the CycList without recursion.
 CycList rest()
          Returns the CycList after removing the first element.
 CycList reverse()
          Returns a new CycList whose elements are the reverse of this CycList, which is unaffected.
 java.lang.String safeToString()
          Returns a String representation of this List without causing additional api calls to complete the name field of constants.
 java.lang.Object second()
          Returns the second element of the CycList.
 void setDottedElement(java.lang.Object dottedElement)
          Sets the dotted element and set the improper list attribute to true.
 CycList sort()
          Returns a new CycList, which is sorted in the default collating sequence.
 java.lang.String stringApiValue()
          Returns this object in a form suitable for use as an String api expression value.
 CycList subst(java.lang.Object newObject, java.lang.Object oldObject)
          Returns a new CycList with every occurrance of Object oldObject replaced by Object newObject.
 java.lang.Object third()
          Returns the third element of the CycList.
 java.lang.String toPrettyString(java.lang.String indent)
          Returns a `pretty-printed' String representation of this CycList.
 java.lang.String toString()
          Returns a String representation of this List.
protected  java.lang.String toStringHelper(boolean safe)
          Returns a String representation of this CycList.
protected  void toXML(java.lang.Object object, XMLWriter xmlWriter, int indent, boolean relative)
          Writes a CycList element the the given XML output stream.
 void toXML(XMLWriter xmlWriter, int indent, boolean relative)
          Prints the XML representation of the CycList to an XMLWriter
 java.lang.String toXMLString()
          Returns the XML representation of this object.
 boolean treeContains(java.lang.Object object)
          Returns true if the proper list tree contains the given object anywhere in the tree.
 
Methods inherited from class java.util.ArrayList
add, add, addAll, addAll, clear, contains, ensureCapacity, get, indexOf, isEmpty, lastIndexOf, remove, removeRange, set, size, toArray, toArray, trimToSize
 
Methods inherited from class java.util.AbstractList
equals, hashCode, iterator, listIterator, listIterator, subList
 
Methods inherited from class java.util.AbstractCollection
containsAll, remove, removeAll, retainAll
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.List
containsAll, equals, hashCode, iterator, listIterator, listIterator, remove, removeAll, retainAll, subList
 

Field Detail

cycListXMLTag

public static final java.lang.String cycListXMLTag
XML serialization tags.

integerXMLTag

public static final java.lang.String integerXMLTag

doubleXMLTag

public static final java.lang.String doubleXMLTag

stringXMLTag

public static final java.lang.String stringXMLTag

dottedElementXMLTag

public static final java.lang.String dottedElementXMLTag

indentLength

public static int indentLength
XML serialization indentation.
Constructor Detail

CycList

public CycList()
Constructs a new empty CycList object.

CycList

public CycList(java.util.Collection c)
Constructs a new CycList object, containing the elements of the specified collection, in the order they are returned by the collection's iterator.
Parameters:
c - the collection of assumed valid OpenCyc objects.

CycList

public CycList(java.lang.Object firstElement,
               java.util.Collection remainingElements)
Constructs a new CycList object, containing as its first element firstElement, and containing as its remaining elements the contents of the Collection remaining elements.
Parameters:
firstElement - the object which becomes the head of the CycList
remainingElements - a Collection, whose elements become the remainder of the CycList

CycList

public CycList(java.lang.Object element)
Constructs a new CycList object, containing as its sole element element
Parameters:
element - the object which becomes the head of the CycList

CycList

public CycList(java.lang.Object element1,
               java.lang.Object element2)
Constructs a new CycList object, containing as its first element element1, and element2 as its second element.
Parameters:
element1 - the object which becomes the head of the CycList
element2 - the object which becomes the second element of the CycList
Method Detail

construct

public static CycList construct(java.lang.Object object1,
                                java.lang.Object object2)
Constructs a CycList using the semantics of Lisp symbolic expressions.
1. construct(a, NIL) --> (a)
2. construct(a, b) --> (a . b)
Parameters:
object1 - the first Object in the CycList
object2 - NIL or an Object
Returns:
CycList (object) if object2 is NIL, otherwise return the improper CycList (object1 . object2)

clone

public java.lang.Object clone()
Creates and returns a copy of this CycList.
Overrides:
clone in class java.util.ArrayList
Returns:
a clone of this instance

deepCopy

public CycList deepCopy()
Creates and returns a deep copy of this CycList. In a deep copy, directly embedded CycList objects are also deep copied. Objects which are not CycLists are cloned.
Returns:
a deep copy of this CycList

getDottedElement

public java.lang.Object getDottedElement()
Gets the dotted element.
Returns:
the Object which forms the dotted element of this CycList

setDottedElement

public void setDottedElement(java.lang.Object dottedElement)
Sets the dotted element and set the improper list attribute to true.

isProperList

public boolean isProperList()
Returns true if this is a proper list.
Returns:
true if this is a proper list, otherwise return false

isValid

public boolean isValid()
Answers true iff the CycList contains valid elements. This is a necessary, but not sufficient condition for CycL well-formedness.

list

public static CycList list(java.lang.Object element)
Creates a new CycList containing the given element.
Parameters:
element - the contents of the new CycList
Returns:
a new CycList containing the given element

list

public static CycList list(java.lang.Object element1,
                           java.lang.Object element2)
Creates a new CycList containing the given two elements.
Parameters:
element1 - the first item of the new CycList
element2 - the second item of the new CycList
Returns:
a new CycList containing the given two elements

list

public static CycList list(java.lang.Object element1,
                           java.lang.Object element2,
                           java.lang.Object element3)
Creates a new CycList containing the given three elements.
Parameters:
element1 - the first item of the new CycList
element2 - the second item of the new CycList
element3 - the third item of the new CycList
Returns:
a new CycList containing the given three elements

first

public java.lang.Object first()
Returns the first element of the CycList.
Returns:
the Object which is the first element of the list.

second

public java.lang.Object second()
Returns the second element of the CycList.
Returns:
the Object which is the second element of the list.

third

public java.lang.Object third()
Returns the third element of the CycList.
Returns:
the Object which is the third element of the list.

fourth

public java.lang.Object fourth()
Returns the fourth element of the CycList.
Returns:
the Object which is the fourth element of the list.

last

public java.lang.Object last()
Returns the last element of the CycList.
Returns:
the Object which is the last element of the list.

rest

public CycList rest()
Returns the CycList after removing the first element.
Returns:
new CycList with first element removed.

addNew

public void addNew(java.lang.Object object)
Adds the given element to this list if it is not already contained.

addAllNew

public void addAllNew(java.util.Collection objects)
Adds the given elements to this list if they are not already contained.

containsDuplicates

public boolean containsDuplicates()
Returns true iff this list contains duplicate elements.
Returns:
true iff this list contains duplicate elements

reverse

public CycList reverse()
Returns a new CycList whose elements are the reverse of this CycList, which is unaffected.
Returns:
new CycList with elements reversed.

combinationsOf

public CycList combinationsOf(int n)
Returns a CycList of the length N combinations of sublists from this object. This algorithm preserves the list order with the sublists.
Parameters:
n - the length of the sublist
Returns:
a CycList of the length N combinations of sublists from this object

randomPermutation

public CycList randomPermutation()
Returns a random ordering of the CycList without recursion.
Returns:
a random ordering of the CycList without recursion

subst

public CycList subst(java.lang.Object newObject,
                     java.lang.Object oldObject)
Returns a new CycList with every occurrance of Object oldObject replaced by Object newObject. Substitute recursively into embedded CycList objects.
Returns:
a new CycList with every occurrance of Object oldObject replaced by Object newObject

toString

public java.lang.String toString()
Returns a String representation of this List.
Overrides:
toString in class java.util.AbstractCollection

safeToString

public java.lang.String safeToString()
Returns a String representation of this List without causing additional api calls to complete the name field of constants.

toStringHelper

protected java.lang.String toStringHelper(boolean safe)
Returns a String representation of this CycList. When the parameter is true, the representation is created without causing additional api calls to complete the name field of constants.
Parameters:
safe - when true, the representation is created without causing additional api calls to complete the name field of constants
Returns:
a String representation of this CycList

toPrettyString

public java.lang.String toPrettyString(java.lang.String indent)
Returns a `pretty-printed' String representation of this CycList.
Parameters:
indent, - the indent string that is added before the String representation this CycList
Returns:
a `pretty-printed' String representation of this CycList.

cyclify

public java.lang.String cyclify()
Returns a cyclified string representation of the OpenCyc CycList. Embedded constants are prefixed with ""#$".
Returns:
a String representation in cyclified form.

stringApiValue

public java.lang.String stringApiValue()
Returns this object in a form suitable for use as an String api expression value.
Returns:
this object in a form suitable for use as an String api expression value

cycListApiValue

public java.lang.Object cycListApiValue()
Returns this object in a form suitable for use as an CycList api expression value.
Returns:
this object in a form suitable for use as an CycList api expression value

sort

public CycList sort()
Returns a new CycList, which is sorted in the default collating sequence.
Returns:
a new CycList, sorted in the default collating sequence.

cycListVisitor

public CycListVisitor cycListVisitor()
Returns a CycListVisitor enumeration of the non-CycList and non-nil elements.
Returns:
a CycListVisitor enumeration of the non-CycList and non-nil elements.

treeContains

public boolean treeContains(java.lang.Object object)
Returns true if the proper list tree contains the given object anywhere in the tree.
Parameters:
object - the object to be found in the tree.
Returns:
true if the proper list tree contains the given object anywhere in the tree

doesElementPrecedeOthers

public boolean doesElementPrecedeOthers(java.lang.Object element,
                                        CycList otherElements)
Returns true if the element is a member of this CycList and no element in CycList otherElements precede it.
Parameters:
element - the element under consideration
otherElements - the CycList of other elements under consideration
Returns:
true if the element is a member of this CycList and no elements in CycList otherElements contained in this CycList precede it

toXMLString

public java.lang.String toXMLString()
                             throws java.io.IOException
Returns the XML representation of this object.
Returns:
the XML representation of this object

toXML

public void toXML(XMLWriter xmlWriter,
                  int indent,
                  boolean relative)
           throws java.io.IOException
Prints the XML representation of the CycList to an XMLWriter
Parameters:
xmlWriter - the output XML serialization writer
indent - specifies by how many spaces the XML output should be indented
relative - specifies whether the indentation should be absolute -- indentation with respect to the beginning of a new line, relative = false -- or relative to the indentation currently specified in the indent_string field of the xml_writer object, relative = true.

toXML

protected void toXML(java.lang.Object object,
                     XMLWriter xmlWriter,
                     int indent,
                     boolean relative)
              throws java.io.IOException
Writes a CycList element the the given XML output stream.
Parameters:
object - the object to be serialized as XML
xmlWriter - the output XML serialization writer
indent - specifies by how many spaces the XML output should be indented
relative - specifies whether the indentation should be absolute -- indentation with respect to the beginning of a new line, relative = false -- or relative to the indentation currently specified in the indent_string field of the xml_writer object, relative = true.

getValueForKeyword

public java.lang.Object getValueForKeyword(CycSymbol keyword)
Gets the value following the given keyword symbol.
Parameters:
keyword - the keyword symbol
Returns:
the value following the given keyword symbol, or null if not found

addQuoted

public void addQuoted(java.lang.Object object)
Forms a quote expression for the given object and adds it to the list.
Parameters:
object - the object to be quoted and added to this list