1DateTime::Format::NaturUasle(r3)Contributed Perl DocumenDtaatteiToinme::Format::Natural(3)
2
6 DateTime::Format::Natural - Create machine readable date/time with
7 natural parsing logic
8
10 use DateTime::Format::Natural;
11 $parser = DateTime::Format::Natural->new;
13 $date_string = $parser->extract_datetime($extract_string);
15 @date_strings = $parser->extract_datetime($extract_string);
16 $dt = $parser->parse_datetime($date_string);
18 @dt = $parser->parse_datetime_duration($date_string);
19 if ($parser->success) {
21 # operate on $dt/@dt, for example:
22 printf("%02d.%02d.%4d %02d:%02d:%02d\n", $dt->day,
23 $dt->month,
24 $dt->year,
25 $dt->hour,
26 $dt->min,
27 $dt->sec);
28 } else {
29 warn $parser->error;
30 }
31 @traces = $parser->trace;
33
35 "DateTime::Format::Natural" takes a string with a human readable
36 date/time and creates a machine readable one by applying natural
37 parsing logic.
38
40 new
41 Creates a new "DateTime::Format::Natural" object. Arguments to "new()"
42 are options and not necessarily required.
43 $parser = DateTime::Format::Natural->new(
45 datetime => DateTime->new(...),
46 lang => 'en',
47 format => 'mm/dd/yy',
48 prefer_future => '[0|1]',
49 time_zone => 'floating',
50 daytime => { morning => 06,
51 afternoon => 13,
52 evening => 20,
53 },
54 );
55 · "datetime"
57 Overrides the present now with a DateTime object provided.
59 · "lang"
61 Contains the language selected, currently limited to "en"
63 (english). Defaults to '"en"'.
64 · "format"
66 Specifies the format of numeric dates, defaults to '"d/m/y"'.
68 · "prefer_future"
70 Turns ambiguous weekdays/months to their future relatives. Accepts
72 a boolean, defaults to false.
73 · "time_zone"
75 The time zone to use when parsing and for output. Accepts any time
77 zone recognized by DateTime. Defaults to 'floating'.
78 · "daytime"
80 An anonymous hash reference consisting of customized daytime hours,
82 which may be selectively changed.
83
85 parse_datetime
86 Returns a DateTime object constructed from a human readable date/time
87 string.
88 $dt = $parser->parse_datetime($date_string);
90 $dt = $parser->parse_datetime(string => $date_string);
91 · "string"
93 The date string.
95 parse_datetime_duration
97 Returns one or two DateTime objects constructed from a human readable
98 date/time string which may contain timespans/durations. Same interface
99 and options as "parse_datetime()", but should be explicitly called in
100 list context.
101 @dt = $parser->parse_datetime_duration($date_string);
103 @dt = $parser->parse_datetime_duration(string => $date_string);
104 extract_datetime
106 Returns parsable date/time substrings (also known as expressions)
107 extracted from the string provided; in scalar context only the first
108 parsable substring is returned, whereas in list context all parsable
109 substrings are returned. Each extracted substring can then be passed
110 to the "parse_datetime()"/ "parse_datetime_duration()" methods.
111 $date_string = $parser->extract_datetime($extract_string);
113 @date_strings = $parser->extract_datetime($extract_string);
114 # or
115 $date_string = $parser->extract_datetime(string => $extract_string);
116 @date_strings = $parser->extract_datetime(string => $extract_string);
117 success
119 Returns a boolean indicating success or failure for parsing the
120 date/time string given.
121 error
123 Returns the error message if the parsing did not succeed.
124 trace
126 Returns one or two strings with the grammar keyword for the valid
127 expression parsed, traces of methods which were called within the Calc
128 class and a summary how often certain units have been modified. More
129 than one string is commonly returned for durations. Useful as a
130 debugging aid.
131
133 The grammar handling has been rewritten to be easily extendable and
134 hence everybody is encouraged to propose sensible new additions and/or
135 changes.
136 See the classes "DateTime::Format::Natural::Lang::[language_code]" if
138 you're intending to hack a bit on the grammar guts.
139
141 See the classes "DateTime::Format::Natural::Lang::[language_code]" for
142 an overview of currently valid input.
143
145 "parse_datetime()"/"parse_datetime_duration()" always return one or two
146 DateTime objects regardless whether the parse was successful or not. In
147 case no valid expression was found or a failure occurred, an unaltered
148 DateTime object with its initial values (most often the "current" now)
149 is likely to be returned. It is therefore recommended to use
150 "success()" to assert that the parse did succeed (at least, for common
151 uses), otherwise the absence of a parse failure cannot be guaranteed.
152 "parse_datetime()" is not capable of handling durations.
154
156 Thanks to Tatsuhiko Miyagawa for the initial inspiration. See
157 Miyagawa's journal entry <http://use.perl.org/~miyagawa/journal/31378>
158 for more information.
159 Furthermore, thanks to (in order of appearance) who have contributed
161 valuable suggestions and patches:
162 Clayton L. Scott
164 Dave Rolsky
165 CPAN Author 'SEKIMURA'
166 mike (pulsation)
167 Mark Stosberg
168 Tuomas Jormola
169 Cory Watson
170 Urs Stotz
171 Shawn M. Moore
172 Andreas J. Koenig
173 Chia-liang Kao
174 Jonny Schulz
175 Jesse Vincent
176 Jason May
177 Pat Kale
178 Ankur Gupta
179 Alex Bowley
180 Elliot Shank
181 Anirvan Chatterjee
182 Michael Reddick
183 Christian Brink
184 Giovanni Pensa
185 Andrew Sterling Hanenkamp
186 Eric Wilhelm
187 Kevin Field
188 Wes Morgan
189 Vladimir Marek
190 Rod Taylor
191 Tim Esselens
192 Colm Dougan
193 Chifung Fan
194 Xiao Yafeng
195
197 DateTime, Date::Calc, <http://datetime.perl.org>
198
200 Steven Schubiger <schubiger@cpan.org>
201
203 This program is free software; you may redistribute it and/or modify it
204 under the same terms as Perl itself.
205 See <http://dev.perl.org/licenses/>
207perl v5.12.4 2011-11-06 DateTime::Format::Natural(3)