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 on term-refs, consult the section on "Mixing C 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 are explained in detail in the User's Manual. 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.

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 a integer.
static int	SP_TYPE_VARIABLE The term is a variable.

Constructor Summary

SPTerm()
Creates a null-term, but doesn't require a pointer to the SICStus object.

SPTerm(long nativeTermRef)
Creates a term given only the native term ref.

SPTerm(SICStus sp)
Creates a null-term.

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, java.lang.String value)
Creates a term initialized to a Prolog atom.

SPTerm(SICStus sp, java.lang.String functor, int arity, SPTerm[] args)
Creates a term initialized to a Prolog compound term.

Method Summary

int	compare(SPTerm with) Compare two terms according to standard order.
SPTerm	consFunctor(java.lang.String functor, int arity, 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.
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	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.
boolean	isNumber() Tests if the term is a number.
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	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 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 a 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)
       throws IllegalCallerException

Creates a null-term. (i.e. the empty list, '[]')

Parameters:

sp - Pointer to the SICStus object.

Throws:

IllegalCallerException -

SPTerm

public SPTerm(SICStus sp,
              int value)
       throws IllegalCallerException

Creates a term initialized to a Prolog integer.

Parameters:

sp - Pointer to the SICStus object.

value - Initial value of the integer.

Throws:

IllegalCallerException -

See Also:

putInteger(int)

SPTerm

public SPTerm(SICStus sp,
              double value)
       throws IllegalCallerException

Creates a term initialized to a Prolog float.

Parameters:

sp - Pointer to the SICStus object.

value - Initial value of the float.

Throws:

IllegalCallerException -

See Also:

putFloat(double)

SPTerm

public SPTerm(SICStus sp,
              float value)
       throws IllegalCallerException

Creates a term initialized to a Prolog float.

Parameters:

sp - Pointer to the SICStus object.

value - Initial value of the float.

Throws:

IllegalCallerException -

See Also:

putFloat(double)

SPTerm

public SPTerm(SICStus sp,
              java.lang.String value)
       throws IllegalCallerException

Creates a term initialized to a Prolog atom.

Parameters:

sp - Pointer to the SICStus object.

value - String describing the initial value of the atom.

Throws:

IllegalCallerException -

See Also:

putString(java.lang.String)

SPTerm

public SPTerm(SICStus sp,
              java.lang.String functor,
              int arity,
              SPTerm[] args)
       throws IllegalCallerException

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

args - The arguments as an array of SPTerm:s

Throws:

IllegalCallerException -

See Also:

consFunctor(java.lang.String, int, se.sics.jasper.SPTerm[])

SPTerm

public SPTerm(long nativeTermRef)
       throws IllegalCallerException

Creates a term given only the native term ref. It should really have been private, but for internal technical reasons it must be public.

Throws:

IllegalCallerException - The use of this constructor is strongly discouraged!

SPTerm

public SPTerm()
       throws IllegalCallerException

Creates a null-term, but doesn't require a pointer to the SICStus object. Should really have been private, but for internal technical reasons it must be public.

Throws:

IllegalCallerException - The use of this constructor is strongly discouraged!

Method Detail

type

public int type()

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()

Tests if the term is a variable.

Returns:

true if the term is a variable; false otherwise

isInteger

public boolean isInteger()

Tests if the term is an integer.

Returns:

true if the term is an integer; false otherwise

isAtom

public boolean isAtom()

Tests if the term is an atom.

Returns:

true if the term is an atom; false otherwise

isFloat

public boolean isFloat()

Tests if the term is a float.

Returns:

true if the term is a float; false otherwise

isCompound

public boolean isCompound()

Tests if the term is a compound term.

Returns:

true if the term is a compound term; false otherwise

isList

public boolean isList()

Tests if the term is a list.

Returns:

true if the term is a list; false otherwise

isAtomic

public boolean isAtomic()

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()

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

Assigns the term to an unbound variable.

Returns:

Returns a reference to itself

Throws:

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

IllegalCallerException -

putInteger

public SPTerm putInteger(int value)
                  throws ConversionFailedException,
                         IllegalCallerException

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.

IllegalCallerException -

putFloat

public SPTerm putFloat(double value)
                throws ConversionFailedException,
                       IllegalCallerException

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.

IllegalCallerException -

putFloat

