This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to Locale::Codes 2.01.
authorJarkko Hietaniemi <jhi@iki.fi>
Tue, 19 Feb 2002 13:49:52 +0000 (13:49 +0000)
committerJarkko Hietaniemi <jhi@iki.fi>
Tue, 19 Feb 2002 13:49:52 +0000 (13:49 +0000)
p4raw-id: //depot/perl@14770

13 files changed:
MANIFEST
lib/Locale/Codes/ChangeLog
lib/Locale/Codes/README
lib/Locale/Constants.pm
lib/Locale/Constants.pod [new file with mode: 0644]
lib/Locale/Country.pm
lib/Locale/Country.pod [new file with mode: 0644]
lib/Locale/Currency.pm
lib/Locale/Currency.pod [new file with mode: 0644]
lib/Locale/Language.pm
lib/Locale/Language.pod [new file with mode: 0644]
lib/Locale/Script.pm
lib/Locale/Script.pod [new file with mode: 0644]

index 36326fd..b922e72 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -1106,7 +1106,7 @@ lib/lib_pm.PL                     For "use lib", produces lib/lib.pm
 lib/locale.pm                  For "use locale"
 lib/locale.t                   See if locale support works
 lib/Locale/Codes/ChangeLog     Locale::Codes
-lib/Locale/Codes/README        Locale::Codes
+lib/Locale/Codes/README                Locale::Codes
 lib/Locale/Codes/t/all.t       See if Locale::Codes work
 lib/Locale/Codes/t/constants.t See if Locale::Codes work
 lib/Locale/Codes/t/country.t   See if Locale::Codes work
@@ -1115,9 +1115,13 @@ lib/Locale/Codes/t/languages.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/Constants.pod       Locale::Codes documentation
 lib/Locale/Country.pm          Locale::Codes
+lib/Locale/Country.pod         Locale::Codes documentation
 lib/Locale/Currency.pm         Locale::Codes
+lib/Locale/Currency.pod                Locale::Codes documentation
 lib/Locale/Language.pm         Locale::Codes
+lib/Locale/Language.pod                Locale::Codes documentation
 lib/Locale/Maketext.pm         Locale::Maketext
 lib/Locale/Maketext.pod                Locale::Maketext documentation
 lib/Locale/Maketext/ChangeLog  Locale::Maketext
@@ -1125,6 +1129,7 @@ lib/Locale/Maketext/README        Locale::Maketext
 lib/Locale/Maketext/test.pl    See if Locale::Maketext works
 lib/Locale/Maketext/TPJ13.pod  Locale::Maketext documentation article
 lib/Locale/Script.pm           Locale::Codes
+lib/Locale/Script.pod          Locale::Codes documentation
 lib/look.pl                    A "look" equivalent
 lib/Math/BigFloat.pm           An arbitrary precision floating-point arithmetic package
 lib/Math/BigInt.pm             An arbitrary precision integer arithmetic package
index d8a1837..639e631 100644 (file)
@@ -1,6 +1,12 @@
 
                ChangeLog for Locale-Codes Distribution
 
+2.01  2002-02-18 neilb
+
+       * Split the documentation for all modules into separate pod files.
+       * Made sure all =over were =over 4; some were other values.
+       * The code2code() methods had one more shift than was needed.
+
 2.00  2002-02-17 neilb
 
        * Created Locale::Script which provides an interface to the
index 20d174f..917b2c5 100644 (file)
@@ -1,6 +1,6 @@
 
                        Locale-Codes Distribution
-                               v2.00
+                               v2.01
 
 This distribution contains four Perl modules which can be used to process
 ISO codes for identifying languages, countries, scripts,
@@ -33,7 +33,7 @@ To install these modules, you should just have to run the following:
        % make install
 
 The modules are documented using pod. When you "make install", you
-will get three man-pages: Locale::Language, Locale::Country,
+will get four man-pages: Locale::Language, Locale::Country,
 Locale::Currency, Locale::Script.
 
 The first version of Locale::Currency was written by Michael Hennecke,
index 88651fd..c16d45e 100644 (file)
@@ -1,20 +1,26 @@
-package Locale::Constants;
 #
 # Locale::Constants - defined constants for identifying codesets
 #
-# $Id: Constants.pm,v 2.0 2002/02/05 22:37:58 neilb Exp $
+# $Id: Constants.pm,v 2.1 2002/02/06 04:07:09 neilb Exp $
 #
 
+package Locale::Constants;
 use strict;
 
 require Exporter;
 
+#-----------------------------------------------------------------------
+#      Public Global Variables
+#-----------------------------------------------------------------------
 use vars qw($VERSION @ISA @EXPORT);
-$VERSION   = sprintf("%d.%02d", q$Revision: 2.0 $ =~ /(\d+)\.(\d+)/);
+$VERSION   = sprintf("%d.%02d", q$Revision: 2.1 $ =~ /(\d+)\.(\d+)/);
 @ISA   = qw(Exporter);
 @EXPORT = qw(LOCALE_CODE_ALPHA_2 LOCALE_CODE_ALPHA_3 LOCALE_CODE_NUMERIC
                LOCALE_CODE_DEFAULT);
 
+#-----------------------------------------------------------------------
+#      Constants
+#-----------------------------------------------------------------------
 use constant LOCALE_CODE_ALPHA_2 => 1;
 use constant LOCALE_CODE_ALPHA_3 => 2;
 use constant LOCALE_CODE_NUMERIC => 3;
@@ -23,80 +29,3 @@ use constant LOCALE_CODE_DEFAULT => LOCALE_CODE_ALPHA_2;
 
 1;
 
