1 /*

     2 **********************************************************************

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

     4 * Corporation and others.  All Rights Reserved.

     5 **********************************************************************

     6 * Author: Alan Liu

     7 * Created: September 24 2003

     8 * Since: ICU 2.8

     9 **********************************************************************

    10 */

    11 #ifndef _RULEITER_H_

    12 #define _RULEITER_H_

    13 

    14 #include "unicode/utypes.h"

    15 

    16 U_NAMESPACE_BEGIN

    17 

    18 class UnicodeString;

    19 class ParsePosition;

    20 class SymbolTable;

    21 

    22 /**

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

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

    25  * in order to minimize complexity.

    26  * @author Alan Liu

    27  * @since ICU 2.8

    28  */

    29 class U_COMMON_API RuleCharacterIterator {

    30 

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

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

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

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

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

    36 

    37 private:

    38     /**

    39      * Text being iterated.

    40      */    

    41     const UnicodeString& text;

    42 

    43     /**

    44      * Position of iterator.

    45      */

    46     ParsePosition& pos;

    47 

    48     /**

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

    50      */

    51     const SymbolTable* sym;

    52     

    53     /**

    54      * Current variable expansion, or 0 if none.

    55      */

    56     const UnicodeString* buf;

    57 

    58     /**

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

    60      */

    61     int32_t bufPos;

    62 

    63 public:

    64     /**

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

    66      */

    67     enum { DONE = -1 };

    68 

    69     /**

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

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

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

    73      */

    74     enum { PARSE_VARIABLES = 1 };

    75 

    76     /**

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

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

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

    80      */

    81     enum { PARSE_ESCAPES   = 2 };

    82 

    83     /**

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

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

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

    87      * characters are defined by UCharacterProperty.isRuleWhiteSpace().

    88      */

    89     enum { SKIP_WHITESPACE = 4 };

    90 

    91     /**

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

    93      * position.

    94      * @param text the text to be iterated

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

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

    97      * option is set.

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

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

   100      * characters of the variable value are iterated.

   101      */

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

   103                           ParsePosition& pos);

   104     

   105     /**

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

   107      */

   108     UBool atEnd() const;

   109 

   110     /**

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

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

   113      * character.

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

   115      * together: PARSE_VARIABLES, PARSE_ESCAPES, SKIP_WHITESPACE.

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

   117      * was escaped

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

   119      * this routing if options includes PARSE_VARIABLES and an unknown

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

   121      * an invalid escape sequence is seen.

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

   123      */

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

   125 

   126     /**

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

   128      */

   129     inline UBool inVariable() const;

   130 

   131     /**

   132      * An opaque object representing the position of a RuleCharacterIterator.

   133      */

   134     struct Pos {

   135     private:

   136         const UnicodeString* buf;

   137         int32_t pos;

   138         int32_t bufPos;

   139         friend class RuleCharacterIterator;

   140     };

   141 

   142     /**

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

   144      * restore this iterator's position.  Usage idiom:

   145      *

   146      * RuleCharacterIterator iterator = ...;

   147      * RuleCharacterIterator::Pos pos;

   148      * iterator.getPos(pos);

   149      * for (;;) {

   150      *   iterator.getPos(pos);

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

   152      *   ...

   153      * }

   154      * iterator.setPos(pos);

   155      *

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

   157      * current position.

   158      */

   159     void getPos(Pos& p) const;

   160 

   161     /**

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

   163      * set the given object.

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

   165      */

   166     void setPos(const Pos& p);

   167 

   168     /**

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

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

   171      *

   172      * Currently, this only has an effect for SKIP_WHITESPACE.

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

   174      * together: PARSE_VARIABLES, PARSE_ESCAPES, SKIP_WHITESPACE.

   175      */

   176     void skipIgnored(int32_t options);

   177 

   178     /**

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

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

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

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

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

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

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

   186      * resynchronize the iterator.

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

   188      * by future calls to next()

   189      * @return a reference to result

   190      */

   191     UnicodeString& lookahead(UnicodeString& result) const;

   192 

   193     /**

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

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

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

   197      */

   198     void jumpahead(int32_t count);

   199 

   200     /**

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

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

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

   204      * @param result output parameter to receive a string

   205      * representation of this object

   206      */

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

   208     

   209 private:

   210     /**

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

   212      * variables, or skipping whitespace.

   213      * @return the current 32-bit code point

   214      */

   215     UChar32 _current() const;

   216     

   217     /**

   218      * Advances the position by the given amount.

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

   220      */

   221     void _advance(int32_t count);

   222 };

   223 

   224 inline UBool RuleCharacterIterator::inVariable() const {

   225     return buf != 0;

   226 }

   227 

   228 U_NAMESPACE_END

   229 

   230 #endif // _RULEITER_H_

   231 //eof