1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 * Copyright (C) {1999-2001}, International Business Machines Corporation and others. All Rights Reserved. 5 ********************************************************************** 6 * Date Name Description 7 * 11/17/99 aliu Creation. 8 ********************************************************************** 9 */ 10 #ifndef RBT_RULE_H 11 #define RBT_RULE_H 12 13 #include "unicode/utypes.h" 14 15 #if !UCONFIG_NO_TRANSLITERATION 16 17 #include "unicode/uobject.h" 18 #include "unicode/unistr.h" 19 #include "unicode/utrans.h" 20 #include "unicode/unimatch.h" 21 22 U_NAMESPACE_BEGIN 23 24 class Replaceable; 25 class TransliterationRuleData; 26 class StringMatcher; 27 class UnicodeFunctor; 28 29 /** 30 * A transliteration rule used by 31 * <code>RuleBasedTransliterator</code>. 32 * <code>TransliterationRule</code> is an immutable object. 33 * 34 * <p>A rule consists of an input pattern and an output string. When 35 * the input pattern is matched, the output string is emitted. The 36 * input pattern consists of zero or more characters which are matched 37 * exactly (the key) and optional context. Context must match if it 38 * is specified. Context may be specified before the key, after the 39 * key, or both. The key, preceding context, and following context 40 * may contain variables. Variables represent a set of Unicode 41 * characters, such as the letters <i>a</i> through <i>z</i>. 42 * Variables are detected by looking up each character in a supplied 43 * variable list to see if it has been so defined. 44 * 45 * <p>A rule may contain segments in its input string and segment 46 * references in its output string. A segment is a substring of the 47 * input pattern, indicated by an offset and limit. The segment may 48 * be in the preceding or following context. It may not span a 49 * context boundary. A segment reference is a special character in 50 * the output string that causes a segment of the input string (not 51 * the input pattern) to be copied to the output string. The range of 52 * special characters that represent segment references is defined by 53 * RuleBasedTransliterator.Data. 54 * 55 * @author Alan Liu 56 */ 57 class TransliterationRule : public UMemory { 58 59 private: 60 61 // TODO Eliminate the pattern and keyLength data members. They 62 // are used only by masks() and getIndexValue() which are called 63 // only during build time, not during run-time. Perhaps these 64 // methods and pattern/keyLength can be isolated into a separate 65 // object. 66 67 /** 68 * The match that must occur before the key, or null if there is no 69 * preceding context. 70 */ 71 StringMatcher *anteContext; 72 73 /** 74 * The matcher object for the key. If null, then the key is empty. 75 */ 76 StringMatcher *key; 77 78 /** 79 * The match that must occur after the key, or null if there is no 80 * following context. 81 */ 82 StringMatcher *postContext; 83 84 /** 85 * The object that performs the replacement if the key, 86 * anteContext, and postContext are matched. Never null. 87 */ 88 UnicodeFunctor* output; 89 90 /** 91 * The string that must be matched, consisting of the anteContext, key, 92 * and postContext, concatenated together, in that order. Some components 93 * may be empty (zero length). 94 * @see anteContextLength 95 * @see keyLength 96 */ 97 UnicodeString pattern; 98 99 /** 100 * An array of matcher objects corresponding to the input pattern 101 * segments. If there are no segments this is null. N.B. This is 102 * a UnicodeMatcher for generality, but in practice it is always a 103 * StringMatcher. In the future we may generalize this, but for 104 * now we sometimes cast down to StringMatcher. 105 * 106 * The array is owned, but the pointers within it are not. 107 */ 108 UnicodeFunctor** segments; 109 110 /** 111 * The number of elements in segments[] or zero if segments is NULL. 112 */ 113 int32_t segmentsCount; 114 115 /** 116 * The length of the string that must match before the key. If 117 * zero, then there is no matching requirement before the key. 118 * Substring [0,anteContextLength) of pattern is the anteContext. 119 */ 120 int32_t anteContextLength; 121 122 /** 123 * The length of the key. Substring [anteContextLength, 124 * anteContextLength + keyLength) is the key. 125 126 */ 127 int32_t keyLength; 128 129 /** 130 * Miscellaneous attributes. 131 */ 132 int8_t flags; 133 134 /** 135 * Flag attributes. 136 */ 137 enum { 138 ANCHOR_START = 1, 139 ANCHOR_END = 2 140 }; 141 142 /** 143 * An alias pointer to the data for this rule. The data provides 144 * lookup services for matchers and segments. 145 */ 146 const TransliterationRuleData* data; 147 148 public: 149 150 /** 151 * Construct a new rule with the given input, output text, and other 152 * attributes. A cursor position may be specified for the output text. 153 * @param input input string, including key and optional ante and 154 * post context. 155 * @param anteContextPos offset into input to end of ante context, or -1 if 156 * none. Must be <= input.length() if not -1. 157 * @param postContextPos offset into input to start of post context, or -1 158 * if none. Must be <= input.length() if not -1, and must be >= 159 * anteContextPos. 160 * @param outputStr output string. 161 * @param cursorPosition offset into output at which cursor is located, or -1 if 162 * none. If less than zero, then the cursor is placed after the 163 * <code>output</code>; that is, -1 is equivalent to 164 * <code>output.length()</code>. If greater than 165 * <code>output.length()</code> then an exception is thrown. 166 * @param cursorOffset an offset to be added to cursorPos to position the 167 * cursor either in the ante context, if < 0, or in the post context, if > 168 * 0. For example, the rule "abc{def} > | @@@ xyz;" changes "def" to 169 * "xyz" and moves the cursor to before "a". It would have a cursorOffset 170 * of -3. 171 * @param segs array of UnicodeMatcher corresponding to input pattern 172 * segments, or null if there are none. The array itself is adopted, 173 * but the pointers within it are not. 174 * @param segsCount number of elements in segs[]. 175 * @param anchorStart TRUE if the the rule is anchored on the left to 176 * the context start. 177 * @param anchorEnd TRUE if the rule is anchored on the right to the 178 * context limit. 179 * @param data the rule data. 180 * @param status Output parameter filled in with success or failure status. 181 */ 182 TransliterationRule(const UnicodeString& input, 183 int32_t anteContextPos, int32_t postContextPos, 184 const UnicodeString& outputStr, 185 int32_t cursorPosition, int32_t cursorOffset, 186 UnicodeFunctor** segs, 187 int32_t segsCount, 188 UBool anchorStart, UBool anchorEnd, 189 const TransliterationRuleData* data, 190 UErrorCode& status); 191 192 /** 193 * Copy constructor. 194 * @param other the object to be copied. 195 */ 196 TransliterationRule(TransliterationRule& other); 197 198 /** 199 * Destructor. 200 */ 201 virtual ~TransliterationRule(); 202 203 /** 204 * Change the data object that this rule belongs to. Used 205 * internally by the TransliterationRuleData copy constructor. 206 * @param data the new data value to be set. 207 */ 208 void setData(const TransliterationRuleData* data); 209 210 /** 211 * Return the preceding context length. This method is needed to 212 * support the <code>Transliterator</code> method 213 * <code>getMaximumContextLength()</code>. Internally, this is 214 * implemented as the anteContextLength, optionally plus one if 215 * there is a start anchor. The one character anchor gap is 216 * needed to make repeated incremental transliteration with 217 * anchors work. 218 * @return the preceding context length. 219 */ 220 virtual int32_t getContextLength(void) const; 221 222 /** 223 * Internal method. Returns 8-bit index value for this rule. 224 * This is the low byte of the first character of the key, 225 * unless the first character of the key is a set. If it's a 226 * set, or otherwise can match multiple keys, the index value is -1. 227 * @return 8-bit index value for this rule. 228 */ 229 int16_t getIndexValue() const; 230 231 /** 232 * Internal method. Returns true if this rule matches the given 233 * index value. The index value is an 8-bit integer, 0..255, 234 * representing the low byte of the first character of the key. 235 * It matches this rule if it matches the first character of the 236 * key, or if the first character of the key is a set, and the set 237 * contains any character with a low byte equal to the index 238 * value. If the rule contains only ante context, as in foo)>bar, 239 * then it will match any key. 240 * @param v the given index value. 241 * @return true if this rule matches the given index value. 242 */ 243 UBool matchesIndexValue(uint8_t v) const; 244 245 /** 246 * Return true if this rule masks another rule. If r1 masks r2 then 247 * r1 matches any input string that r2 matches. If r1 masks r2 and r2 masks 248 * r1 then r1 == r2. Examples: "a>x" masks "ab>y". "a>x" masks "a[b]>y". 249 * "[c]a>x" masks "[dc]a>y". 250 * @param r2 the given rule to be compared with. 251 * @return true if this rule masks 'r2' 252 */ 253 virtual UBool masks(const TransliterationRule& r2) const; 254 255 /** 256 * Attempt a match and replacement at the given position. Return 257 * the degree of match between this rule and the given text. The 258 * degree of match may be mismatch, a partial match, or a full 259 * match. A mismatch means at least one character of the text 260 * does not match the context or key. A partial match means some 261 * context and key characters match, but the text is not long 262 * enough to match all of them. A full match means all context 263 * and key characters match. 264 * 265 * If a full match is obtained, perform a replacement, update pos, 266 * and return U_MATCH. Otherwise both text and pos are unchanged. 267 * 268 * @param text the text 269 * @param pos the position indices 270 * @param incremental if TRUE, test for partial matches that may 271 * be completed by additional text inserted at pos.limit. 272 * @return one of <code>U_MISMATCH</code>, 273 * <code>U_PARTIAL_MATCH</code>, or <code>U_MATCH</code>. If 274 * incremental is FALSE then U_PARTIAL_MATCH will not be returned. 275 */ 276 UMatchDegree matchAndReplace(Replaceable& text, 277 UTransPosition& pos, 278 UBool incremental) const; 279 280 /** 281 * Create a rule string that represents this rule object. Append 282 * it to the given string. 283 */ 284 virtual UnicodeString& toRule(UnicodeString& pat, 285 UBool escapeUnprintable) const; 286 287 /** 288 * Union the set of all characters that may be modified by this rule 289 * into the given set. 290 */ 291 void addSourceSetTo(UnicodeSet& toUnionTo) const; 292 293 /** 294 * Union the set of all characters that may be emitted by this rule 295 * into the given set. 296 */ 297 void addTargetSetTo(UnicodeSet& toUnionTo) const; 298 299 private: 300 301 friend class StringMatcher; 302 303 TransliterationRule &operator=(const TransliterationRule &other); // forbid copying of this class 304 }; 305 306 U_NAMESPACE_END 307 308 #endif /* #if !UCONFIG_NO_TRANSLITERATION */ 309 310 #endif 311