-__END__
-
-=head1 NAME
-
-Locale::Constants - constants for Locale codes
-
-=head1 SYNOPSIS
-
-    use Locale::Constants;
-    
-    $codeset = LOCALE_CODE_ALPHA_2;
-
-=head1 DESCRIPTION
-
-B<Locale::Constants> defines symbols which are used in
-the four modules from the Locale-Codes distribution:
-
-       Locale::Language
-       Locale::Country
-       Locale::Currency
-       Locale::Script
-
-B<Note:> at the moment only Locale::Country and Locale::Script
-support more than one code set.
-
-The symbols defined are used to specify which codes you
-want to be used:
-
-       LOCALE_CODE_ALPHA_2
-       LOCALE_CODE_ALPHA_3
-       LOCALE_CODE_NUMERIC
-
-You shouldn't have to C<use> this module directly yourself -
-it is used by the three Locale modules, which in turn export
-the symbols.
-
-=head1 KNOWN BUGS AND LIMITATIONS
-
-None at the moment.
-
-=head1 SEE ALSO
-
-=over 4
-
-=item Locale::Language
-
-Codes for identification of languages.
-
-=item Locale::Country
-
-Codes for identification of countries.
-
-=item Locale::Script
-
-Codes for identification of scripts.
-
-=item Locale::Currency
-
-Codes for identification of currencies and funds.
-
-=back
-
-=head1 AUTHOR
-
-Neil Bowers E<lt>neil@bowers.comE<gt>
-
-=head1 COPYRIGHT
-
-Copyright (C) 2002, Neil Bowers.
-
-Copyright (C) 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
-
diff --git a/lib/Locale/Constants.pod b/lib/Locale/Constants.pod
new file mode 100644 (file)
index 0000000..68d3358
--- /dev/null
@@ -0,0 +1,76 @@
+
+=head1 NAME
+
+Locale::Constants - constants for Locale codes
+
+=head1 SYNOPSIS
+
+    use Locale::Constants;
+    
+    $codeset = LOCALE_CODE_ALPHA_2;
+
+=head1 DESCRIPTION
+
+B<Locale::Constants> defines symbols which are used in
+the four modules from the Locale-Codes distribution:
+
+       Locale::Language
+       Locale::Country
+       Locale::Currency
+       Locale::Script
+
+B<Note:> at the moment only Locale::Country and Locale::Script
+support more than one code set.
+
+The symbols defined are used to specify which codes you
+want to be used:
+
+       LOCALE_CODE_ALPHA_2
+       LOCALE_CODE_ALPHA_3
+       LOCALE_CODE_NUMERIC
+
+You shouldn't have to C<use> this module directly yourself -
+it is used by the three Locale modules, which in turn export
+the symbols.
+
+=head1 KNOWN BUGS AND LIMITATIONS
+
+None at the moment.
+
+=head1 SEE ALSO
+
+=over 4
+
+=item Locale::Language
+
+Codes for identification of languages.
+
+=item Locale::Country
+
+Codes for identification of countries.
+
+=item Locale::Script
+
+Codes for identification of scripts.
+
+=item Locale::Currency
+
+Codes for identification of currencies and funds.
+
+=back
+
+=head1 AUTHOR
+
+Neil Bowers E<lt>neil@bowers.comE<gt>
+
+=head1 COPYRIGHT
+
+Copyright (C) 2002, Neil Bowers.
+
+Copyright (C) 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
+
index 2f43ae7..48cb477 100644 (file)
@@ -1,86 +1,13 @@
-#-----------------------------------------------------------------------
-
-=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();
-    
-    # add "uk" as a pseudo country code for United Kingdom
-    Locale::Country::_alias_code('uk' => 'gb');
-
-=cut
-
-#-----------------------------------------------------------------------
+#
+# Locale::Country - ISO codes for country identification (ISO 3166)
+#
+# $Id: Country.pm,v 2.1 2002/02/06 04:07:09 neilb Exp $
+#
 
 package Locale::Country;
 use strict;
 require 5.002;
 
-#-----------------------------------------------------------------------
-
-=head1 DESCRIPTION
-
-The C<Locale::Country> module provides access to the ISO
-codes for identifying countries, as defined in ISO 3166.
-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') 
-
-=cut
-
-#-----------------------------------------------------------------------
-
 require Exporter;
 use Carp;
 use Locale::Constants;
@@ -90,7 +17,7 @@ use Locale::Constants;
 #      Public Global Variables
 #-----------------------------------------------------------------------
 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
-$VERSION   = sprintf("%d.%02d", q$Revision: 2.0 $ =~ /(\d+)\.(\d+)/);
+$VERSION   = sprintf("%d.%02d", q$Revision: 2.1 $ =~ /(\d+)\.(\d+)/);
 @ISA       = qw(Exporter);
 @EXPORT    = qw(code2country country2code
                 all_country_codes all_country_names
@@ -105,54 +32,9 @@ my $COUNTRIES = [];
 
 
 #=======================================================================
-
-=head1 CONVERSION ROUTINES
-
-There are three conversion routines: C<code2country()>, C<country2code()>,
-and C<country_code2code()>.
-
-=over 8
-
-=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
-
-=cut
-
+#
+# code2country ( CODE [, CODESET ] )
+#
 #=======================================================================
 sub code2country
 {
@@ -191,6 +73,12 @@ sub code2country
     }
 }
 
+
+#=======================================================================
+#
+# country2code ( NAME [, CODESET ] )
+#
+#=======================================================================
 sub country2code
 {
     my $country = shift;
@@ -212,6 +100,12 @@ sub country2code
     }
 }
 
+
+#=======================================================================
+#
+# country_code2code ( NAME [, CODESET ] )
+#
+#=======================================================================
 sub country_code2code
 {
     (@_ == 3) or croak "country_code2code() takes 3 arguments!";
@@ -219,7 +113,7 @@ sub country_code2code
     my $code = shift;
     my $inset = shift;
     my $outset = shift;
-    my $outcode = shift;
+    my $outcode;
     my $country;
 
 
@@ -230,37 +124,12 @@ sub country_code2code
     return $outcode;
 }
 
-#=======================================================================
-
-=head1 QUERY ROUTINES
-
-There are two function which can be used to obtain a list of all codes,
-or all country names:
-
-=over 8
-
-=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
-
-=cut
 
 #=======================================================================
+#
+# all_country_codes ( [ CODESET ] )
+#
+#=======================================================================
 sub all_country_codes
 {
     my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
@@ -268,6 +137,12 @@ sub all_country_codes
     return keys %{ $CODES->[$codeset] };
 }
 
+
+#=======================================================================
+#
+# all_country_names ( [ CODESET ] )
+#
+#=======================================================================
 sub all_country_names
 {
     my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
@@ -275,34 +150,17 @@ sub all_country_names
     return values %{ $CODES->[$codeset] };
 }
 
