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.