1
#-----------------------------------------------------------------------
5
Locale::Country - ISO codes for country identification (ISO 3166)
11
$country = code2country('jp'); # $country gets 'Japan'
12
$code = country2code('Norway'); # $code gets 'no'
14
@codes = all_country_codes();
15
@names = all_country_names();
17
# add "uk" as a pseudo country code for United Kingdom
18
Locale::Country::_alias_code('uk' => 'gb');
22
#-----------------------------------------------------------------------
24
package Locale::Country;
28
#-----------------------------------------------------------------------
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.
38
There are three different code sets you can use for identifying
45
Two letter codes, such as 'tv' for Tuvalu.
46
This code set is identified with the symbol C<LOCALE_CODE_ALPHA_2>.
50
Three letter codes, such as 'brb' for Barbados.
51
This code set is identified with the symbol C<LOCALE_CODE_ALPHA_3>.
55
Numeric codes, such as 064 for Bhutan.
56
This code set is identified with the symbol C<LOCALE_CODE_NUMERIC>.
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.
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.
74
#-----------------------------------------------------------------------
78
use Locale::Constants;
81
#-----------------------------------------------------------------------
82
# Public Global Variables
83
#-----------------------------------------------------------------------
84
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
85
$VERSION = sprintf("%d.%02d", q$Revision: 1.2 $ =~ /(\d+)\.(\d+)/);
87
@EXPORT = qw(code2country country2code
88
all_country_codes all_country_names
90
LOCALE_CODE_ALPHA_2 LOCALE_CODE_ALPHA_3 LOCALE_CODE_NUMERIC);
92
#-----------------------------------------------------------------------
93
# Private Global Variables
94
#-----------------------------------------------------------------------
99
#=======================================================================
101
=head1 CONVERSION ROUTINES
103
There are three conversion routines: C<code2country()>, C<country2code()>,
104
and C<country_code2code()>.
108
=item code2country( CODE, [ CODESET ] )
110
This function takes a country code and returns a string
111
which contains the name of the country identified.
112
If the code is not a valid country code, as defined by ISO 3166,
113
then C<undef> will be returned:
115
$country = code2country('fi');
117
=item country2code( STRING, [ CODESET ] )
119
This function takes a country name and returns the corresponding
120
country code, if such exists.
121
If the argument could not be identified as a country name,
122
then C<undef> will be returned:
124
$code = country2code('Norway', LOCALE_CODE_ALPHA_3);
125
# $code will now be 'nor'
127
The case of the country name is not important.
128
See the section L<KNOWN BUGS AND LIMITATIONS> below.
130
=item country_code2code( CODE, CODESET, CODESET )
132
This function takes a country code from one code set,
133
and returns the corresponding code from another code set.
135
$alpha2 = country_code2code('fin',
136
LOCALE_CODE_ALPHA_3 => LOCALE_CODE_ALPHA_2);
137
# $alpha2 will now be 'fi'
139
If the code passed is not a valid country code in
140
the first code set, or if there isn't a code for the
141
corresponding country in the second code set,
142
then C<undef> will be returned.
148
#=======================================================================
152
my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
155
return undef unless defined $code;
157
#-------------------------------------------------------------------
158
# Make sure the code is in the right form before we use it
159
# to look up the corresponding country.
160
# We have to sprintf because the codes are given as 3-digits,
161
# with leading 0's. Eg 052 for Barbados.
162
#-------------------------------------------------------------------
163
if ($codeset == LOCALE_CODE_NUMERIC)
165
return undef if ($code =~ /\D/);
166
$code = sprintf("%.3d", $code);
173
if (exists $CODES->[$codeset]->{$code})
175
return $CODES->[$codeset]->{$code};
179
#---------------------------------------------------------------
180
# no such country code!
181
#---------------------------------------------------------------
189
my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
192
return undef unless defined $country;
193
$country = lc($country);
194
if (exists $COUNTRIES->[$codeset]->{$country})
196
return $COUNTRIES->[$codeset]->{$country};
200
#---------------------------------------------------------------
202
#---------------------------------------------------------------
207
sub country_code2code
209
(@_ == 3) or croak "country_code2code() takes 3 arguments!";
218
return undef if $inset == $outset;
219
$country = code2country($code, $inset);
220
return undef if not defined $country;
221
$outcode = country2code($country, $outset);
225
#=======================================================================
227
=head1 QUERY ROUTINES
229
There are two function which can be used to obtain a list of all codes,
230
or all country names:
234
=item C<all_country_codes( [ CODESET ] )>
236
Returns a list of all two-letter country codes.
237
The codes are guaranteed to be all lower-case,
238
and not in any particular order.
240
=item C<all_country_names( [ CODESET ] )>
242
Returns a list of all country names for which there is a corresponding
243
country code in the specified code set.
244
The names are capitalised, and not returned in any particular order.
246
Not all countries have alpha-3 and numeric codes -
247
some just have an alpha-2 code,
248
so you'll get a different number of countries
249
depending on which code set you specify.
255
#=======================================================================
256
sub all_country_codes
258
my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
260
return keys %{ $CODES->[$codeset] };
263
sub all_country_names
265
my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
267
return values %{ $CODES->[$codeset] };
270
#-----------------------------------------------------------------------
274
This module supports a semi-private routine for specifying two letter
277
Locale::Country::_alias_code( ALIAS => CODE [, CODESET ] )
279
This feature was added as a mechanism for handling
280
a "uk" code. The ISO standard says that the two-letter code for
281
"United Kingdom" is "gb", whereas domain names are all .uk.
283
By default the module does not understand "uk", since it is implementing
284
an ISO standard. If you would like 'uk' to work as the two-letter
285
code for United Kingdom, use the following:
289
Locale::Country::_alias_code('uk' => 'gb');
291
With this code, both "uk" and "gb" are valid codes for United Kingdom,
292
with the reverse lookup returning "uk" rather than the usual "gb".
296
#-----------------------------------------------------------------------
302
my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
307
if (not exists $CODES->[$codeset]->{$real})
309
carp "attempt to alias \"$alias\" to unknown country code \"$real\"\n";
312
$country = $CODES->[$codeset]->{$real};
313
$CODES->[$codeset]->{$alias} = $country;
314
$COUNTRIES->[$codeset]->{"\L$country"} = $alias;
319
#-----------------------------------------------------------------------
323
The following example illustrates use of the C<code2country()> function.
324
The user is prompted for a country code, and then told the corresponding
327
$| = 1; # turn off buffering
329
print "Enter country code: ";
330
chop($code = <STDIN>);
331
$country = code2country($code, LOCALE_CODE_ALPHA_2);
332
if (defined $country)
334
print "$code = $country\n";
338
print "'$code' is not a valid country code!\n";
343
Most top-level domain names are based on these codes,
344
but there are certain codes which aren't.
345
If you are using this module to identify country from hostname,
346
your best bet is to preprocess the country code.
348
For example, B<edu>, B<com>, B<gov> and friends would map to B<us>;
349
B<uk> would map to B<gb>. Any others?
351
=head1 KNOWN BUGS AND LIMITATIONS
357
When using C<country2code()>, the country name must currently appear
358
exactly as it does in the source of the module. For example,
360
country2code('United States')
362
will return B<us>, as expected. But the following will all return C<undef>:
364
country2code('United States of America')
365
country2code('Great Britain')
366
country2code('U.S.A.')
368
If there's need for it, a future version could have variants
373
In the current implementation, all data is read in when the
374
module is loaded, and then held in memory.
375
A lazy implementation would be more memory friendly.
383
=item Locale::Language
385
ISO two letter codes for identification of language (ISO 639).
387
=item Locale::Currency
389
ISO three letter codes for identification of currencies
390
and funds (ISO 4217).
394
The ISO standard which defines these codes.
396
=item http://www.din.de/gremien/nas/nabd/iso3166ma/
398
Official home page for ISO 3166
400
=item http://www.egt.ie/standards/iso3166/iso3166-1-en.html
402
Another useful, but not official, home page.
404
=item http://www.cia.gov/cia/publications/factbook/docs/app-f.html
406
An appendix in the CIA world fact book which lists country codes
407
as defined by ISO 3166, FIPS 10-4, and internet domain names.
414
Neil Bowers E<lt>neilb@cre.canon.co.ukE<gt>
418
Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
420
This module is free software; you can redistribute it and/or
421
modify it under the same terms as Perl itself.
425
#-----------------------------------------------------------------------
427
#=======================================================================
428
# initialisation code - stuff the DATA into the ALPHA2 hash
429
#=======================================================================
431
my ($alpha2, $alpha3, $numeric);
434
open(DATA, "/usr/share/iso-codes/iso-codes-2.tab") ||
435
die "iso-codes data file not present";
441
($alpha2, $alpha3, $numeric, $country) = split(/\t/, $_, 4);
443
$CODES->[LOCALE_CODE_ALPHA_2]->{$alpha2} = $country;
444
$COUNTRIES->[LOCALE_CODE_ALPHA_2]->{"\L$country"} = $alpha2;
448
$CODES->[LOCALE_CODE_ALPHA_3]->{$alpha3} = $country;
449
$COUNTRIES->[LOCALE_CODE_ALPHA_3]->{"\L$country"} = $alpha3;
454
$CODES->[LOCALE_CODE_NUMERIC]->{$numeric} = $country;
455
$COUNTRIES->[LOCALE_CODE_NUMERIC]->{"\L$country"} = $numeric;
added
removed
notes/Country.pm
