On Apache
Under GNU General Public License
2012-05-23 06:01 @38.107.179.239 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
DateTime::Locale(3pm) User Contributed Perl Documentation DateTime::Locale(3pm)
NAME
DateTime::Locale - Localization support for DateTime.pm
SYNOPSIS
use DateTime::Locale;
my $loc = DateTime::Locale->load('en_GB');
print $loc->native_locale_name, "\n",
$loc->long_datetime_format, "\n";
# but mostly just things like ...
my $dt = DateTime->now( locale => 'fr' );
print "Aujourd'hui le mois est " . $dt->month_name, "\n":
DESCRIPTION
DateTime::Locale is primarily a factory for the various locale subclasses. It also pro-
vides some functions for getting information on available locales.
If you want to know what methods are available for locale objects, then please read the
"DateTime::Locale::Base" documentation.
USAGE
This module provides the following class methods:
* load( $locale_id | $locale_name | $alias )
Returns the locale object for the specified locale id, name, or alias - see the "Date-
Time::LocaleCatalog" documentation for a list of built in names and ids. The name
provided may be either the English or native name.
If the requested locale is not found, a fallback search takes place to find a suitable
replacement.
The fallback search order is:
language_script_territory
language_script
language_territory_variant
language_territory
language
Eg. For locale "es_XX_UNKNOWN" the fallback search would be:
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
Eg. For locale "es_Latn_XX" the fallback search would be:
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
If no suitable replacement is found, then an exception is thrown.
Please note that if you provide an id to this method, then the returned locale
object's "id()" method will always return the value you gave, even if that value was
an alias to some other id.
This is done for forwards compatibility, in case something that is currently an alias
becomes a unique locale in the future.
This means that the value of "id()" and the object's class may not match.
The loaded locale is cached, so that locale objects may be singletons. Calling "reg-
ister()", "add_aliases()", or "remove_alias()" clears the cache.
* ids
my @ids = DateTime::Locale->ids;
my $ids = DateTime::Locale->ids;
Returns an unsorted list of the available locale ids, or an array reference if called
in a scalar context. This list does not include aliases.
* names
my @names = DateTime::Locale->names;
my $names = DateTime::Locale->names;
Returns an unsorted list of the available locale names in English, or an array refer-
ence if called in a scalar context.
* native_names
my @names = DateTime::Locale->native_names;
my $names = DateTime::Locale->native_names;
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 are utf8 encoded.
NB: Many locales are only partially translated, so some native locale names may still
contain some English.
* add_aliases ( $alias1 => $id1, $alias2 => $id2, ... )
Adds an alias to an existing locale id. This allows a locale to be "load()"ed by its
alias rather than id or name. Multiple aliases are allowed.
If the passed locale id is neither registered nor listed in "AVAILABLE LOCALES", an
exception is thrown.
DateTime::Locale->add_aliases( LastResort => 'es_ES' );
# Equivalent to DateTime::Locale->load('es_ES');
DateTime::Locale->load('LastResort');
You can also pass a hash reference to this method.
DateTime::Locale->add_aliases( { Default => 'en_GB',
Alternative => 'en_US',
LastResort => 'es_ES' } );
* remove_alias( $alias )
Removes a locale id alias, and returns true if the specified alias actually existed.
DateTime::Locale->add_aliases( LastResort => 'es_ES' );
# Equivalent to DateTime::Locale->load('es_ES');
DateTime::Locale->load('LastResort');
DateTime::Locale->remove_alias('LastResort');
# Throws an exception, 'LastResort' no longer exists
DateTime::Locale->load('LastResort');
* register( { ... }, { ... } )
This method allows you to register custom locales with the module. A single locale is
specified as a hash, and you may register multiple locales at once by passing an array
of hash references.
Until registered, custom locales cannot be instantiated via "load()" and will not be
returned by querying methods such as "ids()" or "names()".
register( id => $locale_id,
en_language => ..., # something like 'English' or 'Afar',
# All other keys are optional. These are:
en_script => ...,
en_territory => ...,
en_variant => ...,
native_language => ...,
native_sript => ...,
native_territory => ...,
native_variant => ...,
# Optional - defaults to DateTime::Locale::$locale_id
class => $class_name,
replace => $boolean
)
The locale id and English name are required, and the following formats should used
wherever possible:
id: languageId[_script][_territoryId[_variantId]]
Where: languageId = Lower case ISO 639 code -
Always choose 639-1 over 639-2 where possible.
script = Title Case ISO 15924 script code
territoryId = Upper case ISO 3166 code -
Always choose 3166-1 over 3166-2 where possible.
variantId = Upper case variant id -
Basically anything you want, since this is typically the
component that uniquely identifies a custom locale.
You cannot not use '@' or '=' in locale ids - these are reserved for future use. The
underscore (_) is the component separator, and should not be used for any other pur-
pose.
If the "native_*" components are supplied, they must be utf8 encoded and follow:
If omitted, the native name is assumed to be identical to the English name.
If class is supplied, it must be the full module name of your custom locale. If omit-
ted, the locale module is assumed to be a DateTime::Locale subclass.
Examples:
DateTime::Locale->register
( id => 'en_GB_RIDAS',
en_language => 'English',
en_territory => 'United Kingdom',
en_variant => 'Ridas Custom Locale',
);
# Returns instance of class DateTime::Locale::en_GB_RIDAS
my $l = DateTime::Locale->load('en_GB_RIDAS');
DateTime::Locale->register
( id => 'hu_HU',
en_language => 'Hungarian',
en_territory => Hungary',
native_language => 'Magyar',
native_territory => 'Magyarorszg',
);
# Returns instance of class DateTime::Locale::hu_HU
my $l = DateTime::Locale->load('hu_HU');
DateTime::Locale->register
( id => 'en_GB_RIDAS',
name => 'English United Kingdom Ridas custom locale',
class => 'Ridas::Locales::CustomGB',
);
# Returns instance of class Ridas::Locales::CustomGB
# NOT Ridas::Locales::Custom::en_GB_RIDAS !
my $l = DateTime::Locale->load('en_GB_RIDAS');
If you register a locale for an id that already exists, the "replace" parameter must
be true or an exception will be thrown.
The complete name for a registered locale is generated by joining together the lan-
guage, territory, and variant components with a single space.
This means that in the first example, the complete English and native names for the
locale would be "English United Kingdom Ridas Custom Locale", and in the second exam-
ple the complete English name is "Hungarian Hungary", while the complete native name
is "Magyar Magyarorszg". The locale will be loadable by these complete names (English
and native), via the "load()" method.
ADDING CUSTOM LOCALES
These are added in one of two ways:
1. Subclass an existing locale implementing only the changes you require.
2. Create a completely new locale.
In either case the locale MUST be registered before use.
Subclass an existing locale.
The following example sublasses the United Kingdom English locale to provide different
date/time formats:
package Ridas::Locale::en_GB_RIDAS1;
use strict;
use DateTime::Locale::en_GB;
@Ridas::Locale::en_GB_RIDAS1::ISA = qw ( DateTime::Locale::en_GB );
my $locale_id = 'en_GB_RIDAS1';
my $date_formats =
{
'full' => '%A %{day} %B %{ce_year}',
'long' => '%{day} %B %{ce_year}',
'medium' => '%{day} %b %{ce_year}',
'short' => '%{day}/%m/%y',
};
my $time_formats =
{
'full' => '%H h %{minute} %{time_zone_short_name}',
'long' => '%{hour12}:%M:%S %p',
'medium' => '%{hour12}:%M:%S %p',
'short' => '%{hour12}:%M %p',
};
sub short_date_format { $date_formats{short} }
sub medium_date_format { $date_formats{medium} }
sub long_date_format { $date_formats{long} }
sub full_date_format { $date_formats{full} }
sub short_time_format { $time_formats{short} }
sub medium_time_format { $time_formats{medium} }
sub long_time_format { $time_formats{long} }
sub full_time_format { $time_formats{full} }
1;
Now register it:
DateTime::Locale->register
( id => 'en_GB_RIDAS1',
# name, territory, and variant as described in register() documentation
class => 'Ridas::Locale::en_GB_RIDAS1' );
Creating a completely new locale
A completely new custom locale must implement the following methods:
id
month_names
month_abbreviations
day_names
day_abbreviations
am_pms
eras
short_date_format
medium_date_format
long_date_format
full_date_format
short_time_format
medium_time_format
long_time_format
full_time_format
datetime_format_pattern_order
date_parts_order
_default_date_format_length
_default_time_format_length
See "DateTime::Locale::Base" for a description of each method, and take a look at Date-
Time/Locale/root.pm for an example of a complete implementation.
You are, of course, free to subclass "DateTime::Locale::Base" if you want to, though this
is not required.
Once created, remember to register it!
Of course, you can always do the registration in the module itself, and simply load it
before using it.
LOCALE OBJECT METHODS
All objects that inherit from "DateTime::Locale::Base" will offer certain methods. All
the included locales are "DateTime::Locale::Base" subclasses.
The following methods can be used to get information about the locale's id and name.
* id
The complete locale id, something like "en_US".
* language_id
The language portion of the id, like "en".
* script_id
The script portion of the id, like "Hant".
* territory_id
The territory portion of the id, like "US".
* variant_id
The variant portion of the id, like "PREEURO".
* name
The locale's complete name, which always includes at least a language component, plus
optional territory and variant components. Something like "English United States".
The value returned will always be in English.
* language
* script
* territory
* variant
The relevant component from the locale's complete name, like "English" or "United
States".
* native_name
The locale's complete name in localized form as a UTF-8 string.
* native_language
* native_script
* native_territory
* native_variant
The relevant component from the locale's complete native name as a UTF-8 string.
The following methods all accept a "DateTime.pm" object and return a localized name.
* month_name ($dt)
* month_abbreviation ($dt)
* day_name ($dt)
* day_abbreviation ($dt)
* am_pm ($dt)
The following methods return strings appropriate for the "DateTime.pm" "strftime()"
method:
* full_date_format
* long_date_format
* medium_date_format
* short_date_format
* full_time_format
* long_time_format
* medium_time_format
* short_time_format
* full_datetime_format
* long_datetime_format
* medium_datetime_format
* short_datetime_format
The following methods deal with the default format lengths:
default_date_format_length
default_time_format_length
These methods return one of "full", "long", "medium", or "short", indicating the cur-
rent default format length.
The default when an object is created is determined by the CLDR locale data.
set_default_date_format_length ($length)
set_default_time_format_length ($length)
These methods accept one of "full", "long", "medium", or "short", indicating the new
default format length.
The following methods can be used to get the object's raw localization data. If a method
returns a reference, altering it will alter the object, so make a copy if you need to do
so.
* month_names
Returns an array reference containing the full names of the months, with January as
the first month.
* month_abbreviations
Returns an array reference containing the abbreviated names of the months, with Jan-
uary as the first month.
* month_narrows
Returns an array reference containing the narrow names of the months, with January as
the first month. Narrow names are the shortest possible names, and may not be unique.
* day_names
Returns an array reference containing the full names of the days, with Monday as the
first day.
* day_abbreviations
Returns an array reference containing the abbreviated names of the days, with Monday
as the first day.
* day_narrows
Returns an array reference containing the narrow names of the days, with Monday as the
first day. Narrow names are the shortest possible names, and may not be unique.
* am_pms
Returns an array reference containing the localized forms of "AM" and "PM".
* eras
Returns an array reference containing the localized forms of "BCE" and "CE".
* date_formats
Returns a hash reference containing the date formats used for the locale. The hash
contains the keys "long", "full", "medium", and "short".
* time_formats
Returns a hash reference containing the time formats used for the locale. The hash
contains the keys "long", "full", "medium", and "short".
* date_before_time
This returns a boolean value indicating whether or not the date comes before the time
when formatting a complete date and time for presentation.
* date_parts_order
This returns a string indicating the order of the parts of a date that is in the form
XX/YY/ZZ. The possible values are "dmy", "mdy", "ydm" and "ymd".
SUPPORT
Please be aware that all locale data has been generated from the CLDR (Common Locale Data
Repository) project locales data). The data is currently incomplete, and will contain
errors in some locales.
When reporting errors in data, please check the primary data sources first, then where
necessary report errors directly to the primary source via the CLDR bug report system. See
http://unicode.org/cldr/filing_bug_reports.html for details.
Once these errors have been confirmed, please forward the error report and corrections to
the DateTime mailing list, datetime AT perl.org.
Support for this module is provided via the datetime AT perl.org email list. See
http://lists.perl.org/ for more details.
AUTHORS
Richard Evans <rich AT ridas.com>
Dave Rolsky <autarch AT urth.org>
These modules are loosely based on the DateTime::Language modules, which were in turn
based on the Date::Language modules from Graham Barr's TimeDate distribution.
Thanks to Rick Measham for providing the Java to strftime pattern conversion routines used
during locale generation.
COPYRIGHT
Copyright (c) 2003 Richard Evans. Copyright (c) 2004-2006 David Rolsky. All rights
reserved.
This program is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
The locale modules in directory "DateTime/Locale/" have been generated from data provided
by the CLDR project, see "DateTime/Locale/LICENSE.cldr" for details on the CLDR data's
license.
SEE ALSO
DateTime::Locale::Base
datetime AT perl.org mailing list
http://datetime.perl.org/
perl v5.8.8 2007-11-18 DateTime::Locale(3pm)
Generated by $Id: phpMan.php,v 4.49 2006/02/26 13:18:18 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2012-05-23 06:01 @38.107.179.239 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)