Upgrade to Locale::Codes 2.02.

p4raw-id: //depot/perl@15161

7 files changed, 217 insertions, 20 deletions

diff --git a/MANIFEST b/MANIFEST
index de50f973bf..f18186fb17 100644
--- 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/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
diff --git a/lib/Locale/Codes/ChangeLog b/lib/Locale/Codes/ChangeLog
index 639e6319b3..e77140b4df 100644
--- a/lib/Locale/Codes/ChangeLog
+++ b/lib/Locale/Codes/ChangeLog
@@ -1,6 +1,15 @@
 
 		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.
diff --git a/lib/Locale/Codes/README b/lib/Locale/Codes/README
index 917b2c5b02..4bdd2183dd 100644
--- a/lib/Locale/Codes/README
+++ b/lib/Locale/Codes/README
@@ -1,6 +1,6 @@
 
 			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,
diff --git a/lib/Locale/Codes/t/rename.t b/lib/Locale/Codes/t/rename.t
new file mode 100644
index 0000000000..27f506c84b
--- /dev/null
+++ b/lib/Locale/Codes/t/rename.t
@@ -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;
diff --git a/lib/Locale/Codes/t/uk.t b/lib/Locale/Codes/t/uk.t
index 948e2d1af2..ceca3721b5 100644
--- a/lib/Locale/Codes/t/uk.t
+++ b/lib/Locale/Codes/t/uk.t
@@ -10,7 +10,7 @@ BEGIN {
 
 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.
diff --git a/lib/Locale/Country.pm b/lib/Locale/Country.pm
index 48cb47795b..9172721aa8 100644
--- a/lib/Locale/Country.pm
+++ b/lib/Locale/Country.pm
@@ -1,7 +1,7 @@
 #
 # 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;
@@ -17,7 +17,7 @@ use Locale::Constants;
 #	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
@@ -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).
 #
-#   Locale::Country::_alias_code('uk' => 'gb');
+#   Locale::Country::alias_code('uk' => 'gb');
 #
 #=======================================================================
-sub _alias_code
+sub alias_code
 {
     my $alias = shift;
     my $real  = shift;
@@ -182,6 +182,81 @@ sub _alias_code
     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;
+}
+
 
 #=======================================================================
 #
diff --git a/lib/Locale/Country.pod b/lib/Locale/Country.pod
index bfa5bd5807..ff130aadc0 100644
--- a/lib/Locale/Country.pod
+++ b/lib/Locale/Country.pod
@@ -13,14 +13,15 @@ Locale::Country - ISO codes for country identification (ISO 3166)
     @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
-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.
@@ -141,12 +142,19 @@ depending on which code set you specify.
 =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
@@ -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:
 
-    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".
 
+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
 
@@ -236,13 +262,20 @@ ISO codes for identification of scripts (ISO 15924).
 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.
 
-=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