icuSources/i18n/transreg.h

   1 // © 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4 **********************************************************************
   5 *   Copyright (c) 2001-2016 International Business Machines
   6 *   Corporation and others.  All Rights Reserved.
   7 **********************************************************************
   8 *   Date        Name        Description
   9 *   08/10/2001  aliu        Creation.
  10 **********************************************************************
  11 */
  12 #ifndef _TRANSREG_H
  13 #define _TRANSREG_H
  14
  15 #include "unicode/utypes.h"
  16
  17 #if !UCONFIG_NO_TRANSLITERATION
  18
  19 #include "unicode/uobject.h"
  20 #include "unicode/translit.h"
  21 #include "hash.h"
  22 #include "uvector.h"
  23
  24 U_NAMESPACE_BEGIN
  25
  26 class TransliteratorEntry;
  27 class TransliteratorSpec;
  28 class UnicodeString;
  29
  30 //------------------------------------------------------------------
  31 // TransliteratorAlias
  32 //------------------------------------------------------------------
  33
  34 /**
  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.
  39  *
  40  * Why all the shenanigans?  To prevent circular calls between
  41  * the registry code and the transliterator code that deadlocks.
  42  */
  43 class TransliteratorAlias : public UMemory {
  44  public:
  45     /**
  46      * Construct a simple alias (type == SIMPLE)
  47      * @param aliasID the given id.
  48      */
  49     TransliteratorAlias(const UnicodeString& aliasID, const UnicodeSet* compoundFilter);
  50
  51     /**
  52      * Construct a compound RBT alias (type == COMPOUND)
  53      */
  54     TransliteratorAlias(const UnicodeString& ID, const UnicodeString& idBlocks,
  55                         UVector* adoptedTransliterators,
  56                         const UnicodeSet* compoundFilter);
  57
  58     /**
  59      * Construct a rules alias (type = RULES)
  60      */
  61     TransliteratorAlias(const UnicodeString& theID,
  62                         const UnicodeString& rules,
  63                         UTransDirection dir);
  64
  65     ~TransliteratorAlias();
  66
  67     /**
  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.
  71      *
  72      * Note: Only call create() if isRuleBased() returns FALSE.
  73      *
  74      * This method must be called *outside* of the TransliteratorRegistry
  75      * mutex.
  76      */
  77     Transliterator* create(UParseError&, UErrorCode&);
  78
  79     /**
  80      * Return TRUE if this alias is rule-based.  If so, the caller
  81      * must call parse() on it, then call TransliteratorRegistry::reget().
  82      */
  83     UBool isRuleBased() const;
  84
  85     /**
  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.
  89      *
  90      * Note: Only call parse() if isRuleBased() returns TRUE.
  91      *
  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.
  95      */
  96     void parse(TransliteratorParser& parser,
  97                UParseError& pe, UErrorCode& ec) const;
  98
  99  private:
 100     // We actually come in three flavors:
 101     // 1. Simple alias
 102     //    Here aliasID is the alias string.  Everything else is
 103     //    null, zero, empty.
 104     // 2. CompoundRBT
 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.
 109     // 3. Rules
 110     //    Here ID is the ID, aliasID is the rules string.
 111     //    idSplitPoint is the UTransDirection.
 112     UnicodeString ID;
 113     UnicodeString aliasesOrRules;
 114     UVector* transes; // owned
 115     const UnicodeSet* compoundFilter; // alias
 116     UTransDirection direction;
 117     enum { SIMPLE, COMPOUND, RULES } type;
 118
 119     TransliteratorAlias(const TransliteratorAlias &other); // forbid copying of this class
 120     TransliteratorAlias &operator=(const TransliteratorAlias &other); // forbid copying of this class
 121 };
 122
 123
 124 /**
 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.
 130  *
 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.
 135  *
 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.
 139  *
 140  * @author Alan Liu
 141  */
 142 class TransliteratorRegistry : public UMemory {
 143
 144  public:
 145
 146     /**
 147      * Contructor
 148      * @param status Output param set to success/failure code.
 149      */
 150     TransliteratorRegistry(UErrorCode& status);
 151
 152     /**
 153      * Nonvirtual destructor -- this class is not subclassable.
 154      */
 155     ~TransliteratorRegistry();
 156
 157     //------------------------------------------------------------------
 158     // Basic public API
 159     //------------------------------------------------------------------
 160
 161     /**
 162      * Given a simple ID (forward direction, no inline filter, not
 163      * compound) attempt to instantiate it from the registry.  Return
 164      * 0 on failure.
 165      *
 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.
 176      */
 177     Transliterator* get(const UnicodeString& ID,
 178                         TransliteratorAlias*& aliasReturn,
 179                         UErrorCode& status);
 180
 181     /**
 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.
 187      *
 188      * Note: Another alias might be returned by this method.
 189      *
 190      * This method (like all public methods of this class) must be called
 191      * from within the TransliteratorRegistry mutex.
 192      *
 193      * @param aliasReturn output param to receive TransliteratorAlias;
 194      *                    should be NULL on entry
 195      */
 196     Transliterator* reget(const UnicodeString& ID,
 197                           TransliteratorParser& parser,
 198                           TransliteratorAlias*& aliasReturn,
 199                           UErrorCode& status);
 200
 201     /**
 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.
 205      */
 206     void put(Transliterator* adoptedProto,
 207              UBool visible,
 208              UErrorCode& ec);
 209
 210     /**
 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.
 214      */
 215     void put(const UnicodeString& ID,
 216              Transliterator::Factory factory,
 217              Transliterator::Token context,
 218              UBool visible,
 219              UErrorCode& ec);
 220
 221     /**
 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.
 225      */
 226     void put(const UnicodeString& ID,
 227              const UnicodeString& resourceName,
 228              UTransDirection dir,
 229              UBool readonlyResourceAlias,
 230              UBool visible,
 231              UErrorCode& ec);
 232
 233     /**
 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.
 237      */
 238     void put(const UnicodeString& ID,
 239              const UnicodeString& alias,
 240              UBool readonlyAliasAlias,
 241              UBool visible,
 242              UErrorCode& ec);
 243
 244     /**
 245      * Unregister an ID.  This removes an entry from the dynamic store
 246      * if there is one.  The static locale resource store is
 247      * unaffected.
 248      * @param ID    the given ID.
 249      */
 250     void remove(const UnicodeString& ID);
 251
 252     //------------------------------------------------------------------
 253     // Public ID and spec management
 254     //------------------------------------------------------------------
 255
 256     /**
 257      * Return a StringEnumeration over the IDs currently registered
 258      * with the system.
 259      * @internal
 260      */
 261     StringEnumeration* getAvailableIDs() const;
 262
 263     /**
 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.
 269      * @internal
 270      */
 271     int32_t countAvailableIDs(void) const;
 272
 273     /**
 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.
 282      * @internal
 283      */
 284     const UnicodeString& getAvailableID(int32_t index) const;
 285
 286     /**
 287      * Return the number of registered source specifiers.
 288      * @return the number of registered source specifiers.
 289      */
 290     int32_t countAvailableSources(void) const;
 291
 292     /**
 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
 299      */
 300     UnicodeString& getAvailableSource(int32_t index,
 301                                       UnicodeString& result) const;
 302
 303     /**
 304      * Return the number of registered target specifiers for a given
 305      * source specifier.
 306      * @param source the given source specifier.
 307      * @return the number of registered target specifiers for a given
 308      *         source specifier.
 309      */
 310     int32_t countAvailableTargets(const UnicodeString& source) const;
 311
 312     /**
 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
 319      * be empty.
 320      * @return reference to result
 321      */
 322     UnicodeString& getAvailableTarget(int32_t index,
 323                                       const UnicodeString& source,
 324                                       UnicodeString& result) const;
 325
 326     /**
 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.
 336      */
 337     int32_t countAvailableVariants(const UnicodeString& source,
 338                                    const UnicodeString& target) const;
 339
 340     /**
 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
 343      * at index 0.
 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
 352      */
 353     UnicodeString& getAvailableVariant(int32_t index,
 354                                        const UnicodeString& source,
 355                                        const UnicodeString& target,
 356                                        UnicodeString& result) const;
 357
 358  private:
 359
 360     //----------------------------------------------------------------
 361     // Private implementation
 362     //----------------------------------------------------------------
 363
 364     TransliteratorEntry* find(const UnicodeString& ID);
 365
 366     TransliteratorEntry* find(UnicodeString& source,
 367                 UnicodeString& target,
 368                 UnicodeString& variant);
 369
 370     TransliteratorEntry* findInDynamicStore(const TransliteratorSpec& src,
 371                               const TransliteratorSpec& trg,
 372                               const UnicodeString& variant) const;
 373
 374     TransliteratorEntry* findInStaticStore(const TransliteratorSpec& src,
 375                              const TransliteratorSpec& trg,
 376                              const UnicodeString& variant);
 377
 378     static TransliteratorEntry* findInBundle(const TransliteratorSpec& specToOpen,
 379                                const TransliteratorSpec& specToFind,
 380                                const UnicodeString& variant,
 381                                UTransDirection direction);
 382
 383     void registerEntry(const UnicodeString& source,
 384                        const UnicodeString& target,
 385                        const UnicodeString& variant,
 386                        TransliteratorEntry* adopted,
 387                        UBool visible);
 388
 389     void registerEntry(const UnicodeString& ID,
 390                        TransliteratorEntry* adopted,
 391                        UBool visible);
 392
 393     void registerEntry(const UnicodeString& ID,
 394                        const UnicodeString& source,
 395                        const UnicodeString& target,
 396                        const UnicodeString& variant,
 397                        TransliteratorEntry* adopted,
 398                        UBool visible);
 399
 400     void registerSTV(const UnicodeString& source,
 401                      const UnicodeString& target,
 402                      const UnicodeString& variant);
 403
 404     void removeSTV(const UnicodeString& source,
 405                    const UnicodeString& target,
 406                    const UnicodeString& variant);
 407
 408     Transliterator* instantiateEntry(const UnicodeString& ID,
 409                                      TransliteratorEntry *entry,
 410                                      TransliteratorAlias*& aliasReturn,
 411                                      UErrorCode& status);
 412
 413     /**
 414      * A StringEnumeration over the registered IDs in this object.
 415      */
 416     class Enumeration : public StringEnumeration {
 417     public:
 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;
 425     private:
 426         int32_t index;
 427         const TransliteratorRegistry& reg;
 428     };
 429     friend class Enumeration;
 430
 431  private:
 432
 433     /**
 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
 437      * specDAG or not.
 438      */
 439     Hashtable registry;
 440
 441     /**
 442      * DAG of visible IDs by spec.  Hashtable: source => (Hashtable:
 443      * target => variant bitmask)
 444      */
 445     Hashtable specDAG;
 446
 447     /**
 448      * Vector of all variant names
 449      */
 450     UVector variantList;
 451
 452     /**
 453      * Vector of public full IDs.
 454      */
 455     UVector availableIDs;
 456
 457     TransliteratorRegistry(const TransliteratorRegistry &other); // forbid copying of this class
 458     TransliteratorRegistry &operator=(const TransliteratorRegistry &other); // forbid copying of this class
 459 };
 460
 461 U_NAMESPACE_END
 462
 463 U_CFUNC UBool utrans_transliterator_cleanup(void);
 464
 465 #endif /* #if !UCONFIG_NO_TRANSLITERATION */
 466
 467 #endif
 468 //eof