Locale::Codes(3pm)

1Locale::Codes(3)      User Contributed Perl Documentation     Locale::Codes(3)
2
3
4

NAME

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

DESCRIPTION

9       Locale-Codes is a distribution containing a set of modules.  The
10       modules each deal with different types of codes which identify parts of
11       the locale including languages, countries, currency, etc.
12
13       Currently, the following modules are included:
14
15       Locale::Codes::Country, Locale::Country
16           This includes support for country codes (such as those listed in
17           ISO-3166) to specify the country.
18
19           Because this module was originally distributed as Locale::Country,
20           it is also available under that name.
21
22       Locale::Codes::Language, Locale::Language
23           This includes support for language codes (such as those listed in
24           ISO-639) to specify the language.
25
26           Because this module was originally distributed as Locale::Language,
27           it is also available under that name.
28
29       Locale::Codes::Currency, Locale::Currency
30           This includes support for currency codes (such as those listed in
31           ISO-4217) to specify the currency.
32
33           Because this module was originally distributed as Locale::Currency,
34           it is also available under that name.
35
36       Locale::Codes::Script, Locale::Script
37           This includes support for script codes (such as those listed in
38           ISO-15924) to specify the script.
39
40           Because this module was originally distributed as Locale::Script,
41           it is also available under that name.
42
43       Locale::Codes::LangExt
44           This includes support for language extension codes (such as those
45           listed in the IANA language registry) to specify the language
46           extension.
47
48       Locale::Codes::LangVar
49           This includes support for language variation codes (such as those
50           listed in the IANA language registry) to specify the language
51           variation.
52
53       Locale::Codes::LangFam
54           This includes support for language family codes (such as those
55           listed in ISO 639-5) to specify families of languages.
56
57       Each module can support an arbitrary number of code sets, and it is not
58       required that the relationship between these code sets be one-to-one.
59       For example, the Locale::Codes::Country module supports code sets from
60       ISO-3166 and the FIPS 10 standard, and they do not break the world down
61       into exactly the same sets of countries. This does not cause any
62       problem (though converting codes from ISO-3166 to FIPS or back will not
63       work except for countries that are one-to-one).
64
65       All data in all of these modules comes directly from the original
66       standards (or as close to direct as possible), so it should be up-to-
67       date at the time of release.
68
69       I plan on releasing a new version several times a year to incorporate
70       any changes made in the standards. However, I don't always know about
71       changes that occur, so if any of the standards change, and you want a
72       new release sooner, just email me and I'll get one out.
73
74       In addition to the modules above, there are a number of support modules
75       included in the distribution including:
76
77       Locale::Codes
78       Locale::Codes::Constants
79       Locale::Codes::Country_codes
80       Locale::Codes::Language_codes
81       Locale::Codes::Currency_codes
82       Locale::Codes::Script_codes
83       Locale::Codes::LangExt_codes
84       Locale::Codes::LangVar_codes
85       Locale::Codes::LangFam_codes
86
87       These modules are not intended to be used by programmers. They contain
88       functions or data that are used by the modules listed above.
89

NEW CODE SETS

91       I'm always open to suggestions for new code sets.
92
93       In order for me to add a code set, I want the following criteria to be
94       met:
95
96       General-use code set
97           If a code set is not general use, I'm not likely to spend the time
98           to add and support it.
99
100       An official source of data
101           I require an official (or at least, a NEARLY official) source where
102           I can get the data on a regular basis.
103
104           Ideally, I'd only get data from an official source, but sometimes
105           that is not possible. For example the ISO standards are not
106           typically available for free, so I may have to get some of that
107           data from alternate sources that I'm confident are getting their
108           data from the official source.  However, I will always be hesitant
109           to accept a non-official source.
110
111           As an example, I used to get some country data from the CIA World
112           Factbook. Given the nature of the source, I'm sure they're updating
113           data from the official sources and I consider it "nearly" official.
114           However, even in this case, I found that they were adding codes
115           that were not part of the standard, so I have stopped using them as
116           a source.
117
118           There are many 3rd party sites which maintain lists (many of which
119           are actually in a more convenient form than the official sites).
120           Unfortunately, I will reject most of them since I have no feel for
121           how "official" they are.
122
123       A free source of the data
124           Obviously, the data must be free-of-charge. I'm not interested in
125           paying for the data (and I'm not interested in the overhead of
126           having someone else pay for the data for me).
127
128       A reliable source of data
129           The source of data must come from a source that I can reasonably
130           expect to exist for the foreseeable future since I will be
131           extremely reluctant to drop support for a data set once it's
132           included.
133
134           I am also reluctant to accept data sent to me by an individual.
135           Although I appreciate the offer, it is simply not practical to
136           consider an individual contribution as a reliable source of data.
137           The source should be an official agency of some sort.
138
139       These requirements are open to discussion. If you have a code set you'd
140       like to see added, but which may not meet all of the above
141       requirements, feel free to email me and we'll discuss it.  Depending on
142       circumstances, I may be willing to waive some of these criteria.
143

