/ 
DateTime-Format-JP-v0.1.6
River stage one • 1 direct dependent • 2 total dependents
/ README.md

SYNOPSIS

    use DateTime::Format::JP;
    my $fmt = DateTime::Format::JP->new(
        hankaku      => 1,
        pattern      => '%c', # default
        traditional  => 0,
        kanji_number => 0,
        zenkaku      => 0,
        time_zone    => 'local',
    );
    my $dt = DateTime->now;
    $dt->set_formatter( $fmt );
    # set the encoding in and out to utf8
    use open ':std' => ':utf8';
    print "$dt\n"; # will print something like 令和3年7月12日午後2:30:20

    my $dt  = $fmt->parse_datetime( "令和３年７月１２日午後２時３０分" );
    
    my $str = $fmt->format_datetime( $dt );
    print "$str\n";

VERSION

    v0.1.2

DESCRIPTION

This module is used to parse and format Japanese date and time. It is lightweight and yet versatile.

It implements 2 main methods: "parse_datetime"{.perl-module} and "format_datetime"{.perl-module} both expect and return decoded utf8 string.

You can use Encode{.perl-module} to decode and encode from perl internal utf8 representation to real utf8 and vice versa.

METHODS

new

The constructor accepts the following parameters:

hankaku boolean

: If true, the digits used will be "half-size" (半角), or roman numbers like 1, 2, 3, etc.

The opposite is *zenkaku* (全角) or full-width. This will enable the
use of double-byte Japanese numbers that still look like roman
numbers, such as: １, ２, ３, etc.

Defaults to true.

pattern string

: The pattern to use to format the date and time. See below the available "PATTERN TOKENS"{.perl-module} and their meanings.

Defaults to `%c`

traditional boolean

: If true, then it will use a more traditional date/time representation. The effect of this parameter on the formatting is documented in "PATTERN TOKENS"{.perl-module}

kanji_number boolean

: If true, this will have "format_datetime"{.perl-module} use numbers in kanji, such as: 一, 二, 三, 四, etc.

zenkaku boolean

: If true, this will use full-width, ie double-byte Japanese numbers that still look like roman numbers, such as: １, ２, ３, etc.

time_zone string

: The time zone to use when creating a DateTime{.perl-module} object. Defaults to local if DateTime::TimeZone{.perl-module} supports it, otherwise it will fallback on UTC

error

Returns the latest error set, if any.

All method in this module return undef upon error and set an error that can be retrieved with this method.

format_datetime

Takes a DateTime{.perl-module} object and returns a formatted date and time based on the pattern specified, which defaults to %c.

You can call this method directly, or you can set this formatter object in "set_formatter" in DateTime{.perl-module} so that ie will be used for stringification of the DateTime{.perl-module} object.

See below "PATTERN TOKENS"{.perl-module} for the available tokens and their meanings.

hankaku

Sets or gets the boolean value for hankaku.

kanji_number

Sets or gets the boolean value for kanji_number.

parse_datetime

Takes a string representing a Japanese date, parse it and return a new DateTime{.perl-module}. If an error occurred, it will return undef and you can get the error using "error"{.perl-module}

time_zone

Sets or gets the string representing the time zone to use when creating DateTime{.perl-module} object. This is used by "parse_datetime"{.perl-module}

traditional

Sets or gets the boolean value for traditional.

zenkaku

Sets or gets the boolean value for zenkaku.

SUPPORT METHODS

kanji_to_romaji

Takes a number in kanji and returns its equivalent value in roman (regular) numbers.

lookup_era

Takes an Japanese era in kanji and returns an DateTime::Format::JP::Era object

lookup_era_by_date

Takes a DateTime{.perl-module} object and returns a DateTime::Format::JP::Era object

make_datetime

Returns a DateTime{.perl-module} based on parameters provided.

romaji_to_kanji

Takes a number and returns its equivalent representation in Japanese kanji. Thus, for example, 1234 would be returned as 千二百三十四

Please note that, since this is intended to be used only for dates, it does not format number over 9 thousand. If you think there is such need, please contact the author.

romaji_to_kanji_simple

Replaces numbers with their Japanese kanji equivalent. It does not use numerals.

romaji_to_zenkaku

Takes a number and returns its equivalent representation in double-byte Japanese numbers. Thus, for example, 1234 would be returned as １２３４

zenkaku_to_romaji

Takes a string representing a number in full width (全角), i.e. double-byte and returns a regular equivalent number. Thus, for example, １２３４ would be returned as 1234

PATTERN TOKENS

Here are below the available tokens for formatting and the value they represent.

In all respect, they are closely aligned with "strftime" in DateTime{.perl-module} (see ["strftime Patterns" in DateTime](https://metacpan.org/pod/DateTime#strftime Patterns){.perl-module}), except that the formatter object parameters provided upon instantiation alter the values used.

HISTORICAL NOTE

Japanese eras, also known as 元号 (gengo) or 年号 (nengo) form one of the two parts of a Japanese year in any given date.

It was instituted by and under first Emperor Kōtoku in 645 AD. So be warned that requiring an era-based Japanese date before will not yield good results.

Era name were adopted for various reasons such as a to commemorate an auspicious or ward off a malign event, and it is only recently that era name changes are tied to a new Emperor.

More on this here{.perl-module}

From 1334 until 1392, there were 2 competing regimes in Japan; the North and South. This period was called "Nanboku-chō" (南北朝). This module uses the official Northern branch.

Also there has been two times during the period "Asuka" (飛鳥時代) with no era names, from 654/11/24 until 686/8/14 after Emperor Kōtoku death and from 686/10/1 until 701/5/3 after Emperor Tenmu's death just 2 months after his enthronement.

Thus if you want a Japanese date using era during those two periods, you will get and empty era.

More on this here{.perl-module}

AUTHOR

Jacques Deguest <jack@deguest.jp{classes="ARRAY(0x55fc45a5a250)"}>

SEE ALSO

DateTime{.perl-module}

COPYRIGHT & LICENSE

Copyright(c) 2021 DEGUEST Pte. Ltd. DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.