1DateTime::Format::NaturUasle(r3)Contributed Perl DocumenDtaatteiToinme::Format::Natural(3)
2
6 DateTime::Format::Natural - Parse informal natural language date/time
7 strings
8
10 use DateTime::Format::Natural;
11 $parser = DateTime::Format::Natural->new;
13 $dt = $parser->parse_datetime($date_string);
15 @dt = $parser->parse_datetime_duration($date_string);
16 $date_string = $parser->extract_datetime($extract_string);
18 @date_strings = $parser->extract_datetime($extract_string);
19 if ($parser->success) {
21 # operate on $dt/@dt, for example:
22 print $dt->strftime('%d.%m.%Y %H:%M:%S'), "\n";
23 } else {
24 warn $parser->error;
25 }
26 @traces = $parser->trace;
28 # examples
30 12:14 PM
32 next tuesday at 2am
33 tomorrow morning
34 4pm yesterday
35 10 weeks ago
36 1st tuesday last november
38 2nd friday in august
39 final thursday in april
40 for 3 hours
42 monday to friday
43 1 April 10 am to 1 May 8am
44 jan 24, 2011 12:00
46
48 "DateTime::Format::Natural" parses informal natural language date/time
49 strings. In addition, parsable date/time substrings may be extracted
50 from ordinary strings.
51
53 new
54 Creates a new "DateTime::Format::Natural" object. Arguments to new()
55 are options and not necessarily required.
56 $parser = DateTime::Format::Natural->new(
58 datetime => DateTime->new(...),
59 lang => 'en',
60 format => 'mm/dd/yy',
61 prefer_future => [0|1],
62 demand_future => [0|1],
63 time_zone => 'floating',
64 daytime => { morning => 06,
65 afternoon => 13,
66 evening => 20,
67 },
68 );
69 • "datetime"
71 Overrides the present now with a DateTime object provided.
73 • "lang"
75 Contains the language selected, currently limited to "en"
77 (english). Defaults to '"en"'.
78 • "format"
80 Specifies the format of numeric dates.
82 The format is used to influence how numeric dates are parsed. Given
84 two numbers separated by a slash, the month/day order expected
85 comes from this option. If there is a third number, this option
86 describes where to expect the year. When this format can't be used
87 to interpret the date, some unambiguous dates may be parsed, but
88 there is no form guarantee.
89 Current supported "month/day" formats: "dd/mm", "mm/dd".
91 Current supported "year/month/day" formats (with slashes):
93 "dd/mm/yy", "dd/mm/yyyy", "mm/dd/yyyy", "yyyy/mm/dd".
94 Note that all of the above formats with three units do also parse
96 with dots or dashes as format separators.
97 Furthermore, formats can be abbreviated as long as they remain
99 unambiguous.
100 Defaults to '"d/m/y"'.
102 • "prefer_future"
104 Prefers future time and dates. Accepts a boolean, defaults to
106 false.
107 • "demand_future"
109 Demands future time and dates. Similar to "prefer_future", but
111 stronger. Accepts a boolean, defaults to false.
112 • "time_zone"
114 The time zone to use when parsing and for output. Accepts any time
116 zone recognized by DateTime. Defaults to 'floating'.
117 • "daytime"
119 An anonymous hash reference consisting of customized daytime hours,
121 which may be selectively changed.
122
124 parse_datetime
125 Returns a DateTime object constructed from a natural language date/time
126 string.
127 $dt = $parser->parse_datetime($date_string);
129 $dt = $parser->parse_datetime(string => $date_string);
130 • "string"
132 The date string.
134 parse_datetime_duration
136 Returns one or two DateTime objects constructed from a natural language
137 date/time string which may contain timespans/durations. Same interface
138 and options as parse_datetime(), but should be explicitly called in
139 list context.
140 @dt = $parser->parse_datetime_duration($date_string);
142 @dt = $parser->parse_datetime_duration(string => $date_string);
143 extract_datetime
145 Returns parsable date/time substrings (also known as expressions)
146 extracted from the string provided; in scalar context only the first
147 parsable substring is returned, whereas in list context all parsable
148 substrings are returned. Each extracted substring can then be passed
149 to the parse_datetime()/ parse_datetime_duration() methods.
150 $date_string = $parser->extract_datetime($extract_string);
152 @date_strings = $parser->extract_datetime($extract_string);
153 # or
154 $date_string = $parser->extract_datetime(string => $extract_string);
155 @date_strings = $parser->extract_datetime(string => $extract_string);
156 success
158 Returns a boolean indicating success or failure for parsing the
159 date/time string given.
160 error
162 Returns the error message if the parsing did not succeed.
163 trace
165 Returns one or two strings with the grammar keyword for the valid
166 expression parsed, traces of methods which were called within the Calc
167 class and a summary how often certain units have been modified. More
168 than one string is commonly returned for durations. Useful as a
169 debugging aid.
170
172 The grammar handling has been rewritten to be easily extendable and
173 hence everybody is encouraged to propose sensible new additions and/or
174 changes.
175 See the class DateTime::Format::Natural::Lang::EN if you're intending
177 to hack a bit on the grammar guts.
178
180 See the class DateTime::Format::Natural::Lang::EN for an overview of
181 currently valid input.
182
184 parse_datetime()/parse_datetime_duration() always return one or two
185 DateTime objects regardless whether the parse was successful or not. In
186 case no valid expression was found or a failure occurred, an unaltered
187 DateTime object with its initial values (most often the "current" now)
188 is likely to be returned. It is therefore recommended to use success()
189 to assert that the parse did succeed (at least, for common uses),
190 otherwise the absence of a parse failure cannot be guaranteed.
191 parse_datetime() is not capable of handling durations.
193
195 Thanks to Tatsuhiko Miyagawa for the initial inspiration. See
196 Miyagawa's journal entry <http://use.perl.org/~miyagawa/journal/31378>
197 for more information.
198 Furthermore, thanks to (in order of appearance) who have contributed
200 valuable suggestions and patches:
201 Clayton L. Scott
203 Dave Rolsky
204 CPAN Author 'SEKIMURA'
205 mike (pulsation)
206 Mark Stosberg
207 Tuomas Jormola
208 Cory Watson
209 Urs Stotz
210 Shawn M. Moore
211 Andreas J. König
212 Chia-liang Kao
213 Jonny Schulz
214 Jesse Vincent
215 Jason May
216 Pat Kale
217 Ankur Gupta
218 Alex Bowley
219 Elliot Shank
220 Anirvan Chatterjee
221 Michael Reddick
222 Christian Brink
223 Giovanni Pensa
224 Andrew Sterling Hanenkamp
225 Eric Wilhelm
226 Kevin Field
227 Wes Morgan
228 Vladimir Marek
229 Rod Taylor
230 Tim Esselens
231 Colm Dougan
232 Chifung Fan
233 Xiao Yafeng
234 Roman Filippov
235 David Steinbrunner
236 Debian Perl Group
237 Tim Bunce
238 Ricardo Signes
239 Felix Ostmann
240 Jörn Clausen
241 Jim Avera
242 Olaf Alders
243 Karen Etheridge
244
246 dateparse, DateTime, Date::Calc, <http://datetime.perl.org>
247
249 Steven Schubiger <schubiger@cpan.org>
250
252 This program is free software; you may redistribute it and/or modify it
253 under the same terms as Perl itself.
254 See <http://dev.perl.org/licenses/>
256perl v5.36.0 2023-02-05 DateTime::Format::Natural(3)