Term.java

Go to the documentation of this file.

//tabstop=4
//*****************************************************************************/
// Project: jpl
//
// File:    $Id$
// Date:    $Date$
// Author:  Fred Dushin <fadushin@syr.edu>
//          
//
// Description:
//    
//
// -------------------------------------------------------------------------
// Copyright (c) 2004 Paul Singleton
// Copyright (c) 1998 Fred Dushin
//                    All rights reserved.
// 
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Library Public License
// as published by the Free Software Foundation; either version 2
// of the License, or (at your option) any later version.
// 
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Library Public License for more details.
//*****************************************************************************/
package jpl;

import java.util.Hashtable;
import java.util.Iterator;
import java.util.Map;
import jpl.fli.DoubleHolder;
import jpl.fli.Int64Holder;
import jpl.fli.IntHolder;
import jpl.fli.Prolog;
import jpl.fli.StringHolder;
import jpl.fli.term_t;

//----------------------------------------------------------------------/
// Term
public abstract class Term {
        //==================================================================/
        //  Attributes
        //==================================================================/

        //==================================================================/
        //  Constructors
        //==================================================================/

        protected Term() {
        }

        //==================================================================/
        //  Methods (abstract, common)
        //==================================================================/

        public abstract Term arg(int ano);

        public abstract Term[] args();

        public abstract boolean hasFunctor(String name, int arity);

        public abstract boolean hasFunctor(int value, int arity);
        public abstract boolean hasFunctor(double value, int arity);

        public String name() {
                throw new JPLException("jpl." + this.typeName() + ".name() is undefined");
        };

        public int arity() {
                throw new JPLException("jpl." + this.typeName() + ".arity() is undefined");
        };

        public int intValue() {
                throw new JPLException("jpl." + this.typeName() + ".intValue() is undefined");
        }
        public long longValue() {
                throw new JPLException("jpl." + this.typeName() + ".longValue() is undefined");
        }
        public float floatValue() {
                throw new JPLException("jpl." + this.typeName() + ".floatValue() is undefined");
        }

        public double doubleValue() {
                throw new JPLException("jpl." + this.typeName() + ".doubleValue() is undefined");
        }

        //==================================================================/
        //  Methods (common)
        //==================================================================/

        public abstract int type();

        public abstract String typeName();

        public boolean isAtom() {
                return this instanceof Atom;
        }

        public boolean isCompound() {
                return this instanceof Compound;
        }

        public boolean isFloat() {
                return this instanceof Float;
        }

        public boolean isInteger() {
                return this instanceof Integer;
        }

        public boolean isVariable() {
                return this instanceof Variable;
        }

        public boolean isJFalse() {
                return false; // overridden in Compound, where it might sometimes be true
        }

        public boolean isJTrue() {
                return false; // overridden in Compound, where it might sometimes be true
        }

        public boolean isJNull() {
                return false; // overridden in Compound, where it might sometimes be true
        }

        public boolean isJVoid() {
                return false; // overridden in Compound, where it might sometimes be true
        }

        public boolean isJObject() {
                return false; // overridden in Compound, where it might sometimes be true
        }

        public boolean isJRef() {
                return false; // overridden in Compound, where it might sometimes be true
        }

        public abstract Object jrefToObject();

        // objectToJRef(Object)
        public static Term objectToJRef(Object obj) {
                return new Compound( "@", new Term[]{new Atom(Prolog.object_to_tag(obj))});
        }

        public Term putParams(Term[] ps) {
                IntHolder next = new IntHolder();
                next.value = 0;
                Term t2 = this.putParams1(next, ps);
                if (next.value != ps.length) {
                        throw new JPLException("Term.putParams: more actual params than formal");
                }
                return t2;
        }

        public Term putParams(Term plist) {
                Term[] ps = plist.toTermArray();
                return putParams(ps);
        }

