DateTime::Format::Natural(3pm)

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                  time_zone     => 'floating',
63                  daytime       => { morning   => 06,
64                                     afternoon => 13,
65                                     evening   => 20,
66                                   },
67        );
68
69       ·   "datetime"
70
71           Overrides the present now with a DateTime object provided.
72
73       ·   "lang"
74
75           Contains the language selected, currently limited to "en"
76           (english).  Defaults to '"en"'.
77
78       ·   "format"
79
80           Specifies the format of numeric dates, defaults to '"d/m/y"'.
81
82       ·   "prefer_future"
83
84           Prefers future time and dates. Accepts a boolean, defaults to
85           false.
86
87       ·   "time_zone"
88
89           The time zone to use when parsing and for output. Accepts any time
90           zone recognized by DateTime. Defaults to 'floating'.
91
92       ·   "daytime"
93
94           An anonymous hash reference consisting of customized daytime hours,
95           which may be selectively changed.
96

METHODS

98   parse_datetime
99       Returns a DateTime object constructed from a natural language date/time
100       string.
101
102        $dt = $parser->parse_datetime($date_string);
103        $dt = $parser->parse_datetime(string => $date_string);
104
105       ·   "string"
106
107           The date string.
108
109   parse_datetime_duration
110       Returns one or two DateTime objects constructed from a natural language
111       date/time string which may contain timespans/durations. Same interface
112       and options as "parse_datetime()", but should be explicitly called in
113       list context.
114
115        @dt = $parser->parse_datetime_duration($date_string);
116        @dt = $parser->parse_datetime_duration(string => $date_string);
117
118   extract_datetime
119       Returns parsable date/time substrings (also known as expressions)
120       extracted from the string provided; in scalar context only the first
121       parsable substring is returned, whereas in list context all parsable
122       substrings are returned.  Each extracted substring can then be passed
123       to the "parse_datetime()"/ "parse_datetime_duration()" methods.
124
125        $date_string  = $parser->extract_datetime($extract_string);
126        @date_strings = $parser->extract_datetime($extract_string);
127        # or
128        $date_string  = $parser->extract_datetime(string => $extract_string);
129        @date_strings = $parser->extract_datetime(string => $extract_string);
130
131   success
132       Returns a boolean indicating success or failure for parsing the
133       date/time string given.
134
135   error
136       Returns the error message if the parsing did not succeed.
137
138   trace
139       Returns one or two strings with the grammar keyword for the valid
140       expression parsed, traces of methods which were called within the Calc
141       class and a summary how often certain units have been modified. More
142       than one string is commonly returned for durations. Useful as a
143       debugging aid.
144

GRAMMAR

146       The grammar handling has been rewritten to be easily extendable and
147       hence everybody is encouraged to propose sensible new additions and/or
148       changes.
149
150       See the class DateTime::Format::Natural::Lang::EN if you're intending
151       to hack a bit on the grammar guts.
152

EXAMPLES

154       See the class DateTime::Format::Natural::Lang::EN for an overview of
155       currently valid input.
156

BUGS & CAVEATS

158       "parse_datetime()"/"parse_datetime_duration()" always return one or two
159       DateTime objects regardless whether the parse was successful or not. In
160       case no valid expression was found or a failure occurred, an unaltered
161       DateTime object with its initial values (most often the "current" now)
162       is likely to be returned. It is therefore recommended to use
163       "success()" to assert that the parse did succeed (at least, for common
164       uses), otherwise the absence of a parse failure cannot be guaranteed.
165
166       "parse_datetime()" is not capable of handling durations.
167

CREDITS

169       Thanks to Tatsuhiko Miyagawa for the initial inspiration. See
170       Miyagawa's journal entry <http://use.perl.org/~miyagawa/journal/31378>
171       for more information.
172
173       Furthermore, thanks to (in order of appearance) who have contributed
174       valuable suggestions and patches:
175
176        Clayton L. Scott
177        Dave Rolsky
178        CPAN Author 'SEKIMURA'
179        mike (pulsation)
180        Mark Stosberg
181        Tuomas Jormola
182        Cory Watson
183        Urs Stotz
184        Shawn M. Moore
185        Andreas J. Koenig
186        Chia-liang Kao
187        Jonny Schulz
188        Jesse Vincent
189        Jason May
190        Pat Kale
191        Ankur Gupta
192        Alex Bowley
193        Elliot Shank
194        Anirvan Chatterjee
195        Michael Reddick
196        Christian Brink
197        Giovanni Pensa
198        Andrew Sterling Hanenkamp
199        Eric Wilhelm
200        Kevin Field
201        Wes Morgan
202        Vladimir Marek
203        Rod Taylor
204        Tim Esselens
205        Colm Dougan
206        Chifung Fan
207        Xiao Yafeng
208        Roman Filippov
209        David Steinbrunner
210        Debian Perl Group
211        Tim Bunce
212        Ricardo Signes
213        Felix Ostmann
214

AUTHOR

219       Steven Schubiger <schubiger@cpan.org>
220

LICENSE

222       This program is free software; you may redistribute it and/or modify it
223       under the same terms as Perl itself.
224
225       See <http://dev.perl.org/licenses/>
226
227
228
229perl v5.30.1                      2020-01-29      DateTime::Format::Natural(3)