diff options
Diffstat (limited to 'systems/texlive/tlnet/tlpkg/tlperl/lib/Locale/Codes.pod')
-rw-r--r-- | systems/texlive/tlnet/tlpkg/tlperl/lib/Locale/Codes.pod | 600 |
1 files changed, 600 insertions, 0 deletions
diff --git a/systems/texlive/tlnet/tlpkg/tlperl/lib/Locale/Codes.pod b/systems/texlive/tlnet/tlpkg/tlperl/lib/Locale/Codes.pod new file mode 100644 index 0000000000..9049b667ba --- /dev/null +++ b/systems/texlive/tlnet/tlpkg/tlperl/lib/Locale/Codes.pod @@ -0,0 +1,600 @@ +=pod + +=head1 NAME + +Locale::Codes - a distribution of modules to handle locale codes + +=head1 DESCRIPTION + +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. + +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 B<new ( [TYPE [,CODESET]] )> + + $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; + +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. + +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. + +The last example is only available if the constants were imported when +the module was loaded. + +=item B<show_errors ( FLAG )> + + $obj->show_errors(1); + $obj->show_errors(0); + +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. + +=item B<type ( TYPE )> + + $obj->type($type) + +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: + + country + language + currency + script + etc. + +The list of valid types, and the code sets supported in each, are described +in the L<Locale::Codes::Types> document. + +This method can be called any number of times to toggle between different types +of code sets. + +=item B<codeset ( CODESET )> + + $obj->codeset($codeset); + +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. + +In all other methods below, when an optional B<CODESET> argument is +omitted, it will default to this value. + +=item B<code2name ( CODE [,CODESET] [,'retired'] )> + + $name = $obj->code2name($code [,$codeset] [,'retired']); + +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. + +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: + + $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 )> + + $code = $obj->code2code($code [,$codeset] ,$codeset2); + +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. + + $obj->code2code('fin','alpha-3','alpha-2'); + => 'fi' + +Note that this function does NOT support retired codes. + +=item B<all_codes ( [CODESET] [,'retired'] )> + + @code = $obj->all_codes([$codeset] [,'retired']); + +This 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_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 + +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. + +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: + + $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 L<Locale::Codes::Country>, L<Locale::Country> + +This includes support for country codes (such as those listed in ISO-3166) +to specify the country. + +Because this module was originally distributed as L<Locale::Country>, it is +also available under that name. + +=item L<Locale::Codes::Language>, L<Locale::Language> + +This includes support for language codes (such as those listed in ISO-639) +to specify the language. + +Because this module was originally distributed as L<Locale::Language>, it is +also available under that name. + +=item L<Locale::Codes::Currency>, L<Locale::Currency> + +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. + +=item L<Locale::Codes::LangExt> + +This includes support for language extension codes (such as those listed +in the IANA language registry) to specify the language extension. + +=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> + +This includes support for language family codes (such as those listed +in ISO 639-5) to specify families of languages. + +=back + +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 + +As of version 2.00, the modules supported common variants of names. + +For example, Locale::Country supports variant names for countries, and +a few of the most common ones are included in the data. The country +code for "United States" is "us", so: + + country2code('United States'); + => "us" + +Now the following will also return 'us': + + country2code('United States of America'); + country2code('USA'); + +Any number of common aliases may be included in the data, in addition +to the names that come directly from the standards. If you have a +common alias for a country, language, or any other of the types of +codes, let me know and I'll add it, with some restrictions. + +For example, the country name "North Korea" never appeared in any of +the official sources (instead, it was "Korea, North" or "Korea, +Democratic People's Republic of". I would honor a request to add an +alias "North Korea" since that's a very common way to specify the +country (please don't request this... I've already added it). + +On the other hand, a request to add Zaire as an alias for "Congo, The +Democratic Republic of" will not be honored. The country's official +name is no longer Zaire, so adding it as an alias violates the +standard. Zaire was kept as an alias in versions of this module prior +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 RETIRED CODES + +Occasionally, a code is deprecated, but it may still be desirable to +have access to it. + +Although there is no way to see every code that has ever existed and +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 code2name, name2code, +all_codes, and all_names methods above. + +=head1 SEE ALSO + +=over 4 + +=item L<Locale::Codes::Types> + +The list of all code sets available for each type. + +=item L<Locale::Codes::Changes> + +A history of changes made to this distribution. + +=back + +=head1 KNOWN BUGS AND LIMITATIONS + +=over 4 + +=item B<Relationship between code sets> + +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. + +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.). + +This may cause some confusion... I've done the best that I could do +to minimize it. + +=item B<Non-ASCII characters not supported> + +Currently all names must be all ASCII. I plan on relaxing that +limitation in the future. + +=back + +=head1 BUGS AND QUESTIONS + +If you find a bug in Locale::Codes, there are three ways to send it to me. +Any of them are fine, so use the method that is easiest for you. + +=over 4 + +=item Direct email + +You are welcome to send it directly to me by email. The email address +to use is: sbeck@cpan.org. + +=item CPAN Bug Tracking + +You can submit it using the CPAN tracking too. This can be done at the +following URL: + +L<http://rt.cpan.org/Public/Dist/Display.html?Name=Locale-Codes> + +=item GitHub + +You can submit it as an issue on GitHub. This can be done at the following +URL: + +L<https://github.com/SBECK-github/Locale-Codes> + +=back + +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: + +=over 4 + +=item B<Locale::Codes version> + +Please include the version of Locale::Codes you are using. You can get +this by using the script: + + use Locale::Codes; + print $Locale::Codes::VERSION,"\n"; + +=back + +If you want to report missing or incorrect codes, you must be running the +most recent version of Locale::Codes. + +If you find any problems with the documentation (errors, typos, or items +that are not clear), please send them to me. I welcome any suggestions +that will allow me to improve the documentation. + +=head1 AUTHOR + +Locale::Country and Locale::Language were originally written by Neil +Bowers at the Canon Research Centre Europe (CRE). They maintained the +distribution from 1997 to 2001. + +Locale::Currency was originally written by Michael Hennecke and was +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::Script. + +From 2004-2009, the module was unmaintained. + +In 2010, maintenance was taken over by Sullivan Beck (sbeck@cpan.org) +with Neil Bower's permission. All problems or comments should be +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-2018 Sullivan Beck + +This module is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. + +=cut |