yap-6.3/LGPL/JPL/java/jpl/Term.java

//tabstop=4
//*****************************************************************************/
// Project: jpl
//
// File:    $Id: Term.java,v 1.1 2004-08-27 20:27:56 vsc Exp $
// Date:    $Date: 2004-08-27 20:27:56 $
// 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.Map;

import jpl.fli.IntHolder;
import jpl.fli.Prolog;
import jpl.fli.term_t;

//----------------------------------------------------------------------/
// Term
/**
 * 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.
 * 
 * <hr><i>
 * Copyright (C) 2004  Paul Singleton<p>
 * Copyright (C) 1998  Fred Dushin<p>
 * 
 * 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.<p>
 * 
 * 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.<p>
 * </i><hr>
 * @author  Fred Dushin <fadushin@syr.edu>
 * @version $Revision: 1.1 $
 */
public abstract class Term {
	//==================================================================/
	//  Attributes
	//==================================================================/

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

	/**
	 * This default constructor is provided in order for subclasses
	 * to be able to define their own default constructors.
	 */
	protected Term() {
	}

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

	/**
	 * returns the ano-th (1+) argument of a (Compound) Term
	 * throws a JPLException for any other subclass
	 * 
	 * @return the ano-th argument of a (Compound) Term
	 */
	public Term arg(int ano) {
		throw new JPLException("jpl." + this.typeName() + ".arg() is undefined");
	};

	/**
	 * Tests whether this Term's functor has (String) 'name' and 'arity'
	 * Returns false if called inappropriately
	 * 
	 * @return whether this Term's functor has (String) 'name' and 'arity'
	 */
	public boolean hasFunctor(String name, int arity) {
		return false;
	}

	/**
	 * Tests whether this Term's functor has (int) 'name' and 'arity'
	 * Returns false if called inappropriately
	 * 
	 * @return whether this Term's functor has (int) 'name' and 'arity'
	 */
	public boolean hasFunctor(int value, int arity) {
		return false;
	}

	/**
	 * Tests whether this Term's functor has (double) 'name' and 'arity'
	 * Returns false if called inappropriately
	 * 
	 * @return whether this Term's functor has (double) 'name' and 'arity'
	 */
	public boolean hasFunctor(double value, int arity) {
		return false;
	}

	/**
	 * returns, as a String, the name of a Compound, Atom or Variable
	 * throws a JPLException from an Integer or Float
	 * 
	 * @return the name of a Compound, Atom or Variable
	 */
	public String name() {
		throw new JPLException("jpl." + this.typeName() + ".name() is undefined");
	};

	/**
	 * returns, as an int, the arity of a Compound, Atom, Integer or Float
	 * throws a JPLException from a Variable
	 * 
	 * @return the arity of a Compound, Atom, Integer or Float
	 */
	public int arity() {
		throw new JPLException("jpl." + this.typeName() + ".arity() is undefined");
	};

	/**
	 * returns the value (as an int) of an Integer or Float
	 * throws a JPLException from a Compound, Atom or Variable
	 * 
	 * @return the value (as an int) of an Integer or Float
	 */
	public int intValue() {
		throw new JPLException("jpl." + this.typeName() + ".intValue() is undefined");
	}
	/**
	 * returns the value (as a long) of an Integer or Float
	 * throws a JPLException from a Compound, Atom or Variable
	 * 
	 * @return the value (as a long) of an Integer or Float
	 */
	public long longValue() {
		throw new JPLException("jpl." + this.typeName() + ".longValue() is undefined");
	}
	/**
	 * returns the value (as a float) of an Integer or Float
	 * throws a JPLException from a Compound, Atom or Variable
	 * 
	 * @return the value (as a float) of an Integer or Float
	 */
	public float floatValue() {
		throw new JPLException("jpl." + this.typeName() + ".floatValue() is undefined");
	}

	/**
	 * returns the value (as a double) of an Integer or Float
	 * throws a JPLException from any other subclass
	 * 
	 * @return the value (as an double) of an Integer or Float
	 */
	public double doubleValue() {
		throw new JPLException("jpl." + this.typeName() + ".doubleValue() is undefined");
	}

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

	/**
	 * returns the type of this term, as one of jpl.fli.Prolog.COMPOUND, .ATOM, .VARIABLE, .INTEGER, .FLOAT etc
	 * 
	 * @return the type of this term, as one of jpl.fli.Prolog.COMPOUND, .ATOM, .VARIABLE, .INTEGER, .FLOAT etc
	 */
	public abstract int type();

	/**
	 * returns the name of the type of this term, as one of "Compound", "Atom", "Variable", "Integer", "Float" etc
	 * 
	 * @return the name of the type of this term, as one of "Compound", "Atom", "Variable", "Integer", "Float" etc
	 */
	public abstract String typeName();

	/**
	 * whether this Term represents an atom
	 * 
	 * @return whether this Term represents an atom
	 */
	public boolean isAtom() {
		return this instanceof Atom;
	}

	/**
	 * whether this Term represents a compound term
	 * 
	 * @return whether this Term represents a compound atom
	 */
	public boolean isCompound() {
		return this instanceof Compound;
	}

	/**
	 * whether this Term represents an atom
	 * 
	 * @return whether this Term represents an atom
	 */
	public boolean isFloat() {
		return this instanceof Float;
	}

	/**
	 * whether this Term represents an atom
	 * 
	 * @return whether this Term represents an atom
	 */
	public boolean isInteger() {
		return this instanceof Integer;
	}

	/**
	 * whether this Term is a JBoolean
	 * 
	 * @return whether this Term is a JBoolean
	 */
	public boolean isJBoolean() {
		return this instanceof JBoolean;
	}

