.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Locale::Codes 3"
.TH Locale::Codes 3 "2013-05-29" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Locale::Codes \- a distribution of modules to handle locale codes
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBLocale-Codes\fR is a distribution containing a set of modules.  The
modules each deal with different types of codes which identify parts
of the locale including languages, countries, currency, etc.
.PP
Currently, the following modules are included:
.IP "\fBLocale::Codes::Country, Locale::Country\fR" 4
.IX Item "Locale::Codes::Country, Locale::Country"
This includes support for country codes (such as those listed in \s-1ISO\-3166\s0)
to specify the country.
.Sp
Because this module was originally distributed as Locale::Country, it is
also available under that name.
.IP "\fBLocale::Codes::Language, Locale::Language\fR" 4
.IX Item "Locale::Codes::Language, Locale::Language"
This includes support for language codes (such as those listed in \s-1ISO\-639\s0)
to specify the language.
.Sp
Because this module was originally distributed as Locale::Language, it is
also available under that name.
.IP "\fBLocale::Codes::Currency, Locale::Currency\fR" 4
.IX Item "Locale::Codes::Currency, Locale::Currency"
This includes support for currency codes (such as those listed in \s-1ISO\-4217\s0)
to specify the currency.
.Sp
Because this module was originally distributed as Locale::Currency, it is
also available under that name.
.IP "\fBLocale::Codes::Script, Locale::Script\fR" 4
.IX Item "Locale::Codes::Script, Locale::Script"
This includes support for script codes (such as those listed in \s-1ISO\-15924\s0)
to specify the script.
.Sp
Because this module was originally distributed as Locale::Script, it is
also available under that name.
.IP "\fBLocale::Codes::LangExt\fR" 4
.IX Item "Locale::Codes::LangExt"
This includes support for language extension codes (such as those listed
in the \s-1IANA\s0 language registry) to specify the language extension.
.IP "\fBLocale::Codes::LangVar\fR" 4
.IX Item "Locale::Codes::LangVar"
This includes support for language variation codes (such as those listed
in the \s-1IANA\s0 language registry) to specify the language variation.
.IP "\fBLocale::Codes::LangFam\fR" 4
.IX Item "Locale::Codes::LangFam"
This includes support for language family codes (such as those listed
in \s-1ISO 639\-5\s0) to specify families of languages.
.PP
Each module can support an arbitrary number of code sets, and it is
not required that the relationship between these code sets be
one-to-one.  For example, the Locale::Codes::Country module supports
code sets from \s-1ISO\-3166\s0 and the \s-1FIPS 10\s0 standard, and they do not
break the world down into exactly the same sets of countries. This
does not cause any problem (though converting codes from \s-1ISO\-3166\s0 to
\&\s-1FIPS\s0 or back will not work except for countries that are one-to-one).
.PP
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.
.PP
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.
.PP
In addition to the modules above, there are a number of support modules included
in the distribution including:
.IP "\fBLocale::Codes\fR" 4
.IX Item "Locale::Codes"
.PD 0
.IP "\fBLocale::Codes::Constants\fR" 4
.IX Item "Locale::Codes::Constants"
.IP "\fBLocale::Codes::Country_codes\fR" 4
.IX Item "Locale::Codes::Country_codes"
.IP "\fBLocale::Codes::Language_codes\fR" 4
.IX Item "Locale::Codes::Language_codes"
.IP "\fBLocale::Codes::Currency_codes\fR" 4
.IX Item "Locale::Codes::Currency_codes"
.IP "\fBLocale::Codes::Script_codes\fR" 4
.IX Item "Locale::Codes::Script_codes"
.IP "\fBLocale::Codes::LangExt_codes\fR" 4
.IX Item "Locale::Codes::LangExt_codes"
.IP "\fBLocale::Codes::LangVar_codes\fR" 4
.IX Item "Locale::Codes::LangVar_codes"
.IP "\fBLocale::Codes::LangFam_codes\fR" 4
.IX Item "Locale::Codes::LangFam_codes"
.PD
.PP
These modules are not intended to be used by programmers. They contain functions
or data that are used by the modules listed above.
.SH "NEW CODE SETS"
.IX Header "NEW CODE SETS"
I'm always open to suggestions for new code sets.
.PP
In order for me to add a code set, I want the following criteria
to be met:
.IP "\fBGeneral-use code set\fR" 4
.IX Item "General-use code set"
If a code set is not general use, I'm not likely to spend the time
to add and support it.
.IP "\fBAn official source of data\fR" 4
.IX Item "An official source of data"
I require an official (or at least, a \s-1NEARLY\s0 official) source where I
can get the data on a regular basis.
.Sp
Ideally, I'd only get data from an official source, but sometimes that
is not possible. For example the \s-1ISO\s0 standards are not typically
available for free, so I may have to get some of that data from
alternate sources that I'm confident are getting their data from the
official source.  However, I will always be hesitant to accept a
non-official source.
.Sp
As an example, I used to get some country data from the \s-1CIA\s0 World
Factbook. Given the nature of the source, I'm sure they're updating
data from the official sources and I consider it \*(L"nearly\*(R" official.
However, even in this case, I found that they were adding codes that
were not part of the standard, so I have stopped using them as a
source.
.Sp
There are many 3rd party sites which maintain lists (many of which are
actually in a more convenient form than the official sites).
Unfortunately, I will reject most of them since I have no feel for how
\&\*(L"official\*(R" they are.
.IP "\fBA free source of the data\fR" 4
.IX Item "A free source of the data"
Obviously, the data must be free-of-charge. I'm not interested in
paying for the data (and I'm not interested in the overhead of having
someone else pay for the data for me).
.IP "\fBA reliable source of data\fR" 4
.IX Item "A reliable source of data"
The source of data must come from a source that I can reasonably expect
to exist for the foreseeable future since I will be extremely reluctant
to drop support for a data set once it's included.
.Sp
I am also reluctant to accept data sent to me by an individual.
Although I appreciate the offer, it is simply not practical to consider
an individual contribution as a reliable source of data. The source
should be an official agency of some sort.
.PP
These requirements are open to discussion. If you have a code set
you'd like to see added, but which may not meet all of the above
requirements, feel free to email me and we'll discuss it.  Depending
on circumstances, I may be willing to waive some of these criteria.
.SH "COMMON ALIASES"
.IX Header "COMMON ALIASES"
As of version 2.00, the modules supported common variants of names.
.PP
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 \*(L"United States\*(R" is \*(L"us\*(R", so:
.PP
.Vb 2
\&   country2code(\*(AqUnited States\*(Aq);
\&      => "us"
.Ve
.PP
Now the following will also return 'us':
.PP
.Vb 2
\&   country2code(\*(AqUnited States of America\*(Aq);
\&   country2code(\*(AqUSA\*(Aq);
.Ve
.PP
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.
.PP
For example, the country name \*(L"North Korea\*(R" never appeared in any of
the official sources (instead, it was \*(L"Korea, North\*(R" or \*(L"Korea,
Democratic People's Republic of\*(R". I would honor a request to add an
alias \*(L"North Korea\*(R" since that's a very common way to specify the
country (please don't request this... I've already added it).
.PP
On the other hand, a request to add Zaire as an alias for \*(L"Congo, The
Democratic Republic of\*(R" 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 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.
.SH "DEPRECATED CODES"
.IX Header "DEPRECATED CODES"
Occasionally, a code is deprecated, but it may still be desirable to
have access to it.
.PP
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.
.PP
For more information, refer to the documentation on the code2XXX, XXX2code,
all_XXX_codes, and all_XXX_names function in the \fBLocale::Codes::API\fR
documentation.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\fBLocale::Codes::API\fR" 4
.IX Item "Locale::Codes::API"
The list of functions available in each of the modules listed below.
The APIs for each module are exactly identical.
.IP "\fBLocale::Codes::Country\fR" 4
.IX Item "Locale::Codes::Country"
Codes for identification of countries.
.IP "\fBLocale::Codes::Language\fR" 4
.IX Item "Locale::Codes::Language"
Codes for identification of languages.
.IP "\fBLocale::Codes::Script\fR" 4
.IX Item "Locale::Codes::Script"
Codes for identification of scripts.
.IP "\fBLocale::Codes::Currency\fR" 4
.IX Item "Locale::Codes::Currency"
Codes for identification of currencies and funds.
.IP "\fBLocale::Codes::LangExt\fR" 4
.IX Item "Locale::Codes::LangExt"
Codes for identification of language extensions.
.IP "\fBLocale::Codes::LangVar\fR" 4
.IX Item "Locale::Codes::LangVar"
Codes for identification of language variations.
.IP "\fBLocale::Codes::LangFam\fR" 4
.IX Item "Locale::Codes::LangFam"
Codes for identification of language families.
.IP "\fBLocale::Codes::Changes\fR" 4
.IX Item "Locale::Codes::Changes"
A history of changes made to this distribution.
.SH "AUTHOR"
.IX Header "AUTHOR"
Locale::Country and Locale::Language were originally written by Neil
Bowers at the Canon Research Centre Europe (\s-1CRE\s0). They maintained the
distribution from 1997 to 2001.
.PP
Locale::Currency was originally written by Michael Hennecke and was
modified by Neil Bowers for inclusion in the distribution.
.PP
From 2001 to 2004, maintenance was continued by Neil Bowers.  He
modified Locale::Currency for inclusion in the distribution. He also
added Locale::Constants and Locale::Script.
.PP
From 2004\-2009, the module was unmaintained.
.PP
In 2010, maintenance was taken over by Sullivan Beck (sbeck@cpan.org)
with Neil Bower's permission.  All problems or comments should be
sent there.  Alternately, problems can be reported using the
perl problem tracker at:
.PP
.Vb 1
\&   https://rt.cpan.org/Dist/Display.html?Queue=Locale\-Codes
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
.Vb 4
\&   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\-2013 Sullivan Beck
.Ve
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
