Commit | Line | Data |
f768f60b |
1 | =pod |
2 | |
3 | =head1 NAME |
4 | |
5 | Locale::Codes - a distribution of modules to handle locale codes |
6 | |
7 | =head1 DESCRIPTION |
8 | |
9 | B<Locale::Codes> is a distribution containing a set of modules. The |
10 | modules each deal with different types of codes which identify parts |
11 | of the locale including languages, countries, currency, etc. |
12 | |
13 | Currently, the following modules are included: |
14 | |
15 | =over 4 |
16 | |
17 | =item B<Locale::Country> |
18 | |
19 | This includes support for country codes (such as those listed in ISO-3166) |
20 | to specify the country. |
21 | |
22 | =item B<Locale::Language> |
23 | |
24 | This includes support for language codes (such as those listed in ISO-639) |
25 | to specify the language. |
26 | |
27 | =item B<Locale::Currency> |
28 | |
29 | This includes support for currency codes (such as those listed in ISO-4217) |
30 | to specify the currency. |
31 | |
32 | =item B<Locale::Script> |
33 | |
34 | This includes support for script codes (such as those listed in ISO-15924) |
35 | to specify the script. |
36 | |
37 | =back |
38 | |
39 | Each module can support an arbitrary number of code sets, and it it |
40 | not required that the relationship between these code sets be |
41 | one-to-one. For example, the Locale::Country module supports code |
42 | sets from ISO-3166 and the FIPS 10 standard, and they do not break the |
43 | world down into exactly the same sets of countries. This does not |
44 | cause any problem (though converting codes from ISO-3166 to FIPS or |
45 | back will not work except for countries that are one-to-one). |
46 | |
47 | All data in all of these modules comes directly from the original |
48 | standards (or as close to direct as possible), so it should be |
49 | up-to-date at the time of release. |
50 | |
51 | I plan on releasing a new version a couple of times a year to |
52 | incorporate any changes made in the standards. However, I don't always |
53 | know about changes that occur, so if any of the standards change, and |
54 | you want a new release sooner, just email me and I'll get one out. |
55 | |
56 | =head1 NEW CODE SETS |
57 | |
58 | I'm always open to suggestions for new code sets. |
59 | |
60 | In order for me to add a code set, I want the following criteria |
61 | to be met: |
62 | |
63 | =over 4 |
64 | |
65 | =item B<General-use code set> |
66 | |
67 | If a code set is not general use, I'm not likely to spend the time |
68 | to add and support it. |
69 | |
70 | =item B<An official source of data> |
71 | |
72 | I require an official (or at least, a NEARLY official) source where I |
73 | can get the data on a regular basis. |
74 | |
75 | Ideally, I'd only get data from an official source, but sometimes that |
76 | is not possible. For example the ISO standards are not typically |
77 | available for free, so I may have to get some of that data from |
78 | alternate sources that I'm confident are getting their data from the |
79 | official source. |
80 | |
81 | As an example, I get some country data from the CIA World |
82 | Factbook. Given the nature of the source, I'm sure they're updating |
83 | data from the official sources and I consider it "nearly" official. |
84 | |
85 | There are many 3rd party sites which maintain lists (many of which are |
86 | actually in a more convenient form than the official sites). |
87 | Unfortunately, I will reject most of them since I have no feel for how |
88 | "official" they are. |
89 | |
90 | =item B<A free source of the data> |
91 | |
92 | Obviously, the data must be free-of-charge. I'm not interested in |
93 | paying for the data (and I'm not interested in the overhead of having |
94 | someone else pay for the data for me). |
95 | |
96 | =item B<A reliable source of data> |
97 | |
98 | The source of data must come from a source that I can reasonably expect |
99 | to exist for the foreseeable future since I will be extremely reluctant |
100 | to drop support for a data set once it's included. |
101 | |
102 | I am also reluctant to accept data sent to me by an individual. |
103 | Although I appreciate the offer, it is simply not practical to consider |
104 | an individual contribution as a reliable source of data. The source |
105 | should be an official agency of some sort. |
106 | |
107 | =back |
108 | |
109 | These requirements are open to discussion. If you have a code set |
110 | you'd like to see added, but which may not meet all of the above |
111 | requirements, feel free to email me and we'll discuss it. Depending |
112 | on circumstances, I may be willing to waive some of these criteria. |
113 | |
114 | =head1 COMMON ALIASES |
115 | |
116 | As of version 2.00, the modules supported common variants of names. |
117 | |
118 | For example, Locale::Country supports variant names for countries, and |
119 | a few of the most common ones are included in the data. The country |
120 | code for "United States" is "us", so: |
121 | |
122 | country2code('United States'); |
123 | => "us" |
124 | |
125 | Now the following will also return 'us': |
126 | |
127 | country2code('United States of America'); |
128 | country2code('USA'); |
129 | |
130 | Any number of common aliases may be included in the data, in addition |
131 | to the names that come directly from the standards. If you have a |
132 | common alias for a country, language, or any other of the types of |
133 | codes, let me know and I'll add it, with some restrictions. |
134 | |
135 | For example, the country name "North Korea" never appeared in any of |
136 | the official sources (instead, it was "Korea, North" or "Korea, |
137 | Democratic People's Republic of". I would honor a request to add an |
138 | alias "North Korea" since that's a very common way to specify the |
139 | country (please don't request this... I've already added it). |
140 | |
141 | On the other hand, a request to add Zaire as an alias for "Congo, The |
142 | Democratic Republic of" may not be honored. The country's official |
143 | name is not Zaire, so adding it as an alias violates the standard. |
144 | Zaire was kept as an alias in versions prior to 3.00, but it has been |
145 | removed. Other aliases (if any) which no longer appear in any standard |
146 | have also been removed. |
147 | |
148 | =head1 ROUTINES |
149 | |
150 | As of 3.10, the interface for all of the modules listed above are |
151 | identical (as a matter of fact, they are all just wrappers around a |
152 | central module which does all the real work). |
153 | |
154 | In order to maintain the documentation for the modules consistently, |
155 | the functions are all documented here, rather than in the documentation |
156 | for the separate modules. |
157 | |
158 | The name of the function depends on the module. For example, every module |
159 | contains a function "code2XXX" where XXX refers to the type of data |
160 | (country, language, currency, or script). So, the Locale::Country module |
161 | contains the function code2country, the Locale::Language module contains |
162 | the function code2language, etc. |
163 | |
164 | In all of the functions below, CODE refers to a code for one element in |
165 | the code set. For example, in the two-letter country codes from ISO 3166-1, |
166 | the code 'fi' is used to refer to the country Finland. CODE is always |
167 | case insensitive (though when a code is returned, it will always be in |
168 | the case as used in the standard), so 'fi', 'FI', and 'Fi' would all |
169 | be equivalent. |
170 | |
171 | CODESET refers to a constant specified in the documentation for each |
172 | module to label the various code sets. For example, in the |
173 | Locale::Language module, CODESET could be LOCALE_CODE_ALPHA_2 or |
174 | LOCALE_CODE_ALPHA_3 (among others). Most functions have a default one, |
175 | so they do not need to be specified. So the following calls are valid: |
176 | |
177 | code2country("fi"); |
178 | code2country("fi",LOCALE_CODE_ALPHA_2); |
179 | code2country("fin",LOCALE_CODE_ALPHA_3); |
180 | |
181 | Since LOCALE_CODE_ALPHA_2 is the default code set, the first two are |
182 | identical. |
183 | |
184 | =over 4 |
185 | |
186 | =item B<code2country ( CODE [,CODESET] )> |
187 | |
188 | =item B<code2language( CODE [,CODESET] )> |
189 | |
190 | =item B<code2currency( CODE [,CODESET] )> |
191 | |
192 | =item B<code2script ( CODE [,CODESET] )> |
193 | |
194 | These functions take a code and returns a string which contains |
195 | the name of the element identified. If the code is not a valid |
196 | code in the CODESET specified then C<undef> will be returned. |
197 | |
198 | The name of the element is the name as specified in the standard, |
199 | and as a result, different variations of an element name may |
200 | be returned for different values of CODESET. |
201 | |
202 | For example, the B<alpha-2> country code set defines the two-letter |
203 | code "bo" to be "Bolivia, Plurinational State of", whereas the |
204 | B<alpha-3> code set defines the code 'bol' to be the country "Bolivia |
205 | (Plurinational State of)". So: |
206 | |
207 | code2country('bo',LOCALE_CODE_ALPHA_2); |
208 | => 'Bolivia, Plurinational State of' |
209 | |
210 | code2country('bol',LOCALE_CODE_ALPHA_3); |
211 | => 'Bolivia (Plurinational State of)' |
212 | |
213 | =item B<country2code ( NAME [,CODESET] )> |
214 | |
215 | =item B<language2code( NAME [,CODESET] )> |
216 | |
217 | =item B<currency2code( NAME [,CODESET] )> |
218 | |
219 | =item B<script2code ( NAME [,CODESET] )> |
220 | |
221 | These functions takes the name of an element (or any of it's aliases) |
222 | and returns the code that corresponds to it, if it exists. If NAME |
223 | could not be identified as the name of one of the elements, then |
224 | C<undef> will be returned. |
225 | |
226 | The name is not case sensitive. Also, any known variation of a name |
227 | may be passed in. |
228 | |
229 | For example, even though the country name returned using |
230 | LOCALE_CODE_ALPHA_2 and LOCALE_CODE_ALPHA_3 country codes for Bolivia is different, |
231 | either country name may be passed in since for each code set, in addition to |
232 | the alias 'Bolivia'. So: |
233 | |
234 | country2code('Bolivia, Plurinational State of', |
235 | LOCALE_CODE_ALPHA_2); |
236 | => bo |
237 | |
238 | country2code('Bolivia (Plurinational State of)', |
239 | LOCALE_CODE_ALPHA_2); |
240 | => bo |
241 | |
242 | country2code('Bolivia',LOCALE_CODE_ALPHA_2); |
243 | => bo |
244 | |
245 | =item B<country_code2code ( CODE ,CODESET ,CODESET2 )> |
246 | |
247 | =item B<language_code2code( CODE ,CODESET ,CODESET2 )> |
248 | |
249 | =item B<currency_code2code( CODE ,CODESET ,CODESET2 )> |
250 | |
251 | =item B<script_code2code ( CODE ,CODESET ,CODESET2 )> |
252 | |
253 | These functions takes a a code from one code set, and returns the |
254 | corresponding code from another code set. CODE must exists in the code |
255 | set specified by CODESET and must have a corresponding code in the |
256 | code set specified by CODESET2 or C<undef> will be returned. |
257 | |
258 | Both CODESETs must be explicitly entered. |
259 | |
260 | country_code2code('fin', LOCALE_CODE_ALPHA_3, |
261 | LOCALE_CODE_ALPHA_2); |
262 | => 'fi' |
263 | |
264 | =item B<all_country_codes ( [CODESET] )> |
265 | |
266 | =item B<all_language_codes( [CODESET] )> |
267 | |
268 | =item B<all_currency_codes( [CODESET] )> |
269 | |
270 | =item B<all_script_codes ( [CODESET] )> |
271 | |
272 | These returns a list of all code in the code set. The codes will be |
273 | sorted. |
274 | |
275 | =item B<all_country_names ( [CODESET] )> |
276 | |
277 | =item B<all_language_names( [CODESET] )> |
278 | |
279 | =item B<all_currency_names( [CODESET] )> |
280 | |
281 | =item B<all_script_names ( [CODESET] )> |
282 | |
283 | These return a list of all elements names for which there is a |
284 | corresponding code in the specified code set. |
285 | |
286 | The names returned are exactly as they are specified in the standard, |
287 | and are sorted. |
288 | |
289 | Since not all elements are listed in all code sets, the list of |
290 | elements may differ depending on the code set specified. |
291 | |
292 | =back |
293 | |
294 | =head1 SEMI-PRIVATE ROUTINES |
295 | |
296 | Additional semi-private routines which may be used to modify the |
297 | internal data are also available. Given their status, they aren't |
298 | exported, and so need to be called by prefixing the function name with |
299 | the package name. |
300 | |
301 | =over 4 |
302 | |
303 | =item B<Locale::Country::rename_country ( CODE ,NEW_NAME [,CODESET] )> |
304 | |
305 | =item B<Locale::Language::rename_language( CODE ,NEW_NAME [,CODESET] )> |
306 | |
307 | =item B<Locale::Currency::rename_currency( CODE ,NEW_NAME [,CODESET] )> |
308 | |
309 | =item B<Locale::Script::rename_script ( CODE ,NEW_NAME [,CODESET] )> |
310 | |
311 | These routines are used to change the official name of an element. At |
312 | that point, the name returned by the code2XXX routine would be |
313 | NEW_NAME instead of the name specified in the standard. |
314 | |
315 | The original name will remain as an alias. |
316 | |
317 | For example, the official country name for code 'gb' is 'United |
318 | Kingdom'. If you want to change that, you might call: |
319 | |
320 | Locale::Country::rename_country('gb', 'Great Britain'); |
321 | |
322 | This means that calling code2country('gb') will now return 'Great |
323 | Britain' instead of 'United Kingdom'. |
324 | |
325 | If any error occurs, a warning is issued and 0 is returned. An error |
326 | occurs if CODE doesn't exist in the specified code set, or if |
327 | NEW_NAME is already in use but for a different element. |
328 | |
329 | If the routine succeeds, 1 is returned. |
330 | |
331 | =item B<Locale::Country::add_country ( CODE ,NAME [,CODESET] )> |
332 | |
333 | =item B<Locale::Language::add_language( CODE ,NAME [,CODESET] )> |
334 | |
335 | =item B<Locale::Currency::add_currency( CODE ,NAME [,CODESET] )> |
336 | |
337 | =item B<Locale::Script::add_script ( CODE ,NAME [,CODESET] )> |
338 | |
339 | These routines are used to add a new code and name to the data. |
340 | |
341 | Both CODE and NAME must be unused in the data set or an error |
342 | occurs (though NAME may be used in a different data set). |
343 | |
344 | For example, to create the fictitious country named "Duchy of |
345 | Grand Fenwick" with codes "gf" and "fen", use the following: |
346 | |
347 | Locale::Country::add_country("fe","Duchy of Grand Fenwick", |
348 | LOCALE_CODE_ALPHA_2); |
349 | |
350 | Locale::Country::add_country("fen","Duchy of Grand Fenwick", |
351 | LOCALE_CODE_ALPHA_3); |
352 | |
353 | The return value is 1 on success, 0 on an error. |
354 | |
355 | =item B<Locale::Country::delete_country ( CODE [,CODESET] )> |
356 | |
357 | =item B<Locale::Language::delete_language( CODE [,CODESET] )> |
358 | |
359 | =item B<Locale::Currency::delete_currency( CODE [,CODESET] )> |
360 | |
361 | =item B<Locale::Script::delete_script ( CODE [,CODESET] )> |
362 | |
363 | These routines are used to delete a code from the data. |
364 | |
365 | CODE must refer to an existing code in the code set. |
366 | |
367 | The return value is 1 on success, 0 on an error. |
368 | |
369 | =item B<Locale::Country::add_country_alias ( NAME ,NEW_NAME )> |
370 | |
371 | =item B<Locale::Language::add_language_alias( NAME ,NEW_NAME )> |
372 | |
373 | =item B<Locale::Currency::add_currency_alias( NAME ,NEW_NAME )> |
374 | |
375 | =item B<Locale::Script::add_script_alias ( NAME ,NEW_NAME )> |
376 | |
377 | These routines are used to add a new alias to the data. They do |
378 | not alter the return value of the code2XXX function. |
379 | |
380 | NAME must be an existing element name, and NEW_NAME must |
381 | be unused or an error occurs. |
382 | |
383 | The return value is 1 on success, 0 on an error. |
384 | |
385 | =item B<Locale::Country::delete_country_alias ( NAME )> |
386 | |
387 | =item B<Locale::Language::delete_language_alias( NAME )> |
388 | |
389 | =item B<Locale::Currency::delete_currency_alias( NAME )> |
390 | |
391 | =item B<Locale::Script::delete_script_alias ( NAME )> |
392 | |
393 | These routines are used to delete an alias from the data. Once |
394 | removed, the element may not be referred to by NAME. |
395 | |
396 | NAME must be one of a list of at least two names that may be used to |
397 | specify an element. If the element may only be referred to by a single |
398 | name, you'll need to use the add_XXX_alias function to add a new alias |
399 | first, or the remove_XXX function to remove the element entirely. |
400 | |
401 | If the alias is used as the name in any code set, one of the other |
402 | names will be used instead. Predicting exactly which one will |
403 | be used requires you to know the order in which the standards |
404 | were read, which is not reliable, so you may want to use the |
405 | rename_XXX function to force one of the alternate names to be |
406 | used. |
407 | |
408 | The return value is 1 on success, 0 on an error. |
409 | |
410 | =item B<Locale::Country::rename_country_code ( CODE ,NEW_CODE [,CODESET] )> |
411 | |
412 | =item B<Locale::Language::rename_language_code( CODE ,NEW_CODE [,CODESET] )> |
413 | |
414 | =item B<Locale::Currency::rename_currency_code( CODE ,NEW_CODE [,CODESET] )> |
415 | |
416 | =item B<Locale::Script::rename_script_code ( CODE ,NEW_CODE [,CODESET] )> |
417 | |
418 | These routines are used to change the official code for an element. At |
419 | that point, the code returned by the XXX2code routine would be |
420 | NEW_CODE instead of the code specified in the standard. |
421 | |
422 | NEW_CODE may either be a code that is not in use, or it may be an |
423 | alias for CODE (in which case, CODE becomes and alias and NEW_CODE |
424 | becomes the "real" code). |
425 | |
426 | The original code is kept as an alias, so that the code2XXX routines |
427 | will work with either the code from the standard or the new code. |
428 | |
429 | However, the all_XXX_codes routine will only return the codes which |
430 | are considered "real" (which means that the list of codes will now |
431 | contain NEW_CODE, but will not contain CODE). |
432 | |
433 | =item B<Locale::Country::add_country_code_alias ( CODE ,NEW_CODE [,CODESET] )> |
434 | |
435 | =item B<Locale::Language::add_language_code_alias( CODE ,NEW_CODE [,CODESET] )> |
436 | |
437 | =item B<Locale::Currency::add_currency_code_alias( CODE ,NEW_CODE [,CODESET] )> |
438 | |
439 | =item B<Locale::Script::add_script_code_alias ( CODE ,NEW_CODE [,CODESET] )> |
440 | |
441 | These routines add an alias for the code. At that point, NEW_CODE and CODE |
442 | will both work in the code2XXX routines. However, the XXX2code routines will |
443 | still return the original code. |
444 | |
445 | =item B<Locale::Country::delete_country_code_alias ( CODE [,CODESET] )> |
446 | |
447 | =item B<Locale::Language::delete_language_code_alias( CODE [,CODESET] )> |
448 | |
449 | =item B<Locale::Currency::delete_currency_code_alias( CODE [,CODESET] )> |
450 | |
451 | =item B<Locale::Script::delete_script_code_alias ( CODE [,CODESET] )> |
452 | |
453 | These routines delete an alias for the code. |
454 | |
455 | These will only work if CODE is actually an alias. If it is the "real" |
456 | code, it will not be deleted. You will need to use the rename_XXX_code |
457 | function to switch the real code with one of the aliases, and then |
458 | delete the alias. |
459 | |
460 | =back |
461 | |
462 | =head1 KNOWN BUGS AND LIMITATIONS |
463 | |
464 | =over 4 |
465 | |
466 | =item B<*> |
467 | |
468 | Because each code set uses a slightly different list of elements, and |
469 | they are not necessarily one-to-one, there may be some confusion |
470 | about the relationship between codes from different code sets. |
471 | |
472 | For example, ISO 3166 assigns one code to the country "United States |
473 | Minor Outlying Islands", but the FIPS 10 codes give different codes |
474 | to different islands (Baker Island, Howland Island, etc.). |
475 | |
476 | This may cause some confusion... I've done the best that I could do |
477 | to minimize it. |
478 | |
479 | =item B<*> |
480 | |
481 | Currently all names must be all ASCII. I plan on relaxing that |
482 | limitation in the future. |
483 | |
484 | =back |
485 | |
486 | =head1 SEE ALSO |
487 | |
488 | =over 4 |
489 | |
490 | =item B<Locale::Constants> |
491 | |
492 | Constants for Locale codes. |
493 | |
494 | =item B<Locale::Country> |
495 | |
496 | Codes for identification of countries. |
497 | |
498 | =item B<Locale::Language> |
499 | |
500 | Codes for identification of languages. |
501 | |
502 | =item B<Locale::Script> |
503 | |
504 | Codes for identification of scripts. |
505 | |
506 | =item B<Locale::Currency> |
507 | |
508 | Codes for identification of currencies and funds. |
509 | |
510 | =back |
511 | |
512 | =head1 AUTHOR |
513 | |
514 | Locale::Country and Locale::Language were originally written by Neil |
515 | Bowers at the Canon Research Centre Europe (CRE). They maintained the |
516 | distribution from 1997 to 2001. |
517 | |
518 | Locale::Currency was originally written by Michael Hennecke. |
519 | |
520 | From 2001 to 2004, maintenance was continued by Neil Bowers. He |
521 | modified Locale::Currency for inclusion in the distribution. He also |
522 | added Locale::Constants and Locale::Script. |
523 | |
524 | From 2004-2009, the module was unmaintained. |
525 | |
526 | In 2010, maintenance was taken over by Sullivan Beck (sbeck@cpan.org) |
527 | with Neil Bower's permission. |
528 | |
529 | =head1 COPYRIGHT |
530 | |
531 | Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). |
532 | Copyright (c) 2001 Michael Hennecke (Locale::Currency) |
533 | Copyright (c) 2001-2010 Neil Bowers |
534 | Copyright (c) 2010-2010 Sullivan Beck |
535 | |
536 | This module is free software; you can redistribute it and/or |
537 | modify it under the same terms as Perl itself. |
538 | |
539 | =cut |
540 | |