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