.\" 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 "Locales 3"
.TH Locales 3 "2016-01-16" "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"
Locales \- Methods for getting localized CLDR language/territory names (and a subset of other data)
.SH "VERSION"
.IX Header "VERSION"
This document describes Locales version 0.33
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Locales;
\&
\&    my $locale = Locales\->new(\*(Aqen_gb\*(Aq);
\&
\&    print $locale\->get_locale(); # \*(Aqen_gb\*(Aq
\&    print $locale\->get_language(); # \*(Aqen\*(Aq
\&    print $locale\->get_territory(); # \*(Aqgb\*(Aq
\&
\&    print $locale\->get_language_from_code(\*(Aqfr\*(Aq); # \*(AqFrench\*(Aq
\&    print $locale\->get_code_from_language(\*(AqFrench\*(Aq); # \*(Aqfr\*(Aq
\&
\&    print $locale\->get_territory_from_code(\*(Aqus\*(Aq); # \*(AqUnited States\*(Aq
\&    print $locale\->get_code_from_territory(\*(AqAustralia\*(Aq); # \*(Aqau\*(Aq
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Locales lets you create an object for a certain locale that lets you access certain data harvested directly from \s-1CLDR.\s0
.PP
<http://cldr.unicode.org/index/downloads>
.PP
Currently the data/methods include translated locale names and territory names.
.PP
For simplicity Locales does not work with or know about Variants or Scripts. It only knows about languages and territories.
.PP
Also it does not contain all the data contained in \s-1CLDR.\s0 For example, DateTimeXs localization already has all the calender/date/time info from \s-1CLDR.\s0 Other information has not had any demand yet.
.PP
For consistency all data is written in utf\-8. No conversion should be necessary if you are (wisely) using utf\-8 as your character set everywhere (See <http://drmuey.com\e/?do=page&id=57> for more info on that.).
.PP
Note: You probably [don't need to/should not] use utf8 in regards to the data contained herein.
.SH "Based on CLDR"
.IX Header "Based on CLDR"
This module is based on \s-1CLDR\s0 v2.0.
.PP
You can learn about the Unicode Common Locale Data Repository at <http://cldr.unicode.org/>.
.SH "Supported Locale Criteria"
.IX Header "Supported Locale Criteria"
The locale tags that can be objectified fit this criteria:
.IP "the locale must have data in the \s-1CLDR\s0" 4
.IX Item "the locale must have data in the CLDR"
As noted in \s-1XI\s0 am using a locale code that I know exists in the \s-1CLDR\s0 but I can't use it anywhere in LocalesX in \*(L"\s-1BEFORE YOU SUBMIT A BUG REPORT\*(R"\s0.
.IP "the locale must have an entry in CLDRXs en data" 4
.IX Item "the locale must have an entry in CLDRXs en data"
As noted in \s-1XI\s0 am using a locale code that I know exists in the \s-1CLDR\s0 but I can't use it anywhere in LocalesX in \*(L"\s-1BEFORE YOU SUBMIT A BUG REPORT\*(R"\s0.
.IP "the locale can only have language and territory parts" 4
.IX Item "the locale can only have language and territory parts"
As noted in the \*(L"\s-1DESCRIPTION\*(R"\s0.
.IP "the only exceptions are Xsoft localesX." 4
.IX Item "the only exceptions are Xsoft localesX."
As described in \*(L"Soft Locales\*(R".
.SH "Soft Locales"
.IX Header "Soft Locales"
As Xsoft localeX is a language-territory locale that does not fit the \*(L"Supported Locale Criteria\*(R" directly but its super does and the territory is known.
.PP
For example Xes-MXX does not fit the criteria but XesX does and \s-1XMXX\s0 is a valid territory code.
.SH "To byte or not to byte, that is the question. Ok, IXll byte X"
.IX Header "To byte or not to byte, that is the question. Ok, IXll byte X"
The \s-1CLDR\s0 data is in bytes, specifically utf\-8.
.PP
By default this module simply passes along the strings as bytes, which works fine in applications that donXt operate in character mode (i.e. that use utf8 byte strings instead of Unicode strings**).
.PP
If you want Unicode strings instead you can do so by bringing in the module this way:
.PP
.Vb 1
\&    use Locales unicode => 1;
.Ve
.PP
[**] What is the difference between Unicode strings and utf\-8 bytes strings you ask? See String::UnicodeUTF8 for more info.
.SH "INTERFACE"
.IX Header "INTERFACE"
.SS "\fInew()\fP"
.IX Subsection "new()"
Takes one argument, the locale tag whose \s-1CLDR\s0 data you want to use.
.PP
No argument defaults to 'en'.
.PP
It is an argument based singleton so you can call it more than once with out it having to rebuild the object every time.
.PP
It returns false if a locale given is not available. $@ should have been set at that point by eval.
.PP
.Vb 1
\&    my $en = Locales\->new(\*(Aqen\*(Aq) or die $@;
.Ve
.SS "Object methods"
.IX Subsection "Object methods"
\fIMisc methods\fR
.IX Subsection "Misc methods"
.IP "\fIget_cldr_version()\fR" 4
.IX Item "get_cldr_version()"
Takes no arguments.
.Sp
Returns the version of the \s-1CLDR\s0 any data it uses comes from. Can also be called as a class method or function.
.IP "\fIget_locale()\fR" 4
.IX Item "get_locale()"
Takes no arguments.
.Sp
Returns the normalized locale of the object, this is the same as the argument to \fInew()\fR
.IP "\fIget_language()\fR" 4
.IX Item "get_language()"
Takes no arguments.
.Sp
Returns the language portion of the objectXs locale.
.IP "\fIget_territory()\fR" 4
.IX Item "get_territory()"
Takes no arguments.
.Sp
Returns the territory portion of the objectXs locale if any (e.g. 'en_au'), undef if there is none (e.g. 'it').
.IP "\fIget_soft_locale_fallback()\fR" 4
.IX Item "get_soft_locale_fallback()"
Takes no arguments.
.Sp
Returns the locale that the object is based on in the case that the given locale (i.e. \*(L"\fIget_locale()\fR\*(R") is a soft locale.
.Sp
Note: If you do not want to have soft locale objects you should simply not call \fInew()\fR if it is soft:
.Sp
.Vb 2
\&    \- my $loc = Locales\->new($tag) || die $@;
\&    + my $loc = (Locales::tag_is_soft_locale($tag) ? undef : Locales\->new($tag)) || die $@;
.Ve
.Sp
This could be added to the constructor but for now I don't want to make it more complicated only to support something that seems odd. If you have a use case submit an rt w/ details. Thanks!
.IP "\fInumf()\fR" 4
.IX Item "numf()"
Note: As of v0.17 you probably want \*(L"\fIget_formatted_decimal()\fR\*(R" instead of \fInumf()\fR.
.Sp
Takes one optional boolean argument.
.Sp
Returns 1 if the objectXss localeXs number format is comma for thousand separator, period for decimal.
.Sp
Returns 2  if the objectXs localeXs number format is period for thousand separator, comma for decimal.
.Sp
Otherwise it returns a reference to a 3 element array containing this \s-1CLDR\s0 data: number format, separator character, decimal character.
.Sp
The boolean argument, when true will do itXs best to determine and return a 1 or a 2.
.PP
\fITerritory methods\fR
.IX Subsection "Territory methods"
.IP "\fIget_territory_codes()\fR" 4
.IX Item "get_territory_codes()"
Take no arguments.
.Sp
Returns an unsorted list of known territory codes.
.IP "\fIget_territory_names()\fR" 4
.IX Item "get_territory_names()"
Take no arguments.
.Sp
Returns an unsorted list of the display names for each known territory code.
.IP "\fIget_territory_lookup()\fR" 4
.IX Item "get_territory_lookup()"
Take no arguments.
.Sp
Returns a copy of the lookup hash of the display names for each known territory code.
.IP "\fIget_territory_from_code()\fR" 4
.IX Item "get_territory_from_code()"
Takes one argument, the locale code whose territory name you want to find. Defaults to the territory of the of objectXs locale, if any.
.Sp
Returns the name of the given tagXs territory or, if not found, the territory portion (if any), returns false otherwise.
.Sp
An optional second argument, when true, will force it to return the normalized tag if nothing else can be figured out.
.IP "\fIget_code_from_territory()\fR" 4
.IX Item "get_code_from_territory()"
Takes one argument, the territory name whose locale you want to find.
.Sp
Returns the locale tag if found, false otherwise.
.IP "\fIcode2territory()\fR" 4
.IX Item "code2territory()"
Alias for \fIget_territory_from_code()\fR
.IP "\fIterritory2code()\fR" 4
.IX Item "territory2code()"
Alias for \fIget_code_from_territory()\fR
.PP
\fILanguage Methods\fR
.IX Subsection "Language Methods"
.IP "\fIget_language_codes()\fR" 4
.IX Item "get_language_codes()"
Take no arguments.
.Sp
Returns an unsorted list of known language codes.
.IP "\fIget_language_names()\fR" 4
.IX Item "get_language_names()"
Take no arguments.
.Sp
Returns an unsorted list of the display names for each known language code.
.IP "\fIget_language_lookup()\fR" 4
.IX Item "get_language_lookup()"
Take no arguments.
.Sp
Returns a copy of the lookup hash of the display names for each known language code.
.IP "\fIget_language_from_code()\fR" 4
.IX Item "get_language_from_code()"
Takes one argument, the locale code whose language name you want to find. Defaults to the objectXs locale.
.Sp
Returns the name of the given tagXs language, returns false otherwise.
.Sp
An optional second argument, when true, will force it to return a properly formatted \s-1CLDR\s0 format display based on if we know the language and/or territory if nothing else can be figured out.
.IP "\fIget_code_from_language()\fR" 4
.IX Item "get_code_from_language()"
Takes one argument, the language name whose locale you want to find.
.Sp
Returns the locale tag if found, false otherwise.
.IP "\fIget_native_language_from_code()\fR" 4
.IX Item "get_native_language_from_code()"
Like \fIget_language_from_code()\fR except it returns the name in the given localeXs native language.
.IP "\fIget_character_orientation_from_code()\fR" 4
.IX Item "get_character_orientation_from_code()"
Like \fIget_language_from_code()\fR except it returns the character orientation identifier for the given locale. (defaulting to the locale of the object if non is given)
.Sp
Typically it will be the string Xleft-to-rightX or Xright-to-leftX.
.Sp
See <http://unicode.org/repos/cldr\-tmp/trunk/diff/by_type/misc.layout.html> for more information.
.IP "\fIget_character_orientation_from_code_fast()\fR" 4
.IX Item "get_character_orientation_from_code_fast()"
Same as \fIget_character_orientation_from_code()\fR except it should use less-overhead. Can be called as a function also so you can use it without creating an object.
.IP "\fIget_locale_display_pattern_from_code()\fR" 4
.IX Item "get_locale_display_pattern_from_code()"
Like \fIget_character_orientation_from_code()\fR except it returns the locale display pattern for the given locale. (defaulting to the locale of the object if non is given)
.Sp
Typically it will be something like '{0} ({1})'
.Sp
See <http://unicode.org/repos/cldr\-tmp/trunk/diff/by_type/names.localeDisplayPattern.html> for more information.
.IP "\fIget_locale_display_pattern_from_code_fast()\fR" 4
.IX Item "get_locale_display_pattern_from_code_fast()"
Same as \fIget_locale_display_pattern_from_code()\fR except it should use less-overhead. Can be called as a function also so you can use it without creating an object.
.IP "\fIget_cldr_number_symbol_decimal()\fR" 4
.IX Item "get_cldr_number_symbol_decimal()"
Returns the decimal point symbol for the objectXs locale. Takes no arguments.
.Sp
For formatting numbers use \fIget_formatted_decimal()\fR.
.IP "\fIget_cldr_number_symbol_group()\fR" 4
.IX Item "get_cldr_number_symbol_group()"
Returns the integer grouping symbol for the objectXs locale. Takes no arguments.
.Sp
For formatting numbers use \fIget_formatted_decimal()\fR.
.IP "\fIget_fallback_list()\fR" 4
.IX Item "get_fallback_list()"
Returns a fallback list of locales in the order they apply based on the objectXs locale.
.Sp
The basic list will be: objectXs locale, objectXs super if any, the objectXs \s-1CLDR\s0 fallback if any, Xspecial lookupX if any, 'en'
.Sp
.Vb 2
\&    my @list = $fr_ca\->get_fallback_list();
\&    # fr_ca fr en
.Ve
.Sp
\&\*(L"special lookup\*(R" is a code ref that can be passed in as the first optional arg.
.Sp
It is given the objectXs locale when called and should return a list of locale tags (they will be normalized).
.Sp
.Vb 2
\&    my @list = $fr_ca\->get_fallback_list(sub { return $_[0] =~ m/fr/ ? qw(i_yoda i_love_rhi) : () } );
\&    # fr_ca fr i_yoda i_love_rhi en
.Ve
.IP "\fIget_plural_form()\fR" 4
.IX Item "get_plural_form()"
Takes a number and returns the plural category that the number fits under for the objectXs locale.
.Sp
You can also add an array of items to return instead of the category name. For the details on what arguments a given local needs see Locales::DB::Docs::PluralForms.
.Sp
The array should be the same length of the list of plural form categories for the locale. See \fIget_plural_form_categories()\fR.
.Sp
The exception to that is when you specify the optional \*(L"XSpecial ZeroX Argument\*(R" in Locales::DB::Docs::PluralForms.
.Sp
For example, 'en' has the plural categories XoneX and XotherX, so it'd work like this:
.Sp
.Vb 3
\&    my $cat = $en\->get_plural_form(0); # \*(Aqother\*(Aq
\&    my $str = $en\->get_plural_form(0,\*(AqI am 1\*(Aq,\*(AqI am other\*(Aq); # I am other
\&    my $str = $en\->get_plural_form(0,\*(AqI am 1\*(Aq,\*(AqI am other\*(Aq,\*(AqI am nothing\*(Aq); # I am nothing
\&
\&    my $cat = $en\->get_plural_form(1); # \*(Aqone\*(Aq
\&    my $str = $en\->get_plural_form(1,\*(AqI am 1\*(Aq,\*(AqI am other\*(Aq); # I am 1
\&    my $str = $en\->get_plural_form(1,\*(AqI am 1\*(Aq,\*(AqI am other\*(Aq,\*(AqI am nothing\*(Aq);  #I am 1
\&
\&    my $cat = $en\->get_plural_form(2); # \*(Aqother\*(Aq
\&    my $str = $en\->get_plural_form(2,\*(AqI am 1\*(Aq,\*(AqI am other\*(Aq); # I am other
\&    my $str = $en\->get_plural_form(2,\*(AqI am 1\*(Aq,\*(AqI am other\*(Aq,\*(AqI am nothing\*(Aq); # I am other
.Ve
.Sp
In array context the second value is a boolean for if the return value is the \*(L"XSpecial ZeroX Argument\*(R" in Locales::DB::Docs::PluralForms or not.
.Sp
This boolean value only has meaning when called with the additional array of items to return instead of the category name.
.Sp
This method can \fIcarp()\fR a few things:
.RS 4
.ie n .IP """Could not determine plural logic.""" 4
.el .IP "\f(CWCould not determine plural logic.\fR" 4
.IX Item "Could not determine plural logic."
The locale does not have plural logic data.
.ie n .IP """The number of given values (%d) does not match the number of categories (%d).""" 4
.el .IP "\f(CWThe number of given values (%d) does not match the number of categories (%d).\fR" 4
.IX Item "The number of given values (%d) does not match the number of categories (%d)."
You passed too many or too few values after the initial numeric argument.
.Sp
You'll only see this if \f(CW$locales_object\fR\->{'verbose'} is set to true.
.ie n .IP """The category (%s) is not used by this locale.""" 4
.el .IP "\f(CWThe category (%s) is not used by this locale.\fR" 4
.IX Item "The category (%s) is not used by this locale."
The localeXs plural rules come up with a category that is not applicable to the locale. Default to XotherX at this point.
.RE
.RS 4
.RE
.IP "\fIget_plural_form_categories()\fR" 4
.IX Item "get_plural_form_categories()"
Returns an array of the \s-1CLDR\s0 plural rule category names that this locale uses.
.Sp
Their order corresponds to the position of the corresponding value that \fIget_plural_form()\fR uses.
.IP "\fIsupports_special_zeroth()\fR" 4
.IX Item "supports_special_zeroth()"
Takes no arguments, returns a boolean.
.Sp
It is true if the locale uses the \*(L"XSpecial ZeroX Argument\*(R" in Locales::DB::Docs::PluralForms.
.Sp
False if it does not.
.IP "\fIplural_category_count()\fR" 4
.IX Item "plural_category_count()"
Takes no arguments.
.Sp
Returns the number of plural categories applicable to the objectXs locale.
.Sp
Does not factor in support (or not) of the special zeroth category.
.IP "\fIget_list_and()\fR" 4
.IX Item "get_list_and()"
Stringify an \*(L"and\*(R" list of items as defined in the \s-1CLDR\s0 for the objectXs locale.
.Sp
Note: \fIget_list_or()\fR will be done once \s-1CLDR\s0 defines the OR-list data <http://unicode.org/cldr/trac/ticket/4051>.
.Sp
.Vb 5
\&    $en\->get_list_and() # nothing
\&    $en\->get_list_and(1) # 1
\&    $en\->get_list_and(1,2) # 1 and 2
\&    $en\->get_list_and(1,2,3) # 1, 2, and 3
\&    $en\->get_list_and(1,2,3,4) # 1, 2, 3, and 3
\&
\&    $es\->get_list_and() # nothing
\&    $es\->get_list_and(1) # 1
\&    $es\->get_list_and(1,2) # 1 y 2
\&    $es\->get_list_and(1,2,3) # 1, 2 y 3
\&    $es\->get_list_and(1,2,3,4) # 1, 2, 3 y 3
.Ve
.Sp
To help disambiguate ambiguous arguments (none, undef, \s-1XX,\s0 all space/non\-break\-space) you can use \f(CW$loc\fR\->{'misc'}{'list_quote_mode'}.
.Sp
The default value is XnoneX.
.Sp
Possible values:
.RS 4
.IP "XallX" 4
.IX Item "XallX"
\&\fIquote()\fR all values.
.IP "XsomeX" 4
.IX Item "XsomeX"
\&\fIquote()\fR only ambiguous values (none (as if it was \s-1XX\s0), undef, \s-1XX,\s0 all space/non\-break\-space).
.IP "XnoneX" 4
.IX Item "XnoneX"
do not \fIquote()\fR any values
.RE
.RS 4
.Sp
If another value is given or the entry does not exist you'll get XnoneX behavior. If it is set to an unknown value you'll get a \fIcarp()\fR of X$self\->{misc}{list_quote_mode} is set to an unknown valueX.
.RE
.IP "\fIget_list_or()\fR" 4
.IX Item "get_list_or()"
Stringify an \*(L"or\*(R" list of items as defined in the \s-1CLDR\s0 for the objectXs locale.
.Sp
This is a stub until \s-1CLDR\s0 defines the OR-list data <http://unicode.org/cldr/trac/ticket/4051>.
.Sp
Until then it is essentially the same as \*(L"\fIget_list_and()\fR\*(R"except it uses English rules/grammer for or lists.
.Sp
Uses \f(CW$loc\fR\->{'misc'}{'list_quote_mode'} the same way \fIget_list_and()\fR does.
.IP "\fIget_formatted_ellipsis_initial()\fR" 4
.IX Item "get_formatted_ellipsis_initial()"
Formats the given string per the initial ellipsis pattern.
.Sp
Truncating for length is the callerXs responsibility since knowing how to do that correctly depends on what the string is (e.g. plain text needs to factor in the encoding or we might corrupt the text, \s-1HTML\s0 might have a broken or unclosed tag, \s-1ANSI\s0 might be unclosed or truncated, etc) so it is outside of the scope of the \s-1CLDR.\s0
.Sp
.Vb 1
\&    Xfoo
.Ve
.IP "\fIget_formatted_ellipsis_medial()\fR" 4
.IX Item "get_formatted_ellipsis_medial()"
Formats the given string per the medial ellipsis pattern.
.Sp
Truncating for length is the callerXs responsibility since knowing how to do that correctly depends on what the string is (e.g. plain text needs to factor in the encoding or we might corrupt the text, \s-1HTML\s0 might have a broken or unclosed tag, \s-1ANSI\s0 might be unclosed or truncated, etc) so it is outside of the scope of the \s-1CLDR.\s0
.Sp
.Vb 1
\&    fooXbar
.Ve
.IP "\fIget_formatted_ellipsis_final()\fR" 4
.IX Item "get_formatted_ellipsis_final()"
Formats the given string per the medial ellipsis pattern.
.Sp
Truncating for length is the callerXs responsibility since knowing how to do that correctly depends on what the string is (e.g. plain text needs to factor in the encoding or we might corrupt the text, \s-1HTML\s0 might have a broken or includes tag, \s-1ANSI\s0 might be unclosed or truncated, etc) so it is outside of the scope of the \s-1CLDR.\s0
.Sp
.Vb 1
\&    fooX
.Ve
.IP "\fIquote()\fR" 4
.IX Item "quote()"
Quotes the argument with the \s-1CLDR\s0 delimiters quotation_start and quotation_end.
.IP "\fIquote_alt()\fR" 4
.IX Item "quote_alt()"
Quotes the argument with the \s-1CLDR\s0 delimiters alternate_quotation_start and alternate_quotation_end.
.IP "\fIget_formatted_decimal()\fR" 4
.IX Item "get_formatted_decimal()"
Return the given number as a string formatted per the localeXs \s-1CLDR\s0 decimal format pattern.
.Sp
An optional second argument defines a maximum length of decimal places (default is 6 perl \f(CW%f\fR, max is 14, if you have a need for a larger max please open an rt w/ context and we may make the max settable in the object)
.Sp
.Vb 3
\&    $fr\->get_formatted_decimal("1234567890.12345"); # 1\ 234\ 567\ 890,12345
\&    $fr\->get_formatted_decimal("1234567890.12345",4); # 1\ 234\ 567\ 890,123
\&    $fr\->get_formatted_decimal("1234567890.12345",3); # 1\ 234\ 567\ 890,1235
.Ve
.Sp
Perl number stringification caveats:
.RS 4
.IP "You can avoid most stringification of large integers issues by passing strings." 4
.IX Item "You can avoid most stringification of large integers issues by passing strings."
.Vb 2
\&     $l\->get_formatted_decimal(99999999999999999983222787.1234); # returns 1e+26 since that is how it comes into the function
\&     $l\->get_formatted_decimal("99999999999999999983222787.1234"); # 99,999,999,999,999,999,983,222,787.1234
.Ve
.IP "You can avoid most formatting of large decimal parts issues by passing strings." 4
.IX Item "You can avoid most formatting of large decimal parts issues by passing strings."
.Vb 2
\&     $l\->get_formatted_decimal(10000000001.12345678911234,12); # 10,000,000,001.1235 since it is already truncated  when it comes into the function
\&     $l\->get_formatted_decimal("10000000001.12345678911234",12); # 10,000,000,001.123456789112
.Ve
.IP "If the abs integer is > 10_000_000_000 and the decimal part alone stringify into an exponential number the rounding is not done." 4
.IX Item "If the abs integer is > 10_000_000_000 and the decimal part alone stringify into an exponential number the rounding is not done."
That is \s-1OK\s0 though, since this isn't intended to be used in math and you are already aware of how large integers and decimals act oddly on computers right?
.IP "In general very large integers and/or very large decimal places get wonky when you want to turn them into a string like [0\-9]+.[0\-9]+" 4
.IX Item "In general very large integers and/or very large decimal places get wonky when you want to turn them into a string like [0-9]+.[0-9]+"
This is why we have a hard limit of 14 decimal places, to enforce some sense of sanity. You might consider only using the max decimal places argument to make it less than 6 digits long.
.RE
.RS 4
.Sp
This method can \fIcarp()\fR a few (hopefully self explanatory) things regarding \s-1CLDR\s0 number format syntax errors:
.ie n .IP """Format had more than 2 pos/neg sections. Using default pattern.""" 4
.el .IP "\f(CWFormat had more than 2 pos/neg sections. Using default pattern.\fR" 4
.IX Item "Format had more than 2 pos/neg sections. Using default pattern."
.PD 0
.ie n .IP """Format should have one decimal section. Using default pattern.""" 4
.el .IP "\f(CWFormat should have one decimal section. Using default pattern.\fR" 4
.IX Item "Format should have one decimal section. Using default pattern."
.ie n .IP """Format is empty. Using default pattern.""" 4
.el .IP "\f(CWFormat is empty. Using default pattern.\fR" 4
.IX Item "Format is empty. Using default pattern."
.RE
.RS 4
.RE
.IP "\fIcode2language()\fR" 4
.IX Item "code2language()"
.PD
Alias for \fIget_language_from_code()\fR
.IP "\fIlanguage2code()\fR" 4
.IX Item "language2code()"
Alias for \fIget_code_from_language()\fR
.SS "Utility functions"
.IX Subsection "Utility functions"
These are some functions used internally that you might find useful.
.IP "\fILocales::normalize_tag()\fR" 4
.IX Item "Locales::normalize_tag()"
Takes a single argument, the locale tag to normalize.
.Sp
Returns the normalized tag.
.Sp
.Vb 1
\&   print Locales::normalize_tag("  en\-GB\en "); # \*(Aqen_gb\*(Aq
.Ve
.IP "\fILocales::normalize_tag_for_datetime_locale()\fR" 4
.IX Item "Locales::normalize_tag_for_datetime_locale()"
Like \fInormalize_tag()\fR except the return value should be suitable for DateTime::Locale
.Sp
.Vb 1
\&   print Locales::normalize_tag_for_datetime_locale("  en\-GB\en "); # \*(Aqen_GB\*(Aq
.Ve
.IP "\fILocales::normalize_tag_for_ietf()\fR" 4
.IX Item "Locales::normalize_tag_for_ietf()"
Like \fInormalize_tag()\fR except the return value should be suitable for \s-1IETF.\s0
.Sp
This is not a comprehensive \s-1IETF\s0 formatter, it is intended (for now at least) for the subset of tags Locales.pm uses.
.Sp
.Vb 1
\&   print Locales::normalize_tag_for_ietf("  en_gb\en "); # \*(Aqen\-GB\*(Aq
.Ve
.IP "\fILocales::split_tag()\fR" 4
.IX Item "Locales::split_tag()"
Takes a single argument, the locale tag to split into language and territory parts.
.Sp
Returns the resulting array of 1 or 2 normalized (but not validated) items.
.Sp
.Vb 1
\&   my ($language, $territory) = Locales::split_tag("  en\-GB\en "); # (\*(Aqen\*(Aq,\*(Aqgb\*(Aq)
\&
\&   my ($language, $territory) = Locales::split_tag(\*(Aqfr\*(Aq); # (\*(Aqfr\*(Aq);
\&
\&   my ($language, $territory) = Locales::split_tag(\*(Aqsr_Cyrl_YU\*(Aq); # (\*(Aqsr\*(Aq,\*(Aqcyrl_yu\*(Aq), yes \*(Aqcyrl_yu\*(Aq is invalid here since Locales doesn\*(Aqt work with the Script variants, good catch
.Ve
.IP "\fILocales::get_i_tag_for_string()\fR" 4
.IX Item "Locales::get_i_tag_for_string()"
Takes a single argument, the locale tag string to transform into \*(L"i\*(R" notation.
.Sp
Returns the resulting normalized locale tag.
.Sp
The standard tag for strings/tags without a standard is an \*(L"i\*(R" notation tag.
.Sp
For example, the language \*(L"Yoda Speak\*(R" does not have an \s-1ISO\s0 code. You'd have to use i_yoda_speak.
.Sp
.Vb 9
\&    # assuming $string = "Yoda Speak"; you\*(Aqd get into the if(), assuming it was \*(AqSpanish\*(Aq or \*(Aqes\*(Aq
\&    if (!$en\->get_language_from_code($string) && !$en\->get_code_from_language($string) ) {
\&        # it is not a code or a language (at least in the language of $en) so lets create a tag for it:
\&        _create_locale_files( Locales::get_i_tag_for_string($string) ); # i_yoda_speak
\&    }
\&    else {
\&        # if it is a language name then we fetch the code otherwise, at this point, we know it is a code, so return a normailized version
\&        _create_locale_files( $en\->get_code_from_language($yoda) || Locales::normalize_tag($yoda) );
\&    }
.Ve
.IP "\fILocales::tag_is_soft_locale()\fR" 4
.IX Item "Locales::tag_is_soft_locale()"
Takes a single argument, the locale tag you want to check to see if it is <soft locale|/Soft Locales> or not.
.Sp
If it is it returns the super portion that an object would be based on. If it is not it returns false.
.IP "\fILocales::tag_is_loadable()\fR" 4
.IX Item "Locales::tag_is_loadable()"
Returns true if the given tag can be loaded as a Locales object via \fInew()\fR. False otherwise.
.IP "\fILocales::territory_code_is_known()\fR" 4
.IX Item "Locales::territory_code_is_known()"
Returns true if the given tag is a known territory. False otherwise.
.IP "\fILocales::get_loadable_language_codes()\fR" 4
.IX Item "Locales::get_loadable_language_codes()"
Takes no arguments. Returns an unsorted list of codes that can be loaded as a Locales object via \fInew()\fR.
.IP "\fILocales::non_locale_list()\fR" 4
.IX Item "Locales::non_locale_list()"
Takes no arguments. Returns a list of locale tags that are not actually locales. e.g. 'mul' means XMultiple LanguagesX.
.IP "\fILocales::is_non_locale()\fR" 4
.IX Item "Locales::is_non_locale()"
Takes a locale tag as the argument and returns true if it is a non-locale code (See \*(L"\fILocales::non_locale_list()\fR\*(R"), false otherwise.
.IP "Locales::typical_en_alias_list" 4
.IX Item "Locales::typical_en_alias_list"
Takes no arguments. Returns a list of locale tags that are typically aliases of 'en'.
.IP "Locales::is_typical_en_alias" 4
.IX Item "Locales::is_typical_en_alias"
Takes a locale tag as the argument and returns true if it is typically an alias of 'en' (See \*(L"\fILocales::typical_en_alias_list()\fR\*(R"), false otherwise.
.IP "\fILocales::normalize_for_key_lookup()\fR" 4
.IX Item "Locales::normalize_for_key_lookup()"
Takes a single argument, the phrase string normalize in the same way the names are stored in each localeXs lookup hash.
.Sp
Returns the resulting normalized string.
.Sp
This is used internally to normalize a given name in the same manner the name-to-code hash keys are normalized.
.Sp
If said normalization is ever improved then using this function will ensure everything is normalized consistently.
.Sp
That allows \f(CW$en\fR\->get_code_from_language($name) to map to 'afa' if given these various variations of \f(CW$arg:\fR
.Sp
.Vb 5
\&  "Afro\-Asiatic Language"
\&  "afroasiatic\etLanguage"
\&  "AFRO\-Asiatic Language"
\&  "  Afro_Asiatic    Language"
\&  "afro.Asiatic Language\en"
.Ve
.IP "\fILocales::get_cldr_plural_category_list()\fR" 4
.IX Item "Locales::get_cldr_plural_category_list()"
Returns a list of plural categories that \s-1CLDR\s0 uses.
.Sp
With no argument, the order is what is appropriate for some noun quantifying localization methods.
.Sp
With a true argument, the order is the order it makes sense to check their corresponding rules in.
.IP "\fILocales::plural_rule_string_to_code()\fR" 4
.IX Item "Locales::plural_rule_string_to_code()"
This is used under the hood to facilitate \fIget_plural_form()\fR. That being the case there probably isn't much use for it to be used directly.
.Sp
This takes the plural rule string as found in the \s-1CLDR XML\s0 and returns an \fIeval()\fRable perl code version of it.
.Sp
It will carp \*(L"Unknown plural rule syntax\*(R" and return; if it does not understand what you sent.
.Sp
A second, optional, argument is the value to return if the rule matches.
.Sp
If you eval the returned string you'll have a code reference that returns true (or whatever you give it) if the rule matched the given number or not:
.Sp
.Vb 3
\&    my $perly = Locales::plural_rule_string_to_code("n is 42 or n mod 42 is not 7");
\&    my $check = eval $perly;
\&    my $plural_category = $check\->(42);
.Ve
.IP "\fILocales::plural_rule_hashref_to_code()\fR" 4
.IX Item "Locales::plural_rule_hashref_to_code()"
This is used under the hood to facilitate \fIget_plural_form()\fR. That being the case there probably isn't much use for it to be used directly.
.Sp
This takes a hashref that contains rules, puts them in the hash, and returns an overall code ref. Its pretty internal so if you really need the details have a gander at the source.
.IP "Locales::plural_rule_string_to_javascript_code" 4
.IX Item "Locales::plural_rule_string_to_javascript_code"
Same as \fILocales::plural_rule_string_to_code()\fR except it returns javascript code instead of perl code.
.Sp
Used internally when building this distributionXs share/misc_info contents.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
Throws no warning or errors of itXs own. If any function or method returns false then the arguments given (or not given) were invalid/not found.
.PP
Deviations from this are documented per function/method.
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
Locales requires no configuration files or environment variables.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
None.
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
None reported.
.SH "TODO"
.IX Header "TODO"
.Vb 6
\&  \- CLDR builder TODOs
\&  \- more CLDR version/misc\-info fetchers
\&  \- generally improve get_code_from_* lookups
\&  \- tests that misc info doesn\*(Aqt get odd structs from XML instead of a string
\&  \- ? install share/ via L<File::ShareDir> mechanism ?
\&  \- vet share/ && document better
.Ve
.SH "DEPRECATED MODULES/INTERFACE"
.IX Header "DEPRECATED MODULES/INTERFACE"
The original, non \s-1CLDR\s0 based,  '::Base' based modules/interface in this distribution were deprecated in version 0.06.
.PP
These modules were removed in version 0.15.
.SH "BUGS AND FEATURES"
.IX Header "BUGS AND FEATURES"
Please report any bugs or feature requests (and a pull request for bonus points)
 through the issue tracker at <https://github.com/drmuey/p5\-Locales/issues>.
.PP
Please report any bugs or feature requests regarding \s-1CLDR\s0 data as per
<http://cldr.unicode.org/index/bug\-reports>.
.SS "\s-1BEFORE YOU SUBMIT A BUG REPORT\s0"
.IX Subsection "BEFORE YOU SUBMIT A BUG REPORT"
Please read \s-1TODO, DESCRIPTION,\s0 and the information below thoroughly to see if your thought is already addressed.
.IP "\(bu" 4
A non-English object returns English names.
.Sp
Data that is not defined in a localeXs \s-1CLDR\s0 data falls back to English.
.Sp
Please report the missing data to the \s-1CLDR\s0 as per <http://cldr.unicode.org/index/bug\-reports>.
.IP "\(bu" 4
I am using a locale code that I know exists in the \s-1CLDR\s0 but I can't use it anywhere in Locales
.Sp
Only locales and territory codes that 'en' knows about are used. Only locales that have their own data set in \s-1CLDR\s0 are able to be objectified.
.Sp
Additions or updates can be request as per <http://cldr.unicode.org/index/bug\-reports>.
.IP "\(bu" 4
A name is misformatted, incorrect, etc.
.Sp
The data is automatically harvested from \s-1CLDR.\s0 So if there is really a problem you'll have to report the problem to them. (as per <http://cldr.unicode.org/index/bug\-reports>)
.Sp
Here are some things to check before submitting a report:
.RS 4
.IP "\(bu" 4
Corrupt text
.RS 4
.IP "\(bu" 4
Is your charset correct?
.Sp
For example, viewing \s-1UTF\-8\s0 characters on a latin1 web page will result in garbled characters.
.IP "\(bu" 4
It still looks corrupt!
.Sp
Some localeXs require special fonts to be installed on your system to view them properly.
.Sp
For example Bengali (bn) is like this. As per <http://www.unicode.org/help/display_problems.html> if you install the proper font it renders correctly.
.RE
.RS 4
.RE
.IP "\(bu" 4
Incorrect data or formatting
.RS 4
.IP "\(bu" 4
Is it really inaccurate?
.Sp
It could simply be an incomplete understanding of the context of the data, for example:
.Sp
In English we capitalize proper names (e.g. French).
.Sp
In other languages it may be perfectly acceptable for a language or territory name to not start with upper case letters.
.Sp
In that case a report about names not being capitalized like we do in English would be unwarranted.
.IP "\(bu" 4
Is it really mis-formatted?
.Sp
Sometimes something might look strange to us and we'd be tempted to report the problem. Keep in mind though that sometimes locale nuances can cause things to render in a way that non-native speakers may not understand.
.Sp
For example ArabicXs (ar) right-to-left text direction can seem strange when mixed with latin text. It's simply not wrong. You may be able to improve it by using the direction data to render it better (e.g. \s-1CSS\s0 or \s-1HTML\s0 attributes if the output is \s-1HTML\s0).
.Sp
Also, \s-1CLDR\s0 pattern formats can differ per locale.
.Sp
In cases like this a report would be unwarranted.
.RE
.RS 4
.RE
.RE
.RS 4
.RE
.SH "AUTHOR"
.IX Header "AUTHOR"
Daniel Muey  \f(CW\*(C`<http://drmuey.com/cpan_contact.pl>\*(C'\fR
.SH "LICENCE AND COPYRIGHT"
.IX Header "LICENCE AND COPYRIGHT"
Copyright (c) 2009, Daniel Muey \f(CW\*(C`<http://drmuey.com/cpan_contact.pl>\*(C'\fR. All rights reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See perlartistic.
.SH "DISCLAIMER OF WARRANTY"
.IX Header "DISCLAIMER OF WARRANTY"
\&\s-1BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE SOFTWARE \*(L"AS IS\*(R" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
NECESSARY SERVICING, REPAIR, OR CORRECTION.\s0
.PP
\&\s-1IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
THE SOFTWARE \s0(\s-1INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE\s0), \s-1EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.\s0