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]',
                  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 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

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