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
  @seconds = $cron->sec
  @minutes = $cron->min
  @hours = $cron->hour
  @mdays = $cron->mday
  @months = $cron->mon
  @wdays = $cron->wday
    Accessors that return a list of the accepted values for each scheduling
    field. These are returned in a plain list of numbers, regardless of the
    form they were specified to the constructor.

    Also note that the list of valid months will be 0-based (in the range 0
    to 11) rather than 1-based, to match the values used by `localtime',
    `gmtime', `mktime' and `timegm'.

  $time = $cron->next_time( $start_time )
    Returns the next scheduled time, as an epoch timestamp, after the given
    timestamp. This is a stateless operation; it does not change any state
    stored by the `$cron' object.

AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>