DateTime::Format::Natural - Create machine readable date/time with natural parsing logic
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;
DateTime::Format::Natural takes a string with a human readable date/time and creates a machine readable one by applying natural parsing logic.
DateTime::Format::Natural
Creates a new DateTime::Format::Natural object. Arguments to new() are options and not necessarily required.
new()
$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'.
en
format
Specifies the format of numeric dates, defaults to 'd/m/y'.
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.
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.
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.
parse_datetime()
@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.
parse_datetime_duration()
$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);
Returns a boolean indicating success or failure for parsing the date/time string given.
Returns the error message if the parsing did not succeed.
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.
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.
DateTime::Format::Natural::Lang::[language_code]
See the classes DateTime::Format::Natural::Lang::[language_code] for an overview of currently valid input.
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.
success()
parse_datetime() is not capable of handling durations.
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. König 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
DateTime, Date::Calc, http://datetime.perl.org
Steven Schubiger <schubiger@cpan.org>
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/
1 POD Error
The following errors were encountered while parsing the POD:
Non-ASCII character seen before =encoding in 'König'. Assuming CP1252
To install DateTime::Format::Natural, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DateTime::Format::Natural
CPAN shell
perl -MCPAN -e shell install DateTime::Format::Natural
For more information on module installation, please visit the detailed CPAN module installation guide.