NAME
    Locale::Codes - a distribution of modules to handle locale codes

DESCRIPTION
    Locale::Codes is a distribution containing a set of modules. The modules
    each deal with different types of codes which identify parts of the
    locale including languages, countries, currency, etc.

    Currently, the following modules are included:

    Locale::Country
        This includes support for country codes (such as those listed in
        ISO-3166) to specify the country.

    Locale::Language
        This includes support for language codes (such as those listed in
        ISO-639) to specify the language.

    Locale::Currency
        This includes support for currency codes (such as those listed in
        ISO-4217) to specify the currency.

    Locale::Script
        This includes support for script codes (such as those listed in
        ISO-15924) to specify the script.

    Each module can support an arbitrary number of code sets, and it it not
    required that the relationship between these code sets be one-to-one.
    For example, the Locale::Country module supports code sets from ISO-3166
    and the FIPS 10 standard, and they do not break the world down into
    exactly the same sets of countries. This does not cause any problem
    (though converting codes from ISO-3166 to FIPS or back will not work
    except for countries that are one-to-one).

    All data in all of these modules comes directly from the original
    standards (or as close to direct as possible), so it should be
    up-to-date at the time of release.

    I plan on releasing a new version a couple of times a year to
    incorporate any changes made in the standards. However, I don't always
    know about changes that occur, so if any of the standards change, and
    you want a new release sooner, just email me and I'll get one out.

NEW CODE SETS
    I'm always open to suggestions for new code sets.

    In order for me to add a code set, I want the following criteria to be
    met:

    General-use code set
        If a code set is not general use, I'm not likely to spend the time
        to add and support it.

    An official source of data
        I require an official (or at least, a NEARLY official) source where
        I can get the data on a regular basis.

        Ideally, I'd only get data from an official source, but sometimes
        that is not possible. For example the ISO standards are not
        typically available for free, so I may have to get some of that data
        from alternate sources that I'm confident are getting their data
        from the official source.

        As an example, I get some country data from the CIA World Factbook.
        Given the nature of the source, I'm sure they're updating data from
        the official sources and I consider it "nearly" official.

        There are many 3rd party sites which maintain lists (many of which
        are actually in a more convenient form than the official sites).
        Unfortunately, I will reject most of them since I have no feel for
        how "official" they are.

    A free source of the data
        Obviously, the data must be free-of-charge. I'm not interested in
        paying for the data (and I'm not interested in the overhead of
        having someone else pay for the data for me).

    A reliable source of data
        The source of data must come from a source that I can reasonably
        expect to exist for the foreseeable future since I will be extremely
        reluctant to drop support for a data set once it's included.

        I am also reluctant to accept data sent to me by an individual.
        Although I appreciate the offer, it is simply not practical to
        consider an individual contribution as a reliable source of data.
        The source should be an official agency of some sort.

    These requirements are open to discussion. If you have a code set you'd
    like to see added, but which may not meet all of the above requirements,
    feel free to email me and we'll discuss it. Depending on circumstances,
    I may be willing to waive some of these criteria.

COMMON ALIASES
    As of version 2.00, the modules supported common variants of names.

    For example, Locale::Country supports variant names for countries, and a
    few of the most common ones are included in the data. The country code
    for "United States" is "us", so:

       country2code('United States');
          => "us"

    Now the following will also return 'us':

       country2code('United States of America');
       country2code('USA');

    Any number of common aliases may be included in the data, in addition to
    the names that come directly from the standards. If you have a common
    alias for a country, language, or any other of the types of codes, let
    me know and I'll add it, with some restrictions.

    For example, the country name "North Korea" never appeared in any of the
    official sources (instead, it was "Korea, North" or "Korea, Democratic
    People's Republic of". I would honor a request to add an alias "North
    Korea" since that's a very common way to specify the country (please
    don't request this... I've already added it).

    On the other hand, a request to add Zaire as an alias for "Congo, The
    Democratic Republic of" may not be honored. The country's official name
    is not Zaire, so adding it as an alias violates the standard. Zaire was
    kept as an alias in versions prior to 3.00, but it has been removed.
    Other aliases (if any) which no longer appear in any standard have also
    been removed.