        protected Term putParams1(IntHolder next, Term[] ps) {
                switch (this.type()) {
                        case Prolog.COMPOUND :
                                return new Compound(this.name(), putParams2(this.args(), next, ps));
                        case Prolog.ATOM :
                                if (this.name().equals("?")) {
                                        if (next.value >= ps.length) {
                                                throw new JPLException("Term.putParams: fewer actual params than formal params");
                                        }
                                        return ps[next.value++];
                                } // else drop through to default
                        default :
                                return this;
                }
        }

        static protected Term[] putParams2(Term[] ts, IntHolder next, Term[] ps) {
                int n = ts.length;
                Term[] ts2 = new Term[n];
                for (int i = 0; i < n; i++) {
                        ts2[i] = ts[i].putParams1(next, ps);
                }
                return ts2;
        }

        public int listLength() {
                if (this.hasFunctor(".", 2)) {
                        return 1 + this.arg(2).listLength();
                } else if (this.hasFunctor("[]", 0)) {
                        return 0;
                } else {
                        throw new JPLException("Term.listLength: term is not a list");
                }
        }

        public Term[] toTermArray() {
                try {
                        int len = this.listLength();
                        Term[] ts = new Term[len];
                        Term t = this;

                        for (int i = 0; i < len; i++) {
                                ts[i] = t.arg(1);
                                t = t.arg(2);
                        }
                        return ts;
                } catch (JPLException e) {
                        throw new JPLException("Term.toTermArray: term is not a proper list");
                }
        }

        //==================================================================/
        //  Methods (deprecated)
        //==================================================================/

        public abstract String debugString();

        public static String debugString(Term arg[]) {
                String s = "[";

                for (int i = 0; i < arg.length; ++i) {
                        s += arg[i].debugString();
                        if (i != arg.length - 1) {
                                s += ", ";
                        }
                }
                return s + "]";
        }

        //==================================================================/
        //  Converting JPL Terms to Prolog terms
        // 
        // To convert a Term to a term_t, we need to traverse the Term
        // structure and build a corresponding Prolog term_t object.
        // There are some issues:
        // 
        // - Prolog term_ts rely on the *consecutive* nature of term_t
        //   references.  In particular, to build a compound structure
        //   in the Prolog FLI, one must *first* determine the arity of the
        //   compound, create a *sequence* of term_t references, and then
        //   put atoms, functors, etc. into those term references.  We
        //   do this in these methods by first determining the arity of the
        //   Compound, and then by "put"-ing a type into a term_t.
        //   The "put" method is implemented differently in each of Term's
        //   five subclasses.
        // 
        // - What if we are trying to make a term_t from a Term, but the
        //   Term has multiple instances of the same Variable?  We want
        //   to ensure that _one_ Prolog variable will be created, or else
        //   queries will give incorrect answers.  We thus pass a Hashtable
        //   (var_table) through these methods.  The table contains term_t 
        //   instances, keyed on Variable instances.
        //==================================================================/

        public void put( term_t term){
                put( new Hashtable(), term);
        }
        protected abstract void put(Map varnames_to_vars, term_t term);

        protected static term_t putTerms(Map varnames_to_vars, Term[] args) {

                // first create a sequence of term_ts.  The 0th term_t
                // will be a jpl.fli.term_t.  Successive Prolog term_t 
                // references will reside in the Prolog engine, and
                // can be obtained by term0.value+i.
                // 
                term_t term0 = Prolog.new_term_refs(args.length);

                // for each new term reference, construct a Prolog term
                // by putting an appropriate Prolog type into the reference.
                // 
                long ith_term_t = term0.value;
                for (int i = 0; i < args.length; ++i, ++ith_term_t) {
                        term_t term = new term_t();
                        term.value = ith_term_t;
                        args[i].put(varnames_to_vars, term); // each subclass defines its own put()
                }

                return term0;
        }

        // experiment: for jni_jobject_to_term_byval/2 in jpl.c
        public static void putTerm( Object obj, term_t termref){
                if (obj instanceof Term){
                        ((Term)obj).put(termref);
                } else {
                        throw new JPLException("not a Term");
                }
        }