-#-----------------------------------------------------------------------
-
-=head1 CODE ALIASING
-
-This module supports a semi-private routine for specifying two letter
-code aliases.
-
-    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:
-
-    use Locale::Country;
-    
-    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".
-
-=cut
-
-#-----------------------------------------------------------------------
 
+#=======================================================================
+#
+# _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');
+#
+#=======================================================================
 sub _alias_code
 {
     my $alias = shift;
@@ -324,119 +182,11 @@ sub _alias_code
     return $alias;
 }
 
-#-----------------------------------------------------------------------
-
-=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 ISO 3166
-
-The ISO standard which defines these codes.
-
-=item http://www.din.de/gremien/nas/nabd/iso3166ma/
-
-Official home page for ISO 3166
-
-=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-f.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, 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
-
-#-----------------------------------------------------------------------
 
 #=======================================================================
+#
 # initialisation code - stuff the DATA into the ALPHA2 hash
+#
 #=======================================================================
 {
     my ($alpha2, $alpha3, $numeric);
diff --git a/lib/Locale/Country.pod b/lib/Locale/Country.pod
new file mode 100644 (file)
index 0000000..bfa5bd5
--- /dev/null
@@ -0,0 +1,273 @@
+
+=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();
+    
+    # add "uk" as a pseudo country code for United Kingdom
+    Locale::Country::_alias_code('uk' => 'gb');
+
+
+=head1 DESCRIPTION
+
+The C<Locale::Country> module provides access to the ISO
+codes for identifying countries, as defined in ISO 3166.
+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 CODE ALIASING
+
+This module supports a semi-private routine for specifying two letter
+code aliases.
+
+    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:
+
+    use Locale::Country;
+    
+    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".
+
+
+=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 ISO 3166
+
+The ISO standard which defines these codes.
+
+=item http://www.din.de/gremien/nas/nabd/iso3166ma/
+
+Official home page for ISO 3166
+
+=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-f.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, 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
+
index d8732e7..f8efffb 100644 (file)
@@ -1,64 +1,21 @@
-#-----------------------------------------------------------------------
-
-=head1 NAME
-
-Locale::Currency - ISO three letter codes for currency identification (ISO 4217)
-
-=head1 SYNOPSIS
-
-    use Locale::Currency;
-
-    $curr = code2currency('usd');     # $curr gets 'US Dollar'
-    $code = currency2code('Euro');    # $code gets 'eur'
-
-    @codes   = all_currency_codes();
-    @names   = all_currency_names();
-
-=cut
-
-#-----------------------------------------------------------------------
+#
+# Locale::Currency - ISO three letter codes for currency identification
+#                    (ISO 4217)
+#
+# $Id: Currency.pm,v 2.1 2002/02/06 04:07:10 neilb Exp $
+#
 
 package Locale::Currency;
 use strict;
 require 5.002;
 
-#-----------------------------------------------------------------------
-
-=head1 DESCRIPTION
-
-The C<Locale::Currency> module provides access to the ISO three-letter
-codes for identifying currencies and funds, as defined in ISO 4217.
-You can either access the codes via the L<conversion routines>
-(described below),
-or with the two functions which return lists of all currency codes or
-all currency names.
-
-There are two special codes defined by the standard which aren't
-understood by this module:
-
-=over 4
-
-=item XTS
-
-Specifically reserved for testing purposes.
-
-=item XXX
-
-For transactions where no currency is involved.
-
-=back
-
-=cut
-
-#-----------------------------------------------------------------------
-
 require Exporter;
 
 #-----------------------------------------------------------------------
 #      Public Global Variables
 #-----------------------------------------------------------------------
 use vars qw($VERSION @ISA @EXPORT);
-$VERSION      = sprintf("%d.%02d", q$Revision: 2.0 $ =~ /(\d+)\.(\d+)/);
+$VERSION      = sprintf("%d.%02d", q$Revision: 2.1 $ =~ /(\d+)\.(\d+)/);
 @ISA          = qw(Exporter);
 @EXPORT       = qw(&code2currency &currency2code
                    &all_currency_codes &all_currency_names );
@@ -71,38 +28,9 @@ my %CURRENCIES = ();
 
 
 #=======================================================================
-
-=head1 CONVERSION ROUTINES
-
-There are two conversion routines: C<code2currency()> and C<currency2code()>.
-
-=over 8
-
-=item code2currency()
-
-This function takes a three letter currency code and returns a string
-which contains the name of the currency identified. If the code is
-not a valid currency code, as defined by ISO 4217, then C<undef>
-will be returned.
-
-    $curr = code2currency($code);
-
-=item currency2code()
-
-This function takes a currency name and returns the corresponding
-three letter currency code, if such exists.
-If the argument could not be identified as a currency name,
-then C<undef> will be returned.
-
-    $code = currency2code('French Franc');
-
-The case of the currency name is not important.
-See the section L<KNOWN BUGS AND LIMITATIONS> below.
-
-=back
-
-=cut
-
+#
+# code2currency( CODE )
+#
 #=======================================================================
 sub code2currency
 {
@@ -124,6 +52,12 @@ sub code2currency
     }
 }
 
+
+#=======================================================================
+#
+# currency2code ( CURRENCY )
+#
+#=======================================================================
 sub currency2code
 {
     my $curr = shift;
@@ -144,141 +78,28 @@ sub currency2code
     }
 }
 
-#=======================================================================
-
-=head1 QUERY ROUTINES
-
-There are two function which can be used to obtain a list of all
-currency codes, or all currency names:
-
-=over 8
-
-=item C<all_currency_codes()>
-
-Returns a list of all three-letter currency codes.
-The codes are guaranteed to be all lower-case,
-and not in any particular order.
-
-=item C<all_currency_names()>
-
-Returns a list of all currency names for which there is a corresponding
-three-letter currency code. The names are capitalised, and not returned
-in any particular order.
-
-=back
-
-=cut
 
 #=======================================================================
+#
+# all_currency_codes()
+#
+#=======================================================================
 sub all_currency_codes
 {
     return keys %CODES;
 }
 
+
+#=======================================================================
+#
+# all_currency_names()
+#
+#=======================================================================
 sub all_currency_names
 {
     return values %CODES;
 }
 
