Provided by: libdatetime-format-flexible-perl_0.26-1_all 
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