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',
               calendar_class => 'DateTime::Calendar::Julian',
               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'.

      * calendar_class

      The calendar class used for fixed-date holidays such as christmas
      day. Accepts DateTime::Calendar::Julian. Defaults to 'gregorian'.

      * 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. 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
     Roman Filippov
     David Steinbrunner
     Debian Perl Group
     Tim Bunce
     Ricardo Signes
     Felix Ostmann
     Jörn Clausen
     Jim Avera
     Olaf Alders
     Karen Etheridge
     Graham Ollis
     isla w
     gibus

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/

