1NAME
2 Locale::Codes - a distribution of modules to handle locale codes
3
4DESCRIPTION
5 Locale-Codes is a distribution containing a set of modules designed to
6 work with sets of codes which uniquely identify something. For example,
7 there are codes associated with different countries, different
8 currencies, different languages, etc. These sets of codes are typically
9 maintained in some standard.
10
11 This distribution provides a way to work with these lists of codes.
12 Because the data from the various standards is not available in any sort
13 of consistent API, access to the lists is not available in any direct
14 fashion. To compensate for this, the list of codes is stored internally
15 within this distribution, and the distribution is updated on a regular
16 basis to include all known codes at that point in time. This does mean
17 that it is necessary to keep this distribution up-to-date to keep up
18 with the various changes that are made in the various standards.
19
20 Traditionally, a module has been created to work with each type of code
21 sets. So, there is a module for working with country lists, one for
22 currency lists, etc. Since version 3.00, all of these individual modules
23 were written as wrappers around a central module (which was not intended
24 to be used directly) which did all of the real work.
25
26 Starting with version 3.50, the central module was reworked slightly to
27 provide an object-oriented interface. All of the modules for working
28 with individual types of code sets were reworked to use the improved OO
29 module, so the traditional interfaces still work as they always have. As
30 a result, you are free to use the traditional functional (non-OO)
31 interfaces, or to use the OO interface and bypass the wrapper modules
32 entirely.
33
34 Both methods will be supported in the future, so use the one that is
35 best suited to your needs.
36
37 Within each type, any number of code sets are allowed. For example, sets
38 of country codes are maintained in several different locations including
39 the ISO-3166 standard, the IANA, and by the United Nations. The lists of
40 countries are similar, but not identical. Multiple code sets are
41 supported, though trying to convert from one code set to another will
42 not always work since the list of countries is not one-to-one.
43
44 All data in all of these modules comes directly from the original
45 standards (or as close to direct as possible), so it should be
46 up-to-date at the time of release.
47
48 I plan on releasing a new version several times a year to incorporate
49 any changes made in the standards. However, I don't always know about
50 changes that occur, so if any of the standards change, and you want a
51 new release sooner, just email me and I'll get one out.
52
53SYNOPSIS (OBJECT-ORIENTED INTERFACE)
54 use Locale::Codes;
55 or
56 use Locale::Codes ':constants';
57
58 $obj = new Locale::Codes 'country';
59
60OBJECT-ORIENTED METHODS
61 The following methods are available.
62
63 In all methods, when specifying a code set, the name (as a string) is
64 always available.
65
66 Traditionally, you could also use a perl constant to specify the code
67 set. In order to do so with the OO interface, you have to import the
68 constants. To do that, load the module with:
69
70 use Locale::Codes ':constants';
71
72 new ( [TYPE [,CODESET]] )
73 $obj = new Locale::Codes;
74 $obj = new Locale::Codes 'country';
75 $obj = new Locale::Codes 'country','alpha-3';
76 $obj = new Locale::Codes 'country',LOCALE_COUNTRY_ALPHA_3;
77
78 This creates a new object that can access the data. If no type is
79 specified (in the first argument), you must use the type method
80 described below. No operations will work unless the type is
81 specified.
82
83 The second argument is the default code set to use. This is
84 optional, as each type has a default code set. The default code set
85 can be set using the codeset method below.
86
87 The last example is only available if the constants were imported
88 when the module was loaded.
89
90 show_errors ( FLAG )
91 $obj->show_errors(1);
92 $obj->show_errors(0);
93
94 By default, error messages will be produced when bad data is passed
95 to any method. By passing in '0', these will be turned off so that
96 all failures will be silent.
97
98 type ( TYPE )
99 $obj->type($type)
100
101 This will set the type of codes that will be worked with. $type may
102 be any of the recognized types of code sets, including:
103
104 country
105 language
106 currency
107 script
108 etc.
109
110 The list of valid types, and the code sets supported in each, are
111 described in the Locale::Codes::Types document.
112
113 This method can be called any number of times to toggle between
114 different types of code sets.
115
116 codeset ( CODESET )
117 $obj->codeset($codeset);
118
119 This sets the default code set to use. The list of code sets
120 available for each type are described in the Locale::Codes::Types
121 document.
122
123 In all other methods below, when an optional CODESET argument is
124 omitted, it will default to this value.
125
126 code2name ( CODE [,CODESET] [,'retired'] )
127 $name = $obj->code2name($code [,$codeset] [,'retired']);
128
129 This functions take a code and returns a string which contains the
130 name of the element identified. If the code is not a valid code in
131 the CODESET specified then "undef" will be returned.
132
133 The name of the element is the name as specified in the standard,
134 and as a result, different variations of an element name may be
135 returned for different values of CODESET.
136
137 For example, the alpha-2 country code set defines the two-letter
138 code "bo" to be "Bolivia, Plurinational State of", whereas the
139 alpha-3 code set defines the code 'bol' to be the country "Bolivia
140 (Plurinational State of)". So:
141
142 $obj->code2name('bo','alpha-2');
143 => 'Bolivia, Plurinational State of'
144
145 $obj->code2name('bol','alpha-3');
146 => 'Bolivia (Plurinational State of)'
147
148 By default, only active codes will be used, but if the string
149 'retired' is passed in as an argument, both active and retired codes
150 will be examined.
151
152 name2code ( NAME [,CODESET] [,'retired'] )
153 $code = $obj->name2code($name [,$codeset] [,'retired']);
154
155 This function takes the name of an element (or any of it's aliases)
156 and returns the code that corresponds to it, if it exists. If NAME
157 could not be identified as the name of one of the elements, then
158 "undef" will be returned.
159
160 The name is not case sensitive. Also, any known variation of a name
161 may be passed in.
162
163 For example, even though the country name returned using 'alpha-2'
164 and 'alpha-3' country codes for Bolivia are different, either
165 country name may be passed in since for each code set (in addition
166 to the more common alias 'Bolivia'). So:
167
168 $obj->name2code('Bolivia, Plurinational State of','alpha-2');
169 => bo
170
171 $obj->name2code('Bolivia (Plurinational State of)','alpha-2');
172 => bo
173
174 $obj->name2code('Bolivia','alpha-2');
175 => bo
176
177 By default, only active names will be used, but if the string
178 'retired' is passed in as an argument, both active and retired names
179 will be examined.
180
181 code2code ( CODE [,CODESET] ,CODESET2 )
182 $code = $obj->code2code($code [,$codeset] ,$codeset2);
183
184 This function takes a code from one code set (CODESET or the default
185 code set), and returns the corresponding code from another code set
186 (CODESET2). CODE must exists in the code set specified by CODESET
187 and must have a corresponding code in the code set specified by
188 CODESET2 or "undef" will be returned.
189
190 $obj->code2code('fin','alpha-3','alpha-2');
191 => 'fi'
192
193 Note that this function does NOT support retired codes.
194
195 all_codes ( [CODESET] [,'retired'] )
196 @code = $obj->all_codes([$codeset] [,'retired']);
197
198 This returns a list of all code in the code set. The codes will be
199 sorted.
200
201 By default, only active codes will be returned, but if the string
202 'retired' is passed in as an argument, both active and retired codes
203 will be returned.
204
205 all_names ( [CODESET] [,'retired'] )
206 @name = $obj->all_names([$codeset] [,'retired']);
207
208 This method returns a list of all elements names for which there is
209 a corresponding code in the specified code set.
210
211 The names returned are exactly as they are specified in the
212 standard, and are sorted.
213
214 Since not all elements are listed in all code sets, the list of
215 elements may differ depending on the code set specified.
216
217 By default, only active names will be returned, but if the string
218 'retired' is passed in as an argument, both active and retired names
219 will be returned.
220
221 The following additional methods are available and can be used to modify
222 the code list data (and are therefore not generally useful).
223
224 rename_code ( CODE ,NEW_NAME [,CODESET] )
225 $flag = $obj->rename_code($code,$new_name [,$codeset]);
226
227 This method can be used to change the official name of an element.
228 At that point, the name returned by the "code2name" method would be
229 NEW_NAME instead of the name specified in the standard.
230
231 The original name will remain as an alias.
232
233 For example, the official country name for code 'gb' is 'United
234 Kingdom'. If you want to change that, you might call:
235
236 $obj->rename_code('gb', 'Great Britain');
237
238 This means that calling code2name('gb') will now return 'Great
239 Britain' instead of 'United Kingdom'.
240
241 If any error occurs, a warning is issued and 0 is returned. An error
242 occurs if CODE doesn't exist in the specified code set, or if
243 NEW_NAME is already in use but for a different element.
244
245 If the method succeeds, 1 is returned.
246
247 add_code ( CODE ,NAME [,CODESET] )
248 $flag = $obj->add_code($code,$name [,$codeset]);
249
250 This method is used to add a new code and name to the data.
251
252 Both CODE and NAME must be unused in the data set or an error occurs
253 (though NAME may be used in a different data set).
254
255 For example, to create the fictitious country named "Duchy of Grand
256 Fenwick" with codes "gf" and "fen", use the following:
257
258 $obj->add_code("fe","Duchy of Grand Fenwick",'alpha-2');
259 $obj->add_code("fen","Duchy of Grand Fenwick",'alpha-3');
260
261 The return value is 1 on success, 0 on an error.
262
263 delete_code ( CODE [,CODESET] )
264 $flag = $obj->delete_code($code [,$codeset]);
265
266 This method is used to delete a code from the data.
267
268 CODE must refer to an existing code in the code set.
269
270 The return value is 1 on success, 0 on an error.
271
272 add_alias ( NAME ,NEW_NAME )
273 $flag = $obj->add_alias($name,$new_name);
274
275 This method is used to add a new alias to the data. They do not
276 alter the return value of the "code2name" function.
277
278 NAME must be an existing element name, and NEW_NAME must be unused
279 or an error occurs.
280
281 The return value is 1 on success, 0 on an error.
282
283 delete_alias ( NAME )
284 $flag = $obj->delete_alias($name);
285
286 This method is used to delete an alias from the data. Once removed,
287 the element may not be referred to by NAME.
288
289 NAME must be one of a list of at least two names that may be used to
290 specify an element. If the element may only be referred to by a
291 single name, you'll need to use the "add_alias" method to add a new
292 alias first, or the "remove_code" method to remove the element
293 entirely.
294
295 If the alias is used as the name in any code set, one of the other
296 names will be used instead. Predicting exactly which one will be
297 used requires you to know the order in which the standards were
298 read, which is not reliable, so you may want to use the
299 "rename_code" method to force one of the alternate names to be used.
300
301 The return value is 1 on success, 0 on an error.
302
303 replace_code ( CODE ,NEW_CODE [,CODESET] )
304 $flag = $obj->replace_code($code,$new_code [,$codeset]);
305
306 This method is used to change the official code for an element. At
307 that point, the code returned by the "name2code" method would be
308 NEW_CODE instead of the code specified in the standard.
309
310 NEW_CODE may either be a code that is not in use, or it may be an
311 alias for CODE (in which case, CODE becomes and alias and NEW_CODE
312 becomes the "real" code).
313
314 The original code is kept as an alias, so that the "code2name"
315 routines will work with either the code from the standard or the new
316 code.
317
318 However, the "all_codes" method will only return the codes which are
319 considered "real" (which means that the list of codes will now
320 contain NEW_CODE, but will not contain CODE).
321
322 add_code_alias ( CODE ,NEW_CODE [,CODESET] )
323 $flag = $obj->add_code_alias($code,$new_code [,$codeset]);
324
325 This method adds an alias for the code. At that point, NEW_CODE and
326 CODE will both work in the "code2name" method. However, the
327 "name2code" method will still return the original code.
328
329 delete_code_alias ( CODE [,CODESET] )
330 These routines delete an alias for the code.
331
332 These will only work if CODE is actually an alias. If it is the
333 "real" code, it will not be deleted. You will need to use the
334 "rename_code" method to switch the real code with one of the
335 aliases, and then delete the alias.
336
337TRADITIONAL INTERFACES
338 In addition the the primary OO module, the following modules are
339 included in the distribution for the traditional way of working with
340 code sets.
341
342 Each module will work with one specific type of code sets.
343
344 Locale::Codes::Country, Locale::Country
345 This includes support for country codes (such as those listed in
346 ISO-3166) to specify the country.
347
348 Because this module was originally distributed as Locale::Country,
349 it is also available under that name.
350
351 Locale::Codes::Language, Locale::Language
352 This includes support for language codes (such as those listed in
353 ISO-639) to specify the language.
354
355 Because this module was originally distributed as Locale::Language,
356 it is also available under that name.
357
358 Locale::Codes::Currency, Locale::Currency
359 This includes support for currency codes (such as those listed in
360 ISO-4217) to specify the currency.
361
362 Because this module was originally distributed as Locale::Currency,
363 it is also available under that name.
364
365 Locale::Codes::Script, Locale::Script
366 This includes support for script codes (such as those listed in
367 ISO-15924) to specify the script.
368
369 Because this module was originally distributed as Locale::Script, it
370 is also available under that name.
371
372 Locale::Codes::LangExt
373 This includes support for language extension codes (such as those
374 listed in the IANA language registry) to specify the language
375 extension.
376
377 Locale::Codes::LangVar
378 This includes support for language variation codes (such as those
379 listed in the IANA language registry) to specify the language
380 variation.
381
382 Locale::Codes::LangFam
383 This includes support for language family codes (such as those
384 listed in ISO 639-5) to specify families of languages.
385
386 In addition to the modules above, there are a number of support modules
387 included in the distribution. Any module not listed above falls into
388 that category.
389
390 These modules are not intended to be used by programmers. They contain
391 functions or data that are used by the modules listed above. No support
392 of any kind is offered for using these modules directly. They may be
393 modified at any time.
394
395COMMON ALIASES
396 As of version 2.00, the modules supported common variants of names.
397
398 For example, Locale::Country supports variant names for countries, and a
399 few of the most common ones are included in the data. The country code
400 for "United States" is "us", so:
401
402 country2code('United States');
403 => "us"
404
405 Now the following will also return 'us':
406
407 country2code('United States of America');
408 country2code('USA');
409
410 Any number of common aliases may be included in the data, in addition to
411 the names that come directly from the standards. If you have a common
412 alias for a country, language, or any other of the types of codes, let
413 me know and I'll add it, with some restrictions.
414
415 For example, the country name "North Korea" never appeared in any of the
416 official sources (instead, it was "Korea, North" or "Korea, Democratic
417 People's Republic of". I would honor a request to add an alias "North
418 Korea" since that's a very common way to specify the country (please
419 don't request this... I've already added it).
420
421 On the other hand, a request to add Zaire as an alias for "Congo, The
422 Democratic Republic of" will not be honored. The country's official name
423 is no longer Zaire, so adding it as an alias violates the standard.
424 Zaire was kept as an alias in versions of this module prior to 3.00, but
425 it has been removed. Other aliases (if any) which no longer appear in
426 any standard (and which are not common variations of the name in the
427 standards) have also been removed.
428
429RETIRED CODES
430 Occasionally, a code is deprecated, but it may still be desirable to
431 have access to it.
432
433 Although there is no way to see every code that has ever existed and
434 been deprecated (since most codesets do not have that information
435 available), as of version 3.20, every code which has ever been included
436 in these modules can be referenced.
437
438 For more information, refer to the documentation on the code2name,
439 name2code, all_codes, and all_names methods above.
440
441SEE ALSO
442 Locale::Codes::Types
443 The list of all code sets available for each type.
444
445 Locale::Codes::Changes
446 A history of changes made to this distribution.
447
448KNOWN BUGS AND LIMITATIONS
449 Relationship between code sets
450 Because each code set uses a slightly different list of elements,
451 and they are not necessarily one-to-one, there may be some confusion
452 about the relationship between codes from different code sets.
453
454 For example, ISO 3166 assigns one code to the country "United States
455 Minor Outlying Islands", but the IANA codes give different codes to
456 different islands (Baker Island, Howland Island, etc.).
457
458 This may cause some confusion... I've done the best that I could do
459 to minimize it.
460
461 Non-ASCII characters not supported
462 Currently all names must be all ASCII. I plan on relaxing that
463 limitation in the future.
464
465BUGS AND QUESTIONS
466 If you find a bug in Locale::Codes, there are three ways to send it to
467 me. Any of them are fine, so use the method that is easiest for you.
468
469 Direct email
470 You are welcome to send it directly to me by email. The email
471 address to use is: sbeck@cpan.org.
472
473 CPAN Bug Tracking
474 You can submit it using the CPAN tracking tool. This can be done at
475 the following URL:
476
477 <http://rt.cpan.org/Public/Dist/Display.html?Name=Locale-Codes>
478
479 GitHub
480 You can submit it as an issue on GitHub. This can be done at the
481 following URL:
482
483 <https://github.com/SBECK-github/Locale-Codes>
484
485 Please do not use other means to report bugs (such as forums for a
486 specific OS or Linux distribution) as it is impossible for me to keep up
487 with all of them. These are the current methods that are guaranteed to
488 notify me.
489
490 When filing a bug report, please include the following information:
491
492 Locale::Codes version
493 Please include the version of Locale::Codes you are using. You can
494 get this by using the script:
495
496 use Locale::Codes;
497 print $Locale::Codes::VERSION,"\n";
498
499 If you want to report missing or incorrect codes, you must be running
500 the most recent version of Locale::Codes.
501
502 If you find any problems with the documentation (errors, typos, or items
503 that are not clear), please send them to me. I welcome any suggestions
504 that will allow me to improve the documentation.
505
506AUTHOR
507 Locale::Country and Locale::Language were originally written by Neil
508 Bowers at the Canon Research Centre Europe (CRE). They maintained the
509 distribution from 1997 to 2001.
510
511 Locale::Currency was originally written by Michael Hennecke and was
512 modified by Neil Bowers for inclusion in the distribution.
513
514 From 2001 to 2004, maintenance was continued by Neil Bowers. He modified
515 Locale::Currency for inclusion in the distribution. He also added
516 Locale::Script.
517
518 From 2004-2009, the module was unmaintained.
519
520 In 2010, maintenance was taken over by Sullivan Beck (sbeck@cpan.org)
521 with Neil Bower's permission. All problems or comments should be sent to
522 him using any of the methods listed above.
523
524COPYRIGHT
525 Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
526 Copyright (c) 2001 Michael Hennecke (Locale::Currency)
527 Copyright (c) 2001-2010 Neil Bowers
528 Copyright (c) 2010-2020 Sullivan Beck
529
530 This module is free software; you can redistribute it and/or modify it
531 under the same terms as Perl itself.
532
533