iclterm.java

SRI international 发布的OAA框架软件

   * @throws UnsupportedOperationException if term cannot have children
   */
  public abstract void removeAllUnifying(IclTerm n) throws UnsupportedOperationException;

  /**
   * Remove the first child found that unifies with the given one.
   *
   * @param n the term against which to unify
   * @return IclTerm: the removed term, or null
   * @throws UnsupportedOperationException if term cannot have children
   */
  public abstract IclTerm removeUnifying(IclTerm n) throws UnsupportedOperationException;

  /**
   * Remove the child at the given index.
   *
   * @param i the index
   * @throws UnsupportedOperationException if term cannot have children
   */
  public abstract void removeElement(int i) throws UnsupportedOperationException;

  /**
   * Replace all terms that unify with target with replacement.
   * Note that we don't use copies of the replacement, but the
   * replacement itself.
   *
   * @param target the target against which to unify
   * @param replacement the replacement
   * @throws UnsupportedOperationException if term cannot have children
   */
  public abstract void replaceUnifying(IclTerm target, IclTerm replacement) throws UnsupportedOperationException;
  
  /**
   * Replace the term at the given index. If there is no child at
   * the given index, nothing happens.  Again, no copies of the
   * replacement are used.
   *
   * @param target the index to replace
   * @param replacement the replacement
   * @throws IndexOutOfBoundsException if target is out of bounds
   */
  public abstract void replaceElement(int target, IclTerm replacement) throws IndexOutOfBoundsException, UnsupportedOperationException;

  /**
   * Generate an IclTerm from a string, throwing a RuntimeException on
   * any parsing exceptions.  Thread safe.
   *
   * @param failFast if true, throw RuntimeException on error; if
   * false, just display errors to stderr
   * @param t the string from which to generate an IclTerm
   * @return IclTerm: the new IclTerm or null if it could not be parsed
   * @throws RuntimeException if the string could not be parsed
   */
  public static final IclTerm fromString(boolean failFast, String t) 
  {
    try {
      return fromString(t);
    }
    catch(ANTLRException ae) {
      if(failFast) {
        RuntimeException re = new RuntimeException(ae.toString());
        re.fillInStackTrace();
        throw re;
      }
      else {
	System.err.println("IclUtils.fromString(): error parsing " + t);
	System.err.println(ae.toString());
      }
      return null;
    }
  }

  /**
   * Generate an IclTerm from a string. Thread safe.
   *
   * @param String t: the string from which to generate an IclTerm
   * @return IclTerm: the new IclTerm or null if the passed in String is ""--in
   * the future, this may change to throw an exception in this case
   * @throws RecognitionException if the string could not be parsed
   * @throws TokenStreamException if the string could not be tokenized
   */
  public static final IclTerm fromString(String t) throws RecognitionException, TokenStreamException
  {
    IclAST ast = null;
    
    // We can use one of two thread safety schemes.  Either create a
    // new lexer and parser each time, or synchronize on the parser.
    // They're about equally fast, but creating a new one each time
    // lets us get more throughput when multiple threads use
    // fromString--which is all the time if OAA is used, and not just
    // IclTerm.fromString().  Note that synchronization would use
    // something like:
    //     if(fromStringFirst) {
    //       fromStringParser.setASTNodeType("com.sri.oaa2.icl.IclAST");
    //       fromStringFirst = false;
    //     }
    //     synchronized(fromStringParser) {
    //       fromStringLexer.getInputState().resetInput(new CharBuffer(new StringReader(t)));
    //       fromStringParser.setTokenBuffer(new TokenBuffer(fromStringLexer));
    //       fromStringParser.start();
    //       ast = (IclTerm)fromStringParser.getAST();
    //     }

    // Thread safe, since we create a new lexer and parser each time
    OaaPrologLexer lexer = new OaaPrologLexer(new StringReader(t));
    OaaPrologParser parser = new OaaPrologParser(lexer);
    parser.setASTNodeType("com.sri.oaa2.icl.IclAST");
    parser.startOneOnly();
    ast = (IclAST)parser.getAST();
    // this null check and return is to be backwards compatible with
    // prior versions--throwing a NullPointerException might be good,
    // or even some ANTLRException, as it's not too likely that folks
    // expect a null return from this
    if(ast == null) {
      return null;
    }
    return ast.getIclTerm();
  }

  /**
   * Get an iterator for the children of this term.  If no iterator is possible for
   * this type of term, returns an empty Iterator that cannot be modified.  If there are no children, but children are
   * possible, then return an empty Iterator. All optional methods of the Iterator
   * interface are implemented if the term is composite.
   *
   * @return Iterator an iterator over the children of this term
   * @see #isAtomic
   * @see #isComposite
   */
  public abstract Iterator iterator();

  /**
   * Get an iterator for the children of this term.  If no iterator is possible for
   * this type of term, returns an empty ListIterator that cannot be modified.  If there are no children, but children are
   * possible, then return an empty Iterator.  All optional methods of the ListIterator
   * interface are implemented if the term is composite.
   *
   * @return ListIterator, an iterator over the children of this term
   * @see #isAtomic
   * @see #isComposite
   */
  public abstract ListIterator listIterator();

  //
  // DEPRECATED INTERFACE
  //
  //
  // Following is the deprecated interface
  //

  /**
   * @deprecated use listIterator() or iterator()
   */
  public final ListIterator iclListIterator() 
  {
    if(getChildren() != null) {
      return listIterator();
    }
    else {
      return null;
    }
  }

  /**
   * @deprecated use listIterator() or iterator()
   */
  public final ListIterator iclArgumentsIterator() 
  {
    if(getChildren() != null) {
      return listIterator();
    }
    else {
      return null;
    }
  }

  /**
   * @deprecated use clone()
   */
  public final IclTerm iclClone() 
  {
    return (IclTerm)clone();
  }

  /**
   * @deprecated use add(IclTerm) or add(int, IclTerm)
   */
  public final void iclAddToList(IclTerm t, boolean atEnd) 
  {
    if(atEnd) {
      add(t);
    }
    else {
      add(0, t);
    }
  }

  /**
   * @deprecated use add
   */
  public final void iclAddToList(IclTerm t) 
  {
    add(0, t);
  }

  /**
   * @deprecated use removeUnifying
   */
  public final void iclDelete(IclTerm t) {
    removeAllUnifying(t);
  }

  /**
   * @deprecated use removeUnifying
   */
  public final IclTerm iclRemoveElement(IclTerm t) 
  {
    return removeUnifying(t);
  }

  /**
   * @deprecated use removeUnifying
   */
  public final void iclRemoveFromList(IclTerm t) 
  {
    removeUnifying(t);
  }

  /**
   * @deprecated use replaceUnifying
   */
  public final void iclReplaceElement(IclTerm oldTerm, IclTerm newTerm) { 
    replaceUnifying(oldTerm, newTerm);
  }

  /**
   * @deprecated use replaceElement
   */
  public final void iclReplaceNthTerm(int position, IclTerm newTerm) 
  {
    replaceElement(position - 1, newTerm);
  }

  /**
   * @deprecated use add
   */
  public final void iclAppend(IclTerm inList) 
  {
    addAll(inList);
  }

  /**
   * @deprecated use clearTerms
   */
  public final void iclRetractAll() 
  {
    clearTerms();
  }

  /**
   * @deprecated use size
   */
  public final int iclListLen() 
  {
    return size();
  }

  /**
   * @deprecated use size
   */
  public final int iclNumTerms() 
  {
    return size();
  }

  /**
   * @deprecated use getTerm(index - 1)
   */
  public final IclTerm iclNthTerm(int index) 
  {
    return getTerm(index - 1);
  }


  /**
   * @deprecated use Unifier.getInstance().unify()
   */
  public static final IclTerm iclUnify(IclTerm t1, IclTerm t2, boolean inDebug)
  { 
    return Unifier.getInstance().unify(t1, t2);
  }

  /**
   * @deprecated use Unifier.getInstance().unify()
   */
  public static final IclTerm iclUnify(IclTerm t1, IclTerm t2) 
  {
    return Unifier.getInstance().unify(t1, t2);
  }

  /**
   * @deprecated use Unifier.getInstance().unify()
   */
  public static final IclTerm iclUnify(IclTerm t1, IclTerm t2, HashMap bindings)
  {
    return Unifier.getInstance().unify(t1, t2, bindings);
  }

  /**
   * @deprecated  use Unifier.getInstance().deref()
   */
  public static final IclTerm iclDerefTerm(IclTerm t1, HashMap bindings) 
  {
    return Unifier.getInstance().deref(t1, bindings);
  }

  /**
   * @deprecated use toIdentifyingString()
   */
  public String iclStr() 
  {
    return toIdentifyingString();
  }

  /**
   * @deprecated use toArrayList()
   */
  public Vector toVector() 
  {
    return new Vector(toArrayList());
  }

  /**
   * @deprecated use ToInt.getInstance().from() or ((IclInt)this).toInt
   */
  public int iclInt() 
  {
    if(this.isInt()) {
      return ((IclInt)this).toInt();
    }
    else {
      return ToInt.getInstance().from(this, 0);
    }
  }

  /**
   * @deprecated use ToStarter.getInstance().from() or ((IclGroup)this).getStarter
   */
  public char iclStarter() 
  {
    if(this.isGroup()) {
      return ((IclGroup)this).getStarter();
    }
    else {
      return ToStarter.getInstance().from(this, (char)0);
    }
  }

  /**
   * @deprecated use ToFloat.getInstance().from() or ((IclFloat)this).toFloat
   * or ((IclFloat)this).toDouble
   */
  public float iclFloat() 
  {
    if(this.isFloat()) {
      return ((IclFloat)this).toFloat();
    }
    else {
      return ToFloat.getInstance().from(this, 0.0f);
    }
  }

  /**
   * @deprecated use ToFunctor.getInstance().from() or ((IclStruct)this).getFunctor()
   */
  public String iclFunctor() 
  {
      String ret = null;

    if(this.isStruct()) {
      ret = ((IclStruct)this).getFunctor();
    }
    else {
      ret = ToFunctor.getInstance().from(this, null);
    }

      // OAA 2.1 returns a blank string from iclFunctor(). This is added
      // to 2.2 to maintain backwards compatibility.
      if (ret == null) {
        ret = "";
      }

      return ret;
  }

  /**
   * @deprecated use toArrayList()
   */
  public ArrayList iclArguments() 
  {
    return toArrayList();
  }
}