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