1DateTime::Format::NaturUasle(r3)Contributed Perl DocumenDtaatteiToinme::Format::Natural(3)
2
3
4

NAME

6       DateTime::Format::Natural - Parse informal natural language date/time
7       strings
8

SYNOPSIS

10        use DateTime::Format::Natural;
11
12        $parser = DateTime::Format::Natural->new;
13
14        $dt = $parser->parse_datetime($date_string);
15        @dt = $parser->parse_datetime_duration($date_string);
16
17        $date_string  = $parser->extract_datetime($extract_string);
18        @date_strings = $parser->extract_datetime($extract_string);
19
20        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
27        @traces = $parser->trace;
28
29        # examples
30
31        12:14 PM
32        next tuesday at 2am
33        tomorrow morning
34        4pm yesterday
35        10 weeks ago
36
37        1st tuesday last november
38        2nd friday in august
39        final thursday in april
40
41        for 3 hours
42        monday to friday
43        1 April 10 am to 1 May 8am
44
45        jan 24, 2011 12:00
46

DESCRIPTION

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

CONSTRUCTOR

53   new
54       Creates a new "DateTime::Format::Natural" object. Arguments to "new()"
55       are options and not necessarily required.
56
57        $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
70       •   "datetime"
71
72           Overrides the present now with a DateTime object provided.
73
74       •   "lang"
75
76           Contains the language selected, currently limited to "en"
77           (english).  Defaults to '"en"'.
78
79       •   "format"
80
81           Specifies the format of numeric dates.
82
83           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
90           Current supported "month/day" formats: "dd/mm", "mm/dd".
91
92           Current supported "year/month/day" formats (with slashes):
93           "dd/mm/yy", "dd/mm/yyyy", "mm/dd/yyyy", "yyyy/mm/dd".
94
95           Note that all of the above formats with three units do also parse
96           with dots or dashes as format separators.
97
98           Furthermore, formats can be abbreviated as long as they remain
99           unambiguous.
100
101           Defaults to '"d/m/y"'.
102
103       •   "prefer_future"
104
105           Prefers future time and dates. Accepts a boolean, defaults to
106           false.
107
108       •   "demand_future"
109
110           Demands future time and dates. Similar to "prefer_future", but
111           stronger.  Accepts a boolean, defaults to false.
112
113       •   "time_zone"
114
115           The time zone to use when parsing and for output. Accepts any time
116           zone recognized by DateTime. Defaults to 'floating'.
117
118       •   "daytime"
119
120           An anonymous hash reference consisting of customized daytime hours,
121           which may be selectively changed.
122

METHODS

124   parse_datetime
125       Returns a DateTime object constructed from a natural language date/time
126       string.
127
128        $dt = $parser->parse_datetime($date_string);
129        $dt = $parser->parse_datetime(string => $date_string);
130
131       •   "string"
132
133           The date string.
134
135   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
141        @dt = $parser->parse_datetime_duration($date_string);
142        @dt = $parser->parse_datetime_duration(string => $date_string);
143
144   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
151        $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
157   success
158       Returns a boolean indicating success or failure for parsing the
159       date/time string given.
160
161   error
162       Returns the error message if the parsing did not succeed.
163
164   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

GRAMMAR

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
176       See the class DateTime::Format::Natural::Lang::EN if you're intending
177       to hack a bit on the grammar guts.
178

EXAMPLES

180       See the class DateTime::Format::Natural::Lang::EN for an overview of
181       currently valid input.
182

BUGS & CAVEATS

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
189       "success()" to assert that the parse did succeed (at least, for common
190       uses), otherwise the absence of a parse failure cannot be guaranteed.
191
192       "parse_datetime()" is not capable of handling durations.
193

CREDITS

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
199       Furthermore, thanks to (in order of appearance) who have contributed
200       valuable suggestions and patches:
201
202        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. Koenig
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        Joern Clausen
241

SEE ALSO

243       dateparse, DateTime, Date::Calc, <http://datetime.perl.org>
244

AUTHOR

246       Steven Schubiger <schubiger@cpan.org>
247

LICENSE

249       This program is free software; you may redistribute it and/or modify it
250       under the same terms as Perl itself.
251
252       See <http://dev.perl.org/licenses/>
253
254
255
256perl v5.36.0                      2022-07-22      DateTime::Format::Natural(3)
Impressum