Term
Date: 2018-01-12

org.jpl7

## Class Term

- java.lang.Object
- - org.jpl7.Term

- Direct Known Subclasses:
    Atom, Compound, Float, Integer, JRef, Variable

      public abstract class Term
      extends java.lang.Object

  Term is the abstract base class for Compound, Atom, Variable, Integer and Float, which comprise a Java-oriented concrete syntax for Prolog. You cannot create instances of Term directly; rather, you should create instances of Term's concrete subclasses. Alternatively, use textToTerm() to construct a Term from its conventional Prolog source text representation.

  Copyright (C) 2004 Paul Singleton

  Copyright (C) 1998 Fred Dushin

  Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `Term` | `arg(int i)` returns the i-th (1+) argument of a Term; defined only for Compound
    `Term[]` | `args()` The arguments of this Term.
    `int` | `arity()` the arity of a Compound, Atom, Integer or Float
    `java.lang.String` | `atomType()`
    `java.math.BigInteger` | `bigValue()` the value (as a java.math.BigInteger) of an Integer, whether or not it is big
    `double` | `doubleValue()` the value (as a double) of an Integer or Float
    `float` | `floatValue()` the value (as a float) of an Integer or Float
    `boolean` | `hasFunctor(java.math.BigInteger name, int arity)` Tests whether this Term's functor has 'name' and 'arity'
    `boolean` | `hasFunctor(double name, int arity)` Tests whether this Term's functor has 'name' and 'arity'
    `boolean` | `hasFunctor(long name, int arity)` Tests whether this Term's functor has 'name' and 'arity'
    `boolean` | `hasFunctor(java.lang.String name, int arity)` Whether this Term's functor has 'name' and 'arity' (c.f.
    `int` | `intValue()` returns the value (as an int) of an Integer or Float
    `boolean` | `isAtom()` whether this Term is an Atom (of any type)
    `boolean` | `isBig()` Tests whether this Integer's value is too big to represent as a long.
    `boolean` | `isBigInteger()` Tests whether this Term is an Integer whose value is too big to represent as a long
    `boolean` | `isCompound()` Tests whether this Term is a Compound.
    `boolean` | `isFloat()` Tests whether this Term is an org.jpl7.Float.
    `boolean` | `isInteger()` Tests whether this Term is an org.jpl7.Integer.
    `boolean` | `isJFalse()` Tests whether this Term is a 'jfalse' structure, i.e.
    `boolean` | `isJNull()` Tests whether this Term is a 'jnull' structure, i.e.
    `boolean` | `isJRef()` Tests whether this Term is a (non-null, non-String) JPL reference to a Java object, e.g.
    `boolean` | `isJTrue()` Tests whether this Term is a 'jtrue' structure, i.e.
    `boolean` | `isJVoid()` Tests whether this Term is a 'jvoid' structure, i.e.
    `boolean` | `isListNil()` Tests whether this Term denotes an empty list within the current syntax ("traditional" or "modern").
    `boolean` | `isListPair()` Tests whether this Term is a list pair within the current syntax ("traditional" or "modern").
    `boolean` | `isVariable()` Tests whether this Term is a Variable.
    `java.lang.Object` | `jrefToObject()` Deprecated. Use `JRef.object()`
    `int` | `listLength()` Deprecated. Use `Util.listToLength(Term)`
    `long` | `longValue()` The (long) value of a Float or Integer.
    `java.lang.String` | `name()` The name of an Atom, Compound or Variable.
    `java.lang.Object` | `object()` The (non-null, non-String) Object which this org.jpl7.JRef refers to, iff this Term is a JRef.
    `static Term` | `objectToJRef(java.lang.Object object)` Deprecated. Use `JPL.newJRef(java.lang.Object)`
    `Term` | `putParams(Term[] ps)` This internal method is public because it needs to be callable via JNI, but it is not part of JPL's public API and should not be used by applications.
    `static void` | `putTerm(java.lang.Object obj, term_t termref)`
    `java.lang.Object` | `ref()` Deprecated. Use `JRef.object()`
    `static java.lang.String` | `toString(Term[] args)` Converts a list of Terms to a String.
    `Term[]` | `toTermArray()` returns an array of Terms whose elements are the respective members of this list, iff it is a list.
    `abstract int` | `type()` returns the type of this term, as one of org.jpl7.fli.Prolog.COMPOUND, .ATOM, .VARIABLE, .INTEGER, .FLOAT etc
    `abstract java.lang.String` | `typeName()` returns the name of the type of this term, as one of "Compound", "Atom", "Variable", "Integer", "Float" or "JRef"

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### arg

          public Term arg(int i)

      returns the i-th (1+) argument of a Term; defined only for Compound
      Returns:
        the i-th argument of a (Compound) Term
      Throws:
        `JPLException` - if Term is not a Compound

    - #### args

          public Term[] args()

      The arguments of this Term.

      Note that a SWI Prolog 7.x compound term can have zero arguments.

      This method returns an empty Term[] from an Atom, Float, Integer or JRef, approximating the behaviour of SWI Prolog's =../2

      Returns:
        the arguments of a Compound
      Throws:
        `JPLException` - if the Term is a Variable

    - #### arity

          public int arity()

      the arity of a Compound, Atom, Integer or Float
      Returns:
        the arity of a Compound, Atom, Integer or Float
      Throws:
        `JPLException` - if the Term is a Variable

    - #### atomType

          public java.lang.String atomType()

      Returns:
        the type ("text", "string", "reserved_symbol", "jref" etc.) of an Atom
      Throws:
        `JPLException` - if the Term is not an Atom

    - #### bigValue

          public java.math.BigInteger bigValue()

      the value (as a java.math.BigInteger) of an Integer, whether or not it is big
      Returns:
        the value (as a java.math.BigInteger) of an Integer, whether or not it is big
      Throws:
        `JPLException` - if the Term is not an Integer

    - #### doubleValue

          public double doubleValue()

      the value (as a double) of an Integer or Float
      Returns:
        the value (as a double) of an Integer or Float
      Throws:
        `JPLException` - if the Term is neither an Integer nor a Float

    - #### floatValue

          public float floatValue()

      the value (as a float) of an Integer or Float
      Returns:
        the value (as a float) of an Integer or Float
      Throws:
        `JPLException` - if the Term is neither an Integer nor a Float

    - #### hasFunctor

          public boolean hasFunctor(java.lang.String name,
                                    int arity)

      Whether this Term's functor has 'name' and 'arity' (c.f. behaviour of SWI Prolog's functor/3)
      Parameters:
        `name` - a possible name for the functor of a term
        `arity` - an arity 0+
      Returns:
        whether this Term's functor has 'name' and 'arity'
      Throws:
        `JPLException` - if this Term is a Variable

    - #### hasFunctor

          public boolean hasFunctor(long name,
                                    int arity)

      Tests whether this Term's functor has 'name' and 'arity'

      For Float and Integer, mimics behaviour of SWI Prolog's functor/3

      Parameters:
        `name` - a possible name for the functor of a term
        `arity` - an arity 0+
      Returns:
        whether this Term's functor has 'name' and 'arity'
      Throws:
        `JPLException` - if this Term is a Variable

    - #### hasFunctor

          public boolean hasFunctor(java.math.BigInteger name,
                                    int arity)

      Tests whether this Term's functor has 'name' and 'arity'

      For Float and Integer, mimics behaviour of SWI Prolog's functor/3

      Parameters:
        `name` - a possible name for the functor of a term
        `arity` - an arity 0+
      Returns:
        whether this Term's functor has 'name' and 'arity'
      Throws:
        `JPLException` - if this Term is a Variable

    - #### hasFunctor

          public boolean hasFunctor(double name,
                                    int arity)

      Tests whether this Term's functor has 'name' and 'arity'

      For Float and Integer, mimics behaviour of SWI Prolog's functor/3

      Parameters:
        `name` - a possible name for the functor of a term
        `arity` - an arity 0+
      Returns:
        whether this Term's functor has 'name' and 'arity'
      Throws:
        `JPLException` - if this Term is a Variable

    - #### intValue

          public int intValue()

      returns the value (as an int) of an Integer or Float
      Returns:
        the value (as an int) of an Integer or Float
      Throws:
        `JPLException` - if this Term is a Compound, Atom or Variable

    - #### isAtom

          public final boolean isAtom()

      whether this Term is an Atom (of any type)
      Returns:
        whether this Term is an Atom (of any type)

    - #### isBig

          public boolean isBig()

      Tests whether this Integer's value is too big to represent as a long.

      Use this in contexts where the Term is known to be an Integer.

      Returns:
        whether this Integer's value is too big to represent as a long
      Throws:
        `JPLException` - if Term is not an org.jpl7.Integer
      See Also:
        `isBigInteger()`

    - #### isBigInteger

          public boolean isBigInteger()

      Tests whether this Term is an Integer whose value is too big to represent as a long
      Returns:
        whether this Term is an Integer whose value is too big to represent as a long
      See Also:
        `isBig()`

    - #### isCompound

          public final boolean isCompound()

      Tests whether this Term is a Compound.
      Returns:
        whether this Term is a Compound.

    - #### isFloat

          public final boolean isFloat()

      Tests whether this Term is an org.jpl7.Float.
      Returns:
        whether this Term is an org.jpl7.Float.

    - #### isInteger

          public final boolean isInteger()

      Tests whether this Term is an org.jpl7.Integer.
      Returns:
        whether this Term is an org.jpl7.Integer.

    - #### isJFalse

          public boolean isJFalse()

      Tests whether this Term is a 'jfalse' structure, i.e. @(false).
      Returns:
        whether this Term is a 'jfalse' structure, i.e. @(false).

    - #### isJNull

          public boolean isJNull()

      Tests whether this Term is a 'jnull' structure, i.e. @(null).
      Returns:
        whether this Term is a 'jnull' structure, i.e. @(null).

    - #### isJRef

          public final boolean isJRef()

      Tests whether this Term is a (non-null, non-String) JPL reference to a Java object, e.g. <jref>(0x1234560)
      Returns:
        whether this Term is a (non-null, non-String) reference to a Java object, e.g. <jref>(0x1234560)
      See Also:
        `JRef.object()`

    - #### isJTrue

          public boolean isJTrue()

      Tests whether this Term is a 'jtrue' structure, i.e. @(true).
      Returns:
        whether this Term is a 'jtrue' structure, i.e. @(true).

    - #### isJVoid

          public boolean isJVoid()

      Tests whether this Term is a 'jvoid' structure, i.e. @(void).
      Returns:
        whether this Term is a 'jvoid' structure, i.e. @(void).

    - #### isListNil

          public boolean isListNil()

      Tests whether this Term denotes an empty list within the current syntax ("traditional" or "modern").
      Returns:
        whether this Term denotes an empty list within the current syntax ("traditional" or "modern").
      See Also:
        `JPL.getSyntax()`

    - #### isListPair

          public boolean isListPair()

      Tests whether this Term is a list pair within the current syntax ("traditional" or "modern").
      Returns:
        whether this Term is a list pair within the current syntax ("traditional" or "modern").

    - #### isVariable

          public final boolean isVariable()

      Tests whether this Term is a Variable.
      Returns:
        whether this Term is a Variable.

    - #### jrefToObject

          public java.lang.Object jrefToObject()

      Deprecated. Use `JRef.object()`
      Returns:
        the Object which this JRef references

    - #### listLength

          public final int listLength()

      Deprecated. Use `Util.listToLength(Term)`
      The length of this list, iff it is one, else an exception is thrown.
      Returns:
        the length (as an int) of this list, iff it is one.
      Throws:
        `JPLException`

    - #### longValue

          public long longValue()

      The (long) value of a Float or Integer.
      Returns:
        the (long) value of a Float or Integer.
      Throws:
        `JPLException` - if this Term is not a Float or Integer.

    - #### name

          public java.lang.String name()

      The name of an Atom, Compound or Variable.
      Returns:
        the name of an Atom, Compound or Variable.
      Throws:
        `JPLException` - if this Term is not an Atom, Compound or Variable.

    - #### object

          public java.lang.Object object()

      The (non-null, non-String) Object which this org.jpl7.JRef refers to, iff this Term is a JRef.
      Returns:
        the (non-null, non-String) Object which this Term refers to, iff this Term is a JRef.
      Throws:
        `JPLException` - if this Term is not a JRef.

    - #### objectToJRef

          public static final Term objectToJRef(java.lang.Object object)

      Deprecated. Use `JPL.newJRef(java.lang.Object)`
      Returns:
        a new JRef which references object, or @(null) if object == null.
      Throws:
        `JPLException` - if object is a String.

    - #### putParams

          public Term putParams(Term[] ps)

      This internal method is public because it needs to be callable via JNI, but it is not part of JPL's public API and should not be used by applications.
      Parameters:
        `ps` -
      Returns:
      Throws:
        `JPLException` - if there are more actual than formal parameters.

    - #### putTerm

          public static void putTerm(java.lang.Object obj,
                                     term_t termref)

    - #### ref

          public java.lang.Object ref()

      Deprecated. Use `JRef.object()`
      The (non-null, non-String) object which this org.jpl7.JRef references.
      Returns:
        the (non-null, non-String) object which this org.jpl7.JRef references.
      Throws:
        `JPLException` - if this Term is not a JRef

    - #### toTermArray

          public final Term[] toTermArray()

      returns an array of Terms whose elements are the respective members of this list, iff it is a list.
      Returns:
        an array of Terms whose elements are the respective members of this list, iff it is a list.
      Throws:
        `JPLException` - if this Term is not a proper list.

    - #### toString

          public static java.lang.String toString(Term[] args)

      Converts a list of Terms to a String.
      Parameters:
        `args` - An array of Terms to convert
      Returns:
        String representation of a list of Terms

    - #### type

          public abstract int type()

      returns the type of this term, as one of org.jpl7.fli.Prolog.COMPOUND, .ATOM, .VARIABLE, .INTEGER, .FLOAT etc
      Returns:
        the type of this term, as one of org.jpl7.fli.Prolog.COMPOUND, .ATOM, .VARIABLE, .INTEGER, .FLOAT etc

    - #### typeName

          public abstract java.lang.String typeName()

      returns the name of the type of this term, as one of "Compound", "Atom", "Variable", "Integer", "Float" or "JRef"
      Returns:
        the name of the type of this term, as one of "Compound", "Atom", "Variable", "Integer", "Float" or "JRef"