/*

 **********************************************************************

 * Copyright (c) 2003-2005, International Business Machines

 * Corporation and others.  All Rights Reserved.

 **********************************************************************

 * Author: Alan Liu

 * Created: September 24 2003

 * Since: ICU 2.8

 **********************************************************************

 */

 #ifndef _RULEITER_H_

 #define _RULEITER_H_

 #include "unicode/utypes.h"

 U_NAMESPACE_BEGIN

 class UnicodeString;

 class ParsePosition;

 class SymbolTable;

 /**

  * An iterator that returns 32-bit code points.  This class is deliberately

  * <em>not</em> related to any of the ICU character iterator classes

  * in order to minimize complexity.

  * @author Alan Liu

  * @since ICU 2.8

  */

 class U_COMMON_API RuleCharacterIterator {

     // TODO: Ideas for later.  (Do not implement if not needed, lest the

     // code coverage numbers go down due to unused methods.)

     // 1. Add a copy constructor, operator==() method.

     // 2. Rather than return DONE, throw an exception if the end

     // is reached -- this is an alternate usage model, probably not useful.

 private:

     /**

      * Text being iterated.

      */    

     const UnicodeString& text;

     /**

      * Position of iterator.

      */

     ParsePosition& pos;

     /**

      * Symbol table used to parse and dereference variables.  May be 0.

      */

     const SymbolTable* sym;

     /**

      * Current variable expansion, or 0 if none.

      */

     const UnicodeString* buf;

     /**

      * Position within buf.  Meaningless if buf == 0.

      */

     int32_t bufPos;

 public:

     /**

      * Value returned when there are no more characters to iterate.

      */

     enum { DONE = -1 };

     /**

      * Bitmask option to enable parsing of variable names.  If (options &

      * PARSE_VARIABLES) != 0, then an embedded variable will be expanded to

      * its value.  Variables are parsed using the SymbolTable API.

      */

     enum { PARSE_VARIABLES = 1 };

     /**

      * Bitmask option to enable parsing of escape sequences.  If (options &

      * PARSE_ESCAPES) != 0, then an embedded escape sequence will be expanded

      * to its value.  Escapes are parsed using Utility.unescapeAt().

      */

     enum { PARSE_ESCAPES   = 2 };

     /**

      * Bitmask option to enable skipping of whitespace.  If (options &

      * SKIP_WHITESPACE) != 0, then whitespace characters will be silently

      * skipped, as if they were not present in the input.  Whitespace

      * characters are defined by UCharacterProperty.isRuleWhiteSpace().

      */

     enum { SKIP_WHITESPACE = 4 };

     /**

      * Constructs an iterator over the given text, starting at the given

      * position.

      * @param text the text to be iterated

      * @param sym the symbol table, or null if there is none.  If sym is null,

      * then variables will not be deferenced, even if the PARSE_VARIABLES

      * option is set.

      * @param pos upon input, the index of the next character to return.  If a

      * variable has been dereferenced, then pos will <em>not</em> increment as

      * characters of the variable value are iterated.

      */

     RuleCharacterIterator(const UnicodeString& text, const SymbolTable* sym,

                           ParsePosition& pos);

     /**

      * Returns true if this iterator has no more characters to return.

      */

     UBool atEnd() const;

     /**

      * Returns the next character using the given options, or DONE if there

      * are no more characters, and advance the position to the next

      * character.

      * @param options one or more of the following options, bitwise-OR-ed

      * together: PARSE_VARIABLES, PARSE_ESCAPES, SKIP_WHITESPACE.

      * @param isEscaped output parameter set to TRUE if the character

      * was escaped

      * @param ec input-output error code.  An error will only be set by

      * this routing if options includes PARSE_VARIABLES and an unknown

      * variable name is seen, or if options includes PARSE_ESCAPES and

      * an invalid escape sequence is seen.

      * @return the current 32-bit code point, or DONE

      */

     UChar32 next(int32_t options, UBool& isEscaped, UErrorCode& ec);

     /**

      * Returns true if this iterator is currently within a variable expansion.

      */

     inline UBool inVariable() const;

     /**

      * An opaque object representing the position of a RuleCharacterIterator.

      */

     struct Pos {

     private:

         const UnicodeString* buf;

         int32_t pos;

         int32_t bufPos;

         friend class RuleCharacterIterator;

     };

     /**

      * Sets an object which, when later passed to setPos(), will

      * restore this iterator's position.  Usage idiom:

      *

      * RuleCharacterIterator iterator = ...;

      * RuleCharacterIterator::Pos pos;

      * iterator.getPos(pos);

      * for (;;) {

      *   iterator.getPos(pos);

      *   int c = iterator.next(...);

      *   ...

      * }

      * iterator.setPos(pos);

      *

      * @param p a position object to be set to this iterator's

      * current position.

      */

     void getPos(Pos& p) const;

     /**

      * Restores this iterator to the position it had when getPos()

      * set the given object.

      * @param p a position object previously set by getPos()

      */

     void setPos(const Pos& p);

     /**

      * Skips ahead past any ignored characters, as indicated by the given

      * options.  This is useful in conjunction with the lookahead() method.

      *

      * Currently, this only has an effect for SKIP_WHITESPACE.

      * @param options one or more of the following options, bitwise-OR-ed

      * together: PARSE_VARIABLES, PARSE_ESCAPES, SKIP_WHITESPACE.

      */

     void skipIgnored(int32_t options);

     /**

      * Returns a string containing the remainder of the characters to be

      * returned by this iterator, without any option processing.  If the

      * iterator is currently within a variable expansion, this will only

      * extend to the end of the variable expansion.  This method is provided

      * so that iterators may interoperate with string-based APIs.  The typical

      * sequence of calls is to call skipIgnored(), then call lookahead(), then

      * parse the string returned by lookahead(), then call jumpahead() to

      * resynchronize the iterator.

      * @param result a string to receive the characters to be returned

      * by future calls to next()

      * @return a reference to result

      */

     UnicodeString& lookahead(UnicodeString& result) const;

     /**

      * Advances the position by the given number of 16-bit code units.

      * This is useful in conjunction with the lookahead() method.

      * @param count the number of 16-bit code units to jump over

      */

     void jumpahead(int32_t count);

     /**

      * Returns a string representation of this object, consisting of the

      * characters being iterated, with a '|' marking the current position.

      * Position within an expanded variable is <em>not</em> indicated.

      * @param result output parameter to receive a string

      * representation of this object

      */

 //    UnicodeString& toString(UnicodeString& result) const;

 private:

     /**

      * Returns the current 32-bit code point without parsing escapes, parsing

      * variables, or skipping whitespace.

      * @return the current 32-bit code point

      */

     UChar32 _current() const;

     /**

      * Advances the position by the given amount.

      * @param count the number of 16-bit code units to advance past

      */

     void _advance(int32_t count);

 };

 inline UBool RuleCharacterIterator::inVariable() const {

     return buf != 0;

 }

 U_NAMESPACE_END

 #endif // _RULEITER_H_

 //eof