README
1NAME
2 DateTime::Format::Flexible - DateTime::Format::Flexible - Flexibly parse
3 strings and turn them into DateTime objects.
4
5SYNOPSIS
6 use DateTime::Format::Flexible;
7 my $dt = DateTime::Format::Flexible->parse_datetime( 'January 8, 1999' );
8 # $dt = a DateTime object set at 1999-01-08T00:00:00
9
10DESCRIPTION
11 If you have ever had to use a program that made you type in the date a
12 certain way and thought "Why can't the computer just figure out what
13 date I wanted?", this module is for you.
14
15 DateTime::Format::Flexible attempts to take any string you give it and
16 parse it into a DateTime object.
17
18 The test file tests 2500+ variations of date/time strings. If you can
19 think of any that I do not cover, please let me know.
20
21USAGE
22 This module uses DateTime::Format::Builder under the covers.
23
24 build, parse_datetime
25 build and parse_datetime do the same thing. Give it a string and it
26 attempts to parse it and return a DateTime object.
27
28 If it can't it will throw an exception.
29
30 my $dt = DateTime::Format::Flexible->build( $date );
31
32 my $dt = DateTime::Format::Flexible->parse_datetime( $date );
33
34 my $dt = DateTime::Format::Flexible->parse_datetime(
35 $date,
36 strip => [qr{\.\z}],
37 tz_map => {EDT => 'America/New_York'},
38 european => 1
39 );
40
41 * "strip"
42
43 Remove a substring from the string you are trying to parse. You can
44 pass multiple regexes in an arrayref.
45
46 example:
47
48 my $dt = DateTime::Format::Flexible->parse_datetime(
49 '2011-04-26 00:00:00 (registry time)' ,
50 strip => [qr{\(registry time\)\z}] ,
51 );
52 # $dt is now 2011-04-26T00:00:00
53
54 This is helpful if you have a load of dates you want to normalize
55 and you know of some weird formatting beforehand.
56
57 * "tz_map"
58
59 map a given timezone to another recognized timezone Values are given
60 as a hashref.
61
62 example:
63
64 my $dt = DateTime::Format::Flexible->parse_datetime(
65 '25-Jun-2009 EDT' ,
66 tz_map => {EDT => 'America/New_York'}
67 );
68 # $dt is now 2009-06-25T00:00:00 with a timezone of America/New_York
69
70 This is helpful if you have a load of dates that have timezones that
71 are not recognized by DateTime::Timezone.
72
73 * "european"
74
75 If european is set to a true value, an attempt will be made to parse
76 as a DD-MM-YYYY date instead of the default MM-DD-YYYY. There is a
77 chance that this will not do the right thing due to ambiguity.
78
79 example:
80
81 my $dt = DateTime::Format::Flexible->parse_datetime(
82 '16/06/2010' , european => 1 ,
83 );
84 # $dt is now 2010-06-16T00:00:00
85
86 Example formats
87 A small list of supported formats:
88
89 YYYYMMDDTHHMMSS
90 YYYYMMDDTHHMM
91 YYYYMMDDTHH
92 YYYYMMDD
93 YYYYMM
94 MM-DD-YYYY
95 MM-D-YYYY
96 MM-DD-YY
97 M-DD-YY
98 YYYY/DD/MM
99 YYYY/M/DD
100 YYYY/MM/D
101 M-D
102 MM-D
103 M-D-Y
104 Month D, YYYY
105 Mon D, YYYY
106 Mon D, YYYY HH:MM:SS
107 ...
108
109 there are 9000+ variations that are detected correctly in the test files
110 (see t/data/* for most of them).
111
112NOTES
113 The DateTime website http://datetime.perl.org/?Modules as of march 2008
114 lists this module under 'Confusing' and recommends the use of
115 DateTime::Format::Natural.
116
117 Unfortunately I do not agree. DateTime::Format::Natural currently fails
118 more than 2000 of my parsing tests. DateTime::Format::Flexible supports
119 different types of date/time strings than DateTime::Format::Natural. I
120 think there is utility in that can be found in both of them.
121
122 The whole goal of DateTime::Format::Flexible is to accept just about any
123 crazy date/time string that a user might care to enter.
124 DateTime::Format::Natural seems to be a little stricter in what it can
125 parse.
126
127BUGS
128 You cannot use a 1 or 2 digit year as the first field:
129
130 YY-MM-DD # not supported
131 Y-MM-DD # not supported
132
133 It would get confused with MM-DD-YY
134
135AUTHOR
136 Tom Heady
137 CPAN ID: thinc
138 Punch, Inc.
139 cpan@punch.net
140 http://www.punch.net/
141
142COPYRIGHT and LICENSE
143 Copyright 2007-2018 Tom Heady
144
145 This program is free software; you can redistribute it and/or modify it
146 under the same terms as Perl itself.
147
148 The full text of the license can be found in the LICENSE file included
149 with this module.
150
151SEE ALSO
152 DateTime::Format::Builder, DateTime::Timezone, DateTime::Format::Natural
153
154