DateTimeX::Easy(3pm)

1DateTimeX::Easy(3)    User Contributed Perl Documentation   DateTimeX::Easy(3)
2
3
4

NAME

6       DateTimeX::Easy - Parse a date/time string using the best method
7       available
8

VERSION

10       Version 0.088
11

SYNOPSIS

13           # Make DateTimeX object for "now":
14           my $dt = DateTimeX::Easy->new("today");
15
16           # Same thing:
17           my $dt = DateTimeX::Easy->new("now");
18
19           # Uses ::F::Natural's coolness (similar in capability to Date::Manip)
20           my $dt = DateTimeX::Easy->new("last monday");
21
22           # ... but in 1969:
23           my $dt = DateTimeX::Easy->new("last monday", year => 1969);
24
25           # ... at the 100th nanosecond:
26           my $dt = DateTimeX::Easy->new("last monday", year => 1969, nanosecond => 100);
27
28           # ... in US/Eastern: (This will NOT do a timezone conversion)
29           my $dt = DateTimeX::Easy->new("last monday", year => 1969, nanosecond => 100, timezone => "US/Eastern");
30
31           # This WILL do a proper timezone conversion:
32           my $dt = DateTimeX::Easy->new("last monday", year => 1969, nanosecond => 100, timezone => "US/Pacific");
33           $dt->set_time_zone("US/Eastern");
34
35           # Custom DateTimeX ability:
36           my $dt = DateTimeX::Easy->new("last second of last month");
37           $dt = DateTimeX::Easy->new("last second of first month of last year");
38           $dt = DateTimeX::Easy->new("last second of first month of 2000");
39

DESCRIPTION

41       DateTimeX::Easy makes DateTime object creation quick and easy. It uses
42       a variety of DateTime::Format packages to do the bulk of the parsing,
43       with some custom tweaks to smooth out the rough edges (mainly
44       concerning timezone detection and selection).
45

PARSING

47       Currently, DateTimeX::Easy will attempt to parse input in the following
48       order:
49
50       DateTime - Is the input a DateTime object?
51       ICal - Was DT::F::ICal able to parse the input?
52       DateParse - Was DT::F::DateParse able to parse the input?
53           A caveat, I actually use a modified version of DateParse in order
54           to avoid DateParse's default timezone selection.
55
56       Natural - Was DT::F::Natural able to parse the input?
57           Since this module barfs pretty loudly on strange input, we use a
58           silent $SIG{__WARN__} to hide errors.
59
60       Flexible - Was DT::F::Flexible able to parse the input?
61           This step also looks at the string to see if there is any timezone
62           information at the end.
63
64       DateManip - Was DT::F::DateManip able to parse the input?
65           DateManip isn't very nice with preserving the input timezone, but
66           it's here as a last resort.
67

"last second of first month of year of 2005"

69       DateTimeX::Easy also provides additional parsing and transformation for
70       input like:
71
72           "first day of last month"
73           "last day of last month"
74           "last day of this month"
75           "last day of next month"
76           "last second of first month of last year"
77           "ending day of month of 2007-10-02"
78           "last second of first month of year of 2005"
79           "last second of last month of year of 2005"
80           "beginning day of month of 2007-10-02"
81           "last month of year of 2007"
82
83       It will look at each sequence of "<first|last> of <period>" and do
84       ->add, ->subtract, and ->truncate operations on the parsed DateTime
85       object
86
87       Also, It's best to be as explicit as possible; the following will work:
88
89           "last month of 2007"
90           "last second of last month of 2005"
91           "beginning day of 2007-10-02"
92
93       This won't, though:
94
95           "last day of 2007"
96
97       You'll have to do this instead:
98
99           "last day of year of 2007"
100
101       The reason is that the date portion is opaque to the parser. It doesn't
102       know whether it has "2007" or "2007-10" or "now" as the last input. To
103       fix this, you can give a hint to the parser, like "<period> of
104       <date/time>" (as in "year of 2007" above).
105
106       WARNING: This feature is still somewhat new, so there may be bugs
107       lurking about. Please forward failing tests/scenarios.
108

METHODS

