se.sics.jasper
Class SPTerm

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

All Implemented Interfaces:

Term

public class SPTerm

extends java.lang.Object

implements Term

SPTerms are Java representations of Prolog terms. SPTerms do not contain Prolog terms themselves; Prolog terms are always stored on the Prolog heap. Instead, an SPTerm object contains an SP_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 SP_term_refs. The actual life of an SP_term_ref (and of the Prolog term) are completely independent of the life of an SPTerm object. So, if a SPTerm object is garbage collected, the SP_term_ref and the Prolog term may very well be alive and well inside the Prolog stack. On the other hand, just because an SPTerm object is not GC:d, that does not mean that the Prolog term is still alive. The life-span of SP_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 SP_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.

Fields inherited from interface se.sics.jasper.Term

TYPE_ATOM, TYPE_COMPOUND, TYPE_FLOAT, TYPE_INTEGER, TYPE_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() Throws an exception if the term is not valid.
void	CheckValid(SICStus sp)
int	compare(Term with) Compares 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() Invalidates the SPTerm object and makes the SP_term_ref available for re-use.
Term	getArg(int i, Term arg) Gets an argument from a compound term.
SPCanonicalAtom	getCanonicalAtom() Obtains the canonical representation of a Prolog atom.
double	getDouble() Obtains the value of the Prolog float.
int	getFunctorArity() Obtains the arity of a functor.
java.lang.String	getFunctorName() Obtains the name of a functor.
long	getInteger() Obtains the integer value of the Prolog term.
Term	getList(Term head, Term tail) Gets the head and tail of a Prolog list.
java.lang.String	getListChars() Obtains the value of a list of characters as a string.
java.lang.String	getNumberChars() Obtains 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() Obtains 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 an 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	putInteger(long value) Assigns the term to a Prolog integer from a Java long.
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.
Term[]	toPrologTermArray() Converts a list to an array of Terms.
java.lang.String	toString() Returns a string-respresentation of a term.
java.lang.String	toString(Term options) Returns a string-representation of a term.
SPTerm[]	toTermArray() Converts a list to an array of SPTerm.
int	type() Returns the type of this term.
boolean	unify(Term with) Unifies 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,
              IllegalTermException

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,
              IllegalTermException

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

Invalidates the SPTerm object and makes the SP_term_ref available for re-use. Accessing an invalid SPTerm object throws IllegalTermException.

Specified by:

delete in interface Term

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.

Specified by:

isValid in interface Term

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

Throws 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

Specified by:

type in interface Term

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.

Specified by:

isVariable in interface Term

Returns:

true if the term is a variable; false otherwise

isInteger

public boolean isInteger()
                  throws IllegalTermException

Tests if the term is an integer.

Specified by:

isInteger in interface Term

Returns:

true if the term is an integer; false otherwise

isAtom

public boolean isAtom()
               throws IllegalTermException

Tests if the term is an atom.

Specified by:

isAtom in interface Term

Returns:

true if the term is an atom; false otherwise

isFloat

public boolean isFloat()
                throws IllegalTermException

Tests if the term is a float.

Specified by:

isFloat in interface Term

Returns:

true if the term is a float; false otherwise

isCompound

public boolean isCompound()
                   throws IllegalTermException

Tests if the term is a compound term.

Specified by:

isCompound in interface 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=[_|_].

Specified by:

isList in interface Term

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.

Specified by:

isEmptyList in interface Term

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.

Specified by:

isAtomic in interface Term

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.

Specified by:

isNumber in interface Term

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.

putInteger

public SPTerm putInteger(long value)
                  throws ConversionFailedException,
                         IllegalTermException

Assigns the term to a Prolog integer from a Java long.

Parameters:

value - The value of the integer

Returns:

Returns a reference to itself

Throws:

ConversionFailedException - The term could not be converted to a integer.

Since:

3.9.1 FIXME: Should be made public when Java longs (64bit) can be put also on 32bit machines. /FIXED [PD] 3.9.2 Added in order to support 64bit platforms (Tru64)

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:

canonical_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 an SPCanonicalAtom object.

Parameters:

cAtom - 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 putObject(java.lang.Object).

Specified by:

getObject in interface Term

Returns:

A Java object

putTerm

public SPTerm putTerm(SPTerm new_term)
               throws ConversionFailedException,
                      IllegalTermException

Assigns the term to another Prolog term.

Parameters:

new_term - 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:

string - The String object

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:

string - 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

Obtains the integer value of the Prolog term.

Specified by:

getInteger in interface 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

Obtains the value of the Prolog float.

Specified by:

getDouble in interface Term

Returns:

The value of the Prolog float as a Java double.

Throws:

ConversionFailedException - The term could not be converted to a double.

getCanonicalAtom

public SPCanonicalAtom getCanonicalAtom()
                                 throws ConversionFailedException,
                                        AtomRegisterFailure,
                                        IllegalTermException

Obtains the canonical representation of a Prolog atom.

Returns:

The canonical representation of a Prolog atom as an 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

Obtains the value of the Prolog atom as a string.

Specified by:

getString in interface Term

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

Obtains the value of a list of characters as a string.

Specified by:

getListChars in interface Term

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

Obtains the value of a Prolog number as a string.

Specified by:

getNumberChars in interface Term

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

Obtains the name of a functor.

Specified by:

getFunctorName in interface Term

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

Obtains the arity of a functor.

Specified by:

getFunctorArity in interface Term

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 Term getList(Term head,
                    Term tail)
             throws ConversionFailedException,
                    IllegalTermException

Gets the head and tail of a Prolog list.

Specified by:

getList in interface Term

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 Term getArg(int i,
                   Term arg)
            throws ConversionFailedException,
                   IllegalTermException

Gets an argument from a compound term. Similar to calling arg/3 with the third argument unbound.

Specified by:

getArg in interface Term

Parameters:

i - The number of the argument.

arg - The term to which the ith 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(Term with)
              throws IllegalTermException

Unifies the term with another term.

Specified by:

unify in interface Term

Parameters:

with - The term with which to unify.

Returns:

True/False depending on whether or not the unification succeeded.

compare

public int compare(Term with)
            throws IllegalTermException

Compares two terms according to standard order.

Specified by:

compare in interface Term

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.

Specified by:

toString in interface Term

Overrides:

toString in class java.lang.Object

toString

public java.lang.String toString(Term options)
                          throws SPException

Description copied from interface: Term

Returns a string-representation of a term. This is an interface to write_term/3, which see.

Specified by:

toString in interface Term

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.

toPrologTermArray

public Term[] toPrologTermArray()
                         throws ConversionFailedException,
                                IllegalTermException

Description copied from interface: Term

Converts a list to an array of Terms. Useful when examining lists returned from Prolog queries. This is of course only possible on a list.

Specified by:

toPrologTermArray in interface Term

Following copied from interface: se.sics.jasper.Term

Returns:

An array of the terms.