Commit | Line | Data |
---|---|---|
6b14ceb7 JH |
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 |