.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DateTime::Format::Flexible 3pm"
.TH DateTime::Format::Flexible 3pm "2021-08-22" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DateTime::Format::Flexible \- DateTime::Format::Flexible \- Flexibly parse strings and turn them into DateTime objects.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&  use DateTime::Format::Flexible;
\&  my $dt = DateTime::Format::Flexible\->parse_datetime(
\&      \*(AqJanuary 8, 1999\*(Aq
\&  );
\&  # $dt = a DateTime object set at 1999\-01\-08T00:00:00
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
If you have ever had to use a program that made you type in the
date a certain way and thought \*(L"Why can't the computer just figure
out what date I wanted?\*(R", this module is for you.
.PP
\&\fIDateTime::Format::Flexible\fR attempts to take any string you give
it and parse it into a DateTime object.
.SH "USAGE"
.IX Header "USAGE"
This module uses \fIDateTime::Format::Builder\fR under the covers.
.SS "parse_datetime"
.IX Subsection "parse_datetime"
Give it a string and it attempts to parse it and return a DateTime
object.
.PP
If it cannot it will throw an exception.
.PP
.Vb 1
\& my $dt = DateTime::Format::Flexible\->parse_datetime( $date );
\&
\& my $dt = DateTime::Format::Flexible\->parse_datetime(
\&     $date,
\&     strip    => [qr{\e.\ez}],                  # optional, remove a trailing period
\&     tz_map   => {EDT => \*(AqAmerica/New_York\*(Aq}, # optional, map the EDT timezone to America/New_York
\&     lang     => [\*(Aqes\*(Aq],                      # optional, only parse using spanish
\&     european => 1,                           # optional, catch some cases of DD\-MM\-YY
\& );
.Ve
.IP "\(bu" 4
\&\f(CW\*(C`base\*(C'\fR (optional)
.Sp
Does the same thing as the method \f(CW\*(C`base\*(C'\fR.  Sets a base datetime for
incomplete dates.  Requires a valid DateTime object as an argument.
.Sp
example:
.Sp
.Vb 6
\& my $base_dt = DateTime\->new( year => 2005, month => 2, day => 1 );
\& my $dt = DateTime::Format::Flexible\->parse_datetime(
\&    \*(Aq18 Mar\*(Aq,
\&     base => $base_dt,
\& );
\& # $dt is now 2005\-03\-18T00:00:00
.Ve
.IP "\(bu" 4
\&\f(CW\*(C`strip\*(C'\fR (optional)
.Sp
Remove a substring from the string you are trying to parse.
You can pass multiple regexes in an arrayref.
.Sp
example:
.Sp
.Vb 5
\& my $dt = DateTime::Format::Flexible\->parse_datetime(
\&     \*(Aq2011\-04\-26 00:00:00 (registry time)\*(Aq,
\&     strip => [qr{\e(registry time\e)\ez}],
\& );
\& # $dt is now 2011\-04\-26T00:00:00
.Ve
.Sp
This is helpful if you have a load of dates you want to normalize
and you know of some weird formatting beforehand.
.IP "\(bu" 4
\&\f(CW\*(C`tz_map\*(C'\fR (optional)
.Sp
Map a given timezone to another recognized timezone
Values are given as a hashref.
.Sp
example:
.Sp
.Vb 5
\& my $dt = DateTime::Format::Flexible\->parse_datetime(
\&     \*(Aq25\-Jun\-2009 EDT\*(Aq,
\&     tz_map => {EDT => \*(AqAmerica/New_York\*(Aq},
\& );
\& # $dt is now 2009\-06\-25T00:00:00 with a timezone of America/New_York
.Ve
.Sp
This is helpful if you have a load of dates that have timezones that
are not recognized by \fIDateTime::Timezone\fR.
.IP "\(bu" 4
\&\f(CW\*(C`lang\*(C'\fR (optional)
.Sp
Specify the language map plugins to use.
.Sp
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.
.Sp
\&\s-1NOTE:\s0 as of 0.22, it will only do this search if it detects a string
in the given date.
.Sp
Setting \f(CW\*(C`lang\*(C'\fR this lets you limit the scope of the search.
.Sp
example:
.Sp
.Vb 5
\& my $dt = DateTime::Format::Flexible\->parse_datetime(
\&     \*(AqWed, Jun 10, 2009\*(Aq,
\&     lang => [\*(Aqen\*(Aq],
\& );
\& # $dt is now 2009\-06\-10T00:00:00
.Ve
.Sp
Currently supported languages are english (en), spanish (es) and
german (de). Contributions, corrections, requests and examples
are \s-1VERY\s0 welcome.
.Sp
See the \fIDateTime::Format::Flexible::lang::en\fR,
\&\fIDateTime::Format::Flexible::lang::es\fR, and
\&\fIDateTime::Format::Flexible::lang::de\fR
for examples of the plugins.
.IP "\(bu" 4
\&\f(CW\*(C`european\*(C'\fR (optional)
.Sp
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.
.Sp
example:
.Sp
.Vb 4
\& my $dt = DateTime::Format::Flexible\->parse_datetime(
\&     \*(Aq16/06/2010\*(Aq , european => 1,
\& );
\& # $dt is now 2010\-06\-16T00:00:00
.Ve
.IP "\(bu" 4
\&\f(CW\*(C`MMYY\*(C'\fR (optional)
.Sp
By default, this module will parse 12/10 as December 10th of the
current year (\s-1MM/DD\s0).
.Sp
If you want it to parse this as \s-1MM/YY\s0 instead, you can enable the
\&\f(CW\*(C`MMYY\*(C'\fR option.
.Sp
example:
.Sp
.Vb 2
\& my $dt = DateTime::Format::Flexible\->parse_datetime(\*(Aq12/10\*(Aq);
\& # $dt is now [current year]\-12\-10T00:00:00
\&
\& my $dt = DateTime::Format::Flexible\->parse_datetime(
\&     \*(Aq12/10\*(Aq, MMYY => 1,
\& );
\& # $dt is now 2010\-12\-01T00:00:00
.Ve
.Sp
This is useful if you know you are going to be parsing a credit card
expiration date.
.SS "base"
.IX Subsection "base"
gets/sets the base DateTime for incomplete dates.  Requires a valid
DateTime object as an argument when setting.  This defaults to
DateTime\->now.
.PP
example:
.PP
.Vb 5
\& DateTime::Format::Flexible\->base( DateTime\->new(
\&     year => 2009, month => 6, day => 22
\& ));
\& my $dt = DateTime::Format::Flexible\->parse_datetime( \*(Aq23:59\*(Aq );
\& # $dt is now 2009\-06\-22T23:59:00
.Ve
.SS "build"
.IX Subsection "build"
an alias for parse_datetime
.SS "Example formats"
.IX Subsection "Example formats"
A small list of supported formats:
.IP "\s-1YYYYMMDDTHHMMSS\s0" 4
.IX Item "YYYYMMDDTHHMMSS"
.PD 0
.IP "\s-1YYYYMMDDTHHMM\s0" 4
.IX Item "YYYYMMDDTHHMM"
.IP "\s-1YYYYMMDDTHH\s0" 4
.IX Item "YYYYMMDDTHH"
.IP "\s-1YYYYMMDD\s0" 4
.IX Item "YYYYMMDD"
.IP "\s-1YYYYMM\s0" 4
.IX Item "YYYYMM"
.IP "MM-DD-YYYY" 4
.IX Item "MM-DD-YYYY"
.IP "MM-D-YYYY" 4
.IX Item "MM-D-YYYY"
.IP "MM-DD-YY" 4
.IX Item "MM-DD-YY"
.IP "M\-DD-YY" 4
.IX Item "M-DD-YY"
.IP "\s-1YYYY/DD/MM\s0" 4
.IX Item "YYYY/DD/MM"
.IP "\s-1YYYY/M/DD\s0" 4
.IX Item "YYYY/M/DD"
.IP "\s-1YYYY/MM/D\s0" 4
.IX Item "YYYY/MM/D"
.IP "M\-D" 4
.IX Item "M-D"
.IP "MM-D" 4
.IX Item "MM-D"
.IP "M\-D-Y" 4
.IX Item "M-D-Y"
.IP "Month D, \s-1YYYY\s0" 4
.IX Item "Month D, YYYY"
.IP "Mon D, \s-1YYYY\s0" 4
.IX Item "Mon D, YYYY"
.IP "Mon D, \s-1YYYY HH:MM:SS\s0" 4
.IX Item "Mon D, YYYY HH:MM:SS"
.IP "... thousands more" 4
.IX Item "... thousands more"
.PD
.PP
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.
.SH "NOTES"
.IX Header "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
\&'\fBis_infinite()\fR' from the object returned.
.PP
example:
.PP
.Vb 5
\& my $dt = DateTime::Format::Flexible\->parse_datetime( \*(Aqinfinity\*(Aq );
\& if ( $dt\->is_infinite )
\& {
\&      # you have a Infinite object.
\& }
.Ve
.SH "BUGS/LIMITATIONS"
.IX Header "BUGS/LIMITATIONS"
You cannot use a 1 or 2 digit year as the first field unless the
year is > 31:
.PP
.Vb 2
\& YY\-MM\-DD # not supported if YY is <= 31
\& Y\-MM\-DD  # not supported
.Ve
.PP
It gets confused with MM-DD-YY
.SH "AUTHOR"
.IX Header "AUTHOR"
Tom Heady <cpan@punch.net>
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2007\-2018 Tom Heady.
.PP
This program is free software; you can redistribute it and/or
modify it under the terms of either:
.IP "\(bu" 4
the \s-1GNU\s0 General Public License as published by the Free
    Software Foundation; either version 1, or (at your option) any
    later version, or
.IP "\(bu" 4
the Artistic License.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIDateTime::Format::Builder\fR, \fIDateTime::Timezone\fR, \fIDateTime::Format::Natural\fR