	/**
	 * whether this Term is a JRef
	 * 
	 * @return whether this Term is a JRef
	 */
	public boolean isJRef() {
		return this instanceof JRef;
	}

	/**
	 * whether this Term is a JVoid
	 * 
	 * @return whether this Term is a JVoid
	 */
	public boolean isJVoid() {
		return this instanceof JVoid;
	}

	/**
	 * whether this Term is a variable
	 * 
	 * @return whether this Term is a variable
	 */
	public boolean isVariable() {
		return this instanceof Variable;
	}

	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;
	}

	/**
	 * the length of this list, iff it is one, else an exception is thrown
	 * 
	 * @throws JPLException
	 * @return the length (as an int) of this list, iff it is one
	 */
	public int listLength() {
		int len = 0;

		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");
		}
	}

	/** returns an array of terms which are the successive members of this list, if it is a list, else throws an exception
	 * 
	 * @throws JPLException
	 * @return an array of terms which are the successive members of this list, if it is 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)
	//==================================================================/

	/**
	 * returns, as a Term[], the arguments of a Compound
	 * returns an empty Term[] from an Atom, Integer or Float
	 * throws a JPLException from a Variable 
	 * 
	 * @return the arguments of a Compound as a Term[
	 * @deprecated
	 */
	public abstract Term[] args();

	/**
	 * Returns a debug-friendly representation of a Term
	 * 
	 * @return  a debug-friendly representation of a Term
	 * @deprecated
	 */
	public abstract String debugString();

	/**
	 * Returns a debug-friendly representation of a list of Terms
	 * 
	 * @return  a debug-friendly representation of a list of Terms
	 * @deprecated
	 */
	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.
	//==================================================================/

	/**
	 * Cache the reference to the Prolog term_t here.
	 * 
	 * @param   varnames_to_vars  A Map from variable names to JPL Variables.
	 * @param   term              A (previously created) term_t which is to be
	 *                            put with a Prolog term-type appropriate to the Term type
	 *                            (e.g., Atom, Variable, Compound, etc.) on which the method is
	 *                            invoked.)
	 */
	protected abstract void put(Map varnames_to_vars, term_t term);

	/**
	 * This static method converts an array of Terms to a *consecutive* 
	 * sequence of term_t objects.  Note that the first term_t object
	 * returned is a term_t class (structure); the succeeding term_t
	 * objects are consecutive references obtained by incrementing the
	 * *value* field of the term_t.
	 * 
	 * @param   varnames_to_vars  Map from variable names to JPL Variables.
	 * @param   args              An array of jpl.Term references.
	 * @return                    consecutive term_t references (first of which is
	 *                            a structure)
	 */
	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;
	}

	//==================================================================/
	//  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...).
	//==================================================================/

	/**
	 * This method calls from_term_t on each term in the n consecutive term_ts.
	 * A temporary jpl.term_t "holder" (byref) structure must be created
	 * in order to extract type information from the Prolog engine.
	 * 
	 * @param   vars_to_Vars      A Map from Prolog variables to jpl.Variable instances
	 * @param   n         The number of consecutive term_ts
	 * @param   term0     The 0th term_t (structure); subsequent
	 *                    term_ts are not structures.
	 * @return            An array of converted Terms
	 */
	/*
	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;
	}
	*/

	/**
	 * We discover the Prolog type of the term, then forward the
	 * call to the appropriate subclass
	 * 
	 * @param   vars  A Map from Prolog variables to jpl.Variable instances
	 * @param   term  The Prolog term (in a term_t holder) to convert
	 * @return        The converted Term subtype instance.
	 */
	protected static Term getTerm(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);
		}
	}

	//==================================================================/
	//  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
	/**
	 * This method computes a substitution from a Term.  The bindings
	 * Hashtable stores Terms, keyed by Variables.  Thus, a
	 * substitution is as it is in mathematical logic, a sequence
	 * of the form \sigma = {t_0/x_0, ..., t_n/x_n}.  Once the
	 * substitution is computed, the substitution should satisfy
	 * 
	 *   \sigma T = t
	 * 
	 * where T is the Term from which the substitution is computed,
	 * and t is the term_t which results from the Prolog query.<p>
	 * 
	 * A second Hashtable, vars, is required; this table holds
	 * the Variables that occur (thus far) in the unified term.
	 * The Variable instances in this table are guaranteed to be
	 * unique and are keyed on Strings which are Prolog internal
	 * representations of the variables.
	 * 
	 * @param   bindings  table holding Term substitutions, keyed on
	 * Variables.
	 * @param   vars  A Hashtable holding the Variables that occur
	 * thus far in the term; keyed by internal (Prolog) string rep.
	 */
	protected abstract void getSubst(Map varnames_to_Terms, Map vars_to_Vars);

	//------------------------------------------------------------------/
	// getSubsts
	/**
	 * Just calls computeSubstitution for each Term in the array.
	 * 
	 * @param   varnames_to_Terms  a Map from variable names to Terms
	 * @param   vars_to_Vars       a Map from Prolog variables to JPL Variables
	 * @param   arg                a list of Terms
	 */
	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
	/**
	 * This method is used (by Compound.equals) to determine the Terms in two Term arrays
	 * are pairwise equal, where two Terms are equal if they satisfy
	 * the equals predicate (defined differently in each Term subclass).
	 * 
	 * @param   t1  an array of Terms
	 * @param   t2  another array of Terms
	 * @return  true if all of the Terms in the (same-length) arrays are pairwise equal
	 */
	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
	/**
	 * Converts a list of Terms to a String.
	 * 
	 * @param   args    An array of Terms to convert
	 * @return  String representation of a list of Terms
	 */
	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