All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.cyc.kb.Sentence Maven / Gradle / Ivy

There is a newer version: 1.0.0-rc7.0
Show newest version
package com.cyc.kb;

import com.cyc.kb.exception.CreateException;
import com.cyc.kb.exception.KbException;
import com.cyc.kb.exception.KbTypeException;

import java.util.List;
import java.util.Set;

/*
 * #%L
 * File: Sentence.java
 * Project: Core API Object Specification
 * %%
 * Copyright (C) 2013 - 2015 Cycorp, Inc
 * %%
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * #L%
 */
/**
 * The interface for Cyc sentences. Sentences encode propositions, which can be used as questions
 * (in a {@link Query}) or claims (in an {@link Assertion}).
 *
 * @author vijay
 * @version $Id: Sentence.java 163206 2015-12-16 00:07:09Z nwinant $
 * @since 1.0
 */
public interface Sentence extends KbObject {

  /**
   * Assert this sentence in the context ctx.
   *
   * In many cases, it will be useful to call
   * {@link #isAssertible(com.cyc.kb.Context)} before asserting a sentence.
   *
   * @param ctx the context where this sentence will be asserted.
   *
   * @return the {@link Assertion} object, either a {@link Fact} or a {@link Rule}.
   *
   * @throws KbException if the assertion fails for any reason, include being syntactically
   * invalid.
   */
  public Assertion assertIn(Context ctx) throws KbException;

  /**
   * Checks if a given sentence meets the constraints necessary to be assertible in
   * ctx. In particular, returns true if the arguments of the sentence are compatible 
   * with the argument constraints of the operator (i.e. could be made to actually meet the 
   * constraints without removing any existing assertions). For sentences with predicate operators, 
   * the arguments must also be compatible with all relevant interArg* constraints. In some cases,
   * additional requirements are imposed (e.g. the constraints must actually be known to be met, not
   * just not be known to be incompatible). For an explanation of why a particular sentence is not
   * assertible, check {@link #notAssertibleExplanation(com.cyc.kb.Context)}
   *
   * @param ctx the context where semantic constraints are checked
   *
   * @return if the sentence is compatible with all relevant syntactic and semantic constraints, and
   * is therefore assertible.
   *
   * @throws CycApiException if unable to determine whether constraints are met.
   */
  public boolean isAssertible(Context ctx);

  /**
   * Return an explanation of why the sentence is not assertible. Note that this reason may not be
   * exhaustive; once the problems mentioned in the reason are fixed, additional calls to this
   * method may turn up additional problems.
   *
   * @param ctx the context where semantic constraints are checked
   *
   * @return a detailed explanation of why a sentence is not assertible. Returns null if it
   * encounters an internal error.
   *
   */
  public String notAssertibleExplanation(Context ctx);

  /**
   * For each element of from replace it with the element of to that's at
   * the same index.  This does not modify the original Sentence, but instead returns a new 
   * sentence.
   * 
   * @param from  a list of objects that will be replaced if found
   * @param to    a list of objects that will be in the new modified sentence
   * 
   * @return a new Sentence with the replaced terms
   * 
   * @throws KbTypeException
   */
  public Sentence replaceTerms(List from, List to) 
          throws KbTypeException, CreateException;

  public Sentence quantify(KbObject variable) throws KbTypeException, CreateException;

  /*
  // A ENUM interface that returns modified sentences for commonly used sentence operators,
  // such as #$not and #$assertedSentence.
  public interface SentenceOperator {
    // Return a new sentence with sent sentence wrapped with this
    // enumerator.
    public Sentence wrap(Sentence sent) throws KbTypeException, CreateException;
  }
  */
  
  /**
   * Returns a set of arg positions that describe all the locations where the
   * given term can be found in this formula.
   *
   * @param term The term to search for
   * @return The set of all arg positions where term can be found
   */ 
  public Set getArgPositionsForTerm(final Object term);
}