=head1 DESCRIPTION
-Although there are several modules in the Locale-Codes distribution, all of them
+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.
for the separate modules.
The name of the function depends on the module. For example, every module
-contains a function "code2XXX" where XXX refers to the type of data.
+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
script Locale::Codes::Script
langext Locale::Codes::LangExt
langvar Locale::Codes::LangVar
- langfam Locale::Codes::LangFAM
+ langfam Locale::Codes::LangFam
-So, the Locale::Country module contains the function code2country, the
-Locale::Language module contains the function code2language, etc.
+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, 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. CODE is always
-case insensitive (though when a code is returned, it will always be in
-the case as used in the standard), so 'fi', 'FI', and 'Fi' would all
-be equivalent.
+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.
-CODESET refers to a constant specified in the documentation for each
+B<CODESET> refers to a constant specified in the documentation for each
module to label the various code sets. For example, in the
-Locale::Language module, CODESET could be LOCALE_CODE_ALPHA_2 or
+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:
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 CODESET specified then C<undef> will be returned.
+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 CODESET.
+be returned for different values of B<CODESET>.
-For example, the B<alpha-2> country code set defines the two-letter
+For example, the alpha-2 country code set defines the two-letter
code "bo" to be "Bolivia, Plurinational State of", whereas the
-B<alpha-3> code set defines the code 'bol' to be the country "Bolivia
+alpha-3 code set defines the code 'bol' to be the country "Bolivia
(Plurinational State of)". So:
code2country('bo',LOCALE_CODE_ALPHA_2);
=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 NAME
+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.
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:
+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);
=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. CODE must exists in the code
-set specified by CODESET and must have a corresponding code in the
-code set specified by CODESET2 or C<undef> will be returned.
+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 CODESETs must be explicitly entered.
+Both B<CODESET> and B<CODESET2> must be explicitly entered.
country_code2code('fin', LOCALE_CODE_ALPHA_3,
LOCALE_CODE_ALPHA_2);
=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 code2XXX routine would be
-NEW_NAME instead of the name specified in the standard.
+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.
Britain' instead of 'United Kingdom'.
If any error occurs, a warning is issued and 0 is returned. An error
-occurs if CODE doesn't exist in the specified code set, or if
-NEW_NAME is already in use but for a different element.
+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.
These routines are used to add a new code and name to the data.
-Both CODE and NAME must be unused in the data set or an error
-occurs (though NAME may be used in a different data set).
+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:
These routines are used to delete a code from the data.
-CODE must refer to an existing code in the code set.
+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 code2XXX function.
+not alter the return value of the C<code2XXX> function.
-NAME must be an existing element name, and NEW_NAME must
+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 NAME.
+removed, the element may not be referred to by B<NAME>.
-NAME must be one of a list of at least two names that may be used to
+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 add_XXX_alias function to add a new alias
-first, or the remove_XXX function to remove the element entirely.
+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
-rename_XXX function to force one of the alternate names to be
+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 XXX2code routine would be
-NEW_CODE instead of the code specified in the standard.
+that point, the code returned by the C<XXX2code> routine would be
+B<NEW_CODE> instead of the code specified in the standard.
-NEW_CODE may either be a code that is not in use, or it may be an
-alias for CODE (in which case, CODE becomes and alias and NEW_CODE
+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 code2XXX routines
+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 all_XXX_codes routine will only return the codes which
+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 NEW_CODE, but will not contain CODE).
+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, NEW_CODE and CODE
-will both work in the code2XXX routines. However, the XXX2code routines will
+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 CODE is actually an alias. If it is the "real"
-code, it will not be deleted. You will need to use the rename_XXX_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.
=head1 SEE ALSO
-Locale::Codes
+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
https://perl5.git.perl.org / perl5.git / blobdiff