NAME

DateTime::Format::GnuAt - Parse time specifications as Debian 'at' command.

SYNOPSIS

  use DateTime::Format::GnuAt;

  $parser = DateTime::Format::GnuAt->new;
  $dt = $parser->parse_datetime("today");
  $dt = $parser->parse_datetime("next week + 3 days");

DESCRIPTION

This module implements the same parser rules as Debian 'at' command (which is also the 'at' used by most non Debian based Linux distributions).

From the at manual page:

at allows fairly complex time specifications, extending the POSIX.2 standard. It accepts times of the form HH:MM to run a job at a specific time of day. (If that time is already past, the next day is assumed.) You may also specify minight, noon, or teatime (4pm) and you can have a time-of-day suffixed with AM or PM for running in the morning or the evening. You can also say what day the job will be run, by giving a date in the form month-name day with an optional year, or giving a date of the form MMDD[CC]YY, MM/DD/[CC]YY, DD.MM.[CC]YY or [CC]YY-MM-DD. The specification of a date must follow the specification of the time of day. You can also give times like now + count time-units, where the time-units can be minutes, hours, days, or weeks and you can tell at to run the job today by suffixing the time with today and to run the job tomorrow by suffixing the time with tomorrow.

For example, to run a job at 4pm three days from now, you would do at 4pm + 3 days, to run a job at 10:00am on July 31, you would do at 10am Jul 31 and to run a job at 1am tomorrow, you would do at 1am tomorrow.

The definition of the time specification can be found in /usr/share/doc/at/timespec.

API

The module provides the following methods:

my $p = DateTime::Format::GnuAt->new;

Returns a new date-time parser object.

my $datetime = $p->parse_datetime($string)

my $datetime = $p->parse_datetime($string, %opts)

Parses the given string and returns a DateTime object. On failure it croaks.

The following options can also be passed to the method as a list of $key = $value> pairs after the date-time specification:

now => $datetime

A DateTime object to be used as the current "now".

This allows to parse the date-time specifications relative to a custom date.

It can also be used to set the default time-zone (by default local is used).

SEE ALSO

DateTime.

AUTHOR

Salvador Fandiño, <sfandino@yahoo.com>

COPYRIGHT AND LICENSE

Copyright (C) 2013 by Qindel Formación y Servicios, S.L.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.

The Perl code in this module has been written from scratch, though the source code of the Debian at command was used for inspiration and to determine undocumented behavior.

And excerpt from the at(1) man page has also been copied here.

The test suite is an adaptation of the parsetime.pl script also distributed in the at package.

The reference directory contains the original C files and their copyright conditions.