110   DateTimeX::Easy->new( ... )
111   DateTimeX::Easy->parse( ... )
112   DateTimeX::Easy->parse_date( ... )
113   DateTimeX::Easy->parse_datetime( ... )
114   DateTimeX::Easy->date( ... )
115   DateTimeX::Easy->datetime( ... )
116   DateTimeX::Easy->new_date( ... )
117   DateTimeX::Easy->new_datetime( ... )
118       Parse the given date/time specification using ::F::Flexible or
119       ::F::Natural and use the result to create a DateTime object. Returns a
120       DateTime object.
121
122       You can pass the following in:
123
124           parse       # The string or DateTime object to parse.
125
126           year        # A year to override the result of parsing
127           month       # A month to override the result of parsing
128           day         # A day to override the result of parsing
129           hour        # A hour to override the result of parsing
130           minute      # A minute to override the result of parsing
131           second      # A second to override the result of parsing
132
133           truncate    # A truncation parameter (e.g. year, day, month, week, etc.)
134
135           time_zone   # - Can be:
136           timezone    # * A timezone (e.g. US/Pacific, UTC, etc.)
137           tz          # * A DateTime special timezone (e.g. floating, local)
138                       #
139                       # - If neither "tz", "timezone", nor "time_zone" is set, then it'll use whatever is parsed.
140                       # - If no timezone is parsed, then the default is floating.
141                       # - If the given timezone is different from the parsed timezone,
142                       #   then a time conversion will take place (unless "soft_time_zone_conversion" is set).
143                       # - Either "time_zone", "timezone", "tz" will work (in that order), with "time_zone" having highest precedence
144                       # - See below for examples!
145
146           soft_time_zone_conversion   # Set this flag to 1 if you don't want the time to change when a given timezone is
147                                       # different from a parsed timezone. For example, "10:00 UTC" soft converted to
148                                       # PST8PDT would be "10:00 PST8PDT".
149
150           time_zone_if_floating       # The value of this option should be a valid timezone. If this option is set, then a DateTime object
151                                       # with a floating timezone has it's timezone set to the value.
152           default_time_zone           # Same as "time_zone_if_floating"
153
154           ambiguous   # Set this flag to 0 if you want to disallow ambiguous input like:
155                       # "last day of 2007" or "first minute of April"
156                       # This will require you to specify them as "last day of year of 2007" and "first minute of month of April"
157                       # instead. This flag is 1 (false) by default.
158
159           ... and anything else that you want to pass to the DateTime->new constructor
160
161       If "truncate" is specificied, then DateTime->truncate will be run after
162       object creation.
163
164       Furthermore, you can simply pass the value for "parse" as the first
165       positional argument of the DateTimeX::Easy call, e.g.:
166
167           # This:
168           DateTimeX::Easy->new("today", year => 2008, truncate => "hour");
169
170           # ... is the same as this:
171           DateTimeX::Easy->new(parse => "today", year => 2008, truncate => "hour");
172
173       Timezone processing can be a little complicated.  Here are some
174       examples:
175
176           DateTimeX::Easy->parse("today"); # Will use a floating timezone
177
178           DateTimeX::Easy->parse("2007-07-01 10:32:10"); # Will ALSO use a floating timezone
179
180           DateTimeX::Easy->parse("2007-07-01 10:32:10 US/Eastern"); # Will use US/Eastern as a timezone
181
182           DateTimeX::Easy->parse("2007-07-01 10:32:10"); # Will use the floating timezone
183
184           DateTimeX::Easy->parse("2007-07-01 10:32:10", time_zone_if_floating => "local"); # Will use the local timezone
185
186           DateTimeX::Easy->parse("2007-07-01 10:32:10 UTC", time_zone => "US/Pacific"); # Will convert from UTC to US/Pacific
187
188           my $dt = DateTime->now->set_time_zone("US/Eastern");
189           DateTimeX::Easy->parse($dt); # Will use US/Eastern as the timezone
190
191           DateTimeX::Easy->parse($dt, time_zone => "floating"); # Will use a floating timezone
192
193           DateTimeX::Easy->parse($dt, time_zone => "US/Pacific", soft_time_zone_conversion => 1);
194                                                                   # Will use US/Pacific as the timezone with NO conversion
195                                                                   # For example, "22:00 US/Eastern" will become "22:00 PST8PDT"
196
197           DateTimeX::Easy->parse($dt)->set_time_zone("US/Pacific"); # Will use US/Pacific as the timezone WITH conversion
198                                                                     # For example, "22:00 US/Eastern" will become "19:00 PST8PDT"
199
200           DateTimeX::Easy->parse($dt, time_zone => "US/Pacific"); # Will ALSO use US/Pacific as the timezone WITH conversion
201

EXPORT

203   parse( ... )
204   parse_date( ... )
205   parse_datetime( ... )
206   date( ... )
207   datetime( ... )
208   new_date( ... )
209   new_datetime( ... )
210       Same syntax as above. See above for more information.
211

MOTIVATION

213       Although I really like using DateTime for date/time handling, I was
214       often frustrated by its inability to parse even the simplest of
215       date/time strings.  There does exist a wide variety of
216       DateTime::Format::* modules, but they all have different interfaces and
217       different capabilities.  Coming from a Date::Manip background, I wanted
218       something that gave me the power of ParseDate while still returning a
219       DateTime object.  Most importantly, I wanted explicit control of the
220       timezone setting at every step of the way. DateTimeX::Easy is the
221       result.
222

THANKS

224       Dave Rolsky and crew for writing DateTime
225

AUTHOR

242       Robert Krimen, "<rkrimen at cpan.org>"
243

SOURCE

245       You can contribute or fork this project via GitHub:
246
247       http://github.com/robertkrimen/datetimex-easy/tree/master
248       <http://github.com/robertkrimen/datetimex-easy/tree/master>
249
250           git clone git://github.com/robertkrimen/datetimex-easy.git DateTimeX-Easy
251

BUGS

253       Please report any bugs or feature requests to "bug-datetime-easy at
254       rt.cpan.org", or through the web interface at
255       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DateTimeX-Easy
256       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DateTimeX-Easy>.  I
257       will be notified, and then you'll automatically be notified of progress
258       on your bug as I make changes.
259

SUPPORT

261       You can find documentation for this module with the perldoc command.
262
263           perldoc DateTimeX::Easy
264
265       You can also look for information at:
266
267       ·   RT: CPAN's request tracker
268
269           http://rt.cpan.org/NoAuth/Bugs.html?Dist=DateTimeX-Easy
270           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=DateTimeX-Easy>
271
272       ·   AnnoCPAN: Annotated CPAN documentation
273
274           http://annocpan.org/dist/DateTimeX-Easy
275           <http://annocpan.org/dist/DateTimeX-Easy>
276
277       ·   CPAN Ratings
278
279           http://cpanratings.perl.org/d/DateTimeX-Easy
280           <http://cpanratings.perl.org/d/DateTimeX-Easy>
281
282       ·   Search CPAN
283
284           http://search.cpan.org/dist/DateTimeX-Easy
285           <http://search.cpan.org/dist/DateTimeX-Easy>
286

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

289       Copyright 2007 Robert Krimen, all rights reserved.
290
291       This program is free software; you can redistribute it and/or modify it
292       under the same terms as Perl itself.
293
294
295
296perl v5.12.0                      2010-01-07                DateTimeX::Easy(3)