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(
12             'January 8, 1999'
13         );
14         # $dt = a DateTime object set at 1999-01-08T00:00:00
15

DESCRIPTION

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

USAGE

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

NOTES

198       As of version 0.11 you will get a DateTime::Infinite::Future object if
199       the passed in date is 'infinity' and a DateTime::Infinite::Past object
200       if the passed in date is '-infinity'.  If you are expecting these types
201       of strings, you might want to check for 'is_infinite()' from the object
202       returned.
203
204       example:
205
206        my $dt = DateTime::Format::Flexible->parse_datetime( 'infinity' );
207        if ( $dt->is_infinite )
208        {
209             # you have a Infinite object.
210        }
211

BUGS/LIMITATIONS

213       You cannot use a 1 or 2 digit year as the first field unless the year
214       is > 31:
215
216        YY-MM-DD # not supported if YY is <= 31
217        Y-MM-DD  # not supported
218
219       It gets confused with MM-DD-YY
220

AUTHOR

222       Tom Heady <cpan@punch.net>
223

COPYRIGHT & LICENSE

225       Copyright 2007-2018 Tom Heady.
226
227       This program is free software; you can redistribute it and/or modify it
228       under the terms of either:
229
230       •   the GNU General Public License as published by the Free
231               Software Foundation; either version 1, or (at your option) any
232               later version, or
233
234       •   the Artistic License.
235