2
**********************************************************************
3
* Copyright (C) 1999-2001, International Business Machines
4
* Corporation and others. All Rights Reserved.
5
**********************************************************************
6
* Date Name Description
7
* 11/17/99 aliu Creation.
8
**********************************************************************
13
#include "unicode/translit.h"
14
#include "unicode/utypes.h"
15
#include "unicode/parseerr.h"
19
class TransliterationRuleData;
22
* <code>RuleBasedTransliterator</code> is a transliterator
23
* that reads a set of rules in order to determine how to perform
24
* translations. Rule sets are stored in resource bundles indexed by
25
* name. Rules within a rule set are separated by semicolons (';').
26
* To include a literal semicolon, prefix it with a backslash ('\').
27
* Whitespace, as defined by <code>Character.isWhitespace()</code>,
28
* is ignored. If the first non-blank character on a line is '#',
29
* the entire line is ignored as a comment. </p>
31
* <p>Each set of rules consists of two groups, one forward, and one
32
* reverse. This is a convention that is not enforced; rules for one
33
* direction may be omitted, with the result that translations in
34
* that direction will not modify the source text. In addition,
35
* bidirectional forward-reverse rules may be specified for
36
* symmetrical transformations.</p>
38
* <p><b>Rule syntax</b> </p>
40
* <p>Rule statements take one of the following forms: </p>
43
* <dt><code>$alefmadda=\u0622;</code></dt>
44
* <dd><strong>Variable definition.</strong> The name on the
45
* left is assigned the text on the right. In this example,
46
* after this statement, instances of the left hand name,
47
* "<code>$alefmadda</code>", will be replaced by
48
* the Unicode character U+0622. Variable names must begin
49
* with a letter and consist only of letters, digits, and
50
* underscores. Case is significant. Duplicate names cause
51
* an exception to be thrown, that is, variables cannot be
52
* redefined. The right hand side may contain well-formed
53
* text of any length, including no text at all ("<code>$empty=;</code>").
54
* The right hand side may contain embedded <code>UnicodeSet</code>
55
* patterns, for example, "<code>$softvowel=[eiyEIY]</code>".</dd>
57
* <dt><code>ai>$alefmadda;</code></dt>
58
* <dd><strong>Forward translation rule.</strong> This rule
59
* states that the string on the left will be changed to the
60
* string on the right when performing forward
61
* transliteration.</dd>
63
* <dt><code>ai<$alefmadda;</code></dt>
64
* <dd><strong>Reverse translation rule.</strong> This rule
65
* states that the string on the right will be changed to
66
* the string on the left when performing reverse
67
* transliteration.</dd>
71
* <dt><code>ai<>$alefmadda;</code></dt>
72
* <dd><strong>Bidirectional translation rule.</strong> This
73
* rule states that the string on the right will be changed
74
* to the string on the left when performing forward
75
* transliteration, and vice versa when performing reverse
76
* transliteration.</dd>
79
* <p>Translation rules consist of a <em>match pattern</em> and an <em>output
80
* string</em>. The match pattern consists of literal characters,
81
* optionally preceded by context, and optionally followed by
82
* context. Context characters, like literal pattern characters,
83
* must be matched in the text being transliterated. However, unlike
84
* literal pattern characters, they are not replaced by the output
85
* text. For example, the pattern "<code>abc{def}</code>"
86
* indicates the characters "<code>def</code>" must be
87
* preceded by "<code>abc</code>" for a successful match.
88
* If there is a successful match, "<code>def</code>" will
89
* be replaced, but not "<code>abc</code>". The final '<code>}</code>'
90
* is optional, so "<code>abc{def</code>" is equivalent to
91
* "<code>abc{def}</code>". Another example is "<code>{123}456</code>"
92
* (or "<code>123}456</code>") in which the literal
93
* pattern "<code>123</code>" must be followed by "<code>456</code>".
96
* <p>The output string of a forward or reverse rule consists of
97
* characters to replace the literal pattern characters. If the
98
* output string contains the character '<code>|</code>', this is
99
* taken to indicate the location of the <em>cursor</em> after
100
* replacement. The cursor is the point in the text at which the
101
* next replacement, if any, will be applied. The cursor is usually
102
* placed within the replacement text; however, it can actually be
103
* placed into the precending or following context by using the
104
* special character '<code>@</code>'. Examples:</p>
107
* <p><code>a {foo} z > | @ bar; # foo -> bar, move cursor
109
* {foo} xyz > bar @@|; # foo -> bar, cursor between
113
* <p><b>UnicodeSet</b></p>
115
* <p><code>UnicodeSet</code> patterns may appear anywhere that
116
* makes sense. They may appear in variable definitions.
117
* Contrariwise, <code>UnicodeSet</code> patterns may themselves
118
* contain variable references, such as "<code>$a=[a-z];$not_a=[^$a]</code>",
119
* or "<code>$range=a-z;$ll=[$range]</code>".</p>
121
* <p><code>UnicodeSet</code> patterns may also be embedded directly
122
* into rule strings. Thus, the following two rules are equivalent:</p>
125
* <p><code>$vowel=[aeiou]; $vowel>'*'; # One way to do this<br>
127
* #
128
* Another way</code></p>
131
* <p>See {@link UnicodeSet} for more documentation and examples.</p>
133
* <p><b>Segments</b></p>
135
* <p>Segments of the input string can be matched and copied to the
136
* output string. This makes certain sets of rules simpler and more
137
* general, and makes reordering possible. For example:</p>
140
* <p><code>([a-z]) > $1 $1;
141
* #
142
* double lowercase letters<br>
143
* ([:Lu:]) ([:Ll:]) > $2 $1; # reverse order of Lu-Ll pairs</code></p>
146
* <p>The segment of the input string to be copied is delimited by
147
* "<code>(</code>" and "<code>)</code>". Up to
148
* nine segments may be defined. Segments may not overlap. In the
149
* output string, "<code>$1</code>" through "<code>$9</code>"
150
* represent the input string segments, in left-to-right order of
153
* <p><b>Anchors</b></p>
155
* <p>Patterns can be anchored to the beginning or the end of the text. This is done with the
156
* special characters '<code>^</code>' and '<code>$</code>'. For example:</p>
159
* <p><code>^ a > 'BEG_A'; # match 'a' at start of text<br>
160
* a > 'A'; # match other instances
162
* z $ > 'END_Z'; # match 'z' at end of text<br>
163
* z > 'Z'; # match other instances
167
* <p>It is also possible to match the beginning or the end of the text using a <code>UnicodeSet</code>.
168
* This is done by including a virtual anchor character '<code>$</code>' at the end of the
169
* set pattern. Although this is usually the match chafacter for the end anchor, the set will
170
* match either the beginning or the end of the text, depending on its placement. For
174
* <p><code>$x = [a-z$]; # match 'a' through 'z' OR anchor<br>
175
* $x 1 > 2; # match '1' after a-z or at the start<br>
176
* 3 $x > 4; # match '3' before a-z or at the end</code></p>
179
* <p><b>Example</b> </p>
181
* <p>The following example rules illustrate many of the features of
182
* the rule language. </p>
184
* <table border="0" cellpadding="4">
186
* <td valign="top">Rule 1.</td>
187
* <td valign="top" nowrap><code>abc{def}>x|y</code></td>
190
* <td valign="top">Rule 2.</td>
191
* <td valign="top" nowrap><code>xyz>r</code></td>
194
* <td valign="top">Rule 3.</td>
195
* <td valign="top" nowrap><code>yz>q</code></td>
199
* <p>Applying these rules to the string "<code>adefabcdefz</code>"
200
* yields the following results: </p>
202
* <table border="0" cellpadding="4">
204
* <td valign="top" nowrap><code>|adefabcdefz</code></td>
205
* <td valign="top">Initial state, no rules match. Advance
209
* <td valign="top" nowrap><code>a|defabcdefz</code></td>
210
* <td valign="top">Still no match. Rule 1 does not match
211
* because the preceding context is not present.</td>
214
* <td valign="top" nowrap><code>ad|efabcdefz</code></td>
215
* <td valign="top">Still no match. Keep advancing until
216
* there is a match...</td>
219
* <td valign="top" nowrap><code>ade|fabcdefz</code></td>
220
* <td valign="top">...</td>
223
* <td valign="top" nowrap><code>adef|abcdefz</code></td>
224
* <td valign="top">...</td>
227
* <td valign="top" nowrap><code>adefa|bcdefz</code></td>
228
* <td valign="top">...</td>
231
* <td valign="top" nowrap><code>adefab|cdefz</code></td>
232
* <td valign="top">...</td>
235
* <td valign="top" nowrap><code>adefabc|defz</code></td>
236
* <td valign="top">Rule 1 matches; replace "<code>def</code>"
237
* with "<code>xy</code>" and back up the cursor
238
* to before the '<code>y</code>'.</td>
241
* <td valign="top" nowrap><code>adefabcx|yz</code></td>
242
* <td valign="top">Although "<code>xyz</code>" is
243
* present, rule 2 does not match because the cursor is
244
* before the '<code>y</code>', not before the '<code>x</code>'.
245
* Rule 3 does match. Replace "<code>yz</code>"
246
* with "<code>q</code>".</td>
249
* <td valign="top" nowrap><code>adefabcxq|</code></td>
250
* <td valign="top">The cursor is at the end;
251
* transliteration is complete.</td>
255
* <p>The order of rules is significant. If multiple rules may match
256
* at some point, the first matching rule is applied. </p>
258
* <p>Forward and reverse rules may have an empty output string.
259
* Otherwise, an empty left or right hand side of any statement is a
262
* <p>Single quotes are used to quote any character other than a
263
* digit or letter. To specify a single quote itself, inside or
264
* outside of quotes, use two single quotes in a row. For example,
265
* the rule "<code>'>'>o''clock</code>" changes the
266
* string "<code>></code>" to the string "<code>o'clock</code>".
269
* <p><b>Notes</b> </p>
271
* <p>While a RuleBasedTransliterator is being built, it checks that
272
* the rules are added in proper order. For example, if the rule
273
* "a>x" is followed by the rule "ab>y",
274
* then the second rule will throw an exception. The reason is that
275
* the second rule can never be triggered, since the first rule
276
* always matches anything it matches. In other words, the first
277
* rule <em>masks</em> the second rule. </p>
280
* @deprecated To be removed after 2002-sep-30; use the Transliterator::createFromRules factory method.
282
class U_I18N_API RuleBasedTransliterator : public Transliterator {
285
* The data object is immutable, so we can freely share it with
286
* other instances of RBT, as long as we do NOT own this object.
288
TransliterationRuleData* data;
291
* If true, we own the data object and must delete it.
298
* Constructs a new transliterator from the given rules.
299
* @param rules rules, separated by ';'
300
* @param direction either FORWARD or REVERSE.
301
* @exception IllegalArgumentException if rules are malformed.
302
* @deprecated To be removed after 2002-sep-30; use the Transliterator::createFromRules factory method.
304
RuleBasedTransliterator(const UnicodeString& id,
305
const UnicodeString& rules,
306
UTransDirection direction,
307
UnicodeFilter* adoptedFilter,
308
UParseError& parseError,
312
* Constructs a new transliterator from the given rules.
313
* @param rules rules, separated by ';'
314
* @param direction either FORWARD or REVERSE.
315
* @exception IllegalArgumentException if rules are malformed.
316
* @deprecated To be removed after 2002-sep-30; use the Transliterator::createFromRules factory method.
318
RuleBasedTransliterator(const UnicodeString& id,
319
const UnicodeString& rules,
320
UTransDirection direction,
321
UnicodeFilter* adoptedFilter,
325
* Covenience constructor with no filter.
326
* @deprecated To be removed after 2002-sep-30; use the Transliterator::createFromRules factory method.
328
RuleBasedTransliterator(const UnicodeString& id,
329
const UnicodeString& rules,
330
UTransDirection direction,
334
* Covenience constructor with no filter and FORWARD direction.
335
* @deprecated To be removed after 2002-sep-30; use the Transliterator::createFromRules factory method.
337
RuleBasedTransliterator(const UnicodeString& id,
338
const UnicodeString& rules,
342
* Covenience constructor with FORWARD direction.
343
* @deprecated To be removed after 2002-sep-30; use the Transliterator::createFromRules factory method.
345
RuleBasedTransliterator(const UnicodeString& id,
346
const UnicodeString& rules,
347
UnicodeFilter* adoptedFilter,
351
friend class TransliteratorRegistry; // to access TransliterationRuleData convenience ctor
353
* Covenience constructor.
355
RuleBasedTransliterator(const UnicodeString& id,
356
const TransliterationRuleData* theData,
357
UnicodeFilter* adoptedFilter = 0);
360
friend class Transliterator; // to access following ct
363
* Internal constructor.
365
RuleBasedTransliterator(const UnicodeString& id,
366
TransliterationRuleData* data,
367
UBool isDataAdopted);
373
* @deprecated To be removed after 2002-sep-30; use the Transliterator::createFromRules factory method.
375
RuleBasedTransliterator(const RuleBasedTransliterator&);
377
virtual ~RuleBasedTransliterator();
380
* Implement Transliterator API.
381
* @deprecated To be removed after 2002-sep-30.
383
Transliterator* clone(void) const;
386
* Implements {@link Transliterator#handleTransliterate}.
387
* @deprecated To be removed after 2002-sep-30.
389
virtual void handleTransliterate(Replaceable& text, UTransPosition& offsets,
390
UBool isIncremental) const;
393
* Return a representation of this transliterator as source rules.
394
* These rules will produce an equivalent transliterator if used
395
* to construct a new transliterator.
396
* @param result the string to receive the rules. Previous
397
* contents will be deleted.
398
* @param escapeUnprintable if TRUE then convert unprintable
399
* character to their hex escape representations, \uxxxx or
400
* \Uxxxxxxxx. Unprintable characters are those other than
401
* U+000A, U+0020..U+007E.
402
* @deprecated To be removed after 2002-sep-30; use the Transliterator::toRules directly.
404
virtual UnicodeString& toRules(UnicodeString& result,
405
UBool escapeUnprintable) const;
408
* Return the class ID for this class. This is useful only for
409
* comparing to a return value from getDynamicClassID(). For example:
411
* . Base* polymorphic_pointer = createPolymorphicObject();
412
* . if (polymorphic_pointer->getDynamicClassID() ==
413
* . Derived::getStaticClassID()) ...
415
* @return The class ID for all objects of this class.
416
* @deprecated To be removed after 2002-sep-30.
418
static UClassID getStaticClassID(void) { return (UClassID)&fgClassID; }
421
* Returns a unique class ID <b>polymorphically</b>. This method
422
* is to implement a simple version of RTTI, since not all C++
423
* compilers support genuine RTTI. Polymorphic operator==() and
424
* clone() methods call this method.
426
* <p>Concrete subclasses of Transliterator that wish clients to
427
* be able to identify them should implement getDynamicClassID()
428
* and also a static method and data member:
431
* static UClassID getStaticClassID() { return (UClassID)&fgClassID; }
432
* static char fgClassID;
435
* Subclasses that do not implement this method will have a
436
* dynamic class ID of Transliterator::getStatisClassID().
438
* @return The class ID for this object. All objects of a given
439
* class have the same class ID. Objects of other classes have
440
* different class IDs.
442
virtual UClassID getDynamicClassID(void) const { return getStaticClassID(); };
447
* Class identifier for RuleBasedTransliterator.
449
static const char fgClassID;
451
void _construct(const UnicodeString& rules,
452
UTransDirection direction,
453
UParseError& parseError,
458
* Constructs a new transliterator from the given rules.
459
* @param rules rules, separated by ';'
460
* @param direction either FORWARD or REVERSE.
461
* @exception IllegalArgumentException if rules are malformed
462
* or direction is invalid.
464
inline RuleBasedTransliterator::RuleBasedTransliterator(
465
const UnicodeString& id,
466
const UnicodeString& rules,
467
UTransDirection direction,
468
UnicodeFilter* adoptedFilter,
469
UParseError& parseError,
470
UErrorCode& status) :
471
Transliterator(id, adoptedFilter) {
472
_construct(rules, direction,parseError,status);
476
* Constructs a new transliterator from the given rules.
477
* @param rules rules, separated by ';'
478
* @param direction either FORWARD or REVERSE.
479
* @exception IllegalArgumentException if rules are malformed
480
* or direction is invalid.
482
inline RuleBasedTransliterator::RuleBasedTransliterator(
483
const UnicodeString& id,
484
const UnicodeString& rules,
485
UTransDirection direction,
486
UnicodeFilter* adoptedFilter,
487
UErrorCode& status) :
488
Transliterator(id, adoptedFilter) {
489
UParseError parseError;
490
_construct(rules, direction,parseError, status);
494
* Covenience constructor with no filter.
496
inline RuleBasedTransliterator::RuleBasedTransliterator(
497
const UnicodeString& id,
498
const UnicodeString& rules,
499
UTransDirection direction,
500
UErrorCode& status) :
501
Transliterator(id, 0) {
502
UParseError parseError;
503
_construct(rules, direction,parseError, status);
507
* Covenience constructor with no filter and FORWARD direction.
509
inline RuleBasedTransliterator::RuleBasedTransliterator(
510
const UnicodeString& id,
511
const UnicodeString& rules,
512
UErrorCode& status) :
513
Transliterator(id, 0) {
514
UParseError parseError;
515
_construct(rules, UTRANS_FORWARD, parseError, status);
519
* Covenience constructor with FORWARD direction.
521
inline RuleBasedTransliterator::RuleBasedTransliterator(
522
const UnicodeString& id,
523
const UnicodeString& rules,
524
UnicodeFilter* adoptedFilter,
525
UErrorCode& status) :
526
Transliterator(id, adoptedFilter) {
527
UParseError parseError;
528
_construct(rules, UTRANS_FORWARD,parseError, status);
added
removed
source/i18n/unicode/rbt.h