ROUTINES
    As of 3.10, the interface for all of the modules listed above are
    identical (as a matter of fact, they are all just wrappers around a
    central module which does all the real work).

    In order to maintain the documentation for the modules consistently, the
    functions are all documented here, rather than in the documentation for
    the separate modules.

    The name of the function depends on the module. For example, every
    module contains a function "code2XXX" where XXX refers to the type of
    data (country, language, currency, or script). So, the Locale::Country
    module contains the function code2country, the Locale::Language module
    contains the function code2language, etc.

    In all of the functions below, CODE refers to a code for one element in
    the code set. For example, in the two-letter country codes from ISO
    3166-1, the code 'fi' is used to refer to the country Finland. CODE is
    always case insensitive (though when a code is returned, it will always
    be in the case as used in the standard), so 'fi', 'FI', and 'Fi' would
    all be equivalent.

    CODESET refers to a constant specified in the documentation for each
    module to label the various code sets. For example, in the
    Locale::Language module, CODESET could be LOCALE_CODE_ALPHA_2 or
    LOCALE_CODE_ALPHA_3 (among others). Most functions have a default one,
    so they do not need to be specified. So the following calls are valid:

       code2country("fi");
       code2country("fi",LOCALE_CODE_ALPHA_2);
       code2country("fin",LOCALE_CODE_ALPHA_3);

    Since LOCALE_CODE_ALPHA_2 is the default code set, the first two are
    identical.

    code2country ( CODE [,CODESET] )
    code2language( CODE [,CODESET] )
    code2currency( CODE [,CODESET] )
    code2script ( CODE [,CODESET] )
        These functions take a code and returns a string which contains the
        name of the element identified. If the code is not a valid code in
        the CODESET specified then "undef" will be returned.

        The name of the element is the name as specified in the standard,
        and as a result, different variations of an element name may be
        returned for different values of CODESET.

        For example, the alpha-2 country code set defines the two-letter
        code "bo" to be "Bolivia, Plurinational State of", whereas the
        alpha-3 code set defines the code 'bol' to be the country "Bolivia
        (Plurinational State of)". So:

           code2country('bo',LOCALE_CODE_ALPHA_2);
              => 'Bolivia, Plurinational State of'

           code2country('bol',LOCALE_CODE_ALPHA_3);
              => 'Bolivia (Plurinational State of)'

    country2code ( NAME [,CODESET] )
    language2code( NAME [,CODESET] )
    currency2code( NAME [,CODESET] )
    script2code ( NAME [,CODESET] )
        These functions takes the name of an element (or any of it's
        aliases) and returns the code that corresponds to it, if it exists.
        If NAME could not be identified as the name of one of the elements,
        then "undef" will be returned.

        The name is not case sensitive. Also, any known variation of a name
        may be passed in.

        For example, even though the country name returned using
        LOCALE_CODE_ALPHA_2 and LOCALE_CODE_ALPHA_3 country codes for
        Bolivia is different, either country name may be passed in since for
        each code set, in addition to the alias 'Bolivia'. So:

           country2code('Bolivia, Plurinational State of',
                        LOCALE_CODE_ALPHA_2);
              => bo

           country2code('Bolivia (Plurinational State of)',
                        LOCALE_CODE_ALPHA_2);
              => bo

           country2code('Bolivia',LOCALE_CODE_ALPHA_2);
              => bo

    country_code2code ( CODE ,CODESET ,CODESET2 )
    language_code2code( CODE ,CODESET ,CODESET2 )
    currency_code2code( CODE ,CODESET ,CODESET2 )
    script_code2code ( CODE ,CODESET ,CODESET2 )
        These functions takes a a code from one code set, and returns the
        corresponding code from another code set. CODE must exists in the
        code set specified by CODESET and must have a corresponding code in
        the code set specified by CODESET2 or "undef" will be returned.

        Both CODESETs must be explicitly entered.

           country_code2code('fin', LOCALE_CODE_ALPHA_3,
                             LOCALE_CODE_ALPHA_2);
              => 'fi'

    all_country_codes ( [CODESET] )
    all_language_codes( [CODESET] )
    all_currency_codes( [CODESET] )
    all_script_codes ( [CODESET] )
        These returns a list of all code in the code set. The codes will be
        sorted.

    all_country_names ( [CODESET] )
    all_language_names( [CODESET] )
    all_currency_names( [CODESET] )
    all_script_names ( [CODESET] )
        These return a list of all elements names for which there is a
        corresponding code in the specified code set.

        The names returned are exactly as they are specified in the
        standard, and are sorted.

        Since not all elements are listed in all code sets, the list of
        elements may differ depending on the code set specified.