-#-----------------------------------------------------------------------
-
-=head1 EXAMPLES
-
-The following example illustrates use of the C<code2currency()> function.
-The user is prompted for a currency code, and then told the corresponding
-currency name:
-
-    $| = 1;    # turn off buffering
-
-    print "Enter currency code: ";
-    chop($code = <STDIN>);
-    $curr = code2currency($code);
-    if (defined $curr)
-    {
-        print "$code = $curr\n";
-    }
-    else
-    {
-        print "'$code' is not a valid currency code!\n";
-    }
-
-=head1 KNOWN BUGS AND LIMITATIONS
-
-=over 4
-
-=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 *
-
-This module also includes the special codes which are
-not for a currency, such as Gold, Platinum, etc.
-This might cause a problem if you're using this module
-to display a list of currencies.
-Let Neil know if this does cause a problem, and we can
-do something about it.
-
-=item *
-
-ISO 4217 also defines a numeric code for each currency.
-Currency codes are not currently supported by this module,
-in the same way Locale::Country supports multiple codesets.
-
-=item *
-
-There are three cases where there is more than one
-code for the same currency name.
-Kwacha has two codes: mwk for Malawi, and zmk for Zambia.
-The Russian Ruble has two codes: rub and rur.
-The Belarussian Ruble has two codes: byr and byb.
-The currency2code() function only returns one code, so
-you might not get back the code you expected.
-
-=back
-
-=head1 SEE ALSO
-
-=over 4
-
-=item Locale::Country
-
-ISO codes for identification of country (ISO 3166).
-
-=item Locale::Script
-
-ISO codes for identification of written scripts (ISO 15924).
-
-=item ISO 4217:1995
-
-Code for the representation of currencies and funds.
-
-=item http://www.bsi-global.com/iso4217currency
-
-Official web page for the ISO 4217 maintenance agency.
-This has the latest list of codes, in MS Word format. Boo.
-
-=back
-
-=head1 AUTHOR
-
-Michael Hennecke E<lt>hennecke@rz.uni-karlsruhe.deE<gt>
-and
-Neil Bowers E<lt>neil@bowers.comE<gt>
-
-=head1 COPYRIGHT
-
-Copyright (c) 2001 Michael Hennecke and
-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
-
-#-----------------------------------------------------------------------
 
 #=======================================================================
 # initialisation code - stuff the DATA into the CODES hash
diff --git a/lib/Locale/Currency.pod b/lib/Locale/Currency.pod
new file mode 100644 (file)
index 0000000..4678d3e
--- /dev/null
@@ -0,0 +1,191 @@
+
+=head1 NAME
+
+Locale::Currency - ISO three letter codes for currency identification (ISO 4217)
+
+=head1 SYNOPSIS
+
+    use Locale::Currency;
+
+    $curr = code2currency('usd');     # $curr gets 'US Dollar'
+    $code = currency2code('Euro');    # $code gets 'eur'
+
+    @codes   = all_currency_codes();
+    @names   = all_currency_names();
+
+
+=head1 DESCRIPTION
+
+The C<Locale::Currency> module provides access to the ISO three-letter
+codes for identifying currencies and funds, as defined in ISO 4217.
+You can either access the codes via the L<conversion routines>
+(described below),
+or with the two functions which return lists of all currency codes or
+all currency names.
+
+There are two special codes defined by the standard which aren't
+understood by this module:
+
+=over 4
+
+=item XTS
+
+Specifically reserved for testing purposes.
+
+=item XXX
+
+For transactions where no currency is involved.
+
+=back
+
+
+=head1 CONVERSION ROUTINES
+
+There are two conversion routines: C<code2currency()> and C<currency2code()>.
+
+=over 4
+
+=item code2currency()
+
+This function takes a three letter currency code and returns a string
+which contains the name of the currency identified. If the code is
+not a valid currency code, as defined by ISO 4217, then C<undef>
+will be returned.
+
+    $curr = code2currency($code);
+
+=item currency2code()
+
+This function takes a currency name and returns the corresponding
+three letter currency code, if such exists.
+If the argument could not be identified as a currency name,
+then C<undef> will be returned.
+
+    $code = currency2code('French Franc');
+
+The case of the currency name is not important.
+See the section L<KNOWN BUGS AND LIMITATIONS> below.
+
+=back
+
+
+=head1 QUERY ROUTINES
+
+There are two function which can be used to obtain a list of all
+currency codes, or all currency names:
+
+=over 4
+
+=item C<all_currency_codes()>
+
+Returns a list of all three-letter currency codes.
+The codes are guaranteed to be all lower-case,
+and not in any particular order.
+
+=item C<all_currency_names()>
+
+Returns a list of all currency names for which there is a corresponding
+three-letter currency code. The names are capitalised, and not returned
+in any particular order.
+
+=back
+
+
+=head1 EXAMPLES
+
+The following example illustrates use of the C<code2currency()> function.
+The user is prompted for a currency code, and then told the corresponding
+currency name:
+
+    $| = 1;    # turn off buffering
+
+    print "Enter currency code: ";
+    chop($code = <STDIN>);
+    $curr = code2currency($code);
+    if (defined $curr)
+    {
+        print "$code = $curr\n";
+    }
+    else
+    {
+        print "'$code' is not a valid currency code!\n";
+    }
+
+=head1 KNOWN BUGS AND LIMITATIONS
+
+=over 4
+
+=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 *
+
+This module also includes the special codes which are
+not for a currency, such as Gold, Platinum, etc.
+This might cause a problem if you're using this module
+to display a list of currencies.
+Let Neil know if this does cause a problem, and we can
+do something about it.
+
+=item *
+
+ISO 4217 also defines a numeric code for each currency.
+Currency codes are not currently supported by this module,
+in the same way Locale::Country supports multiple codesets.
+
+=item *
+
+There are three cases where there is more than one
+code for the same currency name.
+Kwacha has two codes: mwk for Malawi, and zmk for Zambia.
+The Russian Ruble has two codes: rub and rur.
+The Belarussian Ruble has two codes: byr and byb.
+The currency2code() function only returns one code, so
+you might not get back the code you expected.
+
+=back
+
+=head1 SEE ALSO
+
+=over 4
+
+=item Locale::Country
+
+ISO codes for identification of country (ISO 3166).
+
+=item Locale::Script
+
+ISO codes for identification of written scripts (ISO 15924).
+
+=item ISO 4217:1995
+
+Code for the representation of currencies and funds.
+
+=item http://www.bsi-global.com/iso4217currency
+
+Official web page for the ISO 4217 maintenance agency.
+This has the latest list of codes, in MS Word format. Boo.
+
+=back
+
+=head1 AUTHOR
+
+Michael Hennecke E<lt>hennecke@rz.uni-karlsruhe.deE<gt>
+and
+Neil Bowers E<lt>neil@bowers.comE<gt>
+
+=head1 COPYRIGHT
+
+Copyright (C) 2002, Neil Bowers.
+
+Copyright (c) 2001 Michael Hennecke and
+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
+
index 6479c28..70f118a 100644 (file)
@@ -1,48 +1,20 @@
-#-----------------------------------------------------------------------
-
-=head1 NAME
-
-Locale::Language - ISO two letter codes for language identification (ISO 639)
-
-=head1 SYNOPSIS
-
-    use Locale::Language;
-    
-    $lang = code2language('en');        # $lang gets 'English'
-    $code = language2code('French');    # $code gets 'fr'
-    
-    @codes   = all_language_codes();
-    @names   = all_language_names();
-
-=cut
-
-#-----------------------------------------------------------------------
+#
+# Locale::Language - ISO two letter codes for language identification (ISO 639)
+#
+# $Id: Language.pm,v 2.1 2002/02/06 04:07:10 neilb Exp $
+#
 
 package Locale::Language;
 use strict;
 require 5.002;
 
