NAME
    DateTime::Format::CLDR - Parse and format CLDR time patterns

SYNOPSIS
        use DateTime::Format::CLDR;
    
        my $cldr = new DateTime::Format::CLDR(
            pattern     => 'HH:mm:ss',
            locale      => 'de_AT',
            time_zone   => 'Europe/Vienna',
        );
    
        my $dt = $cldr->parse_datetime('23:16:42');
    
        $cldr->format_datetime($dt);
        # 23:16:42
    
        # Get pattern from selected locale
        my $cldr = new DateTime::Format::CLDR(
            locale      => 'de_AT',
        );
    
        # pattern is taken from 'date_format_medium' in DateTime::Locale::de_AT
        my $dt = $cldr->parse_datetime('23.11.2007');
    
        # Croak when things go wrong:
        my $cldr = new DateTime::Format::CLDR(
            locale      => 'de_AT',
            on_error    => 'croak',
        );
    
        # This will croak
        $cldr->parse_datetime('23.33.2007');

DESCRIPTION
    This module provides a parser (and also a formater) for datetime strings
    using patterns as defined by the Unicode CLDR Project (Common Locale
    Data Repository). <http://unicode.org/cldr/>.

    CLDR format is supported by DateTime and DateTime::Locale starting with
    version 0.40.

METHODS
  Constructor
   new
     DateTime::Format::CLDR->new(%PARAMS);

    The following parameters are used by DateTime::Format::CLDR:

    *   locale

        Locale.

        See locale accessor.

    *   pattern (optional)

        CLDR pattern. If you don't provide a pattern the
        "date_format_medium" pattern from DateTime::Local for the selected
        locale will be used.

        See pattern accessor.

    *   time_zone (optional)

        Timezone that should be used by default. If your pattern contains
        timezone information this attribute will be ignored.

        See time_zone accessor.

    *   on_error (optional)

        Set the error behaviour.

        See on_error accessor.

    *   incomplete (optional)

        Set the behaviour how to handle incomplete date information.

        See incomplete accessor.

  Accessors
   pattern
    Get/set pattern. See "CLDR Patterns" in DateTime for details about
    patterns.

   time_zone
    Get/set time_zone. Returns a "DateTime::TimeZone" object.

    Accepts either a timezone name or a "DateTime::TimeZone" object.

   locale
    Get/set a locale. Returns a "DateTime::Locale" object.

    Accepts either a locale name or a "DateTime::Locale::*" object.

   on_error
    Get/set the error behaviour.

    Accepts the following values

    *   'undef' (Literal) (default)

        Returns undef on error and sets errmsg

    *   'croak'

        Croak on error

    *   CODEREF

        Run the given coderef on error.

   incomplete
    Set the behaviour how to handle incomplete Date information.

    Accepts the following values

    *   '1' (default)

        Sets the missing values to '1'. Thus if you only parse a time you
        would get '0001-01-01' as the date.

    *   'incomplete'

        Create a DateTime::Incomplete object instead.

    *   CODEREF

        Run the given coderef on incomplete values. The code reference will
        be called with the "DateTime::Format::CLDR" object and a hash of
        parsed values as supplied to "DateTime->new". It should return a
        modified hash which will be passed to "DateTine->new".

  Public Methods
   parse_datetime
     my $datetime = $cldr->parse_datetime($string);

    Parses a string and returns a "DateTime" object on success (If you
    provide incomplete data and set the incomplete attribute accordingly it
    will return a "DateTime::Incomplete" object). If the string cannot be
    parsed an error will be thrown (depending on the "on_error" attribute).

   format_datetime
     my $string = $cldr->format_datetime($datetime);

    Formats a "DateTime" object using the set locale and pattern. (not the
    time_zone)

   errmsg
     my $string = $cldr->errmsg();

    Stores the last error message. Usefull if the on_error behavior of the
    object is 'undef', so you can work out why things went wrong.

  Exportable functions
    There are no methods exported by default, however the following are
    available:

   cldr_format
     &cldr_format($pattern,$datetime);

   cldr_parse
     &cldr_format($pattern,$string);
     OR
     &cldr_format($pattern,$string,$locale);

    Default locale is 'en'.

