Event will start next at 0:45:00 on 28 Aug, 2002
Following event will start at 0:50:00 on 28 Aug, 2002
Last event started at 0:40:00 on 28 Aug, 2002
Event did start at 1:20:00 on 26 Oct, 1985
...or that can be expressed as 499134000 seconds which is Sat Oct 26 01:20:00 1985

Note that results will vary according to your local time and timezone.

Given a line from a crontab, tells you the time at which cron will next run the line, or when the last event occurred, relative to any date you choose. The object keeps that reference date internally, and updates it when you call nextEvent() or previousEvent() - such that successive calls will give you a sequence of events going forward, or backwards, in time.

Use setCounterToNow() to reset this reference time to the current date on your system, or use setCounterToDate() to set the reference to any arbitrary time, or resetCounter() to take the object back to the date you constructed it with.

This module uses Set::Crontab to understand the date specification, so we should be able to handle all forms of cron entries.

In the following, DATE_LIST is a list of 6 values suitable for passing to Time::Local::timelocal() which are the same as the first 6 values returned by the builtin localtime(), namely these 6 numbers in this order

Returns a new object for the specified line from the crontab. The first 5 fields of the line are actually parsed by Set::Crontab, which should be able to handle the original crontab(5) ranges aswell as Vixie cron ranges and the like. It's up to you to supply a valid line - if you supply a comment line, an environment variable setting line, or a line which does not seem to begin with 5 fields (e.g. a blank line), this method returns undef.

Give either the Seconds option or the Date option, not both. Supply a six-element array (as described above) to specify the date at which you want to start. Alternatively, the reference time is the number of seconds since the epoch for the time you want to start looking from.

If neither of the 'Seconds' and 'Date' options are given we use the current time().

If something goes wrong the general approach is to raise a fatal error with confess() so use eval {} to trap these errors. If you supply a comment line to the constructor then you'll simply get back undef, not a fatal error. If you supply a line like 'foo bar */15 baz qux /bin/false' you'll get a confess().