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



@class MPToken;
@protocol MPToken;


/*!
    @typedef    MPTokenType
    @brief      The type of a <code>token</code> identifies its behaviour in a mathematical
                context.
 
    @constant   MPEOFToken
                A token that represents the end of the input. This token should
                not be used to create a @c MPToken instance. It exists so that
                you can safely send a @c tokenType message to @c nil without
                getting confusing results. A token with this token type should be
                interpreted as 'no token'.
 
    @constant   MPMultiplicationSymbolToken
                A multiplication symbol.
 
    @constant   MPOperatorListToken
                A list of operators (+ and - symbols). The token may be longer
                than the number of operators if there are spaces between them.

    @constant   MPElementaryFunction
                @em Most elementary functions are represented by this token type.
                Elementary functions not categorized as such are those that can
                not be represented as text (e.g. roots and powers).
 
    @constant   MPNumberToken
                A number. This may be an integer or a floating point number.
                Floating point numbers contain a @c NSLocaleDecimalSeparator.
 
    @constant   MPVariableToken
                A variable. A variable is exactly one character long.
 
    @constant   MPFactorialToken
                The factorial symbol (!).
 
    @constant   MPEqualsToken
                The equals sign.
 
    @constant   MPGenericFunctionToken
                A function represented by the @c MPFunction class. A token with
                this token type is guaranteed to be a @c MPFunction instance.
 
    @constant   MPWhitespaceToken
                A whitespace. This token can typically be ignored.

    @constant   MPUnidentifiedToken
                Any symbol that does not match any other token.
 */
typedef NS_ENUM(NSUInteger, MPTokenType) {
    MPEOFToken = 0,
    MPMultiplicationSymbolToken,
    MPOperatorListToken,
    MPElementaryFunctionToken,
    MPNumberToken,
    MPDeformedNumberToken,
    MPVariableToken,
    MPEqualsToken,
    MPFactorialToken,
    MPPowerToken,
    MPGenericFunctionToken,
    
    MPWhitespaceToken,
    MPUnidentifiedToken,
};



/*!
    @protocol   MPToken
    @brief      Tokens represent logical units in an expresion.
 */
@protocol MPToken <NSObject>


/*!
    @method     tokenType
    @brief      Returns the receiver's token type.
 
    @discussion The token type identifies what kind of token the receiver is. For
                more information see the documentation on the <code>MPTokenType
                </code> enum.
 
    @return     The receiver's token type.
 */
- (MPTokenType)tokenType;


/*!
    @method     range
    @brief      Returns the receiver's range.
 
    @discussion The range identifies where the token is in the expression. It is
                specified in the symbol reference frame.
 
    @return     The range the token occupies in the expression it was parsed
                from specified in the symbol reference frame.
 */
- (NSRange)range;


/*!
    @method     stringValue
    @brief      The string that caused the token to be parsed.
 
    @discussion Depending on the type of the token the string value can have a
                fixed or variable length. For example the equals token always has
                a length of @c 1 whereas a number or whitespace token can be much
                longer.
 
    @return     The receiver's string value.
 */
- (NSString *)stringValue;

@end



/*!
    @class      MPToken
    @brief      The @c MPToken class implements the functionality of the @c
                MPToken protocol. Most tokens are instances of the @c MPToken
                class.
 */
@interface MPToken : NSObject <MPToken>


/*!
    @method     initWithTokenType:range:stringValue:
    @brief      Creates a new @c MPToken instance.
 
    @param      tokenType
                The type of the token.
 
    @param      range
                The range of the token in the expression. Specified in the symbol
                reference frame.
 
    @param      input
                The string value of the token.
 
    @return     A newly initialized token.
 */
- (instancetype)initWithTokenType:(MPTokenType)tokenType
                            range:(NSRange)range
                      stringValue:(NSString *)input; /* designated initializer */

@end