-#-----------------------------------------------------------------------
-
-=head1 DESCRIPTION
-
-The C<Locale::Language> module provides access to the ISO two-letter
-codes for identifying languages, as defined in ISO 639. You can either
-access the codes via the L<conversion routines> (described below),
-or via the two functions which return lists of all language codes or
-all language names.
-
-=cut
-
-#-----------------------------------------------------------------------
-
 require Exporter;
 
 #-----------------------------------------------------------------------
 #      Public Global Variables
 #-----------------------------------------------------------------------
 use vars qw($VERSION @ISA @EXPORT);
-$VERSION      = sprintf("%d.%02d", q$Revision: 2.0 $ =~ /(\d+)\.(\d+)/);
+$VERSION      = sprintf("%d.%02d", q$Revision: 2.1 $ =~ /(\d+)\.(\d+)/);
 @ISA          = qw(Exporter);
 @EXPORT       = qw(&code2language &language2code
                    &all_language_codes &all_language_names );
@@ -55,38 +27,9 @@ my %LANGUAGES = ();
 
 
 #=======================================================================
-
-=head1 CONVERSION ROUTINES
-
-There are two conversion routines: C<code2language()> and C<language2code()>.
-
-=over 8
-
-=item code2language()
-
-This function takes a two letter language code and returns a string
-which contains the name of the language identified. If the code is
-not a valid language code, as defined by ISO 639, then C<undef>
-will be returned.
-
-    $lang = code2language($code);
-
-=item language2code()
-
-This function takes a language name and returns the corresponding
-two letter language code, if such exists.
-If the argument could not be identified as a language name,
-then C<undef> will be returned.
-
-    $code = language2code('French');
-
-The case of the language name is not important.
-See the section L<KNOWN BUGS AND LIMITATIONS> below.
-
-=back
-
-=cut
-
+#
+# code2language ( CODE )
+#
 #=======================================================================
 sub code2language
 {
@@ -108,6 +51,12 @@ sub code2language
     }
 }
 
+
+#=======================================================================
+#
+# language2code ( LANGUAGE )
+#
+#=======================================================================
 sub language2code
 {
     my $lang = shift;
@@ -128,126 +77,28 @@ sub language2code
     }
 }
 
-#=======================================================================
-
-=head1 QUERY ROUTINES
-
-There are two function which can be used to obtain a list of all
-language codes, or all language names:
-
-=over 8
-
-=item C<all_language_codes()>
-
-Returns a list of all two-letter language codes.
-The codes are guaranteed to be all lower-case,
-and not in any particular order.
-
-=item C<all_language_names()>
-
-Returns a list of all language names for which there is a corresponding
-two-letter language code. The names are capitalised, and not returned
-in any particular order.
-
-=back
-
-=cut
 
 #=======================================================================
+#
+# all_language_codes()
+#
+#=======================================================================
 sub all_language_codes
 {
     return keys %CODES;
 }
 
+
+#=======================================================================
+#
+# all_language_names()
+#
+#=======================================================================
 sub all_language_names
 {
     return values %CODES;
 }
 
-#-----------------------------------------------------------------------
-
-=head1 EXAMPLES
-
-The following example illustrates use of the C<code2language()> function.
-The user is prompted for a language code, and then told the corresponding
-language name:
-
-    $| = 1;    # turn off buffering
-    
-    print "Enter language code: ";
-    chop($code = <STDIN>);
-    $lang = code2language($code);
-    if (defined $lang)
-    {
-        print "$code = $lang\n";
-    }
-    else
-    {
-        print "'$code' is not a valid language code!\n";
-    }
-
-=head1 KNOWN BUGS AND LIMITATIONS
-
-=over 4
-
-=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 *
-
-Currently just supports the two letter language codes -
-there are also three-letter codes, and numbers.
-Would these be of any use to anyone?
-
-=back
-
-=head1 SEE ALSO
-
-=over 4
-
-=item Locale::Country
-
-ISO codes for identification of country (ISO 3166).
-Supports 2-letter, 3-letter, and numeric country codes.
-
-=item Locale::Script
-
-ISO codes for identification of written scripts (ISO 15924).
-
-=item Locale::Currency
-
-ISO three letter codes for identification of currencies and funds (ISO 4217).
-
-=item ISO 639:1988 (E/F)
-
-Code for the representation of names of languages.
-
-=item http://lcweb.loc.gov/standards/iso639-2/langhome.html
-
-Home page for ISO 639-2.
-
-=back
-
-
-=head1 AUTHOR
-
-Neil Bowers E<lt>neil@bowers.comE<gt>
-
-=head1 COPYRIGHT
-
-Copyright (C) 2002, 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
-
-#-----------------------------------------------------------------------
 
 #=======================================================================
 # initialisation code - stuff the DATA into the CODES hash
