| 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>neil@bowers.comE<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 | |