package common;
import java.util.NoSuchElementException;
import javax.swing.tree.TreeNode;
import expressions.Expression;
/**
* Base class for proof nodes that present the fundamental
* parts of the {@link common.ProofModel}s.
*
* @author Benedikt Meurer
* @version $Id$
*
* @see javax.swing.tree.TreeNode
*/
public interface ProofNode extends TreeNode {
//
// Primitives
//
/**
* Returns the {@link Expression} associated with this proof
* node. This is garantied to never return <code>null</code>.
*
* @return the {@link Expression} for this proof node.
*
* @see #getSteps()
*/
public Expression getExpression();
/**
* Returns the {@link ProofStep}s which were already performed
* on this proof node. The steps represent the {@link ProofRule}s
* that were applied to this node already and the associated
* expressions (which may be sub expressions of the expression
* associated with this proof node), to which the rules were
* applied.
*
* @return the {@link ProofStep}s or an empty array if no rules
* were applied to this node yet.
*
* @see #getExpression()
*/
public ProofStep[] getSteps();
/**
* Returns <code>true</code> if this node is already proven, that
* is, whether no more rules can be applied to this node. If
* <code>false</code> is returned the user must still apply
* additional rules to complete this node.
*
* @return <code>true</code> if this node is already proven.
*
* @see #getSteps()
*/
public boolean isProven();
/**
* Returns <code>true</code> if the {@link Expression} associated with this
* proof node contains syntactic code at the top most level. That is the
* surrounding expression is syntactic sugar that can be translated into the
* core syntax.
*
* @return <code>true</code> if the associated {@link Expression} contains
* syntactic sugar.
*
* @see #getExpression()
*/
public boolean containsSyntacticSugar();
/**
* Returns the child of this node at the <code>childIndex</code>.
*
* @param childIndex the index of the child node to return.
*
* @return the child {@link ProofNode} at the given index
* <code>childIndex</code>.
*
* @throws ArrayIndexOutOfBoundsException if <code>childIndex</code> is out
* of bounds.
*
* @see javax.swing.tree.TreeNode#getChildAt(int)
*/
public ProofNode getChildAt(int childIndex);
/**
* Returns the node's parent or <code>null</code> if this node has no
* parent.
*
* @return this node's parent {@link ProofNode}, or <code>null</code> if
* this node has no parent.
*
* @see javax.swing.tree.TreeNode#getParent()
*/
public ProofNode getParent();
//
// User Objects
//
/**
* Returns the user object associated with this proof node,
* or <code>null</code> if no user object was previously set
* via {@link #setUserObject(Object)}.
*
* @return the user object set for this proof node or <code>null</code>.
*
* @see #setUserObject(Object)
*/
public Object getUserObject();
/**
* Associates the specified <code>userObject</code> with this
* proof node. The <code>userObject</code> may be null, in
* which case only the previously set user object will be reset.
*
* @param userObject the new user object to associate with this
* proof node.
*
* @see #getUserObject()
*/
public void setUserObject(Object userObject);
//
// Tree Queries
//
/**
* Returns <code>true</code> if <code>anotherNode</code> is an ancestor of
* this node -- if it is this node, this node's parent, or an ancestor of this
* node's parent (note that a node is considered an ancestor of itself). If
* <code>anotherNode</code> is null, this method returns false. This
* operation is at worst <code>O(h)</code> where <code>h</code> is the distance
* from the root to this node.
*
* @param anotherNode node to test as an ancestor of this node
*
* @return <code>true</code> if this node is a descendant of
* <code>anotherNode</code>.
*
* @see #isNodeChild(TreeNode)
* @see #isNodeDescendant(ProofNode)
*/
public boolean isNodeAncestor(TreeNode anotherNode);
/**
* Returns <code>true</code> if <code>anotherNode</code> is a descendant
* of this node -- if it is this node, one of this node's children, or a
* descendant of one of this node's children. Note that a node is considered a
* descendant of itself. If <code>anotherNode</code> is <code>null</code>,
* returns <code>false</code>. This operation is at worst O(h) where h is
* the distance from the root to <code>anotherNode</code>.
*
* @param anotherNode node to test as descendant of this node
*
* @return <code>true</code> if this node is an ancestor of
* <code>anotherNode</code>.
*
* @see #isNodeAncestor(TreeNode)
* @see #isNodeChild(TreeNode)
*/
public boolean isNodeDescendant(ProofNode anotherNode);
/**
* Returns <code>true</code> if and only if <code>aNode</code> is in the
* same tree as this node. Returns <code>false</code> if <code>aNode</code>
* is <code>null</code>.
*
* @return <code>true if <code>aNode</code> is in the same tree as this node;
* <code>false</code> if <code>aNode</code> is <code>null</code>.
*
* @see #getRoot()
*/
public boolean isNodeRelated(ProofNode aNode);
/**
* Returns the root of the tree that contains this node. The root is the
* ancestor with a <code>null</code> parent.
*
* @return the root of the tree that contains this node.
*
* @see #isNodeAncestor(ProofNode)
* @see #isRoot()
*/
public ProofNode getRoot();
/**
* Returns true if this node is the root of the tree. The root is the only
* node in the tree with a <code>null</code> parent; every tree has exactly
* one root.
*
* @return <code>true</code> if this node is the root of its tree.
*
* @see #getRoot()
*/
public boolean isRoot();
//
// Child Queries
//
/**
* Returns <code>true</code> if <code>aNode</code> is a child of this
* node. If <code>aNode</code> is <code>null</code>, this method returns
* <code>false</code>.
*
* @return <code>true</code> if <code>aNode</code> is a child of this
* node; <code>false</code> if <code>aNode</code> is
* <code>null</code>.
*
* @see #isNodeAncestor(TreeNode)
*/
public boolean isNodeChild(TreeNode aNode);
/**
* Returns this node's first child. If this node has no children, throws
* {@link NoSuchElementException}.
*
* @return the first child of this node.
*
* @throws NoSuchElementException if this node has no children.
*
* @see #getLastChild()
*/
public ProofNode getFirstChild();
/**
* Returns this node's last child. If this node has no children, throws
* {@link NoSuchElementException}.
*
* @return the last child of this node.
*
* @throws NoSuchElementException if this node has no children.
*
* @see #getFirstChild()
*/
public ProofNode getLastChild();
/**
* Returns the child in this node's child array that immediately follows
* <code>aChild</code>, which must be a child of this node. If <code>aChild</code>
* is the last child, returns <code>null</code>. This method performs a linear
* search of this node's children for <code>aChild</code> and is <code>O(n)</code>
* where <code>n</code> is the number of children; to traverse the entire array of
* children, use an enumeration instead.
*
* @return the child of this node that immediately follows <code>aChild</code>.
*
* @throws IllegalArgumentException if <code>aChild</code> is <code>null</code>
* or is not a child of this node.
*
* @see javax.swing.tree.TreeNode#children()
* @see #getChildBefore(TreeNode)
*/
public ProofNode getChildAfter(TreeNode aChild);
/**
* Returns the child in this node's child array that immediately precedes
* <code>aChild</code>, which must be a child of this node. If <code>aChild</code>
* is the first child, returns <code>null</code>. This method performs a linear
* search of this node's children for <code>aChild</code> and is O(n) where n
* is the number of children.
*
* @return the child of this node that immediately precedes <code>aChild</code>.
*
* @throws IllegalArgumentException if <code>aChild</code> is <code>null</code>
* or is not a child of this node.
*
* @see javax.swing.tree.TreeNode#children()
* @see #getChildAfter(TreeNode)
*/
public ProofNode getChildBefore(TreeNode aChild);
//
// Leaf Queries
//
/**
* Finds and returns the first leaf that is a descendant of this node --
* either this node or its first child's first leaf. Returns this node if
* it is a leaf.
*
* @return the first leaf in the subtree rooted at this node.
*
* @see javax.swing.tree.TreeNode#isLeaf()
* @see #isNodeDescendant(ProofNode)
*/
public ProofNode getFirstLeaf();
/**
* Finds and returns the last leaf that is a descendant of this node --
* either this node or its last child's last leaf. Returns this node if
* it is a leaf.
*
* @return the last leaf in the subtree rooted at this node.
*
* @see javax.swing.tree.TreeNode#isLeaf()
* @see #isNodeDescendant(ProofNode)
*/
public ProofNode getLastLeaf();
}