diff --git a/lib/Locale/Language.pod b/lib/Locale/Language.pod
new file mode 100644 (file)
index 0000000..07ce4ba
--- /dev/null
@@ -0,0 +1,158 @@
+
+=head1 NAME
+
+Locale::Language - ISO two letter codes for language identification (ISO 639)
+
+=head1 SYNOPSIS
+
+    use Locale::Language;
+    
+    $lang = code2language('en');        # $lang gets 'English'
+    $code = language2code('French');    # $code gets 'fr'
+    
+    @codes   = all_language_codes();
+    @names   = all_language_names();
+
+
+=head1 DESCRIPTION
+
+The C<Locale::Language> module provides access to the ISO two-letter
+codes for identifying languages, as defined in ISO 639. You can either
+access the codes via the L<conversion routines> (described below),
+or via the two functions which return lists of all language codes or
+all language names.
+
+
+=head1 CONVERSION ROUTINES
+
+There are two conversion routines: C<code2language()> and C<language2code()>.
+
+=over 4
+
+=item code2language()
+
+This function takes a two letter language code and returns a string
+which contains the name of the language identified. If the code is
+not a valid language code, as defined by ISO 639, then C<undef>
+will be returned.
+
+    $lang = code2language($code);
+
+=item language2code()
+
+This function takes a language name and returns the corresponding
+two letter language code, if such exists.
+If the argument could not be identified as a language name,
+then C<undef> will be returned.
+
+    $code = language2code('French');
+
+The case of the language name is not important.
+See the section L<KNOWN BUGS AND LIMITATIONS> below.
+
+=back
+
+
+=head1 QUERY ROUTINES
+
+There are two function which can be used to obtain a list of all
+language codes, or all language names:
+
+=over 4
+
+=item C<all_language_codes()>
+
+Returns a list of all two-letter language codes.
+The codes are guaranteed to be all lower-case,
+and not in any particular order.
+
+=item C<all_language_names()>
+
+Returns a list of all language names for which there is a corresponding
+two-letter language code. The names are capitalised, and not returned
+in any particular order.
+
+=back
+
+
+=head1 EXAMPLES
+
+The following example illustrates use of the C<code2language()> function.
+The user is prompted for a language code, and then told the corresponding
+language name:
+
+    $| = 1;    # turn off buffering
+    
+    print "Enter language code: ";
+    chop($code = <STDIN>);
+    $lang = code2language($code);
+    if (defined $lang)
+    {
+        print "$code = $lang\n";
+    }
+    else
+    {
+        print "'$code' is not a valid language code!\n";
+    }
+
+=head1 KNOWN BUGS AND LIMITATIONS
+
+=over 4
+
+=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 *
+
+Currently just supports the two letter language codes -
+there are also three-letter codes, and numbers.
+Would these be of any use to anyone?
+
+=back
+
+=head1 SEE ALSO
+
+=over 4
+
+=item Locale::Country
+
+ISO codes for identification of country (ISO 3166).
+Supports 2-letter, 3-letter, and numeric country codes.
+
+=item Locale::Script
+
+ISO codes for identification of written scripts (ISO 15924).
+
+=item Locale::Currency
+
+ISO three letter codes for identification of currencies and funds (ISO 4217).
+
+=item ISO 639:1988 (E/F)
+
+Code for the representation of names of languages.
+
+=item http://lcweb.loc.gov/standards/iso639-2/langhome.html
+
+Home page for ISO 639-2.
+
+=back
+
+
+=head1 AUTHOR
+
+Neil Bowers E<lt>neil@bowers.comE<gt>
+
+=head1 COPYRIGHT
+
+Copyright (C) 2002, 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
+
index a7168fe..6b75afb 100644 (file)
-#-----------------------------------------------------------------------
-
-=head1 NAME
-
-Locale::Script - ISO codes for script identification (ISO 15924)
-
-=head1 SYNOPSIS
-
-    use Locale::Script;
-    use Locale::Constants;
-    
-    $script  = code2script('ph');                       # 'Phoenician'
-    $code    = script2code('Tibetan');                  # 'bo'
-    $code3   = script2code('Tibetan',
-                           LOCALE_CODE_ALPHA_3);        # 'bod'
-    $codeN   = script2code('Tibetan',
-                           LOCALE_CODE_ALPHA_NUMERIC);  # 330
-    
-    @codes   = all_script_codes();
-    @scripts = all_script_names();
-    
-=cut
-
-#-----------------------------------------------------------------------
+#
+# Locale::Script - ISO codes for script identification (ISO 15924)
+#
+# $Id: Script.pm,v 2.1 2002/02/06 04:07:10 neilb Exp $
+#
 
 package Locale::Script;
 use strict;
 require 5.002;
 
-#-----------------------------------------------------------------------
-
-=head1 DESCRIPTION
-
-The C<Locale::Script> module provides access to the ISO
-codes for identifying scripts, as defined in ISO 15924.
-For example, Egyptian hieroglyphs are denoted by the two-letter
-code 'eg', the three-letter code 'egy', and the numeric code 050.
-
-You can either access the codes via the conversion routines
-(described below), or with the two functions which return lists
-of all script codes or all script names.
-
-There are three different code sets you can use for identifying
-scripts:
-
-=over 4
-
-=item B<alpha-2>
-
-Two letter codes, such as 'bo' for Tibetan.
-This code set is identified with the symbol C<LOCALE_CODE_ALPHA_2>.
-
-=item B<alpha-3>
-
-Three letter codes, such as 'ell' for Greek.
-This code set is identified with the symbol C<LOCALE_CODE_ALPHA_3>.
-
-=item B<numeric>
-
-Numeric codes, such as 410 for Hiragana.
-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 Locale modules 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 Tibetan.
-When a code is returned by one of the functions in
-this module, it will always be lower-case.
-
-=head2 SPECIAL CODES
-
-The standard defines various special codes.
-
-=over 4
-
-=item *
-
-The standard reserves codes in the ranges B<qa> - B<qt>,
-B<qaa> - B<qat>, and B<900> - B<919>, for private use.
-
-=item *
-
-B<zx>, B<zxx>, and B<997>, are the codes for unwritten languages.
-
-=item *
-
-B<zy>, B<zyy>, and B<998>, are the codes for an undetermined script.
-
-=item *
-
-B<zz>, B<zzz>, and B<999>, are the codes for an uncoded script.
-
-=back
-
-The private codes are not recognised by Locale::Script,
-but the others are.
-
-=cut
-
-#-----------------------------------------------------------------------
-
 require Exporter;
 use Carp;
 use Locale::Constants;
