1 |
|
---|
2 | =head1 NAME
|
---|
3 |
|
---|
4 | Locale::Country - ISO codes for country identification (ISO 3166)
|
---|
5 |
|
---|
6 | =head1 SYNOPSIS
|
---|
7 |
|
---|
8 | use Locale::Country;
|
---|
9 |
|
---|
10 | $country = code2country('jp'); # $country gets 'Japan'
|
---|
11 | $code = country2code('Norway'); # $code gets 'no'
|
---|
12 |
|
---|
13 | @codes = all_country_codes();
|
---|
14 | @names = all_country_names();
|
---|
15 |
|
---|
16 | # semi-private routines
|
---|
17 | Locale::Country::alias_code('uk' => 'gb');
|
---|
18 | Locale::Country::rename_country('gb' => 'Great Britain');
|
---|
19 |
|
---|
20 |
|
---|
21 | =head1 DESCRIPTION
|
---|
22 |
|
---|
23 | The C<Locale::Country> module provides access to the ISO
|
---|
24 | codes for identifying countries, as defined in ISO 3166-1.
|
---|
25 | You can either access the codes via the L<conversion routines>
|
---|
26 | (described below), or with the two functions which return lists
|
---|
27 | of all country codes or all country names.
|
---|
28 |
|
---|
29 | There are three different code sets you can use for identifying
|
---|
30 | countries:
|
---|
31 |
|
---|
32 | =over 4
|
---|
33 |
|
---|
34 | =item B<alpha-2>
|
---|
35 |
|
---|
36 | Two letter codes, such as 'tv' for Tuvalu.
|
---|
37 | This code set is identified with the symbol C<LOCALE_CODE_ALPHA_2>.
|
---|
38 |
|
---|
39 | =item B<alpha-3>
|
---|
40 |
|
---|
41 | Three letter codes, such as 'brb' for Barbados.
|
---|
42 | This code set is identified with the symbol C<LOCALE_CODE_ALPHA_3>.
|
---|
43 |
|
---|
44 | =item B<numeric>
|
---|
45 |
|
---|
46 | Numeric codes, such as 064 for Bhutan.
|
---|
47 | This code set is identified with the symbol C<LOCALE_CODE_NUMERIC>.
|
---|
48 |
|
---|
49 | =back
|
---|
50 |
|
---|
51 | All of the routines take an optional additional argument
|
---|
52 | which specifies the code set to use.
|
---|
53 | If not specified, it defaults to the two-letter codes.
|
---|
54 | This is partly for backwards compatibility (previous versions
|
---|
55 | of this module only supported the alpha-2 codes), and
|
---|
56 | partly because they are the most widely used codes.
|
---|
57 |
|
---|
58 | The alpha-2 and alpha-3 codes are not case-dependent,
|
---|
59 | so you can use 'BO', 'Bo', 'bO' or 'bo' for Bolivia.
|
---|
60 | When a code is returned by one of the functions in
|
---|
61 | this module, it will always be lower-case.
|
---|
62 |
|
---|
63 | As of version 2.00, Locale::Country supports variant
|
---|
64 | names for countries. So, for example, the country code for "United States"
|
---|
65 | is "us", so country2code('United States') returns 'us'.
|
---|
66 | Now the following will also return 'us':
|
---|
67 |
|
---|
68 | country2code('United States of America')
|
---|
69 | country2code('USA')
|
---|
70 |
|
---|
71 |
|
---|
72 | =head1 CONVERSION ROUTINES
|
---|
73 |
|
---|
74 | There are three conversion routines: C<code2country()>, C<country2code()>,
|
---|
75 | and C<country_code2code()>.
|
---|
76 |
|
---|
77 | =over 4
|
---|
78 |
|
---|
79 | =item code2country( CODE, [ CODESET ] )
|
---|
80 |
|
---|
81 | This function takes a country code and returns a string
|
---|
82 | which contains the name of the country identified.
|
---|
83 | If the code is not a valid country code, as defined by ISO 3166,
|
---|
84 | then C<undef> will be returned:
|
---|
85 |
|
---|
86 | $country = code2country('fi');
|
---|
87 |
|
---|
88 | =item country2code( STRING, [ CODESET ] )
|
---|
89 |
|
---|
90 | This function takes a country name and returns the corresponding
|
---|
91 | country code, if such exists.
|
---|
92 | If the argument could not be identified as a country name,
|
---|
93 | then C<undef> will be returned:
|
---|
94 |
|
---|
95 | $code = country2code('Norway', LOCALE_CODE_ALPHA_3);
|
---|
96 | # $code will now be 'nor'
|
---|
97 |
|
---|
98 | The case of the country name is not important.
|
---|
99 | See the section L<KNOWN BUGS AND LIMITATIONS> below.
|
---|
100 |
|
---|
101 | =item country_code2code( CODE, CODESET, CODESET )
|
---|
102 |
|
---|
103 | This function takes a country code from one code set,
|
---|
104 | and returns the corresponding code from another code set.
|
---|
105 |
|
---|
106 | $alpha2 = country_code2code('fin',
|
---|
107 | LOCALE_CODE_ALPHA_3, LOCALE_CODE_ALPHA_2);
|
---|
108 | # $alpha2 will now be 'fi'
|
---|
109 |
|
---|
110 | If the code passed is not a valid country code in
|
---|
111 | the first code set, or if there isn't a code for the
|
---|
112 | corresponding country in the second code set,
|
---|
113 | then C<undef> will be returned.
|
---|
114 |
|
---|
115 | =back
|
---|
116 |
|
---|
117 |
|
---|
118 | =head1 QUERY ROUTINES
|
---|
119 |
|
---|
120 | There are two function which can be used to obtain a list of all codes,
|
---|
121 | or all country names:
|
---|
122 |
|
---|
123 | =over 4
|
---|
124 |
|
---|
125 | =item C<all_country_codes( [ CODESET ] )>
|
---|
126 |
|
---|
127 | Returns a list of all two-letter country codes.
|
---|
128 | The codes are guaranteed to be all lower-case,
|
---|
129 | and not in any particular order.
|
---|
130 |
|
---|
131 | =item C<all_country_names( [ CODESET ] )>
|
---|
132 |
|
---|
133 | Returns a list of all country names for which there is a corresponding
|
---|
134 | country code in the specified code set.
|
---|
135 | The names are capitalised, and not returned in any particular order.
|
---|
136 |
|
---|
137 | Not all countries have alpha-3 and numeric codes -
|
---|
138 | some just have an alpha-2 code,
|
---|
139 | so you'll get a different number of countries
|
---|
140 | depending on which code set you specify.
|
---|
141 |
|
---|
142 | =back
|
---|
143 |
|
---|
144 |
|
---|
145 | =head1 SEMI-PRIVATE ROUTINES
|
---|
146 |
|
---|
147 | Locale::Country provides two semi-private routines for modifying
|
---|
148 | the internal data.
|
---|
149 | Given their status, they aren't exported by default,
|
---|
150 | and so need to be called by prefixing the function name with the
|
---|
151 | package name.
|
---|
152 |
|
---|
153 | =head2 alias_code
|
---|
154 |
|
---|
155 | Define a new code as an alias for an existing code:
|
---|
156 |
|
---|
157 | Locale::Country::alias_code( ALIAS => CODE [, CODESET ] )
|
---|
158 |
|
---|
159 | This feature was added as a mechanism for handling
|
---|
160 | a "uk" code. The ISO standard says that the two-letter code for
|
---|
161 | "United Kingdom" is "gb", whereas domain names are all .uk.
|
---|
162 |
|
---|
163 | By default the module does not understand "uk", since it is implementing
|
---|
164 | an ISO standard. If you would like 'uk' to work as the two-letter
|
---|
165 | code for United Kingdom, use the following:
|
---|
166 |
|
---|
167 | Locale::Country::alias_code('uk' => 'gb');
|
---|
168 |
|
---|
169 | With this code, both "uk" and "gb" are valid codes for United Kingdom,
|
---|
170 | with the reverse lookup returning "uk" rather than the usual "gb".
|
---|
171 |
|
---|
172 | B<Note:> this function was previously called _alias_code,
|
---|
173 | but the leading underscore has been dropped.
|
---|
174 | The old name will be supported for all 2.X releases for
|
---|
175 | backwards compatibility.
|
---|
176 |
|
---|
177 | =head2 rename_country
|
---|
178 |
|
---|
179 | If the official country name just isn't good enough for you,
|
---|
180 | you can rename a country. For example, the official country
|
---|
181 | name for code 'gb' is 'United Kingdom'.
|
---|
182 | If you want to change that, you might call:
|
---|
183 |
|
---|
184 | Locale::Country::rename_country('gb' => 'Great Britain');
|
---|
185 |
|
---|
186 | This means that calling code2country('gb') will now return
|
---|
187 | 'Great Britain' instead of 'United Kingdom'.
|
---|
188 | The original country name is retained as an alias,
|
---|
189 | so for the above example, country2code('United Kingdom')
|
---|
190 | will still return 'gb'.
|
---|
191 |
|
---|
192 |
|
---|
193 | =head1 EXAMPLES
|
---|
194 |
|
---|
195 | The following example illustrates use of the C<code2country()> function.
|
---|
196 | The user is prompted for a country code, and then told the corresponding
|
---|
197 | country name:
|
---|
198 |
|
---|
199 | $| = 1; # turn off buffering
|
---|
200 |
|
---|
201 | print "Enter country code: ";
|
---|
202 | chop($code = <STDIN>);
|
---|
203 | $country = code2country($code, LOCALE_CODE_ALPHA_2);
|
---|
204 | if (defined $country)
|
---|
205 | {
|
---|
206 | print "$code = $country\n";
|
---|
207 | }
|
---|
208 | else
|
---|
209 | {
|
---|
210 | print "'$code' is not a valid country code!\n";
|
---|
211 | }
|
---|
212 |
|
---|
213 | =head1 DOMAIN NAMES
|
---|
214 |
|
---|
215 | Most top-level domain names are based on these codes,
|
---|
216 | but there are certain codes which aren't.
|
---|
217 | If you are using this module to identify country from hostname,
|
---|
218 | your best bet is to preprocess the country code.
|
---|
219 |
|
---|
220 | For example, B<edu>, B<com>, B<gov> and friends would map to B<us>;
|
---|
221 | B<uk> would map to B<gb>. Any others?
|
---|
222 |
|
---|
223 | =head1 KNOWN BUGS AND LIMITATIONS
|
---|
224 |
|
---|
225 | =over 4
|
---|
226 |
|
---|
227 | =item *
|
---|
228 |
|
---|
229 | When using C<country2code()>, the country name must currently appear
|
---|
230 | exactly as it does in the source of the module. The module now supports
|
---|
231 | a small number of variants.
|
---|
232 |
|
---|
233 | Possible extensions to this are: an interface for getting at the
|
---|
234 | list of variant names, and regular expression matches.
|
---|
235 |
|
---|
236 | =item *
|
---|
237 |
|
---|
238 | In the current implementation, all data is read in when the
|
---|
239 | module is loaded, and then held in memory.
|
---|
240 | A lazy implementation would be more memory friendly.
|
---|
241 |
|
---|
242 | =item *
|
---|
243 |
|
---|
244 | Support for country names in different languages.
|
---|
245 |
|
---|
246 | =back
|
---|
247 |
|
---|
248 | =head1 SEE ALSO
|
---|
249 |
|
---|
250 | =over 4
|
---|
251 |
|
---|
252 | =item Locale::Language
|
---|
253 |
|
---|
254 | ISO two letter codes for identification of language (ISO 639).
|
---|
255 |
|
---|
256 | =item Locale::Script
|
---|
257 |
|
---|
258 | ISO codes for identification of scripts (ISO 15924).
|
---|
259 |
|
---|
260 | =item Locale::Currency
|
---|
261 |
|
---|
262 | ISO three letter codes for identification of currencies
|
---|
263 | and funds (ISO 4217).
|
---|
264 |
|
---|
265 | =item Locale::SubCountry
|
---|
266 |
|
---|
267 | ISO codes for country sub-divisions (states, counties, provinces, etc),
|
---|
268 | as defined in ISO 3166-2.
|
---|
269 | This module is not part of the Locale-Codes distribution,
|
---|
270 | but is available from CPAN in CPAN/modules/by-module/Locale/
|
---|
271 |
|
---|
272 | =item ISO 3166-1
|
---|
273 |
|
---|
274 | The ISO standard which defines these codes.
|
---|
275 |
|
---|
276 | =item http://www.iso.org/iso/en/prods-services/iso3166ma/index.html
|
---|
277 |
|
---|
278 | Official home page for the ISO 3166 maintenance agency.
|
---|
279 |
|
---|
280 | =item http://www.egt.ie/standards/iso3166/iso3166-1-en.html
|
---|
281 |
|
---|
282 | Another useful, but not official, home page.
|
---|
283 |
|
---|
284 | =item http://www.cia.gov/cia/publications/factbook/docs/app-d-1.html
|
---|
285 |
|
---|
286 | An appendix in the CIA world fact book which lists country codes
|
---|
287 | as defined by ISO 3166, FIPS 10-4, and internet domain names.
|
---|
288 |
|
---|
289 | =back
|
---|
290 |
|
---|
291 |
|
---|
292 | =head1 AUTHOR
|
---|
293 |
|
---|
294 | Neil Bowers E<lt>[email protected]<gt>
|
---|
295 |
|
---|
296 | =head1 COPYRIGHT
|
---|
297 |
|
---|
298 | Copyright (C) 2002-2004, Neil Bowers.
|
---|
299 |
|
---|
300 | Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
|
---|
301 |
|
---|
302 | This module is free software; you can redistribute it and/or
|
---|
303 | modify it under the same terms as Perl itself.
|
---|
304 |
|
---|
305 | =cut
|
---|
306 |
|
---|