Check in the pristine copy of ICU 4.6...

icu46/source/i18n/transreg.h

+/*
+**********************************************************************
+*   Copyright (c) 2001-2008, International Business Machines
+*   Corporation and others.  All Rights Reserved.
+**********************************************************************
+*   Date        Name        Description
+*   08/10/2001  aliu        Creation.
+**********************************************************************
+*/
+#ifndef _TRANSREG_H
+#define _TRANSREG_H
+
+#include "unicode/utypes.h"
+
+#if !UCONFIG_NO_TRANSLITERATION
+
+#include "unicode/uobject.h"
+#include "unicode/translit.h"
+#include "hash.h"
+#include "uvector.h"
+
+U_NAMESPACE_BEGIN
+
+class TransliteratorEntry;
+class TransliteratorSpec;
+class UnicodeString;
+
+//------------------------------------------------------------------
+// TransliteratorAlias
+//------------------------------------------------------------------
+
+/**
+ * A TransliteratorAlias object is returned by get() if the given ID
+ * actually translates into something else.  The caller then invokes
+ * the create() method on the alias to create the actual
+ * transliterator, and deletes the alias.
+ *
+ * Why all the shenanigans?  To prevent circular calls between
+ * the registry code and the transliterator code that deadlocks.
+ */
+class TransliteratorAlias : public UMemory {
+ public:
+    /**
+     * Construct a simple alias (type == SIMPLE)
+     * @param aliasID the given id.
+     */
+    TransliteratorAlias(const UnicodeString& aliasID, const UnicodeSet* compoundFilter);
+
+    /**
+     * Construct a compound RBT alias (type == COMPOUND)
+     */
+    TransliteratorAlias(const UnicodeString& ID, const UnicodeString& idBlocks,
+                        UVector* adoptedTransliterators,
+                        const UnicodeSet* compoundFilter);
+
+    /**
+     * Construct a rules alias (type = RULES)
+     */
+    TransliteratorAlias(const UnicodeString& theID,
+                        const UnicodeString& rules,
+                        UTransDirection dir);
+
+    ~TransliteratorAlias();
+
+    /**
+     * The whole point of create() is that the caller must invoke
+     * it when the registry mutex is NOT held, to prevent deadlock.
+     * It may only be called once.
+     *
+     * Note: Only call create() if isRuleBased() returns FALSE.
+     *
+     * This method must be called *outside* of the TransliteratorRegistry
+     * mutex.
+     */
+    Transliterator* create(UParseError&, UErrorCode&);
+
+    /**
+     * Return TRUE if this alias is rule-based.  If so, the caller
+     * must call parse() on it, then call TransliteratorRegistry::reget().
+     */
+    UBool isRuleBased() const;
+
+    /**
+     * If isRuleBased() returns TRUE, then the caller must call this
+     * method, followed by TransliteratorRegistry::reget().  The latter
+     * method must be called inside the TransliteratorRegistry mutex.
+     *
+     * Note: Only call parse() if isRuleBased() returns TRUE.
+     *
+     * This method must be called *outside* of the TransliteratorRegistry
+     * mutex, because it can instantiate Transliterators embedded in
+     * the rules via the "&Latin-Arabic()" syntax.
+     */
+    void parse(TransliteratorParser& parser,
+               UParseError& pe, UErrorCode& ec) const;
+
+ private:
+    // We actually come in three flavors:
+    // 1. Simple alias
+    //    Here aliasID is the alias string.  Everything else is
+    //    null, zero, empty.
+    // 2. CompoundRBT
+    //    Here ID is the ID, aliasID is the idBlock, trans is the
+    //    contained RBT, and idSplitPoint is the offet in aliasID
+    //    where the contained RBT goes.  compoundFilter is the
+    //    compound filter, and it is _not_ owned.
+    // 3. Rules
+    //    Here ID is the ID, aliasID is the rules string.
+    //    idSplitPoint is the UTransDirection.
+    UnicodeString ID;
+    UnicodeString aliasesOrRules;
+    UVector* transes; // owned
+    const UnicodeSet* compoundFilter; // alias
+    UTransDirection direction;
+    enum { SIMPLE, COMPOUND, RULES } type;
+
+    TransliteratorAlias(const TransliteratorAlias &other); // forbid copying of this class
+    TransliteratorAlias &operator=(const TransliteratorAlias &other); // forbid copying of this class
+};
+
+
+/**
+ * A registry of system transliterators.  This is the data structure
+ * that implements the mapping between transliterator IDs and the data
+ * or function pointers used to create the corresponding
+ * transliterators.  There is one instance of the registry that is
+ * created statically.
+ *
+ * The registry consists of a dynamic component -- a hashtable -- and
+ * a static component -- locale resource bundles.  The dynamic store
+ * is semantically overlaid on the static store, so the static mapping
+ * can be dynamically overridden.
+ *
+ * This is an internal class that is only used by Transliterator.
+ * Transliterator maintains one static instance of this class and
+ * delegates all registry-related operations to it.
+ *
+ * @author Alan Liu
+ */
+class TransliteratorRegistry : public UMemory {
+
+ public:
+
+    /**
+     * Contructor
+     * @param status Output param set to success/failure code.
+     */
+    TransliteratorRegistry(UErrorCode& status);
+
+    /**
+     * Nonvirtual destructor -- this class is not subclassable.
+     */
+    ~TransliteratorRegistry();
+
+    //------------------------------------------------------------------
+    // Basic public API
+    //------------------------------------------------------------------
+
+    /**
+     * Given a simple ID (forward direction, no inline filter, not
+     * compound) attempt to instantiate it from the registry.  Return
+     * 0 on failure.
+     *
+     * Return a non-NULL aliasReturn value if the ID points to an alias.
+     * We cannot instantiate it ourselves because the alias may contain
+     * filters or compounds, which we do not understand.  Caller should
+     * make aliasReturn NULL before calling.
+     * @param ID          the given ID
+     * @param aliasReturn output param to receive TransliteratorAlias;
+     *                    should be NULL on entry
+     * @param parseError  Struct to recieve information on position
+     *                    of error if an error is encountered
+     * @param status      Output param set to success/failure code.
+     */
+    Transliterator* get(const UnicodeString& ID,
+                        TransliteratorAlias*& aliasReturn,
+                        UErrorCode& status);
+
+    /**
+     * The caller must call this after calling get(), if [a] calling get()
+     * returns an alias, and [b] the alias is rule based.  In that
+     * situation the caller must call alias->parse() to do the parsing
+     * OUTSIDE THE REGISTRY MUTEX, then call this method to retry
+     * instantiating the transliterator.
+     *
+     * Note: Another alias might be returned by this method.
+     *
+     * This method (like all public methods of this class) must be called
+     * from within the TransliteratorRegistry mutex.
+     *
+     * @param aliasReturn output param to receive TransliteratorAlias;
+     *                    should be NULL on entry
+     */
+    Transliterator* reget(const UnicodeString& ID,
+                          TransliteratorParser& parser,
+                          TransliteratorAlias*& aliasReturn,
+                          UErrorCode& status);
+
+    /**
+     * Register a prototype (adopted).  This adds an entry to the
+     * dynamic store, or replaces an existing entry.  Any entry in the
+     * underlying static locale resource store is masked.
+     */
+    void put(Transliterator* adoptedProto,
+             UBool visible,
+             UErrorCode& ec);
+
+    /**
+     * Register an ID and a factory function pointer.  This adds an
+     * entry to the dynamic store, or replaces an existing entry.  Any
+     * entry in the underlying static locale resource store is masked.
+     */
+    void put(const UnicodeString& ID,
+             Transliterator::Factory factory,
+             Transliterator::Token context,
+             UBool visible,
+             UErrorCode& ec);
+
+    /**
+     * Register an ID and a resource name.  This adds an entry to the
+     * dynamic store, or replaces an existing entry.  Any entry in the
+     * underlying static locale resource store is masked.
+     */
+    void put(const UnicodeString& ID,
+             const UnicodeString& resourceName,
+             UTransDirection dir,
+             UBool readonlyResourceAlias,
+             UBool visible,
+             UErrorCode& ec);
+
+    /**
+     * Register an ID and an alias ID.  This adds an entry to the
+     * dynamic store, or replaces an existing entry.  Any entry in the
+     * underlying static locale resource store is masked.
+     */
+    void put(const UnicodeString& ID,
+             const UnicodeString& alias,
+             UBool readonlyAliasAlias,
+             UBool visible,
+             UErrorCode& ec);
+
+    /**
+     * Unregister an ID.  This removes an entry from the dynamic store
+     * if there is one.  The static locale resource store is
+     * unaffected.
+     * @param ID    the given ID.
+     */
+    void remove(const UnicodeString& ID);
+
+    //------------------------------------------------------------------
+    // Public ID and spec management
+    //------------------------------------------------------------------
+
+    /**
+     * Return a StringEnumeration over the IDs currently registered
+     * with the system.
+     * @internal
+     */
+    StringEnumeration* getAvailableIDs() const;
+
+    /**
+     * == OBSOLETE - remove in ICU 3.4 ==
+     * Return the number of IDs currently registered with the system.
+     * To retrieve the actual IDs, call getAvailableID(i) with
+     * i from 0 to countAvailableIDs() - 1.
+     * @return the number of IDs currently registered with the system.
+     * @internal
+     */
+    int32_t countAvailableIDs(void) const;
+
+    /**
+     * == OBSOLETE - remove in ICU 3.4 ==
+     * Return the index-th available ID.  index must be between 0
+     * and countAvailableIDs() - 1, inclusive.  If index is out of
+     * range, the result of getAvailableID(0) is returned.
+     * @param index the given index.
+     * @return the index-th available ID.  index must be between 0
+     *         and countAvailableIDs() - 1, inclusive.  If index is out of
+     *         range, the result of getAvailableID(0) is returned.
+     * @internal
+     */
+    const UnicodeString& getAvailableID(int32_t index) const;
+
+    /**
+     * Return the number of registered source specifiers.
+     * @return the number of registered source specifiers.
+     */
+    int32_t countAvailableSources(void) const;
+
+    /**
+     * Return a registered source specifier.
+     * @param index which specifier to return, from 0 to n-1, where
+     * n = countAvailableSources()
+     * @param result fill-in paramter to receive the source specifier.
+     * If index is out of range, result will be empty.
+     * @return reference to result
+     */
+    UnicodeString& getAvailableSource(int32_t index,
+                                      UnicodeString& result) const;
+
+    /**
+     * Return the number of registered target specifiers for a given
+     * source specifier.
+     * @param source the given source specifier.
+     * @return the number of registered target specifiers for a given
+     *         source specifier.
+     */
+    int32_t countAvailableTargets(const UnicodeString& source) const;
+
+    /**
+     * Return a registered target specifier for a given source.
+     * @param index which specifier to return, from 0 to n-1, where
+     * n = countAvailableTargets(source)
+     * @param source the source specifier
+     * @param result fill-in paramter to receive the target specifier.
+     * If source is invalid or if index is out of range, result will
+     * be empty.
+     * @return reference to result
+     */
+    UnicodeString& getAvailableTarget(int32_t index,
+                                      const UnicodeString& source,
+                                      UnicodeString& result) const;
+
+    /**
+     * Return the number of registered variant specifiers for a given
+     * source-target pair.  There is always at least one variant: If
+     * just source-target is registered, then the single variant
+     * NO_VARIANT is returned.  If source-target/variant is registered
+     * then that variant is returned.
+     * @param source the source specifiers
+     * @param target the target specifiers
+     * @return the number of registered variant specifiers for a given
+     *         source-target pair.
+     */
+    int32_t countAvailableVariants(const UnicodeString& source,
+                                   const UnicodeString& target) const;
+
+    /**
+     * Return a registered variant specifier for a given source-target
+     * pair.  If NO_VARIANT is one of the variants, then it will be
+     * at index 0.
+     * @param index which specifier to return, from 0 to n-1, where
+     * n = countAvailableVariants(source, target)
+     * @param source the source specifier
+     * @param target the target specifier
+     * @param result fill-in paramter to receive the variant
+     * specifier.  If source is invalid or if target is invalid or if
+     * index is out of range, result will be empty.
+     * @return reference to result
+     */
+    UnicodeString& getAvailableVariant(int32_t index,
+                                       const UnicodeString& source,
+                                       const UnicodeString& target,
+                                       UnicodeString& result) const;
+
+ private:
+
+    //----------------------------------------------------------------
+    // Private implementation
+    //----------------------------------------------------------------
+
+    TransliteratorEntry* find(const UnicodeString& ID);
+
+    TransliteratorEntry* find(UnicodeString& source,
+                UnicodeString& target,
+                UnicodeString& variant);
+
+    TransliteratorEntry* findInDynamicStore(const TransliteratorSpec& src,
+                              const TransliteratorSpec& trg,
+                              const UnicodeString& variant) const;
+
+    TransliteratorEntry* findInStaticStore(const TransliteratorSpec& src,
+                             const TransliteratorSpec& trg,
+                             const UnicodeString& variant);
+
+    static TransliteratorEntry* findInBundle(const TransliteratorSpec& specToOpen,
+                               const TransliteratorSpec& specToFind,
+                               const UnicodeString& variant,
+                               UTransDirection direction);
+
+    void registerEntry(const UnicodeString& source,
+                       const UnicodeString& target,
+                       const UnicodeString& variant,
+                       TransliteratorEntry* adopted,
+                       UBool visible);
+
+    void registerEntry(const UnicodeString& ID,
+                       TransliteratorEntry* adopted,
+                       UBool visible);
+
+    void registerEntry(const UnicodeString& ID,
+                       const UnicodeString& source,
+                       const UnicodeString& target,
+                       const UnicodeString& variant,
+                       TransliteratorEntry* adopted,
+                       UBool visible);
+
+    void registerSTV(const UnicodeString& source,
+                     const UnicodeString& target,
+                     const UnicodeString& variant);
+
+    void removeSTV(const UnicodeString& source,
+                   const UnicodeString& target,
+                   const UnicodeString& variant);
+
+    Transliterator* instantiateEntry(const UnicodeString& ID,
+                                     TransliteratorEntry *entry,
+                                     TransliteratorAlias*& aliasReturn,
+                                     UErrorCode& status);
+
+    /**
+     * A StringEnumeration over the registered IDs in this object.
+     */
+    class Enumeration : public StringEnumeration {
+    public:
+        Enumeration(const TransliteratorRegistry& reg);
+        virtual ~Enumeration();
+        virtual int32_t count(UErrorCode& status) const;
+        virtual const UnicodeString* snext(UErrorCode& status);
+        virtual void reset(UErrorCode& status);
+        static UClassID U_EXPORT2 getStaticClassID();
+        virtual UClassID getDynamicClassID() const;
+    private:
+        int32_t index;
+        const TransliteratorRegistry& reg;
+    };
+    friend class Enumeration;
+
+ private:
+
+    /**
+     * Dynamic registry mapping full IDs to Entry objects.  This
+     * contains both public and internal entities.  The visibility is
+     * controlled by whether an entry is listed in availableIDs and
+     * specDAG or not.
+     */
+    Hashtable registry;
+
+    /**
+     * DAG of visible IDs by spec.  Hashtable: source => (Hashtable:
+     * target => (UVector: variant)) The UVector of variants is never
+     * empty.  For a source-target with no variant, the special
+     * variant NO_VARIANT (the empty string) is stored in slot zero of
+     * the UVector.
+     */
+    Hashtable specDAG;
+
+    /**
+     * Vector of public full IDs.
+     */
+    UVector availableIDs;
+
+    TransliteratorRegistry(const TransliteratorRegistry &other); // forbid copying of this class
+    TransliteratorRegistry &operator=(const TransliteratorRegistry &other); // forbid copying of this class
+};
+
+U_NAMESPACE_END
+
+#endif /* #if !UCONFIG_NO_TRANSLITERATION */
+
+#endif
+//eof