moses.controlState
Class Term

java.lang.Object
  |
  +--moses.controlState.Term

public class Term
extends java.lang.Object

The LGI control state is a Prolog-like bag of terms. The Term class is designed to store such a term, and the control state itself is represented through a Term object. The terms have a tree-like structure: a certain term can be composed of other (sub)terms.

A Term object contains:

  1. data structures for representing such tree;
  2. methods for direct access to different components of the tree;
  3. pattern matching methods for retrieving terms from bags of terms.
Classification-wise, a term can be either an atomic term or a non-atomic term. An atomic term can be a string, an integer, or a float value. A non-atomic term can be either a list of terms or a compound term. A compound term consists of a functor (which is of type String) and a number of sub terms.

Structurally, a term object is composed of a type field, a number of value fields, and a vector field. The type field determines how the value fields and vector fields are to be interpreted.

The following types are available:

A number of methods allow for direct manipulation of the above fields. A careless manipulation, however, can lead to the object being in an non-consistent state, and furthermore it renders the object useless. It is the responsibility of the programmer to keep this object consistent, as the consistency constraints are not provided by this API. A typical usage case for the Term object follows:


        Term lt = Term.parse("[role(chair,ceo),department(3),active]");
 
        if(lt.has("role(chair,%B)")) {
        //true if the first role is "chair"; the second role is neutral
        ....
        }
        
 
        UnifyResult dep =  lt.find("department(%N)");
        
        Term dept =  dep.getTerm(); //returns the whole department term
        Term depno =  dep.getTVar("N"); //returns the number of the department
 
        

The example above shows the usage of the high-level API for this object. The low-level API is to be used in application where performance is a concern.


Field Summary
static int CType
          Non-atomic compound type term.
static int FType
          Atomic float type term.
 java.lang.String functor
          This field has double purpose: in the case of SType terms, it holds the value of this term.
 float FValue
          This field maintains the float value of a FType term.
static int IType
          Atomic integer type term.
 int IValue
          This field maintains the integer value of a IType term.
static int LType
          Non-atomic list type term.
static int SType
          Atomic String type term.
 int type
          This field maintains the type of this Term.
 java.util.Vector VValue
          This field maintains the sub terms of this term in the case of CType and LType terms.
 
Constructor Summary
Term(double dvalue)
          Constructor that builds an FType term out of a double value.
Term(float fvalue)
          Constructor that builds an FType term out of a float value.
Term(int ivalue)
          Constructor that builds an IType term out of an int value.
Term(java.lang.String svalue)
          Constructor that builds an SType term out of a String value.
Term(java.lang.String functor, int type)
          Constructor that builds a term object given a functor and its type.
 
Method Summary
 moses.controlState.Term addST(moses.controlState.Term term)
          This method adds a (sub) term to the VValue vector.
 void addSubTerm(moses.controlState.Term term)
          This method adds a (sub) term to the VValue vector.
 void appToStringBuff(java.lang.StringBuffer sbuf)
          Helper method, not intended to be used directly.
 moses.controlState.Term deep_clone()
          Deep cloning method: creates a deep copy of this object and returns it.
 boolean deep_equals(java.lang.Object obj)
          Deep implementation of the equals() method.
 boolean deep_equals1(java.lang.Object obj)
          The same method as deep_equal, except that each operand is transformed to a string then the comparison is made using String.equals() method (see the mishaps pointed out before, though) Performance wise, it seems more than 5 times slower than the previous implementation.
 int fetchInt(java.lang.String functor)
          This method searches in this compound or list term for a term with a functor that equals the argument, and whose only sub term is an integer.
 moses.controlState.UnifyResult find(java.lang.String sterm)
          This method is the same method as findST(Term t) above, overloaded with String argument.
 moses.controlState.UnifyResult find(moses.controlState.Term t)
          This method is the same method as findST(Term t) above, overloaded with a more suggestive name.
It tries to find a sub term of this compound term (CType or LType) that matches (unifies) the argument.
 moses.controlState.UnifyResult findST(moses.controlState.Term t)
          This method tries to find a sub term of this compound term (CType or LType) that matches (unifies) the argument.
 moses.controlState.Term findT(java.lang.String sterm)
          Finds a term or a pattern of a term in a compound term or a list, and returns it.
 moses.controlState.Term findT(moses.controlState.Term t)
          This method is the same as above findT(String sterm), except it is overloaded with a Term type argument.
 moses.controlState.Term get(int index)
          This method retrieves the sub term in VValue vector at position index.
 int getArity()
          This method returns the arity of this compound or list-type term.
