//
//  MPParsedExpression.h
//  MathPad
//
//  Created by Kim Wittenburg on 14.11.14.
//  Copyright (c) 2014 Kim Wittenburg. All rights reserved.
//


/*!
 @header
 This file contains the <code>MPParsedExpression</code> class.
 */


/*!
    @const      MPMathKitErrorDomain
    @abstract   Predefined error domain for errors from the MathKit framework.
 
    @discussion Errors in MathKit can occur during parsing or evaluation of
                expressions. These two can be distinguished by their respective
                error codes. Parsing errors have error codes below
                <code>100</code>. Evaluation errors (math errors) on the other
                hand have error codes from <code>100</code> upwards.
 */
FOUNDATION_EXPORT NSString *const MPMathKitErrorDomain;


/*!
    @const      MPPathToExpressionKey
    @abstract   Predefined key for the path to the expression that caused an error.
 
    @discussion Parsing errors in the <code>MPMathKitErrorDomain</code> have a
                value for this key in their <code>userInfo</code> dictionary. The
                value is of type <code>NSIndexPath</code>. The root of that path
                is also the root expression of the expression tree of the
                expression that was parsed (which in turn caused an error).
 */
FOUNDATION_EXPORT NSString *const MPPathToExpressionKey;


/*!
    @const      MPErrorRangeKey
    @abstract   Predefined key for the range inside an expression that caused a
                parsing error.
 
    @discussion Parsing errors in the <code>MPMathKitErrorDomain</code> have a
                value for this key in their <code>userInfo</code> dictionary. The
                value is a <code>NSRange</code> value wrapped in a
                <code>NSValue</code> object.
 */
FOUNDATION_EXPORT NSString *const MPErrorRangeKey;



@class MPParsedExpression, MPTerm;


/*!
    @class      MPParsedExpression
    @abstract   A parsed expression represents an expression whose syntax is
                mathematically valid and thus can be evaluated.
 
    @discussion This class should not be instanciated directly. Instead you
                should use the <code>parse...</code> methods from the <code>@link
                //apple_ref/occ/cl/MPExpression@/link</code> class. A
                successfully parsed expression can still fail to be evaluated if
                it contains mathematically undefined expressions.
 */
@interface MPParsedExpression : NSObject

/*!
    @property   definedVariable
    @abstract   The variable defined by the expression, if any.
 
    @discussion If a variable was defined this property is a string of length
                <code>1</code> containing the name of that variable. If no
                variable was defined this property is <code>nil</code>.
 
                This property should not be set manually.
 */
@property (nonatomic, strong) NSString *definedVariable;


/*!
    @property   term
    @abstract   The receiver's evaluatable term.
 
    @discussion The term may still contain mathematicall undefined expressions.
 
                This property should not be set manually.
 */
@property (nonatomic, strong) MPTerm *term;


/*!
    @method     evaluate:
    @abstract   Evaluates the receiver.

    @discussion This method is a convenience method for evaluating the receiver's
                <code>@link
                //apple_ref/occ/instp/MPParsedExpression/term@/link</code>.
 
    @param      error
                If an error occured during evaluation it will be returned
                indirectly through this parameter. If you are not interested in
                errors pass <code>NULL</code>.
 
    @return     A <code>NSDecimalNumber</code> containing the result of the
                evaluation. Depending on the evaluated expression the result may
                only be of double precision.
 */
- (NSDecimalNumber *)evaluate:(NSError *__autoreleasing *)error;

@end