public SPTerm putFloat(float value)
                throws ConversionFailedException,
                       IllegalCallerException

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.

IllegalCallerException -

putString

public SPTerm putString(java.lang.String value)
                 throws ConversionFailedException,
                        IllegalCallerException

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.

IllegalCallerException -

putAtom

public SPTerm putAtom(long canonical_value)
               throws ConversionFailedException,
                      IllegalCallerException

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.

IllegalCallerException -

putCanonicalAtom

public SPTerm putCanonicalAtom(SPCanonicalAtom cAtom)
                        throws ConversionFailedException,
                               IllegalCallerException

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.

IllegalCallerException -

See Also:

SPCanonicalAtom

putObject

public SPTerm putObject(java.lang.Object obj)
                 throws ConversionFailedException,
                        IllegalCallerException

Assigns the term to a 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.

IllegalCallerException -

getObject

public java.lang.Object getObject()
                           throws se.sics.jasper.NativeCodeException,
                                  IllegalCallerException

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

Throws:

IllegalCallerException -

putTerm

public SPTerm putTerm(SPTerm new_term)
               throws ConversionFailedException,
                      IllegalCallerException

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.

IllegalCallerException -

putListChars

public SPTerm putListChars(java.lang.String string)
                    throws ConversionFailedException,
                           IllegalCallerException

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.

IllegalCallerException -

putNumberChars

public SPTerm putNumberChars(java.lang.String string)
                      throws ConversionFailedException,
                             IllegalCallerException

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.

IllegalCallerException -

putFunctor

public SPTerm putFunctor(java.lang.String functor,
                         int arity)
                  throws ConversionFailedException,
                         IllegalCallerException

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.

IllegalCallerException -

consFunctor

public SPTerm consFunctor(java.lang.String functor,
                          int arity,
                          SPTerm[] args)
                   throws ConversionFailedException,
                          IllegalCallerException

Assigns the term to a compount term.

Parameters:

functor - The term's functor as a Java String

arity - The term's arity

args - The arguments of the term

Returns:

Returns a reference to itself.

Throws:

ConversionFailedException - The term could not be converted to compound term.

IllegalCallerException -

putList

public SPTerm putList()
               throws ConversionFailedException,
                      IllegalCallerException

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.

IllegalCallerException -

consList

public SPTerm consList(SPTerm head,
                       SPTerm tail)
                throws ConversionFailedException,
                       IllegalCallerException

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.

IllegalCallerException -

getInteger

public long getInteger()
                throws ConversionFailedException,
                       IllegalCallerException

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.

IllegalCallerException -

getDouble

public double getDouble()
                 throws ConversionFailedException,
                        IllegalCallerException

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.

IllegalCallerException -

getAtom

public long getAtom()
             throws ConversionFailedException,
                    IllegalCallerException

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.

IllegalCallerException -

getCanonicalAtom

public SPCanonicalAtom getCanonicalAtom()
                                 throws ConversionFailedException,
                                        IllegalCallerException,
                                        AtomRegisterFailure

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.

IllegalCallerException -

AtomRegisterFailure -

See Also:

SPCanonicalAtom

getString

public java.lang.String getString()
                           throws ConversionFailedException,
                                  IllegalCallerException

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.

IllegalCallerException -

getListChars

public java.lang.String getListChars()
                              throws ConversionFailedException,
                                     IllegalCallerException

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.

IllegalCallerException -

getNumberChars

public java.lang.String getNumberChars()
                                throws ConversionFailedException,
                                       IllegalCallerException

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.

IllegalCallerException -

getFunctorName

public java.lang.String getFunctorName()
                                throws ConversionFailedException,
                                       IllegalCallerException

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.

IllegalCallerException -

getFunctorArity

public int getFunctorArity()
                    throws ConversionFailedException,
                           IllegalCallerException

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.

IllegalCallerException -

getList

public SPTerm getList(SPTerm head,
                      SPTerm tail)
               throws ConversionFailedException,
                      IllegalCallerException

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

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.

IllegalCallerException -

unify

public boolean unify(SPTerm with)
              throws IllegalCallerException

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.

Throws:

IllegalCallerException -

compare

public int compare(SPTerm with)
            throws IllegalCallerException

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.

Throws:

IllegalCallerException -

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

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.

IllegalCallerException -