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

VERSION

v0.1.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.

• 1. 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

• 1. It allows formatting of datetime intervals

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

• 1. 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

format_datetime

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.

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.