• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // Copyright (C) 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