CLDR PATTERNS
  Parsing
    Some patterns like day of week, quarter, ect. cannot be used to
    construct a date. However these patterns can be parsed, and a warning
    will be issued if they do not match the parsed date.

    Ambigous patterns (eg. narrow day of week formats for many locales) will
    be parsed but ignored in datetime calculation.

  Supported CLDR Patterns
    See "CLDR Patterns" in DateTime.

    CLDR provides the following pattenrs:

    *   G{1,3}

        The abbreviated era (BC, AD).

        Not used to construct a date.

    *   GGGG

        The wide era (Before Christ, Anno Domini).

        Not used to construct a date.

    *   GGGGG

        The narrow era, if it exists (and it mostly doesn't).

        Not used to construct a date.

    *   y and y{3,}

        The year, zero-prefixed as needed.

    *   yy

        This is a special case. It always produces a two-digit year, so
        "1976" becomes "76".

    *   Y{1,}

        The week of the year, from "$dt->week_year()".

    *   u{1,}

        Same as "y" except that "uu" is not a special case.

    *   Q{1,2}

        The quarter as a number (1..4).

        Not used to construct a date.

    *   QQQ

        The abbreviated format form for the quarter.

        Not used to construct a date.

    *   QQQQ

        The wide format form for the quarter.

        Not used to construct a date.

    *   q{1,2}

        The quarter as a number (1..4).

        Not used to construct a date.

    *   qqq

        The abbreviated stand-alone form for the quarter.

        Not used to construct a date.

    *   qqqq

        The wide stand-alone form for the quarter.

        Not used to construct a date.

    *   M{1,2}

        The numerical month.

    *   MMM

        The abbreviated format form for the month.

    *   MMMM

        The wide format form for the month.

    *   MMMMM

        The narrow format form for the month.

    *   L{1,2}

        The numerical month.

    *   LLL

        The abbreviated stand-alone form for the month.

    *   LLLL

        The wide stand-alone form for the month.

    *   LLLLL

        The narrow stand-alone form for the month.

    *   w{1,2}

        The week of the year, from "$dt->week_number()".

        Not used to construct a date.

    *   W

        The week of the month, from "$dt->week_of_month()".

        Not used to construct a date.

    *   d{1,2}

        The numeric day of of the month.

    *   D{1,3}

        The numeric day of of the year.

        Not used to construct a date.

    *   F

        The day of the week in the month, from "$dt->weekday_of_month()".

        Not used to construct a date.

    *   g{1,}

        The modified Julian day, from "$dt->mjd()".

        Not supported by DateTime::Format::CLDR

    *   E{1,3}

        The abbreviated format form for the day of the week.

        Not used to construct a date.

    *   EEEE

        The wide format form for the day of the week.

        Not used to construct a date.

    *   EEEEE

        The narrow format form for the day of the week.

        Not used to construct a date.

    *   e{1,2}

        The *local* day of the week, from 1 to 7. This number depends on
        what day is considered the first day of the week, which varies by
        locale. For example, in the US, Sunday is the first day of the week,
        so this returns 2 for Monday.

        Not used to construct a date.

    *   eee

        The abbreviated format form for the day of the week.

        Not used to construct a date.

    *   eeee

        The wide format form for the day of the week.

        Not used to construct a date.

    *   eeeee

        The narrow format form for the day of the week.

        Not used to construct a date.

    *   c

        The numeric day of the week (not localized).

        Not used to construct a date.

    *   ccc

        The abbreviated stand-alone form for the day of the week.

        Not used to construct a date.

    *   cccc

        The wide stand-alone form for the day of the week.

        Not used to construct a date.

    *   ccccc

        The narrow format form for the day of the week.

        Not used to construct a date.

    *   a

        The localized form of AM or PM for the time.

    *   h{1,2}

        The hour from 1-12.

    *   H{1,2}

        The hour from 0-23.

    *   K{1,2}

        The hour from 0-11.

    *   k{1,2}

        The hour from 1-24.

    *   j{1,2}

        The hour, in 12 or 24 hour form, based on the preferred form for the
        locale. In other words, this is equivalent to either "h{1,2}" or
        "H{1,2}".

    *   m{1,2}

        The minute.

    *   s{1,2}

        The second.

    *   S{1,}

        The fractional portion of the seconds, rounded based on the length
        of the specifier. This returned without a leading decimal point, but
        may have leading or trailing zeroes.

    *   A{1,}

        The millisecond of the day, based on the current time. In other
        words, if it is 12:00:00.00, this returns 43200000.

        Not supported by DateTime::Format::CLDR

    *   z{1,3}

        The time zone short name.

    *   zzzz

        The time zone long name.

    *   Z{1,3}

        The time zone short name and the offset as one string, so something
        like "CDT-0500".

    *   ZZZZ

        The time zone long name.

    *   v{1,3}

        The time zone short name.

    *   vvvv

        The time zone long name.

    *   V{1,3}

        The time zone short name.

    *   VVVV

        The time zone long name.

CAVEATS
    y and y{3} patterns can only parse four digit years (1000 -> 9999)

    Patterns without separators (like 'dMy' or 'yMd') are ambigous for some
    dates and might fail.

    Quote from the Author of "DateTime::Format::Strptime" which also applies
    to this module:

     "If your module uses this module to parse a known format: stop it. This module 
     is clunky and slow because it can parse almost anything. Parsing a known 
     format is not so difficult, is it? You'll make your module faster if you do. 
     And you're not left at the whim of my potentially broken code."

SUPPORT
    Please report any bugs or feature requests to
    "datetime-format-cldr@rt.cpan.org", or through the web interface at
    <http://rt.cpan.org/Public/Bug/Report.html?Queue=DateTime::Format::CLDR>
    . I will be notified and then you'll automatically be notified of the
    progress on your report as I make changes.

AUTHOR
        Maroš Kollár
        CPAN ID: MAROS
        maros [at] k-1.com
    
        L<http://www.revdev.at>

ACKNOWLEDGEMENTS
    This module was written for Revdev <http://www.revdev.at>, a nice litte
    software company I run with Koki and Domm
    (<http://search.cpan.org/~domm/>).

COPYRIGHT
    DateTime::Format::CLDR is Copyright (c) 2008 Maroš Kollár -
    <http://www.revdev.at>

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

    The full text of the license can be found in the LICENSE file included
    with this module.

SEE ALSO
    datetime@perl.org mailing list

    <http://datetime.perl.org/>

    DateTime, DateTime::Locale, DateTime::TimeZone and
    DateTime::Format::Strptime

