ubc.cs.JLog.Terms
Interface iTerm

All Superinterfaces:
iConsultable, iName, iUnifiable, iValue
All Known Subinterfaces:
iList
All Known Implementing Classes:
iPredicate, jAbs, jACos, jAdd, jAddEvent, jAfter, jAfterEqual, jAnimate, jAnimate_addshape, jAnimate_create, jAnimate_delete, jAnimate_getattr, jAnimate_getobject, jAnimate_getshape, jAnimate_init, jAnimate_move, jAnimate_objects, jAnimate_path, jAnimate_removeshape, jAnimate_rotate, jAnimate_setattr, jAnimate_setlevel, jAnimate_setmagnify, jAnimate_setview, jAnimate_shapes, jAnimate_update, jAppendArray, jArg, jASin, jAssert, jAsserta, jAssertz, jATan, jATan2, jAtom, jBefore, jBeforeEqual, jBinaryBuiltinPredicate, jBitwiseConjunction, jBitwiseDisjunction, jBitwiseExclusiveDisjunction, jBitwiseLeftShift, jBitwiseNegation, jBitwiseRightShift, jBuiltinPredicate, jCall, jCallN, jCeiling, jClause, jCommand, jCompare, jCompoundTerm, jConjunctTerm, jCons, jConvertArray, jCopyTerm, jCos, jCreate3, jCreate4, jCreateArray, jCurrentOpList, jCut, jDBConnect, jDBDisconnect, jDBExecute, jDBExecuteParam, jDBSelect, jDCG, jDynamic, jEnumerateVariablesArray, jEqual, jEquivalence, jEquivalent, jExists, jExp, jExpandTerm, jFail, jFloor, jFSDelete, jFSExists, jFSisFileOrDir, jFSLength, jFSListDir, jFSMakeDir, jFSRead, jFSWrite, jFunctor, jGetArrayElement, jGreaterThan, jGreaterThanEqual, jIf, jImport, jInteger, jIntegerArithmetic, jIntegerDivide, jIntegerOnlyArithmetic, jIntersectArray, jInvoke4, jInvoke5, jIs, jIsAtom, jIsAtomic, jIsCallable, jIsCompound, jIsGround, jIsInteger, jIsList, jIsNonVariable, jIsNumber, jIsReal, jIsSimple, jIsType, jIsVariable, jJ2P, jKeysort, jLessThan, jLessThanEqual, jList, jListPair, jLoadLibrary, jLog, jLog10, jLog2, jLogBase, jLookup, jMax, jMin, jMinus, jMod, jMultiply, jName, jNaryBuiltinPredicate, jNotEqual, jNotEquivalence, jNotEquivalent, jNotUnify, jNullList, jNumericComparison, jObject, jOp, jOperator, jOr, jOrPredicate, jP2J, jPlus, jPow, jPredicate, jPredicateTerms, jQuadaryBuiltinPredicate, jRandom, jRead, jReal, jRealArithmetic, jRealDivide, jRealUnaryArithmetic, jRegister, jRepeat, jRetract, jRound, jSetArrayElement, jSin, jSort, jSqrt, jStatic, jSubtract, jSubtractArray, jTan, jTerm, jTermToList, jTime, jTrinaryBuiltinPredicate, jTrue, jTruncate, jUnaryArithmetic, jUnaryBuiltinPredicate, jUnaryOperator, jUnify, jUnionArray, jUnregister, jVariable, jWrite

public interface iTerm
extends iName, iValue, iUnifiable, iConsultable

This is the fundamental interface for Prolog terms.

Author:
Glendon Holst

Field Summary
static int EQUAL
           
static int GREATER_THAN
           
