Provided by: libdatetime-format-flexible-perl_0.28-1_all bug

NAME

       DateTime::Format::Flexible - DateTime::Format::Flexible - Flexibly parse strings and turn
       them into DateTime objects.

SYNOPSIS

         use DateTime::Format::Flexible;
         my $dt = DateTime::Format::Flexible->parse_datetime(
             'January 8, 1999'
         );
         # $dt = a DateTime object set at 1999-01-08T00:00:00

DESCRIPTION

       If you have ever had to use a program that made you type in the date a certain way and
       thought "Why can't the computer just figure out what date I wanted?", this module is for
       you.

       DateTime::Format::Flexible attempts to take any string you give it and parse it into a
       DateTime object.

USAGE

       This module uses DateTime::Format::Builder under the covers.

   parse_datetime
       Give it a string and it attempts to parse it and return a DateTime object.

       If it cannot it will throw an exception.

        my $dt = DateTime::Format::Flexible->parse_datetime( $date );

        my $dt = DateTime::Format::Flexible->parse_datetime(
            $date,
            strip    => [qr{\.\z}],                  # optional, remove a trailing period
            tz_map   => {EDT => 'America/New_York'}, # optional, map the EDT timezone to America/New_York
            lang     => ['es'],                      # optional, only parse using spanish
            european => 1,                           # optional, catch some cases of DD-MM-YY
        );

       •   "base" (optional)

           Does the same thing as the method "base".  Sets a base datetime for incomplete dates.
           Requires a valid DateTime object as an argument.

           example:

            my $base_dt = DateTime->new( year => 2005, month => 2, day => 1 );
            my $dt = DateTime::Format::Flexible->parse_datetime(
               '18 Mar',
                base => $base_dt,
            );
            # $dt is now 2005-03-18T00:00:00

       •   "strip" (optional)

           Remove a substring from the string you are trying to parse.  You can pass multiple
           regexes in an arrayref.

           example:

            my $dt = DateTime::Format::Flexible->parse_datetime(
                '2011-04-26 00:00:00 (registry time)',
                strip => [qr{\(registry time\)\z}],
            );
            # $dt is now 2011-04-26T00:00:00

           This is helpful if you have a load of dates you want to normalize and you know of some
           weird formatting beforehand.

       •   "tz_map" (optional)

           Map a given timezone to another recognized timezone Values are given as a hashref.

           example:

            my $dt = DateTime::Format::Flexible->parse_datetime(
                '25-Jun-2009 EDT',
                tz_map => {EDT => 'America/New_York'},
            );
            # $dt is now 2009-06-25T00:00:00 with a timezone of America/New_York

           This is helpful if you have a load of dates that have timezones that are not
           recognized by DateTime::Timezone.

       •   "lang" (optional)

           Specify the language map plugins to use.

           When DateTime::Format::Flexible parses a date with a string in it, it will search for
           a way to convert that string to a number.  By default it will search through all the
           language plugins to search for a match.

           NOTE: as of 0.22, it will only do this search if it detects a string in the given
           date.

           Setting "lang" this lets you limit the scope of the search.

           example:

            my $dt = DateTime::Format::Flexible->parse_datetime(
                'Wed, Jun 10, 2009',
                lang => ['en'],
            );
            # $dt is now 2009-06-10T00:00:00

           Currently supported languages are english (en), spanish (es) and german (de).
           Contributions, corrections, requests and examples are VERY welcome.

           See the DateTime::Format::Flexible::lang::en, DateTime::Format::Flexible::lang::es,
           and DateTime::Format::Flexible::lang::de for examples of the plugins.

       •   "european" (optional)

           If european is set to a true value, an attempt will be made to parse as a DD-MM-YYYY
           date instead of the default MM-DD-YYYY.  There is a chance that this will not do the
           right thing due to ambiguity.

           example:

            my $dt = DateTime::Format::Flexible->parse_datetime(
                '16/06/2010' , european => 1,
            );
            # $dt is now 2010-06-16T00:00:00

       •   "MMYY" (optional)

           By default, this module will parse 12/10 as December 10th of the current year (MM/DD).

           If you want it to parse this as MM/YY instead, you can enable the "MMYY" option.

           example:

            my $dt = DateTime::Format::Flexible->parse_datetime('12/10');
            # $dt is now [current year]-12-10T00:00:00

            my $dt = DateTime::Format::Flexible->parse_datetime(
                '12/10', MMYY => 1,
            );
            # $dt is now 2010-12-01T00:00:00

           This is useful if you know you are going to be parsing a credit card expiration date.

   base
       gets/sets the base DateTime for incomplete dates.  Requires a valid DateTime object as an
       argument when setting.  This defaults to DateTime->now.

       example:

        DateTime::Format::Flexible->base( DateTime->new(
            year => 2009, month => 6, day => 22
        ));
        my $dt = DateTime::Format::Flexible->parse_datetime( '23:59' );
        # $dt is now 2009-06-22T23:59:00

   build
       an alias for parse_datetime

   Example formats
       A small list of supported formats:

       YYYYMMDDTHHMMSS
       YYYYMMDDTHHMM
       YYYYMMDDTHH
       YYYYMMDD
       YYYYMM
       MM-DD-YYYY
       MM-D-YYYY
       MM-DD-YY
       M-DD-YY
       YYYY/DD/MM
       YYYY/M/DD
       YYYY/MM/D
       M-D
       MM-D
       M-D-Y
       Month D, YYYY
       Mon D, YYYY
       Mon D, YYYY HH:MM:SS
       ... thousands more

       there are 9000+ variations that are detected correctly in the test files (see t/data/* for
       most of them).  If you can think of any that I do not cover, please let me know.

NOTES

       As of version 0.11 you will get a DateTime::Infinite::Future object if the passed in date
       is 'infinity' and a DateTime::Infinite::Past object if the passed in date is '-infinity'.
       If you are expecting these types of strings, you might want to check for 'is_infinite()'
       from the object returned.

       example:

        my $dt = DateTime::Format::Flexible->parse_datetime( 'infinity' );
        if ( $dt->is_infinite )
        {
             # you have a Infinite object.
        }

BUGS/LIMITATIONS

       You cannot use a 1 or 2 digit year as the first field unless the year is > 31:

        YY-MM-DD # not supported if YY is <= 31
        Y-MM-DD  # not supported

       It gets confused with MM-DD-YY

AUTHOR

       Tom Heady <cpan@punch.net>

COPYRIGHT & LICENSE

       Copyright 2007-2012 Tom Heady.

       This program is free software; you can redistribute it and/or modify it under the terms of
       either:

       •   the GNU General Public License as published by the Free
               Software Foundation; either version 1, or (at your option) any
               later version, or

       •   the Artistic License.

SEE ALSO

       DateTime::Format::Builder, DateTime::Timezone, DateTime::Format::Natural