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



@class MPTokenStream;
@protocol MPToken;


/*!
    @class      MPTokenStream
    @brief      This class is a helper class for processing tokens from the
                beginning of an expression to the end.
 
    @discussion A token stream is a single-use object. After the stream has
                reached the end there is no way to reset it.
 */
@interface MPTokenStream : NSObject


/*!
    @method     initWithTokens:
    @brief      Creates a new token stream that @em streams the contents of the
            	@c tokens array.
 
    @param      tokens
                The tokens to be @em streamed. All objects in the array must
                conform to the @c MPToken protocol.
 
    @return     A new token stream.
 */
- (instancetype)initWithTokens:(NSArray *)tokens; /* designated initializer */


/*!
    @method     beginIgnoringWhitespaceTokens
    @brief      After calling this method a @c -currentToken message will skip
                whitespace characters before returning the current token.
 
    @discussion Any call to this method or @c -beginAcceptingWhitespaceTokens
                must be matched by a @c -endIgnoringOrAcceptingWhitespaceTokens
                message. Calls to both methods can be nested.
 
                By default whitespace tokens are accepted.
 
    @see        -beginAcceptingWhitespaceTokens
    @see        -endIgnoringOrAcceptingWhitespaceTokens
 */
- (void)beginIgnoringWhitespaceTokens;


/*!
    @method     beginAcceptingWhitespaceTokens
    @brief      After calling this method @c -currentToken may return a token of
                type @c MPWhitespaceToken.
 
    @discussion Any call to this method or @c -beginAcceptingWhitespaceTokens
                must be matched by a @c -endIgnoringOrAcceptingWhitespaceTokens
                message. Calls to both methods can be nested.
 
                By default whitespace tokens are accepted.
 
    @see        -beginIgnoringWhitespaceTokens
    @see        -endIgnoringOrAcceptingWhitespaceTokens
 */
- (void)beginAcceptingWhitespaceTokens;


/*!
    @method     endIgnoringOrAcceptingWhitespaceTokens
    @brief      This method balances @c -beginIgnoringWhitespaceTokens and @c
                -beginAcceptingWhitespaceTokens messages.
 
    @discussion After this method was
                calles the whitespace behaviour falls back to the way it behaved
                before the last @c -beginIgnoringWhitespaceTokens or @c
                -beginAcceptingWhitespaceTokens message was sent.
 */
- (void)endIgnoringOrAcceptingWhitespaceTokens;



/*!
    @method     hasMoreTokens
    @brief      Use this method to check wether there are any tokens left.
 
    @discussion This method repects the whitespace skipping behaviour. That means
                that if the token stream currently ignores whitespaces and there
                are only whitespaces left in the stream this method returns @c
                NO.
 
    @return     @c YES if there are more tokens, @c NO otherwise.
 */
- (BOOL)hasMoreTokens;


/*!
    @method     currentToken
    @brief      Returns the receiver's current token.
 
    @discussion This is one of the core methods of @c MPTokenStream. Subsequent
                calls to this method will return the same value until @c
                -currentTokenConsumed is called.
 
    @return     The current token or @c nil if there are no more tokens.
 */
- (id<MPToken>)currentToken;


/*!
    @method     peekNextToken
    @brief      Looks at the next token and returns it.
 
    @discussion This method behaves as if you called @c -currentTokenConsumed
                followed by @c -currentToken except that it does not consume the
                current token. That means that you can use this method to look at
                the next token (respecting the current whitespace ignoring
                behaviour) without changing the @c currentToken.

    @return     The next token or @c nil if there is no token after the current
                one.
 */
- (id<MPToken>)peekNextToken;


/*!
    @method     currentTokenConsumed
    @brief      Marks the current token as consumed and discards it.
 */
- (void)currentTokenConsumed;

@end