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.

  The format is used to influence how numeric dates are parsed. Given two numbers separated by a slash, the month/day order expected comes from this option. If there is a third number, this option describes where to expect the year. When this format can't be used to interpret the date, some unambiguous dates may be parsed, but there is no form guarantee.

  Current supported "month/day" formats: "dd/mm", "mm/dd".

  Current supported "year/month/day" formats (with slashes): "dd/mm/yy", "dd/mm/yyyy", "mm/dd/yyyy", "yyyy/mm/dd".

  Note that all of the above formats with three units do also parse with dots or dashes as format separators.

  Furthermore, formats can be abbreviated as long as they remain unambiguous.

  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"

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

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.