/*

 * Created on Sep 19, 2003

 */

package isac.util.interfaces;

import isac.util.formulae.*;

import isac.util.tactics.*;

/**

 * Interface to be used to communicate in the direction towards the Math Engine.

 * 

 * @author Alan Krempler

 */

public interface IToCalc {

	/**

	 * Get a new iterator referencing the root element of the calculation tree. 

	 * <p> The functionality for navigating the calculation 

	 * is implemented in the CalcIterator object.

	 * @return new instance of CalcIterator

	 */

	public ICalcIterator iterator();

	/**

	 * Register a new listener who wants to be notified of changes in the data.

	 * The listener has to implement the IToUser interface.

	 * 

	 * @param listener New listener to be registered.

	 * @return false on success, true otherwise.

	 */  

	public boolean addListener(IToUser listener);

	/**

	 * @return an iterator referencing the current

	 * "hot spot" in the calculation, i.e. the active formula.

	 */

	public ICalcIterator getActiveFormula();

	/**

	 * Makes the passed formula the active formula, i.e. the formula 

	 * the next tactic is applied to.

	 * @param newActiveFormula Iterator referencing the new desired position

	 */

	public void moveActiveFormula(ICalcIterator newActiveFormula);

	/**

	 * Tries to replaces the active formula in the calculation tree by 

	 * the passed formula. This could fail if no valid derivation from 

	 * the preceding formula to the (new) active formula can be found. 

	 * <p>Parts of the calculation after the replaced 

	 * formula are likely to become invalid, listeners will be informed

	 * of this with the update message, which contains the last unchanged 

	 * formula.

	 * @param newFormula

	 * @return The method will return 0 on success or a nonzero value 

	 * indicating the status otherwise. 

	 */

	public int replaceFormula(Formula newFormula);

	/**

	Tries to append the passed formula after the active formula. 

	This could fail if no valid derivation from the preceding formula 

	to the (new) active formula can be found. The method will fail as 

	well if the active formula is not the last formula in the (sub)calculation.

	Parts of the calculation might become invalid.

	* @param newFormula

	* @return The method will return 0 on success or a nonzero value 

	indicating the status otherwise.

	*/

	public int appendFormula(Formula newFormula);

	/**

	 Set the tactic to be used in the next step of calculation.   

	 * @param tactic the Tactic to be used in the the next step

	 * @return The return value indicates success, failure or probable

	 * success at a later time.

	 */

	 public int setNextTactic(Tactic tactic);

	/**

	 * Retrieve the tactic proposed by the SML-Kernel for 

	 * the next step in the calculation.  

	 * @return proposed tactic.

	 * Can be null, if the kernel does

	 * not know what to do next, or if the end 

	 * of the calculation is reached 

	 */

	 public Tactic fetchProposedTactic();

	 public static final int TACTICS_ALL = 1;

	 public static final int TACTICS_CURRENT_THEORY = 2;

	 public static final int TACTICS_CURRENT_METHOD = 3;

	/**

	 * Get a list of tactics applicable to the active formula. 

	 * @param scope The filter parameter selects the scope of

	 * search for applicable tactics.

	 * @return Array with applicable tactics

	 * @see #TACTICS_ALL

	 * @see #TACTICS_CURRENT_THEORY

	 * @see #TACTICS_CURRENT_METHOD

	 */

	 public Tactic[] fetchApplicableTactics(int scope);

	 public static final int SCOPE_CALCULATION = 1;

	 public static final int SCOPE_SUBCALCULATION = 2;

	 public static final int SCOPE_SUBPROBLEM = 3;

	/**

	 * Calculate the next n steps starting from the active formula.   

	 * @param scope The scope parameter can have following values:

	 * @param nSteps Specifies the count of steps to be autocalculated. 

	 * Passing 0 for nSteps will calculate until reaching a final result. 

	 * @return The method returns an unique id to identify the request when 

	 * notifying about updates in the tree.

	 * @see #SCOPE_CALCULATION

	 * @see #SCOPE_SUBCALCULATION

	 * @see #SCOPE_SUBPROBLEM

	 */

	 public int autoCalculate(int scope, int nSteps);

}