static moses.controlState.Term getATerm(java.lang.String afunctor)
          This method creates a atomic Term out of a given string argument.
 float getFloat()
          Getter method, it retrieves the FValue of this term.
 java.lang.String getFunctor()
          Getter method, it retrieves the functor of this term.
 int getInteger()
          Getter method, it retrieves the IValue field of this term.
 moses.controlState.Term getSubTerm(int index)
          This method retrieves the sub term in VValue vector at position index.
static moses.controlState.Term getTerm(java.lang.String sTerm)
          This method parses a string into a term.
 int getType()
          Getter method, it retrieves the type of this term.
 java.util.Vector getVector()
          Getter method, it retrieves the VValue vector in this term.
 boolean has(java.lang.String st)
          This method searches for the pattern argument within this term.
 boolean has(moses.controlState.Term t)
          The same as above, except that it is overloaded with a term type argument.
 boolean incrementable()
          This method verifies that a term is of incrementable form (of compound type, with exactly one sub term, which is of type IType or FType).
static void main(java.lang.String[] args)
           
static moses.controlState.Term parse(java.lang.String sTerm)
          This method is the same as getTerm(String sTerm), overloaded with a friendlier, more suggestive name.
 void setFloat(float fvalue)
          This method sets the FValue field of this object directly.
 void setFunctor(java.lang.String functor)
          This method sets the functor field of this object directly.
 void setInteger(int ivalue)
          This method sets the IValue field of this object directly.
 void setSubTerm(int index, moses.controlState.Term term)
          This method sets (replaces) the component at position index of the VValue field to the term argument.
 java.lang.String toString()
          This method transforms a Term object into its string representation.
 java.lang.String toString1()
          Testing/helper method: it transforms this term into a string representation.
 moses.controlState.UnifyResult unify(moses.controlState.Term t1)
          Method that unifies this term with a given argument.
 boolean unify(moses.controlState.Term t1, java.util.Hashtable symbols)
          Helper method.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

type

public int type
This field maintains the type of this Term. It can have one of the values: SType(0), IType (1), FType (2), LType(3), CType(4).


functor

public java.lang.String functor
This field has double purpose: in the case of SType terms, it holds the value of this term. In the case of CType terms, it holds the functor of the term. It is neutral in all other cases.


IValue

public int IValue
This field maintains the integer value of a IType term. Neutral in all other cases.


FValue

public float FValue
This field maintains the float value of a FType term. Neutral in all other cases.


VValue

public java.util.Vector VValue
This field maintains the sub terms of this term in the case of CType and LType terms. It is neutral in all other cases.


SType

public static final int SType
Atomic String type term.

See Also:
Constant Field Values

IType

public static final int IType
Atomic integer type term.

See Also:
Constant Field Values

FType

public static final int FType
Atomic float type term.

See Also:
Constant Field Values

LType

public static final int LType
Non-atomic list type term.

See Also:
Constant Field Values

CType

public static final int CType
Non-atomic compound type term.

See Also:
Constant Field Values
Constructor Detail

Term

public Term(int ivalue)
Constructor that builds an IType term out of an int value.

Parameters:
ivalue - represents the integer value of this term

Term

public Term(float fvalue)
Constructor that builds an FType term out of a float value.

Parameters:
fvalue - represents the float value of this term

Term

public Term(double dvalue)
Constructor that builds an FType term out of a double value.

Parameters:
dvalue - represents the value (truncated to float) of this term

Term

public Term(java.lang.String svalue)
Constructor that builds an SType term out of a String value.

Parameters:
svalue - represents the String value of this term

Term

public Term(java.lang.String functor,
            int type)
Constructor that builds a term object given a functor and its type.
If the type is SType, the functor argument is saved in the functor field.
If the type is IType, the functor argument is parsed into an integer and saved in the IValue field.
If the type is FType, the functor argument is parsed into a float and saved in the FValue field.
If the type is LType, the functor argument is ignored, and the VValue vector field is initialized.
If the type is CType, the functor argument is saved in the functor field, and the VValue vector field is initialized.

Note that in the last case, the constructor leaves the object in a somehow incomplete state, since a compound term usually (and normally) requires at least one sub term.