@@ -115,7 +17,7 @@ use Locale::Constants;
 #      Public Global Variables
 #-----------------------------------------------------------------------
 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
-$VERSION   = sprintf("%d.%02d", q$Revision: 2.0 $ =~ /(\d+)\.(\d+)/);
+$VERSION   = sprintf("%d.%02d", q$Revision: 2.1 $ =~ /(\d+)\.(\d+)/);
 @ISA       = qw(Exporter);
 @EXPORT    = qw(code2script script2code
                 all_script_codes all_script_names
@@ -130,54 +32,9 @@ my $COUNTRIES = [];
 
 
 #=======================================================================
-
-=head1 CONVERSION ROUTINES
-
-There are three conversion routines: C<code2script()>, C<script2code()>,
-and C<script_code2code()>.
-
-=over 8
-
-=item code2script( CODE, [ CODESET ] )
-
-This function takes a script code and returns a string
-which contains the name of the script identified.
-If the code is not a valid script code, as defined by ISO 15924,
-then C<undef> will be returned:
-
-    $script = code2script('cy');   # Cyrillic
-
-=item script2code( STRING, [ CODESET ] )
-
-This function takes a script name and returns the corresponding
-script code, if such exists.
-If the argument could not be identified as a script name,
-then C<undef> will be returned:
-
-    $code = script2code('Gothic', LOCALE_CODE_ALPHA_3);
-    # $code will now be 'gth'
-
-The case of the script name is not important.
-See the section L<KNOWN BUGS AND LIMITATIONS> below.
-
-=item script_code2code( CODE, CODESET, CODESET )
-
-This function takes a script code from one code set,
-and returns the corresponding code from another code set.
-
-    $alpha2 = script_code2code('jwi',
-                LOCALE_CODE_ALPHA_3 => LOCALE_CODE_ALPHA_2);
-    # $alpha2 will now be 'jw' (Javanese)
-
-If the code passed is not a valid script code in
-the first code set, or if there isn't a code for the
-corresponding script in the second code set,
-then C<undef> will be returned.
-
-=back
-
-=cut
-
+#
+# code2script ( CODE [, CODESET ] )
+#
 #=======================================================================
 sub code2script
 {
@@ -216,6 +73,12 @@ sub code2script
     }
 }
 
+
+#=======================================================================
+#
+# script2code ( SCRIPT [, CODESET ] )
+#
+#=======================================================================
 sub script2code
 {
     my $script = shift;
@@ -237,6 +100,12 @@ sub script2code
     }
 }
 
+
+#=======================================================================
+#
+# script_code2code ( CODE, IN-CODESET, OUT-CODESET )
+#
+#=======================================================================
 sub script_code2code
 {
     (@_ == 3) or croak "script_code2code() takes 3 arguments!";
@@ -244,7 +113,7 @@ sub script_code2code
     my $code = shift;
     my $inset = shift;
     my $outset = shift;
-    my $outcode = shift;
+    my $outcode;
     my $script;
 
 
@@ -255,32 +124,12 @@ sub script_code2code
     return $outcode;
 }
 
-#=======================================================================
-
-=head1 QUERY ROUTINES
-
-There are two function which can be used to obtain a list of all codes,
-or all script names:
-
-=over 8
-
-=item C<all_script_codes ( [ CODESET ] )>
-
-Returns a list of all two-letter script codes.
-The codes are guaranteed to be all lower-case,
-and not in any particular order.
-
-=item C<all_script_names ( [ CODESET ] )>
-
-Returns a list of all script names for which there is a corresponding
-script code in the specified code set.
-The names are capitalised, and not returned in any particular order.
-
-=back
-
-=cut
 
 #=======================================================================
+#
+# all_script_codes()
+#
+#=======================================================================
 sub all_script_codes
 {
     my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
@@ -288,6 +137,12 @@ sub all_script_codes
     return keys %{ $CODES->[$codeset] };
 }
 
+
+#=======================================================================
+#
+# all_script_names()
+#
+#=======================================================================
 sub all_script_names
 {
     my $codeset = @_ > 0 ? shift : LOCALE_CODE_DEFAULT;
@@ -296,102 +151,10 @@ sub all_script_names
 }
 
 
-#-----------------------------------------------------------------------
-
-=head1 EXAMPLES
-
-The following example illustrates use of the C<code2script()> function.
-The user is prompted for a script code, and then told the corresponding
-script name:
-
-    $| = 1;   # turn off buffering
-    
-    print "Enter script code: ";
-    chop($code = <STDIN>);
-    $script = code2script($code, LOCALE_CODE_ALPHA_2);
-    if (defined $script)
-    {
-        print "$code = $script\n";
-    }
-    else
-    {
-        print "'$code' is not a valid script code!\n";
-    }
-
-
-=head1 KNOWN BUGS AND LIMITATIONS
-
-=over 4
-
-=item *
-
-When using C<script2code()>, the script name must currently appear
-exactly as it does in the source of the module. For example,
-
-    script2code('Egyptian hieroglyphs')
-
-will return B<eg>, as expected. But the following will all return C<undef>:
-
-    script2code('hieroglyphs')
-    script2code('Egyptian Hieroglypics')
-
-If there's need for it, a future version could have variants
-for script names.
-
-=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.
-
-=back
-
-=head1 SEE ALSO
-
-=over 4
-
-=item Locale::Language
-
-ISO two letter codes for identification of language (ISO 639).
-
-=item Locale::Currency
-
-ISO three letter codes for identification of currencies
-and funds (ISO 4217).
-
-=item Locale::Country
-
-ISO three letter codes for identification of countries (ISO 3166)
-
-=item ISO 15924
-
-The ISO standard which defines these codes.
-
-=item http://www.evertype.com/standards/iso15924/
-
-Home page for ISO 15924.
-
-
-=back
-
-
-=head1 AUTHOR
-
-Neil Bowers E<lt>neil@bowers.comE<gt>
-
-=head1 COPYRIGHT
-
-Copyright (c) 2002 Neil Bowers.
-
-This module is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-=cut
-
-#-----------------------------------------------------------------------
-
 #=======================================================================
