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

SYNOPSIS

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

DESCRIPTION

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

PARSING

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

"last second of first month of year of 2005"

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

METHODS

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

EXPORT

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

MOTIVATION

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

THANKS

221       Dave Rolsky and crew for writing DateTime
222

AUTHOR

239       Robert Krimen <rokr@cpan.org>
240

COPYRIGHT AND LICENSE

242       This software is copyright (c) 2022 by Robert Krimen and others, see
243       the git log.
244
245       This is free software; you can redistribute it and/or modify it under
246       the same terms as the Perl 5 programming language system itself.
247
248
249
250perl v5.36.0                      2023-01-20                DateTimeX::Easy(3)