Ubuntu Manpage: Locale::Codes::Types - types of data sets supported

Provided by: liblocale-codes-perl_3.72-1_all

NAME

       Locale::Codes::Types - types of data sets supported

DESCRIPTION

       This document contains a description of different types of code sets supported by the
       Locale-Codes distribution.

       The following types are supported:

       "country"
       "language"
       "currency"
       "script"
       "langfam"
       "langvar"
       "langext"

       Any time you have to specify the type of data, use one of the values from this list.  When
       using the OO interface, you have to specify the type of data you are working with.  For
       example:

          use Locale::Codes;
          ...
          $obj->type('country');
          $obj->type('langext');

       When using the traditional interfaces, the functions all have the data type included in
       the function name.  For example:

          use Locale::Codes::Country;
          code2country(...);

          use Locale::Codes::LangExt;
          code2langext(...);

       Each type of data may have any number of code sets.  Code sets may be specified by name.
       Traditionally, a perl constant was exported and could also be used to specify the code
       set.

       Both methods are available for both the OO and traditional interfaces, so whenever a
       function or method takes an argument specifying a code set, either the name or a constant
       can be used.

       In the lists below, a code set is specified in the list by including the name and the
       constant.  So, for example, the first country code set is named 'alpha-2' and has a perl
       constant "LOCALE_COUNTRY_ALPHA_2" associated with it.  When using the OO interface, the
       constants are only available if you import them by loading the module with:

          use Locale::Codes ':constants';

       The constants are always available when using the traditional interfaces.

       Some of the older perl constants names were not consistent, and in those cases, two
       constants are available (a newer consistent name and the older inconsistent one).  Either
       may be used.

       The default code set for each type is marked with an asterisk (*).

country

Code sets for identifying countries are maintained by several different agencies and
standards.

The following code sets are maintained in the ISO 3166 standard. The official home page
for the ISO 3166 maintenance agency is:
<http://www.iso.org/iso/home/standards/country_codes.htm> .

Only the officially assigned codes are included.

* alpha-2, LOCALE_COUNTRY_ALPHA_2, LOCALE_CODE_ALPHA_2
This is the set of two-letter (lowercase) codes from ISO 3166-1, such as 'tv' for
Tuvalu.

alpha-3, LOCALE_COUNTRY_ALPHA_3, LOCALE_CODE_ALPHA_3
This is the set of three-letter (lowercase) codes from ISO 3166-1, such as 'brb' for
Barbados. These codes are actually defined and maintained by the U.N. Statistics
division.

numeric, LOCALE_COUNTRY_NUMERIC, LOCALE_CODE_NUMERIC
This is the set of three-digit numeric codes from ISO 3166-1, such as 064 for Bhutan.

If a 2-digit code is entered, it is converted to 3 digits by prepending a 0.

A list of domain names are maintained by the IANA (Internet Assigned Numbers Authority).
These are available at: <http://www.iana.org/domains/root/db/> . Only the actual country
codes are used, and the country names come from ISO 3166.

dom, LOCALE_COUNTRY_DOM, LOCALE_CODE_DOM
The country domains assigned by IANA are usually the two-letter (lowercase) codes from
ISO 3166, but there are a few other additions.

The United Nations also maintains country lists. Their list is also similar, but not
identical, to the ISO 3166 list.

The data is available here: <https://unstats.un.org/unsd/methodology/m49/>

Previously, this table was treated as a source of the ISO 3166 data, but I found that the
table was incomplete, so I stopped using it. Later, it was added back in as it's own list
of codes.

un-alpha-3, LOCALE_COUNTRY_UN_ALPHA_3, LOCALE_CODE_UN_ALPHA_3
This is similar to the 'alpha-3' set from ISO 3166, except that the codes are
uppercase.

un-numeric, LOCALE_COUNTRY_UN_NUMERIC, LOCALE_CODE_UN_NUMERIC
This is similar to the 'numeric' set from ISO 3166.

The US Government also keeps a list of codes. Originally, it maintained the FIPS-11 code
set, but this was deprecated and replaced by the GENC code set. The FIPS-11 code sets are
no longer supported by Locale-Codes.

The GENC code sets are available here: <https://nsgreg.nga.mil/genc/discovery> . They are
also similar, but not identical, to the ISO 3166 code sets.

genc-alpha-2, LOCALE_COUNTRY_GENC_ALPHA_2, LOCALE_CODE_GENC_ALPHA_2
Similar to the 'alpha-2' set, but uppercase.

genc-alpha-3, LOCALE_COUNTRY_GENC_ALPHA_3, LOCALE_CODE_GENC_ALPHA_3
Similar to the 'alpha-3' set, but uppercase.

genc-numeric, LOCALE_COUNTRY_GENC_NUMERIC, LOCALE_CODE_GENC_NUMERIC
Similar to the 'numeric' set.

