summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Locale/Codes.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Locale/Codes.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Locale/Codes.pod600
1 files changed, 0 insertions, 600 deletions
diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes.pod b/Master/tlpkg/tlperl/lib/Locale/Codes.pod
deleted file mode 100644
index 9049b667ba6..00000000000
--- a/Master/tlpkg/tlperl/lib/Locale/Codes.pod
+++ /dev/null
@@ -1,600 +0,0 @@
-=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