From: Jarkko Hietaniemi Date: Tue, 19 Feb 2002 13:49:52 +0000 (+0000) Subject: Upgrade to Locale::Codes 2.01. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=6b14ceb78325f07f9267f4d0b22adc748311a9a0;p=p5sagit%2Fp5-mst-13.2.git Upgrade to Locale::Codes 2.01. p4raw-id: //depot/perl@14770 --- diff --git a/MANIFEST b/MANIFEST index 36326fd..b922e72 100644 --- 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 diff --git a/lib/Locale/Codes/ChangeLog b/lib/Locale/Codes/ChangeLog index d8a1837..639e631 100644 --- a/lib/Locale/Codes/ChangeLog +++ b/lib/Locale/Codes/ChangeLog @@ -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 diff --git a/lib/Locale/Codes/README b/lib/Locale/Codes/README index 20d174f..917b2c5 100644 --- a/lib/Locale/Codes/README +++ b/lib/Locale/Codes/README @@ -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, diff --git a/lib/Locale/Constants.pm b/lib/Locale/Constants.pm index 88651fd..c16d45e 100644 --- a/lib/Locale/Constants.pm +++ b/lib/Locale/Constants.pm @@ -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 defines symbols which are used in -the four modules from the Locale-Codes distribution: - - Locale::Language - Locale::Country - Locale::Currency - Locale::Script - -B 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 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 Eneil@bowers.comE - -=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 index 0000000..68d3358 --- /dev/null +++ b/lib/Locale/Constants.pod @@ -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 defines symbols which are used in +the four modules from the Locale-Codes distribution: + + Locale::Language + Locale::Country + Locale::Currency + Locale::Script + +B 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 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 Eneil@bowers.comE + +=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/Country.pm b/lib/Locale/Country.pm index 2f43ae7..48cb477 100644 --- a/lib/Locale/Country.pm +++ b/lib/Locale/Country.pm @@ -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 module provides access to the ISO -codes for identifying countries, as defined in ISO 3166. -You can either access the codes via the L -(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 - -Two letter codes, such as 'tv' for Tuvalu. -This code set is identified with the symbol C. - -=item B - -Three letter codes, such as 'brb' for Barbados. -This code set is identified with the symbol C. - -=item B - -Numeric codes, such as 064 for Bhutan. -This code set is identified with the symbol C. - -=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, C, -and C. - -=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 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 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 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 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 - -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 - -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 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 = ); - $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, B, B and friends would map to B; -B would map to B. Any others? - -=head1 KNOWN BUGS AND LIMITATIONS - -=over 4 - -=item * - -When using C, 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 Eneil@bowers.comE - -=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 index 0000000..bfa5bd5 --- /dev/null +++ b/lib/Locale/Country.pod @@ -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 module provides access to the ISO +codes for identifying countries, as defined in ISO 3166. +You can either access the codes via the L +(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 + +Two letter codes, such as 'tv' for Tuvalu. +This code set is identified with the symbol C. + +=item B + +Three letter codes, such as 'brb' for Barbados. +This code set is identified with the symbol C. + +=item B + +Numeric codes, such as 064 for Bhutan. +This code set is identified with the symbol C. + +=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, C, +and C. + +=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 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 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 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 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 + +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 + +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 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 = ); + $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, B, B and friends would map to B; +B would map to B. Any others? + +=head1 KNOWN BUGS AND LIMITATIONS + +=over 4 + +=item * + +When using C, 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 Eneil@bowers.comE + +=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 + diff --git a/lib/Locale/Currency.pm b/lib/Locale/Currency.pm index d8732e7..f8efffb 100644 --- a/lib/Locale/Currency.pm +++ b/lib/Locale/Currency.pm @@ -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 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 -(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 ¤cy2code &all_currency_codes &all_currency_names ); @@ -71,38 +28,9 @@ my %CURRENCIES = (); #======================================================================= - -=head1 CONVERSION ROUTINES - -There are two conversion routines: C and C. - -=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 -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 will be returned. - - $code = currency2code('French Franc'); - -The case of the currency name is not important. -See the section L 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 - -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 - -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 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 = ); - $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 Ehennecke@rz.uni-karlsruhe.deE -and -Neil Bowers Eneil@bowers.comE - -=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 index 0000000..4678d3e --- /dev/null +++ b/lib/Locale/Currency.pod @@ -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 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 +(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 and C. + +=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 +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 will be returned. + + $code = currency2code('French Franc'); + +The case of the currency name is not important. +See the section L 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 + +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 + +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 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 = ); + $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 Ehennecke@rz.uni-karlsruhe.deE +and +Neil Bowers Eneil@bowers.comE + +=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 + diff --git a/lib/Locale/Language.pm b/lib/Locale/Language.pm index 6479c28..70f118a 100644 --- a/lib/Locale/Language.pm +++ b/lib/Locale/Language.pm @@ -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 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 (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 and C. - -=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 -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 will be returned. - - $code = language2code('French'); - -The case of the language name is not important. -See the section L 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 - -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 - -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 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 = ); - $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 Eneil@bowers.comE - -=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 index 0000000..07ce4ba --- /dev/null +++ b/lib/Locale/Language.pod @@ -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 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 (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 and C. + +=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 +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 will be returned. + + $code = language2code('French'); + +The case of the language name is not important. +See the section L 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 + +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 + +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 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 = ); + $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 Eneil@bowers.comE + +=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 + diff --git a/lib/Locale/Script.pm b/lib/Locale/Script.pm index a7168fe..6b75afb 100644 --- a/lib/Locale/Script.pm +++ b/lib/Locale/Script.pm @@ -1,111 +1,13 @@ -#----------------------------------------------------------------------- - -=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 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 - -Two letter codes, such as 'bo' for Tibetan. -This code set is identified with the symbol C. - -=item B - -Three letter codes, such as 'ell' for Greek. -This code set is identified with the symbol C. - -=item B - -Numeric codes, such as 410 for Hiragana. -This code set is identified with the symbol C. - -=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 - B, -B - B, and B<900> - B<919>, for private use. - -=item * - -B, B, and B<997>, are the codes for unwritten languages. - -=item * - -B, B, and B<998>, are the codes for an undetermined script. - -=item * - -B, B, 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, C, -and C. - -=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 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 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 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 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 - -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 - -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 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 = ); - $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, the script name must currently appear -exactly as it does in the source of the module. For example, - - script2code('Egyptian hieroglyphs') - -will return B, as expected. But the following will all return C: - - 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 Eneil@bowers.comE - -=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 index 0000000..8cc981e --- /dev/null +++ b/lib/Locale/Script.pod @@ -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 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 + +Two letter codes, such as 'bo' for Tibetan. +This code set is identified with the symbol C. + +=item B + +Three letter codes, such as 'ell' for Greek. +This code set is identified with the symbol C. + +=item B + +Numeric codes, such as 410 for Hiragana. +This code set is identified with the symbol C. + +=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 - B, +B - B, and B<900> - B<919>, for private use. + +=item * + +B, B, and B<997>, are the codes for unwritten languages. + +=item * + +B, B, and B<998>, are the codes for an undetermined script. + +=item * + +B, B, 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, C, +and C. + +=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 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 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 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 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 + +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 + +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 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 = ); + $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, the script name must currently appear +exactly as it does in the source of the module. For example, + + script2code('Egyptian hieroglyphs') + +will return B, as expected. But the following will all return C: + + 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 Eneil@bowers.comE + +=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 +