SEMI-PRIVATE ROUTINES
    Additional semi-private routines which may be used to modify the
    internal data are also available. Given their status, they aren't
    exported, and so need to be called by prefixing the function name with
    the package name.

    Locale::Country::rename_country ( CODE ,NEW_NAME [,CODESET] )
    Locale::Language::rename_language( CODE ,NEW_NAME [,CODESET] )
    Locale::Currency::rename_currency( CODE ,NEW_NAME [,CODESET] )
    Locale::Script::rename_script ( CODE ,NEW_NAME [,CODESET] )
        These routines are used to change the official name of an element.
        At that point, the name returned by the code2XXX routine would be
        NEW_NAME instead of the name specified in the standard.

        The original name will remain as an alias.

        For example, the official country name for code 'gb' is 'United
        Kingdom'. If you want to change that, you might call:

           Locale::Country::rename_country('gb', 'Great Britain');

        This means that calling code2country('gb') will now return 'Great
        Britain' instead of 'United Kingdom'.

        If any error occurs, a warning is issued and 0 is returned. An error
        occurs if CODE doesn't exist in the specified code set, or if
        NEW_NAME is already in use but for a different element.

        If the routine succeeds, 1 is returned.

    Locale::Country::add_country ( CODE ,NAME [,CODESET] )
    Locale::Language::add_language( CODE ,NAME [,CODESET] )
    Locale::Currency::add_currency( CODE ,NAME [,CODESET] )
    Locale::Script::add_script ( CODE ,NAME [,CODESET] )
        These routines are used to add a new code and name to the data.

        Both CODE and NAME must be unused in the data set or an error occurs
        (though NAME may be used in a different data set).

        For example, to create the fictitious country named "Duchy of Grand
        Fenwick" with codes "gf" and "fen", use the following:

           Locale::Country::add_country("fe","Duchy of Grand Fenwick",
                                        LOCALE_CODE_ALPHA_2);

           Locale::Country::add_country("fen","Duchy of Grand Fenwick",
                                        LOCALE_CODE_ALPHA_3);

        The return value is 1 on success, 0 on an error.

    Locale::Country::delete_country ( CODE [,CODESET] )
    Locale::Language::delete_language( CODE [,CODESET] )
    Locale::Currency::delete_currency( CODE [,CODESET] )
    Locale::Script::delete_script ( CODE [,CODESET] )
        These routines are used to delete a code from the data.

        CODE must refer to an existing code in the code set.

        The return value is 1 on success, 0 on an error.

    Locale::Country::add_country_alias ( NAME ,NEW_NAME )
    Locale::Language::add_language_alias( NAME ,NEW_NAME )
    Locale::Currency::add_currency_alias( NAME ,NEW_NAME )
    Locale::Script::add_script_alias ( NAME ,NEW_NAME )
        These routines are used to add a new alias to the data. They do not
        alter the return value of the code2XXX function.

        NAME must be an existing element name, and NEW_NAME must be unused
        or an error occurs.

        The return value is 1 on success, 0 on an error.

    Locale::Country::delete_country_alias ( NAME )
    Locale::Language::delete_language_alias( NAME )
    Locale::Currency::delete_currency_alias( NAME )
    Locale::Script::delete_script_alias ( NAME )
        These routines are used to delete an alias from the data. Once
        removed, the element may not be referred to by NAME.

        NAME must be one of a list of at least two names that may be used to
        specify an element. If the element may only be referred to by a
        single name, you'll need to use the add_XXX_alias function to add a
        new alias first, or the remove_XXX function to remove the element
        entirely.

        If the alias is used as the name in any code set, one of the other
        names will be used instead. Predicting exactly which one will be
        used requires you to know the order in which the standards were
        read, which is not reliable, so you may want to use the rename_XXX
        function to force one of the alternate names to be used.

        The return value is 1 on success, 0 on an error.

    Locale::Country::rename_country_code ( CODE ,NEW_CODE [,CODESET] )
    Locale::Language::rename_language_code( CODE ,NEW_CODE [,CODESET] )
    Locale::Currency::rename_currency_code( CODE ,NEW_CODE [,CODESET] )
    Locale::Script::rename_script_code ( CODE ,NEW_CODE [,CODESET] )
        These routines are used to change the official code for an element.
        At that point, the code returned by the XXX2code routine would be
        NEW_CODE instead of the code specified in the standard.

        NEW_CODE may either be a code that is not in use, or it may be an
        alias for CODE (in which case, CODE becomes and alias and NEW_CODE
        becomes the "real" code).

        The original code is kept as an alias, so that the code2XXX routines
        will work with either the code from the standard or the new code.

        However, the all_XXX_codes routine will only return the codes which
        are considered "real" (which means that the list of codes will now
        contain NEW_CODE, but will not contain CODE).

    Locale::Country::add_country_code_alias ( CODE ,NEW_CODE [,CODESET] )
    Locale::Language::add_language_code_alias( CODE ,NEW_CODE [,CODESET] )
    Locale::Currency::add_currency_code_alias( CODE ,NEW_CODE [,CODESET] )
    Locale::Script::add_script_code_alias ( CODE ,NEW_CODE [,CODESET] )
        These routines add an alias for the code. At that point, NEW_CODE
        and CODE will both work in the code2XXX routines. However, the
        XXX2code routines will still return the original code.

    Locale::Country::delete_country_code_alias ( CODE [,CODESET] )
    Locale::Language::delete_language_code_alias( CODE [,CODESET] )
    Locale::Currency::delete_currency_code_alias( CODE [,CODESET] )
    Locale::Script::delete_script_code_alias ( CODE [,CODESET] )
        These routines delete an alias for the code.

        These will only work if CODE is actually an alias. If it is the
        "real" code, it will not be deleted. You will need to use the
        rename_XXX_code function to switch the real code with one of the
        aliases, and then delete the alias.

