se.sics.jasper
Class SPTerm

java.lang.Object
  |
  +--se.sics.jasper.SPTerm

public class SPTerm
extends java.lang.Object

SPTerms are Java representations of Prolog terms. SPTerms do not contain Prolog terms themselves, Prolog terms are always stored on the Prolog heap. Instead a SPTerm object contains a so-called term-reference (often abbreviated term-ref), which is an index into a stack maintained by Prolog. This stack in turn contains references into the Prolog heap. For more information, consult the section on "Mixing Java and Prolog" in the SICStus Prolog User's Manual.

In other words, SPTerm objects are only handles to term-refs. The actual life of a term-ref (and of the Prolog term) are completely independent of the life of a SPTerm object. So, if a SPTerm object is garbage collected, the term-ref and the Prolog term may very well be alive and well inside the Prolog stack. On the other hand, just because a SPTerm object is not GC:d, that does not mean that the Prolog term is still alive. The life-span of term-refs and Prolog terms are explained in detail in the User's Manual Section "SPTerm and Memory".

The methods in this class are encapsulations of the C-functions in the C-Prolog interface which accesses term-refs and their underlying Prolog terms.

You should not inherit from SPTerm.


Field Summary
static int SP_TYPE_ATOM
          The term is an atom.
static int SP_TYPE_COMPOUND
          The term is a compound term.
static int SP_TYPE_FLOAT
          The term is a float.
static int SP_TYPE_INTEGER
          The term is an integer.
static int SP_TYPE_VARIABLE
          The term is a variable.
 
