diff options
author | Siep Kroonenberg <siepo@cybercomm.nl> | 2011-02-17 17:57:31 +0000 |
---|---|---|
committer | Siep Kroonenberg <siepo@cybercomm.nl> | 2011-02-17 17:57:31 +0000 |
commit | 320d8694fec25ed148613684543b5a0504a046ae (patch) | |
tree | 0ddcf933d3acd3c98a387fa2bf73d0554ca6e50d /Master/tlpkg/tlperl/lib/Locale/Country.pod | |
parent | 779e71f16ca01a6244b632b95bdb461fec163b34 (diff) |
New tlperl part XIV
git-svn-id: svn://tug.org/texlive/trunk@21436 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Locale/Country.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Locale/Country.pod | 306 |
1 files changed, 306 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Locale/Country.pod b/Master/tlpkg/tlperl/lib/Locale/Country.pod new file mode 100644 index 00000000000..b13cd22a4a7 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Locale/Country.pod @@ -0,0 +1,306 @@ + +=head1 NAME + +Locale::Country - ISO codes for country identification (ISO 3166) + +=head1 SYNOPSIS + + use Locale::Country; + + $country = code2country('jp'); # $country gets 'Japan' + $code = country2code('Norway'); # $code gets 'no' + + @codes = all_country_codes(); + @names = all_country_names(); + + # semi-private routines + Locale::Country::alias_code('uk' => 'gb'); + Locale::Country::rename_country('gb' => 'Great Britain'); + + +=head1 DESCRIPTION + +The C<Locale::Country> module provides access to the ISO +codes for identifying countries, as defined in ISO 3166-1. +You can either access the codes via the L<conversion routines> +(described below), or with the two functions which return lists +of all country codes or all country names. + +There are three different code sets you can use for identifying +countries: + +=over 4 + +=item B<alpha-2> + +Two letter codes, such as 'tv' for Tuvalu. +This code set is identified with the symbol C<LOCALE_CODE_ALPHA_2>. + +=item B<alpha-3> + +Three letter codes, such as 'brb' for Barbados. +This code set is identified with the symbol C<LOCALE_CODE_ALPHA_3>. + +=item B<numeric> + +Numeric codes, such as 064 for Bhutan. +This code set is identified with the symbol C<LOCALE_CODE_NUMERIC>. + +=back + +All of the routines take an optional additional argument +which specifies the code set to use. +If not specified, it defaults to the two-letter codes. +This is partly for backwards compatibility (previous versions +of this module only supported the alpha-2 codes), and +partly because they are the most widely used codes. + +The alpha-2 and alpha-3 codes are not case-dependent, +so you can use 'BO', 'Bo', 'bO' or 'bo' for Bolivia. +When a code is returned by one of the functions in +this module, it will always be lower-case. + +As of version 2.00, Locale::Country supports variant +names for countries. So, for example, the country code for "United States" +is "us", so country2code('United States') returns 'us'. +Now the following will also return 'us': + + country2code('United States of America') + country2code('USA') + + +=head1 CONVERSION ROUTINES + +There are three conversion routines: C<code2country()>, C<country2code()>, +and C<country_code2code()>. + +=over 4 + +=item code2country( CODE, [ CODESET ] ) + +This function takes a country code and returns a string +which contains the name of the country identified. +If the code is not a valid country code, as defined by ISO 3166, +then C<undef> will be returned: + + $country = code2country('fi'); + +=item country2code( STRING, [ CODESET ] ) + +This function takes a country name and returns the corresponding +country code, if such exists. +If the argument could not be identified as a country name, +then C<undef> will be returned: + + $code = country2code('Norway', LOCALE_CODE_ALPHA_3); + # $code will now be 'nor' + +The case of the country name is not important. +See the section L<KNOWN BUGS AND LIMITATIONS> below. + +=item country_code2code( CODE, CODESET, CODESET ) + +This function takes a country code from one code set, +and returns the corresponding code from another code set. + + $alpha2 = country_code2code('fin', + LOCALE_CODE_ALPHA_3, LOCALE_CODE_ALPHA_2); + # $alpha2 will now be 'fi' + +If the code passed is not a valid country code in +the first code set, or if there isn't a code for the +corresponding country in the second code set, +then C<undef> will be returned. + +=back + + +=head1 QUERY ROUTINES + +There are two function which can be used to obtain a list of all codes, +or all country names: + +=over 4 + +=item C<all_country_codes( [ CODESET ] )> + +Returns a list of all two-letter country codes. +The codes are guaranteed to be all lower-case, +and not in any particular order. + +=item C<all_country_names( [ CODESET ] )> + +Returns a list of all country names for which there is a corresponding +country code in the specified code set. +The names are capitalised, and not returned in any particular order. + +Not all countries have alpha-3 and numeric codes - +some just have an alpha-2 code, +so you'll get a different number of countries +depending on which code set you specify. + +=back + + +=head1 SEMI-PRIVATE ROUTINES + +Locale::Country provides two semi-private routines for modifying +the internal data. +Given their status, they aren't exported by default, +and so need to be called by prefixing the function name with the +package name. + +=head2 alias_code + +Define a new code as an alias for an existing code: + + Locale::Country::alias_code( ALIAS => CODE [, CODESET ] ) + +This feature was added as a mechanism for handling +a "uk" code. The ISO standard says that the two-letter code for +"United Kingdom" is "gb", whereas domain names are all .uk. + +By default the module does not understand "uk", since it is implementing +an ISO standard. If you would like 'uk' to work as the two-letter +code for United Kingdom, use the following: + + Locale::Country::alias_code('uk' => 'gb'); + +With this code, both "uk" and "gb" are valid codes for United Kingdom, +with the reverse lookup returning "uk" rather than the usual "gb". + +B<Note:> this function was previously called _alias_code, +but the leading underscore has been dropped. +The old name will be supported for all 2.X releases for +backwards compatibility. + +=head2 rename_country + +If the official country name just isn't good enough for you, +you can rename a country. For example, the official country +name for code 'gb' is 'United Kingdom'. +If you want to change that, you might call: + + Locale::Country::rename_country('gb' => 'Great Britain'); + +This means that calling code2country('gb') will now return +'Great Britain' instead of 'United Kingdom'. +The original country name is retained as an alias, +so for the above example, country2code('United Kingdom') +will still return 'gb'. + + +=head1 EXAMPLES + +The following example illustrates use of the C<code2country()> function. +The user is prompted for a country code, and then told the corresponding +country name: + + $| = 1; # turn off buffering + + print "Enter country code: "; + chop($code = <STDIN>); + $country = code2country($code, LOCALE_CODE_ALPHA_2); + if (defined $country) + { + print "$code = $country\n"; + } + else + { + print "'$code' is not a valid country code!\n"; + } + +=head1 DOMAIN NAMES + +Most top-level domain names are based on these codes, +but there are certain codes which aren't. +If you are using this module to identify country from hostname, +your best bet is to preprocess the country code. + +For example, B<edu>, B<com>, B<gov> and friends would map to B<us>; +B<uk> would map to B<gb>. Any others? + +=head1 KNOWN BUGS AND LIMITATIONS + +=over 4 + +=item * + +When using C<country2code()>, the country name must currently appear +exactly as it does in the source of the module. The module now supports +a small number of variants. + +Possible extensions to this are: an interface for getting at the +list of variant names, and regular expression matches. + +=item * + +In the current implementation, all data is read in when the +module is loaded, and then held in memory. +A lazy implementation would be more memory friendly. + +=item * + +Support for country names in different languages. + +=back + +=head1 SEE ALSO + +=over 4 + +=item Locale::Language + +ISO two letter codes for identification of language (ISO 639). + +=item Locale::Script + +ISO codes for identification of scripts (ISO 15924). + +=item Locale::Currency + +ISO three letter codes for identification of currencies +and funds (ISO 4217). + +=item Locale::SubCountry + +ISO codes for country sub-divisions (states, counties, provinces, etc), +as defined in ISO 3166-2. +This module is not part of the Locale-Codes distribution, +but is available from CPAN in CPAN/modules/by-module/Locale/ + +=item ISO 3166-1 + +The ISO standard which defines these codes. + +=item http://www.iso.org/iso/en/prods-services/iso3166ma/index.html + +Official home page for the ISO 3166 maintenance agency. + +=item http://www.egt.ie/standards/iso3166/iso3166-1-en.html + +Another useful, but not official, home page. + +=item http://www.cia.gov/cia/publications/factbook/docs/app-d-1.html + +An appendix in the CIA world fact book which lists country codes +as defined by ISO 3166, FIPS 10-4, and internet domain names. + +=back + + +=head1 AUTHOR + +Neil Bowers E<lt>neil@bowers.comE<gt> + +=head1 COPYRIGHT + +Copyright (C) 2002-2004, Neil Bowers. + +Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). + +This module is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. + +=cut + |