static int LESS_THAN
           
 
Method Summary
 int compare(jTerm term, boolean var_equal)
          The public interface for term comparision, it calls the protected compare that sub-classes must override.
 void consult(jKnowledgeBase kb)
          Consult the given jKnowledgeBase and cache any invariant values (those which would not change until the next time the jKnowledgeBase changes).
 void consultReset()
          Called when the jKnowledgeBase changes.
 jTerm copy()
          Public member function which creates a copy of this term.
 jTerm copy(jVariableRegistry vars)
          Internal member function which creates a copy of this term.
 jTerm duplicate(jVariable[] vars)
          Creates a complete and entirely independant duplicate of this term.
 void enumerateVariables(jVariableVector v, boolean all)
          Adds variables belonging to this term (or belonging to any sub-part of this term) to the jVariableVector.
 boolean equivalence(jTerm term, jEquivalenceMapping v)
          The public interface for evaluating term equivalence (i.e., structural similarity).
 java.lang.String getName()
          Returns the name of this instance.
 jTerm getTerm()
          Returns the non-evaluated jTerm representation of this term.
 jTerm getValue()
          Return the value of this object after.
 boolean isConsultNeeded()
          Determine if cached values already exist and hence if consulting is required.
 void registerUnboundVariables(jUnifiedVector v)
          Adds any unbound variables belonging to this term (or belonging to any sub-part of this term) to the jUnifiedVector
 void registerVariables(jVariableVector v)
          Adds all variables belonging to this term (or belonging to any sub-part of this term) to the jUnifiedVector Should be called during the consultation phase by rules for their owned terms both head and base.
 boolean requiresCompleteVariableState()
          Call to determine if enclosing rule should record all variable states.
 java.lang.String toString(boolean usename)
          Produces a string identifying this term, suitable for display to the console.
 boolean unify(jTerm term, jUnifiedVector v)
          Determines if this instance and term unify.
 

Field Detail

LESS_THAN

static final int LESS_THAN
See Also:
Constant Field Values

EQUAL

static final int EQUAL
See Also:
Constant Field Values

GREATER_THAN

static final int GREATER_THAN
See Also:
Constant Field Values
Method Detail

getValue

jTerm getValue()
Description copied from interface: iValue
Return the value of this object after.

Specified by:
getValue in interface iValue
Returns:
jTerm which represents the evaluated value of this instance, or the value bound to this instance, in the case of a variable.

getTerm

jTerm getTerm()
Returns the non-evaluated jTerm representation of this term. Variables return the non-evaluated terms they are bound to.

Returns:
jTerm of the non-evaluated term bound to this instance.

getName

java.lang.String getName()
Description copied from interface: iName
Returns the name of this instance.

Specified by:
getName in interface iName
Returns:
String containing name of this instance.

compare

int compare(jTerm term,
            boolean var_equal)
The public interface for term comparision, it calls the protected compare that sub-classes must override.

Parameters:
term - the jTerm to compare with this instance of jTerm.
var_equal - if var_equal is true, then unbound variables are considered equal. var_equal = false is standard prolog behavior.
Returns:
LESS_THAN if this instance is less than term, EQUAL if the two terms are equal, and GREATER_THAN if this instance is greater than term.

requiresCompleteVariableState

boolean requiresCompleteVariableState()
Call to determine if enclosing rule should record all variable states. A rules goal only tracks variables which were unified, and relies on stack unwinding to unbind all variables. Terms such as cut, which jump back to the containing rules goal require that all variables are restored.

Returns:
true if all variable bindings must be recorded by the rule containing this term. false otherwise. Normally returns false

registerUnboundVariables

void registerUnboundVariables(jUnifiedVector v)
Adds any unbound variables belonging to this term (or belonging to any sub-part of this term) to the jUnifiedVector

Parameters:
v - The jUnifiedVector where unbound variables are added to. This parameter is used to as output to the caller, not as input.

registerVariables

void registerVariables(jVariableVector v)
Adds all variables belonging to this term (or belonging to any sub-part of this term) to the jUnifiedVector Should be called during the consultation phase by rules for their owned terms both head and base. All variables encountered should be unbound; hence it is NOT recommended to call this method after the consultation phase completes (e.g., after a query proof). After call, this term should not be modified in any way.

Parameters:
v - The jUnifiedVector where variables are added to. This parameter is used to as output to the caller, not as input.

enumerateVariables

void enumerateVariables(jVariableVector v,
                        boolean all)
Adds variables belonging to this term (or belonging to any sub-part of this term) to the jVariableVector. If a variable is bound, it is not included in the enumeration.

