DateTime::Format::Natural.3pm

Langue: en

Version: 2010-10-07 (fedora - 01/12/10)

Section: 3 (Bibliothèques de fonctions)

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;
  }
 
  @traces = $parser->trace;
 
 

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 future 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 one or more strings with traces of methods which were called within the Base class and a summary how often certain units have been modified. More than one string is commonly returned for durations.

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.

BUGS & CAVEATS

"parse_datetime()"/"parse_datetime_duration()" always return one or more 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. Ko.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
 
 

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