In perl.git, the branch blead has been updated <http://perl5.git.perl.org/perl.git/commitdiff/afac733b093ba4436b25410cd880bcfdae213746?hp=16279618f4fddf32c6336e8b43059c0392284359>
- Log ----------------------------------------------------------------- commit afac733b093ba4436b25410cd880bcfdae213746 Author: Sullivan Beck <[email protected]> Date: Thu Jun 1 17:33:18 2017 -0400 Update Locale-Codes from CPAN 3.42 to 3.52. Committer: re-sorted MANIFEST. ----------------------------------------------------------------------- Summary of changes: MANIFEST | 43 +- Porting/Maintainers.pl | 2 +- cpan/Locale-Codes/lib/Locale/Codes.pm | 702 +- cpan/Locale-Codes/lib/Locale/Codes.pod | 536 +- cpan/Locale-Codes/lib/Locale/Codes/API.pod | 335 - cpan/Locale-Codes/lib/Locale/Codes/Changes.pod | 80 +- cpan/Locale-Codes/lib/Locale/Codes/Constants.pm | 328 +- cpan/Locale-Codes/lib/Locale/Codes/Country.pm | 76 +- cpan/Locale-Codes/lib/Locale/Codes/Country.pod | 168 +- .../Locale-Codes/lib/Locale/Codes/Country_Codes.pm | 1142 +- .../lib/Locale/Codes/Country_Retired.pm | 8 +- cpan/Locale-Codes/lib/Locale/Codes/Currency.pm | 74 +- cpan/Locale-Codes/lib/Locale/Codes/Currency.pod | 102 +- .../lib/Locale/Codes/Currency_Codes.pm | 16 +- .../lib/Locale/Codes/Currency_Retired.pm | 4 +- cpan/Locale-Codes/lib/Locale/Codes/LangExt.pm | 75 +- cpan/Locale-Codes/lib/Locale/Codes/LangExt.pod | 98 +- .../Locale-Codes/lib/Locale/Codes/LangExt_Codes.pm | 310 +- .../lib/Locale/Codes/LangExt_Retired.pm | 6 +- cpan/Locale-Codes/lib/Locale/Codes/LangFam.pm | 75 +- cpan/Locale-Codes/lib/Locale/Codes/LangFam.pod | 98 +- .../Locale-Codes/lib/Locale/Codes/LangFam_Codes.pm | 4 +- .../lib/Locale/Codes/LangFam_Retired.pm | 2 +- cpan/Locale-Codes/lib/Locale/Codes/LangVar.pm | 76 +- cpan/Locale-Codes/lib/Locale/Codes/LangVar.pod | 98 +- .../Locale-Codes/lib/Locale/Codes/LangVar_Codes.pm | 464 +- .../lib/Locale/Codes/LangVar_Retired.pm | 4 +- cpan/Locale-Codes/lib/Locale/Codes/Language.pm | 75 +- cpan/Locale-Codes/lib/Locale/Codes/Language.pod | 105 +- .../lib/Locale/Codes/Language_Codes.pm | 32921 ++++++++++--------- .../lib/Locale/Codes/Language_Retired.pm | 30 +- cpan/Locale-Codes/lib/Locale/Codes/Script.pm | 74 +- cpan/Locale-Codes/lib/Locale/Codes/Script.pod | 101 +- cpan/Locale-Codes/lib/Locale/Codes/Script_Codes.pm | 2107 +- .../lib/Locale/Codes/Script_Retired.pm | 4 +- cpan/Locale-Codes/lib/Locale/Codes/Types.pod | 414 + cpan/Locale-Codes/lib/Locale/Country.pm | 104 +- cpan/Locale-Codes/lib/Locale/Country.pod | 168 +- cpan/Locale-Codes/lib/Locale/Currency.pm | 104 +- cpan/Locale-Codes/lib/Locale/Currency.pod | 102 +- cpan/Locale-Codes/lib/Locale/Language.pm | 104 +- cpan/Locale-Codes/lib/Locale/Language.pod | 105 +- cpan/Locale-Codes/lib/Locale/Script.pm | 104 +- cpan/Locale-Codes/lib/Locale/Script.pod | 101 +- cpan/Locale-Codes/t/country.t | 47 - cpan/Locale-Codes/t/country_func.t | 27 + cpan/Locale-Codes/t/country_old.t | 32 +- cpan/Locale-Codes/t/country_oo.t | 27 + cpan/Locale-Codes/t/currency.t | 47 - cpan/Locale-Codes/t/currency_func.t | 27 + cpan/Locale-Codes/t/currency_old.t | 32 +- cpan/Locale-Codes/t/currency_oo.t | 27 + cpan/Locale-Codes/t/do_tests.pl | 328 + cpan/Locale-Codes/t/langext.t | 47 - cpan/Locale-Codes/t/langext_func.t | 27 + cpan/Locale-Codes/t/langext_oo.t | 27 + cpan/Locale-Codes/t/langfam.t | 47 - cpan/Locale-Codes/t/langfam_func.t | 27 + cpan/Locale-Codes/t/langfam_oo.t | 27 + cpan/Locale-Codes/t/language.t | 47 - cpan/Locale-Codes/t/language_func.t | 27 + cpan/Locale-Codes/t/language_old.t | 32 +- cpan/Locale-Codes/t/language_oo.t | 27 + cpan/Locale-Codes/t/langvar.t | 47 - cpan/Locale-Codes/t/langvar_func.t | 27 + cpan/Locale-Codes/t/langvar_oo.t | 27 + cpan/Locale-Codes/t/script.t | 47 - cpan/Locale-Codes/t/script_func.t | 27 + cpan/Locale-Codes/t/script_old.t | 32 +- cpan/Locale-Codes/t/script_oo.t | 27 + cpan/Locale-Codes/t/testfunc.pl | 2 +- cpan/Locale-Codes/t/vals.pl | 212 - cpan/Locale-Codes/t/vals_country.pl | 60 +- cpan/Locale-Codes/t/vals_currency.pl | 12 +- cpan/Locale-Codes/t/vals_langext.pl | 7 +- cpan/Locale-Codes/t/vals_langfam.pl | 7 +- cpan/Locale-Codes/t/vals_language.pl | 8 +- cpan/Locale-Codes/t/vals_langvar.pl | 7 +- cpan/Locale-Codes/t/vals_script.pl | 9 +- 79 files changed, 22164 insertions(+), 20972 deletions(-) delete mode 100644 cpan/Locale-Codes/lib/Locale/Codes/API.pod create mode 100644 cpan/Locale-Codes/lib/Locale/Codes/Types.pod delete mode 100644 cpan/Locale-Codes/t/country.t create mode 100644 cpan/Locale-Codes/t/country_func.t create mode 100644 cpan/Locale-Codes/t/country_oo.t delete mode 100644 cpan/Locale-Codes/t/currency.t create mode 100644 cpan/Locale-Codes/t/currency_func.t create mode 100644 cpan/Locale-Codes/t/currency_oo.t create mode 100644 cpan/Locale-Codes/t/do_tests.pl delete mode 100644 cpan/Locale-Codes/t/langext.t create mode 100644 cpan/Locale-Codes/t/langext_func.t create mode 100644 cpan/Locale-Codes/t/langext_oo.t delete mode 100644 cpan/Locale-Codes/t/langfam.t create mode 100644 cpan/Locale-Codes/t/langfam_func.t create mode 100644 cpan/Locale-Codes/t/langfam_oo.t delete mode 100644 cpan/Locale-Codes/t/language.t create mode 100644 cpan/Locale-Codes/t/language_func.t create mode 100644 cpan/Locale-Codes/t/language_oo.t delete mode 100644 cpan/Locale-Codes/t/langvar.t create mode 100644 cpan/Locale-Codes/t/langvar_func.t create mode 100644 cpan/Locale-Codes/t/langvar_oo.t delete mode 100644 cpan/Locale-Codes/t/script.t create mode 100644 cpan/Locale-Codes/t/script_func.t create mode 100644 cpan/Locale-Codes/t/script_oo.t delete mode 100644 cpan/Locale-Codes/t/vals.pl diff --git a/MANIFEST b/MANIFEST index 295875012e..8c4950e1b4 100644 --- a/MANIFEST +++ b/MANIFEST @@ -1618,7 +1618,6 @@ cpan/libnet/t/smtp_ssl.t cpan/libnet/t/time.t libnet cpan/Locale-Codes/lib/Locale/Codes.pm Locale::Codes cpan/Locale-Codes/lib/Locale/Codes.pod Locale::Codes documentation -cpan/Locale-Codes/lib/Locale/Codes/API.pod Locale::Codes documentation cpan/Locale-Codes/lib/Locale/Codes/Changes.pod Locale::Codes documentation cpan/Locale-Codes/lib/Locale/Codes/Constants.pm Locale::Codes cpan/Locale-Codes/lib/Locale/Codes/Country.pm Locale::Codes @@ -1649,6 +1648,7 @@ cpan/Locale-Codes/lib/Locale/Codes/Script.pm Locale::Codes cpan/Locale-Codes/lib/Locale/Codes/Script.pod Locale::Codes documentation cpan/Locale-Codes/lib/Locale/Codes/Script_Codes.pm Locale::Codes cpan/Locale-Codes/lib/Locale/Codes/Script_Retired.pm Locale::Codes +cpan/Locale-Codes/lib/Locale/Codes/Types.pod Locale::Codes documentation cpan/Locale-Codes/lib/Locale/Country.pm Locale::Codes cpan/Locale-Codes/lib/Locale/Country.pod Locale::Codes documentation cpan/Locale-Codes/lib/Locale/Currency.pm Locale::Codes @@ -1657,26 +1657,33 @@ cpan/Locale-Codes/lib/Locale/Language.pm Locale::Codes cpan/Locale-Codes/lib/Locale/Language.pod Locale::Codes documentation cpan/Locale-Codes/lib/Locale/Script.pm Locale::Codes cpan/Locale-Codes/lib/Locale/Script.pod Locale::Codes documentation -cpan/Locale-Codes/t/country.t Locale::Codes tests +cpan/Locale-Codes/t/country_func.t Locale::Codes tests cpan/Locale-Codes/t/country_old.t Locale::Codes tests -cpan/Locale-Codes/t/currency.t -cpan/Locale-Codes/t/currency_old.t -cpan/Locale-Codes/t/langext.t -cpan/Locale-Codes/t/langfam.t -cpan/Locale-Codes/t/language.t Locale::Codes tests +cpan/Locale-Codes/t/country_oo.t Locale::Codes tests +cpan/Locale-Codes/t/currency_func.t Locale::Codes tests +cpan/Locale-Codes/t/currency_old.t Locale::Codes tests +cpan/Locale-Codes/t/currency_oo.t Locale::Codes tests +cpan/Locale-Codes/t/do_tests.pl Locale::Codes tests +cpan/Locale-Codes/t/langext_func.t Locale::Codes tests +cpan/Locale-Codes/t/langext_oo.t Locale::Codes tests +cpan/Locale-Codes/t/langfam_func.t Locale::Codes tests +cpan/Locale-Codes/t/langfam_oo.t Locale::Codes tests +cpan/Locale-Codes/t/language_func.t Locale::Codes tests cpan/Locale-Codes/t/language_old.t Locale::Codes tests -cpan/Locale-Codes/t/langvar.t -cpan/Locale-Codes/t/script.t -cpan/Locale-Codes/t/script_old.t +cpan/Locale-Codes/t/language_oo.t Locale::Codes tests +cpan/Locale-Codes/t/langvar_func.t Locale::Codes tests +cpan/Locale-Codes/t/langvar_oo.t Locale::Codes tests +cpan/Locale-Codes/t/script_func.t Locale::Codes tests +cpan/Locale-Codes/t/script_old.t Locale::Codes tests +cpan/Locale-Codes/t/script_oo.t Locale::Codes tests cpan/Locale-Codes/t/testfunc.pl Locale::Codes tests -cpan/Locale-Codes/t/vals.pl -cpan/Locale-Codes/t/vals_country.pl -cpan/Locale-Codes/t/vals_currency.pl -cpan/Locale-Codes/t/vals_langext.pl -cpan/Locale-Codes/t/vals_langfam.pl -cpan/Locale-Codes/t/vals_language.pl -cpan/Locale-Codes/t/vals_langvar.pl -cpan/Locale-Codes/t/vals_script.pl +cpan/Locale-Codes/t/vals_country.pl Locale::Codes tests +cpan/Locale-Codes/t/vals_currency.pl Locale::Codes tests +cpan/Locale-Codes/t/vals_langext.pl Locale::Codes tests +cpan/Locale-Codes/t/vals_langfam.pl Locale::Codes tests +cpan/Locale-Codes/t/vals_language.pl Locale::Codes tests +cpan/Locale-Codes/t/vals_langvar.pl Locale::Codes tests +cpan/Locale-Codes/t/vals_script.pl Locale::Codes tests cpan/Locale-Maketext-Simple/lib/Locale/Maketext/Simple.pm Locale::Simple cpan/Locale-Maketext-Simple/t/0-signature.t Locale::Simple tests cpan/Locale-Maketext-Simple/t/1-basic.t Locale::Simple tests diff --git a/Porting/Maintainers.pl b/Porting/Maintainers.pl index 3c1b8486ba..26ada3539f 100755 --- a/Porting/Maintainers.pl +++ b/Porting/Maintainers.pl @@ -684,7 +684,7 @@ use File::Glob qw(:case); }, 'Locale-Codes' => { - 'DISTRIBUTION' => 'SBECK/Locale-Codes-3.42.tar.gz', + 'DISTRIBUTION' => 'SBECK/Locale-Codes-3.52.tar.gz', 'FILES' => q[cpan/Locale-Codes], 'EXCLUDED' => [ qw( README.first diff --git a/cpan/Locale-Codes/lib/Locale/Codes.pm b/cpan/Locale-Codes/lib/Locale/Codes.pm index bbe6ab50dd..fab6b763db 100644 --- a/cpan/Locale-Codes/lib/Locale/Codes.pm +++ b/cpan/Locale-Codes/lib/Locale/Codes.pm @@ -1,25 +1,34 @@ package Locale::Codes; # Copyright (C) 2001 Canon Research Centre Europe (CRE). # Copyright (C) 2002-2009 Neil Bowers -# Copyright (c) 2010-2016 Sullivan Beck +# Copyright (c) 2010-2017 Sullivan Beck # This program is free software; you can redistribute it and/or modify it # under the same terms as Perl itself. +############################################################################### + use strict; -require 5.006; use warnings; +require 5.006; use Carp; use Locale::Codes::Constants; -#======================================================================= -# Public Global Variables -#======================================================================= +our($VERSION); +$VERSION='3.52'; -# This module is not called directly... %Data is filled in by the -# calling modules. +use Exporter qw(import); +our(@EXPORT_OK,%EXPORT_TAGS); +@EXPORT_OK = @Locale::Codes::Constants::CONSTANTS; +%EXPORT_TAGS = ( 'constants' => [ @EXPORT_OK ] ); -our($VERSION,%Data,%Retired); +############################################################################### +# GLOBAL DATA +############################################################################### +# All of the data is stored in a couple global variables. They are filled +# in by requiring the appropriate TYPE_Codes and TYPE_Retired modules. + +our(%Data,%Retired); # $Data{ TYPE }{ code2id }{ CODESET } { CODE } = [ ID, I ] # { id2code }{ CODESET } { ID } = CODE @@ -31,27 +40,109 @@ our($VERSION,%Data,%Retired); # $Retired{ TYPE }{ CODESET }{ code }{ CODE } = NAME # { name }{ NAME } = [CODE,NAME] (the key is lowercase) -$VERSION='3.42'; +############################################################################### +# METHODS +############################################################################### + +sub new { + my($class,$type,$codeset,$show_errors) = @_; + my $self = { 'type' => '', + 'codeset' => '', + 'err' => (defined($show_errors) ? $show_errors : 1), + }; + + bless $self,$class; + + $self->type($type) if ($type); + $self->codeset($codeset) if ($codeset); + return $self; +} + +sub show_errors { + my($self,$val) = @_; + $$self{'err'} = $val; +} + +sub type { + my($self,$type) = @_; + + if (! exists $ALL_CODESETS{$type}) { + carp "ERROR: type: invalid argument: $type\n" if ($$self{'err'}); + return; + } + + if (! $ALL_CODESETS{$type}{'loaded'}) { + my $label = $ALL_CODESETS{$type}{'module'}; + eval "require Locale::Codes::${label}_Codes"; + if ($@) { + croak "ERROR: type: unable to load module: ${label}_Codes\n"; + } + eval "require Locale::Codes::${label}_Retired"; + if ($@) { + croak "ERROR: type: unable to load module: ${label}_Retired\n"; + } + $ALL_CODESETS{$type}{'loaded'} = 1; + } + + $$self{'type'} = $type; + $$self{'codeset'} = $ALL_CODESETS{$type}{'default'}; +} -#======================================================================= +sub codeset { + my($self,$codeset) = @_; + + my $type = $$self{'type'}; + if (! exists $ALL_CODESETS{$type}{'codesets'}{$codeset}) { + carp "ERROR: codeset: invalid argument: $codeset\n" if ($$self{'err'}); + } + + $$self{'codeset'} = $codeset; +} + +sub version { + my($self) = @_; + return $VERSION; +} + +############################################################################### + +# This is used to validate a codeset and/or code. It will also format +# a code for that codeset. # -# _code ( TYPE,CODE,CODESET ) +# (ERR,RET_CODE,RET_CODESET) = $o->_code([CODE [,CODESET]]) +# +# If CODE is empty/undef, only the codeset will be validated +# and RET_CODE will be empty. +# +# If CODE is passed in, it will be returned formatted correctly +# for the codeset. +# +# ERR will be 0 or 1. +# +# If $no_check_code is 1, then the code will not be validated (i.e. +# it doesn't already have to exist). This will be useful for adding +# a new code. # -#======================================================================= - sub _code { - return (1) if (@_ > 3); + my($self,$code,$codeset,$no_check_code) = @_; + $code = '' if (! defined($code)); + $codeset = lc($codeset) if (defined($codeset)); - my($type,$code,$codeset) = @_; - $code = '' if (! defined $code); + if (! $$self{'type'}) { + carp "ERROR: no type set for Locale::Codes object\n" if ($$self{'err'}); + return (1); + } + my $type = $$self{'type'}; + if ($codeset && ! exists $ALL_CODESETS{$type}{'codesets'}{$codeset}) { + carp "ERROR: _code: invalid codeset provided: $codeset\n" + if ($$self{'err'}); + return (1); + } - # Determine the codeset + # If no codeset was passed in, return the codeset specified. - $codeset = $ALL_CODESETS{$type}{'default'} - if (! defined($codeset) || $codeset eq ''); - $codeset = lc($codeset); - return (1) if (! exists $ALL_CODESETS{$type}{'codesets'}{$codeset}); - return (0,$code,$codeset) if ($code eq ''); + $codeset = $$self{'codeset'} if (! defined($codeset) || $codeset eq ''); + return (0,'',$codeset) if ($code eq ''); # Determine the properties of the codeset @@ -59,47 +150,65 @@ sub _code { if ($op eq 'lc') { $code = lc($code); - return (0,$code,$codeset); } if ($op eq 'uc') { $code = uc($code); - return (0,$code,$codeset); } if ($op eq 'ucfirst') { $code = ucfirst(lc($code)); - return (0,$code,$codeset); } # uncoverable branch false if ($op eq 'numeric') { - return (1) unless ($code =~ /^\d+$/); - my $l = $args[0]; - $code = sprintf("%.${l}d", $code); - return (0,$code,$codeset); + if ($code =~ /^\d+$/) { + my $l = $args[0]; + $code = sprintf("%.${l}d", $code); + + } else { + carp "ERROR: _code: invalid numeric code: $code\n" if ($$self{'err'}); + return (1); + } } - # uncoverable statement - die "ERROR: codeset not defined correctly: $codeset [$op]\n"; + # Determine if the code is in the codeset. + + if (! $no_check_code && + ! exists $Data{$type}{'code2id'}{$codeset}{$code} && + ! exists $Retired{$type}{$codeset}{'code'}{$code} && + ! exists $Data{$type}{'codealias'}{$codeset}{$code}) { + carp "ERROR: _code: code not in codeset: $code [$codeset]\n" + if ($$self{'err'}); + return (1); + } + + return (0,$code,$codeset); } -#======================================================================= +############################################################################### + +# $name = $o->code2name(CODE [,CODESET] [,'retired']) +# $code = $o->name2code(NAME [,CODESET] [,'retired']) # -# _code2name ( TYPE,CODE [,CODESET] [,'retired'] ) +# Returns the name associated with the CODE (or vice versa). # -#======================================================================= - -sub _code2name { - my($type,@args) = @_; - my $retired = 0; - if (@args > 0 && $args[$#args] && $args[$#args] eq 'retired') { +sub code2name { + my($self,@args) = @_; + my $retired = 0; + if (@args && defined($args[$#args]) && lc($args[$#args]) eq 'retired') { pop(@args); - $retired = 1; + $retired = 1; } - my($err,$code,$codeset) = _code($type,@args); - return undef if ($err); + if (! $$self{'type'}) { + carp "ERROR: no type set for Locale::Codes object\n" if ($$self{'err'}); + return (1); + } + my $type = $$self{'type'}; + + my ($err,$code,$codeset) = $self->_code(@args); + return undef if ($err || ! $code); $code = $Data{$type}{'codealias'}{$codeset}{$code} if (exists $Data{$type}{'codealias'}{$codeset}{$code}); @@ -117,24 +226,24 @@ sub _code2name { } } -#======================================================================= -# -# _name2code ( TYPE,NAME [,CODESET] [,'retired'] ) -# -#======================================================================= - -sub _name2code { - my($type,$name,@args) = @_; +sub name2code { + my($self,$name,@args) = @_; return undef if (! $name); $name = lc($name); - my $retired = 0; - if (@args > 0 && $args[$#args] eq 'retired') { + my $retired = 0; + if (@args && defined($args[$#args]) && lc($args[$#args]) eq 'retired') { pop(@args); - $retired = 1; + $retired = 1; } - my($err,$tmp,$codeset) = _code($type,'',@args); + if (! $$self{'type'}) { + carp "ERROR: no type set for Locale::Codes object\n" if ($$self{'err'}); + return (1); + } + my $type = $$self{'type'}; + + my ($err,$tmp,$codeset) = $self->_code('',@args); return undef if ($err); if (exists $Data{$type}{'alias2id'}{$name}) { @@ -150,58 +259,64 @@ sub _name2code { return undef; } -#======================================================================= +# $code = $o->code2code(CODE,CODESET2) +# $code = $o->code2code(CODE,CODESET1,CODESET2) # -# _code2code ( TYPE,CODE,CODESET ) +# Changes the code in the CODESET1 (or the current codeset) to another +# codeset (CODESET2) # -#======================================================================= - -sub _code2code { - my($type,@args) = @_; +sub code2code { + my($self,@args) = @_; - # For tests, we'll ALWAYS have $nowarn - my $nowarn = 0; - if (@args) { # uncoverable branch false - if ($args[$#args] eq "nowarn") { # uncoverable branch false - $nowarn = 1; - pop(@args); - } + if (! $$self{'type'}) { + carp "ERROR: no type set for Locale::Codes object\n" if ($$self{'err'}); + return (1); } + my $type = $$self{'type'}; - if (@args != 3) { - if (! $nowarn) { # uncoverable branch true - croak "${type}_code2code() takes 3 arguments!"; # uncoverable statement - } - return undef; - } + my($code,$codeset1,$codeset2,$err); - my($code,$inset,$outset) = @args; - my($err,$tmp); - ($err,$code,$inset) = _code($type,$code,$inset); - return undef if ($err); - ($err,$tmp,$outset) = _code($type,'',$outset); - return undef if ($err); + if (@args == 2) { + ($code,$codeset2) = @args; + ($err,$code,$codeset1) = $self->_code($code); + return undef if ($err); - my $name = _code2name($type,$code,$inset); - my $outcode = _name2code($type,$name,$outset); - return $outcode; + } elsif (@args == 3) { + ($code,$codeset1,$codeset2) = @args; + ($err,$code) = $self->_code($code,$codeset1); + return undef if ($err); + ($err) = $self->_code('',$codeset2); + return undef if ($err); + } + + my $name = $self->code2name($code,$codeset1); + my $out = $self->name2code($name,$codeset2); + return $out; } -#======================================================================= -# -# _all_codes ( TYPE [,CODESET] [,'retired'] ) +############################################################################### + +# @codes = $o->all_codes([CODESET] [,'retired']); +# @names = $o->all_names([CODESET] [,'retired']); # -#======================================================================= +# Returns all codes/names in the specified codeset, including retired +# ones if the option is given. -sub _all_codes { - my($type,@args) = @_; - my $retired = 0; - if (@args > 0 && $args[$#args] eq 'retired') { +sub all_codes { + my($self,@args) = @_; + my $retired = 0; + if (@args && defined($args[$#args]) && lc($args[$#args]) eq 'retired') { pop(@args); - $retired = 1; + $retired = 1; + } + + if (! $$self{'type'}) { + carp "ERROR: no type set for Locale::Codes object\n" if ($$self{'err'}); + return (1); } + my $type = $$self{'type'}; - my ($err,$tmp,$codeset) = _code($type,'',@args); + my ($err,$tmp,$codeset) = $self->_code('',@args); return () if ($err); my @codes = keys %{ $Data{$type}{'code2id'}{$codeset} }; @@ -209,24 +324,24 @@ sub _all_codes { return (sort @codes); } -#======================================================================= -# -# _all_names ( TYPE [,CODESET] [,'retired'] ) -# -#======================================================================= - -sub _all_names { - my($type,@args) = @_; - my $retired = 0; - if (@args > 0 && $args[$#args] eq 'retired') { +sub all_names { + my($self,@args) = @_; + my $retired = 0; + if (@args && defined($args[$#args]) && lc($args[$#args]) eq 'retired') { pop(@args); - $retired = 1; + $retired = 1; } - my ($err,$tmp,$codeset) = _code($type,'',@args); + if (! $$self{'type'}) { + carp "ERROR: no type set for Locale::Codes object\n" if ($$self{'err'}); + return (1); + } + my $type = $$self{'type'}; + + my ($err,$tmp,$codeset) = $self->_code('',@args); return () if ($err); - my @codes = _all_codes($type,$codeset); + my @codes = $self->all_codes($codeset); my @names; foreach my $code (@codes) { @@ -243,50 +358,34 @@ sub _all_names { return (sort @names); } -#======================================================================= -# -# _rename ( TYPE,CODE,NAME,CODESET ) +############################################################################### + +# $flag = $o->rename_code (CODE,NEW_NAME [,CODESET]) # # Change the official name for a code. The original is retained # as an alias, but the new name will be returned if you lookup the # name from code. # -#======================================================================= - -sub _rename { - my($type,$code,$new_name,@args) = @_; - - # For tests, we'll ALWAYS have $nowarn - my $nowarn = 0; - if (@args) { # uncoverable branch false - if ($args[$#args] eq "nowarn") { # uncoverable branch false - $nowarn = 1; - pop(@args); - } - } - - my $codeset = shift(@args); - my $err; - ($err,$code,$codeset) = _code($type,$code,$codeset); +# Returns 1 on success. +# +sub rename_code { + my($self,$code,$new_name,$codeset) = @_; - if (! $codeset) { - if (! $nowarn) { # uncoverable branch true - carp "rename_$type(): unknown codeset\n"; # uncoverable statement - } + if (! $$self{'type'}) { + carp "ERROR: no type set for Locale::Codes object\n" if ($$self{'err'}); return 0; } + my $type = $$self{'type'}; - # Check that $code exists in the codeset. + # Make sure $code/$codeset are both valid - my $id; - if (exists $Data{$type}{'code2id'}{$codeset}{$code}) { - $id = $Data{$type}{'code2id'}{$codeset}{$code}[0]; - } else { - if (! $nowarn) { # uncoverable branch true - carp "rename_$type(): unknown code: $code\n"; # uncoverable statement - } + my($err,$c,$cs) = $self->_code($code,$codeset); + if ($err) { + carp "ERROR: rename: Unknown code/codeset: $code [$codeset]\n" + if ($$self{'err'}); return 0; } + ($code,$codeset) = ($c,$cs); # Cases: # 1. Renaming to a name which exists with a different ID @@ -299,17 +398,16 @@ sub _rename { # Create a new alias # Change code2id (I value) + my $id = $Data{$type}{'code2id'}{$codeset}{$code}[0]; + if (exists $Data{$type}{'alias2id'}{lc($new_name)}) { # Existing name (case 1 and 2) my ($new_id,$i) = @{ $Data{$type}{'alias2id'}{lc($new_name)} }; if ($new_id != $id) { # Case 1 - if (! $nowarn) { # uncoverable branch true - # uncoverable statement - carp "rename_$type(): rename to an existing $type not allowed\n"; - } - + carp "ERROR: rename: rename to an existing name not allowed\n" + if ($$self{'err'}); return 0; } @@ -330,45 +428,37 @@ sub _rename { return 1; } -#======================================================================= -# -# _add_code ( TYPE,CODE,NAME,CODESET ) +############################################################################### + +# $flag = $o->add_code (CODE,NAME [,CODESET]) # # Add a new code to the codeset. Both CODE and NAME must be # unused in the code set. # -#======================================================================= +sub add_code { + my($self,$code,$name,$codeset) = @_; -sub _add_code { - my($type,$code,$name,@args) = @_; - - # For tests, we'll ALWAYS have $nowarn - my $nowarn = 0; - if (@args) { # uncoverable branch false - if ($args[$#args] eq "nowarn") { # uncoverable branch false - $nowarn = 1; - pop(@args); - } + if (! $$self{'type'}) { + carp "ERROR: no type set for Locale::Codes object\n" if ($$self{'err'}); + return 0; } + my $type = $$self{'type'}; - my $codeset = shift(@args); - my $err; - ($err,$code,$codeset) = _code($type,$code,$codeset); + # Make sure that $codeset is valid. - if (! $codeset) { - if (! $nowarn) { # uncoverable branch true - carp "add_$type(): unknown codeset\n"; # uncoverable statement - } + my($err,$c,$cs) = $self->_code($code,$codeset,1); + if ($err) { + carp "ERROR: rename: Unknown codeset: $codeset\n" + if ($$self{'err'}); return 0; } + ($code,$codeset) = ($c,$cs); # Check that $code is unused. if (exists $Data{$type}{'code2id'}{$codeset}{$code} || exists $Data{$type}{'codealias'}{$codeset}{$code}) { - if (! $nowarn) { # uncoverable branch true - carp "add_$type(): code already in use: $code\n";# uncoverable statement - } + carp "add_code: code already in use: $code\n" if ($$self{'err'}); return 0; } @@ -380,10 +470,7 @@ sub _add_code { if (exists $Data{$type}{'alias2id'}{lc($name)}) { ($id,$i) = @{ $Data{$type}{'alias2id'}{lc($name)} }; if (exists $Data{$type}{'id2code'}{$codeset}{$id}) { - if (! $nowarn) { # uncoverable branch true - # uncoverable statement - carp "add_$type(): name already in use: $name\n"; - } + carp "add_code: name already in use: $name\n" if ($$self{'err'}); return 0; } @@ -402,46 +489,30 @@ sub _add_code { return 1; } -#======================================================================= -# -# _delete_code ( TYPE,CODE,CODESET ) +############################################################################### + +# $flag = $o->delete_code (CODE [,CODESET]) # # Delete a code from the codeset. # -#======================================================================= - -sub _delete_code { - my($type,$code,@args) = @_; +sub delete_code { + my($self,$code,$codeset) = @_; - # For tests, we'll ALWAYS have $nowarn - my $nowarn = 0; - if (@args) { # uncoverable branch false - if ($args[$#args] eq "nowarn") { # uncoverable branch false - $nowarn = 1; - pop(@args); - } - } - - my $codeset = shift(@args); - my $err; - ($err,$code,$codeset) = _code($type,$code,$codeset); - - if (! $codeset) { - if (! $nowarn) { # uncoverable branch true - carp "delete_$type(): unknown codeset\n"; # uncoverable statement - } + if (! $$self{'type'}) { + carp "ERROR: no type set for Locale::Codes object\n" if ($$self{'err'}); return 0; } + my $type = $$self{'type'}; - # Check that $code is valid. + # Make sure $code/$codeset are both valid - if (! exists $Data{$type}{'code2id'}{$codeset}{$code}) { - if (! $nowarn) { # uncoverable branch true - # uncoverable statement - carp "delete_$type(): code does not exist: $code\n"; - } + my($err,$c,$cs) = $self->_code($code,$codeset); + if ($err) { + carp "ERROR: rename: Unknown code/codeset: $code [$codeset]\n" + if ($$self{'err'}); return 0; } + ($code,$codeset) = ($c,$cs); # Delete the code @@ -472,25 +543,20 @@ sub _delete_code { return 1; } -#======================================================================= -# -# _add_alias ( TYPE,NAME,NEW_NAME ) +############################################################################### + +# $flag = $o->add_alias (NAME,NEW_NAME) # # Add a new alias. NAME must exist, and NEW_NAME must be unused. # -#======================================================================= - -sub _add_alias { - my($type,$name,$new_name,@args) = @_; +sub add_alias { + my($self,$name,$new_name) = @_; - # For tests, we'll ALWAYS have $nowarn - my $nowarn = 0; - if (@args) { # uncoverable branch false - if ($args[$#args] eq "nowarn") { # uncoverable branch false - $nowarn = 1; - pop(@args); - } + if (! $$self{'type'}) { + carp "ERROR: no type set for Locale::Codes object\n" if ($$self{'err'}); + return 0; } + my $type = $$self{'type'}; # Check that $name is used and $new_name is new. @@ -498,18 +564,12 @@ sub _add_alias { if (exists $Data{$type}{'alias2id'}{lc($name)}) { $id = $Data{$type}{'alias2id'}{lc($name)}[0]; } else { - if (! $nowarn) { # uncoverable branch true - # uncoverable statement - carp "add_${type}_alias(): name does not exist: $name\n"; - } + carp "add_alias: name does not exist: $name\n" if ($$self{'err'}); return 0; } if (exists $Data{$type}{'alias2id'}{lc($new_name)}) { - if (! $nowarn) { # uncoverable branch true - # uncoverable statement - carp "add_${type}_alias(): alias already in use: $new_name\n"; - } + carp "add_alias: alias already in use: $new_name\n" if ($$self{'err'}); return 0; } @@ -522,9 +582,9 @@ sub _add_alias { return 1; } -#======================================================================= -# -# _delete_alias ( TYPE,NAME ) +############################################################################### + +# $flag = $o->delete_alias (NAME) # # This deletes a name from the list of names used by an element. # NAME must be used, but must NOT be the only name in the list. @@ -532,19 +592,14 @@ sub _add_alias { # Any id2name that references this name will be changed to # refer to the first name in the list. # -#======================================================================= +sub delete_alias { + my($self,$name) = @_; -sub _delete_alias { - my($type,$name,@args) = @_; - - # For tests, we'll ALWAYS have $nowarn - my $nowarn = 0; - if (@args) { # uncoverable branch false - if ($args[$#args] eq "nowarn") { # uncoverable branch false - $nowarn = 1; - pop(@args); - } + if (! $$self{'type'}) { + carp "ERROR: no type set for Locale::Codes object\n" if ($$self{'err'}); + return 0; } + my $type = $$self{'type'}; # Check that $name is used. @@ -552,19 +607,14 @@ sub _delete_alias { if (exists $Data{$type}{'alias2id'}{lc($name)}) { ($id,$i) = @{ $Data{$type}{'alias2id'}{lc($name)} }; } else { - if (! $nowarn) { # uncoverable branch true - # uncoverable statement - carp "delete_${type}_alias(): name does not exist: $name\n"; - } + carp "delete_alias: name does not exist: $name\n" if ($$self{'err'}); return 0; } my $n = $#{ $Data{$type}{'id2names'}{$id} } + 1; if ($n == 1) { - if (! $nowarn) { # uncoverable branch true - # uncoverable statement - carp "delete_${type}_alias(): only one name defined (use _delete_${type} instead)\n"; - } + carp "delete_alias: only one name defined (use delete_code instead)\n" + if ($$self{'err'}); return 0; } @@ -594,49 +644,34 @@ sub _delete_alias { return 1; } -#======================================================================= -# -# _rename_code ( TYPE,CODE,NEW_CODE,CODESET ) +############################################################################### + +# $flag = $o->replace_code (CODE,NEW_CODE [,CODESET]) # # Change the official code. The original is retained as an alias, but -# the new name will be returned if you lookup the code from name. +# the new code will be returned if do a name2code lookup. # -#======================================================================= - -sub _rename_code { - my($type,$code,$new_code,@args) = @_; - - # For tests, we'll ALWAYS have $nowarn - my $nowarn = 0; - if (@args) { # uncoverable branch false - if ($args[$#args] eq "nowarn") { # uncoverable branch false - $nowarn = 1; - pop(@args); - } - } - - my $codeset = shift(@args); - my $err; - ($err,$code,$codeset) = _code($type,$code,$codeset); +sub replace_code { + my($self,$code,$new_code,$codeset) = @_; - if (! $codeset) { - if (! $nowarn) { # uncoverable branch true - carp "rename_${type}_code(): unknown codeset\n"; # uncoverable statement - } + if (! $$self{'type'}) { + carp "ERROR: no type set for Locale::Codes object\n" if ($$self{'err'}); return 0; } + my $type = $$self{'type'}; - ($err,$new_code,$codeset) = _code($type,$new_code,$codeset); - - # Check that $code exists in the codeset. + # Make sure $code/$codeset are both valid (and that $new_code is the + # correct format) - if (! exists $Data{$type}{'code2id'}{$codeset}{$code}) { - if (! $nowarn) { # uncoverable branch true - # uncoverable statement - carp "rename_${type}_code(): unknown code: $code\n"; - } + my($err,$c,$cs) = $self->_code($code,$codeset); + if ($err) { + carp "ERROR: rename_code: Unknown code/codeset: $code [$codeset]\n" + if ($$self{'err'}); return 0; } + ($code,$codeset) = ($c,$cs); + + ($err,$new_code,$codeset) = $self->_code($new_code,$codeset,1); # Cases: # 1. Renaming code to an existing alias of this code: @@ -661,19 +696,15 @@ sub _rename_code { } else { # Case 2 - if (! $nowarn) { # uncoverable branch true - # uncoverable statement - carp "rename_${type}_code(): new code already in use: $new_code\n"; - } + carp "rename_code: new code already in use: $new_code\n" + if ($$self{'err'}); return 0; } } elsif (exists $Data{$type}{'code2id'}{$codeset}{$new_code}) { # Case 3 - if (! $nowarn) { # uncoverable branch true - # uncoverable statement - carp "rename_${type}_code(): new code already in use: $new_code\n"; - } + carp "rename_code: new code already in use: $new_code\n" + if ($$self{'err'}); return 0; } @@ -682,7 +713,8 @@ sub _rename_code { $Data{$type}{'codealias'}{$codeset}{$code} = $new_code; my $id = $Data{$type}{'code2id'}{$codeset}{$code}[0]; - $Data{$type}{'code2id'}{$codeset}{$new_code} = $Data{$type}{'code2id'}{$codeset}{$code}; + $Data{$type}{'code2id'}{$codeset}{$new_code} = + $Data{$type}{'code2id'}{$codeset}{$code}; delete $Data{$type}{'code2id'}{$codeset}{$code}; $Data{$type}{'id2code'}{$codeset}{$id} = $new_code; @@ -690,57 +722,39 @@ sub _rename_code { return 1; } -#======================================================================= -# -# _add_code_alias ( TYPE,CODE,NEW_CODE,CODESET ) +############################################################################### + +# $flag = $o->add_code_alias (CODE,NEW_CODE [,CODESET]) # # Adds an alias for the code. # -#======================================================================= - -sub _add_code_alias { - my($type,$code,$new_code,@args) = @_; +sub add_code_alias { + my($self,$code,$new_code,$codeset) = @_; - # For tests, we'll ALWAYS have $nowarn - my $nowarn = 0; - if (@args) { # uncoverable branch false - if ($args[$#args] eq "nowarn") { # uncoverable branch false - $nowarn = 1; - pop(@args); - } + if (! $$self{'type'}) { + carp "ERROR: no type set for Locale::Codes object\n" if ($$self{'err'}); + return 0; } + my $type = $$self{'type'}; - my $codeset = shift(@args); - my $err; - ($err,$code,$codeset) = _code($type,$code,$codeset); + # Make sure $code/$codeset are both valid and that the new code is + # properly formatted. - if (! $codeset) { - if (! $nowarn) { # uncoverable branch true - # uncoverable statement - carp "add_${type}_code_alias(): unknown codeset\n"; - } + my($err,$c,$cs) = $self->_code($code,$codeset); + if ($err) { + carp "ERROR: add_code_alias: Unknown code/codeset: $code [$codeset]\n" + if ($$self{'err'}); return 0; } + ($code,$codeset) = ($c,$cs); - ($err,$new_code,$codeset) = _code($type,$new_code,$codeset); - - # Check that $code exists in the codeset and that $new_code - # does not exist. + ($err,$new_code,$cs) = $self->_code($new_code,$codeset,1); - if (! exists $Data{$type}{'code2id'}{$codeset}{$code}) { - if (! $nowarn) { # uncoverable branch true - # uncoverable statement - carp "add_${type}_code_alias(): unknown code: $code\n"; - } - return 0; - } + # Check that $new_code does not exist. if (exists $Data{$type}{'code2id'}{$codeset}{$new_code} || exists $Data{$type}{'codealias'}{$codeset}{$new_code}) { - if (! $nowarn) { # uncoverable branch true - # uncoverable statement - carp "add_${type}_code_alias(): code already in use: $new_code\n"; - } + carp "add_code_alias: code already in use: $new_code\n" if ($$self{'err'}); return 0; } @@ -751,45 +765,35 @@ sub _add_code_alias { return 1; } -#======================================================================= -# -# _delete_code_alias ( TYPE,ALIAS,CODESET ) +############################################################################### + +# $flag = $o->delete_code_alias (ALIAS [,CODESET]) # # Deletes an alias for the code. # -#======================================================================= - -sub _delete_code_alias { - my($type,$code,@args) = @_; +sub delete_code_alias { + my($self,$code,$codeset) = @_; - # For tests, we'll ALWAYS have $nowarn - my $nowarn = 0; - if (@args) { # uncoverable branch false - if ($args[$#args] eq "nowarn") { # uncoverable branch false - $nowarn = 1; - pop(@args); - } + if (! $$self{'type'}) { + carp "ERROR: no type set for Locale::Codes object\n" if ($$self{'err'}); + return 0; } + my $type = $$self{'type'}; - my $codeset = shift(@args); - my $err; - ($err,$code,$codeset) = Locale::Codes::_code($type,$code,$codeset); + # Make sure $code/$codeset are both valid - if (! $codeset) { - if (! $nowarn) { # uncoverable branch true - # uncoverable statement - carp "delete_${type}_code_alias(): unknown codeset\n"; - } + my($err,$c,$cs) = $self->_code($code,$codeset); + if ($err) { + carp "ERROR: rename: Unknown code/codeset: $code [$codeset]\n" + if ($$self{'err'}); return 0; } + ($code,$codeset) = ($c,$cs); # Check that $code exists in the codeset as an alias. if (! exists $Data{$type}{'codealias'}{$codeset}{$code}) { - if (! $nowarn) { # uncoverable branch true - # uncoverable statement - carp "delete_${type}_code_alias(): no alias defined: $code\n"; - } + carp "delete_code_alias(): no alias defined: $code\n" if ($$self{'err'}); return 0; } diff --git a/cpan/Locale-Codes/lib/Locale/Codes.pod b/cpan/Locale-Codes/lib/Locale/Codes.pod index d52c82f435..9f0d2e9c2e 100644 --- a/cpan/Locale-Codes/lib/Locale/Codes.pod +++ b/cpan/Locale-Codes/lib/Locale/Codes.pod @@ -6,171 +6,428 @@ Locale::Codes - a distribution of modules to handle locale codes =head1 DESCRIPTION -B<Locale-Codes> is a distribution containing a set of modules. The -modules each deal with different types of codes which identify parts -of the locale including languages, countries, currency, etc. +B<Locale-Codes> is a distribution containing a set of modules designed +to work with sets of codes which uniquely identify something. For +example, there are codes associated with different countries, different +currencies, different languages, etc. These sets of codes are typically +maintained in some standard. + +This distribution provides a way to work with these lists of codes. +Because the data from the various standards is not available in any +sort of consistent API, access to the lists is not available in any +direct fashion. To compensate for this, the list of codes is stored +internally within this distribution, and the distribution is updated +on a regular basis to include all known codes at that point in time. +This does mean that it is necessary to keep this distribution +up-to-date to keep up with the various changes that are made in the +various standards. + +Traditionally, a module has been created to work with each type of +code sets. So, there is a module for working with country lists, one +for currency lists, etc. Since version 3.00, all of these individual +modules were written as wrappers around a central module (which was not +intended to be used directly) which did all of the real work. + +Starting with version 3.50, the central module was reworked slightly +to provide an object-oriented interface. All of the modules for +working with individual types of code sets were reworked to use the +improved OO module, so the traditional interfaces still work as they +always have. As a result, you are free to use the traditional +functional (non-OO) interfaces, or to use the OO interface and bypass +the wrapper modules entirely. + +Both methods will be supported in the future, so use the one that is +best suited to your needs. + +Within each type, any number of code sets are allowed. For example, +sets of country codes are maintained in several different locations +including the ISO-3166 standard, the IANA, and by the United Nations. +The lists of countries are similar, but not identical. Multiple code +sets are supported, though trying to convert from one code set to +another will not always work since the list of countries is not +one-to-one. -Currently, the following modules are included: +All data in all of these modules comes directly from the original +standards (or as close to direct as possible), so it should be +up-to-date at the time of release. + +I plan on releasing a new version several times a year to incorporate +any changes made in the standards. However, I don't always know about +changes that occur, so if any of the standards change, and you want a +new release sooner, just email me and I'll get one out. + +=head1 SYNOPSIS (OBJECT-ORIENTED INTERFACE) + + use Locale::Codes; + or + use Locale::Codes ':constants'; + + $obj = new Locale::Codes 'country'; + +=head1 OBJECT-ORIENTED METHODS + +The following methods are available. + +In all methods, when specifying a code set, the name (as a string) +is always available. + +Traditionally, you could also use a perl constant to specify the +code set. In order to do so with the OO interface, you have to +import the constants. To do that, load the module with: + + use Locale::Codes ':constants'; =over 4 -=item L<Locale::Codes::Country>, L<Locale::Country> +=item B<new ( [TYPE [,CODESET]] )> -This includes support for country codes (such as those listed in ISO-3166) -to specify the country. + $obj = new Locale::Codes; + $obj = new Locale::Codes 'country'; + $obj = new Locale::Codes 'country','alpha-3'; + $obj = new Locale::Codes 'country',LOCALE_COUNTRY_ALPHA_3; -Because this module was originally distributed as L<Locale::Country>, it is -also available under that name. +This creates a new object that can access the data. If no type is specified +(in the first argument), you must use the B<type> method described below. +No operations will work unless the type is specified. -=item L<Locale::Codes::Language>, L<Locale::Language> +The second argument is the default code set to use. This is optional, as +each type has a default code set. The default code set can be set using +the B<codeset> method below. -This includes support for language codes (such as those listed in ISO-639) -to specify the language. +The last example is only available if the constants were imported when +the module was loaded. -Because this module was originally distributed as L<Locale::Language>, it is -also available under that name. +=item B<show_errors ( FLAG )> -=item L<Locale::Codes::Currency>, L<Locale::Currency> + $obj->show_errors(1); + $obj->show_errors(0); -This includes support for currency codes (such as those listed in ISO-4217) -to specify the currency. +By default, error messages will be produced when bad data is passed +to any method. By passing in '0', these will be turned off so that +all failures will be silent. -Because this module was originally distributed as L<Locale::Currency>, it is -also available under that name. +=item B<type ( TYPE )> -=item L<Locale::Codes::Script>, L<Locale::Script> + $obj->type($type) -This includes support for script codes (such as those listed in ISO-15924) -to specify the script. +This will set the type of codes that will be worked with. C<$type> may +be any of the recognized types of code sets, including: -Because this module was originally distributed as L<Locale::Script>, it is -also available under that name. + country + language + currency + script + etc. -=item L<Locale::Codes::LangExt> +The list of valid types, and the code sets supported in each, are described +in the L<Locale::Codes::Types> document. -This includes support for language extension codes (such as those listed -in the IANA language registry) to specify the language extension. +This method can be called any number of times to toggle between different types +of code sets. -=item L<Locale::Codes::LangVar> +=item B<codeset ( CODESET )> -This includes support for language variation codes (such as those listed -in the IANA language registry) to specify the language variation. + $obj->codeset($codeset); -=item L<Locale::Codes::LangFam> +This sets the default code set to use. The list of code sets available +for each type are described in the L<Locale::Codes::Types> document. -This includes support for language family codes (such as those listed -in ISO 639-5) to specify families of languages. +In all other methods below, when an optional B<CODESET> argument is +omitted, it will default to this value. -=back +=item B<code2name ( CODE [,CODESET] [,'retired'] )> -Each module can support an arbitrary number of code sets, and it is -not required that the relationship between these code sets be -one-to-one. For example, the L<Locale::Codes::Country> module -supports code sets from ISO-3166 and the IANA standard, and those two -standards do not break the world down into exactly the same sets of -countries. This does not cause any problem (though converting codes -from ISO-3166 to IANA or back will not work except for countries that -are one-to-one). + $name = $obj->code2name($code [,$codeset] [,'retired']); -All data in all of these modules comes directly from the original -standards (or as close to direct as possible), so it should be -up-to-date at the time of release. +This functions take a code and returns a string which contains +the name of the element identified. If the code is not a valid +code in the B<CODESET> specified then C<undef> will be returned. -I plan on releasing a new version several times a year to incorporate -any changes made in the standards. However, I don't always know about -changes that occur, so if any of the standards change, and you want a -new release sooner, just email me and I'll get one out. +The name of the element is the name as specified in the standard, +and as a result, different variations of an element name may +be returned for different values of B<CODESET>. -In addition to the modules above, there are a number of support modules included -in the distribution including: +For example, the alpha-2 country code set defines the two-letter +code "bo" to be "Bolivia, Plurinational State of", whereas the +alpha-3 code set defines the code 'bol' to be the country "Bolivia +(Plurinational State of)". So: -=over 4 + $obj->code2name('bo','alpha-2'); + => 'Bolivia, Plurinational State of' + + $obj->code2name('bol','alpha-3'); + => 'Bolivia (Plurinational State of)' + +By default, only active codes will be used, but if the string +'retired' is passed in as an argument, both active and retired +codes will be examined. + +=item B<name2code ( NAME [,CODESET] [,'retired'] )> + + $code = $obj->name2code($name [,$codeset] [,'retired']); + +This function takes the name of an element (or any of it's aliases) +and returns the code that corresponds to it, if it exists. If B<NAME> +could not be identified as the name of one of the elements, then +C<undef> will be returned. + +The name is not case sensitive. Also, any known variation of a name +may be passed in. + +For example, even though the country name returned using 'alpha-2' +and 'alpha-3' country codes for Bolivia are different, either country +name may be passed in since for each code set (in addition to the more +common alias 'Bolivia'). So: + + $obj->name2code('Bolivia, Plurinational State of','alpha-2'); + => bo + + $obj->name2code('Bolivia (Plurinational State of)','alpha-2'); + => bo + + $obj->name2code('Bolivia','alpha-2'); + => bo + +By default, only active names will be used, but if the string +'retired' is passed in as an argument, both active and retired +names will be examined. + +=item B<code2code ( CODE [,CODESET] ,CODESET2 )> -=item B<Locale::Codes> + $code = $obj->code2code($code [,$codeset] ,$codeset2); -=item B<Locale::Codes::Constants> +This function takes a code from one code set (B<CODESET> or the +default code set), and returns the corresponding code from another +code set (B<CODESET2>). B<CODE> must exists in the code set specified +by B<CODESET> and must have a corresponding code in the +code set specified by B<CODESET2> or C<undef> will be returned. -=item B<Locale::Codes::Country_codes> + $obj->code2code('fin','alpha-3','alpha-2'); + => 'fi' -=item B<Locale::Codes::Language_codes> +Note that this function does NOT support retired codes. -=item B<Locale::Codes::Currency_codes> +=item B<all_codes ( [CODESET] [,'retired'] )> -=item B<Locale::Codes::Script_codes> + @code = $obj->all_codes([$codeset] [,'retired']); -=item B<Locale::Codes::LangExt_codes> +This returns a list of all code in the code set. The codes will be +sorted. -=item B<Locale::Codes::LangVar_codes> +By default, only active codes will be returned, but if the string +'retired' is passed in as an argument, both active and retired +codes will be returned. -=item B<Locale::Codes::LangFam_codes> +=item B<all_names ( [CODESET] [,'retired'] )> + + @name = $obj->all_names([$codeset] [,'retired']); + +This method returns a list of all elements names for which there is a +corresponding code in the specified code set. + +The names returned are exactly as they are specified in the standard, +and are sorted. + +Since not all elements are listed in all code sets, the list of +elements may differ depending on the code set specified. + +By default, only active names will be returned, but if the string +'retired' is passed in as an argument, both active and retired +names will be returned. =back -These modules are not intended to be used by programmers. They contain functions -or data that are used by the modules listed above. No support of any kind is -offered for using these modules directly. They may be modified at any time. +The following additional methods are available and can be used to +modify the code list data (and are therefore not generally useful). + +=over 4 + +=item B<rename_code ( CODE ,NEW_NAME [,CODESET] )> + + $flag = $obj->rename_code($code,$new_name [,$codeset]); + +This method can be used to change the official name of an element. At +that point, the name returned by the C<code2name> method would be +B<NEW_NAME> instead of the name specified in the standard. + +The original name will remain as an alias. + +For example, the official country name for code 'gb' is 'United +Kingdom'. If you want to change that, you might call: + + $obj->rename_code('gb', 'Great Britain'); + +This means that calling code2name('gb') will now return 'Great +Britain' instead of 'United Kingdom'. + +If any error occurs, a warning is issued and 0 is returned. An error +occurs if B<CODE> doesn't exist in the specified code set, or if +B<NEW_NAME> is already in use but for a different element. + +If the method succeeds, 1 is returned. + +=item B<add_code ( CODE ,NAME [,CODESET] )> + + $flag = $obj->add_code($code,$name [,$codeset]); + +This method is used to add a new code and name to the data. -=head1 NEW CODE SETS +Both B<CODE> and B<NAME> must be unused in the data set or an error +occurs (though B<NAME> may be used in a different data set). -I'm always open to suggestions for new code sets. +For example, to create the fictitious country named "Duchy of +Grand Fenwick" with codes "gf" and "fen", use the following: -In order for me to add a code set, I want the following criteria -to be met: + $obj->add_code("fe","Duchy of Grand Fenwick",'alpha-2'); + $obj->add_code("fen","Duchy of Grand Fenwick",'alpha-3'); + +The return value is 1 on success, 0 on an error. + +=item B<delete_code ( CODE [,CODESET] )> + + $flag = $obj->delete_code($code [,$codeset]); + +This method is used to delete a code from the data. + +B<CODE> must refer to an existing code in the code set. + +The return value is 1 on success, 0 on an error. + +=item B<add_alias ( NAME ,NEW_NAME )> + + $flag = $obj->add_alias($name,$new_name); + +This method is used to add a new alias to the data. They do +not alter the return value of the C<code2name> function. + +B<NAME> must be an existing element name, and B<NEW_NAME> must +be unused or an error occurs. + +The return value is 1 on success, 0 on an error. + +=item B<delete_alias ( NAME )> + + $flag = $obj->delete_alias($name); + +This method is used to delete an alias from the data. Once +removed, the element may not be referred to by B<NAME>. + +B<NAME> must be one of a list of at least two names that may be used to +specify an element. If the element may only be referred to by a single +name, you'll need to use the C<add_alias> method to add a new alias +first, or the C<remove_code> method to remove the element entirely. + +If the alias is used as the name in any code set, one of the other +names will be used instead. Predicting exactly which one will +be used requires you to know the order in which the standards +were read, which is not reliable, so you may want to use the +C<rename_code> method to force one of the alternate names to be +used. + +The return value is 1 on success, 0 on an error. + +=item B<replace_code ( CODE ,NEW_CODE [,CODESET] )> + + $flag = $obj->replace_code($code,$new_code [,$codeset]); + +This method is used to change the official code for an element. At +that point, the code returned by the C<name2code> method would be +B<NEW_CODE> instead of the code specified in the standard. + +B<NEW_CODE> may either be a code that is not in use, or it may be an +alias for B<CODE> (in which case, B<CODE> becomes and alias and B<NEW_CODE> +becomes the "real" code). + +The original code is kept as an alias, so that the C<code2name> routines +will work with either the code from the standard or the new code. + +However, the C<all_codes> method will only return the codes which +are considered "real" (which means that the list of codes will now +contain B<NEW_CODE>, but will not contain B<CODE>). + +=item B<add_code_alias ( CODE ,NEW_CODE [,CODESET] )> + + $flag = $obj->add_code_alias($code,$new_code [,$codeset]); + +This method adds an alias for the code. At that point, B<NEW_CODE> and B<CODE> +will both work in the C<code2name> method. However, the C<name2code> method will +still return the original code. + +=item B<delete_code_alias ( CODE [,CODESET] )> + +These routines delete an alias for the code. + +These will only work if B<CODE> is actually an alias. If it is the "real" +code, it will not be deleted. You will need to use the C<rename_code> +method to switch the real code with one of the aliases, and then +delete the alias. + +=back + +=head1 TRADITIONAL INTERFACES + +In addition the the primary OO module, the following modules are included in +the distribution for the traditional way of working with code sets. + +Each module will work with one specific type of code sets. =over 4 -=item B<General-use code set> +=item L<Locale::Codes::Country>, L<Locale::Country> -If a code set is not general use, I'm not likely to spend the time -to add and support it. +This includes support for country codes (such as those listed in ISO-3166) +to specify the country. -=item B<An official source of data> +Because this module was originally distributed as L<Locale::Country>, it is +also available under that name. -I require an official (or at least, a NEARLY official) source where I -can get the data on a regular basis. +=item L<Locale::Codes::Language>, L<Locale::Language> -Ideally, I'd only get data from an official source, but sometimes that -is not possible. For example the ISO standards are not typically -available for free, so I may have to get some of that data from -alternate sources that I'm confident are getting their data from the -official source. However, I will always be hesitant to accept a -non-official source. +This includes support for language codes (such as those listed in ISO-639) +to specify the language. -As an example, I used to get some country data from the CIA World -Factbook. Given the nature of the source, I'm sure they're updating -data from the official sources and I consider it "nearly" official. -However, even in this case, I found that they were adding codes that -were not part of the standard, so I have stopped using them as a -source. +Because this module was originally distributed as L<Locale::Language>, it is +also available under that name. -There are many 3rd party sites which maintain lists (many of which are -actually in a more convenient form than the official sites). -Unfortunately, I will reject most of them since I have no feel for how -"official" they are. +=item L<Locale::Codes::Currency>, L<Locale::Currency> -=item B<A free source of the data> +This includes support for currency codes (such as those listed in ISO-4217) +to specify the currency. + +Because this module was originally distributed as L<Locale::Currency>, it is +also available under that name. + +=item L<Locale::Codes::Script>, L<Locale::Script> + +This includes support for script codes (such as those listed in ISO-15924) +to specify the script. + +Because this module was originally distributed as L<Locale::Script>, it is +also available under that name. -Obviously, the data must be free-of-charge. I'm not interested in -paying for the data (and I'm not interested in the overhead of having -someone else pay for the data for me). +=item L<Locale::Codes::LangExt> -=item B<A reliable source of data> +This includes support for language extension codes (such as those listed +in the IANA language registry) to specify the language extension. -The source of data must come from a source that I can reasonably expect -to exist for the foreseeable future since I will be extremely reluctant -to drop support for a data set once it's included. +=item L<Locale::Codes::LangVar> + +This includes support for language variation codes (such as those listed +in the IANA language registry) to specify the language variation. + +=item L<Locale::Codes::LangFam> -I am also reluctant to accept data sent to me by an individual. -Although I appreciate the offer, it is simply not practical to consider -an individual contribution as a reliable source of data. The source -should be an official agency of some sort. +This includes support for language family codes (such as those listed +in ISO 639-5) to specify families of languages. =back -These requirements are open to discussion. If you have a code set -you'd like to see added, but which may not meet all of the above -requirements, feel free to email me and we'll discuss it. Depending -on circumstances, I may be willing to waive some of these criteria. +In addition to the modules above, there are a number of support modules included +in the distribution. Any module not listed above falls into that category. + +These modules are not intended to be used by programmers. They contain functions +or data that are used by the modules listed above. No support of any kind is +offered for using these modules directly. They may be modified at any time. =head1 COMMON ALIASES @@ -207,7 +464,7 @@ to 3.00, but it has been removed. Other aliases (if any) which no longer appear in any standard (and which are not common variations of the name in the standards) have also been removed. -=head1 DEPRECATED CODES +=head1 RETIRED CODES Occasionally, a code is deprecated, but it may still be desirable to have access to it. @@ -217,50 +474,44 @@ been deprecated (since most codesets do not have that information available), as of version 3.20, every code which has ever been included in these modules can be referenced. -For more information, refer to the documentation on the code2XXX, XXX2code, -all_XXX_codes, and all_XXX_names function in the L<Locale::Codes::API> -documentation. +For more information, refer to the documentation on the code2name, name2code, +all_codes, and all_names methods above. =head1 SEE ALSO =over 4 -=item L<Locale::Codes::API> - -The list of functions available in each of the modules listed below. -The APIs for each module are exactly identical. - -=item L<Locale::Codes::Country> - -Codes for identification of countries. - -=item L<Locale::Codes::Language> +=item L<Locale::Codes::Types> -Codes for identification of languages. +The list of all code sets available for each type. -=item L<Locale::Codes::Script> +=item L<Locale::Codes::Changes> -Codes for identification of scripts. +A history of changes made to this distribution. -=item L<Locale::Codes::Currency> +=back -Codes for identification of currencies and funds. +=head1 KNOWN BUGS AND LIMITATIONS -=item L<Locale::Codes::LangExt> +=over 4 -Codes for identification of language extensions. +=item B<Relationship between code sets> -=item L<Locale::Codes::LangVar> +Because each code set uses a slightly different list of elements, and +they are not necessarily one-to-one, there may be some confusion +about the relationship between codes from different code sets. -Codes for identification of language variations. +For example, ISO 3166 assigns one code to the country "United States +Minor Outlying Islands", but the IANA codes give different codes +to different islands (Baker Island, Howland Island, etc.). -=item L<Locale::Codes::LangFam> +This may cause some confusion... I've done the best that I could do +to minimize it. -Codes for identification of language families. +=item B<Non-ASCII characters not supported> -=item L<Locale::Codes::Changes> - -A history of changes made to this distribution. +Currently all names must be all ASCII. I plan on relaxing that +limitation in the future. =back @@ -292,9 +543,9 @@ L<https://github.com/SBECK-github/Locale-Codes> =back -Please do not use other means to report bugs (such as Usenet newsgroups, -or forums for a specific OS or Linux distribution) as it is impossible -for me to keep up with all of them. +Please do not use other means to report bugs (such as forums for a specific +OS or Linux distribution) as it is impossible for me to keep up with all of +them. When filing a bug report, please include the following information: @@ -305,7 +556,7 @@ When filing a bug report, please include the following information: Please include the version of Locale::Codes you are using. You can get this by using the script: - use Locale::Codes::Country; + use Locale::Codes; print $Locale::Codes::VERSION,"\n"; =back @@ -328,23 +579,20 @@ modified by Neil Bowers for inclusion in the distribution. From 2001 to 2004, maintenance was continued by Neil Bowers. He modified Locale::Currency for inclusion in the distribution. He also -added Locale::Constants and Locale::Script. +added Locale::Script. From 2004-2009, the module was unmaintained. In 2010, maintenance was taken over by Sullivan Beck ([email protected]) with Neil Bower's permission. All problems or comments should be -sent there. Alternately, problems can be reported using the -perl problem tracker at: - - L<https://rt.cpan.org/Dist/Display.html?Queue=Locale-Codes> +sent to him using any of the methods listed above. =head1 COPYRIGHT Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). Copyright (c) 2001 Michael Hennecke (Locale::Currency) Copyright (c) 2001-2010 Neil Bowers - Copyright (c) 2010-2016 Sullivan Beck + Copyright (c) 2010-2017 Sullivan Beck This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. diff --git a/cpan/Locale-Codes/lib/Locale/Codes/API.pod b/cpan/Locale-Codes/lib/Locale/Codes/API.pod deleted file mode 100644 index 8ad363e3bd..0000000000 --- a/cpan/Locale-Codes/lib/Locale/Codes/API.pod +++ /dev/null @@ -1,335 +0,0 @@ -=pod - -=head1 NAME - -Locale::Codes::API - a description of the callable function in each module - -=head1 DESCRIPTION - -Although there are several modules in the B<Locale-Codes> distribution, all of them -(as of version 3.10) use exactly the same API. As a matter of fact, each of the -main callable modules are just wrappers around a central module which does all -the real work. - -=head1 ROUTINES - -In order to maintain the documentation for the modules consistently, -the functions are all documented here, rather than in the documentation -for the separate modules. - -The name of the function depends on the module. For example, every module -contains a function C<code2XXX> where XXX refers to the type of data. -The values of XXX are described in the following table: - - XXX MODULE - - country Locale::Codes::Country - language Locale::Codes::Language - currency Locale::Codes::Currency - script Locale::Codes::Script - langext Locale::Codes::LangExt - langvar Locale::Codes::LangVar - langfam Locale::Codes::LangFam - -So, the L<Locale::Country> module contains the function C<code2country>, the -L<Locale::Language> module contains the function C<code2language>, etc. - -In all of the functions below, B<CODE> refers to a code for one -element in the code set. For example, in the two-letter country codes -from ISO 3166-1, the code 'fi' is used to refer to the country -Finland. B<CODE> is always case insensitive when passed in as an -argument, so 'fi', 'FI', and 'Fi' would all be equivalent arguments. -When B<CODE> is returned from an argument, it will always be in the -case as used in the standard. - -B<CODESET> refers to a constant specified in the documentation for each -module to label the various code sets. For example, in the -L<Locale::Language> module, B<CODESET> could be LOCALE_CODE_ALPHA_2 or -LOCALE_CODE_ALPHA_3 (among others). Most functions have a default one, -so they do not need to be specified. So the following calls are valid: - - code2country("fi"); - code2country("fi",LOCALE_CODE_ALPHA_2); - code2country("fin",LOCALE_CODE_ALPHA_3); - -Since LOCALE_CODE_ALPHA_2 is the default code set, the first two are -identical. - -=over 4 - -=item B<code2XXX ( CODE [,CODESET] [,'retired'] )> - -These functions take a code and returns a string which contains -the name of the element identified. If the code is not a valid -code in the B<CODESET> specified then C<undef> will be returned. - -The name of the element is the name as specified in the standard, -and as a result, different variations of an element name may -be returned for different values of B<CODESET>. - -For example, the alpha-2 country code set defines the two-letter -code "bo" to be "Bolivia, Plurinational State of", whereas the -alpha-3 code set defines the code 'bol' to be the country "Bolivia -(Plurinational State of)". So: - - code2country('bo',LOCALE_CODE_ALPHA_2); - => 'Bolivia, Plurinational State of' - - code2country('bol',LOCALE_CODE_ALPHA_3); - => 'Bolivia (Plurinational State of)' - -By default, only active codes will be used, but if the string -'retired' is passed in as an argument, both active and retired -codes will be examined. - -=item B<XXX2code ( NAME [,CODESET] [,'retired'] )> - -These functions takes the name of an element (or any of it's aliases) -and returns the code that corresponds to it, if it exists. If B<NAME> -could not be identified as the name of one of the elements, then -C<undef> will be returned. - -The name is not case sensitive. Also, any known variation of a name -may be passed in. - -For example, even though the country name returned using -LOCALE_CODE_ALPHA_2 and LOCALE_CODE_ALPHA_3 country codes for Bolivia -is different, either country name may be passed in since for each code -set (in addition to the alias 'Bolivia'). So: - - country2code('Bolivia, Plurinational State of', - LOCALE_CODE_ALPHA_2); - => bo - - country2code('Bolivia (Plurinational State of)', - LOCALE_CODE_ALPHA_2); - => bo - - country2code('Bolivia',LOCALE_CODE_ALPHA_2); - => bo - -By default, only active names will be used, but if the string -'retired' is passed in as an argument, both active and retired -names will be examined. - -=item B<XXX_code2code ( CODE ,CODESET ,CODESET2 )> - -These functions takes a code from one code set, and returns the -corresponding code from another code set. B<CODE> must exists in the code -set specified by B<CODESET> and must have a corresponding code in the -code set specified by B<CODESET2> or C<undef> will be returned. - -Both B<CODESET> and B<CODESET2> must be explicitly entered. - - country_code2code('fin', LOCALE_CODE_ALPHA_3, - LOCALE_CODE_ALPHA_2); - => 'fi' - -Note that this function does NOT support retired codes. - -=item B<all_XXX_codes ( [CODESET] [,'retired'] )> - -These returns a list of all code in the code set. The codes will be -sorted. - -By default, only active codes will be returned, but if the string -'retired' is passed in as an argument, both active and retired -codes will be returned. - -=item B<all_XXX_names ( [CODESET] [,'retired'] )> - -These return a list of all elements names for which there is a -corresponding code in the specified code set. - -The names returned are exactly as they are specified in the standard, -and are sorted. - -Since not all elements are listed in all code sets, the list of -elements may differ depending on the code set specified. - -By default, only active names will be returned, but if the string -'retired' is passed in as an argument, both active and retired -names will be returned. - -=back - -=head1 SEMI-PRIVATE ROUTINES - -Additional semi-private routines which may be used to modify the -internal data are also available. Given their status, they aren't -exported, and so need to be called by prefixing the function name with -the package name. - -These routines do not currently work with retired codes. - -=over 4 - -=item B<MODULE::rename_XXX ( CODE ,NEW_NAME [,CODESET] )> - -These routines are used to change the official name of an element. At -that point, the name returned by the C<code2XXX> routine would be -B<NEW_NAME> instead of the name specified in the standard. - -The original name will remain as an alias. - -For example, the official country name for code 'gb' is 'United -Kingdom'. If you want to change that, you might call: - - Locale::Codes::Country::rename_country('gb', 'Great Britain'); - -This means that calling code2country('gb') will now return 'Great -Britain' instead of 'United Kingdom'. - -If any error occurs, a warning is issued and 0 is returned. An error -occurs if B<CODE> doesn't exist in the specified code set, or if -B<NEW_NAME> is already in use but for a different element. - -If the routine succeeds, 1 is returned. - -=item B<MODULE::add_XXX ( CODE ,NAME [,CODESET] )> - -These routines are used to add a new code and name to the data. - -Both B<CODE> and B<NAME> must be unused in the data set or an error -occurs (though B<NAME> may be used in a different data set). - -For example, to create the fictitious country named "Duchy of -Grand Fenwick" with codes "gf" and "fen", use the following: - - Locale::Codes::Country::add_country("fe","Duchy of Grand Fenwick", - LOCALE_CODE_ALPHA_2); - - Locale::Codes::Country::add_country("fen","Duchy of Grand Fenwick", - LOCALE_CODE_ALPHA_3); - -The return value is 1 on success, 0 on an error. - -=item B<MODULE::delete_XXX ( CODE [,CODESET] )> - -These routines are used to delete a code from the data. - -B<CODE> must refer to an existing code in the code set. - -The return value is 1 on success, 0 on an error. - -=item B<MODULE::add_XXX_alias ( NAME ,NEW_NAME )> - -These routines are used to add a new alias to the data. They do -not alter the return value of the C<code2XXX> function. - -B<NAME> must be an existing element name, and B<NEW_NAME> must -be unused or an error occurs. - -The return value is 1 on success, 0 on an error. **** PATCH TRUNCATED AT 2000 LINES -- 87760 NOT SHOWN **** -- Perl5 Master Repository
