2f43ae7c5ae69e391b5966a8d37de6facb52c158
[p5sagit/p5-mst-13.2.git] / lib / Locale / Country.pm
1 #-----------------------------------------------------------------------
2
3 =head1 NAME
4
5 Locale::Country - ISO codes for country identification (ISO 3166)
6
7 =head1 SYNOPSIS
8
9     use Locale::Country;
10     
11     $country = code2country('jp');               # $country gets 'Japan'
12     $code    = country2code('Norway');           # $code gets 'no'
13     
14     @codes   = all_country_codes();
15     @names   = all_country_names();
16     
17     # add "uk" as a pseudo country code for United Kingdom
18     Locale::Country::_alias_code('uk' => 'gb');
19
20 =cut
21
22 #-----------------------------------------------------------------------
23
24 package Locale::Country;
25 use strict;
26 require 5.002;
27
28 #-----------------------------------------------------------------------
29
30 =head1 DESCRIPTION
31
32 The C<Locale::Country> module provides access to the ISO
33 codes for identifying countries, as defined in ISO 3166.
34 You can either access the codes via the L<conversion routines>
35 (described below), or with the two functions which return lists
36 of all country codes or all country names.
37
38 There are three different code sets you can use for identifying
39 countries:
40
41 =over 4
42
43 =item B<alpha-2>
44
45 Two letter codes, such as 'tv' for Tuvalu.
46 This code set is identified with the symbol C<LOCALE_CODE_ALPHA_2>.
47
48 =item B<alpha-3>
49
50 Three letter codes, such as 'brb' for Barbados.
51 This code set is identified with the symbol C<LOCALE_CODE_ALPHA_3>.
52
53 =item B<numeric>
54
55 Numeric codes, such as 064 for Bhutan.
56 This code set is identified with the symbol C<LOCALE_CODE_NUMERIC>.
57
58 =back
59
60 All of the routines take an optional additional argument
61 which specifies the code set to use.
62 If not specified, it defaults to the two-letter codes.
63 This is partly for backwards compatibility (previous versions
64 of this module only supported the alpha-2 codes), and
65 partly because they are the most widely used codes.
66
67 The alpha-2 and alpha-3 codes are not case-dependent,
68 so you can use 'BO', 'Bo', 'bO' or 'bo' for Bolivia.
69 When a code is returned by one of the functions in
70 this module, it will always be lower-case.
71
72 As of version 2.00, Locale::Country supports variant
73 names for countries. So, for example, the country code for "United States"
74 is "us", so country2code('United States') returns 'us'.
75 Now the following will also return 'us':
76
77     country2code('United States of America') 
78     country2code('USA') 
79
80 =cut
81
82 #-----------------------------------------------------------------------
83
84 require Exporter;
85 use Carp;
86 use Locale::Constants;
87
88
89 #-----------------------------------------------------------------------
90 #       Public Global Variables
91 #-----------------------------------------------------------------------
92 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
93 $VERSION   = sprintf("%d.%02d", q$Revision: 2.0 $ =~ /(\d+)\.(\d+)/);
94 @ISA       = qw(Exporter);
95 @EXPORT    = qw(code2country country2code
96                 all_country_codes all_country_names
97                 country_code2code
98                 LOCALE_CODE_ALPHA_2 LOCALE_CODE_ALPHA_3 LOCALE_CODE_NUMERIC);
99
100 #-----------------------------------------------------------------------
101 #       Private Global Variables
102 #-----------------------------------------------------------------------
103 my $CODES     = [];
104 my $COUNTRIES = [];
105
106
107 #=======================================================================
108
109 =head1 CONVERSION ROUTINES
110
111 There are three conversion routines: C<code2country()>, C<country2code()>,
112 and C<country_code2code()>.
113
114 =over 8
115
116 =item code2country( CODE, [ CODESET ] )
117
118 This function takes a country code and returns a string
119 which contains the name of the country identified.
120 If the code is not a valid country code, as defined by ISO 3166,
121 then C<undef> will be returned:
122
123     $country = code2country('fi');
124
125 =item country2code( STRING, [ CODESET ] )
126
127 This function takes a country name and returns the corresponding
128 country code, if such exists.
129 If the argument could not be identified as a country name,
130 then C<undef> will be returned:
131
132     $code = country2code('Norway', LOCALE_CODE_ALPHA_3);
133     # $code will now be 'nor'
134
135 The case of the country name is not important.
136 See the section L<KNOWN BUGS AND LIMITATIONS> below.
137
138 =item country_code2code( CODE, CODESET, CODESET )
139
140 This function takes a country code from one code set,
141 and returns the corresponding code from another code set.
142
143     $alpha2 = country_code2code('fin',
144                  LOCALE_CODE_ALPHA_3 => LOCALE_CODE_ALPHA_2);
145     # $alpha2 will now be 'fi'
146
147 If the code passed is not a valid country code in
148 the first code set, or if there isn't a code for the
149 corresponding country in the second code set,
150 then C<undef> will be returned.
151
152 =back
153
154 =cut
155
156 #=======================================================================
157 sub code2country
158 {
159     my $code = shift;
160     my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
161
162
163     return undef unless defined $code;
164
165     #-------------------------------------------------------------------
166     # Make sure the code is in the right form before we use it
167     # to look up the corresponding country.
168     # We have to sprintf because the codes are given as 3-digits,
169     # with leading 0's. Eg 052 for Barbados.
170     #-------------------------------------------------------------------
171     if ($codeset == LOCALE_CODE_NUMERIC)
172     {
173         return undef if ($code =~ /\D/);
174         $code = sprintf("%.3d", $code);
175     }
176     else
177     {
178         $code = lc($code);
179     }
180
181     if (exists $CODES->[$codeset]->{$code})
182     {
183         return $CODES->[$codeset]->{$code};
184     }
185     else
186     {
187         #---------------------------------------------------------------
188         # no such country code!
189         #---------------------------------------------------------------
190         return undef;
191     }
192 }
193
194 sub country2code
195 {
196     my $country = shift;
197     my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
198
199
200     return undef unless defined $country;
201     $country = lc($country);
202     if (exists $COUNTRIES->[$codeset]->{$country})
203     {
204         return $COUNTRIES->[$codeset]->{$country};
205     }
206     else
207     {
208         #---------------------------------------------------------------
209         # no such country!
210         #---------------------------------------------------------------
211         return undef;
212     }
213 }
214
215 sub country_code2code
216 {
217     (@_ == 3) or croak "country_code2code() takes 3 arguments!";
218
219     my $code = shift;
220     my $inset = shift;
221     my $outset = shift;
222     my $outcode = shift;
223     my $country;
224
225
226     return undef if $inset == $outset;
227     $country = code2country($code, $inset);
228     return undef if not defined $country;
229     $outcode = country2code($country, $outset);
230     return $outcode;
231 }
232
233 #=======================================================================
234
235 =head1 QUERY ROUTINES
236
237 There are two function which can be used to obtain a list of all codes,
238 or all country names:
239
240 =over 8
241
242 =item C<all_country_codes( [ CODESET ] )>
243
244 Returns a list of all two-letter country codes.
245 The codes are guaranteed to be all lower-case,
246 and not in any particular order.
247
248 =item C<all_country_names( [ CODESET ] )>
249
250 Returns a list of all country names for which there is a corresponding
251 country code in the specified code set.
252 The names are capitalised, and not returned in any particular order.
253
254 Not all countries have alpha-3 and numeric codes -
255 some just have an alpha-2 code,
256 so you'll get a different number of countries
257 depending on which code set you specify.
258
259 =back
260
261 =cut
262
263 #=======================================================================
264 sub all_country_codes
265 {
266     my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
267
268     return keys %{ $CODES->[$codeset] };
269 }
270
271 sub all_country_names
272 {
273     my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
274
275     return values %{ $CODES->[$codeset] };
276 }
277
278 #-----------------------------------------------------------------------
279
280 =head1 CODE ALIASING
281
282 This module supports a semi-private routine for specifying two letter
283 code aliases.
284
285     Locale::Country::_alias_code( ALIAS => CODE [, CODESET ] )
286
287 This feature was added as a mechanism for handling
288 a "uk" code. The ISO standard says that the two-letter code for
289 "United Kingdom" is "gb", whereas domain names are all .uk.
290
291 By default the module does not understand "uk", since it is implementing
292 an ISO standard. If you would like 'uk' to work as the two-letter
293 code for United Kingdom, use the following:
294
295     use Locale::Country;
296     
297     Locale::Country::_alias_code('uk' => 'gb');
298
299 With this code, both "uk" and "gb" are valid codes for United Kingdom,
300 with the reverse lookup returning "uk" rather than the usual "gb".
301
302 =cut
303
304 #-----------------------------------------------------------------------
305
306 sub _alias_code
307 {
308     my $alias = shift;
309     my $real  = shift;
310     my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
311
312     my $country;
313
314
315     if (not exists $CODES->[$codeset]->{$real})
316     {
317         carp "attempt to alias \"$alias\" to unknown country code \"$real\"\n";
318         return undef;
319     }
320     $country = $CODES->[$codeset]->{$real};
321     $CODES->[$codeset]->{$alias} = $country;
322     $COUNTRIES->[$codeset]->{"\L$country"} = $alias;
323
324     return $alias;
325 }
326
327 #-----------------------------------------------------------------------
328
329 =head1 EXAMPLES
330
331 The following example illustrates use of the C<code2country()> function.
332 The user is prompted for a country code, and then told the corresponding
333 country name:
334
335     $| = 1;   # turn off buffering
336     
337     print "Enter country code: ";
338     chop($code = <STDIN>);
339     $country = code2country($code, LOCALE_CODE_ALPHA_2);
340     if (defined $country)
341     {
342         print "$code = $country\n";
343     }
344     else
345     {
346         print "'$code' is not a valid country code!\n";
347     }
348
349 =head1 DOMAIN NAMES
350
351 Most top-level domain names are based on these codes,
352 but there are certain codes which aren't.
353 If you are using this module to identify country from hostname,
354 your best bet is to preprocess the country code.
355
356 For example, B<edu>, B<com>, B<gov> and friends would map to B<us>;
357 B<uk> would map to B<gb>. Any others?
358
359 =head1 KNOWN BUGS AND LIMITATIONS
360
361 =over 4
362
363 =item *
364
365 When using C<country2code()>, the country name must currently appear
366 exactly as it does in the source of the module. The module now supports
367 a small number of variants.
368
369 Possible extensions to this are: an interface for getting at the
370 list of variant names, and regular expression matches.
371
372 =item *
373
374 In the current implementation, all data is read in when the
375 module is loaded, and then held in memory.
376 A lazy implementation would be more memory friendly.
377
378 =item *
379
380 Support for country names in different languages.
381
382 =back
383
384 =head1 SEE ALSO
385
386 =over 4
387
388 =item Locale::Language
389
390 ISO two letter codes for identification of language (ISO 639).
391
392 =item Locale::Script
393
394 ISO codes for identification of scripts (ISO 15924).
395
396 =item Locale::Currency
397
398 ISO three letter codes for identification of currencies
399 and funds (ISO 4217).
400
401 =item ISO 3166
402
403 The ISO standard which defines these codes.
404
405 =item http://www.din.de/gremien/nas/nabd/iso3166ma/
406
407 Official home page for ISO 3166
408
409 =item http://www.egt.ie/standards/iso3166/iso3166-1-en.html
410
411 Another useful, but not official, home page.
412
413 =item http://www.cia.gov/cia/publications/factbook/docs/app-f.html
414
415 An appendix in the CIA world fact book which lists country codes
416 as defined by ISO 3166, FIPS 10-4, and internet domain names.
417
418 =back
419
420
421 =head1 AUTHOR
422
423 Neil Bowers E<lt>neil@bowers.comE<gt>
424
425 =head1 COPYRIGHT
426
427 Copyright (C) 2002, Neil Bowers.
428
429 Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
430
431 This module is free software; you can redistribute it and/or
432 modify it under the same terms as Perl itself.
433
434 =cut
435
436 #-----------------------------------------------------------------------
437
438 #=======================================================================
439 # initialisation code - stuff the DATA into the ALPHA2 hash
440 #=======================================================================
441 {
442     my ($alpha2, $alpha3, $numeric);
443     my ($country, @countries);
444
445
446     while (<DATA>)
447     {
448         next unless /\S/;
449         chop;
450         ($alpha2, $alpha3, $numeric, @countries) = split(/:/, $_);
451
452         $CODES->[LOCALE_CODE_ALPHA_2]->{$alpha2} = $countries[0];
453         foreach $country (@countries)
454         {
455             $COUNTRIES->[LOCALE_CODE_ALPHA_2]->{"\L$country"} = $alpha2;
456         }
457
458         if ($alpha3)
459         {
460             $CODES->[LOCALE_CODE_ALPHA_3]->{$alpha3} = $countries[0];
461             foreach $country (@countries)
462             {
463                 $COUNTRIES->[LOCALE_CODE_ALPHA_3]->{"\L$country"} = $alpha3;
464             }
465         }
466
467         if ($numeric)
468         {
469             $CODES->[LOCALE_CODE_NUMERIC]->{$numeric} = $countries[0];
470             foreach $country (@countries)
471             {
472                 $COUNTRIES->[LOCALE_CODE_NUMERIC]->{"\L$country"} = $numeric;
473             }
474         }
475
476     }
477 }
478
479 1;
480
481 __DATA__
482 ad:and:020:Andorra
483 ae:are:784:United Arab Emirates
484 af:afg:004:Afghanistan
485 ag:atg:028:Antigua and Barbuda
486 ai:aia:660:Anguilla
487 al:alb:008:Albania
488 am:arm:051:Armenia
489 an:ant:530:Netherlands Antilles
490 ao:ago:024:Angola
491 aq:::Antarctica
492 ar:arg:032:Argentina
493 as:asm:016:American Samoa
494 at:aut:040:Austria
495 au:aus:036:Australia
496 aw:abw:533:Aruba
497 az:aze:031:Azerbaijan
498 ba:bih:070:Bosnia and Herzegovina
499 bb:brb:052:Barbados
500 bd:bgd:050:Bangladesh
501 be:bel:056:Belgium
502 bf:bfa:854:Burkina Faso
503 bg:bgr:100:Bulgaria
504 bh:bhr:048:Bahrain
505 bi:bdi:108:Burundi
506 bj:ben:204:Benin
507 bm:bmu:060:Bermuda
508 bn:brn:096:Brunei Darussalam
509 bo:bol:068:Bolivia
510 br:bra:076:Brazil
511 bs:bhs:044:Bahamas
512 bt:btn:064:Bhutan
513 bv:::Bouvet Island
514 bw:bwa:072:Botswana
515 by:blr:112:Belarus
516 bz:blz:084:Belize
517 ca:can:124:Canada
518 cc:::Cocos (Keeling) Islands
519 cd:cod:180:Congo, The Democratic Republic of the:Congo, Democratic Republic of the
520 cf:caf:140:Central African Republic
521 cg:cog:178:Congo
522 ch:che:756:Switzerland
523 ci:civ:384:Cote D'Ivoire
524 ck:cok:184:Cook Islands
525 cl:chl:152:Chile
526 cm:cmr:120:Cameroon
527 cn:chn:156:China
528 co:col:170:Colombia
529 cr:cri:188:Costa Rica
530 cu:cub:192:Cuba
531 cv:cpv:132:Cape Verde
532 cx:::Christmas Island
533 cy:cyp:196:Cyprus
534 cz:cze:203:Czech Republic
535 de:deu:276:Germany
536 dj:dji:262:Djibouti
537 dk:dnk:208:Denmark
538 dm:dma:212:Dominica
539 do:dom:214:Dominican Republic
540 dz:dza:012:Algeria
541 ec:ecu:218:Ecuador
542 ee:est:233:Estonia
543 eg:egy:818:Egypt
544 eh:esh:732:Western Sahara
545 er:eri:232:Eritrea
546 es:esp:724:Spain
547 et:eth:231:Ethiopia
548 fi:fin:246:Finland
549 fj:fji:242:Fiji
550 fk:flk:238:Falkland Islands (Malvinas):Falkland Islands (Islas Malvinas)
551 fm:fsm:583:Micronesia, Federated States of
552 fo:fro:234:Faroe Islands
553 fr:fra:250:France
554 fx:::France, Metropolitan
555 ga:gab:266:Gabon
556 gb:gbr:826:United Kingdom:Great Britain
557 gd:grd:308:Grenada
558 ge:geo:268:Georgia
559 gf:guf:254:French Guiana
560 gh:gha:288:Ghana
561 gi:gib:292:Gibraltar
562 gl:grl:304:Greenland
563 gm:gmb:270:Gambia
564 gn:gin:324:Guinea
565 gp:glp:312:Guadeloupe
566 gq:gnq:226:Equatorial Guinea
567 gr:grc:300:Greece
568 gs:::South Georgia and the South Sandwich Islands
569 gt:gtm:320:Guatemala
570 gu:gum:316:Guam
571 gw:gnb:624:Guinea-Bissau
572 gy:guy:328:Guyana
573 hk:hkg:344:Hong Kong
574 hm:::Heard Island and McDonald Islands
575 hn:hnd:340:Honduras
576 hr:hrv:191:Croatia
577 ht:hti:332:Haiti
578 hu:hun:348:Hungary
579 id:idn:360:Indonesia
580 ie:irl:372:Ireland
581 il:isr:376:Israel
582 in:ind:356:India
583 io:::British Indian Ocean Territory
584 iq:irq:368:Iraq
585 ir:irn:364:Iran, Islamic Republic of:Iran
586 is:isl:352:Iceland
587 it:ita:380:Italy
588 jm:jam:388:Jamaica
589 jo:jor:400:Jordan
590 jp:jpn:392:Japan
591 ke:ken:404:Kenya
592 kg:kgz:417:Kyrgyzstan
593 kh:khm:116:Cambodia
594 ki:kir:296:Kiribati
595 km:com:174:Comoros
596 kn:kna:659:Saint Kitts and Nevis
597 kp:prk:408:Korea, Democratic People's Republic of:Korea, North:North Korea
598 kr:kor:410:Korea, Republic of:Korea, South:South Korea
599 kw:kwt:414:Kuwait
600 ky:cym:136:Cayman Islands
601 kz:kaz:398:Kazakstan
602 la:lao:418:Lao People's Democratic Republic
603 lb:lbn:422:Lebanon
604 lc:lca:662:Saint Lucia
605 li:lie:438:Liechtenstein
606 lk:lka:144:Sri Lanka
607 lr:lbr:430:Liberia
608 ls:lso:426:Lesotho
609 lt:ltu:440:Lithuania
610 lu:lux:442:Luxembourg
611 lv:lva:428:Latvia
612 ly:lby:434:Libyan Arab Jamahiriya:Libya
613 ma:mar:504:Morocco
614 mc:mco:492:Monaco
615 md:mda:498:Moldova, Republic of
616 mg:mdg:450:Madagascar
617 mh:mhl:584:Marshall Islands
618 mk:mkd:807:Macedonia, the Former Yugoslav Republic of:Macedonia, Former Yugoslav Republic of:Macedonia
619 ml:mli:466:Mali
620 mm:mmr:104:Myanmar
621 mn:mng:496:Mongolia
622 mo:mac:446:Macau
623 mp:mnp:580:Northern Mariana Islands
624 mq:mtq:474:Martinique
625 mr:mrt:478:Mauritania
626 ms:msr:500:Montserrat
627 mt:mlt:470:Malta
628 mu:mus:480:Mauritius
629 mv:mdv:462:Maldives
630 mw:mwi:454:Malawi
631 mx:mex:484:Mexico
632 my:mys:458:Malaysia
633 mz:moz:508:Mozambique
634 na:nam:516:Namibia
635 nc:ncl:540:New Caledonia
636 ne:ner:562:Niger
637 nf:nfk:574:Norfolk Island
638 ng:nga:566:Nigeria
639 ni:nic:558:Nicaragua
640 nl:nld:528:Netherlands
641 no:nor:578:Norway
642 np:npl:524:Nepal
643 nr:nru:520:Nauru
644 nu:niu:570:Niue
645 nz:nzl:554:New Zealand
646 om:omn:512:Oman
647 pa:pan:591:Panama
648 pe:per:604:Peru
649 pf:pyf:258:French Polynesia
650 pg:png:598:Papua New Guinea
651 ph:phl:608:Philippines
652 pk:pak:586:Pakistan
653 pl:pol:616:Poland
654 pm:spm:666:Saint Pierre and Miquelon
655 pn:pcn:612:Pitcairn:Pitcairn Island
656 pr:pri:630:Puerto Rico
657 ps:pse:275:Palestinian Territory, Occupied
658 pt:prt:620:Portugal
659 pw:plw:585:Palau
660 py:pry:600:Paraguay
661 qa:qat:634:Qatar
662 re:reu:638:Reunion
663 ro:rom:642:Romania
664 ru:rus:643:Russian Federation:Russia
665 rw:rwa:646:Rwanda
666 sa:sau:682:Saudi Arabia
667 sb:slb:090:Solomon Islands
668 sc:syc:690:Seychelles
669 sd:sdn:736:Sudan
670 se:swe:752:Sweden
671 sg:sgp:702:Singapore
672 sh:shn:654:Saint Helena
673 si:svn:705:Slovenia
674 sj:sjm:744:Svalbard and Jan Mayen:Jan Mayen:Svalbard
675 sk:svk:703:Slovakia
676 sl:sle:694:Sierra Leone
677 sm:smr:674:San Marino
678 sn:sen:686:Senegal
679 so:som:706:Somalia
680 sr:sur:740:Suriname
681 st:stp:678:Sao Tome and Principe
682 sv:slv:222:El Salvador
683 sy:syr:760:Syrian Arab Republic:Syria
684 sz:swz:748:Swaziland
685 tc:tca:796:Turks and Caicos Islands
686 td:tcd:148:Chad
687 tf:::French Southern Territories
688 tg:tgo:768:Togo
689 th:tha:764:Thailand
690 tj:tjk:762:Tajikistan
691 tk:tkl:772:Tokelau
692 tm:tkm:795:Turkmenistan
693 tn:tun:788:Tunisia
694 to:ton:776:Tonga
695 tp:tmp:626:East Timor
696 tr:tur:792:Turkey
697 tt:tto:780:Trinidad and Tobago
698 tv:tuv:798:Tuvalu
699 tw:twn:158:Taiwan, Province of China:Taiwan
700 tz:tza:834:Tanzania, United Republic of:Tanzania
701 ua:ukr:804:Ukraine
702 ug:uga:800:Uganda
703 um:::United States Minor Outlying Islands
704 us:usa:840:United States:USA:United States of America
705 uy:ury:858:Uruguay
706 uz:uzb:860:Uzbekistan
707 va:vat:336:Holy See (Vatican City State):Hole See (Vatican City)
708 vc:vct:670:Saint Vincent and the Grenadines
709 ve:ven:862:Venezuela
710 vg:vgb:092:Virgin Islands, British:British Virgin Islands
711 vi:vir:850:Virgin Islands, U.S.
712 vn:vnm:704:Vietnam
713 vu:vut:548:Vanuatu
714 wf:wlf:876:Wallis and Futuna
715 ws:wsm:882:Samoa
716 ye:yem:887:Yemen
717 yt:::Mayotte
718 yu:yug:891:Yugoslavia
719 za:zaf:710:South Africa
720 zm:zmb:894:Zambia
721 zr:::Zaire
722 zw:zwe:716:Zimbabwe