1 // Copyright (C) 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
4 **********************************************************************
5 * Copyright (c) 2001-2014, International Business Machines
6 * Corporation and others. All Rights Reserved.
7 **********************************************************************
8 * Date Name Description
9 * 08/10/2001 aliu Creation.
10 **********************************************************************
15 #include "unicode/utypes.h"
17 #if !UCONFIG_NO_TRANSLITERATION
19 #include "unicode/uobject.h"
20 #include "unicode/translit.h"
26 class TransliteratorEntry;
27 class TransliteratorSpec;
30 //------------------------------------------------------------------
31 // TransliteratorAlias
32 //------------------------------------------------------------------
35 * A TransliteratorAlias object is returned by get() if the given ID
36 * actually translates into something else. The caller then invokes
37 * the create() method on the alias to create the actual
38 * transliterator, and deletes the alias.
40 * Why all the shenanigans? To prevent circular calls between
41 * the registry code and the transliterator code that deadlocks.
43 class TransliteratorAlias : public UMemory {
46 * Construct a simple alias (type == SIMPLE)
47 * @param aliasID the given id.
49 TransliteratorAlias(const UnicodeString& aliasID, const UnicodeSet* compoundFilter);
52 * Construct a compound RBT alias (type == COMPOUND)
54 TransliteratorAlias(const UnicodeString& ID, const UnicodeString& idBlocks,
55 UVector* adoptedTransliterators,
56 const UnicodeSet* compoundFilter);
59 * Construct a rules alias (type = RULES)
61 TransliteratorAlias(const UnicodeString& theID,
62 const UnicodeString& rules,
65 ~TransliteratorAlias();
68 * The whole point of create() is that the caller must invoke
69 * it when the registry mutex is NOT held, to prevent deadlock.
70 * It may only be called once.
72 * Note: Only call create() if isRuleBased() returns FALSE.
74 * This method must be called *outside* of the TransliteratorRegistry
77 Transliterator* create(UParseError&, UErrorCode&);
80 * Return TRUE if this alias is rule-based. If so, the caller
81 * must call parse() on it, then call TransliteratorRegistry::reget().
83 UBool isRuleBased() const;
86 * If isRuleBased() returns TRUE, then the caller must call this
87 * method, followed by TransliteratorRegistry::reget(). The latter
88 * method must be called inside the TransliteratorRegistry mutex.
90 * Note: Only call parse() if isRuleBased() returns TRUE.
92 * This method must be called *outside* of the TransliteratorRegistry
93 * mutex, because it can instantiate Transliterators embedded in
94 * the rules via the "&Latin-Arabic()" syntax.
96 void parse(TransliteratorParser& parser,
97 UParseError& pe, UErrorCode& ec) const;
100 // We actually come in three flavors:
102 // Here aliasID is the alias string. Everything else is
103 // null, zero, empty.
105 // Here ID is the ID, aliasID is the idBlock, trans is the
106 // contained RBT, and idSplitPoint is the offet in aliasID
107 // where the contained RBT goes. compoundFilter is the
108 // compound filter, and it is _not_ owned.
110 // Here ID is the ID, aliasID is the rules string.
111 // idSplitPoint is the UTransDirection.
113 UnicodeString aliasesOrRules;
114 UVector* transes; // owned
115 const UnicodeSet* compoundFilter; // alias
116 UTransDirection direction;
117 enum { SIMPLE, COMPOUND, RULES } type;
119 TransliteratorAlias(const TransliteratorAlias &other); // forbid copying of this class
120 TransliteratorAlias &operator=(const TransliteratorAlias &other); // forbid copying of this class
125 * A registry of system transliterators. This is the data structure
126 * that implements the mapping between transliterator IDs and the data
127 * or function pointers used to create the corresponding
128 * transliterators. There is one instance of the registry that is
129 * created statically.
131 * The registry consists of a dynamic component -- a hashtable -- and
132 * a static component -- locale resource bundles. The dynamic store
133 * is semantically overlaid on the static store, so the static mapping
134 * can be dynamically overridden.
136 * This is an internal class that is only used by Transliterator.
137 * Transliterator maintains one static instance of this class and
138 * delegates all registry-related operations to it.
142 class TransliteratorRegistry : public UMemory {
148 * @param status Output param set to success/failure code.
150 TransliteratorRegistry(UErrorCode& status);
153 * Nonvirtual destructor -- this class is not subclassable.
155 ~TransliteratorRegistry();
157 //------------------------------------------------------------------
159 //------------------------------------------------------------------
162 * Given a simple ID (forward direction, no inline filter, not
163 * compound) attempt to instantiate it from the registry. Return
166 * Return a non-NULL aliasReturn value if the ID points to an alias.
167 * We cannot instantiate it ourselves because the alias may contain
168 * filters or compounds, which we do not understand. Caller should
169 * make aliasReturn NULL before calling.
170 * @param ID the given ID
171 * @param aliasReturn output param to receive TransliteratorAlias;
172 * should be NULL on entry
173 * @param parseError Struct to recieve information on position
174 * of error if an error is encountered
175 * @param status Output param set to success/failure code.
177 Transliterator* get(const UnicodeString& ID,
178 TransliteratorAlias*& aliasReturn,
182 * The caller must call this after calling get(), if [a] calling get()
183 * returns an alias, and [b] the alias is rule based. In that
184 * situation the caller must call alias->parse() to do the parsing
185 * OUTSIDE THE REGISTRY MUTEX, then call this method to retry
186 * instantiating the transliterator.
188 * Note: Another alias might be returned by this method.
190 * This method (like all public methods of this class) must be called
191 * from within the TransliteratorRegistry mutex.
193 * @param aliasReturn output param to receive TransliteratorAlias;
194 * should be NULL on entry
196 Transliterator* reget(const UnicodeString& ID,
197 TransliteratorParser& parser,
198 TransliteratorAlias*& aliasReturn,
202 * Register a prototype (adopted). This adds an entry to the
203 * dynamic store, or replaces an existing entry. Any entry in the
204 * underlying static locale resource store is masked.
206 void put(Transliterator* adoptedProto,
211 * Register an ID and a factory function pointer. This adds an
212 * entry to the dynamic store, or replaces an existing entry. Any
213 * entry in the underlying static locale resource store is masked.
215 void put(const UnicodeString& ID,
216 Transliterator::Factory factory,
217 Transliterator::Token context,
222 * Register an ID and a resource name. This adds an entry to the
223 * dynamic store, or replaces an existing entry. Any entry in the
224 * underlying static locale resource store is masked.
226 void put(const UnicodeString& ID,
227 const UnicodeString& resourceName,
229 UBool readonlyResourceAlias,
234 * Register an ID and an alias ID. This adds an entry to the
235 * dynamic store, or replaces an existing entry. Any entry in the
236 * underlying static locale resource store is masked.
238 void put(const UnicodeString& ID,
239 const UnicodeString& alias,
240 UBool readonlyAliasAlias,
245 * Unregister an ID. This removes an entry from the dynamic store
246 * if there is one. The static locale resource store is
248 * @param ID the given ID.
250 void remove(const UnicodeString& ID);
252 //------------------------------------------------------------------
253 // Public ID and spec management
254 //------------------------------------------------------------------
257 * Return a StringEnumeration over the IDs currently registered
261 StringEnumeration* getAvailableIDs() const;
264 * == OBSOLETE - remove in ICU 3.4 ==
265 * Return the number of IDs currently registered with the system.
266 * To retrieve the actual IDs, call getAvailableID(i) with
267 * i from 0 to countAvailableIDs() - 1.
268 * @return the number of IDs currently registered with the system.
271 int32_t countAvailableIDs(void) const;
274 * == OBSOLETE - remove in ICU 3.4 ==
275 * Return the index-th available ID. index must be between 0
276 * and countAvailableIDs() - 1, inclusive. If index is out of
277 * range, the result of getAvailableID(0) is returned.
278 * @param index the given index.
279 * @return the index-th available ID. index must be between 0
280 * and countAvailableIDs() - 1, inclusive. If index is out of
281 * range, the result of getAvailableID(0) is returned.
284 const UnicodeString& getAvailableID(int32_t index) const;
287 * Return the number of registered source specifiers.
288 * @return the number of registered source specifiers.
290 int32_t countAvailableSources(void) const;
293 * Return a registered source specifier.
294 * @param index which specifier to return, from 0 to n-1, where
295 * n = countAvailableSources()
296 * @param result fill-in paramter to receive the source specifier.
297 * If index is out of range, result will be empty.
298 * @return reference to result
300 UnicodeString& getAvailableSource(int32_t index,
301 UnicodeString& result) const;
304 * Return the number of registered target specifiers for a given
306 * @param source the given source specifier.
307 * @return the number of registered target specifiers for a given
310 int32_t countAvailableTargets(const UnicodeString& source) const;
313 * Return a registered target specifier for a given source.
314 * @param index which specifier to return, from 0 to n-1, where
315 * n = countAvailableTargets(source)
316 * @param source the source specifier
317 * @param result fill-in paramter to receive the target specifier.
318 * If source is invalid or if index is out of range, result will
320 * @return reference to result
322 UnicodeString& getAvailableTarget(int32_t index,
323 const UnicodeString& source,
324 UnicodeString& result) const;
327 * Return the number of registered variant specifiers for a given
328 * source-target pair. There is always at least one variant: If
329 * just source-target is registered, then the single variant
330 * NO_VARIANT is returned. If source-target/variant is registered
331 * then that variant is returned.
332 * @param source the source specifiers
333 * @param target the target specifiers
334 * @return the number of registered variant specifiers for a given
335 * source-target pair.
337 int32_t countAvailableVariants(const UnicodeString& source,
338 const UnicodeString& target) const;
341 * Return a registered variant specifier for a given source-target
342 * pair. If NO_VARIANT is one of the variants, then it will be
344 * @param index which specifier to return, from 0 to n-1, where
345 * n = countAvailableVariants(source, target)
346 * @param source the source specifier
347 * @param target the target specifier
348 * @param result fill-in paramter to receive the variant
349 * specifier. If source is invalid or if target is invalid or if
350 * index is out of range, result will be empty.
351 * @return reference to result
353 UnicodeString& getAvailableVariant(int32_t index,
354 const UnicodeString& source,
355 const UnicodeString& target,
356 UnicodeString& result) const;
360 //----------------------------------------------------------------
361 // Private implementation
362 //----------------------------------------------------------------
364 TransliteratorEntry* find(const UnicodeString& ID);
366 TransliteratorEntry* find(UnicodeString& source,
367 UnicodeString& target,
368 UnicodeString& variant);
370 TransliteratorEntry* findInDynamicStore(const TransliteratorSpec& src,
371 const TransliteratorSpec& trg,
372 const UnicodeString& variant) const;
374 TransliteratorEntry* findInStaticStore(const TransliteratorSpec& src,
375 const TransliteratorSpec& trg,
376 const UnicodeString& variant);
378 static TransliteratorEntry* findInBundle(const TransliteratorSpec& specToOpen,
379 const TransliteratorSpec& specToFind,
380 const UnicodeString& variant,
381 UTransDirection direction);
383 void registerEntry(const UnicodeString& source,
384 const UnicodeString& target,
385 const UnicodeString& variant,
386 TransliteratorEntry* adopted,
389 void registerEntry(const UnicodeString& ID,
390 TransliteratorEntry* adopted,
393 void registerEntry(const UnicodeString& ID,
394 const UnicodeString& source,
395 const UnicodeString& target,
396 const UnicodeString& variant,
397 TransliteratorEntry* adopted,
400 void registerSTV(const UnicodeString& source,
401 const UnicodeString& target,
402 const UnicodeString& variant);
404 void removeSTV(const UnicodeString& source,
405 const UnicodeString& target,
406 const UnicodeString& variant);
408 Transliterator* instantiateEntry(const UnicodeString& ID,
409 TransliteratorEntry *entry,
410 TransliteratorAlias*& aliasReturn,
414 * A StringEnumeration over the registered IDs in this object.
416 class Enumeration : public StringEnumeration {
418 Enumeration(const TransliteratorRegistry& reg);
419 virtual ~Enumeration();
420 virtual int32_t count(UErrorCode& status) const;
421 virtual const UnicodeString* snext(UErrorCode& status);
422 virtual void reset(UErrorCode& status);
423 static UClassID U_EXPORT2 getStaticClassID();
424 virtual UClassID getDynamicClassID() const;
427 const TransliteratorRegistry& reg;
429 friend class Enumeration;
434 * Dynamic registry mapping full IDs to Entry objects. This
435 * contains both public and internal entities. The visibility is
436 * controlled by whether an entry is listed in availableIDs and
442 * DAG of visible IDs by spec. Hashtable: source => (Hashtable:
443 * target => (UVector: variant)) The UVector of variants is never
444 * empty. For a source-target with no variant, the special
445 * variant NO_VARIANT (the empty string) is stored in slot zero of
451 * Vector of public full IDs.
453 UVector availableIDs;
455 TransliteratorRegistry(const TransliteratorRegistry &other); // forbid copying of this class
456 TransliteratorRegistry &operator=(const TransliteratorRegistry &other); // forbid copying of this class
461 U_CFUNC UBool utrans_transliterator_cleanup(void);
463 #endif /* #if !UCONFIG_NO_TRANSLITERATION */