There are other sources of codes that are not currently used in this distribution.

ISO codes for country sub-divisions (states, counties, provinces, etc), as defined in ISO
3166-2. This module is not part of the Locale-Codes distribution, but is available from
CPAN in CPAN/modules/by-module/Locale/

The World Factbook maintained by the CIA is a potential source of the data.
Unfortunately, it adds/preserves non-standard codes, so it is not used as a source of
data.
<https://www.cia.gov/library/publications/the-world-factbook/appendix/appendix-d.html>

Another unofficial source of data is the Statoids web site:
<http://www.statoids.com/wab.html> . Currently, it is not used to get data, but the notes
and explanatory material were very useful for understanding discrepancies between the
sources.

language

       Code sets for identifying languages come from a couple different locations.

       The primary source is ISO 639 .  The ISO 639-2 codes are available here:
       <http://www.loc.gov/standards/iso639-2/> and the ISO 639-5 codes are available here:
       <http://www.loc.gov/standards/iso639-5/> .

       In addition, the IANA maintains a language registry which are added to the ISO lists.
       Because it is intended to supplement the ISO standard, the IANA list is not separate.

       The IANA data is available here:
       <http://www.iana.org/assignments/language-subtag-registry>

       The code sets are:

       * alpha-2, LOCALE_LANGUAGE_ALPHA_2, LOCALE_LANG_ALPHA_2
           This is the set of two-letter (lowercase) codes from ISO 639-1, such as 'he' for
           Hebrew.  It also includes additions to this set included in the IANA language
           registry.

       alpha-3, LOCALE_LANGUAGE_ALPHA_3, LOCALE_LANG_ALPHA_3
           This is the set of three-letter (lowercase) bibliographic codes from ISO 639-2 and
           639-5, such as 'heb' for Hebrew.  It also includes additions to this set included in
           the IANA language registry.

       term, LOCALE_LANGUAGE_TERM, LOCALE_LANG_TERM
           This is the set of three-letter (lowercase) terminologic codes from ISO 639.

currency

       The source of currency codes is the ISO 4217 data available here:
       <http://www.iso.org/iso/support/currency_codes_list-1.htm>

       The code sets are:

       * alpha, LOCALE_CURRENCY_ALPHA, LOCALE_CURR_ALPHA
           This is a set of three-letter (uppercase) codes from ISO 4217 such as EUR for Euro.

           Two of the codes specified by the standard (XTS which is reserved for testing purposes
           and XXX which is for transactions where no currency is involved) are omitted.

       num, LOCALE_CURRENCY_NUMERIC, LOCALE_CURR_NUMERIC
           This is the set of three-digit numeric codes from ISO 4217.

script

       The source of script code sets is ISO 15924 available here:
       <http://www.unicode.org/iso15924/>

       Additional data comes from the IANA language subtag registry:
       <http://www.iana.org/assignments/language-subtag-registry> .

       Code sets are:

       * alpha, LOCALE_SCRIPT_ALPHA
           This is a set of four-letter (capitalized) codes from ISO 15924 such as 'Phnx' for
           Phoenician.  It also includes additions to this set included in the IANA language
           registry.

           The Zxxx, Zyyy, and Zzzz codes are not used.

       num, LOCALE_SCRIPT_NUMERIC
           This is a set of three-digit numeric codes from ISO 15924 such as 115 for Phoenician.

langfam

       Language families are specified using codes from ISO 639-5 available here:
       <http://www.loc.gov/standards/iso639-5/id.php>

       Code sets are:

       * alpha, LOCALE_LANGFAM_ALPHA
           This is the set of three-letter (lowercase) codes from ISO 639-5 such as 'apa' for
           Apache languages.

langvar

       Language variations are specified using codes from he IANA language subtag registry
       available here: <http://www.iana.org/assignments/language-subtag-registry>

       Code sets are:

       * alpha, LOCALE_LANGVAR_ALPHA
           This is the set of alphanumeric codes from the IANA language registry, such as
           'arevela' for Eastern Armenian.

langext

       Language extensions are specified using codes from he IANA language subtag registry
       available here: <http://www.iana.org/assignments/language-subtag-registry>

       Code sets are:

       * alpha, LOCALE_LANGEXT_ALPHA
           This is the set of three-letter (lowercase) codes from the IANA language registry,
           such as 'acm' for Mesopotamian Arabic.

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. However, I will always be hesitant to accept a
non-official source.

As an example, I used to 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. However, even in this case, I found that they were
adding codes that were not part of the standard, so I have stopped using them as a
source.

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.

AUTHOR

       See Locale::Codes for full author history.

       Currently maintained by Sullivan Beck (sbeck@cpan.org).

COPYRIGHT

          Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
          Copyright (c) 2001-2010 Neil Bowers
          Copyright (c) 2010-2022 Sullivan Beck

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