← Index
NYTProf Performance Profile   « block view • line view • sub view »
For 05.Domain_and_Item.t
  Run on Tue May 4 17:21:41 2010
Reported on Tue May 4 17:23:17 2010

File /usr/local/lib/perl5/site_perl/5.10.1/DateTime/Locale.pm
Statements Executed 15222
Statement Execution Time 51.9ms
Subroutines — ordered by exclusive time
Calls P F Exclusive
Time
Inclusive
Time
Subroutine
4661117.7ms34.7msDateTime::Locale::::_registerDateTime::Locale::_register
1118.89ms8.94msDateTime::Locale::::BEGIN@11DateTime::Locale::BEGIN@11
1113.12ms13.2msDateTime::Locale::::add_aliasesDateTime::Locale::add_aliases
423112.88ms10.1msDateTime::Locale::::_registered_idDateTime::Locale::_registered_id
1112.53ms37.2msDateTime::Locale::::registerDateTime::Locale::register
1112.34ms3.12msDateTime::Locale::::BEGIN@10DateTime::Locale::BEGIN@10
4043598µs5.57msDateTime::Locale::::loadDateTime::Locale::load
211324µs3.81msDateTime::Locale::::_load_class_from_idDateTime::Locale::_load_class_from_id
46612294µs294µsDateTime::Locale::::CORE:matchDateTime::Locale::CORE:match (opcode)
11136µs50.6msDateTime::Locale::::BEGIN@148DateTime::Locale::BEGIN@148
11135µs35µsDateTime::Locale::::BEGIN@6DateTime::Locale::BEGIN@6
11114µs80µsDateTime::Locale::::BEGIN@12DateTime::Locale::BEGIN@12
11114µs17µsDateTime::Locale::::BEGIN@3DateTime::Locale::BEGIN@3
1117µs16µsDateTime::Locale::::BEGIN@4DateTime::Locale::BEGIN@4
0000s0sDateTime::Locale::::_guess_idDateTime::Locale::_guess_id
0000s0sDateTime::Locale::::_parse_idDateTime::Locale::_parse_id
0000s0sDateTime::Locale::::idsDateTime::Locale::ids
0000s0sDateTime::Locale::::namesDateTime::Locale::names
0000s0sDateTime::Locale::::native_namesDateTime::Locale::native_names
0000s0sDateTime::Locale::::remove_aliasDateTime::Locale::remove_alias
Call graph for these subroutines as a Graphviz dot language file.
Line State
ments
Time
on line
Calls Time
in subs
Code
1package DateTime::Locale;
2
3320µs220µs
# spent 17µs (14+3) within DateTime::Locale::BEGIN@3 which was called # once (14µs+3µs) by DateTime::BEGIN@41 at line 3
use strict;
# spent 17µs making 1 call to DateTime::Locale::BEGIN@3 # spent 3µs making 1 call to strict::import
4319µs225µs
# spent 16µs (7+9) within DateTime::Locale::BEGIN@4 which was called # once (7µs+9µs) by DateTime::BEGIN@41 at line 4
use warnings;
# spent 16µs making 1 call to DateTime::Locale::BEGIN@4 # spent 9µs making 1 call to warnings::import
5
6352µs135µs
# spent 35µs within DateTime::Locale::BEGIN@6 which was called # once (35µs+0s) by DateTime::BEGIN@41 at line 6
use 5.006;
# spent 35µs making 1 call to DateTime::Locale::BEGIN@6
7
8# Loading this here isn't necessary, but it makes it easier to catch
9# syntax errors when testing.
103109µs13.12ms
# spent 3.12ms (2.34+784µs) within DateTime::Locale::BEGIN@10 which was called # once (2.34ms+784µs) by DateTime::BEGIN@41 at line 10
use DateTime::Locale::Base;
# spent 3.12ms making 1 call to DateTime::Locale::BEGIN@10
113144µs18.94ms
# spent 8.94ms (8.89+52µs) within DateTime::Locale::BEGIN@11 which was called # once (8.89ms+52µs) by DateTime::BEGIN@41 at line 11
use DateTime::Locale::Catalog;
# spent 8.94ms making 1 call to DateTime::Locale::BEGIN@11
123433µs2146µs
# spent 80µs (14+66) within DateTime::Locale::BEGIN@12 which was called # once (14µs+66µs) by DateTime::BEGIN@41 at line 12
use Params::Validate qw( validate validate_pos SCALAR );
# spent 80µs making 1 call to DateTime::Locale::BEGIN@12 # spent 66µs making 1 call to Exporter::import
13
141900nsour $VERSION = '0.44';
15
16
171200nsmy %Class;
1810smy %DataForID;
1910smy %NameToID;
2010smy %NativeNameToID;
2110smy %AliasToID;
2210smy %IDToExtra;
23
2410smy %LoadCache;
25
26sub register
27
# spent 37.2ms (2.53+34.7) within DateTime::Locale::register which was called # once (2.53ms+34.7ms) by DateTime::Locale::BEGIN@148 at line 149
{
281700ns my $class = shift;
29
301600ns %LoadCache = ();
31
3211.96ms46634.7ms if ( ref $_[0] )
# spent 34.7ms making 466 calls to DateTime::Locale::_register, avg 74µs/call
33 {
34 $class->_register(%$_) foreach @_;
35 }
36 else
37 {
38 $class->_register(@_);
39 }
40}
41
42sub _register
43
# spent 34.7ms (17.7+17.0) within DateTime::Locale::_register which was called 466 times, avg 74µs/call: # 466 times (17.7ms+17.0ms) by DateTime::Locale::register at line 32, avg 74µs/call
{
44466189µs my $class = shift;
45
4646626.4ms46616.7ms my %p = validate( @_,
# spent 16.7ms making 466 calls to Params::Validate::_validate, avg 36µs/call
47 { id => { type => SCALAR },
48
49 en_language => { type => SCALAR },
50 en_script => { type => SCALAR, optional => 1 },
51 en_territory => { type => SCALAR, optional => 1 },
52 en_variant => { type => SCALAR, optional => 1 },
53
54 native_language => { type => SCALAR, optional => 1 },
55 native_script => { type => SCALAR, optional => 1 },
56 native_territory => { type => SCALAR, optional => 1 },
57 native_variant => { type => SCALAR, optional => 1 },
58
59 class => { type => SCALAR, optional => 1 },
60 replace => { type => SCALAR, default => 0 },
61 } );
62
63466193µs my $id = $p{id};
64
654661.05ms466294µs die "'\@' or '=' are not allowed in locale ids"
# spent 294µs making 466 calls to DateTime::Locale::CORE:match, avg 630ns/call
66 if $id =~ /[\@=]/;
67
68466303µs die "You cannot replace an existing locale ('$id') unless you also specify the 'replace' parameter as true\n"
69 if ! delete $p{replace} && exists $DataForID{$id};
70
71466118µs $p{native_language} = $p{en_language}
72 unless exists $p{native_language};
73
7446648µs my @en_pieces;
754661µs my @native_pieces;
76466354µs foreach my $p ( qw( language script territory variant ) )
77 {
781864893µs push @en_pieces, $p{"en_$p"} if exists $p{"en_$p"};
791864993µs push @native_pieces, $p{"native_$p"} if exists $p{"native_$p"};
80 }
81
82466342µs $p{en_complete_name} = join ' ', @en_pieces;
83466316µs $p{native_complete_name} = join ' ', @native_pieces;
84
85466381µs $DataForID{$id} = \%p;
86
87466370µs $NameToID{ $p{en_complete_name} } = $id;
88466335µs $NativeNameToID{ $p{native_complete_name} } = $id;
89
904661.59ms $Class{$id} = $p{class} if defined exists $p{class};
91}
92
93sub _registered_id
94
# spent 10.1ms (2.88+7.21) within DateTime::Locale::_registered_id which was called 423 times, avg 24µs/call: # 423 times (2.88ms+7.21ms) by DateTime::Locale::add_aliases at line 114, avg 24µs/call
{
9542348µs shift;
964239.15ms4237.21ms my ($id) = validate_pos( @_, { type => SCALAR } );
# spent 7.21ms making 423 calls to Params::Validate::_validate_pos, avg 17µs/call
97
98423134µs return 1 if $AliasToID{$id};
99423964µs return 1 if $DataForID{$id};
100
101 return 0;
102}
103
104sub add_aliases
105
# spent 13.2ms (3.12+10.1) within DateTime::Locale::add_aliases which was called # once (3.12ms+10.1ms) by DateTime::Locale::BEGIN@148 at line 150
{
1061300ns shift;
107
1081500ns %LoadCache = ();
109
1101150µs my $aliases = ref $_[0] ? $_[0] : {@_};
111
1121541µs while ( my ( $alias, $id ) = each %$aliases )
113 {
114423503µs42310.1ms die "Unregistered locale '$id' cannot be used as an alias target for $alias"
# spent 10.1ms making 423 calls to DateTime::Locale::_registered_id, avg 24µs/call
115 unless __PACKAGE__->_registered_id($id);
116
117423153µs die "Can't alias an id to itself"
118 if $alias eq $id;
119
120 # check for overwrite?
121
122423337µs my %seen = ( $alias => 1, $id => 1 );
12342369µs my $copy = $id;
124423161µs while ( $copy = $AliasToID{$copy} )
125 {
126 die "Creating an alias from $alias to $id would create a loop.\n"
127 if $seen{$copy};
128
129 $seen{$copy} = 1;
130 }
131
132423351µs $AliasToID{$alias} = $id;
133 }
134}
135
136sub remove_alias
137{
138 shift;
139
140 %LoadCache = ();
141
142 my ($alias) = validate_pos( @_, { type => SCALAR } );
143
144 return delete $AliasToID{$alias};
145}
146
147BEGIN
148
# spent 50.6ms (36µs+50.6) within DateTime::Locale::BEGIN@148 which was called # once (36µs+50.6ms) by DateTime::BEGIN@41 at line 151
{
149124µs237.2ms __PACKAGE__->register( DateTime::Locale::Catalog->Locales() );
# spent 37.2ms making 1 call to DateTime::Locale::register # spent 16µs making 1 call to DateTime::Locale::Catalog::Locales
150113µs213.4ms __PACKAGE__->add_aliases( DateTime::Locale::Catalog->Aliases() );
# spent 13.2ms making 1 call to DateTime::Locale::add_aliases # spent 158µs making 1 call to DateTime::Locale::Catalog::Aliases
1511703µs150.6ms}
# spent 50.6ms making 1 call to DateTime::Locale::BEGIN@148
152
153sub ids { wantarray ? keys %DataForID : [ keys %DataForID ] }
154sub names { wantarray ? keys %NameToID : [ keys %NameToID ] }
155sub native_names { wantarray ? keys %NativeNameToID : [ keys %NativeNameToID ] }
156
157# These are hardcoded for backwards comaptibility with the
158# DateTime::Language code.
159110µsmy %OldAliases =
160 ( 'Afar' => 'aa',
161 'Amharic' => 'am_ET',
162 'Austrian' => 'de_AT',
163 'Brazilian' => 'pt_BR',
164 'Czech' => 'cs_CZ',
165 'Danish' => 'da_DK',
166 'Dutch' => 'nl_NL',
167 'English' => 'en_US',
168 'French' => 'fr_FR',
169 # 'Gedeo' => undef, # XXX
170 'German' => 'de_DE',
171 'Italian' => 'it_IT',
172 'Norwegian' => 'no_NO',
173 'Oromo' => 'om_ET', # Maybe om_KE or plain om ?
174 'Portugese' => 'pt_PT',
175 'Sidama' => 'sid',
176 'Somali' => 'so_SO',
177 'Spanish' => 'es_ES',
178 'Swedish' => 'sv_SE',
179 'Tigre' => 'tig',
180 'TigrinyaEthiopian' => 'ti_ET',
181 'TigrinyaEritrean' => 'ti_ER',
182 );
183
184sub load
185
# spent 5.57ms (598µs+4.97) within DateTime::Locale::load which was called 40 times, avg 139µs/call: # 17 times (281µs+568µs) by DateTime::Locale::Base::STORABLE_thaw at line 359 of DateTime/Locale/Base.pm, avg 50µs/call # 17 times (211µs+445µs) by DateTime::new at line 204 of DateTime.pm, avg 39µs/call # 5 times (85µs+225µs) by DateTime::Format::Strptime::new at line 143 of DateTime/Format/Strptime.pm, avg 62µs/call # once (21µs+3.73ms) by DateTime::DefaultLocale at line 100 of DateTime.pm
{
1864023µs my $class = shift;
187401.51ms401.16ms my ($name) = validate_pos( @_, { type => SCALAR } );
# spent 1.16ms making 40 calls to Params::Validate::_validate_pos, avg 29µs/call
188
189 # Support RFC 3066 language tags, which use '-' instead of '_'.
1904027µs $name =~ tr/-/_/;
191
1924015µs my $key = $name;
193
19440205µs return $LoadCache{$key} if exists $LoadCache{$key};
195
196 # Custom class registered by user
19723µs if ( $Class{$name} )
198 {
199 return $LoadCache{$key} = $class->_load_class_from_id( $name, $Class{$name} )
200 }
201
202 # special case for backwards compatibility with DT::Language
20322µs $name = $OldAliases{$name} if exists $OldAliases{$name};
204
205219µs23.81ms if ( exists $DataForID{$name} || exists $AliasToID{$name} )
# spent 3.81ms making 2 calls to DateTime::Locale::_load_class_from_id, avg 1.91ms/call
206 {
207 return $LoadCache{$key} = $class->_load_class_from_id($name);
208 }
209
210 foreach my $h ( \%NameToID, \%NativeNameToID )
211 {
212 return $LoadCache{$key} = $class->_load_class_from_id( $h->{$name} )
213 if exists $h->{$name};
214 }
215
216 if ( my $id = $class->_guess_id($name) )
217 {
218 return $LoadCache{$key} = $class->_load_class_from_id($id);
219 }
220
221 die "Invalid locale name or id: $name\n";
222}
223
224sub _guess_id
225{
226 my $class = shift;
227 my $name = shift;
228
229 # Strip off charset for LC_* ids : en_GB.UTF-8 etc
230 $name =~ s/\..*$//;
231
232 my ($language, $script, $territory, $variant ) =
233 _parse_id($name);
234
235 my @guesses;
236
237 if ( defined $script )
238 {
239 my $guess = join '_', lc $language, ucfirst lc $script;
240
241 push @guesses, $guess;
242
243 $guess .= '_' . uc $territory if defined $territory;
244
245 # version with script comes first
246 unshift @guesses, $guess;
247 }
248
249 if ( defined $variant )
250 {
251 push @guesses,
252 join '_', lc $language, uc $territory, uc $variant;
253 }
254
255 if ( defined $territory )
256 {
257 push @guesses,
258 join '_', lc $language, uc $territory;
259 }
260
261 push @guesses, lc $language;
262
263 foreach my $id (@guesses)
264 {
265 return $id
266 if exists $DataForID{$id} || exists $AliasToID{$id};
267 }
268}
269
270sub _parse_id
271{
272 $_[0] =~ /([a-z]+) # id
273 (?: _([A-Z][a-z]+) )? # script - Title Case - optional
274 (?: _([A-Z]+) )? # territory - ALL CAPS - optional
275 (?: _([A-Z]+) )? # variant - ALL CAPS - optional
276 /x;
277
278 return $1, $2, $3, $4;
279}
280
281sub _load_class_from_id
282
# spent 3.81ms (324µs+3.49) within DateTime::Locale::_load_class_from_id which was called 2 times, avg 1.91ms/call: # 2 times (324µs+3.49ms) by DateTime::Locale::load at line 205, avg 1.91ms/call
{
28321µs my $class = shift;
2842800ns my $id = shift;
2852900ns my $real_class = shift;
286
287 # We want the first alias for which there is data, even if it has
288 # no corresponding .pm file. There may be multiple levels of
289 # alias to go through.
2902700ns my $data_id = $id;
29123µs while ( exists $AliasToID{$data_id} && ! exists $DataForID{$data_id} )
292 {
293 $data_id = $AliasToID{$data_id};
294 }
295
29623µs $real_class ||= "DateTime::Locale::$data_id";
297
298230µs27µs unless ( $real_class->can('new') )
# spent 7µs making 2 calls to UNIVERSAL::can, avg 4µs/call
299 {
3001104µs eval "require $real_class";
301
3021500ns die $@ if $@;
303 }
304
305220µs266µs my $locale = $real_class->new( %{ $DataForID{$data_id} },
# spent 66µs making 2 calls to DateTime::Locale::Base::new, avg 33µs/call
306 id => $id,
307 );
308
30921µs return $locale if $DateTime::Locale::InGenerator;
310
311214µs22µs if ( $locale->can('cldr_version') )
# spent 2µs making 2 calls to UNIVERSAL::can, avg 1µs/call
312 {
31325µs24µs my $object_version = $locale->cldr_version();
# spent 4µs making 2 calls to DateTime::Locale::en_US::cldr_version, avg 2µs/call
314210µs25µs my $catalog_version = DateTime::Locale::Catalog->CLDRVersion();
# spent 5µs making 2 calls to DateTime::Locale::Catalog::CLDRVersion, avg 2µs/call
315
31622µs if ( $object_version ne $catalog_version )
317 {
318 warn "Loaded $real_class, which is from an older version ($object_version)"
319 . "of the CLDR database than this installation of"
320 . "DateTime::Locale ($catalog_version).\n";
321 }
322 }
323
32428µs return $locale;
325}
326
327116µs1;
328
329__END__
330
331=pod
332
333=encoding utf8
334
335=head1 NAME
336
337DateTime::Locale - Localization support for DateTime.pm
338
339=head1 SYNOPSIS
340
341 use DateTime::Locale;
342
343 my $loc = DateTime::Locale->load('en_GB');
344
345 print $loc->native_locale_name(), "\n",
346 $loc->datetime_format_long(), "\n";
347
348 # but mostly just things like ...
349
350 my $dt = DateTime->now( locale => 'fr' );
351 print "Aujourd'hui le mois est " . $dt->month_name(), "\n";
352
353=head1 DESCRIPTION
354
355DateTime::Locale is primarily a factory for the various locale
356subclasses. It also provides some functions for getting information on
357all the available locales.
358
359If you want to know what methods are available for locale objects,
360then please read the C<DateTime::Locale::Base> documentation.
361
362=head1 USAGE
363
364This module provides the following class methods:
365
366=head2 DateTime::Locale->load( $locale_id | $locale_name | $alias )
367
368Returns the locale object for the specified locale id, name, or alias
369- see the C<DateTime::Locale::Catalog> documentation for a list of
370built in names and ids. The name provided may be either the English
371or native name.
372
373If the requested locale is not found, a fallback search takes place to
374find a suitable replacement.
375
376The fallback search order is:
377
378 language_script_territory
379 language_script
380 language_territory_variant
381 language_territory
382 language
383
384Eg. For locale C<es_XX_UNKNOWN> the fallback search would be:
385
386 es_XX_UNKNOWN # Fails - no such locale
387 es_XX # Fails - no such locale
388 es # Found - the es locale is returned as the
389 # closest match to the requested id
390
391Eg. For locale C<es_Latn_XX> the fallback search would be:
392
393 es_Latn_XX # Fails - no such locale
394 es_Latn # Fails - no such locale
395 es_XX # Fails - no such locale
396 es # Found - the es locale is returned as the
397 # closest match to the requested id
398
399If no suitable replacement is found, then an exception is thrown.
400
401Please note that if you provide an B<id> to this method, then the
402returned locale object's C<id()> method will B<always> return the
403value you gave, even if that value was an alias to some other id.
404
405This is done for forwards compatibility, in case something that is
406currently an alias becomes a unique locale in the future.
407
408This means that the value of C<< $locale->id() >> and the object's
409class may not match.
410
411The loaded locale is cached, so that B<locale objects may be
412singletons>. Calling C<< DateTime::Locale->register() >>, C<<
413DateTime::Locale->add_aliases() >>, or C<<
414DateTime::Locale->remove_alias() >> clears the cache.
415
416=head2 DateTime::Locale->ids()
417
418 my @ids = DateTime::Locale->ids();
419 my $ids = DateTime::Locale->ids();
420
421Returns an unsorted list of the available locale ids, or an array
422reference if called in a scalar context. This list does not include
423aliases.
424
425=head2 DateTime::Locale->names()
426
427 my @names = DateTime::Locale->names();
428 my $names = DateTime::Locale->names();
429
430Returns an unsorted list of the available locale names in English, or
431an array reference if called in a scalar context.
432
433=head2 DateTime::Locale->native_names()
434
435 my @names = DateTime::Locale->native_names();
436 my $names = DateTime::Locale->native_names();
437
438Returns an unsorted list of the available locale names in their native
439language, or an array reference if called in a scalar context. All
440native names are utf8 encoded.
441
442B<NB>: Many locales are only partially translated, so some native
443locale names may still contain some English.
444
445=head2 DateTime::Locale->add_aliases ( $alias1 => $id1, $alias2 => $id2, ... )
446
447Adds an alias to an existing locale id. This allows a locale to be
448loaded by its alias rather than id or name. Multiple aliases are
449allowed.
450
451If the passed locale id is neither registered nor listed in
452L<DateTime::Local::Catalog>'s list of ids, an exception is thrown.
453
454 DateTime::Locale->add_aliases( LastResort => 'es_ES' );
455
456 # Equivalent to DateTime::Locale->load('es_ES');
457 DateTime::Locale->load('LastResort');
458
459You can also pass a hash reference to this method.
460
461 DateTime::Locale->add_aliases( { Default => 'en_GB',
462 Alternative => 'en_US',
463 LastResort => 'es_ES' } );
464
465=head2 DateTime::Locale->remove_alias( $alias )
466
467Removes a locale id alias, and returns true if the specified alias
468actually existed.
469
470 DateTime::Locale->add_aliases( LastResort => 'es_ES' );
471
472 # Equivalent to DateTime::Locale->load('es_ES');
473 DateTime::Locale->load('LastResort');
474
475 DateTime::Locale->remove_alias('LastResort');
476
477 # Throws an exception, 'LastResort' no longer exists
478 DateTime::Locale->load('LastResort');
479
480=head2 DateTime::Locale->register( { ... }, { ... } )
481
482This method allows you to register custom locales with the module. A
483single locale is specified as a hash, and you may register multiple
484locales at once by passing an array of hash references.
485
486Until registered, custom locales cannot be instantiated via C<load()>
487and will not be returned by querying methods such as C<ids()> or
488C<names()>.
489
490 register( id => $locale_id,
491 en_language => ..., # something like 'English' or 'Afar',
492
493 # All other keys are optional. These are:
494 en_script => ...,
495 en_territory => ...,
496 en_variant => ...,
497
498 native_language => ...,
499 native_sript => ...,
500 native_territory => ...,
501 native_variant => ...,
502
503 # Optional - defaults to DateTime::Locale::$locale_id
504 class => $class_name,
505
506 replace => $boolean
507 )
508
509The locale id and English name are required, and the following formats
510should used wherever possible:
511
512 id: languageId[_script][_territoryId[_variantId]]
513
514 Where: languageId = Lower case ISO 639 code -
515 Always choose 639-1 over 639-2 where possible.
516
517 script = Title Case ISO 15924 script code
518
519 territoryId = Upper case ISO 3166 code -
520 Always choose 3166-1 over 3166-2 where possible.
521
522 variantId = Upper case variant id -
523 Basically anything you want, since this is typically the
524 component that uniquely identifies a custom locale.
525
526You cannot not use '@' or '=' in locale ids - these are reserved for
527future use. The underscore (_) is the component separator, and should
528not be used for any other purpose.
529
530If the "native_*" components are supplied, they must be utf8 encoded.
531
532If omitted, the native name is assumed to be identical to the English
533name.
534
535If class is supplied, it must be the full module name of your custom
536locale. If omitted, the locale module is assumed to be a
537DateTime::Locale subclass.
538
539Examples:
540
541 DateTime::Locale->register
542 ( id => 'en_GB_RIDAS',
543 en_language => 'English',
544 en_territory => 'United Kingdom',
545 en_variant => 'Ridas Custom Locale',
546 );
547
548 # Returns instance of class DateTime::Locale::en_GB_RIDAS
549 my $l = DateTime::Locale->load('en_GB_RIDAS');
550
551 DateTime::Locale->register
552 ( id => 'hu_HU',
553 en_language => 'Hungarian',
554 en_territory => Hungary',
555 native_language => 'Magyar',
556 native_territory => 'Magyarország',
557 );
558
559 # Returns instance of class DateTime::Locale::hu_HU
560 my $l = DateTime::Locale->load('hu_HU');
561
562 DateTime::Locale->register
563 ( id => 'en_GB_RIDAS',
564 name => 'English United Kingdom Ridas custom locale',
565 class => 'Ridas::Locales::CustomGB',
566 );
567
568 # Returns instance of class Ridas::Locales::CustomGB
569 # NOT Ridas::Locales::Custom::en_GB_RIDAS !
570 my $l = DateTime::Locale->load('en_GB_RIDAS');
571
572If you register a locale for an id that is already registered, the
573"replace" parameter must be true or an exception will be thrown.
574
575The complete name for a registered locale is generated by joining
576together the language, territory, and variant components with a single
577space.
578
579This means that in the first example, the complete English and native
580names for the locale would be "English United Kingdom Ridas Custom
581Locale", and in the second example the complete English name is
582"Hungarian Hungary", while the complete native name is "Magyar
583Magyarország". The locale will be loadable by these complete names
584(English and native), via the C<load()> method.
585
586=head1 ADDING CUSTOM LOCALES
587
588These are added in one of two ways:
589
590=over 4
591
592=item 1.
593
594Subclass an existing locale implementing only the changes you require.
595
596=item 2.
597
598Create a completely new locale.
599
600=back
601
602In either case the locale MUST be registered before use.
603
604=head2 Subclassing an existing locale
605
606The following example sublasses the United Kingdom English locale to
607provide different date/time formats:
608
609 package Ridas::Locale::en_GB_RIDAS1;
610
611 use strict;
612 use DateTime::Locale::en_GB;
613
614 use base 'DateTime::Locale::en_GB';
615
616 my $locale_id = 'en_GB_RIDAS1';
617
618 my $date_formats =
619 {
620 'full' => '%A %{day} %B %{ce_year}',
621 'long' => '%{day} %B %{ce_year}',
622 'medium' => '%{day} %b %{ce_year}',
623 'short' => '%{day}/%m/%y',
624 };
625
626 my $time_formats =
627 {
628 'full' => '%H h %{minute} %{time_zone_short_name}',
629 'long' => '%{hour12}:%M:%S %p',
630 'medium' => '%{hour12}:%M:%S %p',
631 'short' => '%{hour12}:%M %p',
632 };
633
634 sub date_format_full { $date_formats{full} }
635 sub date_format_long { $date_formats{long} }
636 sub date_format_medium { $date_formats{medium} }
637 sub date_format_short { $date_formats{short} }
638
639 sub time_format_full { $time_formats{full} }
640 sub time_format_long { $time_formats{long} }
641 sub time_format_medium { $time_formats{medium} }
642 sub time_format_short { $time_formats{short} }
643
644 1;
645
646Now register it:
647
648 DateTime::Locale->register
649 ( id => 'en_GB_RIDAS1',
650
651 # name, territory, and variant as described in register() documentation
652
653 class => 'Ridas::Locale::en_GB_RIDAS1',
654 );
655
656=head2 Creating a completely new locale
657
658You are, of course, free to subclass C<DateTime::Locale::Base> if you
659want to, though this is not required.
660
661Remember to register your custom locale!
662
663Of course, you can always do the registration in the module itself,
664and simply load it before using it.
665
666A completely new custom locale, one which does not subclass
667L<DateTime::Locale::Base>, must implement a number of methods.
668
669The following methods can be used to get information about the
670locale's id and name.
671
672=over 4
673
674=item * $locale->id()
675
676The complete locale id, something like "en_US".
677
678=item * $locale->language_id()
679
680The language portion of the id, like "en".
681
682=item * $locale->script_id()
683
684The script portion of the id, like "Hant".
685
686=item * $locale->territory_id()
687
688The territory portion of the id, like "US".
689
690=item * $locale->variant_id()
691
692The variant portion of the id, like "PREEURO".
693
694=item * $locale->name()
695
696The locale's complete name, which always includes at least a language
697component, plus optional territory and variant components. Something
698like "English United States". The value returned will always be in
699English.
700
701=item * $locale->language()
702
703=item * $locale->script()
704
705=item * $locale->territory()
706
707=item * $locale->variant()
708
709The relevant component from the locale's complete name, like "English"
710or "United States".
711
712=item * $locale->native_name()
713
714The locale's complete name in localized form as a UTF-8 string.
715
716=item * $locale->native_language()
717
718=item * $locale->native_script()
719
720=item * $locale->native_territory()
721
722=item * $locale->native_variant()
723
724The relevant component from the locale's complete native name as a
725UTF-8 string.
726
727=back
728
729The following methods all return an array reference containing the
730specified data.
731
732The format methods return strings that might be used a part of a
733string, like "the month of July", and should always return a set of
734unique values. The stand alone values are for use in things like
735calendars, and the narrow form may not be unique (for example, in day
736column heading for a calendar it's okay to have "T" for both Tuesday
737and Thursday).
738
739=over 4
740
741=item * $locale->month_format_wide()
742
743=item * $locale->month_format_abbreviated($dt)
744
745=item * $locale->month_format_narrow($dt)
746
747=item * $locale->month_stand_alone_wide()
748
749=item * $locale->month_stand_alone_abbreviated($dt)
750
751=item * $locale->month_stand_alone_narrow($dt)
752
753=item * $locale->day_format_wide()
754
755=item * $locale->day_format_abbreviated($dt)
756
757=item * $locale->day_format_narrow($dt)
758
759=item * $locale->day_stand_alone_wide()
760
761=item * $locale->day_stand_alone_abbreviated($dt)
762
763=item * $locale->day_stand_alone_narrow($dt)
764
765=item * $locale->quarter_format_wide()
766
767=item * $locale->quarter_format_abbreviated($dt)
768
769=item * $locale->quarter_format_narrow($dt)
770
771=item * $locale->quarter_stand_alone_wide()
772
773=item * $locale->quarter_stand_alone_abbreviated($dt)
774
775=item * $locale->quarter_stand_alone_narrow($dt)
776
777=item * $locale->am_pm_abbreviated()
778
779=item * $locale->era_wide()
780
781=item * $locale->era_abbreviated($dt)
782
783=item * $locale->era_narrow($dt)
784
785=back
786
787The following methods return strings appropriate for the
788C<< DateTime->format_cldr() >> method:
789
790=over 4
791
792=item * $locale->date_format_full()
793
794=item * $locale->date_format_long()
795
796=item * $locale->date_format_medium()
797
798=item * $locale->date_format_short()
799
800=item * $locale->date_format_default()
801
802=item * $locale->time_format_full()
803
804=item * $locale->time_format_long()
805
806=item * $locale->time_format_medium()
807
808=item * $locale->time_format_short()
809
810=item * $locale->time_format_default()
811
812=item * $locale->datetime_format_full()
813
814=item * $locale->datetime_format_long()
815
816=item * $locale->datetime_format_medium()
817
818=item * $locale->datetime_format_short()
819
820=item * $locale->datetime_format_default()
821
822=back
823
824A locale may also offer one or more formats for displaying part of a
825datetime, such as the year and month, or hour and minute.
826
827=over 4
828
829=item * $locale->format_for($name)
830
831These are accessed by passing a name to C<< $locale->format_for(...)
832>>, where the name is a Java-style format specifier.
833
834The return value is a string suitable for passing to C<<
835$dt->format_cldr() >>, so you can do something like this:
836
837 print $dt->format_cldr( $dt->locale()->format_for('MMMdd') )
838
839which for the "en" locale would print out something like "08 Jul".
840
841Note that the localization may also include additional text specific to the
842locale. For example, the "MMMMd" format for the "zh" locale includes the
843Chinese characters for "day" (日) and month (月), so you get something like "8
844月23日".
845
846=item * $locale->_available_format()
847
848This should return a list of all the format names that could be passed
849to C<< $locale->format_for() >>.
850
851=back
852
853The following methods deal with the default format lengths:
854
855=over 4
856
857=item * $locale->default_date_format_length()
858
859=item * $locale->default_time_format_length()
860
861These methods return one of "full", "long", "medium", or "short",
862indicating the current default format length.
863
864The default when an object is created is determined by the CLDR locale
865data.
866
867=item * $locale->set_default_date_format_length($length)
868
869=item * $locale->set_default_time_format_length($length)
870
871These methods accept one of "full", "long", "medium", or "short",
872indicating the new default format length.
873
874=back
875
876=head1 SUPPORT
877
878Please be aware that all locale data has been generated from the CLDR
879(Common Locale Data Repository) project locales data). The data B<is>
880currently incomplete, and B<will> contain errors in some locales.
881
882When reporting errors in data, please check the primary data sources
883first, then where necessary report errors directly to the primary
884source via the CLDR bug report system. See
885http://unicode.org/cldr/filing_bug_reports.html for details.
886
887Once these errors have been confirmed, please forward the error report
888and corrections to the DateTime mailing list, datetime@perl.org.
889
890Support for this module is provided via the datetime@perl.org email
891list. See http://lists.perl.org/ for more details.
892
893=head1 DONATIONS
894
895If you'd like to thank me for the work I've done on this module,
896please consider making a "donation" to me via PayPal. I spend a lot of
897free time creating free software, and would appreciate any support
898you'd care to offer.
899
900Please note that B<I am not suggesting that you must do this> in order
901for me to continue working on this particular software. I will
902continue to do so, inasmuch as I have in the past, for as long as it
903interests me.
904
905Similarly, a donation made in this way will probably not make me work
906on this software much more, unless I get so many donations that I can
907consider working on free software full time, which seems unlikely at
908best.
909
910To donate, log into PayPal and send money to autarch@urth.org or use
911the button on this page:
912L<http://www.urth.org/~autarch/fs-donation.html>
913
914=head1 AUTHORS
915
916Richard Evans <rich@ridas.com>
917
918Dave Rolsky <autarch@urth.org>
919
920These modules are loosely based on the DateTime::Language modules,
921which were in turn based on the Date::Language modules from Graham
922Barr's TimeDate distribution.
923
924=head1 COPYRIGHT
925
926Copyright (c) 2003 Richard Evans. Copyright (c) 2004-2008 David
927Rolsky. All rights reserved. This program is free software; you can
928redistribute it and/or modify it under the same terms as Perl itself.
929
930This program is free software; you can redistribute it and/or modify
931it under the same terms as Perl itself.
932
933The full text of the license can be found in the F<LICENSE> file included
934with this module.
935
936The locale modules in directory C<DateTime/Locale/> have been
937generated from data provided by the CLDR project, see
938C<DateTime/Locale/LICENSE.cldr> for details on the CLDR data's
939license.
940
941=head1 SEE ALSO
942
943L<DateTime::Locale::Base>
944
945datetime@perl.org mailing list
946
947http://datetime.perl.org/
948
949=cut
950
# spent 294µs within DateTime::Locale::CORE:match which was called 466 times, avg 630ns/call: # 466 times (294µs+0s) by DateTime::Locale::_register at line 65 of DateTime/Locale.pm, avg 630ns/call
sub DateTime::Locale::CORE:match; # xsub