Parameters:
functor - represents the value of this term according to the above rules.
type - represents the type of the term.
Method Detail

setFunctor

public void setFunctor(java.lang.String functor)
This method sets the functor field of this object directly.

Parameters:
functor - represents the new value of the functor.

setInteger

public void setInteger(int ivalue)
This method sets the IValue field of this object directly.

Parameters:
ivalue - represents the new value of the IValue field.

setFloat

public void setFloat(float fvalue)
This method sets the FValue field of this object directly.

Parameters:
fvalue - represents the new value of the field.

addSubTerm

public void addSubTerm(moses.controlState.Term term)
This method adds a (sub) term to the VValue vector.

Parameters:
term - represents the term to add as a sub term to VValue.
See Also:
addST(Term term)

addST

public moses.controlState.Term addST(moses.controlState.Term term)
This method adds a (sub) term to the VValue vector. It is equivalent to addSubTerm method.

Parameters:
term - represents the term to add as a sub term to VValue.
See Also:
addSubTerm(Term term)

setSubTerm

public void setSubTerm(int index,
                       moses.controlState.Term term)
This method sets (replaces) the component at position index of the VValue field to the term argument.

Parameters:
index - represents the position in VValue to replace.
term - represents the term to replace in VValue field.

getType

public int getType()
Getter method, it retrieves the type of this term.

Returns:
the type of this term.

getFunctor

public java.lang.String getFunctor()
Getter method, it retrieves the functor of this term.

Returns:
the functor of this term.

getInteger

public int getInteger()
Getter method, it retrieves the IValue field of this term.

Returns:
the IValue of this term.

getFloat

public float getFloat()
Getter method, it retrieves the FValue of this term.

Returns:
the FValue of this term.

getSubTerm

public moses.controlState.Term getSubTerm(int index)
This method retrieves the sub term in VValue vector at position index.

Parameters:
index - represents the position of the sub term to retrieve.
Returns:
the sub term at position index.
See Also:
get(int index)

get

public moses.controlState.Term get(int index)
This method retrieves the sub term in VValue vector at position index. It is equivalent to the getSubTerm method.

Parameters:
index - represents the position of the sub term to retrieve.
Returns:
the sub term at position index.
See Also:
getSubTerm(int index)

getArity

public int getArity()
This method returns the arity of this compound or list-type term.

Returns:
the arity (i.e. the size of the VValue vector) of this term.

getVector

public java.util.Vector getVector()
Getter method, it retrieves the VValue vector in this term.

Returns:
the VValue field of this term.

getATerm

public static moses.controlState.Term getATerm(java.lang.String afunctor)
This method creates a atomic Term out of a given string argument. The method tests whether the string argument stores an integer, a float or a plain string.

Since exception handling is expensive, in order to avoid parsing exceptions, the method is optimized as follows: if the first character is a number, try to parse it to an integer. If the parsing fails, try a parsing to a float. If none of the parsing works or the first character is not a number, store the term as string.

Parameters:
afunctor - represents the value of the atomic term to be parsed.
Returns:
a Term object of the type SType, or IType, orFType.

toString1

public java.lang.String toString1()
Testing/helper method: it transforms this term into a string representation. The type of each (sub)term is under written beside its value. It helps to observe the structure of terms.

Returns:
the String representation of this term, with annotations for debugging.

appToStringBuff

public void appToStringBuff(java.lang.StringBuffer sbuf)
Helper method, not intended to be used directly. In future releases it will become private member. It transforms this term into a string buffer representation, and it appends it to the String buffer argument. It is intended to be used within the toString method for optimal efficiently.

Parameters:
sbuf - represents the StringBuffer destination where to append this term.

toString

public java.lang.String toString()
This method transforms a Term object into its string representation. The representation emulates the Prolog type representation of terms: The inverse of this function is the parse method that creates a term object out of a String.

Overrides:
toString in class java.lang.Object
Returns:
the string representation of this term.
See Also:
parse(String sTerm)

deep_equals

public boolean deep_equals(java.lang.Object obj)
Deep implementation of the equals() method. It returns true if the argument is of type Term and it has the same value as the this object. The method proceed as follows:
First, the Terms should have the same type.
If true and the type is integer or float, the "==" operator is applied.
If String type, the equals method is used.
If List or Compound, the arity is compared and the method is applied recursively for each of the sub terms.
Note: that two terms may not be deep_equal even when the toString methods return the same string. This is due to the fact that an integer (or a float) can be saved as a String in an SType term.