        //==================================================================/
        //  Converting Prolog terms to JPL Terms
        // 
        // Converting back from term_ts to Terms is simple, since
        // the (simplified) Term representation is canonical (there is only one
        // correct structure for any given Prolog term).
        // 
        // One problem concerns variable bindings.  We illustrate
        // with several examples.  First, consider the Prolog fact
        // 
        //     p( f(X,X)).
        // 
        // And the query
        //
        //     ?- p( Y).
        //
        // A solution should be
        //
        //     y = f(X,X) 
        //
        // and indeed, if this query is run, the term_t to which Y will
        // be unified is a compound, f(X,X).  The problem is, how do
        // we know, in converting the term_ts to Terms in the compound f/2
        // whether we should create one Variable or two?  This begs the
        // question, how do we _identify_ Variables in JPL?  The answer
        // to the latter question is, by reference; two Variable (Java) 
        // references refer to the same variable iff they are, in memory,
        // the same Variable object.  That is, they satisfy the Java == relation.
        // (Note that this condition is _not_ true of the other Term types.)
        // 
        // Given this design decision, therefore, we should create a
        // single Variable instance and a Compound instance whose two arg
        // values refer to the same Variable object.  We therefore need to keep
        // track, in converting a term_t to a Term (in particular, in
        // converting a term_t whose type is variable to a Variable), of
        // which Variables have been created.  We do this by using the vars
        // Hashtable, which gets passed recursively though the from_term_t
        // methods; this table holds the Variable instances that have been
        // created, keyed by the unique and internal-to-Prolog string
        // representation of the variable (I'm not sure about this...).
        //==================================================================/

        /*
        protected static Term[] from_term_ts(Map vars_to_Vars, int n, term_t term0) {
        
                // create an (uninitialised) array of n Term references
                Term[] terms = new Term[n];
        
                // for each term_t (from 0...n-1), create a term_t
                // (temporary) structure and dispatch the translation
                // to a Term to the static from_term_t method of the Term
                // class.  This will perform (Prolog) type analysis on the
                // term_t and call the appropriate static method to create
                // a Term of the right type (e.g., Atom, Variable, List, etc.)
                // 
                long ith_term_t = term0.value;
                for (int i = 0; i < n; ++i, ++ith_term_t) {
                        term_t term = new term_t();
                        term.value = ith_term_t;
        
                        terms[i] = Term.from_term_t(vars_to_Vars, term);
                }
        
                return terms;
        }
        */

        protected static Term getTerm1(Map vars_to_Vars, term_t term) {
                int type = Prolog.term_type(term);

                switch (type) {
                        case Prolog.VARIABLE :
                                return Variable.getTerm(vars_to_Vars, term);
                        case Prolog.ATOM :
                                return Atom.getTerm(vars_to_Vars, term);
                        case Prolog.STRING :
                                return Atom.getString(vars_to_Vars, term);
                        case Prolog.INTEGER :
                                return Integer.getTerm(vars_to_Vars, term);
                        case Prolog.FLOAT :
                                return Float.getTerm(vars_to_Vars, term);
                        case Prolog.COMPOUND :
                                return Compound.getTerm(vars_to_Vars, term);
                        default :
                                // should never happen...
                                throw new JPLException("Term.from_term_t: unknown term type=" + type);
                }
        }