COMMON ALIASES

145       As of version 2.00, the modules supported common variants of names.
146
147       For example, Locale::Country supports variant names for countries, and
148       a few of the most common ones are included in the data. The country
149       code for "United States" is "us", so:
150
151          country2code('United States');
152             => "us"
153
154       Now the following will also return 'us':
155
156          country2code('United States of America');
157          country2code('USA');
158
159       Any number of common aliases may be included in the data, in addition
160       to the names that come directly from the standards.  If you have a
161       common alias for a country, language, or any other of the types of
162       codes, let me know and I'll add it, with some restrictions.
163
164       For example, the country name "North Korea" never appeared in any of
165       the official sources (instead, it was "Korea, North" or "Korea,
166       Democratic People's Republic of". I would honor a request to add an
167       alias "North Korea" since that's a very common way to specify the
168       country (please don't request this... I've already added it).
169
170       On the other hand, a request to add Zaire as an alias for "Congo, The
171       Democratic Republic of" will not be honored. The country's official
172       name is no longer Zaire, so adding it as an alias violates the
173       standard.  Zaire was kept as an alias in versions prior to 3.00, but it
174       has been removed. Other aliases (if any) which no longer appear in any
175       standard (and which are not common variations of the name in the
176       standards) have also been removed.
177

DEPRECATED CODES

179       Occasionally, a code is deprecated, but it may still be desirable to
180       have access to it.
181
182       Although there is no way to see every code that has ever existed and
183       been deprecated (since most codesets do not have that information
184       available), as of version 3.20, every code which has ever been included
185       in these modules can be referenced.
186
187       For more information, refer to the documentation on the code2XXX,
188       XXX2code, all_XXX_codes, and all_XXX_names function in the
189       Locale::Codes::API documentation.
190

AUTHOR

221       Locale::Country and Locale::Language were originally written by Neil
222       Bowers at the Canon Research Centre Europe (CRE). They maintained the
223       distribution from 1997 to 2001.
224
225       Locale::Currency was originally written by Michael Hennecke and was
226       modified by Neil Bowers for inclusion in the distribution.
227
228       From 2001 to 2004, maintenance was continued by Neil Bowers.  He
229       modified Locale::Currency for inclusion in the distribution. He also
230       added Locale::Constants and Locale::Script.
231
232       From 2004-2009, the module was unmaintained.
233
234       In 2010, maintenance was taken over by Sullivan Beck (sbeck@cpan.org)
235       with Neil Bower's permission.  All problems or comments should be sent
236       there.  Alternately, problems can be reported using the perl problem
237       tracker at:
238
239          https://rt.cpan.org/Dist/Display.html?Queue=Locale-Codes
240

COPYRIGHT

242          Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
243          Copyright (c) 2001      Michael Hennecke (Locale::Currency)
244          Copyright (c) 2001-2010 Neil Bowers
245          Copyright (c) 2010-2013 Sullivan Beck
246
247       This module is free software; you can redistribute it and/or modify it
248       under the same terms as Perl itself.
249
250
251
252perl v5.16.3                      2013-05-29                  Locale::Codes(3)