RuleBasedTransliterator.
michael@0: * TransliterationRule is an immutable object.
michael@0: *
michael@0: * A rule consists of an input pattern and an output string. When michael@0: * the input pattern is matched, the output string is emitted. The michael@0: * input pattern consists of zero or more characters which are matched michael@0: * exactly (the key) and optional context. Context must match if it michael@0: * is specified. Context may be specified before the key, after the michael@0: * key, or both. The key, preceding context, and following context michael@0: * may contain variables. Variables represent a set of Unicode michael@0: * characters, such as the letters a through z. michael@0: * Variables are detected by looking up each character in a supplied michael@0: * variable list to see if it has been so defined. michael@0: * michael@0: *
A rule may contain segments in its input string and segment
michael@0: * references in its output string. A segment is a substring of the
michael@0: * input pattern, indicated by an offset and limit. The segment may
michael@0: * be in the preceding or following context. It may not span a
michael@0: * context boundary. A segment reference is a special character in
michael@0: * the output string that causes a segment of the input string (not
michael@0: * the input pattern) to be copied to the output string. The range of
michael@0: * special characters that represent segment references is defined by
michael@0: * RuleBasedTransliterator.Data.
michael@0: *
michael@0: * @author Alan Liu
michael@0: */
michael@0: class TransliterationRule : public UMemory {
michael@0:
michael@0: private:
michael@0:
michael@0: // TODO Eliminate the pattern and keyLength data members. They
michael@0: // are used only by masks() and getIndexValue() which are called
michael@0: // only during build time, not during run-time. Perhaps these
michael@0: // methods and pattern/keyLength can be isolated into a separate
michael@0: // object.
michael@0:
michael@0: /**
michael@0: * The match that must occur before the key, or null if there is no
michael@0: * preceding context.
michael@0: */
michael@0: StringMatcher *anteContext;
michael@0:
michael@0: /**
michael@0: * The matcher object for the key. If null, then the key is empty.
michael@0: */
michael@0: StringMatcher *key;
michael@0:
michael@0: /**
michael@0: * The match that must occur after the key, or null if there is no
michael@0: * following context.
michael@0: */
michael@0: StringMatcher *postContext;
michael@0:
michael@0: /**
michael@0: * The object that performs the replacement if the key,
michael@0: * anteContext, and postContext are matched. Never null.
michael@0: */
michael@0: UnicodeFunctor* output;
michael@0:
michael@0: /**
michael@0: * The string that must be matched, consisting of the anteContext, key,
michael@0: * and postContext, concatenated together, in that order. Some components
michael@0: * may be empty (zero length).
michael@0: * @see anteContextLength
michael@0: * @see keyLength
michael@0: */
michael@0: UnicodeString pattern;
michael@0:
michael@0: /**
michael@0: * An array of matcher objects corresponding to the input pattern
michael@0: * segments. If there are no segments this is null. N.B. This is
michael@0: * a UnicodeMatcher for generality, but in practice it is always a
michael@0: * StringMatcher. In the future we may generalize this, but for
michael@0: * now we sometimes cast down to StringMatcher.
michael@0: *
michael@0: * The array is owned, but the pointers within it are not.
michael@0: */
michael@0: UnicodeFunctor** segments;
michael@0:
michael@0: /**
michael@0: * The number of elements in segments[] or zero if segments is NULL.
michael@0: */
michael@0: int32_t segmentsCount;
michael@0:
michael@0: /**
michael@0: * The length of the string that must match before the key. If
michael@0: * zero, then there is no matching requirement before the key.
michael@0: * Substring [0,anteContextLength) of pattern is the anteContext.
michael@0: */
michael@0: int32_t anteContextLength;
michael@0:
michael@0: /**
michael@0: * The length of the key. Substring [anteContextLength,
michael@0: * anteContextLength + keyLength) is the key.
michael@0:
michael@0: */
michael@0: int32_t keyLength;
michael@0:
michael@0: /**
michael@0: * Miscellaneous attributes.
michael@0: */
michael@0: int8_t flags;
michael@0:
michael@0: /**
michael@0: * Flag attributes.
michael@0: */
michael@0: enum {
michael@0: ANCHOR_START = 1,
michael@0: ANCHOR_END = 2
michael@0: };
michael@0:
michael@0: /**
michael@0: * An alias pointer to the data for this rule. The data provides
michael@0: * lookup services for matchers and segments.
michael@0: */
michael@0: const TransliterationRuleData* data;
michael@0:
michael@0: public:
michael@0:
michael@0: /**
michael@0: * Construct a new rule with the given input, output text, and other
michael@0: * attributes. A cursor position may be specified for the output text.
michael@0: * @param input input string, including key and optional ante and
michael@0: * post context.
michael@0: * @param anteContextPos offset into input to end of ante context, or -1 if
michael@0: * none. Must be <= input.length() if not -1.
michael@0: * @param postContextPos offset into input to start of post context, or -1
michael@0: * if none. Must be <= input.length() if not -1, and must be >=
michael@0: * anteContextPos.
michael@0: * @param outputStr output string.
michael@0: * @param cursorPosition offset into output at which cursor is located, or -1 if
michael@0: * none. If less than zero, then the cursor is placed after the
michael@0: * output; that is, -1 is equivalent to
michael@0: * output.length(). If greater than
michael@0: * output.length() then an exception is thrown.
michael@0: * @param cursorOffset an offset to be added to cursorPos to position the
michael@0: * cursor either in the ante context, if < 0, or in the post context, if >
michael@0: * 0. For example, the rule "abc{def} > | @@@ xyz;" changes "def" to
michael@0: * "xyz" and moves the cursor to before "a". It would have a cursorOffset
michael@0: * of -3.
michael@0: * @param segs array of UnicodeMatcher corresponding to input pattern
michael@0: * segments, or null if there are none. The array itself is adopted,
michael@0: * but the pointers within it are not.
michael@0: * @param segsCount number of elements in segs[].
michael@0: * @param anchorStart TRUE if the the rule is anchored on the left to
michael@0: * the context start.
michael@0: * @param anchorEnd TRUE if the rule is anchored on the right to the
michael@0: * context limit.
michael@0: * @param data the rule data.
michael@0: * @param status Output parameter filled in with success or failure status.
michael@0: */
michael@0: TransliterationRule(const UnicodeString& input,
michael@0: int32_t anteContextPos, int32_t postContextPos,
michael@0: const UnicodeString& outputStr,
michael@0: int32_t cursorPosition, int32_t cursorOffset,
michael@0: UnicodeFunctor** segs,
michael@0: int32_t segsCount,
michael@0: UBool anchorStart, UBool anchorEnd,
michael@0: const TransliterationRuleData* data,
michael@0: UErrorCode& status);
michael@0:
michael@0: /**
michael@0: * Copy constructor.
michael@0: * @param other the object to be copied.
michael@0: */
michael@0: TransliterationRule(TransliterationRule& other);
michael@0:
michael@0: /**
michael@0: * Destructor.
michael@0: */
michael@0: virtual ~TransliterationRule();
michael@0:
michael@0: /**
michael@0: * Change the data object that this rule belongs to. Used
michael@0: * internally by the TransliterationRuleData copy constructor.
michael@0: * @param data the new data value to be set.
michael@0: */
michael@0: void setData(const TransliterationRuleData* data);
michael@0:
michael@0: /**
michael@0: * Return the preceding context length. This method is needed to
michael@0: * support the Transliterator method
michael@0: * getMaximumContextLength(). Internally, this is
michael@0: * implemented as the anteContextLength, optionally plus one if
michael@0: * there is a start anchor. The one character anchor gap is
michael@0: * needed to make repeated incremental transliteration with
michael@0: * anchors work.
michael@0: * @return the preceding context length.
michael@0: */
michael@0: virtual int32_t getContextLength(void) const;
michael@0:
michael@0: /**
michael@0: * Internal method. Returns 8-bit index value for this rule.
michael@0: * This is the low byte of the first character of the key,
michael@0: * unless the first character of the key is a set. If it's a
michael@0: * set, or otherwise can match multiple keys, the index value is -1.
michael@0: * @return 8-bit index value for this rule.
michael@0: */
michael@0: int16_t getIndexValue() const;
michael@0:
michael@0: /**
michael@0: * Internal method. Returns true if this rule matches the given
michael@0: * index value. The index value is an 8-bit integer, 0..255,
michael@0: * representing the low byte of the first character of the key.
michael@0: * It matches this rule if it matches the first character of the
michael@0: * key, or if the first character of the key is a set, and the set
michael@0: * contains any character with a low byte equal to the index
michael@0: * value. If the rule contains only ante context, as in foo)>bar,
michael@0: * then it will match any key.
michael@0: * @param v the given index value.
michael@0: * @return true if this rule matches the given index value.
michael@0: */
michael@0: UBool matchesIndexValue(uint8_t v) const;
michael@0:
michael@0: /**
michael@0: * Return true if this rule masks another rule. If r1 masks r2 then
michael@0: * r1 matches any input string that r2 matches. If r1 masks r2 and r2 masks
michael@0: * r1 then r1 == r2. Examples: "a>x" masks "ab>y". "a>x" masks "a[b]>y".
michael@0: * "[c]a>x" masks "[dc]a>y".
michael@0: * @param r2 the given rule to be compared with.
michael@0: * @return true if this rule masks 'r2'
michael@0: */
michael@0: virtual UBool masks(const TransliterationRule& r2) const;
michael@0:
michael@0: /**
michael@0: * Attempt a match and replacement at the given position. Return
michael@0: * the degree of match between this rule and the given text. The
michael@0: * degree of match may be mismatch, a partial match, or a full
michael@0: * match. A mismatch means at least one character of the text
michael@0: * does not match the context or key. A partial match means some
michael@0: * context and key characters match, but the text is not long
michael@0: * enough to match all of them. A full match means all context
michael@0: * and key characters match.
michael@0: *
michael@0: * If a full match is obtained, perform a replacement, update pos,
michael@0: * and return U_MATCH. Otherwise both text and pos are unchanged.
michael@0: *
michael@0: * @param text the text
michael@0: * @param pos the position indices
michael@0: * @param incremental if TRUE, test for partial matches that may
michael@0: * be completed by additional text inserted at pos.limit.
michael@0: * @return one of U_MISMATCH,
michael@0: * U_PARTIAL_MATCH, or U_MATCH. If
michael@0: * incremental is FALSE then U_PARTIAL_MATCH will not be returned.
michael@0: */
michael@0: UMatchDegree matchAndReplace(Replaceable& text,
michael@0: UTransPosition& pos,
michael@0: UBool incremental) const;
michael@0:
michael@0: /**
michael@0: * Create a rule string that represents this rule object. Append
michael@0: * it to the given string.
michael@0: */
michael@0: virtual UnicodeString& toRule(UnicodeString& pat,
michael@0: UBool escapeUnprintable) const;
michael@0:
michael@0: /**
michael@0: * Union the set of all characters that may be modified by this rule
michael@0: * into the given set.
michael@0: */
michael@0: void addSourceSetTo(UnicodeSet& toUnionTo) const;
michael@0:
michael@0: /**
michael@0: * Union the set of all characters that may be emitted by this rule
michael@0: * into the given set.
michael@0: */
michael@0: void addTargetSetTo(UnicodeSet& toUnionTo) const;
michael@0:
michael@0: private:
michael@0:
michael@0: friend class StringMatcher;
michael@0:
michael@0: TransliterationRule &operator=(const TransliterationRule &other); // forbid copying of this class
michael@0: };
michael@0:
michael@0: U_NAMESPACE_END
michael@0:
michael@0: #endif /* #if !UCONFIG_NO_TRANSLITERATION */
michael@0:
michael@0: #endif