|
Packit |
f3e6b9 |
NAME
|
|
Packit |
f3e6b9 |
Locale::Codes - a distribution of modules to handle locale codes
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
DESCRIPTION
|
|
Packit |
f3e6b9 |
Locale-Codes is a distribution containing a set of modules designed to
|
|
Packit |
f3e6b9 |
work with sets of codes which uniquely identify something. For example,
|
|
Packit |
f3e6b9 |
there are codes associated with different countries, different
|
|
Packit |
f3e6b9 |
currencies, different languages, etc. These sets of codes are typically
|
|
Packit |
f3e6b9 |
maintained in some standard.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This distribution provides a way to work with these lists of codes.
|
|
Packit |
f3e6b9 |
Because the data from the various standards is not available in any sort
|
|
Packit |
f3e6b9 |
of consistent API, access to the lists is not available in any direct
|
|
Packit |
f3e6b9 |
fashion. To compensate for this, the list of codes is stored internally
|
|
Packit |
f3e6b9 |
within this distribution, and the distribution is updated on a regular
|
|
Packit |
f3e6b9 |
basis to include all known codes at that point in time. This does mean
|
|
Packit |
f3e6b9 |
that it is necessary to keep this distribution up-to-date to keep up
|
|
Packit |
f3e6b9 |
with the various changes that are made in the various standards.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Traditionally, a module has been created to work with each type of code
|
|
Packit |
f3e6b9 |
sets. So, there is a module for working with country lists, one for
|
|
Packit |
f3e6b9 |
currency lists, etc. Since version 3.00, all of these individual modules
|
|
Packit |
f3e6b9 |
were written as wrappers around a central module (which was not intended
|
|
Packit |
f3e6b9 |
to be used directly) which did all of the real work.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Starting with version 3.50, the central module was reworked slightly to
|
|
Packit |
f3e6b9 |
provide an object-oriented interface. All of the modules for working
|
|
Packit |
f3e6b9 |
with individual types of code sets were reworked to use the improved OO
|
|
Packit |
f3e6b9 |
module, so the traditional interfaces still work as they always have. As
|
|
Packit |
f3e6b9 |
a result, you are free to use the traditional functional (non-OO)
|
|
Packit |
f3e6b9 |
interfaces, or to use the OO interface and bypass the wrapper modules
|
|
Packit |
f3e6b9 |
entirely.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Both methods will be supported in the future, so use the one that is
|
|
Packit |
f3e6b9 |
best suited to your needs.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Within each type, any number of code sets are allowed. For example, sets
|
|
Packit |
f3e6b9 |
of country codes are maintained in several different locations including
|
|
Packit |
f3e6b9 |
the ISO-3166 standard, the IANA, and by the United Nations. The lists of
|
|
Packit |
f3e6b9 |
countries are similar, but not identical. Multiple code sets are
|
|
Packit |
f3e6b9 |
supported, though trying to convert from one code set to another will
|
|
Packit |
f3e6b9 |
not always work since the list of countries is not one-to-one.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
All data in all of these modules comes directly from the original
|
|
Packit |
f3e6b9 |
standards (or as close to direct as possible), so it should be
|
|
Packit |
f3e6b9 |
up-to-date at the time of release.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
I plan on releasing a new version several times a year to incorporate
|
|
Packit |
f3e6b9 |
any changes made in the standards. However, I don't always know about
|
|
Packit |
f3e6b9 |
changes that occur, so if any of the standards change, and you want a
|
|
Packit |
f3e6b9 |
new release sooner, just email me and I'll get one out.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
SYNOPSIS (OBJECT-ORIENTED INTERFACE)
|
|
Packit |
f3e6b9 |
use Locale::Codes;
|
|
Packit |
f3e6b9 |
or
|
|
Packit |
f3e6b9 |
use Locale::Codes ':constants';
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
$obj = new Locale::Codes 'country';
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
OBJECT-ORIENTED METHODS
|
|
Packit |
f3e6b9 |
The following methods are available.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
In all methods, when specifying a code set, the name (as a string) is
|
|
Packit |
f3e6b9 |
always available.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Traditionally, you could also use a perl constant to specify the code
|
|
Packit |
f3e6b9 |
set. In order to do so with the OO interface, you have to import the
|
|
Packit |
f3e6b9 |
constants. To do that, load the module with:
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
use Locale::Codes ':constants';
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
new ( [TYPE [,CODESET]] )
|
|
Packit |
f3e6b9 |
$obj = new Locale::Codes;
|
|
Packit |
f3e6b9 |
$obj = new Locale::Codes 'country';
|
|
Packit |
f3e6b9 |
$obj = new Locale::Codes 'country','alpha-3';
|
|
Packit |
f3e6b9 |
$obj = new Locale::Codes 'country',LOCALE_COUNTRY_ALPHA_3;
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This creates a new object that can access the data. If no type is
|
|
Packit |
f3e6b9 |
specified (in the first argument), you must use the type method
|
|
Packit |
f3e6b9 |
described below. No operations will work unless the type is
|
|
Packit |
f3e6b9 |
specified.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
The second argument is the default code set to use. This is
|
|
Packit |
f3e6b9 |
optional, as each type has a default code set. The default code set
|
|
Packit |
f3e6b9 |
can be set using the codeset method below.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
The last example is only available if the constants were imported
|
|
Packit |
f3e6b9 |
when the module was loaded.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
show_errors ( FLAG )
|
|
Packit |
f3e6b9 |
$obj->show_errors(1);
|
|
Packit |
f3e6b9 |
$obj->show_errors(0);
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
By default, error messages will be produced when bad data is passed
|
|
Packit |
f3e6b9 |
to any method. By passing in '0', these will be turned off so that
|
|
Packit |
f3e6b9 |
all failures will be silent.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
type ( TYPE )
|
|
Packit |
f3e6b9 |
$obj->type($type)
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This will set the type of codes that will be worked with. $type may
|
|
Packit |
f3e6b9 |
be any of the recognized types of code sets, including:
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
country
|
|
Packit |
f3e6b9 |
language
|
|
Packit |
f3e6b9 |
currency
|
|
Packit |
f3e6b9 |
script
|
|
Packit |
f3e6b9 |
etc.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
The list of valid types, and the code sets supported in each, are
|
|
Packit |
f3e6b9 |
described in the Locale::Codes::Types document.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This method can be called any number of times to toggle between
|
|
Packit |
f3e6b9 |
different types of code sets.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
codeset ( CODESET )
|
|
Packit |
f3e6b9 |
$obj->codeset($codeset);
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This sets the default code set to use. The list of code sets
|
|
Packit |
f3e6b9 |
available for each type are described in the Locale::Codes::Types
|
|
Packit |
f3e6b9 |
document.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
In all other methods below, when an optional CODESET argument is
|
|
Packit |
f3e6b9 |
omitted, it will default to this value.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
code2name ( CODE [,CODESET] [,'retired'] )
|
|
Packit |
f3e6b9 |
$name = $obj->code2name($code [,$codeset] [,'retired']);
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This functions take a code and returns a string which contains the
|
|
Packit |
f3e6b9 |
name of the element identified. If the code is not a valid code in
|
|
Packit |
f3e6b9 |
the CODESET specified then "undef" will be returned.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
The name of the element is the name as specified in the standard,
|
|
Packit |
f3e6b9 |
and as a result, different variations of an element name may be
|
|
Packit |
f3e6b9 |
returned for different values of CODESET.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
For example, the alpha-2 country code set defines the two-letter
|
|
Packit |
f3e6b9 |
code "bo" to be "Bolivia, Plurinational State of", whereas the
|
|
Packit |
f3e6b9 |
alpha-3 code set defines the code 'bol' to be the country "Bolivia
|
|
Packit |
f3e6b9 |
(Plurinational State of)". So:
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
$obj->code2name('bo','alpha-2');
|
|
Packit |
f3e6b9 |
=> 'Bolivia, Plurinational State of'
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
$obj->code2name('bol','alpha-3');
|
|
Packit |
f3e6b9 |
=> 'Bolivia (Plurinational State of)'
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
By default, only active codes will be used, but if the string
|
|
Packit |
f3e6b9 |
'retired' is passed in as an argument, both active and retired codes
|
|
Packit |
f3e6b9 |
will be examined.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
name2code ( NAME [,CODESET] [,'retired'] )
|
|
Packit |
f3e6b9 |
$code = $obj->name2code($name [,$codeset] [,'retired']);
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This function takes the name of an element (or any of it's aliases)
|
|
Packit |
f3e6b9 |
and returns the code that corresponds to it, if it exists. If NAME
|
|
Packit |
f3e6b9 |
could not be identified as the name of one of the elements, then
|
|
Packit |
f3e6b9 |
"undef" will be returned.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
The name is not case sensitive. Also, any known variation of a name
|
|
Packit |
f3e6b9 |
may be passed in.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
For example, even though the country name returned using 'alpha-2'
|
|
Packit |
f3e6b9 |
and 'alpha-3' country codes for Bolivia are different, either
|
|
Packit |
f3e6b9 |
country name may be passed in since for each code set (in addition
|
|
Packit |
f3e6b9 |
to the more common alias 'Bolivia'). So:
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
$obj->name2code('Bolivia, Plurinational State of','alpha-2');
|
|
Packit |
f3e6b9 |
=> bo
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
$obj->name2code('Bolivia (Plurinational State of)','alpha-2');
|
|
Packit |
f3e6b9 |
=> bo
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
$obj->name2code('Bolivia','alpha-2');
|
|
Packit |
f3e6b9 |
=> bo
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
By default, only active names will be used, but if the string
|
|
Packit |
f3e6b9 |
'retired' is passed in as an argument, both active and retired names
|
|
Packit |
f3e6b9 |
will be examined.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
code2code ( CODE [,CODESET] ,CODESET2 )
|
|
Packit |
f3e6b9 |
$code = $obj->code2code($code [,$codeset] ,$codeset2);
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This function takes a code from one code set (CODESET or the default
|
|
Packit |
f3e6b9 |
code set), and returns the corresponding code from another code set
|
|
Packit |
f3e6b9 |
(CODESET2). CODE must exists in the code set specified by CODESET
|
|
Packit |
f3e6b9 |
and must have a corresponding code in the code set specified by
|
|
Packit |
f3e6b9 |
CODESET2 or "undef" will be returned.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
$obj->code2code('fin','alpha-3','alpha-2');
|
|
Packit |
f3e6b9 |
=> 'fi'
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Note that this function does NOT support retired codes.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
all_codes ( [CODESET] [,'retired'] )
|
|
Packit |
f3e6b9 |
@code = $obj->all_codes([$codeset] [,'retired']);
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This returns a list of all code in the code set. The codes will be
|
|
Packit |
f3e6b9 |
sorted.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
By default, only active codes will be returned, but if the string
|
|
Packit |
f3e6b9 |
'retired' is passed in as an argument, both active and retired codes
|
|
Packit |
f3e6b9 |
will be returned.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
all_names ( [CODESET] [,'retired'] )
|
|
Packit |
f3e6b9 |
@name = $obj->all_names([$codeset] [,'retired']);
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This method returns a list of all elements names for which there is
|
|
Packit |
f3e6b9 |
a corresponding code in the specified code set.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
The names returned are exactly as they are specified in the
|
|
Packit |
f3e6b9 |
standard, and are sorted.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Since not all elements are listed in all code sets, the list of
|
|
Packit |
f3e6b9 |
elements may differ depending on the code set specified.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
By default, only active names will be returned, but if the string
|
|
Packit |
f3e6b9 |
'retired' is passed in as an argument, both active and retired names
|
|
Packit |
f3e6b9 |
will be returned.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
The following additional methods are available and can be used to modify
|
|
Packit |
f3e6b9 |
the code list data (and are therefore not generally useful).
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
rename_code ( CODE ,NEW_NAME [,CODESET] )
|
|
Packit |
f3e6b9 |
$flag = $obj->rename_code($code,$new_name [,$codeset]);
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This method can be used to change the official name of an element.
|
|
Packit |
f3e6b9 |
At that point, the name returned by the "code2name" method would be
|
|
Packit |
f3e6b9 |
NEW_NAME instead of the name specified in the standard.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
The original name will remain as an alias.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
For example, the official country name for code 'gb' is 'United
|
|
Packit |
f3e6b9 |
Kingdom'. If you want to change that, you might call:
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
$obj->rename_code('gb', 'Great Britain');
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This means that calling code2name('gb') will now return 'Great
|
|
Packit |
f3e6b9 |
Britain' instead of 'United Kingdom'.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
If any error occurs, a warning is issued and 0 is returned. An error
|
|
Packit |
f3e6b9 |
occurs if CODE doesn't exist in the specified code set, or if
|
|
Packit |
f3e6b9 |
NEW_NAME is already in use but for a different element.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
If the method succeeds, 1 is returned.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
add_code ( CODE ,NAME [,CODESET] )
|
|
Packit |
f3e6b9 |
$flag = $obj->add_code($code,$name [,$codeset]);
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This method is used to add a new code and name to the data.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Both CODE and NAME must be unused in the data set or an error occurs
|
|
Packit |
f3e6b9 |
(though NAME may be used in a different data set).
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
For example, to create the fictitious country named "Duchy of Grand
|
|
Packit |
f3e6b9 |
Fenwick" with codes "gf" and "fen", use the following:
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
$obj->add_code("fe","Duchy of Grand Fenwick",'alpha-2');
|
|
Packit |
f3e6b9 |
$obj->add_code("fen","Duchy of Grand Fenwick",'alpha-3');
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
The return value is 1 on success, 0 on an error.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
delete_code ( CODE [,CODESET] )
|
|
Packit |
f3e6b9 |
$flag = $obj->delete_code($code [,$codeset]);
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This method is used to delete a code from the data.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
CODE must refer to an existing code in the code set.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
The return value is 1 on success, 0 on an error.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
add_alias ( NAME ,NEW_NAME )
|
|
Packit |
f3e6b9 |
$flag = $obj->add_alias($name,$new_name);
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This method is used to add a new alias to the data. They do not
|
|
Packit |
f3e6b9 |
alter the return value of the "code2name" function.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
NAME must be an existing element name, and NEW_NAME must be unused
|
|
Packit |
f3e6b9 |
or an error occurs.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
The return value is 1 on success, 0 on an error.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
delete_alias ( NAME )
|
|
Packit |
f3e6b9 |
$flag = $obj->delete_alias($name);
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This method is used to delete an alias from the data. Once removed,
|
|
Packit |
f3e6b9 |
the element may not be referred to by NAME.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
NAME must be one of a list of at least two names that may be used to
|
|
Packit |
f3e6b9 |
specify an element. If the element may only be referred to by a
|
|
Packit |
f3e6b9 |
single name, you'll need to use the "add_alias" method to add a new
|
|
Packit |
f3e6b9 |
alias first, or the "remove_code" method to remove the element
|
|
Packit |
f3e6b9 |
entirely.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
If the alias is used as the name in any code set, one of the other
|
|
Packit |
f3e6b9 |
names will be used instead. Predicting exactly which one will be
|
|
Packit |
f3e6b9 |
used requires you to know the order in which the standards were
|
|
Packit |
f3e6b9 |
read, which is not reliable, so you may want to use the
|
|
Packit |
f3e6b9 |
"rename_code" method to force one of the alternate names to be used.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
The return value is 1 on success, 0 on an error.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
replace_code ( CODE ,NEW_CODE [,CODESET] )
|
|
Packit |
f3e6b9 |
$flag = $obj->replace_code($code,$new_code [,$codeset]);
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This method is used to change the official code for an element. At
|
|
Packit |
f3e6b9 |
that point, the code returned by the "name2code" method would be
|
|
Packit |
f3e6b9 |
NEW_CODE instead of the code specified in the standard.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
NEW_CODE may either be a code that is not in use, or it may be an
|
|
Packit |
f3e6b9 |
alias for CODE (in which case, CODE becomes and alias and NEW_CODE
|
|
Packit |
f3e6b9 |
becomes the "real" code).
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
The original code is kept as an alias, so that the "code2name"
|
|
Packit |
f3e6b9 |
routines will work with either the code from the standard or the new
|
|
Packit |
f3e6b9 |
code.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
However, the "all_codes" method will only return the codes which are
|
|
Packit |
f3e6b9 |
considered "real" (which means that the list of codes will now
|
|
Packit |
f3e6b9 |
contain NEW_CODE, but will not contain CODE).
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
add_code_alias ( CODE ,NEW_CODE [,CODESET] )
|
|
Packit |
f3e6b9 |
$flag = $obj->add_code_alias($code,$new_code [,$codeset]);
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This method adds an alias for the code. At that point, NEW_CODE and
|
|
Packit |
f3e6b9 |
CODE will both work in the "code2name" method. However, the
|
|
Packit |
f3e6b9 |
"name2code" method will still return the original code.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
delete_code_alias ( CODE [,CODESET] )
|
|
Packit |
f3e6b9 |
These routines delete an alias for the code.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
These will only work if CODE is actually an alias. If it is the
|
|
Packit |
f3e6b9 |
"real" code, it will not be deleted. You will need to use the
|
|
Packit |
f3e6b9 |
"rename_code" method to switch the real code with one of the
|
|
Packit |
f3e6b9 |
aliases, and then delete the alias.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
TRADITIONAL INTERFACES
|
|
Packit |
f3e6b9 |
In addition the the primary OO module, the following modules are
|
|
Packit |
f3e6b9 |
included in the distribution for the traditional way of working with
|
|
Packit |
f3e6b9 |
code sets.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Each module will work with one specific type of code sets.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Locale::Codes::Country, Locale::Country
|
|
Packit |
f3e6b9 |
This includes support for country codes (such as those listed in
|
|
Packit |
f3e6b9 |
ISO-3166) to specify the country.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Because this module was originally distributed as Locale::Country,
|
|
Packit |
f3e6b9 |
it is also available under that name.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Locale::Codes::Language, Locale::Language
|
|
Packit |
f3e6b9 |
This includes support for language codes (such as those listed in
|
|
Packit |
f3e6b9 |
ISO-639) to specify the language.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Because this module was originally distributed as Locale::Language,
|
|
Packit |
f3e6b9 |
it is also available under that name.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Locale::Codes::Currency, Locale::Currency
|
|
Packit |
f3e6b9 |
This includes support for currency codes (such as those listed in
|
|
Packit |
f3e6b9 |
ISO-4217) to specify the currency.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Because this module was originally distributed as Locale::Currency,
|
|
Packit |
f3e6b9 |
it is also available under that name.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Locale::Codes::Script, Locale::Script
|
|
Packit |
f3e6b9 |
This includes support for script codes (such as those listed in
|
|
Packit |
f3e6b9 |
ISO-15924) to specify the script.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Because this module was originally distributed as Locale::Script, it
|
|
Packit |
f3e6b9 |
is also available under that name.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Locale::Codes::LangExt
|
|
Packit |
f3e6b9 |
This includes support for language extension codes (such as those
|
|
Packit |
f3e6b9 |
listed in the IANA language registry) to specify the language
|
|
Packit |
f3e6b9 |
extension.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Locale::Codes::LangVar
|
|
Packit |
f3e6b9 |
This includes support for language variation codes (such as those
|
|
Packit |
f3e6b9 |
listed in the IANA language registry) to specify the language
|
|
Packit |
f3e6b9 |
variation.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Locale::Codes::LangFam
|
|
Packit |
f3e6b9 |
This includes support for language family codes (such as those
|
|
Packit |
f3e6b9 |
listed in ISO 639-5) to specify families of languages.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
In addition to the modules above, there are a number of support modules
|
|
Packit |
f3e6b9 |
included in the distribution. Any module not listed above falls into
|
|
Packit |
f3e6b9 |
that category.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
These modules are not intended to be used by programmers. They contain
|
|
Packit |
f3e6b9 |
functions or data that are used by the modules listed above. No support
|
|
Packit |
f3e6b9 |
of any kind is offered for using these modules directly. They may be
|
|
Packit |
f3e6b9 |
modified at any time.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
COMMON ALIASES
|
|
Packit |
f3e6b9 |
As of version 2.00, the modules supported common variants of names.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
For example, Locale::Country supports variant names for countries, and a
|
|
Packit |
f3e6b9 |
few of the most common ones are included in the data. The country code
|
|
Packit |
f3e6b9 |
for "United States" is "us", so:
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
country2code('United States');
|
|
Packit |
f3e6b9 |
=> "us"
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Now the following will also return 'us':
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
country2code('United States of America');
|
|
Packit |
f3e6b9 |
country2code('USA');
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Any number of common aliases may be included in the data, in addition to
|
|
Packit |
f3e6b9 |
the names that come directly from the standards. If you have a common
|
|
Packit |
f3e6b9 |
alias for a country, language, or any other of the types of codes, let
|
|
Packit |
f3e6b9 |
me know and I'll add it, with some restrictions.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
For example, the country name "North Korea" never appeared in any of the
|
|
Packit |
f3e6b9 |
official sources (instead, it was "Korea, North" or "Korea, Democratic
|
|
Packit |
f3e6b9 |
People's Republic of". I would honor a request to add an alias "North
|
|
Packit |
f3e6b9 |
Korea" since that's a very common way to specify the country (please
|
|
Packit |
f3e6b9 |
don't request this... I've already added it).
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
On the other hand, a request to add Zaire as an alias for "Congo, The
|
|
Packit |
f3e6b9 |
Democratic Republic of" will not be honored. The country's official name
|
|
Packit |
f3e6b9 |
is no longer Zaire, so adding it as an alias violates the standard.
|
|
Packit |
f3e6b9 |
Zaire was kept as an alias in versions of this module prior to 3.00, but
|
|
Packit |
f3e6b9 |
it has been removed. Other aliases (if any) which no longer appear in
|
|
Packit |
f3e6b9 |
any standard (and which are not common variations of the name in the
|
|
Packit |
f3e6b9 |
standards) have also been removed.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
RETIRED CODES
|
|
Packit |
f3e6b9 |
Occasionally, a code is deprecated, but it may still be desirable to
|
|
Packit |
f3e6b9 |
have access to it.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Although there is no way to see every code that has ever existed and
|
|
Packit |
f3e6b9 |
been deprecated (since most codesets do not have that information
|
|
Packit |
f3e6b9 |
available), as of version 3.20, every code which has ever been included
|
|
Packit |
f3e6b9 |
in these modules can be referenced.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
For more information, refer to the documentation on the code2name,
|
|
Packit |
f3e6b9 |
name2code, all_codes, and all_names methods above.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
SEE ALSO
|
|
Packit |
f3e6b9 |
Locale::Codes::Types
|
|
Packit |
f3e6b9 |
The list of all code sets available for each type.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Locale::Codes::Changes
|
|
Packit |
f3e6b9 |
A history of changes made to this distribution.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
KNOWN BUGS AND LIMITATIONS
|
|
Packit |
f3e6b9 |
Relationship between code sets
|
|
Packit |
f3e6b9 |
Because each code set uses a slightly different list of elements,
|
|
Packit |
f3e6b9 |
and they are not necessarily one-to-one, there may be some confusion
|
|
Packit |
f3e6b9 |
about the relationship between codes from different code sets.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
For example, ISO 3166 assigns one code to the country "United States
|
|
Packit |
f3e6b9 |
Minor Outlying Islands", but the IANA codes give different codes to
|
|
Packit |
f3e6b9 |
different islands (Baker Island, Howland Island, etc.).
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This may cause some confusion... I've done the best that I could do
|
|
Packit |
f3e6b9 |
to minimize it.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Non-ASCII characters not supported
|
|
Packit |
f3e6b9 |
Currently all names must be all ASCII. I plan on relaxing that
|
|
Packit |
f3e6b9 |
limitation in the future.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
BUGS AND QUESTIONS
|
|
Packit |
f3e6b9 |
If you find a bug in Locale::Codes, there are three ways to send it to
|
|
Packit |
f3e6b9 |
me. Any of them are fine, so use the method that is easiest for you.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Direct email
|
|
Packit |
f3e6b9 |
You are welcome to send it directly to me by email. The email
|
|
Packit |
f3e6b9 |
address to use is: sbeck@cpan.org.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
CPAN Bug Tracking
|
|
Packit |
f3e6b9 |
You can submit it using the CPAN tracking too. This can be done at
|
|
Packit |
f3e6b9 |
the following URL:
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
<http://rt.cpan.org/Public/Dist/Display.html?Name=Locale-Codes>
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
GitHub
|
|
Packit |
f3e6b9 |
You can submit it as an issue on GitHub. This can be done at the
|
|
Packit |
f3e6b9 |
following URL:
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
<https://github.com/SBECK-github/Locale-Codes>
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Please do not use other means to report bugs (such as forums for a
|
|
Packit |
f3e6b9 |
specific OS or Linux distribution) as it is impossible for me to keep up
|
|
Packit |
f3e6b9 |
with all of them.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
When filing a bug report, please include the following information:
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Locale::Codes version
|
|
Packit |
f3e6b9 |
Please include the version of Locale::Codes you are using. You can
|
|
Packit |
f3e6b9 |
get this by using the script:
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
use Locale::Codes;
|
|
Packit |
f3e6b9 |
print $Locale::Codes::VERSION,"\n";
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
If you want to report missing or incorrect codes, you must be running
|
|
Packit |
f3e6b9 |
the most recent version of Locale::Codes.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
If you find any problems with the documentation (errors, typos, or items
|
|
Packit |
f3e6b9 |
that are not clear), please send them to me. I welcome any suggestions
|
|
Packit |
f3e6b9 |
that will allow me to improve the documentation.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
AUTHOR
|
|
Packit |
f3e6b9 |
Locale::Country and Locale::Language were originally written by Neil
|
|
Packit |
f3e6b9 |
Bowers at the Canon Research Centre Europe (CRE). They maintained the
|
|
Packit |
f3e6b9 |
distribution from 1997 to 2001.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
Locale::Currency was originally written by Michael Hennecke and was
|
|
Packit |
f3e6b9 |
modified by Neil Bowers for inclusion in the distribution.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
From 2001 to 2004, maintenance was continued by Neil Bowers. He modified
|
|
Packit |
f3e6b9 |
Locale::Currency for inclusion in the distribution. He also added
|
|
Packit |
f3e6b9 |
Locale::Script.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
From 2004-2009, the module was unmaintained.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
In 2010, maintenance was taken over by Sullivan Beck (sbeck@cpan.org)
|
|
Packit |
f3e6b9 |
with Neil Bower's permission. All problems or comments should be sent to
|
|
Packit |
f3e6b9 |
him using any of the methods listed above.
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
COPYRIGHT
|
|
Packit |
f3e6b9 |
Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
|
|
Packit |
f3e6b9 |
Copyright (c) 2001 Michael Hennecke (Locale::Currency)
|
|
Packit |
f3e6b9 |
Copyright (c) 2001-2010 Neil Bowers
|
|
Packit |
f3e6b9 |
Copyright (c) 2010-2018 Sullivan Beck
|
|
Packit |
f3e6b9 |
|
|
Packit |
f3e6b9 |
This module is free software; you can redistribute it and/or modify it
|
|
Packit |
f3e6b9 |
under the same terms as Perl itself.
|
|
Packit |
f3e6b9 |
|