Parameters:
obj - represents a Term type object that is to be compared to this term.
Returns:
true if the objects are deeep_equal, according to the above procedure; false otherwise.

deep_equals1

public boolean deep_equals1(java.lang.Object obj)
The same method as deep_equal, except that each operand is transformed to a string then the comparison is made using String.equals() method (see the mishaps pointed out before, though) Performance wise, it seems more than 5 times slower than the previous implementation.

When a term is to be compared to a String, the deep_equals methods are to be avoided. Instead, it is more efficient to transform the term into a string and then compare the strings, rather than parse the string into a term then deep compare the terms. Parse methods are way slower than toString methods.

Parameters:
obj - represents a Term type object that is to be compared to this term.
Returns:
true if the objects are deeep_equal, according to the above procedure; false otherwise.
See Also:
deep_equals(Object obj)

deep_clone

public moses.controlState.Term deep_clone()
Deep cloning method: creates a deep copy of this object and returns it. Recursively, a new cloning is applied at each level of a compound term. For atomic terms, new Terms are created with the same values as this term.

Returns:
a new term with the same values as the original.

unify

public moses.controlState.UnifyResult unify(moses.controlState.Term t1)
Method that unifies this term with a given argument. This term is assumed to be a properly formed, final term (with no variables), whereas the argument may possess variables whose values will be unified with the corresponding values of this term.

Example:
t1(t2(3),t4) will unify with t1(%A,%B) and the bindings will be %A is t2(3) and %B is t4. The variables will be denominated by % symbol followed by the variable name (case insensitive), where "%" symbol is defined in UnifyResult class. If this term contains VAR("%") variables, then they will be treated as legitimate symbols from the term, and no binding attempt will be made against them. The method is robust with respect to argument t1 (the method verifies whether the argument is null).

Parameters:
t1 - represents a pattern to match this term against. This pattern is a term that has so-called variables instead of sub terms. The variables are denominated by a '%' symbol preceding the name of the variable.
Returns:
null in the case the unification has failed, and it returns a UnifyResult object if it has succeeded.

unify

public boolean unify(moses.controlState.Term t1,
                     java.util.Hashtable symbols)
Helper method. This method is used by the unify(Term t1) method, and it will become private in the future releases.

The recursive unification function. It takes as argument the term against whom this term is compared with, and a hashtable with symbols already bound to proper terms.
If the argument is a string-type argument and it is a VAR("%") symbol, the binding is saved in the hashtable argument (unless a binding for that symbol already existed and it is not a match - in which case the method nicely fails ).
Otherwise, if the term is an atomic term (string int float), a deep comparison is attempted against this term.
If the argument is a compound type (Ctype or list), a matching of the functor is attempted and after that, this method is called recursively on each of the sub terms of this term, with the args each of the sub terms of the arg term and the same hashtable.

Parameters:
t1 - the term containing the pattern to compare against.
symbols - represents a hashtable containing variable to value bindings that have been matched so far.
Returns:
true if the matching has been successful; false otherwise.
See Also:
unify(Term t1)

findST

public moses.controlState.UnifyResult findST(moses.controlState.Term t)
This method tries to find a sub term of this compound term (CType or LType) that matches (unifies) the argument. The method calls the above unification method for each of the sub terms of this term. It returns null if this is an atomic term (SType, IType, FType) or no unification has been found for a (CType or LType) term and a valid UnifyResult object otherwise.

Parameters:
t - represents the term containing the pattern to be searched inside this term.
Returns:
a valid UnifyResult object if the matching has been successful; null if this is an atomic term (SType, IType, FType) or no unification has been found for a (CType or LType) term.

find

public moses.controlState.UnifyResult find(java.lang.String sterm)
This method is the same method as findST(Term t) above, overloaded with String argument. It first parses the argument into a pattern term, then performs as above.

Parameters:
sterm - represents the string containing the pattern to be searched inside this term.
Returns:
a valid UnifyResult object if the matching has been successful; null if the string does not parse into a term or it parses into an atomic term (SType, IType, FType) or no unification has been found for a (CType or LType) term.
See Also:
findST(Term t)

find

public moses.controlState.UnifyResult find(moses.controlState.Term t)
This method is the same method as findST(Term t) above, overloaded with a more suggestive name.
It tries to find a sub term of this compound term (CType or LType) that matches (unifies) the argument. The method calls the unification method for each of the sub terms of this term. It returns null if this is an atomic term (SType, IType, FType) or no unification has been found for a (CType or LType) term and a valid UnifyResult object otherwise.

