## org.opencyc.inferencesupport
Class Literal

    java.lang.Object
      |
      +--org.opencyc.inferencesupport.Literal

All Implemented Interfaces:
  java.lang.Comparable

Direct Known Subclasses:
  ConstraintRule, QueryLiteral

public class Literal
extends java.lang.Object
implements java.lang.Comparable

An abstract parent class for `QueryLiteral` and `ConstraintRule` classes.

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:
  `UnitTest.testQueryLiteral()`

Field Summary
`protected CycList` `formula` The literal formula as an OpenCyc query.
`int` `nbrFormulaInstances` The number of instances matching this literal formula in the KB.
`static int` `NO_SUBSUMPTION` Value which indicates that a given literal neither subsumes another given literal or is subsumed by another given literal.
`static int` `SUBSUMED_BY` Value which indicates that a given literal is subsumed by another given literal.
`static int` `SUBSUMES` Value which indicates that a given literal subsumes another given literal.
`protected java.util.ArrayList` `variables` The collection of `CycVariables` used in the literal.

Constructor Summary
`Literal()`

Method Summary
`int` `compareTo(java.lang.Object object)` Compares this object with the specified object for order.
`java.lang.String` `cyclify()` Returns a cyclified string representation of the literal's formula.
`int` `determineSubsumption(Literal literal)` Returns a value indicating the subsumption relationship, or lack of subsumption relationship between this literal and another literal.
`boolean` `equals(java.lang.Object object)` Returns `true` if the object equals this object.
`protected void` `gatherVariables()` Gathers the unique variables from the literal's formula.
`CycList` `getArguments()` Returns the arguments of this `Literal` object.
`int` `getArity()` Returns the literal's arity which is defined to be the number of variables, not necessarily equalling the arity of the literal's first predicate.
`CycList` `getFormula()` Gets the literal's formula.
`CycConstant` `getPredicate()` Returns the predicate of this `Literal` object.
`java.util.ArrayList` `getVariables()` Returns the literal's variables.
`boolean` `hasEvaluatableNumericalArgs()` Returns `true` if this `Literal` has simple evaluatable numerical arguments.
`int` `hashCode()` Provides the hash code appropriate for the `Literal`.
`boolean` `isAllDifferent()` Returns `true` if this `Literal` is a #$different literal.
`boolean` `isEvaluatable()` Returns `true` if this `Literal` is a simple evaluatable literal, which can be answered without KB lookup.
`boolean` `isGround()` Returns `true` iff this is a ground formula having no variables.
`boolean` `isIrreflexive(CycFort mt)` Returns `true` iff the predicate has the irreflexive property: (#$isa ?PRED #$IrreflexsiveBinaryPredicate).
`boolean` `isSubsumedBy(Literal literal)` Returns whether this literal is subsumed by the given literal.
`boolean` `isUnary()` Returns `true` iff this is a formula having one variable.
`static boolean` `isValidConstraintRuleExpression(CycList cycListConstraintRule)` Returns `true` iff the given `CycList` is a valid representation of a constraint rule.
`void` `substituteVariable(CycVariable variable, java.lang.Object newObject)` Substitutes an object for a variable.
`boolean` `subsumes(Literal literal)` Returns whether this literal subsumes the given literal.
`java.lang.String` `toString()` Returns a string representation of the `Literal`.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### nbrFormulaInstances

    public int nbrFormulaInstances

  The number of instances matching this literal formula in the KB. Value of -1 indicates the variable is not yet set.

### formula

    protected CycList formula

  The literal formula as an OpenCyc query.

### variables

    protected java.util.ArrayList variables

  The collection of `CycVariables` used in the literal. There should be at least one, because if there are no variables, then the literal is either always true or always false and has no effect on the solution.

### SUBSUMES

    public static final int SUBSUMES

  Value which indicates that a given literal subsumes another given literal.

### SUBSUMED_BY

    public static final int SUBSUMED_BY

  Value which indicates that a given literal is subsumed by another given literal.

### NO_SUBSUMPTION

    public static final int NO_SUBSUMPTION

  Value which indicates that a given literal neither subsumes another given literal or is subsumed by another given literal.

Constructor Detail

### Literal

    public Literal()

Method Detail

### gatherVariables

    protected void gatherVariables()

  Gathers the unique variables from the literal's formula.

### getFormula

    public CycList getFormula()

  Gets the literal's formula.
  Returns:
    a `CycList` which is the literal's formula.

### getVariables

    public java.util.ArrayList getVariables()

  Returns the literal's variables.
  Returns:
    the `ArrayList` which lists the unique `CycVariables` that are used in the literal's formula.

### getArity

    public int getArity()

  Returns the literal's arity which is defined to be the number of variables, not necessarily equalling the arity of the literal's first predicate.
  Returns:
    literal's arity which is defined to be the number of variables, not necessarily equalling the arity of the literal's first predicate

### equals

    public boolean equals(java.lang.Object object)

  Returns `true` if the object equals this object.
  Overrides:
    `equals` in class `java.lang.Object`
  Parameters:
    `object` - the object for comparison
  Returns:
    `boolean` indicating equality of an object with this object.

### hashCode

    public int hashCode()

  Provides the hash code appropriate for the `Literal`.
  Overrides:
    `hashCode` in class `java.lang.Object`
  Returns:
    the hash code for the `Literal`

### compareTo

    public int compareTo(java.lang.Object object)

  Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.
  Specified by:
    `compareTo` in interface `java.lang.Comparable`
  Parameters:
    `object` - the reference object with which to compare.
  Returns:
    a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object

### determineSubsumption

    public int determineSubsumption(Literal literal)
                             throws java.io.IOException,
                                    CycApiException

  Returns a value indicating the subsumption relationship, or lack of subsumption relationship between this literal and another literal.
  Parameters:
    `literal` - the literal for subsumption determination
  Returns:
    `Literal.SUBSUMES` if this literal subsumes the given literal, `Literal.SUBSUMED_BY` if this literal is subsumed by the given literal, `Literal.NO_SUBSUMPTION` if this literal is neither subsumed by the given literal, nor subsumes the given literal

### isSubsumedBy

    public boolean isSubsumedBy(Literal literal)
                         throws java.io.IOException,
                                CycApiException

  Returns whether this literal is subsumed by the given literal.
  Parameters:
    `literal` - the given literal for subsumption determination.
  Returns:
    `true` iff this literal is subsumed by the given `Literal` object.

### subsumes

    public boolean subsumes(Literal literal)
                     throws java.io.IOException,
                            CycApiException

  Returns whether this literal subsumes the given literal.
  Parameters:
    `literal` - the given literal for subsumption determination.
  Returns:
    `true` iff this literal subsumes the given `Literal` object.

### getPredicate

    public CycConstant getPredicate()

  Returns the predicate of this `Literal` object.
  Returns:
    the predicate `CycConstant` or `CycSymbol` of this `Literal` object

### getArguments

    public CycList getArguments()

  Returns the arguments of this `Literal` object.
  Returns:
    the arguments of this `Literal` object

### substituteVariable

    public void substituteVariable(CycVariable variable,
                                   java.lang.Object newObject)

  Substitutes an object for a variable.
  Parameters:
    `oldVariable` - the variable to replaced

### isAllDifferent

    public boolean isAllDifferent()
                           throws java.io.IOException

  Returns `true` if this `Literal` is a #$different literal.
  Returns:
    `boolean` indicating if this `Literal` is a #$different literal

### isEvaluatable

    public boolean isEvaluatable()
                          throws java.io.IOException

  Returns `true` if this `Literal` is a simple evaluatable literal, which can be answered without KB lookup. Typically an evaluatable constraint literal is a relational operator applied to a primitive data type.
  Returns:
    `true` if this `Literal` is a simple evaluatable literal, which can be answered without KB lookup

### hasEvaluatableNumericalArgs

    public boolean hasEvaluatableNumericalArgs()
                                        throws java.io.IOException

  Returns `true` if this `Literal` has simple evaluatable numerical arguments. Numbers and variables return `true` and functional expressions return `true` iff their arguments are simple numerical expressions.
  Returns:
    `true` if this `Literal` has simple evaluatable numerical arguments

### isGround

    public boolean isGround()

  Returns `true` iff this is a ground formula having no variables.
  Returns:
    `true` iff this is a ground formula having no variables

### isUnary

    public boolean isUnary()

  Returns `true` iff this is a formula having one variable.
  Returns:
    `true` iff this is a formula having one variable

### isIrreflexive

    public boolean isIrreflexive(CycFort mt)
                          throws java.io.IOException,
                                 CycApiException

  Returns `true` iff the predicate has the irreflexive property: (#$isa ?PRED #$IrreflexsiveBinaryPredicate).
  Parameters:
    `mt` - the microtheory in which the irreflexive property is sought
  Returns:
    `true` iff the predicate has the irreflexive property: (#$isa ?PRED #$IrreflexsiveBinaryPredicate)

### toString

    public java.lang.String toString()

  Returns a string representation of the `Literal`.
  Overrides:
    `toString` in class `java.lang.Object`
  Returns:
    the literal's formula formated as a `String`.

### cyclify

    public java.lang.String cyclify()

  Returns a cyclified string representation of the literal's formula. Embedded constants are prefixed with ""#$".
  Returns:
    a cyclified `String`.

### isValidConstraintRuleExpression

    public static boolean isValidConstraintRuleExpression(CycList cycListConstraintRule)

  Returns `true` iff the given `CycList` is a valid representation of a constraint rule. Specifically, an expression is not a valid constraint rule if its predicate is not a `CycConstant` object.
  Parameters:
    `cycListConstraintRule` - the representation of a constraint rule to be validated
  Returns:
    `true` iff the given `CycList` is a valid representation of a constraint rule