        protected static Term getTerm(Map vars_to_Vars, term_t term) {
                StringHolder hString;
                IntHolder hInt;
                Int64Holder hInt64;
                // int type = Prolog.term_type(term);
                switch (Prolog.term_type(term)) {
                case Prolog.VARIABLE:
                        for (Iterator i = vars_to_Vars.keySet().iterator(); i.hasNext();) {
                                term_t varX = (term_t) i.next(); // a previously seen Prolog variable
                                if (Prolog.compare(varX, term) == 0) { // identical Prolog variables?
                                        return (Term) vars_to_Vars.get(varX); // return the associated JPL Variable
                                }
                        }
                        // otherwise, the Prolog variable in term has not been seen before
                        Variable Var = new Variable(); // allocate a new (sequentially named) Variable to represent it
                        Var.term_ = term; // this should become redundant...
                        vars_to_Vars.put(term, Var); // use Hashtable(var,null), but only need set(var)
                        return Var;
                case Prolog.ATOM: // return Atom.getTerm(vars_to_Vars, term);
                        hString = new StringHolder();
                        Prolog.get_atom_chars(term, hString); // ignore return val; assume success...
                        return new Atom(hString.value);
                case Prolog.STRING: // return Atom.getString(vars_to_Vars, term);
                        hString = new StringHolder();
                        Prolog.get_string_chars(term, hString); // ignore return val; assume success...
                        return new Atom(hString.value);
                case Prolog.INTEGER: // return Integer.getTerm(vars_to_Vars, term);
                        hInt64 = new Int64Holder();
                        Prolog.get_integer(term, hInt64); // assume it succeeds...
                        return new jpl.Integer(hInt64.value);
                case Prolog.FLOAT: // return Float.getTerm(vars_to_Vars, term);
                        DoubleHolder hFloatValue = new DoubleHolder();
                        Prolog.get_float(term, hFloatValue); // assume it succeeds...
                        return new jpl.Float(hFloatValue.value);
                case Prolog.COMPOUND: // return Compound.getTerm(vars_to_Vars, term);
                        hString = new StringHolder();
                        hInt = new IntHolder();
                        Prolog.get_name_arity(term, hString, hInt); // assume it succeeds
                        Term args[] = new Term[hInt.value];
                        // term_t term1 = Prolog.new_term_refs(hArity.value);
                        for (int i = 1; i <= hInt.value; i++) {
                                term_t termi = Prolog.new_term_ref();
                                Prolog.get_arg(i, term, termi);
                                args[i - 1] = Term.getTerm(vars_to_Vars, termi);
                        }
                        return new Compound(hString.value, args);
                default:
                        // should never happen...
                        throw new JPLException("Term.from_term_t: unknown term type=" + Prolog.term_type(term));
                }
        }
        
        protected static Term getTerm( term_t term){
                return getTerm( new Hashtable(), term);
        }

        //==================================================================/
        //  Computing Substitutions
        // 
        // Once a solution has been found, the Prolog term_t references
        // will have been instantiated and will refer to new terms.  To compute
        // a substitution, we traverse the (original) Term structure, looking
        // at the term_t reference in the Term.  The only case we really care
        // about is if the (original) Term is a Variable; if so, the term_t
        // back in the Prolog engine may be instantiated (non Variable parts
        // of the original Term cannot change or become uninstantiated).  In
        // this case, we can store this term in a Hashtable, keyed by the
        // Variable with which the term was unified.
        //==================================================================/

        //------------------------------------------------------------------/
        // getSubst
        protected abstract void getSubst(Map varnames_to_Terms, Map vars_to_Vars);

        //------------------------------------------------------------------/
        // getSubsts
        protected static void getSubsts(Map varnames_to_Terms, Map vars_to_Vars, Term[] args) {
                for (int i = 0; i < args.length; ++i) {
                        args[i].getSubst(varnames_to_Terms, vars_to_Vars);
                }
        }

        //------------------------------------------------------------------/
        // terms_equals
        protected static boolean terms_equals(Term[] t1, Term[] t2) {
                if (t1.length != t2.length) {
                        return false;
                }

                for (int i = 0; i < t1.length; ++i) {
                        if (!t1[i].equals(t2[i])) {
                                return false;
                        }
                }
                return true;
        }

        //------------------------------------------------------------------/
        // toString
        public static String toString(Term[] args) {
                String s = "";

                for (int i = 0; i < args.length; ++i) {
                        s += args[i].toString();
                        if (i != args.length - 1) {
                                s += ", ";
                        }
                }

                return s;
        }

}

//345678901234567890123456789012346578901234567890123456789012345678901234567890

---

jpl
Author(s): Lorenz Moesenlechner
autogenerated on Fri Jan 11 09:40:29 2013