com.thesett.aima.logic.fol.prolog.builtins.ResolutionState Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of prolog Show documentation
Implementation of a Prolog interpreter that works directly over the abstract syntax tree.
There is a newer version: 0.9.117
/*
 * Copyright The Sett Ltd, 2005 to 2014.
 *
 * 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.
 */
package com.thesett.aima.logic.fol.prolog.builtins;

import java.util.Queue;

import com.thesett.aima.logic.fol.Clause;
import com.thesett.aima.logic.fol.Functor;
import com.thesett.aima.logic.fol.Variable;
import com.thesett.aima.logic.fol.VariableAndFunctorInterner;
import com.thesett.aima.search.util.backtracking.ReTraversable;
import com.thesett.common.util.Function;
import com.thesett.common.util.SimpleQueue;
import com.thesett.common.util.Sink;

/**
 * ResolutionState forms a state corresponding to a step of a proof in a resolution, where each step of the proof
 * corresponds exactly with one goal functor to be proved in that step. New disjunctive choice points will always
 * correspond to new resolution states, as will sequences of conjunctive steps.
 *
 * This interface is exposed mainly to provide a clean interface to implement {@link BuiltIn}s against the proof
 * search engine. It provides access to the goal stack, the variable bindings, the current clause-as-choice-point, a
 * unifier to perform unifications as required, and a method to create subsequent steps in the proof.
 *
 * 
The goal stack and variable binding sink provided by this interface should be self-undoing. That is if a
 * {@link BuiltIn} adds goals or variable bindings to them, but is later required to be back-tracked over, the built in
 * does not have to explicitly undo its additions. The state implementation is clever enough to be able to handle
 * back-tracking on its own.
 *
 * 

 * CRC Card Responsibilities
 * 
 Provide a stack of outstanding goals to be proved.
 * 
 Provide a sink to insert new variable bindings onto.
 * 
 Provide the current query choice-point being resolved over.
 * 
 Provide a unifier to perform unifications with.
 * 
 Provide an interner to translate interned symbols with.
 * 
 Create a new resolution state as a choice point for a clause.
 * 
 *
 * @author Rupert Smith
 */
public interface ResolutionState extends ReTraversable
{
    /**
     * Adds new resolution states as choices or a single new state to be resolved in the resolution search, as a child
     * state of this one.
     *
     * If the goal resolves against the domain, all possible matching clauses are taken with it to form a set of
     * states to choose amongst as continution states from this one. If the goal is a built-in, a single state to
     * evaluate it as a continuation frmo this state is created. Multiple calls to this method will add more states to
     * the choice set.
     *
     * @param goal The functor to create continuation states for.
     */
    void createContinuationStatesForGoal(BuiltInFunctor goal);

    /**
     * Provides a simple interface onto the goal stack. This may be used to peek at the current goal, and remove or
     * insert a goal onto the stack.
     *
     * @return The current goal stack.
     */
    SimpleQueue getGoalStack();

    /**
     * Provides the most recent state that acted as a choice point that led to this state.
     *
     * @return The most recent state that acted as a choice point that led to this state.
     */
    ResolutionState getLastChoicePoint();

    /**
     * Marks this state as 'cut', which means that it is effectively removed from the search and will fail.
     *
     * Note that the cut will be examined when the state becomes active, so if it has already become active then it
     * will be too late for the cut to have any effect.
     */
    void cut();

    /**
     * Provides the choice point states that this state leads to.
     *
     * @return The choice point states that this state leads to.
     */
    Queue getChoicePoints();

    /**
     * Provides a sink onto the variable binding stack. This may be used to add variable bindings.
     *
     * @return A sink onto the variable binding stack.
     */
    Sink getVariableBindings();

    /**
     * Provides the current choice point clause that this resolution state is a proof step within.
     *
     * @return The current choice point clause that this resolution state is a proof step within.
     */
    Clause getCurrentClause();

    /**
     * Provides a function to transform functors into built-ins. When a functor is being created as a goal, this
     * function should be used to map it onto its implementing built-in.
     *
     * @return A function mapping functors to built-ins.
     */
    Function getBuiltInTransform();

    /**
     * Provides a unifier to perform any required unificiations with.
     *
     * @return The unifier for this state.
     */
    PrologUnifier getUnifier();

    /**
     * Provides an interner to translate interned symbols with.
     *
     * @return An interner to translate interned symbols with.
     */
    VariableAndFunctorInterner getInterner();

    /**
     * Provides a trace indenter to create indents for pretty printing execution trace statements with. This indenter
     * will be set up to increase its indent on every choice point, and decrease it on every back-tracking over a choice
     * point. Trace statements will generally not need to apply a delta to the indentation level but should stick with
     * the indentation as choice point depth scheme.
     *
     * @return A trace indenter to assist with pretty printing trace statements.
     */
    //public TraceIndenter getTraceIndenter();
}