+#
 # initialisation code - stuff the DATA into the ALPHA2 hash
+#
 #=======================================================================
 {
     my ($alpha2, $alpha3, $numeric);
diff --git a/lib/Locale/Script.pod b/lib/Locale/Script.pod
new file mode 100644 (file)
index 0000000..8cc981e
--- /dev/null
@@ -0,0 +1,253 @@
+
+=head1 NAME
+
+Locale::Script - ISO codes for script identification (ISO 15924)
+
+=head1 SYNOPSIS
+
+    use Locale::Script;
+    use Locale::Constants;
+    
+    $script  = code2script('ph');                       # 'Phoenician'
+    $code    = script2code('Tibetan');                  # 'bo'
+    $code3   = script2code('Tibetan',
+                           LOCALE_CODE_ALPHA_3);        # 'bod'
+    $codeN   = script2code('Tibetan',
+                           LOCALE_CODE_ALPHA_NUMERIC);  # 330
+    
+    @codes   = all_script_codes();
+    @scripts = all_script_names();
+    
+
+=head1 DESCRIPTION
+
+The C<Locale::Script> module provides access to the ISO
+codes for identifying scripts, as defined in ISO 15924.
+For example, Egyptian hieroglyphs are denoted by the two-letter
+code 'eg', the three-letter code 'egy', and the numeric code 050.
+
+You can either access the codes via the conversion routines
+(described below), or with the two functions which return lists
+of all script codes or all script names.
+
+There are three different code sets you can use for identifying
+scripts:
+
+=over 4
+
+=item B<alpha-2>
+
+Two letter codes, such as 'bo' for Tibetan.
+This code set is identified with the symbol C<LOCALE_CODE_ALPHA_2>.
+
+=item B<alpha-3>
+
+Three letter codes, such as 'ell' for Greek.
+This code set is identified with the symbol C<LOCALE_CODE_ALPHA_3>.
+
+=item B<numeric>
+
+Numeric codes, such as 410 for Hiragana.
+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 Locale modules 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 Tibetan.
+When a code is returned by one of the functions in
+this module, it will always be lower-case.
+
+=head2 SPECIAL CODES
+
+The standard defines various special codes.
+
+=over 4
+
+=item *
+
+The standard reserves codes in the ranges B<qa> - B<qt>,
+B<qaa> - B<qat>, and B<900> - B<919>, for private use.
+
+=item *
+
+B<zx>, B<zxx>, and B<997>, are the codes for unwritten languages.
+
+=item *
+
+B<zy>, B<zyy>, and B<998>, are the codes for an undetermined script.
+
+=item *
+
+B<zz>, B<zzz>, and B<999>, are the codes for an uncoded script.
+
+=back
+
+The private codes are not recognised by Locale::Script,
+but the others are.
+
+
+=head1 CONVERSION ROUTINES
+
+There are three conversion routines: C<code2script()>, C<script2code()>,
+and C<script_code2code()>.
+
+=over 4
+
+=item code2script( CODE, [ CODESET ] )
+
+This function takes a script code and returns a string
+which contains the name of the script identified.
+If the code is not a valid script code, as defined by ISO 15924,
+then C<undef> will be returned:
+
+    $script = code2script('cy');   # Cyrillic
+
+=item script2code( STRING, [ CODESET ] )
+
+This function takes a script name and returns the corresponding
+script code, if such exists.
+If the argument could not be identified as a script name,
+then C<undef> will be returned:
+
+    $code = script2code('Gothic', LOCALE_CODE_ALPHA_3);
+    # $code will now be 'gth'
+
+The case of the script name is not important.
+See the section L<KNOWN BUGS AND LIMITATIONS> below.
+
+=item script_code2code( CODE, CODESET, CODESET )
+
+This function takes a script code from one code set,
+and returns the corresponding code from another code set.
+
+    $alpha2 = script_code2code('jwi',
+                LOCALE_CODE_ALPHA_3 => LOCALE_CODE_ALPHA_2);
+    # $alpha2 will now be 'jw' (Javanese)
+
+If the code passed is not a valid script code in
+the first code set, or if there isn't a code for the
+corresponding script 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 script names:
+
+=over 4
+
+=item C<all_script_codes ( [ CODESET ] )>
+
+Returns a list of all two-letter script codes.
+The codes are guaranteed to be all lower-case,
+and not in any particular order.
+
+=item C<all_script_names ( [ CODESET ] )>
+
+Returns a list of all script names for which there is a corresponding
+script code in the specified code set.
+The names are capitalised, and not returned in any particular order.
+
+=back
+
+
+=head1 EXAMPLES
+
+The following example illustrates use of the C<code2script()> function.
+The user is prompted for a script code, and then told the corresponding
+script name:
+
+    $| = 1;   # turn off buffering
+    
+    print "Enter script code: ";
+    chop($code = <STDIN>);
+    $script = code2script($code, LOCALE_CODE_ALPHA_2);
+    if (defined $script)
+    {
+        print "$code = $script\n";
+    }
+    else
+    {
+        print "'$code' is not a valid script code!\n";
+    }
+
+
+=head1 KNOWN BUGS AND LIMITATIONS
+
+=over 4
+
+=item *
+
+When using C<script2code()>, the script name must currently appear
+exactly as it does in the source of the module. For example,
+
+    script2code('Egyptian hieroglyphs')
+
+will return B<eg>, as expected. But the following will all return C<undef>:
+
+    script2code('hieroglyphs')
+    script2code('Egyptian Hieroglypics')
+
+If there's need for it, a future version could have variants
+for script names.
+
+=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.
+
+=back
+
+=head1 SEE ALSO
+
+=over 4
+
+=item Locale::Language
+
+ISO two letter codes for identification of language (ISO 639).
+
+=item Locale::Currency
+
+ISO three letter codes for identification of currencies
+and funds (ISO 4217).
+
+=item Locale::Country
+
+ISO three letter codes for identification of countries (ISO 3166)
+
+=item ISO 15924
+
+The ISO standard which defines these codes.
+
+=item http://www.evertype.com/standards/iso15924/
+
+Home page for ISO 15924.
+
+
+=back
+
+
+=head1 AUTHOR
+
+Neil Bowers E<lt>neil@bowers.comE<gt>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2002 Neil Bowers.
+
+This module is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+=cut
+