DateTime::Format::Natural - Create machine readable date/time with natural parsing logic


 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,
 } else {
     warn $parser->error;


DateTime::Format::Natural takes a string with a human readable date/time and creates a machine readable one by applying natural parsing logic.



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

    A hash reference consisting of customized daytime hours, which may be selectively changed.



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.


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


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 a trace of methods which were called within the Base class and a summary how often certain units have been modified.


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.


See the classes DateTime::Format::Natural::Lang::[language_code] for a overview of current valid input.


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


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.


1 POD Error

The following errors were encountered while parsing the POD:

Around line 721:

Non-ASCII character seen before =encoding in 'König'. Assuming ISO8859-1