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 ambigious weekdays/months to their futuristic relatives.
        Accepts a boolean, defaults to 0.

    * "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 consisting of specific hours given for peculiar daytimes.
        Daytimes 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 didn't succeed.

  trace
    Returns a trace of methods which we're called within the Base class and
    a summary how often certain units were 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

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>

