NAME

DateTime::Format::Natural - Create machine readable date/time with natural parsing logic

SYNOPSIS

use DateTime::Format::Natural;

$parser = DateTime::Format::Natural->new;

$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;
}

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 futuristic 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

  A hash reference consisting of customized daytime hours, which may be selectively changed.

METHODS

parse_datetime

Creates a DateTime object 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 a DateTime object.

parse_datetime_duration

Creates one or more DateTime object(s) from a human readable date/time string which may contain timespans/durations. 'Same' interface & options as parse_datetime(), but must be explicitly called in list context.

@dt = $parser->parse_datetime_duration($date_string);
@dt = $parser->parse_datetime_duration(string => $date_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 a trace of methods which were called within the Base class and a summary how often certain units have been modified.

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 a overview of current valid input.

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 & 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

SEE ALSO

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://www.perl.com/perl/misc/Artistic.html

cpanm DateTime::Format::Natural

perl -MCPAN -e shell
install DateTime::Format::Natural