Provided by: libdatetime-format-natural-perl_1.18-1_all 
NAME
DateTime::Format::Natural - Parse informal natural language date/time strings
SYNOPSIS
use DateTime::Format::Natural;
$parser = DateTime::Format::Natural->new;
$dt = $parser->parse_datetime($date_string);
@dt = $parser->parse_datetime_duration($date_string);
$date_string = $parser->extract_datetime($extract_string);
@date_strings = $parser->extract_datetime($extract_string);
if ($parser->success) {
# operate on $dt/@dt, for example:
print $dt->strftime('%d.%m.%Y %H:%M:%S'), "\n";
} else {
warn $parser->error;
}
@traces = $parser->trace;
# examples
12:14 PM
next tuesday at 2am
tomorrow morning
4pm yesterday
10 weeks ago
1st tuesday last november
2nd friday in august
final thursday in april
for 3 hours
monday to friday
1 April 10 am to 1 May 8am
jan 24, 2011 12:00
DESCRIPTION
"DateTime::Format::Natural" parses informal natural language date/time strings. In addition, parsable
date/time substrings may be extracted from ordinary strings.
CONSTRUCTOR
new
Creates a new "DateTime::Format::Natural" object. Arguments to "new()" are options and not necessarily
required.
$parser = DateTime::Format::Natural->new(
datetime => DateTime->new(...),
lang => 'en',
format => 'mm/dd/yy',
prefer_future => [0|1],
demand_future => [0|1],
time_zone => 'floating',
daytime => { morning => 06,
afternoon => 13,
evening => 20,
},
);
• "datetime"
Overrides the present now with a DateTime object provided.
• "lang"
Contains the language selected, currently limited to "en" (english). Defaults to '"en"'.
• "format"
Specifies the format of numeric dates.
The format is used to influence how numeric dates are parsed. Given two numbers separated by a slash,
the month/day order expected comes from this option. If there is a third number, this option
describes where to expect the year. When this format can't be used to interpret the date, some
unambiguous dates may be parsed, but there is no form guarantee.
Current supported "month/day" formats: "dd/mm", "mm/dd".
Current supported "year/month/day" formats (with slashes): "dd/mm/yy", "dd/mm/yyyy", "mm/dd/yyyy",
"yyyy/mm/dd".
Note that all of the above formats with three units do also parse with dots or dashes as format
separators.
Furthermore, formats can be abbreviated as long as they remain unambiguous.
Defaults to '"d/m/y"'.
• "prefer_future"
Prefers future time and dates. Accepts a boolean, defaults to false.
• "demand_future"
Demands future time and dates. Similar to "prefer_future", but stronger. Accepts a boolean, defaults
to false.
• "time_zone"
The time zone to use when parsing and for output. Accepts any time zone recognized by DateTime.
Defaults to 'floating'.
• "daytime"
A hash reference consisting of customized daytime hours, which may be selectively changed.
METHODS
parse_datetime
Returns a DateTime object constructed from a natural language date/time string.
$dt = $parser->parse_datetime($date_string);
$dt = $parser->parse_datetime(string => $date_string);
• "string"
The date string.
parse_datetime_duration
Returns one or two DateTime objects constructed from a natural language date/time string which may
contain timespans/durations. Same interface and options as "parse_datetime()", but should be explicitly
called in list context.
@dt = $parser->parse_datetime_duration($date_string);
@dt = $parser->parse_datetime_duration(string => $date_string);
extract_datetime
Returns parsable date/time substrings (also known as expressions) extracted from the string provided; in
scalar context only the first parsable substring is returned, whereas in list context all parsable
substrings are returned. Each extracted substring can then be passed to the "parse_datetime()"/
"parse_datetime_duration()" methods.
$date_string = $parser->extract_datetime($extract_string);
@date_strings = $parser->extract_datetime($extract_string);
# or
$date_string = $parser->extract_datetime(string => $extract_string);
@date_strings = $parser->extract_datetime(string => $extract_string);
success
Returns a boolean indicating success or failure for parsing the date/time string given.
error
Returns the error message if the parsing did not succeed.
trace
Returns one or two strings with the grammar keyword for the valid expression parsed, traces of methods
which were called within the Calc class and a summary how often certain units have been modified. More
than one string is commonly returned for durations. Useful as a debugging aid.
GRAMMAR
The grammar handling has been rewritten to be easily extendable and hence everybody is encouraged to
propose sensible new additions and/or changes.
See the class DateTime::Format::Natural::Lang::EN if you're intending to hack a bit on the grammar guts.
EXAMPLES
See the class DateTime::Format::Natural::Lang::EN for an overview of currently valid input.
BUGS & CAVEATS
"parse_datetime()"/"parse_datetime_duration()" always return one or two DateTime objects regardless
whether the parse was successful or not. In case no valid expression was found or a failure occurred, an
unaltered DateTime object with its initial values (most often the "current" now) is likely to be
returned. It is therefore recommended to use "success()" to assert that the parse did succeed (at least,
for common uses), otherwise the absence of a parse failure cannot be guaranteed.
"parse_datetime()" is not capable of handling durations.
CREDITS
Thanks to Tatsuhiko Miyagawa for the initial inspiration. See Miyagawa's journal entry
<http://use.perl.org/~miyagawa/journal/31378> for more information.
Furthermore, thanks to (in order of appearance) who have contributed valuable suggestions and patches:
Clayton L. Scott
Dave Rolsky
CPAN Author 'SEKIMURA'
mike (pulsation)
Mark Stosberg
Tuomas Jormola
Cory Watson
Urs Stotz
Shawn M. Moore
Andreas J. Koenig
Chia-liang Kao
Jonny Schulz
Jesse Vincent
Jason May
Pat Kale
Ankur Gupta
Alex Bowley
Elliot Shank
Anirvan Chatterjee
Michael Reddick
Christian Brink
Giovanni Pensa
Andrew Sterling Hanenkamp
Eric Wilhelm
Kevin Field
Wes Morgan
Vladimir Marek
Rod Taylor
Tim Esselens
Colm Dougan
Chifung Fan
Xiao Yafeng
Roman Filippov
David Steinbrunner
Debian Perl Group
Tim Bunce
Ricardo Signes
Felix Ostmann
Joern Clausen
Jim Avera
Olaf Alders
Karen Etheridge
SEE ALSO
dateparse, DateTime, Date::Calc, <http://datetime.perl.org>
AUTHOR
Steven Schubiger <schubiger@cpan.org>
LICENSE
This program is free software; you may redistribute it and/or modify it under the same terms as Perl
itself.
See <http://dev.perl.org/licenses/>
perl v5.36.0 2023-10-26 DateTime::Format::Natural(3pm)