NAME

"Algorithm::Cron" - abstract implementation of the cron(8) scheduling algorithm

SYNOPSIS

 use Algorithm::Cron;

 my $cron = Algorithm::Cron->new(
    base => 'local',
    crontab => "*/10 9-17 * * *",
 );

 my $time = time;
 while(1) {
    $time = $cron->next_time( $time );

    sleep( time - $time );

    print "Do something\n";
 }

DESCRIPTION

Objects in this class implement a time scheduling algorithm such as used by cron(8). Objects are stateless once constructed, and represent a single schedule as defined by a crontab(5) entry. The object implements a method "next_time" which returns an epoch timestamp value to indicate the next time included in the crontab schedule.

Crontabs

The schedule is provided as a set of acceptable values for each field of the broken-down time (as returned by "localtime" or "gmtime"), either in a single string called "crontab" or by a set of named strings, each taking the name of a crontab(5) field.

 my $cron = Algorithm::Cron->new(
    base => 'local',
    crontab => '0 9 * * mon-fri',
 );

 my $cron = Algorithm::Cron->new(
    base => 'local',
    min  => 0,
    hour => 9,
    wday => "mon-fri",
 );

A "crontab" field containing a single asterisk ("*"), or a missing named field, indicates that any value here is included in the scheduled times. To restrict the schedule, a value or set of values can be provided. This should consist of one or more comma-separated numbers or ranges, where a range is given as the start and end points, both inclusive.

 hour => "3-6"
 hour => "3,4,5,6"

Ranges can also be prefixed by a value to give the increment for values in that range.

 min => "*/10"
 min => "0,10,20,30,40,50"

The "mon" and "wday" fields also allow symbolic month or weekday names in place of numeric values. These names are always in the C locale, regardless of the system's locale settings.

 mon => "mar-sep"

 wday => "mon,wed,fri"

Specifying "sun" as the end of a "wday" range, or giving the numeric value of 7 is also supported.

 wday => "fri-sun"
 wday => "5-7"
 # Both equivalent to: wday => "0,5,6"

As per cron(8) behaviour, this algorithm looks for a match of the "min", "hour" and "mon" fields, and at least one of the "mday" or "mday" fields. If both "mday" and "wday" are specified, a match of either will be sufficient.

As an extension, seconds may be provided either by passing six space-separated fields in the "crontab" string, or as an additional "sec" field. If not provided it will default to 0. If six fields are provided, the first gives the seconds.

Time Base

"Algorithm::Cron" supports using either UTC or the local timezone when comparing against the given schedule.

CONSTRUCTOR

$cron = Algorithm::Cron->new( %args )

Constructs a new "Algorithm::Cron" object representing the given schedule relative to the given time base. Takes the following named arguments:

base => STRING: Gives the time base used for scheduling. Either "utc" or "local".
crontab => STRING: Gives the crontab schedule in 5 or 6 space-separated fields.
sec => STRING, min => STRING, ... mon => STRING: Optional. Gives the schedule in a set of individual fields, if the "crontab" field is not specified.

METHODS

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

NAME

SYNOPSIS

DESCRIPTION

Crontabs

Time Base

CONSTRUCTOR

$cron = Algorithm::Cron->new( %args )

METHODS

@seconds = $cron->sec

@minutes = $cron->min

@hours = $cron->hour

@mdays = $cron->mday

@months = $cron->mon

@wdays = $cron->wday

$time = $cron->next_time( $start_time )

AUTHOR