[Summary view] [Print] [Text view]

   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