This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to Locale::Codes 2.02.
authorJarkko Hietaniemi <jhi@iki.fi>
Mon, 11 Mar 2002 03:36:51 +0000 (03:36 +0000)
committerJarkko Hietaniemi <jhi@iki.fi>
Mon, 11 Mar 2002 03:36:51 +0000 (03:36 +0000)
p4raw-id: //depot/perl@15161

MANIFEST
lib/Locale/Codes/ChangeLog
lib/Locale/Codes/README
lib/Locale/Codes/t/rename.t [new file with mode: 0644]
lib/Locale/Codes/t/uk.t
lib/Locale/Country.pm
lib/Locale/Country.pod

index de50f97..f18186f 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -1111,6 +1111,7 @@ lib/Locale/Codes/t/constants.t    See if Locale::Codes work
 lib/Locale/Codes/t/country.t   See if Locale::Codes work
 lib/Locale/Codes/t/currency.t  See if Locale::Codes work
 lib/Locale/Codes/t/languages.t See if Locale::Codes work
 lib/Locale/Codes/t/country.t   See if Locale::Codes work
 lib/Locale/Codes/t/currency.t  See if Locale::Codes work
 lib/Locale/Codes/t/languages.t See if Locale::Codes work
+lib/Locale/Codes/t/rename.t    See if Locale::Codes work
 lib/Locale/Codes/t/script.t    See if Locale::Codes work
 lib/Locale/Codes/t/uk.t                See if Locale::Codes work
 lib/Locale/Constants.pm                Locale::Codes
 lib/Locale/Codes/t/script.t    See if Locale::Codes work
 lib/Locale/Codes/t/uk.t                See if Locale::Codes work
 lib/Locale/Constants.pm                Locale::Codes
index 639e631..e77140b 100644 (file)
@@ -1,6 +1,15 @@
 
                ChangeLog for Locale-Codes Distribution
 
 
                ChangeLog for Locale-Codes Distribution
 
+2.02  2002-03-09 neilb
+
+       * added semi-private routine rename_country() to Locale::Country,
+         based on a patch from Iain Chalmers.
+       * added test rename.t for the above function.
+       * renamed _alias_code to be alias_code. Have retained the old
+         name for backwards compatibility. Will remove it when the
+         major version number next changes.
+
 2.01  2002-02-18 neilb
 
        * Split the documentation for all modules into separate pod files.
 2.01  2002-02-18 neilb
 
        * Split the documentation for all modules into separate pod files.
index 917b2c5..4bdd218 100644 (file)
@@ -1,6 +1,6 @@
 
                        Locale-Codes Distribution
 
                        Locale-Codes Distribution
-                               v2.01
+                               v2.02
 
 This distribution contains four Perl modules which can be used to process
 ISO codes for identifying languages, countries, scripts,
 
 This distribution contains four Perl modules which can be used to process
 ISO codes for identifying languages, countries, scripts,
