Variable
Date: 2020-06-16

org.jpl7

## Class Variable

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

-     public class Variable
      extends Term

  This class supports Java representations of Prolog variables.

  A jpl.Variable instance is equivalent to a variable in a fragment of Prolog source text: it is *not* a "live" variable within a Prolog stack or heap. A corresponding Prolog variable is created only upon opening a Query whose goal refers to a Variable (and then only temporarily).

  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.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `index`
    `java.lang.String` | `name` the name of this Variable (may be changed as of April 2020)
    `protected term_t` | `term_` defined between Query.open() and Query.get2()

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Variable()` Create a new don't tell Variable with new sequential name of the form "_261".
    `Variable(java.lang.String name)` Create a new Variable with 'name' (which must not be null or ""), and may one day be constrained to comply with traditional Prolog syntax.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Term[]` | `args()` The arguments of this Term.
    `int` | `arity()` returns, as an int, the arity of a Term
    `boolean` | `equals(java.lang.Object o)` A Variable is equal to another if their names are the same Totally lexical textual interpretation of vars, not related to bindings Anonymous var _ is always different (including to itsef)
    `protected void` | `getSubst(java.util.Map<java.lang.String,Term> varnames_to_Terms, java.util.Map<term_t,Variable> vars_to_Vars)` This can be used to get the **current** solution binding of the Variable instance.
    `boolean` | `hasFunctor(java.math.BigInteger value, int arity)` Tests whether this Term's functor has 'name' and 'arity'
    `boolean` | `hasFunctor(double value, int arity)` Tests whether this Term's functor has 'name' and 'arity'
    `boolean` | `hasFunctor(long value, 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` | `hashCode()`
    `java.lang.String` | `name()` the lexical name of this Variable
    `protected void` | `put(java.util.Map<java.lang.String,term_t> varnames_to_vars, term_t term)` To put a Variable, we must check whether a (non-anonymous) variable with the same name has already been put in the Term.
    `void` | `setName(java.lang.String name)`
    `java.lang.String` | `toString()` Returns a Prolog source text representation of this Variable
    `int` | `type()` returns the type of this subclass of Term, i.e.
    `java.lang.String` | `typeName()` returns the typeName of this subclass of Term, i.e.

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

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

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

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

- - ### Field Detail

    - #### index

          protected transient int index

    - #### name

          public java.lang.String name

      the name of this Variable (may be changed as of April 2020)

    - #### term_

          protected transient term_t term_

      defined between Query.open() and Query.get2()

  - ### Constructor Detail

    - #### Variable

          public Variable()

      Create a new don't tell Variable with new sequential name of the form "_261".

    - #### Variable

          public Variable(java.lang.String name)

      Create a new Variable with 'name' (which must not be null or ""), and may one day be constrained to comply with traditional Prolog syntax.
      Parameters:
        `name` - the source name of this Variable

  - ### Method Detail

    - #### args

          public final Term[] args()

      Description copied from class: `Term`
      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

      Overrides:
        `args` in class `Term`
      Returns:
        the arguments of a Compound

    - #### arity

          public int arity()

      returns, as an int, the arity of a Term
      Overrides:
        `arity` in class `Term`
      Returns:
        the arity of a Term

    - #### equals

          public boolean equals(java.lang.Object o)

      A Variable is equal to another if their names are the same Totally lexical textual interpretation of vars, not related to bindings Anonymous var _ is always different (including to itsef)
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `o` - The Object to compare.
      Returns:
        true if the Object is a Variable and the above condition apply.

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

      This can be used to get the **current** solution binding of the Variable instance. So we are calling when the goal is in a solution This method returns nothing but modifies the argument mappings, by filling them with the current solution binding of the Variable instance. If Variable instance is anonymous or a dont-tell-me variable, then do nothing Otherwise, if the Variable instance is not already in the varnames_to_Terms Map, put the result of converting the term_t to which this variable has been unified (in the current solution) to a Term in the Map, keyed on this Variable's name. In binding the Variable instance to the Term (in the current solution), such Term may also refer to free variables, whose maps are stores in vars_to_Vars
      Overrides:
        `getSubst` in class `Term`
      Parameters:
        `varnames_to_Terms` - A Map of bindings from variable names to JPL Terms.
        `vars_to_Vars` - A Map from Prolog variables to JPL Variables.

    - #### hasFunctor

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

      Description copied from class: `Term`
      Tests whether this Term's functor has 'name' and 'arity'

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

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

    - #### hasFunctor

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

      Description copied from class: `Term`
      Whether this Term's functor has 'name' and 'arity' (c.f. behaviour of SWI Prolog's functor/3)
      Overrides:
        `hasFunctor` in class `Term`
      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'

    - #### hasFunctor

          public boolean hasFunctor(long value,
                                    int arity)

      Description copied from class: `Term`
      Tests whether this Term's functor has 'name' and 'arity'

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

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

    - #### hasFunctor

          public boolean hasFunctor(double value,
                                    int arity)

      Description copied from class: `Term`
      Tests whether this Term's functor has 'name' and 'arity'

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

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

    - #### name

          public final java.lang.String name()

      the lexical name of this Variable
      Overrides:
        `name` in class `Term`
      Returns:
        the lexical name of this Variable

    - #### setName

          public void setName(java.lang.String name)

      Overrides:
        `setName` in class `Term`

    - #### put

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

      To put a Variable, we must check whether a (non-anonymous) variable with the same name has already been put in the Term. If one has, then the corresponding Prolog variable has been stashed in the varnames_to_vars Map, keyed by the Variable name, so we can look it up and reuse it (this way, the sharing of variables in the Prolog term reflects the sharing of Variable names in the Term. Otherwise, if this Variable name has not already been seen in the Term, then we put a new Prolog variable and add it into the Map (keyed by this Variable name).
      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 (new or reused) Prolog variable.

    - #### toString

          public java.lang.String toString()

      Returns a Prolog source text representation of this Variable
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a Prolog source text representation of this Variable

    - #### type

          public final int type()

      returns the type of this subclass of Term, i.e. Prolog.VARIABLE
      Specified by:
        `type` in class `Term`
      Returns:
        the type of this subclass of Term, i.e. Prolog.VARIABLE

    - #### typeName

          public java.lang.String typeName()

      returns the typeName of this subclass of Term, i.e. "Variable"
      Specified by:
        `typeName` in class `Term`
      Returns:
        the typeName of this subclass of Term, i.e. "Variable"