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
22U_NAMESPACE_BEGIN
23
24class Replaceable;
25class TransliterationRuleData;
26class StringMatcher;
27class 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 */
57class TransliterationRule : public UMemory {
58
59private:
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
148public:
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
306U_NAMESPACE_END
307
308#endif /* #if !UCONFIG_NO_TRANSLITERATION */
309
310#endif
311