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(
               lang          => 'en',
               format        => 'mm/dd/yy',
               prefer_future => '[0|1]'
               time_zone     => 'floating',
               daytime       => { morning   => 06,
                                  afternoon => 13,
                                  evening   => 20,
                                },
     );

    * `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

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