Constructor Summary
SPTerm(SICStus sp)
          Creates a null-term (i.e.
SPTerm(SICStus sp, double value)
          Creates a term initialized to a Prolog float.
SPTerm(SICStus sp, float value)
          Creates a term initialized to a Prolog float.
SPTerm(SICStus sp, int value)
          Creates a term initialized to a Prolog integer.
SPTerm(SICStus sp, SPTerm value)
          Creates a term initialized to an existing term.
SPTerm(SICStus sp, java.lang.String value)
          Creates a term initialized to a Prolog atom.
SPTerm(SICStus sp, java.lang.String functor, int arity, SPTerm[] args)
          Deprecated. Do not pass the arity argument.
SPTerm(SICStus sp, java.lang.String functor, SPTerm[] args)
          Creates a term initialized to a Prolog compound term.
 
Method Summary
 void CheckValid()
          Throw an exception if the term is not valid.
 void CheckValid(SICStus sp)
           
 int compare(SPTerm with)
          Compare two terms according to standard order.
 SPTerm consFunctor(java.lang.String functor, int arity, SPTerm[] args)
          Deprecated. Use consFunctor without arity argument instead.
 SPTerm consFunctor(java.lang.String functor, SPTerm[] args)
          Assigns the term to a compount term.
 SPTerm consList(SPTerm head, SPTerm tail)
          Assigns the term to a list with given head and tail.
 void delete()
          Invalidate the SPTerm object and make the term-ref available for re-use.
 SPTerm getArg(int i, SPTerm arg)
          Get an argument from a compound term.
 long getAtom()
          Deprecated. Use getCanonicalAtom instead.
 SPCanonicalAtom getCanonicalAtom()
          Obtain the canonical representation of a Prolog atom.
 double getDouble()
          Obtain the value of the Prolog float.
 int getFunctorArity()
          Obtain the arity of a functor.
 java.lang.String getFunctorName()
          Obtain the name of a functor.
 long getInteger()
          Obtain the integer value of the Prolog term.
 SPTerm getList(SPTerm head, SPTerm tail)
          Get the head and tail of a Prolog list.
 java.lang.String getListChars()
          Obtain the value of a list of characters as a string.
 java.lang.String getNumberChars()
          Obtain the value of a Prolog number as a string.
 java.lang.Object getObject()
          Returns the object encapsulated in the Prolog term.
 java.lang.String getString()
          Obtain the value of the Prolog atom as a string.
 boolean isAtom()
          Tests if the term is an atom.
 boolean isAtomic()
          Tests if the term is atomic.
 boolean isCompound()
          Tests if the term is a compound term.
 boolean isEmptyList()
          Tests if the term is the empty list.
 boolean isFloat()
          Tests if the term is a float.
 boolean isInteger()
          Tests if the term is an integer.
 boolean isList()
          Tests if the term is a list cell.
 boolean isNumber()
          Tests if the term is a number.
 boolean isValid()
          Tests if the Prolog term referenced is still accessible through this object.
 boolean isValid(SICStus sp)
          As isValid().
 boolean isVariable()
          Tests if the term is a variable.
 SPTerm putAtom(long canonical_value)
          Deprecated. Use putCanonicalAtom instead.
 SPTerm putCanonicalAtom(SPCanonicalAtom cAtom)
          Assigns the term to a Prolog atom, given the canonical representation of the atom as a SPCanonicalAtom object.
 SPTerm putEmptyList()
          Assigns the term to an empty list [].
 SPTerm putFloat(double value)
          Assigns the term to a Prolog float from a Java double.
 SPTerm putFloat(float value)
          Assigns the term to a Prolog float from a Java float.
 SPTerm putFunctor(java.lang.String functor, int arity)
          Assigns the term to a compound term with all arguments initialized to unbound variables.
 SPTerm putInteger(int value)
          Assigns the term to a Prolog integer from a Java int.
 SPTerm putList()
          Assigns the term to a list whose head and tail are both unbound variables.
 SPTerm putListChars(java.lang.String string)
          Assigns the term to a list of character codes from a Java String.
 SPTerm putNumberChars(java.lang.String string)
          Assigns the term to a Prolog number from a string.
 SPTerm putObject(java.lang.Object obj)
          Assigns the term to a *global* reference to a Java object.
 SPTerm putString(java.lang.String value)
          Assigns the term to a Prolog atom from a Java String.
 SPTerm putTerm(SPTerm new_term)
          Assigns the term to another Prolog term.
 SPTerm putVariable()
          Assigns the term to an unbound variable.
 java.lang.String toString()
          Returns a string-respresentation of a term.
 SPTerm[] toTermArray()
          Converts a list to an array of SPTerm.
 int type()
          Returns the type of this term.
 boolean unify(SPTerm with)
          Unify the term with another term.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

SP_TYPE_VARIABLE

public static final int SP_TYPE_VARIABLE
The term is a variable.
See Also:
type()

SP_TYPE_INTEGER

public static final int SP_TYPE_INTEGER
The term is an integer.
See Also:
type()

SP_TYPE_ATOM

public static final int SP_TYPE_ATOM
The term is an atom.
See Also:
type()

SP_TYPE_FLOAT

public static final int SP_TYPE_FLOAT
The term is a float.
See Also:
type()

SP_TYPE_COMPOUND

public static final int SP_TYPE_COMPOUND
The term is a compound term.
See Also:
type()
Constructor Detail

SPTerm

public SPTerm(SICStus sp)
Creates a null-term (i.e. the empty list, '[]').
Parameters:
sp - Pointer to the SICStus object.

SPTerm

public SPTerm(SICStus sp,
              SPTerm value)
       throws IllegalTermException,
              ConversionFailedException
Creates a term initialized to an existing term. Modifications to the created SPTerm does not affect the input SPTerm.
Parameters:
sp - Pointer to the SICStus object.
value - The SPTerm object whose term to use
See Also:
putTerm(se.sics.jasper.SPTerm)

SPTerm

public SPTerm(SICStus sp,
              int value)
Creates a term initialized to a Prolog integer.
Parameters:
sp - Pointer to the SICStus object.
value - Initial value of the integer.
See Also:
putInteger(int)

SPTerm

public SPTerm(SICStus sp,
              double value)
Creates a term initialized to a Prolog float.
Parameters:
sp - Pointer to the SICStus object.
value - Initial value of the float.
See Also:
putFloat(double)

SPTerm

public SPTerm(SICStus sp,
              float value)
Creates a term initialized to a Prolog float.
Parameters:
sp - Pointer to the SICStus object.
value - Initial value of the float.
See Also:
putFloat(double)

SPTerm

public SPTerm(SICStus sp,
              java.lang.String value)
       throws ConversionFailedException
Creates a term initialized to a Prolog atom.
Parameters:
sp - Pointer to the SICStus object.
value - String describing the initial value of the atom.
See Also:
putString(java.lang.String)

SPTerm

public SPTerm(SICStus sp,
              java.lang.String functor,
              SPTerm[] args)
       throws ConversionFailedException
Creates a term initialized to a Prolog compound term.
Parameters:
sp - Pointer to the SICStus object.
functor - The functor of the compound term as a string
args - The arguments as an array of SPTerm:s
See Also:
consFunctor(java.lang.String, se.sics.jasper.SPTerm[])

SPTerm

public SPTerm(SICStus sp,
              java.lang.String functor,
              int arity,
              SPTerm[] args)
       throws ConversionFailedException
Deprecated. Do not pass the arity argument.

Creates a term initialized to a Prolog compound term.
Parameters:
sp - Pointer to the SICStus object.
functor - The functor of the compound term as a string
arity - The arity of the compound term (ignored)
args - The arguments as an SPTerm array.
See Also:
consFunctor(java.lang.String, se.sics.jasper.SPTerm[])
Method Detail

delete

public void delete()
            throws SPException
Invalidate the SPTerm object and make the term-ref available for re-use. Accessing an invalid SPTerm object throws IllegalTermException.
See Also:
SICStus.setReuseTermRefs(boolean)

isValid

public boolean isValid()
Tests if the Prolog term referenced is still accessible through this object. SPTerm object becomes invalid as the result of of explicit delete, closing, cutting or asking for the nextSolution of an enclosing SPQuery.
Returns:
true if still valid; false otherwise. The result is only guaranteed to remain valid while inside a block synchronized on the SICStus object.

isValid

public boolean isValid(SICStus sp)
As isValid(). In addition verifies that this SPTerm belongs to the SICStus object argument.

CheckValid

public void CheckValid()
                throws IllegalTermException
Throw an exception if the term is not valid.
See Also:
isValid()

CheckValid

public void CheckValid(SICStus sp)
                throws IllegalTermException

type

public int type()
         throws IllegalTermException
Returns the type of this term. The return value is as defined by the constants SP_TYPE_INTEGER, SP_TYPE_FLOAT, SP_TYPE_ATOM, SP_TYPE_VARIABLE, and SP_TYPE_COMPOUND
See Also:
SP_TYPE_INTEGER, SP_TYPE_ATOM, SP_TYPE_FLOAT, SP_TYPE_VARIABLE, SP_TYPE_COMPOUND, isVariable(), isInteger(), isAtom(), isFloat(), isCompound(), isList(), isAtomic(), isNumber()

isVariable

public boolean isVariable()
                   throws IllegalTermException
Tests if the term is a variable.
Returns:
true if the term is a variable; false otherwise

isInteger

public boolean isInteger()
                  throws IllegalTermException
Tests if the term is an integer.
Returns:
true if the term is an integer; false otherwise

isAtom

public boolean isAtom()
               throws IllegalTermException
Tests if the term is an atom.
Returns:
true if the term is an atom; false otherwise

isFloat

public boolean isFloat()
                throws IllegalTermException
Tests if the term is a float.
Returns:
true if the term is a float; false otherwise

isCompound

public boolean isCompound()
                   throws IllegalTermException
Tests if the term is a compound term.
Returns:
true if the term is a compound term; false otherwise

isList

public boolean isList()
               throws IllegalTermException
Tests if the term is a list cell. Equivalent to the Prolog code isList(T) :- nonvar(T), T=[_|_].
Returns:
true if the term is a list cell; false otherwise

isEmptyList

public boolean isEmptyList()
                    throws IllegalTermException
Tests if the term is the empty list.
Returns:
true if the term is the atom []; false otherwise

isAtomic

public boolean isAtomic()
                 throws IllegalTermException
Tests if the term is atomic. A term is atomic if it is instantiated to an atom or a number.
Returns:
true if the term is atomic; false otherwise

isNumber

public boolean isNumber()
                 throws IllegalTermException
Tests if the term is a number. A number is a term instantiated to an integer or a float.
Returns:
true if the term is a number; false otherwise

putVariable

public SPTerm putVariable()
                   throws ConversionFailedException,
                          IllegalTermException
Assigns the term to an unbound variable.
Returns:
Returns a reference to itself
Throws:
ConversionFailedException - The term could not be converted to a variable.

putInteger

public SPTerm putInteger(int value)
                  throws ConversionFailedException,
                         IllegalTermException
Assigns the term to a Prolog integer from a Java int.
Parameters:
value - The value of the integer
Returns:
Returns a reference to itself
Throws:
ConversionFailedException - The term could not be converted to a integer.

putFloat

public SPTerm putFloat(double value)
                throws ConversionFailedException,
                       IllegalTermException
Assigns the term to a Prolog float from a Java double.
Parameters:
value - The value of the float
Returns:
Returns a reference to itself
Throws:
ConversionFailedException - The term could not be converted to a float.

putFloat

public SPTerm putFloat(float value)
                throws ConversionFailedException,
                       IllegalTermException
Assigns the term to a Prolog float from a Java float.
Parameters:
value - The value of the float
Returns:
Returns a reference to itself
Throws:
ConversionFailedException - The term could not be converted to a float.

putString

public SPTerm putString(java.lang.String value)
                 throws ConversionFailedException,
                        IllegalTermException
Assigns the term to a Prolog atom from a Java String.
Parameters:
value - The value of the atom as a String
Returns:
Returns a reference to itself.
Throws:
ConversionFailedException - The term could not be converted to an atom.

putEmptyList

public SPTerm putEmptyList()
                    throws ConversionFailedException,
                           IllegalTermException
Assigns the term to an empty list [].
Returns:
Returns a reference to itself.

putAtom

public SPTerm putAtom(long canonical_value)
               throws ConversionFailedException,
                      IllegalTermException
Deprecated. Use putCanonicalAtom instead.

Assigns the term to a Prolog atom. The argument is the canonical representation of a Prolog atom represented as a Java long.
Parameters:
value - The canonical representation of an atom.
Returns:
Returns a reference to itself.
Throws:
ConversionFailedException - The term could not be converted to an atom.

putCanonicalAtom

public SPTerm putCanonicalAtom(SPCanonicalAtom cAtom)
                        throws ConversionFailedException,
                               IllegalTermException
Assigns the term to a Prolog atom, given the canonical representation of the atom as a SPCanonicalAtom object.
Parameters:
value - The canonical representation of an atom.
Returns:
Returns a reference to itself.
Throws:
ConversionFailedException - The term could not be converted to an atom.
See Also:
SPCanonicalAtom

putObject

public SPTerm putObject(java.lang.Object obj)
                 throws ConversionFailedException,
                        IllegalTermException
Assigns the term to a *global* reference to a Java object.
Parameters:
obj - A reference to a Java object.
Returns:
Returns a reference to itself.
Throws:
ConversionFailedException - The term could not be converted to a Java object reference.

getObject

public java.lang.Object getObject()
                           throws se.sics.jasper.NativeCodeException,
                                  IllegalTermException
Returns the object encapsulated in the Prolog term. This method should only be called on terms to which a Java object has been assigned using the method SPTerm#putObject.
Returns:
A Java object

putTerm

public SPTerm putTerm(SPTerm new_term)
               throws ConversionFailedException,
                      IllegalTermException
Assigns the term to another Prolog term.
Parameters:
value - The term's new value
Returns:
Returns a reference to itself.
Throws:
ConversionFailedException - The term could not be converted to another term.

putListChars

public SPTerm putListChars(java.lang.String string)
                    throws ConversionFailedException,
                           IllegalTermException
Assigns the term to a list of character codes from a Java String.
Parameters:
value - The list of character codes
Returns:
Returns a reference to itself.
Throws:
ConversionFailedException - The term could not be converted to list of characters.

putNumberChars

public SPTerm putNumberChars(java.lang.String string)
                      throws ConversionFailedException,
                             IllegalTermException
Assigns the term to a Prolog number from a string.
Parameters:
value - The string containing the printed representation of the number.
Returns:
Returns a reference to itself.
Throws:
ConversionFailedException - The term could not be converted to number.

putFunctor

public SPTerm putFunctor(java.lang.String functor,
                         int arity)
                  throws ConversionFailedException,
                         IllegalTermException
Assigns the term to a compound term with all arguments initialized to unbound variables.
Parameters:
functor - The term's functor as a Java String
arity - The term's arity
Returns:
Returns a reference to itself.
Throws:
ConversionFailedException - The term could not be converted to compound term.

consFunctor

public SPTerm consFunctor(java.lang.String functor,
                          SPTerm[] args)
                   throws ConversionFailedException,
                          IllegalTermException
Assigns the term to a compount term.
Parameters:
functor - The term's functor as a Java String
args - The arguments of the term
Returns:
Returns a reference to itself.
Throws:
ConversionFailedException - The term could not be converted to compound term.

consFunctor

public SPTerm consFunctor(java.lang.String functor,
                          int arity,
                          SPTerm[] args)
                   throws ConversionFailedException,
                          IllegalTermException
Deprecated. Use consFunctor without arity argument instead.

Assigns the term to a compount term.
Parameters:
functor - The term's functor as a Java String
arity - The term's arity (ignored)
args - The arguments of the term
Returns:
Returns a reference to itself.
Throws:
ConversionFailedException - The term could not be converted to compound term.

putList

public SPTerm putList()
               throws ConversionFailedException,
                      IllegalTermException
Assigns the term to a list whose head and tail are both unbound variables.
Returns:
Returns a reference to itself.
Throws:
ConversionFailedException - The term could not be converted to an empty list.

consList

public SPTerm consList(SPTerm head,
                       SPTerm tail)
                throws ConversionFailedException,
                       IllegalTermException
Assigns the term to a list with given head and tail.
Parameters:
head - The head of the list
tail - The tail of the list
Returns:
Returns a reference to itself.
Throws:
ConversionFailedException - The term could not be converted to list.

getInteger

public long getInteger()
                throws ConversionFailedException,
                       IllegalTermException
Obtain the integer value of the Prolog term.
Returns:
The value of the Prolog term as a Java long.
Throws:
ConversionFailedException - The term could not be converted to an integer.

getDouble

public double getDouble()
                 throws ConversionFailedException,
                        IllegalTermException
Obtain the value of the Prolog float.
Returns:
The value of the Prolog float as a Java double.
Throws:
ConversionFailedException - The term could not be converted to a double.

getAtom

public long getAtom()
             throws ConversionFailedException,
                    IllegalTermException
Deprecated. Use getCanonicalAtom instead.

Obtain the canonical representation of a Prolog atom.
Returns:
The canonical representation of a Prolog atom as a Java long.
Throws:
ConversionFailedException - The term could not be converted to the canonical representation of an atom.

getCanonicalAtom

public SPCanonicalAtom getCanonicalAtom()
                                 throws ConversionFailedException,
                                        AtomRegisterFailure,
                                        IllegalTermException
Obtain the canonical representation of a Prolog atom.
Returns:
The canonical representation of a Prolog atom as a SPCanonicalAtom object.
Throws:
ConversionFailedException - The term could not be converted to the canonical representation of an atom.
AtomRegisterFailure -  
See Also:
SPCanonicalAtom

getString

public java.lang.String getString()
                           throws ConversionFailedException,
                                  IllegalTermException
Obtain the value of the Prolog atom as a string.
Returns:
The value of the Prolog atom as a Java String.
Throws:
ConversionFailedException - The term could not be converted to a string.

getListChars

public java.lang.String getListChars()
                              throws ConversionFailedException,
                                     IllegalTermException
Obtain the value of a list of characters as a string.
Returns:
The value of the list as a Java String.
Throws:
ConversionFailedException - The term could not be converted to a list of characters.

getNumberChars

public java.lang.String getNumberChars()
                                throws ConversionFailedException,
                                       IllegalTermException
Obtain the value of a Prolog number as a string.
Returns:
The value of the number as a Java String.
Throws:
ConversionFailedException - The term could not be converted to a number.

getFunctorName

public java.lang.String getFunctorName()
                                throws ConversionFailedException,
                                       IllegalTermException
Obtain the name of a functor.
Returns:
The functor as a Java String.
Throws:
ConversionFailedException - The term could not be converted to the name of a functor.

getFunctorArity

public int getFunctorArity()
                    throws ConversionFailedException,
                           IllegalTermException
Obtain the arity of a functor.
Returns:
The arity of a functor as a Java int.
Throws:
ConversionFailedException - The term could not be converted to the arity of a functor.

getList

public SPTerm getList(SPTerm head,
                      SPTerm tail)
               throws ConversionFailedException,
                      IllegalTermException
Get the head and tail of a Prolog list.
Parameters:
head - The term which will be assigned the head
tail - The term which will be assigned the tail
Returns:
A reference to itself.
Throws:
ConversionFailedException - The term could not be converted to a list.

getArg

public SPTerm getArg(int i,
                     SPTerm arg)
              throws ConversionFailedException,
                     IllegalTermException
Get an argument from a compound term. Similar to calling arg/3 with the third argument unbound.
Parameters:
i - The number of the argument.
arg - The term to which the th argument will be assigned.
Returns:
A reference to itself.
Throws:
ConversionFailedException - The term could not be converted to the argument of a compound term.

unify

public boolean unify(SPTerm with)
              throws IllegalTermException
Unify the term with another term.
Parameters:
with - The term with which to unify.
Returns:
True/False depending on whether or not the unification succeeded.

compare

public int compare(SPTerm with)
            throws IllegalTermException
Compare two terms according to standard order.
Parameters:
with - The term to compare with.
Returns:
-1 if x @< y, 0 if x == y, and 1 if x @> y.

toString

public java.lang.String toString()
Returns a string-respresentation of a term. This is not very sophisticated, for example, it does not take operators or lists into account.
Overrides:
toString in class java.lang.Object

toTermArray

public SPTerm[] toTermArray()
                     throws ConversionFailedException,
                            IllegalTermException
Converts a list to an array of SPTerm. Useful when examining lists returned from Prolog queries. This is of course only possible on a list.
Returns:
An array of the terms.
Throws:
ConversionFailedException - If the term could not be converted to a list.