Parameters:
t - represents the term containing the pattern to be searched inside this term.
Returns:
a valid UnifyResult object if the matching has been successful; null if this is an atomic term (SType, IType, FType) or no unification has been found for a (CType or LType) term.
See Also:
findST(Term t)

getTerm

public static moses.controlState.Term getTerm(java.lang.String sTerm)
This method parses a string into a term. If the string is not parseable, a null is returned. The parsing is done using the Prolog conventions for term representation, also outlined in the toString method. The following symbols have a special meaning, and are used to separate individual tokens:
  • ( following an atomic token, it represents the beginning of the sub term list
  • ) following an atomic token, it represents the end of the sub term list
  • , following an atomic token, it represents the end of a sub term and the beginning of the next sub term
  • [ it represents the beginning of a term list
  • ] it represents the end of a term list
  • ' it represents the beginning of an atomic string (all the other tokens are not parsed till the next occurrence of the character )
  • " the same as above

Parameters:
sTerm - represents the string to be parsed into a term.
Returns:
the Term resulted by the parsing, or null if the parsing was not possible (the argument did not have the proper syntax.)

parse

public static moses.controlState.Term parse(java.lang.String sTerm)
This method is the same as getTerm(String sTerm), overloaded with a friendlier, more suggestive name. It parses a string into a term. If the string is not parseable, a null is returned. The parsing is done using the Prolog conventions for term representation, also outlined in the toString method. The following symbols have a special meaning, and are used to separate individual tokens:
  • ( following an atomic token, it represents the beginning of the sub term list
  • ) following an atomic token, it represents the end of the sub term list
  • , following an atomic token, it represents the end of a sub term and the beginning of the next sub term
  • [ it represents the beginning of a term list
  • ] it represents the end of a term list
  • ' it represents the beginning of an atomic string (all the other tokens are not parsed till the next occurrence of the character )
  • " the same as above

Parameters:
sTerm - represents the string to be parsed into a term.
Returns:
the Term resulted by the parsing, or null if the parsing was not possible (the argument did not have the proper syntax.)
See Also:
getTerm(String sTerm)

has

public boolean has(java.lang.String st)
This method searches for the pattern argument within this term.

Parameters:
st - represents the string containing the pattern to be searched for.
Returns:
true if this term is a compound or list type term, and the argument pattern can be found as a sub term of this object; false otherwise.
See Also:
has(Term t)

has

public boolean has(moses.controlState.Term t)
The same as above, except that it is overloaded with a term type argument. This method searches for the pattern argument within this term.

Parameters:
t - represents the term containing the pattern to be searched for.
Returns:
true if this term is a compound or list type term, and the argument pattern can be found as a sub term of this object; false otherwise.
See Also:
has(String st)

findT

public moses.controlState.Term findT(java.lang.String sterm)
Finds a term or a pattern of a term in a compound term or a list, and returns it.

Parameters:
sterm - represents the string containing the pattern to be searched for.
Returns:
a grounded term object if this term is a compound or list type term, and the argument pattern can be found as a sub term of this object; null otherwise.
See Also:
findT(Term t), has(String st)

findT

public moses.controlState.Term findT(moses.controlState.Term t)
This method is the same as above findT(String sterm), except it is overloaded with a Term type argument. Finds a term or a pattern of a term in a compound term or a list, and returns it.

Parameters:
t - represents the term containing the pattern to be searched for.
Returns:
a grounded term object if this term is a compound or list type term, and the argument pattern can be found as a sub term of this object; null otherwise.
See Also:
findT(String sterm), has(Term t)

fetchInt

public int fetchInt(java.lang.String functor)
This method searches in this compound or list term for a term with a functor that equals the argument, and whose only sub term is an integer. It returns the value of that integer or Integer.MIN_VALUE if nothing found. It is limited to patterns of the form functor(%int).

Parameters:
functor - represents the functor to be searched for.
Returns:
the value of integer sub term; Integer.MIN_VALUE if nothing is found.

incrementable

public boolean incrementable()
This method verifies that a term is of incrementable form (of compound type, with exactly one sub term, which is of type IType or FType).

Returns:
true if this term is incrementable, or false otherwise.

main

public static void main(java.lang.String[] args)