Compound
Date: 2020-06-16

org.jpl7

## Class Compound

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

-     public class Compound
      extends Term

  A Compound represents a structured term, comprising a functor and one or more arguments (Terms). Direct instances of Compound must have one or more arguments (it is an error to attempt to construct a Compound with zero args; a JPLException will be thrown). For example, this Java expression yields a representation of the term f(a):

       new Compound("f", new Term[] { new Atom("a") })

  Note the use of the "anonymous array" notation to denote the arguments (an anonymous array of Term).
  Alternatively, construct the Term from Prolog source syntax:

       Term.textToTerm("f(a)")

  The arity of a Compound is the quantity of its arguments. Once constructed, neither the name nor the arity of a Compound can be altered. An argument of a Compound can be replaced with the setArg() method.

  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.

  See Also:
    `Term`, `Atom`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Term[]` | `args` The (zero or more) arguments of this Compound.
    `protected java.lang.String` | `name` The name of (the functor of) this Compound.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `Compound(java.lang.String name)` Creates a Compound with name and no args (which in SWI Prolog V7 is distinct from a text atom of the same name).
    `protected` | `Compound(java.lang.String name, int arity)` Creates a Compound with name and arity.
    `` | `Compound(java.lang.String name, Term[] args)` Creates a Compound with name and (zero or more) args.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Term` | `arg(int i)` Returns the ith argument (counting from 1) of this Compound.
    `Term[]` | `args()` Returns the arguments of this Compound as a Term[0..arity-1] array.
    `int` | `arity()` Returns the arity (0+) of this Compound.
    `boolean` | `equals(java.lang.Object o)` Two Compounds are equal if they are identical (same object) or their names and arities are equal and their respective arguments are equal.
    `protected void` | `getSubst(java.util.Map<java.lang.String,Term> varnames_to_Terms, java.util.Map<term_t,Variable> vars_to_Vars)` Nothing needs to be done except to pass the buck to this Compound's args.
    `boolean` | `hasFunctor(java.lang.String name, int arity)` Tests whether this Compound's functor has (String) 'name' and 'arity'.
    `int` | `hashCode()`
    `boolean` | `isJFalse()` whether this Term is a 'jboolean' structure denoting Java's false, i.e.
    `boolean` | `isJNull()` whether this Term is a 'jnull' structure, i.e.
    `boolean` | `isJTrue()` whether this Term is a 'jboolean' structure denoting Java's true, i.e.
    `boolean` | `isJVoid()` whether this Term is a 'jvoid' structure, i.e.
    `boolean` | `isListPair()` whether this Term denotes (syntax-specifically) a list cell see this does not check the shape of the second argument to check if it is a list So a list pair may not be a list itself and hence isList() will return false as the second argument many not be a list
    `java.lang.String` | `name()` the name (unquoted) of this Compound
    `protected void` | `put(java.util.Map<java.lang.String,term_t> varnames_to_vars, term_t term)` To put a Compound in a term, we create a sequence of term_t references from the Term.terms_to_term_ts() method, and then use the Prolog.cons_functor_v() method to create a Prolog compound term.
    `void` | `setArg(int i, Term arg)` Sets the i-th (from 1) arg of this Compound to the given Term instance.
    `java.lang.String` | `toString()` a prefix functional representation of a Compound of the form name(arg1,...), where 'name' is quoted iff necessary (to be valid Prolog source text) and each argument is represented according to its toString() method.
    `int` | `type()` the type of this term, as jpl.fli.Prolog.COMPOUND
    `java.lang.String` | `typeName()` the name of the type of this term, as "Compound"

    - ### Methods inherited from class org.jpl7.Term

      `atomListToStringArray, atomType, bigValue, doubleValue, floatValue, getSubsts, getTerm, getTerm, hasFunctor, hasFunctor, hasFunctor, intArrayArrayToList, intArrayToList, intValue, isAtom, isAtomOfNameType, isBig, isBigInteger, isCompound, isFloat, isInteger, isJRef, isList, isList, isListNil, isVariable, jrefToObject, listLength, listLength, listToTermArray, listToTermArray, longValue, object, objectToJRef, put, putParams, putParams, putParams1, putParams2, putTerm, putTerms, ref, setName, stringArrayToList, termArrayToList, textParamsToTerm, textToTerm, toString, toTermArray`

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### args

          protected final Term[] args

      The (zero or more) arguments of this Compound.

    - #### name

          protected final java.lang.String name

      The name of (the functor of) this Compound.

  - ### Constructor Detail

    - #### Compound

          public Compound(java.lang.String name)

      Creates a Compound with name and no args (which in SWI Prolog V7 is distinct from a text atom of the same name).
      Parameters:
        `name` - the name of this Compound
      Throws:
        `JPLException` - if name is null

    - #### Compound

          protected Compound(java.lang.String name,
                             int arity)

      Creates a Compound with name and arity. This constructor, along with the setArg method, serves the new, native Prolog-term-to-Java-term routine, and is public only so as to be accessible via JNI: it is not intended for general use.
      Parameters:
        `name` - the name of this Compound
        `arity` - the arity of this Compound
      Throws:
        `JPLException` - if name is null or arity is negative

    - #### Compound

          public Compound(java.lang.String name,
                          Term[] args)

      Creates a Compound with name and (zero or more) args.
      Parameters:
        `name` - the name of this Compound
        `args` - the (zero or more) arguments of this Compound
      Throws:
        `JPLException` - if name is null or args is null

  - ### Method Detail

    - #### arg

          public final Term arg(int i)

      Returns the ith argument (counting from 1) of this Compound.
      Overrides:
        `arg` in class `Term`
      Parameters:
        `i` - the ordinal number of the required arg (1 denotes the first arg etc.)
      Returns:
        the ith argument (counting from 1) of this Compound
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - if i is inappropriate

    - #### args

          public final Term[] args()

      Returns the arguments of this Compound as a Term[0..arity-1] array.
      Overrides:
        `args` in class `Term`
      Returns:
        the arguments of this Compound as a Term[0..arity-1] array.

    - #### arity

          public final int arity()

      Returns the arity (0+) of this Compound.
      Overrides:
        `arity` in class `Term`
      Returns:
        the arity (0+) of this Compound

    - #### equals

          public boolean equals(java.lang.Object o)

      Two Compounds are equal if they are identical (same object) or their names and arities are equal and their respective arguments are equal.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `o` - the Object to compare (not necessarily another Compound)
      Returns:
        true if the Object satisfies the above condition

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### getSubst

          protected final void getSubst(java.util.Map<java.lang.String,Term> varnames_to_Terms,
                                        java.util.Map<term_t,Variable> vars_to_Vars)

      Nothing needs to be done except to pass the buck to this Compound's args.
      Overrides:
        `getSubst` in class `Term`
      Parameters:
        `varnames_to_Terms` - A Map from variable names to JPL Terms
        `vars_to_Vars` - A Map from Prolog variables to JPL Variables

    - #### hasFunctor

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

      Tests whether this Compound's functor has (String) 'name' and 'arity'.
      Overrides:
        `hasFunctor` in class `Term`
      Parameters:
        `name` - a possible name for the functor of a term
        `arity` - an arity 0+
      Returns:
        whether this Compound's functor has (String) 'name' and 'arity'

    - #### isJFalse

          public boolean isJFalse()

      whether this Term is a 'jboolean' structure denoting Java's false, i.e. @(false)
      Overrides:
        `isJFalse` in class `Term`
      Returns:
        whether this Term is a 'jboolean' structure denoting Java's false, i.e. @(false)

    - #### isJNull

          public boolean isJNull()

      whether this Term is a 'jnull' structure, i.e. @(null)
      Overrides:
        `isJNull` in class `Term`
      Returns:
        whether this Term is a 'jnull' structure, i.e. @(null)

    - #### isJTrue

          public boolean isJTrue()

      whether this Term is a 'jboolean' structure denoting Java's true, i.e. @(true)
      Overrides:
        `isJTrue` in class `Term`
      Returns:
        whether this Term is a 'jboolean' structure denoting Java's true, i.e. @(true)

    - #### isJVoid

          public boolean isJVoid()

      whether this Term is a 'jvoid' structure, i.e. @(void)
      Overrides:
        `isJVoid` in class `Term`
      Returns:
        whether this Term is a 'jvoid' structure, i.e. @(void)

    - #### isListPair

          public final boolean isListPair()

      whether this Term denotes (syntax-specifically) a list cell see this does not check the shape of the second argument to check if it is a list So a list pair may not be a list itself and hence isList() will return false as the second argument many not be a list
      Overrides:
        `isListPair` in class `Term`
      Returns:
        whether this Term denotes (syntax-specifically) a list cell

    - #### name

          public final java.lang.String name()

      the name (unquoted) of this Compound
      Overrides:
        `name` in class `Term`
      Returns:
        the name (unquoted) of this Compound

    - #### put

          protected void put(java.util.Map<java.lang.String,term_t> varnames_to_vars,
                             term_t term)

      To put a Compound in a term, we create a sequence of term_t references from the Term.terms_to_term_ts() method, and then use the Prolog.cons_functor_v() method to create a Prolog compound term.
      Specified by:
        `put` in class `Term`
      Parameters:
        `varnames_to_vars` - A Map from variable names to Prolog variables
        `term` - A (previously created) term_t which is to be set to a Prolog term corresponding to the Term subtype (Atom, Variable, Compound, etc.) on which the method is invoked.

    - #### setArg

          public void setArg(int i,
                             Term arg)

      Sets the i-th (from 1) arg of this Compound to the given Term instance. This method, along with the Compound(name,arity) constructor, serves the new, native Prolog-term-to-Java-term routine, and is public only so as to be accessible via JNI: it is not intended for general use.
      Parameters:
        `i` - the index (1+) of the arg to be set
        `arg` - the Term which is to become the i-th (from 1) arg of this Compound

    - #### toString

          public java.lang.String toString()

      a prefix functional representation of a Compound of the form name(arg1,...), where 'name' is quoted iff necessary (to be valid Prolog source text) and each argument is represented according to its toString() method. Lists are represented depending on JPL.LIST_TOSTRING_TEXTUAL
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        string representation of an Compound

    - #### type

          public int type()

      the type of this term, as jpl.fli.Prolog.COMPOUND
      Specified by:
        `type` in class `Term`
      Returns:
        the type of this term, as jpl.fli.Prolog.COMPOUND

    - #### typeName

          public java.lang.String typeName()

      the name of the type of this term, as "Compound"
      Specified by:
        `typeName` in class `Term`
      Returns:
        the name of the type of this term, as "Compound"