NAME¶
DateTime::Format::Natural - Create machine readable date/time with natural
parsing logic
SYNOPSIS¶
use DateTime::Format::Natural;
$parser = DateTime::Format::Natural->new;
$date_string = $parser->extract_datetime($extract_string);
@date_strings = $parser->extract_datetime($extract_string);
$dt = $parser->parse_datetime($date_string);
@dt = $parser->parse_datetime_duration($date_string);
if ($parser->success) {
# operate on $dt/@dt, for example:
printf("%02d.%02d.%4d %02d:%02d:%02d\n", $dt->day,
$dt->month,
$dt->year,
$dt->hour,
$dt->min,
$dt->sec);
} else {
warn $parser->error;
}
@traces = $parser->trace;
DESCRIPTION¶
"DateTime::Format::Natural" takes a string with a human readable
date/time and creates a machine readable one by applying natural parsing
logic.
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]',
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, defaults to '"d/m/y"'.
- •
- "prefer_future"
Turns ambiguous weekdays/months to their future relatives. 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"
An anonymous hash reference consisting of customized daytime hours, which
may be selectively changed.
METHODS¶
parse_datetime¶
Returns a DateTime object constructed from a human readable 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 human readable 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);
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 classes "DateTime::Format::Natural::Lang::[language_code]" if
you're intending to hack a bit on the grammar guts.
EXAMPLES¶
See the classes "DateTime::Format::Natural::Lang::[language_code]" 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
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/>