//
//  MPExpressionTreeElement.h
//  MathPad
//
//  Created by Kim Wittenburg on 09.10.14.
//  Copyright (c) 2014 Kim Wittenburg. All rights reserved.
//
// TODO: Replace internal inconsistency exception with something else



@class MPTokenStream;


/*!
    @protocol   MPExpressionTreeElement
    @brief      This protocol defines the methods that are essential for dealing
                with an expression in a mathematical context.
 
    @discussion Dealing with an expression in a mathematical context involves
                anything from evaluation to transformation of expressions and
                equations.
 */
@protocol MPExpressionTreeElement <NSObject>
@required


/*!
    @method     initWithTokenStream:
    @brief      Initializes the expression tree element from the given token
                strem.
 
    @discussion This method consumes the tokens that make up this element. If the
                token stream does not start with a token that is appropriate for
                the initializied expression tree element a @c
                NSInternalInconsistency exception is raised.
 
    @param      tokenStream
                The token stream the receiver is to be initialized from.
 
    @return     A new instance.
 */
- (instancetype)initWithTokenStream:(MPTokenStream *)tokenStream;


/*!
    @method     validate:
    @brief      Validates the receiver.
 
    @discussion Validation should only check for syntax errors. Mathematical
                errors like a division by @c 0 should be handled with in @c
                -evaluate.
 
    @param      error
                If there is a syntax error in the receiver this parameter should
                be set to an appropriate value. If you are not interested in the
                type of syntax error pass @c NULL.
 
    @return     @c YES if the receiver is valid, @c NO otherwise. If @c NO is
                returned the @c error parameter should be set to an appropriate
                value.
 */
- (BOOL)validate:(NSError *__autoreleasing *)error;


/*!
    @method     evaluate:
    @brief      Evaluates the receiver.
 
    @discussion Evaluation does not take syntax errors into account. Before this
                method is called you must call @c validate: to make sure that the
                reciever is valid for evaluation. The result of evaluation with
                @c -validate: returning @c NO may be unexpected or evaluation may
                completely fail.
 
    @param      error
                If any errors occur during evaluation (such as division by zero)
                this parameter will be set to an appropriate value. If you are
                not interested in errors pass @c NULL.
       @warning This method is not responsible for syntax validation. Use @c
                -validate: instead.
 
    @return     The result of the evaluationa or @c nil or @c NaN if evaluation
                fails. If evaluation fails the @c error parameter will be set to
                an apporpriate value.
 */
- (NSDecimalNumber *)evaluate:(NSError *__autoreleasing *)error;

@end