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