.\" 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 "DateTime::Locale 3"
.TH DateTime::Locale 3 "2019-03-28" "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"
DateTime::Locale \- Localization support for DateTime.pm
.SH "VERSION"
.IX Header "VERSION"
version 1.24
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use DateTime::Locale;
\&
\& my $loc = DateTime::Locale\->load(\*(Aqen\-GB\*(Aq);
\&
\& print $loc\->native_name, "\en", $loc\->datetime_format_long, "\en";
\&
\& # but mostly just things like ...
\&
\& my $dt = DateTime\->now( locale => \*(Aqfr\*(Aq );
\& print "Aujourd\*(Aqhui le mois est " . $dt\->month_name, "\en";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
DateTime::Locale is primarily a factory for the various locale subclasses. It
also provides some functions for getting information on all the available
locales.
.PP
If you want to know what methods are available for locale objects, then please
read the \f(CW\*(C`DateTime::Locale::FromData\*(C'\fR documentation.
.SH "USAGE"
.IX Header "USAGE"
This module provides the following class methods:
.ie n .SS "DateTime::Locale\->load( $locale_code | $locale_name )"
.el .SS "DateTime::Locale\->load( \f(CW$locale_code\fP | \f(CW$locale_name\fP )"
.IX Subsection "DateTime::Locale->load( $locale_code | $locale_name )"
Returns the locale object for the specified locale code or name \- see the
\&\f(CW\*(C`DateTime::Locale::Catalog\*(C'\fR documentation for the list of available codes and
names. The name provided may be either the English or native name.
.PP
If the requested locale is not found, a fallback search takes place to
find a suitable replacement.
.PP
The fallback search order is:
.PP
.Vb 5
\& {language}\-{script}\-{territory}
\& {language}\-{script}
\& {language}\-{territory}\-{variant}
\& {language}\-{territory}
\& {language}
.Ve
.PP
Eg. For the locale code \f(CW\*(C`es\-XX\-UNKNOWN\*(C'\fR the fallback search would be:
.PP
.Vb 4
\& es\-XX\-UNKNOWN # Fails \- no such locale
\& es\-XX # Fails \- no such locale
\& es # Found \- the es locale is returned as the
\& # closest match to the requested id
.Ve
.PP
Eg. For the locale code \f(CW\*(C`es\-Latn\-XX\*(C'\fR the fallback search would be:
.PP
.Vb 5
\& es\-Latn\-XX # Fails \- no such locale
\& es\-Latn # Fails \- no such locale
\& es\-XX # Fails \- no such locale
\& es # Found \- the es locale is returned as the
\& # closest match to the requested id
.Ve
.PP
If no suitable replacement is found, then an exception is thrown.
.PP
The loaded locale is cached, so that \fBlocale objects may be
singletons\fR. Calling \f(CW\*(C`DateTime::Locale\->register_from_data\*(C'\fR, \f(CW\*(C`DateTime::Locale\->add_aliases\*(C'\fR, or \f(CW\*(C`DateTime::Locale\->remove_alias\*(C'\fR
clears the cache.
.SS "DateTime::Locale\->codes"
.IX Subsection "DateTime::Locale->codes"
.Vb 2
\& my @codes = DateTime::Locale\->codes;
\& my $codes = DateTime::Locale\->codes;
.Ve
.PP
Returns an unsorted list of the available locale codes, or an array reference if
called in a scalar context. This list does not include aliases.
.SS "DateTime::Locale\->names"
.IX Subsection "DateTime::Locale->names"
.Vb 2
\& my @names = DateTime::Locale\->names;
\& my $names = DateTime::Locale\->names;
.Ve
.PP
Returns an unsorted list of the available locale names in English, or an array
reference if called in a scalar context.
.SS "DateTime::Locale\->native_names"
.IX Subsection "DateTime::Locale->native_names"
.Vb 2
\& my @names = DateTime::Locale\->native_names;
\& my $names = DateTime::Locale\->native_names;
.Ve
.PP
Returns an unsorted list of the available locale names in their native
language, or an array reference if called in a scalar context. All native
names use \s-1UTF\-8\s0 as appropriate.
.ie n .SS "DateTime::Locale\->register_from_data( $locale_data )"
.el .SS "DateTime::Locale\->register_from_data( \f(CW$locale_data\fP )"
.IX Subsection "DateTime::Locale->register_from_data( $locale_data )"
This method allows you to register a custom locale. The data for the locale is
specified as a hash (or hashref) where the keys match the method names given
in \f(CW\*(C`DateTime::Locale::FromData\*(C'\fR.
.PP
If you just want to make some small changes on top of an existing locale you
can get that locale's data by calling \f(CW\*(C`$locale\->locale_data\*(C'\fR.
.PP
Here is an example of making a custom locale based off of \f(CW\*(C`en\-US\*(C'\fR:
.PP
.Vb 4
\& my $locale = DateTime::Locale\->load(\*(Aqen\-US\*(Aq);
\& my %data = $locale\->locale_data;
\& $data{code} = \*(Aqen\-US\-CUSTOM\*(Aq;
\& $data{time_format_medium} = \*(AqHH:mm:ss\*(Aq;
\&
\& DateTime::Locale\->register_from_data(%data);
\&
\& # Prints 18:24:38
\& say DateTime\->now( locale => \*(Aqen\-US\-CUSTOM\*(Aq )\->strftime(\*(Aq%X\*(Aq);
\&
\& # Prints 6:24:38 PM
\& say DateTime\->now( locale => \*(Aqen\-US\*(Aq )\->strftime(\*(Aq%X\*(Aq);
.Ve
.PP
The keys that should be present in the hash are the same as the accessor
methods provided by DateTime::Locale::FromData, except for the following:
.ie n .IP "The *_code methods" 4
.el .IP "The \f(CW*_code\fR methods" 4
.IX Item "The *_code methods"
While you should provide a \f(CW\*(C`code\*(C'\fR key, the other methods like
\&\f(CW\*(C`language_code\*(C'\fR and \f(CW\*(C`script_code\*(C'\fR are determined by parsing the code.
.ie n .IP "All ""id"" returning methods" 4
.el .IP "All \f(CWid\fR returning methods" 4
.IX Item "All id returning methods"
These are aliases for the corresponding \f(CW*code\fR methods.
.ie n .IP """prefers_24_hour_time""" 4
.el .IP "\f(CWprefers_24_hour_time\fR" 4
.IX Item "prefers_24_hour_time"
This is determined by looking at the short time format to see how it formats
hours,
.ie n .IP """date_format_default"" and ""time_format_default""" 4
.el .IP "\f(CWdate_format_default\fR and \f(CWtime_format_default\fR" 4
.IX Item "date_format_default and time_format_default"
These are the corresponding medium formats.
.ie n .IP """datetime_format"" and ""datetime_format_default""" 4
.el .IP "\f(CWdatetime_format\fR and \f(CWdatetime_format_default\fR" 4
.IX Item "datetime_format and datetime_format_default"
This is the same as the medium format.
.ie n .IP """date_formats"" and ""time_formats""" 4
.el .IP "\f(CWdate_formats\fR and \f(CWtime_formats\fR" 4
.IX Item "date_formats and time_formats"
These are calculated as needed.
.ie n .IP """available_formats""" 4
.el .IP "\f(CWavailable_formats\fR" 4
.IX Item "available_formats"
This should be provided as a hashref where the keys are things like \f(CW\*(C`Gy\*(C'\fR or
\&\f(CW\*(C`MMMEd\*(C'\fR and the values are an actual format like \f(CW"y G"\fR or \f(CW"E, MMM d"\fR.
.ie n .IP """locale_data""" 4
.el .IP "\f(CWlocale_data\fR" 4
.IX Item "locale_data"
This is everything you pass in.
.SH "LOADING LOCALES IN A PRE-FORKING SYSTEM"
.IX Header "LOADING LOCALES IN A PRE-FORKING SYSTEM"
If you are running an application that does pre-forking (for example with
Starman), then you should try to load all the locales that you'll need in the
parent process. Locales are loaded on-demand, so loading them once in each
child will waste memory that could otherwise be shared.
.SH "CLDR DATA BUGS"
.IX Header "CLDR DATA BUGS"
Please be aware that all locale data has been generated from the \s-1CLDR \s0(Common
Locale Data Repository) project locales data). The data is incomplete, and may
contain errors in some locales.
.PP
When reporting errors in data, please check the primary data sources first,
then where necessary report errors directly to the primary source via the \s-1CLDR\s0
bug report system. See http://unicode.org/cldr/filing_bug_reports.html for
details.
.PP
Once these errors have been confirmed, please forward the error report and
corrections to the DateTime mailing list, datetime@perl.org.
.SH "AUTHOR EMERITUS"
.IX Header "AUTHOR EMERITUS"
Richard Evans wrote the first version of DateTime::Locale, including the tools
to extract the \s-1CLDR\s0 data.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
DateTime::Locale::Base
.PP
datetime@perl.org mailing list
.PP
http://datetime.perl.org/
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs may be submitted at <https://github.com/houseabsolute/DateTime\-Locale/issues>.
.PP
There is a mailing list available for users of this distribution,
<mailto:datetime@perl.org>.
.PP
I am also usually active on \s-1IRC\s0 as 'autarch' on \f(CW\*(C`irc://irc.perl.org\*(C'\fR.
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for DateTime-Locale can be found at <https://github.com/houseabsolute/DateTime\-Locale>.
.SH "DONATIONS"
.IX Header "DONATIONS"
If you'd like to thank me for the work I've done on this module, please
consider making a \*(L"donation\*(R" to me via PayPal. I spend a lot of free time
creating free software, and would appreciate any support you'd care to offer.
.PP
Please note that \fBI am not suggesting that you must do this\fR in order for me
to continue working on this particular software. I will continue to do so,
inasmuch as I have in the past, for as long as it interests me.
.PP
Similarly, a donation made in this way will probably not make me work on this
software much more, unless I get so many donations that I can consider working
on free software full time (let's all have a chuckle at that together).
.PP
To donate, log into PayPal and send money to autarch@urth.org, or use the
button at <http://www.urth.org/~autarch/fs\-donation.html>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky <autarch@urth.org>
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
.IP "\(bu" 4
Karen Etheridge <ether@cpan.org>
.IP "\(bu" 4
Mohammad S Anwar <mohammad.anwar@yahoo.com>
.IP "\(bu" 4
Ryley Breiddal <rbreiddal@presinet.com>
.IP "\(bu" 4
Sergey Leschenko <Sergey.Leschenko@portaone.com>
.IP "\(bu" 4
yasu47b <nakayamayasuhiro1986@gmail.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2003 \- 2019 by Dave Rolsky.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
.PP
The full text of the license can be found in the
\&\fI\s-1LICENSE\s0\fR file included with this distribution.