/ 
DateTime-Format-Unicode-v0.3.0
River stage one • 1 direct dependent • 1 total dependent
/ DateTime::Format::Unicode

NAME

DateTime::Format::Unicode - Unicode CLDR Formatter for DateTime

SYNOPSIS

use DateTime::Format::Unicode;
my $fmt = DateTime::Format::Unicode->new(
    locale      => 'ja-Kana-JP',
    # optional, defaults to the locale medium size date formatting
    # See: DateTime::Locale::FromCLDR for more information
    pattern     => 'HH:mm:ss',
    # optional
    time_zone   => 'Asia/Tokyo',
    # will make error become fatal and have this API die instead of setting an exception object
    on_error    => 'fatal',
) || die( DateTime::Format::Unicode->error );

or, maybe, just:

my $fmt = DateTime::Format::Unicode->new;

which, will default to locale en with date medium-size format pattern MMM d, y

If you specify a locale that uses a different number system than latn (which is 0 to 9), then DateTime::Format::Unicode will honour it. For example:

my $fmt = DateTime::Format::Unicode->new(
    locale => 'ar-SA',
    pattern => 'd/M/y',
) || die( DateTime::Format::Unicode->error );
say $fmt->format; # ١٠/٩/٢٠٢٤

You can also override the locale's default number system, by another one, as long as it is supported by that locale. For example:

my $fmt = DateTime::Format::Unicode->new(
    locale => 'ar-SA-u-nu-latn',
    pattern => 'd/M/y',
) || die( DateTime::Format::Unicode->error );
say $fmt->format; # ١٠/٩/٢٠٢٤

VERSION

v0.3.0

DESCRIPTION

This is a Unicode CLDR (Common Locale Data Repository) formatter for DateTime

It differs from the default formatter used in DateTime with its method format_cldr in several aspects:

1. It uses DateTime::Locale::FromCLDR

A much more comprehensive and accurate API to dynamically access the Unicode CLDR data whereas the module DateTime relies on, DateTime::Locale, which uses static data from over 1,000 pre-generated modules.

2. It allows for any locale

Since, it uses dynamic data, you can use any locale, from the simple en to more complex es-001-valencia, or even ja-t-de-t0-und-x0-medical

3. It allows formatting of datetime intervals

Datetime intervals are very important, and unfortunately unsupported by DateTime as of July 2024.

4. It supports more pattern tokens

DateTime format_cldr does not support all of the CLDR pattern tokens, but DateTime::Format::Unicode does.

Known pattern tokens unsupported by DateTime are:

  • b

    Period of the day, such as am, pm, noon, midnight

    See "calendar_term" in Locale::Unicode::Data and its corollary "day_period" in Locale::Unicode::Data

  • B

    Flexible day periods, such as at night

    See "calendar_term" in Locale::Unicode::Data and its corollary "day_period" in Locale::Unicode::Data

  • O

    Zone, such as O to get the short localized GMT format GMT-8, or OOOO to get the long localized GMT format GMT-08:00

  • r

    Related Gregorian year (numeric).

    The documentation states that "For the Gregorian calendar, the ‘r’ year is the same as the ‘u’ year."

  • U

    Cyclic year name. However, since this is for non gregorian calendars, like Chinese or Hindu calendars, and since DateTime only supports gregorian calendar, we do not support it either.

  • x

    Timezone, such as x would be -08, xx -0800 or +0800, xxx would be -08:00 or +08:00, xxxx would be -0800 or +0000 and xxxxx would be -08:00, or -07:52:58 or +00:00

  • X

    Timezone, such as X (-08 or +0530 or Z), XX (-0800 or Z), XXX (-08:00), XXXX (-0800 or -075258 or Z), XXXXX (-08:00 or -07:52:58 or Z)

DateTime::Format::Unicode only formats CLDR datetime patterns, and does not parse them back into a DateTime object. If you want to achieve that, there is already the module DateTime::Format::CLDR that does this. DateTime::Format::CLDR relies on "format_cldr" in DateTime for CLDR formatting by the way.

CONSTRUCTOR

new

This takes some hash or hash reference of options, instantiates a new DateTime::Format::Unicode object, and returns it.

