NAME
    DateTime::Format::Japanese - A Japanese DateTime Formatter

SYNOPSIS
      use DateTime::Format::Japanese;
      my $fmt = DateTime::Format::Japanese->new();

      # or if you want to set options,
      my $fmt = DateTime::Format::Japanese->new(
        number_format         => FORMAT_KANJI,
        year_format           => FORMAT_ERA,
        with_gregorian_marker => 1,
        with_bc_marker        => 1,
        with_ampm_marker      => 1,
        with_day_of_week      => 1,
        input_encoding        => $enc_name,
        output_encoding       => $enc_name
      );

      my $str = $fmt->format_datetime($dt);
      my $dt  = $fmt->parse_datetime("ʿ������ǯ�������������������ʬ");

DESCRIPTION
    This module implements a DateTime::Format module that can read Japanese
    date notations and create a DateTime object, and vice versa.

      XXX WARNING WARNING WARNING XXX

      Currently DateTime::Format::Japanese only supports Perl 5.7 and up.
      This is because I'm ignorant in the ways of making robust regular
      expressions in Perls <= 5.6.x with Jcode. If anybody can contribute to
      this, I would much appreciate it

      XXX WARNING WARNING WARNING XXX

METHODS
  new()
    This constructor will create a DateTime::Format::Japanese object. You
    may optionally pass any of the following parameters:

      number_format         - how to format numbers (default: FORMAT_KANJI)
      year_format           - how to format years (default: FORMAT_ERA)
      with_day_of_week      - include day of week (default: 0)
      with_gregorian_marker - use gregorian marker (default: 0)
      with_bc_marker        - use B.C. marker (default: 0)
      with_am_marker        - use A.M/P.M marker (default: 0)
      input_encoding        - encoding of input strings for parsing (default: Guess)
      output_encoding       - encoding of output strings for formatting (default: euc-jp)

    Please note that all of the above parameters only take effect for
    *formatting*, and not *parsing*, except for input_encoding. Parsing is
    done in a way such that it accepts any of the known formats that this
    module can produce.

  $fmt->parse_datetime($string)
    This function will parse a Japanese date/time string and convert it to a
    DateTime object. If the parsing is unsuccessful, it will croak. Note
    that it will try to auto-detect whatever encoding you're using via
    Encode::Guess, so you should be safe to pass any of UTF-8, euc-jp,
    shift-jis, and iso-2022-jp encoded strings.

    This function should be able to parse almost all of the common Japanese
    date notations, whether they are written using ascii numerals, double
    byte numerals, and kanji numerals. The date components (year, month, day
    or era name, era year, month, day) must be present in the string. The
    time components are optional.

    This method can be called as a class function as well.

      my $dt = DateTime::Format::Japanese->parse_datetime($string);
      # or
      my $fmt = DateTime::Format::Japanese->new();
      my $fmt->parse_datetime($string);

FORMATTING METHODS
    All of the following methods accept a single parameter, a DateTime
    object, and return the appropriate string representation.

      my $dt  = DateTime->now();
      my $fmt = DateTime::Format::Japanese->new(...);
      my $str = $fmt->format_datetime($dt);

  $fmt->format_datetime($dt)
    Create a complete string representation of a DateTime object in
    Japanese.

  $fmt->format_ymd($dt)
    Create a string representation of year, month, and date of a DateTime
    object in Japanese

  $fmt->format_year($dt)
    Create a string representation of the year of a DateTime object in
    Japanese

  $fmt->format_month($dt)
    Create a string representation of the month of a DateTime object in
    Japanese

  $fmt->format_day($dt)
    Create a string representation of the day (day of month) of a DateTime
    object in Japanese

  $fmt->format_day_of_week($dt)
    Create a string representation of the day of week of a DateTime object
    in Japanese

  $fmt->format_time($dt)
    Create a string representation of the time (hour, minute, second) of a
    DateTime object in Japanese

  $fmt->format_hour($dt)
    Create a string representation of the hour of a DateTime object in
    Japanese

  $fmt->format_minute($dt)
    Create a string representation of the minute of a DateTime object in
    Japanese

  $fmt->format_second($dt)
    Create a string representation of the second of a DateTime object in
    Japanese

OPTIONS
  input_encoding()
  output_encoding()
    Get/Set the encoding that this module should expect to use.

  number_format()
    Get/Set the number formatting option. Possible values are:

    FORMAT_ROMAN
        Formats the numbers in plain ascii roman numerals.

    FORMAT_KANJI
        Formats numbers in kanji numerals without any unit specifiers.

    FORMAT_ZENKAKU
        Formats numbers in zenkaku numerals (double-byte equivalent of roman
        numerals)

    FORMAT_KANJI_WITH_UNIT
        Formats numbers in kanji numerals, with unit specifiers.

  year_format()
    Get/Set the year formatting option. Possible values are:

    FORMAT_ERA
        Formats the year using the Japanese era notation.

    FORMAT_GREGORIAN
        Formats the year using the Gregorian notation

  with_gregorian_marker()
    Get/Set the option to include the gregorian calendar marker ("����")

  with_bc_marker()
    Get/Set the option to include the "B.C." marker instead of a negative
    year.

  with_ampm_marker()
    Get/Set the option to include the AM/PM marker. Implies that the hour
    notation is swictched to 1-12 from 1-23

  with_day_of_week
    Get/Set the option to include day of week.

ENCODING
    As of version 0.02, DateTime::Format::Japanese can handle arbitrary
    Japanese encoding for both input and output.

    By default, input_encoding is set to 'Guess' and uses Encode::Guess.
    However, this method is often not adequate to handle Japanese encodings,
    as there are many ambiguities between any two encoding. In cases where
    Encode::Guess could not guess the encoding being used, it will croak and
    emit an error.

    Therefore it is always recommended that you set the input_encoding.

CAVEATS
  Day Of Week
    Day of week is accepted in the parsing as the last element, but is never
    used for generating DateTime objects. That is, if you give a date and an
    unmatching day of week, your day of week will silently be ignored, and
    DateTime.pm will handle the actual calculation.

  Kanji Dates With Units
    Kanji notations have the following limitations, which were :

    Gregorian years may only expressed like this: '�󡻡���', not '�����'

    All other fields may be expressed as either '����' or '���'. However,
    it will only understand up to the 10s, not anything higher. This is
    because of the limit in the range of the fields.

AUTHOR
    Copyright (c) 2004-2006 Daisuke Maki <daisuke@cpan.org>. All rights
    reserved.