DateTime::Format::Flexible(3pm)

1DateTime::Format::FlexiUbsleer(3C)ontributed Perl DocumeDnattaetTiiomne::Format::Flexible(3)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

15       If you have ever had to use a program that made you type in the date a
16       certain way and thought "Why can't the computer just figure out what
17       date I wanted?", this module is for you.
18
19       DateTime::Format::Flexible attempts to take any string you give it and
20       parse it into a DateTime object.
21

USAGE

23       This module uses DateTime::Format::Builder under the covers.
24
25   parse_datetime
26       Give it a string and it attempts to parse it and return a DateTime
27       object.
28
29       If it cannot it will throw an exception.
30
31        my $dt = DateTime::Format::Flexible->parse_datetime( $date );
32
33        my $dt = DateTime::Format::Flexible->parse_datetime(
34            $date,
35            strip    => [qr{\.\z}],                  # optional, remove a trailing period
36            tz_map   => {EDT => 'America/New_York'}, # optional, map the EDT timezone to America/New_York
37            lang     => ['es'],                      # optional, only parse using spanish
38            european => 1                            # optional, catch some cases of DD-MM-YY
39        );
40
41       ·   "base" (optional)
42
43           Does the same thing as the method "base".  Sets a base datetime for
44           incomplete dates.  Requires a valid DateTime object as an argument.
45
46           example:
47
48            my $base_dt = DateTime->new( year => 2005, month => 2, day => 1 );
49            my $dt = DateTime::Format::Flexible->parse_datetime(
50               '18 Mar',
51                base => $base_dt
52            );
53            # $dt is now 2005-03-18T00:00:00
54
55       ·   "strip" (optional)
56
57           Remove a substring from the string you are trying to parse.  You
58           can pass multiple regexes in an arrayref.
59
60           example:
61
62            my $dt = DateTime::Format::Flexible->parse_datetime(
63                '2011-04-26 00:00:00 (registry time)' ,
64                strip => [qr{\(registry time\)\z}] ,
65            );
66            # $dt is now 2011-04-26T00:00:00
67
68           This is helpful if you have a load of dates you want to normalize
69           and you know of some weird formatting beforehand.
70
71       ·   "tz_map" (optional)
72
73           map a given timezone to another recognized timezone Values are
74           given as a hashref.
75
76           example:
77
78            my $dt = DateTime::Format::Flexible->parse_datetime(
79                '25-Jun-2009 EDT' ,
80                tz_map => {EDT => 'America/New_York'}
81            );
82            # $dt is now 2009-06-25T00:00:00 with a timezone of America/New_York
83
84           This is helpful if you have a load of dates that have timezones
85           that are not recognized by DateTime::Timezone.
86
87       ·   "lang" (optional)
88
89           Specify the language map plugins to use.
90
91           When DateTime::Format::Flexible parses a date with a string in it,
92           it will search for a way to convert that string to a number.  By
93           default it will search through all the language plugins to search
94           for a match.
95
96           Setting this lets you limit the scope of the search
97
98           example:
99
100            my $dt = DateTime::Format::Flexible->parse_datetime(
101                'Wed, Jun 10, 2009' ,
102                lang => ['en']
103            );
104            # $dt is now 2009-06-10T00:00:00
105
106           Currently supported languages are english (en) and spanish (es).
107           Contributions, corrections, requests and examples are VERY welcome.
108           See the DateTime::Format::Flexible::lang::en and
109           DateTime::Dormat::Flexible::lang::es for examples of the plugins.
110
111       ·   "european" (optional)
112
113           If european is set to a true value, an attempt will be made to
114           parse as a DD-MM-YYYY date instead of the default MM-DD-YYYY.
115           There is a chance that this will not do the right thing due to
116           ambiguity.
117
118           example:
119
120            my $dt = DateTime::Format::Flexible->parse_datetime(
121                '16/06/2010' , european => 1 ,
122            );
123            # $dt is now 2010-06-16T00:00:00
124
125   base
126       gets/sets the base DateTime for incomplete dates.  Requires a valid
127       DateTime object as an argument when setting.
128
129       example:
130
131        DateTime::Format::Flexible->base( DateTime->new( year => 2009, month => 6, day => 22 ) );
132        my $dt = DateTime::Format::Flexible->parse_datetime( '23:59' );
133        # $dt is now 2009-06-22T23:59:00
134
135   build
136       an alias for parse_datetime
137
138   Example formats
139       A small list of supported formats:
140
141       YYYYMMDDTHHMMSS
142       YYYYMMDDTHHMM
143       YYYYMMDDTHH
144       YYYYMMDD
145       YYYYMM
146       MM-DD-YYYY
147       MM-D-YYYY
148       MM-DD-YY
149       M-DD-YY
150       YYYY/DD/MM
151       YYYY/M/DD
152       YYYY/MM/D
153       M-D
154       MM-D
155       M-D-Y
156       Month D, YYYY
157       Mon D, YYYY
158       Mon D, YYYY HH:MM:SS
159       ...
160
161       there are 9000+ variations that are detected correctly in the test
162       files (see t/data/* for most of them).  If you can think of any that I
163       do not cover, please let me know.
164

NOTES

166       As of version 0.11 you will get a DateTime::Infinite::Future object if
167       the passed in date is 'infinity' and a DateTime::Infinite::Past object
168       if the passed in date is '-infinity'.  If you are expecting these types
169       of strings, you might want to check for 'is_infinite()' from the object
170       returned.
171
172       example:
173
174        my $dt = DateTime::Format::Flexible->parse_datetime( 'infinity' );
175        if ( $dt->is_infinite )
176        {
177             # you have a Infinite object.
178        }
179
180       The DateTime website http://datetime.perl.org/?Modules as of february
181       2010 lists this module under 'Confusing' and recommends the use of
182       DateTime::Format::Natural.
183
184       Unfortunately I do not agree.  DateTime::Format::Natural fails more
185       than 2000 of my parsing tests.  DateTime::Format::Flexible supports
186       different types of date/time strings than DateTime::Format::Natural.  I
187       think there is utility in that can be found in both of them.
188
189       The whole goal of DateTime::Format::Flexible is to accept just about
190       any crazy date/time string that a user might care to enter.
191       DateTime::Format::Natural seems to be a little stricter in what it can
192       parse.
193

BUGS/LIMITATIONS

195       You cannot use a 1 or 2 digit year as the first field unless the year
196       is > 31:
197
198        YY-MM-DD # not supported if YY is <= 31
199        Y-MM-DD  # not supported
200
201       It gets confused with MM-DD-YY
202

AUTHOR

204       Tom Heady <cpan@punch.net>
205

COPYRIGHT & LICENSE

207       Copyright 2007-2010 Tom Heady.
208
209       This program is free software; you can redistribute it and/or modify it
210       under the terms of either:
211
212       ·   the GNU General Public License as published by the Free
213               Software Foundation; either version 1, or (at your option) any
214               later version, or
215
216       ·   the Artistic License version 2.0.
217