Supported options are as follows. Each option can be later accessed or modified by their associated method.

  • locale

    A locale, which may be very simple like en or much more complex like ja-t-de-t0-und-x0-medical or maybe es-039-valencia (valencian variant of Spanish as spoken in South Europe)

    If not provided, this will default to en

  • on_error

    Specifies what to do upon error. Possible values are: undef (default behaviour), fatal (will die), or a CODE reference that will be called with the exception object as its sole argument, before undef is returned in scalar context, or an empty list in list context.

  • pattern

    A CLDR pattern. If none is provided, this will default to the medium-size date pattern for the given locale. For example, as per the CLDR, for English, this would be MMM d, y whereas for the locale ja, this would be y/MM/dd

  • time_zone

    Set the timezone by providing either a DateTime::TimeZone object, or a string representing a timezone.

    It defaults to the special DateTime timezone floating

METHODS

error

Used as a mutator, this sets an exception object and returns an DateTime::Format::Unicode::NullObject in object context (such as when chaining), or undef in scalar context, or an empty list in list context.

The DateTime::Format::Unicode::NullObject class prevents the perl error of Can't call method "%s" on an undefined value (see perldiag). Upon the last method chained, undef is returned in scalar context or an empty list in list context.

format_datetime

my $fmt = DateTime::Format::Unicode->new(
    locale => 'en',
    pattern => "Hello the time is H:m:s",
);
my $str = $fmt->format_datetime( $dt );

or

my $fmt = DateTime::Format::Unicode->new(
    locale => 'en',
);
my $str = $fmt->format_datetime( $dt,
    pattern => "Hello the time is H:m:s",
);

This takes a DateTime object, or if none is provided, it will instantiate one using "now" in DateTime, and formats the pattern that was set and return the resulting formatted string.

It takes an optional hash or hash reference of options.

The options supported are:

  • pattern

    A pattern to use to format the datetime. If provided, it will override the default set with the method pattern

format_interval

my $fmt = DateTime::Format::Unicode->new(
    locale => 'en',
    pattern => "GyMMMd",
);
my $str = $fmt->format_interval( $dt1, $dt2 );

or

my $fmt = DateTime::Format::Unicode->new(
    locale => 'en',
);
my $str = $fmt->format_interval( $dt1, $dt2
    pattern => "GyMMMd",
);

This takes 2 datetime objects and it returns a formatted string according to the specified locale and based on the interval pattern ID provided with the pattern argument or method.

Alternatively, you can pass a pattern option that will override the default value set with the method pattern

You can retrieve an hash of interval format ID to its interval format pattern by using DateTime::Locale::FromCLDR. For example:

my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $ref = $locale->interval_formats;

This would produce an hash like this:

{
    Bh => [qw( B h )],
    Bhm => [qw( B h m )],
    d => ["d"],
    Gy => [qw( G y )],
    GyM => [qw( G M y )],
    GyMd => [qw( d G M y )],
    GyMEd => [qw( d G M y )],
    GyMMM => [qw( G M y )],
    GyMMMd => [qw( d G M y )],
    GyMMMEd => [qw( d G M y )],
    H => ["H"],
    h => [qw( a h )],
    Hm => [qw( H m )],
    hm => [qw( a h m )],
    Hmv => [qw( H m )],
    hmv => [qw( a h m )],
    Hv => ["H"],
    hv => [qw( a h )],
    M => ["M"],
    Md => [qw( d M )],
    MEd => [qw( d M )],
    MMM => ["M"],
    MMMd => [qw( d M )],
    MMMEd => [qw( d M )],
    y => ["y"],
    yM => [qw( M y )],
    yMd => [qw( d M y )],
    yMEd => [qw( d M y )],
    yMMM => [qw( M y )],
    yMMMd => [qw( d M y )],
    yMMMEd => [qw( d M y )],
    yMMMM => [qw( M y )],
}

The method will try to get the interval greatest difference between the two DateTime objects. If the two objects are equal, the greatest difference will be a day (d). Possibile values are: B (day period), G (eras), H (hours 0-23), M (minutes), a (am/pm), d (days), h (hours 1-12), m (minutes), y (years)

If the method is unable to get a format pattern based on the interval format ID provided, it will assume this is a custom format pattern, and will attempt at breaking it down. If that does not succeed, it will return an error.

Errors

This module does not die upon errors unless requested to. Instead it sets an error object that can be retrieved.

When an error occurred, an error object will be set and the method will return undef in scalar context and an empty list in list context.

The only occasions when this module will die is when there is an internal design error, which would be my fault, or if the value set with on_error is fatal or also if the CODE reference set with on_error would, itself, die.

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

DateTime, DateTime::Format::FromCLDR, Locale::Unicode, Locale::Unicode::Data, DateTime::Locale

COPYRIGHT & LICENSE

Copyright(c) 2024 DEGUEST Pte. Ltd.

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.