michael@0: /*
michael@0: **********************************************************************
michael@0: * Copyright (c) 2003-2011, International Business Machines
michael@0: * Corporation and others.  All Rights Reserved.
michael@0: **********************************************************************
michael@0: * Author: Alan Liu
michael@0: * Created: September 24 2003
michael@0: * Since: ICU 2.8
michael@0: **********************************************************************
michael@0: */
michael@0: #ifndef _RULEITER_H_
michael@0: #define _RULEITER_H_
michael@0: 
michael@0: #include "unicode/uobject.h"
michael@0: 
michael@0: U_NAMESPACE_BEGIN
michael@0: 
michael@0: class UnicodeString;
michael@0: class ParsePosition;
michael@0: class SymbolTable;
michael@0: 
michael@0: /**
michael@0:  * An iterator that returns 32-bit code points.  This class is deliberately
michael@0:  * <em>not</em> related to any of the ICU character iterator classes
michael@0:  * in order to minimize complexity.
michael@0:  * @author Alan Liu
michael@0:  * @since ICU 2.8
michael@0:  */
michael@0: class RuleCharacterIterator : public UMemory {
michael@0: 
michael@0:     // TODO: Ideas for later.  (Do not implement if not needed, lest the
michael@0:     // code coverage numbers go down due to unused methods.)
michael@0:     // 1. Add a copy constructor, operator==() method.
michael@0:     // 2. Rather than return DONE, throw an exception if the end
michael@0:     // is reached -- this is an alternate usage model, probably not useful.
michael@0: 
michael@0: private:
michael@0:     /**
michael@0:      * Text being iterated.
michael@0:      */    
michael@0:     const UnicodeString& text;
michael@0: 
michael@0:     /**
michael@0:      * Position of iterator.
michael@0:      */
michael@0:     ParsePosition& pos;
michael@0: 
michael@0:     /**
michael@0:      * Symbol table used to parse and dereference variables.  May be 0.
michael@0:      */
michael@0:     const SymbolTable* sym;
michael@0:     
michael@0:     /**
michael@0:      * Current variable expansion, or 0 if none.
michael@0:      */
michael@0:     const UnicodeString* buf;
michael@0: 
michael@0:     /**
michael@0:      * Position within buf.  Meaningless if buf == 0.
michael@0:      */
michael@0:     int32_t bufPos;
michael@0: 
michael@0: public:
michael@0:     /**
michael@0:      * Value returned when there are no more characters to iterate.
michael@0:      */
michael@0:     enum { DONE = -1 };
michael@0: 
michael@0:     /**
michael@0:      * Bitmask option to enable parsing of variable names.  If (options &
michael@0:      * PARSE_VARIABLES) != 0, then an embedded variable will be expanded to
michael@0:      * its value.  Variables are parsed using the SymbolTable API.
michael@0:      */
michael@0:     enum { PARSE_VARIABLES = 1 };
michael@0: 
michael@0:     /**
michael@0:      * Bitmask option to enable parsing of escape sequences.  If (options &
michael@0:      * PARSE_ESCAPES) != 0, then an embedded escape sequence will be expanded
michael@0:      * to its value.  Escapes are parsed using Utility.unescapeAt().
michael@0:      */
michael@0:     enum { PARSE_ESCAPES   = 2 };
michael@0: 
michael@0:     /**
michael@0:      * Bitmask option to enable skipping of whitespace.  If (options &
michael@0:      * SKIP_WHITESPACE) != 0, then Pattern_White_Space characters will be silently
michael@0:      * skipped, as if they were not present in the input.
michael@0:      */
michael@0:     enum { SKIP_WHITESPACE = 4 };
michael@0: 
michael@0:     /**
michael@0:      * Constructs an iterator over the given text, starting at the given
michael@0:      * position.
michael@0:      * @param text the text to be iterated
michael@0:      * @param sym the symbol table, or null if there is none.  If sym is null,
michael@0:      * then variables will not be deferenced, even if the PARSE_VARIABLES
michael@0:      * option is set.
michael@0:      * @param pos upon input, the index of the next character to return.  If a
michael@0:      * variable has been dereferenced, then pos will <em>not</em> increment as
michael@0:      * characters of the variable value are iterated.
michael@0:      */
michael@0:     RuleCharacterIterator(const UnicodeString& text, const SymbolTable* sym,
michael@0:                           ParsePosition& pos);
michael@0:     
michael@0:     /**
michael@0:      * Returns true if this iterator has no more characters to return.
michael@0:      */
michael@0:     UBool atEnd() const;
michael@0: 
michael@0:     /**
michael@0:      * Returns the next character using the given options, or DONE if there
michael@0:      * are no more characters, and advance the position to the next
michael@0:      * character.
michael@0:      * @param options one or more of the following options, bitwise-OR-ed
michael@0:      * together: PARSE_VARIABLES, PARSE_ESCAPES, SKIP_WHITESPACE.
michael@0:      * @param isEscaped output parameter set to TRUE if the character
michael@0:      * was escaped
michael@0:      * @param ec input-output error code.  An error will only be set by
michael@0:      * this routing if options includes PARSE_VARIABLES and an unknown
michael@0:      * variable name is seen, or if options includes PARSE_ESCAPES and
michael@0:      * an invalid escape sequence is seen.
michael@0:      * @return the current 32-bit code point, or DONE
michael@0:      */
michael@0:     UChar32 next(int32_t options, UBool& isEscaped, UErrorCode& ec);
michael@0: 
michael@0:     /**
michael@0:      * Returns true if this iterator is currently within a variable expansion.
michael@0:      */
michael@0:     inline UBool inVariable() const;
michael@0: 
michael@0:     /**
michael@0:      * An opaque object representing the position of a RuleCharacterIterator.
michael@0:      */
michael@0:     struct Pos : public UMemory {
michael@0:     private:
michael@0:         const UnicodeString* buf;
michael@0:         int32_t pos;
michael@0:         int32_t bufPos;
michael@0:         friend class RuleCharacterIterator;
michael@0:     };
michael@0: 
michael@0:     /**
michael@0:      * Sets an object which, when later passed to setPos(), will
michael@0:      * restore this iterator's position.  Usage idiom:
michael@0:      *
michael@0:      * RuleCharacterIterator iterator = ...;
michael@0:      * RuleCharacterIterator::Pos pos;
michael@0:      * iterator.getPos(pos);
michael@0:      * for (;;) {
michael@0:      *   iterator.getPos(pos);
michael@0:      *   int c = iterator.next(...);
michael@0:      *   ...
michael@0:      * }
michael@0:      * iterator.setPos(pos);
michael@0:      *
michael@0:      * @param p a position object to be set to this iterator's
michael@0:      * current position.
michael@0:      */
michael@0:     void getPos(Pos& p) const;
michael@0: 
michael@0:     /**
michael@0:      * Restores this iterator to the position it had when getPos()
michael@0:      * set the given object.
michael@0:      * @param p a position object previously set by getPos()
michael@0:      */
michael@0:     void setPos(const Pos& p);
michael@0: 
michael@0:     /**
michael@0:      * Skips ahead past any ignored characters, as indicated by the given
michael@0:      * options.  This is useful in conjunction with the lookahead() method.
michael@0:      *
michael@0:      * Currently, this only has an effect for SKIP_WHITESPACE.
michael@0:      * @param options one or more of the following options, bitwise-OR-ed
michael@0:      * together: PARSE_VARIABLES, PARSE_ESCAPES, SKIP_WHITESPACE.
michael@0:      */
michael@0:     void skipIgnored(int32_t options);
michael@0: 
michael@0:     /**
michael@0:      * Returns a string containing the remainder of the characters to be
michael@0:      * returned by this iterator, without any option processing.  If the
michael@0:      * iterator is currently within a variable expansion, this will only
michael@0:      * extend to the end of the variable expansion.  This method is provided
michael@0:      * so that iterators may interoperate with string-based APIs.  The typical
michael@0:      * sequence of calls is to call skipIgnored(), then call lookahead(), then
michael@0:      * parse the string returned by lookahead(), then call jumpahead() to
michael@0:      * resynchronize the iterator.
michael@0:      * @param result a string to receive the characters to be returned
michael@0:      * by future calls to next()
michael@0:      * @param maxLookAhead The maximum to copy into the result.
michael@0:      * @return a reference to result
michael@0:      */
michael@0:     UnicodeString& lookahead(UnicodeString& result, int32_t maxLookAhead = -1) const;
michael@0: 
michael@0:     /**
michael@0:      * Advances the position by the given number of 16-bit code units.
michael@0:      * This is useful in conjunction with the lookahead() method.
michael@0:      * @param count the number of 16-bit code units to jump over
michael@0:      */
michael@0:     void jumpahead(int32_t count);
michael@0: 
michael@0:     /**
michael@0:      * Returns a string representation of this object, consisting of the
michael@0:      * characters being iterated, with a '|' marking the current position.
michael@0:      * Position within an expanded variable is <em>not</em> indicated.
michael@0:      * @param result output parameter to receive a string
michael@0:      * representation of this object
michael@0:      */
michael@0: //    UnicodeString& toString(UnicodeString& result) const;
michael@0:     
michael@0: private:
michael@0:     /**
michael@0:      * Returns the current 32-bit code point without parsing escapes, parsing
michael@0:      * variables, or skipping whitespace.
michael@0:      * @return the current 32-bit code point
michael@0:      */
michael@0:     UChar32 _current() const;
michael@0:     
michael@0:     /**
michael@0:      * Advances the position by the given amount.
michael@0:      * @param count the number of 16-bit code units to advance past
michael@0:      */
michael@0:     void _advance(int32_t count);
michael@0: };
michael@0: 
michael@0: inline UBool RuleCharacterIterator::inVariable() const {
michael@0:     return buf != 0;
michael@0: }
michael@0: 
michael@0: U_NAMESPACE_END
michael@0: 
michael@0: #endif // _RULEITER_H_
michael@0: //eof