diff --git a/lib/Locale/Codes/t/rename.t b/lib/Locale/Codes/t/rename.t
new file mode 100644 (file)
index 0000000..27f506c
--- /dev/null
@@ -0,0 +1,79 @@
+#!./perl
+#
+# rename.t - tests for Locale::Country with "uk" aliases to "gb"
+#
+
+use Locale::Country;
+
+local $SIG{__WARN__} = sub { };                # muffle warnings from carp
+
+Locale::Country::rename_country('gb' => 'Great Britain');
+
+#-----------------------------------------------------------------------
+# This is an array of tests. Each test is eval'd as an expression.
+# If it evaluates to FALSE, then "not ok N" is printed for the test,
+# otherwise "ok N".
+#-----------------------------------------------------------------------
+@TESTS =
+(
+       #================================================
+       # TESTS FOR code2country
+       #================================================
+
+ #---- selection of examples which should all result in undef -----------
+ '!defined code2country()',                  # no argument
+ '!defined code2country(undef)',             # undef argument
+ '!defined code2country("zz")',              # illegal code
+ '!defined code2country("ja")',              # should be jp for country
+ '!defined code2country("uk")',              # code for United Kingdom is 'gb'
+
+ #---- this call should return 0, since code doesn't exist --------------
+ '!Locale::Country::rename_country("ukz", "United Karz")',
+
+ #---- some successful examples -----------------------------------------
+ 'code2country("BO") eq "Bolivia"',
+ 'code2country("pk") eq "Pakistan"',
+ 'code2country("sn") eq "Senegal"',
+ 'code2country("us") eq "United States"',
+ 'code2country("ad") eq "Andorra"',          # first in DATA segment
+ 'code2country("zw") eq "Zimbabwe"',         # last in DATA segment
+ 'code2country("gb") eq "Great Britain"',    # normally "United Kingdom"
+
+       #================================================
+       # TESTS FOR country2code
+       #================================================
+
+ #---- selection of examples which should all result in undef -----------
+ '!defined country2code()',                  # no argument
+ '!defined country2code(undef)',             # undef argument
+ '!defined country2code("Banana")',          # illegal country name
+
+ #---- some successful examples -----------------------------------------
+ 'country2code("japan")          eq "jp"',
+ 'country2code("japan")          ne "ja"',
+ 'country2code("Japan")          eq "jp"',
+ 'country2code("United States")  eq "us"',
+
+ 'country2code("Great Britain") eq "gb"',
+ 'country2code("Great Britain", LOCALE_CODE_ALPHA_3) eq "gbr"',
+ 'country2code("Great Britain", LOCALE_CODE_NUMERIC) eq "826"',
+
+ 'country2code("United Kingdom") eq "gb"',
+ 'country2code("United Kingdom", LOCALE_CODE_ALPHA_3)  eq "gbr"',
+ 'country2code("United Kingdom", LOCALE_CODE_NUMERIC)  eq "826"',
+
+ 'country2code("Andorra")        eq "ad"',    # first in DATA segment
+ 'country2code("Zimbabwe")       eq "zw"',    # last in DATA segment
+);
+
+print "1..", int(@TESTS), "\n";
+
+$testid = 1;
+foreach $test (@TESTS)
+{
+    eval "print (($test) ? \"ok $testid\\n\" : \"not ok $testid\\n\" )";
+    print "not ok $testid\n" if $@;
+    ++$testid;
+}
+
+exit 0;
index 948e2d1..ceca372 100644 (file)
@@ -10,7 +10,7 @@ BEGIN {
 
 use Locale::Country;
 
 
 use Locale::Country;
 
-Locale::Country::_alias_code('uk' => 'gb');
+Locale::Country::alias_code('uk' => 'gb');
 
 #-----------------------------------------------------------------------
 # This is an array of tests. Each test is eval'd as an expression.
 
 #-----------------------------------------------------------------------
 # This is an array of tests. Each test is eval'd as an expression.
index 48cb477..9172721 100644 (file)
@@ -1,7 +1,7 @@
 #
 # Locale::Country - ISO codes for country identification (ISO 3166)
 #
 #
 # Locale::Country - ISO codes for country identification (ISO 3166)
 #
-# $Id: Country.pm,v 2.1 2002/02/06 04:07:09 neilb Exp $
+# $Id: Country.pm,v 2.2 2002/03/06 10:45:38 neilb Exp $
 #
 
 package Locale::Country;
 #
 
 package Locale::Country;
@@ -17,7 +17,7 @@ use Locale::Constants;
 #      Public Global Variables
 #-----------------------------------------------------------------------
 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
 #      Public Global Variables
 #-----------------------------------------------------------------------
 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
-$VERSION   = sprintf("%d.%02d", q$Revision: 2.1 $ =~ /(\d+)\.(\d+)/);
+$VERSION   = sprintf("%d.%02d", q$Revision: 2.2 $ =~ /(\d+)\.(\d+)/);
 @ISA       = qw(Exporter);
 @EXPORT    = qw(code2country country2code
                 all_country_codes all_country_names
 @ISA       = qw(Exporter);
 @EXPORT    = qw(code2country country2code
                 all_country_codes all_country_names
@@ -153,15 +153,15 @@ sub all_country_names
 
 #=======================================================================
 #
 
 #=======================================================================
 #
-# _alias_code ( ALIAS => CODE [ , CODESET ] )
+# alias_code ( ALIAS => CODE [ , CODESET ] )
 #
 # Add an alias for an existing code. If the CODESET isn't specified,
 # then we use the default (currently the alpha-2 codeset).
 #
 #
 # Add an alias for an existing code. If the CODESET isn't specified,
 # then we use the default (currently the alpha-2 codeset).
 #
-#   Locale::Country::_alias_code('uk' => 'gb');
+#   Locale::Country::alias_code('uk' => 'gb');
 #
 #=======================================================================
 #
 #=======================================================================
-sub _alias_code
+sub alias_code
 {
     my $alias = shift;
     my $real  = shift;
 {
     my $alias = shift;
     my $real  = shift;
@@ -182,6 +182,81 @@ sub _alias_code
     return $alias;
 }
 
     return $alias;
 }
 
+# old name of function for backwards compatibility
+*_alias_code = *alias_code;
+
+
+#=======================================================================
+#
+# rename_country
+#
+# change the official name for a country, eg:
+#      gb => 'Great Britain'
+# rather than the standard 'United Kingdom'. The original is retained
+# as an alias, but the new name will be returned if you lookup the
+# name from code.
+#
+#=======================================================================
+sub rename_country
+{
+    my $code     = shift;
+    my $new_name = shift;
+    my $codeset = @_ > 0 ? shift : _code2codeset($code);
+    my $country;
+    my $c;
+
+
+    if (not defined $codeset)
+    {
+        carp "rename_country(): unknown country code \"$code\"\n";
+        return 0;
+    }
+
+    $country = $CODES->[$codeset]->{$code};
+
+    foreach my $cset (LOCALE_CODE_ALPHA_2,
+                       LOCALE_CODE_ALPHA_3,
+                       LOCALE_CODE_NUMERIC)
+    {
+       if ($cset == $codeset)
+       {
+           $c = $code;
+       }
+       else
+       {
+           $c = country_code2code($code, $codeset, $cset);
+       }
+
+       $CODES->[$cset]->{$c} = $new_name;
+       $COUNTRIES->[$cset]->{"\L$new_name"} = $c;
+    }
+
+    return 1;
+}
+
+
+#=======================================================================
+#
+# _code2codeset
+#
+# given a country code in an unknown codeset, return the codeset
+# it is from, or undef.
+#
+#=======================================================================
+sub _code2codeset
+{
+    my $code = shift;
+
+
+    foreach my $codeset (LOCALE_CODE_ALPHA_2, LOCALE_CODE_ALPHA_3,
+                       LOCALE_CODE_NUMERIC)
+    {
+       return $codeset if (exists $CODES->[$codeset]->{$code})
+    }
+
+    return undef;
+}
+
 
 #=======================================================================
 #
 
 #=======================================================================
 #
index bfa5bd5..ff130aa 100644 (file)
@@ -13,14 +13,15 @@ Locale::Country - ISO codes for country identification (ISO 3166)
     @codes   = all_country_codes();
     @names   = all_country_names();
     
     @codes   = all_country_codes();
     @names   = all_country_names();
     
-    # add "uk" as a pseudo country code for United Kingdom
-    Locale::Country::_alias_code('uk' => 'gb');
+    # 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
 
 
 =head1 DESCRIPTION
 
 The C<Locale::Country> module provides access to the ISO
-codes for identifying countries, as defined in ISO 3166.
+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.
 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.
@@ -141,12 +142,19 @@ depending on which code set you specify.
 =back
 
 
 =back
 
 
-=head1 CODE ALIASING
+=head1 SEMI-PRIVATE ROUTINES
 
 
-This module supports a semi-private routine for specifying two letter
-code aliases.
+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.
 
 
-    Locale::Country::_alias_code( ALIAS => CODE [, CODESET ] )
+=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
 
 This feature was added as a mechanism for handling
 a "uk" code. The ISO standard says that the two-letter code for
@@ -156,13 +164,31 @@ 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:
 
 an ISO standard. If you would like 'uk' to work as the two-letter
 code for United Kingdom, use the following:
 
-    use Locale::Country;
-    
-    Locale::Country::_alias_code('uk' => 'gb');
+    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".
 
 
 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
 
 
 =head1 EXAMPLES
 
@@ -236,13 +262,20 @@ ISO codes for identification of scripts (ISO 15924).
 ISO three letter codes for identification of currencies
 and funds (ISO 4217).
 
 ISO three letter codes for identification of currencies
 and funds (ISO 4217).
 
-=item ISO 3166
+=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.
 
 
 The ISO standard which defines these codes.
 
-=item http://www.din.de/gremien/nas/nabd/iso3166ma/
+=item http://www.iso.org/iso/en/prods-services/iso3166ma/index.html
 
 
-Official home page for ISO 3166
+Official home page for the ISO 3166 maintenance agency.
 
 =item http://www.egt.ie/standards/iso3166/iso3166-1-en.html
 
 
 =item http://www.egt.ie/standards/iso3166/iso3166-1-en.html