//
// MPExpression.h
// MathPad
//
// Created by Kim Wittenburg on 10.08.14.
// Copyright (c) 2014 Kim Wittenburg. All rights reserved.
//
/*!
@const MPIllegalElementException
@brief Name for an exception that is raised if an invalid element is
added to an expression.
@discussion This exception may be raised during initialization of an
expression or when the expression is mutated. This exception
always contains the @c MPIllegalElementExceptionElementKey key in
its @c userInfo dictionary.
*/
FOUNDATION_EXPORT NSString *const MPIllegalElementException;
/*!
@const MPIllegalElementExceptionElementKey
@brief Predefined key for the invalid element that caused an exception
to be raised.
@discussion The invalid element can be of any type.
*/
FOUNDATION_EXPORT NSString *const MPIllegalElementExceptionElementKey;
/*!
@typedef MPReferenceFrame
@brief A reference frame describes what an @em item in an expression is.
@discussion Reference frames have to be passed in multiple methods of the @c
MPExpression class. You can convert between reference frames
using the following methods:
@textblock
- convertIndexFromReferenceFrame:toReferenceFrame:
- convertIndexFromReferenceFrame:toReferenceFrame:offset:
@/textblock
There are three different types of items (reference frames):
symbols, tokens and elements. A symbol is the smalles possible
unit in an expression. Thus a token consists of one or more
symbols. Similarly an element consists of one or more tokens.
@constant MPElementReferenceFrame
Specifies that items should be interpreted as elements. An
element is either a @c NSString object or a @c MPFunction object.
@constant MPSymbolReferenceFrame
Specifies that items should be interpreted as symbols. A symbol
can be a single character (represented by the @c NSString class)
or a @c MPFunction object.
@constant MPTokenReferenceFrame
Specifies that items should be interpreted as tokens. A token is
a logical unit of content in an expression. This can be a single
character (e.g. '+'), an arbitrary number of characters (e.g. a
number) or a @c MPFunction object.
All tokens conform to the @c MPToken protocol.
*/
typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
MPElementReferenceFrame,
MPSymbolReferenceFrame,
MPTokenReferenceFrame
};
@class MPExpression, MPFunction, MPRangePath, MPParsedExpression;
@protocol MPExpressionElement, MPToken;
/*!
@class MPExpression
@brief An @c MPExpression object is the base object for any mathematical
expression.
@discussion Every expression consists of string elements (represented by the
@c NSString class) and function elements (represented by the @c
MPFunction class). Functions likewise can have expressions as
elements (also called children in this context). Both
expressions and functions are mutable. Through this organization
expression are organized in a tree-like structure called the
'expression tree'.
An expression can evaluate itself giving you either a
result or possibly an error if the expression was not constructed
correctly or could not be evaluated.
*/
@interface MPExpression : NSObject
#pragma mark Creation Methods
/*!
@methodgroup Creation Methods
*/
/*!
@method init
@brief Initlializes a newly created expression.
@discussion This method is a convenience initializer to initialize an
expression with @c 0 elements.
@return An expression.
*/
- (instancetype)init;
/*!
@method initWithElement:
@brief Initializes a newly created expression with @c element.
@discussion This method is a convenience initializer to initialize an
expression with a single element.
@param element
The element to be added to the expression. The @c element will be
copied.
@return An expression initialized with @c element.
*/
- (instancetype)initWithElement:(id)element;
/*!
@method initWithElements:
@brief Initializes a newly created expression with the specified
elements.
@discussion All elements must conform to the @c MPExpressionElement protocol.
If one or more objects do not conform to that protocol an @c
MPIllegalElementException is raised.
This method is the designated initializer for the @c MPExpression
class.
@param elements
The elements that should be added to the expression. Every
element must conform to the @c MPExpressionElement protocol. Each
element is copied and the copy is then added to the expression.
The object in the @c elements array is not modified.
@return An expression containing @c elements.
*/
- (instancetype)initWithElements:(NSArray *)elements; /* designated initializer */
#pragma mark Querying Expressions
/*!
@methodgroup Querying Expressions
*/
/*!
@property parent
@brief The receiver's parent.
@discussion Expressions are organized in a tree-like structure. Through this
property an expression's containing function can be accessed.
@warning You should never set this property manually. If you are
implementing a custom subclass of @c MPFunction use the @c
MPFunctionAccessorImplementation macro.
@return The parent of the receiver or @c nil if the receiver is the root
expression.
*/
@property (nonatomic, weak) MPFunction *parent;
/*!
@method rootExpression
@brief Returns the root expression from the receiver's expression tree.
@discussion The root expression is the ultimate parent of all expressions and
functions in the expression tree. A root expression does not have
a parent.
@return The root expression from the receiver's expression tree.
*/
- (MPExpression *)rootExpression;
/*!
@method indexPath
@brief Returns the index path of the receiver in the expression tree.
@discussion The index path is calculated by going up the expression tree
collecting the respective index of the receiver. The indexes are
expressed in the element reference frame. If any of the indexes
exceed the respective receiver's bounds a @c NSRangeException is
raised.
@return The index path of the receiver in the expression tree.
*/
- (NSIndexPath *)indexPath;
/*!
@method countItemsInReferenceFrame:
@brief Returns the number of items in the receiver in the respective
reference frame.
@param referenceFrame
The reference frame that should be used to count the items.
@return The current number of items in the receiver counted in the
specified reference frame.
*/
- (NSUInteger)countItemsInReferenceFrame:(MPReferenceFrame)referenceFrame;
/*!
@method itemAtIndex:referenceFrame:
@brief Returns the item at @c anIndex.
@discussion The item is not copied before it is returned. So be aware that
if you mutate a @c MPFunction object returned from this function
the changes will be reflected in the receiver.
@param anIndex
The index of the item. If the index is greater than the number of
items for the respective reference frame an @c NSRangeException
is raised.
@param referenceFrame
The reference frame that should be used to identify the item at
@c anIndex.
@return The item at @c anIndex.
*/
- (id)itemAtIndex:(NSUInteger)anIndex
referenceFrame:(MPReferenceFrame)referenceFrame;
/*!
@method elementAtIndex:referenceFrame:
@brief Returns the element at the specified index.
@discussion An element is either a string or a function. If @c anIndex
specifies a position inside a string the complete string element
is returned.
This method does not return any item in any reference frame but
only complete elements. Use @c -itemAtIndex:referenceFrame: for
that purpose.
@param anIndex
The index of the element.
@param referenceFrame
The reference frame @c anIndex is specified in.
@return The item at @c anIndex.
*/
- (id)elementAtIndex:(NSUInteger)anIndex
referenceFrame:(MPReferenceFrame)referenceFrame;
/*!
@method indexOfElement:
@brief Returns the index of @c element or @c NSNotFound if it was not
found.
@param element
The element to find.
@return The index of @c element expressed in the element reference frame.
*/
- (NSUInteger)indexOfElement:(id)element;
/*!
@method itemsInRange:referenceFrame:
@brief Returns an array of the items that are located in the specified
range.
@discussion The objects in the returned array are not copied before they are
returned. You should be aware of the fact that mutations to any
returned objects will be reflected in the receiver.
If the @c range exceeds the receiver's bounds an @c
NSRangeException is raised.
@param aRange
The requested range within the receiver's bounds.
@param referenceFrame
The referenceFrame @c aRange is expressed in.
@return An array of objects that conform to the @c MPExpressionElement
protocol (that is @c NSString objects and @c MPFunction objects).
The length of the returned array is equal to the length of the
specified range.
*/
- (NSArray *)itemsInRange:(NSRange)aRange
referenceFrame:(MPReferenceFrame)referenceFrame;
/*!
@method allItemsInReferenceFrame:
@brief Returns an array of all items in the receiver for the specified
reference frame.
@discussion The elements in the returned array are not copied before they are
returned so be aware that mutations to any of the returned
objects will be reflected in the receiver.
@return An array of all items in the receiver.
*/
- (NSArray *)allItemsInReferenceFrame:(MPReferenceFrame)referenceFrame;
/*!
@method elementAtIndexPath:
@brief Returns the element at the specified index path.
@discussion This method @em walks down the expression tree (including
functions) using the specified index path and finds the
corresponding element. The returned object can be an @c NSString,
a @c MPFunction or an @c MPExpression depending on the element @c
indexPath points to. If any of the indexes exceed the bounds of
the respective receiver an @c NSRangeException is raised.
If the index path does not contain any indexes the receiver
itself is returned.
@param indexPath
The index path the required object is located at. The indexes are
expressed in the element reference frame.
@return The element located at @c indexPath. The element is not copied
before it is returned. Be aware of the fact that any mutations
made to the returned object are reflected in the receiver.
*/
- (id)elementAtIndexPath:(NSIndexPath *)indexPath;
/*!
@method convertIndex:fromReferenceFrame:toReferenceFrame:
@brief Converts an index from one reference frame to another.
@discussion This method ignores any offsets into items the conversion between
reference frames can cause. If you are interested in the offset
use @c -convertIndex:fromReferenceFrame:toReferenceFrame:offset:
instead.
@param anIndex
The index to be converted.
@param fromReferenceFrame
The reference frame @c anIndex is specified in.
@param toReferenceFrame
The reference frame @c anIndex should be converted to.
@return An index specified in the @c toReferenceFrame. If @c anIndex
specifies a location inside an item in the @c toReferenceFrame
the index of the corresponding item is returned.
*/
- (NSUInteger)convertIndex:(NSUInteger)anIndex
fromReferenceFrame:(MPReferenceFrame)fromReferenceFrame
toReferenceFrame:(MPReferenceFrame)toReferenceFrame;
/*!
@method convertIndex:fromReferenceFrame:toReferenceFrame:offset:
@brief Converts an index from one reference frame to another.
@discussion If @c anIndex specifies a location inside an item in the @c
toReferenceFrame the index of the corresponding item is returned.
@param anIndex
The index to be converted.
@param fromReferenceFrame
The reference frame @c anIndex is specified in.
@param toReferenceFrame
The reference frame @c anIndex should be converted to.
@param offset
This output parameter will be set to the number of symbols that
are between the location specified by @c anIndex and the index
that is actually returned. The offset is specified in the symbol
reference frame. If you are not interested in the offset pass
@c NULL.
@return An index specified in the @c toReferenceFrame corresponding to
@c anIndex.
*/
- (NSUInteger)convertIndex:(NSUInteger)anIndex
fromReferenceFrame:(MPReferenceFrame)fromReferenceFrame
toReferenceFrame:(MPReferenceFrame)toReferenceFrame
offset:(out NSUInteger *)offset;
/*!
@method convertRange:fromReferenceFrame:toReferenceFrame:
@brief Converts a range from one reference frame to another.
@discussion This method just converts the location and target of the range
separately using @c
-convertIndex:fromReferenceFrame:toReferenceFrame:. This method
ensures that the returned range definitely includes all items
that were specified by @c aRange.
This method ignores the possibility that the returned range may
include more than @a aRange. If you need that information use
@c -convertRange:fromReferenceFrame:toReferenceFrame:leadingOffset:trailingOffset:.
@param aRange
The range to be converted.
@param fromReferenceFrame
The reference frame @c aRange is specified in.
@param toReferenceFrame
The reference frame @c aRange is to be converted to.
@return A range in the @c toReferenceFrame that includes the the items
specified by @c aRange.
*/
- (NSRange)convertRange:(NSRange)aRange
fromReferenceFrame:(MPReferenceFrame)fromReferenceFrame
toReferenceFrame:(MPReferenceFrame)toReferenceFrame;
/*!
@method convertRange:fromReferenceFrame:toReferenceFrame:leadingOffset:trailingOffset:
@brief Converts a range from one reference frame to another.
@discussion This method just converts the location and target of the range
separately using @c
-convertIndex:fromReferenceFrame:toReferenceFrame:. This method
ensures that the returned range definitely includes all items
that were specified by @c aRange.
@param aRange
The range to be converted.
@param fromReferenceFrame
The reference frame @c aRange is specified in.
@param toReferenceFrame
The reference frame @c aRange is to be converted to.
@param leadingOffset
The offset of the location of the returned range in respect to
the location of @c aRange.
@param trailingOffset
The offset of the last index in the range in respect to the last
index of @c aRange.
@return A range in the @c toReferenceFrame that includes the the items
specified by @c aRange.
*/
- (NSRange)convertRange:(NSRange)aRange
fromReferenceFrame:(MPReferenceFrame)fromReferenceFrame
toReferenceFrame:(MPReferenceFrame)toReferenceFrame
leadingOffset:(NSUInteger *)leadingOffset
trailingOffset:(NSUInteger *)trailingOffset;
#pragma mark Mutating Expressions
/*!
@methodgroup Mutating Expressions
*/
/*!
@method replaceItemsInRange:referenceFrame:withElements:
@brief Replaces the elements in the specified range with the contents of
the @c elements array.
@discussion This is the most primitive mutation method of @c MPExpression.
Every other mutating method utlimately must call this method.
After the receiver has been mutated the integrety of the receiver
is restored. That basically means that subsequent strings are
joined and empty strings removed. After restoring integrity the
receiver sends a @c
-changedElementsInIndexedRangePath:replacementLength: to
itself. For more information see the documentation on that
method.
@param aRange
The @c range of symbols (including functions) to replace.
@param referenceFrame
The reference frame @c aRange is specified in.
@param elements
The elements that should replace the symbols specified by @c
range.
*/
- (void)replaceItemsInRange:(NSRange)aRange
referenceFrame:(MPReferenceFrame)referenceFrame
withElements:(NSArray *)elements;
/*!
@method changedElementsInRangePath:replacementLength:
@brief Called after the receiver has been mutated.
@discussion This method does nothing more than notify it's parent that it has
been mutated at the receiver's index. If you need to know about
changes in an expression you should override this method instead
of @c -replaceSymbolsInRange:withElements: because this method
gives you information about the number of elements changed during
the mutation.
@param rangePath
The range path at which the receiver was changed starting at the
receiver. The range addressed by @c rangePath is expressed in the
element reference frame.
@param replacementLength
The number of elements replacing the elements specified by @c
rangePath (also specified in the element reference frame).
*/
- (void)changedElementsInRangePath:(MPRangePath *)rangePath
replacementLength:(NSUInteger)replacementLength;
/*!
@method subexpressionFromIndex:referenceFrame:
@brief Creates an expression from the items in the receiver from the
specified index to the end.
@discussion The items from the receiver are copied. Mutations to the returned
expression will not change the receiver.
@param from
The index from which to start constructing the subexpression.
@param referenceFrame
The reference frame @c from is specified in.
@return An expression containing the items from the specified index to
the end of the receiver.
*/
- (MPExpression *)subexpressionFromIndex:(NSUInteger)from
referenceFrame:(MPReferenceFrame)referenceFrame;
/*!
@method subexpressionToIndex:referenceFrame:
@brief Creates an expression from the items in the receiver from the
first item to the end.
@discussion The items from the receiver are copied. Mutations to the returned
expression will not change the receiver.
@param to
The index of the first element not to include in the newly
constructed subexpression.
@param referenceFrame
The reference frame @c to is specified in.
@return An expression containing the items from the first item to the one
at the specified index.
*/
- (MPExpression *)subexpressionToIndex:(NSUInteger)to
referenceFrame:(MPReferenceFrame)referenceFrame;
/*!
@method subexpressionWithRange:referenceFrame:
@brief Creates an expression from the items in the receiver within the
specified range.
@discussion The items from the receiver are copied. Mutations to the returned
expression will not change the receiver.
@param aRange
Specifies the items to be included in the newly created
subexpression.
@param referenceFrame
The reference frame @c aRange is specified in.
@return An expression containing the items in @c aRange.
*/
- (MPExpression *)subexpressionWithRange:(NSRange)aRange
referenceFrame:(MPReferenceFrame)referenceFrame;
#pragma mark Evaluating Expressions
/*!
@methodgroup Evaluating Expressions
*/
/*!
@method evaluateWitErrors:
@brief Evaluates the receiver.
@discussion This is a convenience method for evaluating an expression. If you
want more control over the evaluation process use @c -parse
instead.
@param errors
If the receiver (or any of its elements) contain syntax errors or
can not be evaluated this parameter is set to an appropriate
value. All items in the array are @c NSError instances. This
parameter is never set to an empty array.
Pass @c NULL if you are not interested in any errors that might
occur.
@return The result of the evaluation or @c nil of the receiver could not
be evaluated. In that case the @c error parameter is set to an
appropriate value.
*/
- (NSDecimalNumber *)evaluateWithErrors:(NSArray *__autoreleasing *)errors;
/*!
@method parse:
@brief Parses the receiver.
@discussion This is a convenience method that calls @c
-parseExpectingVariable:errors: with @c NO as the first argument.
@param errors
If the receiver (or any of its elements) contain syntax errors
this parameter is set to an appropriate value. All items in the
array are @c NSError instances. This parameter is never set to an
empty array.
Pass @c NULL if you are not interested in any errors that might
occur.
@return A @c MPParsedExpression object that represents the receiver and
can be evaluated or @c nil if an error occurs. In that case the
@c errors parameter is set to an array containing at least one
@c NSError instance.
*/
- (MPParsedExpression *)parse:(NSArray *__autoreleasing *)errors;
/*!
@method parseExpectingVariable:errors:
@brief Parses the receiver.
@param flag
If @c YES the receiver must (exept for whitespaces) begin with a
single letter followed by an equals sign. If it doesn't the
expression is considered invalid. Specify @c NO If the expression
should be evaluatable by itself.
@param errors
If the receiver (or any of its elements) contain syntax errors
this parameter is set to an appropriate value. All items in the
array are @c NSError instances. This parameter is never set to an
empty array.
Pass @c NULL if you are not interested in any errors that might
occur.
@return A @c MPParsedExpression object that represents the receiver and
can be evaluated or @c nil if an error occurs. In that case the
@c errors parameter is set to an array containing at least one
@c NSError instance.
*/
- (MPParsedExpression *)parseExpectingVariable:(BOOL)flag
errors:(NSArray *__autoreleasing *)errors;
@end
/*!
@category MPExpression (MPExpressionConvenience)
@brief This category defines convenience methods for the @c MPExpression
class.
@discussion All convenience methods are completely defined in terms of other
methods of the @c MPExpression class.
*/
@interface MPExpression (MPExpressionConvenience)
#pragma mark Querying Expressions
/*!
@methodgroup Querying Expressions
*/
/*!
@method countElements
@brief Returns the number of elements in the receiver.
@return The number of elements in the receiver expressed in the element
reference frame.
*/
- (NSUInteger)countElements;
/*!
@method countSymbols
@brief Returns the number of symbols in the receiver.
@return The number of symbols in the receiver expressed in the symbol
reference frame.
*/
- (NSUInteger)countSymbols;
/*!
@method countTokens
@brief Returns the number of tokens in the receiver.
@return The number of tokens in the receiver expressed in the token
reference frame.
*/
- (NSUInteger)countTokens;
/*!
@method elementAtIndex:
@brief Returns the element at the specified index.
@param anIndex
The index of the element specified in the element reference
frame.
@return The element at @c anIndex.
*/
- (id)elementAtIndex:(NSUInteger)anIndex;
/*!
@method symbolAtIndex:
@brief Returns the symbol at the specified index.
@param anIndex
The index of the symbol specified in the symbol reference frame.
@return The symbol at @c anIndex.
*/
- (id)symbolAtIndex:(NSUInteger)anIndex;
/*!
@method tokenAtIndex:
@brief Returns the token at the specified index.
@param anIndex
The index of the token specified in the token reference frame.
@return The token at @c anIndex.
*/
- (id)tokenAtIndex:(NSUInteger)anIndex;
#pragma mark Mutating Expressions
/*!
@methodgroup Mutating Expressions
*/
/*!
@method appendElement:
@brief Appends @c anElement to the receiver.
@param anElement
The element to append to the receiver.
*/
- (void)appendElement:(id)anElement;
/*!
@method appendElements:
@brief Appends the objects from @c elements to the receiver.
@param elements
The elements to append to the receiver.
*/
- (void)appendElements:(NSArray *)elements;
/*!
@method insertElement:atIndex:referenceFrame:
@brief Inserts @c anElement at the specified index.
@param anElement
The element to be inserted.
@param index
The index where to insert @c anElement.
@param referenceFrame
The reference frame @c index is specified in.
*/
- (void)insertElement:(id)anElement
atIndex:(NSUInteger)index
referenceFrame:(MPReferenceFrame)referenceFrame;
/*!
@method insertElements:atIndex:referenceFrame:
@brief Inserts @c elements at the specified index.
@param elements
The elements to be inserted.
@param index
The index where to insert @c elements.
@param referenceFrame
The reference frame @c index is specified in.
*/
- (void)insertElements:(NSArray *)elements
atIndex:(NSUInteger)index
referenceFrame:(MPReferenceFrame)referenceFrame;
/*!
@method deleteElementsInRange:
@brief Removes the elements specified by @c range from the receiver.
@param range
The range of items to remove from the receiver.
@param referenceFrame
The reference frame @c range is specified in.
*/
- (void)deleteElementsInRange:(NSRange)range
referenceFrame:(MPReferenceFrame)referenceFrame;
@end