DateTime::Format::Natural - Parse informal natural language date/time strings


DateTime::Format::Natural - Parse informal natural language date/time strings


 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


DateTime::Format::Natural parses informal natural language date/time strings. In addition, parsable date/time substrings may be extracted from ordinary strings.



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.



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.


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);


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);


Returns a boolean indicating success or failure for parsing the date/time string given.


Returns the error message if the parsing did not succeed.


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.


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.


See the class DateTime::Format::Natural::Lang::EN for an overview of currently valid input.


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.


Thanks to Tatsuhiko Miyagawa for the initial inspiration. See Miyagawa's journal entry for more information.

Furthermore, thanks to (in order of appearance) who have contributed valuable suggestions and patches:

 Clayton L. Scott
 Dave Rolsky
 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


dateparse, DateTime, Date::Calc,


Steven Schubiger <>


This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.