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'
        An anonymous hash reference consisting of customized daytime hours,
        which may be selectively changed.

METHODS
  parse_datetime

    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.

  parse_datetime_duration

    Returns one or more DateTime object(s) 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.

     @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 currently 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 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

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://dev.perl.org/licenses/