path: root/Master/tlpkg/tlperl/lib/Locale/Codes/API.pod

=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.

=item B<MODULE::delete_XXX_alias  ( NAME )>

These routines are 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_XXX_alias> function to add a new alias
first, or the C<remove_XXX> function 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_XXX> function to force one of the alternate names to be
used.

The return value is 1 on success, 0 on an error.

=item B<MODULE::rename_XXX_code  ( CODE ,NEW_CODE [,CODESET] )>

These routines are used to change the official code for an element. At
that point, the code returned by the C<XXX2code> routine 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<code2XXX> routines
will work with either the code from the standard or the new code.

However, the C<all_XXX_codes> routine 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<MODULE::add_XXX_code_alias  ( CODE ,NEW_CODE [,CODESET] )>

These routines add an alias for the code. At that point, B<NEW_CODE> and B<CODE>
will both work in the C<code2XXX> routines. However, the C<XXX2code> routines will
still return the original code.

=item B<MODULE::delete_XXX_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_XXX_code>
function to switch the real code with one of the aliases, and then
delete the alias.

=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 SEE ALSO

L<Locale::Codes>

L<Locale::Codes::Country>

L<Locale::Codes::Language>

L<Locale::Codes::Currency>

L<Locale::Codes::Script>

L<Locale::Codes::LangExt>

L<Locale::Codes::LangVar>

L<Locale::Codes::LangFam>

=head1 AUTHOR

See Locale::Codes for full author history.

Currently maintained by Sullivan Beck (sbeck@cpan.org).

=head1 COPYRIGHT

   Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
   Copyright (c) 2001-2010 Neil Bowers
   Copyright (c) 2010-2015 Sullivan Beck

This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=cut