## 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.String` `cyclifyWithEscapeChars()` 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.String` `escapeQuoteChars(java.lang.String string)` Inserts an escape character before each quote character in the given string.
`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` `isCycLNonAtomicReifableTerm()` Returns true if formula is well-formed Non Atomic Reifable Term.
`boolean` `isCycLNonAtomicUnreifableTerm()` Returns true if formula is well-formed Non Atomic Un-reifable Term.
`boolean` `isFormulaWellFormed(CycFort mt)` Returns true if formula is well-formed in the relevant mt.
`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.
`java.lang.Object` `rest()` Returns the CycList after removing the first element, in in the case of a dotted pair, returns the dotted 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`.
`static 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 <ttt>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.

### isFormulaWellFormed

    public boolean isFormulaWellFormed(CycFort mt)
                                throws java.io.IOException,
                                       java.net.UnknownHostException,
                                       CycApiException

  Returns true if formula is well-formed in the relevant mt.
  Parameters:
    `formula` - the given EL formula
    `mt` - the relevant mt
  Returns:
    true if formula is well-formed in the relevant mt, otherwise false
  Throws:
    `java.net.UnknownHostException` - if cyc server host not found on the network
    `java.io.IOException` - if a data communication error occurs
    `CycApiException` - if the api request results in a cyc server error

### isCycLNonAtomicReifableTerm

    public boolean isCycLNonAtomicReifableTerm()
                                        throws java.io.IOException,
                                               java.net.UnknownHostException,
                                               CycApiException

  Returns true if formula is well-formed Non Atomic Reifable Term.
  Parameters:
    `formula` - the given EL formula
  Returns:
    true if formula is well-formed Non Atomic Reifable Term, otherwise false
  Throws:
    `java.net.UnknownHostException` - if cyc server host not found on the network
    `java.io.IOException` - if a data communication error occurs
    `CycApiException` - if the api request results in a cyc server error

### isCycLNonAtomicUnreifableTerm

    public boolean isCycLNonAtomicUnreifableTerm()
                                          throws java.io.IOException,
                                                 java.net.UnknownHostException,
                                                 CycApiException

  Returns true if formula is well-formed Non Atomic Un-reifable Term.
  Parameters:
    `formula` - the given EL formula
  Returns:
    true if formula is well-formed Non Atomic Un-reifable Term, otherwise false
  Throws:
    `java.net.UnknownHostException` - if cyc server host not found on the network
    `java.io.IOException` - if a data communication error occurs
    `CycApiException` - if the api request results in a cyc server error

### 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 java.lang.Object rest()

  Returns the CycList after removing the first element, in in the case of a dotted pair, returns the dotted element.
  Returns:
    the CycList after removing the first element, in in the case of a dotted pair, returns the dotted element.

### 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`.

### cyclifyWithEscapeChars

    public java.lang.String cyclifyWithEscapeChars()

  Returns a cyclified string representation of the OpenCyc `CycList`. Embedded constants are prefixed with ""#$". Embedded quote chars in strings are escaped.
  Returns:
    a `String` representation in cyclified form.

### 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.

### escapeQuoteChars

    public java.lang.String escapeQuoteChars(java.lang.String string)

  Inserts an escape character before each quote character in the given string.
  Parameters:
    `string` - the given string
  Returns:
    the string with an escape character before each quote character

### 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 <ttt>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

    public static 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