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

       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'.

   *   "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. 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

SEE ALSO
   dateparse, DateTime, Date::Calc, <http://datetime.perl.org>

AUTHOR
   Steven Schubiger <[email protected]>

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.