KNOWN BUGS AND LIMITATIONS
    *   Because each code set uses a slightly different list of elements,
        and they are not necessarily one-to-one, there may be some confusion
        about the relationship between codes from different code sets.

        For example, ISO 3166 assigns one code to the country "United States
        Minor Outlying Islands", but the FIPS 10 codes give different codes
        to different islands (Baker Island, Howland Island, etc.).

        This may cause some confusion... I've done the best that I could do
        to minimize it.

    *   Currently all names must be all ASCII. I plan on relaxing that
        limitation in the future.

SEE ALSO
    Locale::Constants
        Constants for Locale codes.

    Locale::Country
        Codes for identification of countries.

    Locale::Language
        Codes for identification of languages.

    Locale::Script
        Codes for identification of scripts.

    Locale::Currency
        Codes for identification of currencies and funds.

AUTHOR
    Locale::Country and Locale::Language were originally written by Neil
    Bowers at the Canon Research Centre Europe (CRE). They maintained the
    distribution from 1997 to 2001.

    Locale::Currency was originally written by Michael Hennecke.

    From 2001 to 2004, maintenance was continued by Neil Bowers. He modified
    Locale::Currency for inclusion in the distribution. He also added
    Locale::Constants and Locale::Script.

    From 2004-2009, the module was unmaintained.

    In 2010, maintenance was taken over by Sullivan Beck (sbeck@cpan.org)
    with Neil Bower's permission.

COPYRIGHT
       Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
       Copyright (c) 2001      Michael Hennecke (Locale::Currency)
       Copyright (c) 2001-2010 Neil Bowers
       Copyright (c) 2010-2010 Sullivan Beck

    This module is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