Parameters:
v - The jVariabeVector where variables are added to. This parameter is used to as output to the caller, not as input.
all - If true, then all variables should register, otherwise only add non-existentially qualified variables.

equivalence

boolean equivalence(jTerm term,
                    jEquivalenceMapping v)
The public interface for evaluating term equivalence (i.e., structural similarity).

Parameters:
term - the jTerm to compare with this instance of jTerm.
v - v is the collection of equivalent variable pairs found. It should be empty when first calling this function.
Returns:
true if this instance is equivalent to term, false otherwise.

unify

boolean unify(jTerm term,
              jUnifiedVector v)
Description copied from interface: iUnifiable
Determines if this instance and term unify. Every variable which was previously unbound, but which becomes bound during the unification must register itself with the jUnifiedVector. It is the callers responsibility to deal with the unified vector.

Specified by:
unify in interface iUnifiable
Parameters:
term - the term to unify with this instance.
v - the vector of variables bound during unification. Even if unification fails, this vector may contain recently bound vectors. This parameter is used to as output to the caller, not as input for unify.
Returns:
true if unification succeeded, false otherwise.

duplicate

jTerm duplicate(jVariable[] vars)
Creates a complete and entirely independant duplicate of this term. User should call only for terms for which registerVariables has already been invoked. Within duplicate, any other calls to duplicate should pass along the same vars array produced by registerVariables since the same duplication path previously taken by registerVariables should be taken by duplicate. This call is designed only for terms which belong to rules and are templates for instantiation. Any variables in the term should be unbound. As implied by the modification restrictions on registerVariables, terms and their children cannot change (especially during call!)

Parameters:
vars - The user passes in a duplicate of the variable vector produced from the previous call to registerVariables. vars is produced from the jVariableVector by creating a single duplicate variable for each variable. Since this is created in the same order as the registerVariables, it is now efficient for jVariables to return their unique duplicate.
Returns:
jTerm which is an instantiated duplicate of this term.

copy

jTerm copy()
Public member function which creates a copy of this term. This member function is designed to duplicate a term, but without the restrictions of the duplicate function. Sub-classes need not override, only implement the abstract copy(vars) member function. copy is not as efficient as duplicate.

Returns:
jTerm which is an instantiated copy of this term.

copy

jTerm copy(jVariableRegistry vars)
Internal member function which creates a copy of this term. This member function is designed to duplicate a term, but without the restrictions of the duplicate function. Should only be invoked by copy() or other copy(vars). Should only invoke other copy(vars) functions. Bound variables should return a copy of the bound term.

Parameters:
vars - The registry of variables and their duplicates. Initially this is empty. As variables generate copies, they add themselves and their copy to the jVariableRegistry, and this is output from the function call. Any further calls with the same vars ensures that the same variable (in a different term) returns the same copy.
Returns:
jTerm which is an instantiated copy of this term.

consult

void consult(jKnowledgeBase kb)
Description copied from interface: iConsultable
Consult the given jKnowledgeBase and cache any invariant values (those which would not change until the next time the jKnowledgeBase changes). Where possible, consultable objects should minimize computation and assume that any cached values are still accurate.

Specified by:
consult in interface iConsultable
Parameters:
kb - the knowledge base which attempted proofs are based upon.

consultReset

void consultReset()
Description copied from interface: iConsultable
Called when the jKnowledgeBase changes. Should set all cached values to dirty so that a following call to consult would perform a full lookup as required.

Specified by:
consultReset in interface iConsultable

isConsultNeeded

boolean isConsultNeeded()
Description copied from interface: iConsultable
Determine if cached values already exist and hence if consulting is required. If object does not knowimmediatly whether consulting is needed, then assuming it is required.

Specified by:
isConsultNeeded in interface iConsultable
Returns:
false if cached values are valid, true otherwise, if consult should be called.

toString

java.lang.String toString(boolean usename)
Produces a string identifying this term, suitable for display to the console. param usename determines whether to display variables by name or identity. false is the default for displaying the term, true for displaying this term in a user query.

Returns:
String which is a textual representation of this term.