Algorithm::Cron(3pm)

💖 Algorithm::Cron 💖

okay so bestie, welcome to Algorithm::Cron — the abstract implementation of the cron(8) scheduling algorithm ✨. that's the whole vibe. no cap.

---

✨ 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 🌸

okay so here's the tea ☕. objects in this class implement a time scheduling algorithm, the same kind of thing cron(8) uses. objects are stateless once you've constructed them — they just sit there, iconic, unbothered, moisturised, in their lane 💅. each one represents a single schedule as defined by a crontab(5) entry.

the object implements a method called next_time which returns an epoch timestamp value telling you the next time that's included in the crontab schedule. periodt.

🎀 Crontabs 🎀

so the schedule gets handed to you as a set of acceptable values for each field of the broken-down time (the thing localtime or gmtime gives back). you can give it either as one single string called crontab, or as a set of named strings where each name is the name of a crontab(5) field. either way slays.

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 that's just a single asterisk (*), or a named field that's missing entirely, means any value here counts as a scheduled time. very "come as you are" of it 🦋.

but if you wanna restrict the schedule? give it a value or a set of values. that should be one or more comma-separated numbers or ranges, where a range is the start and end points, both inclusive (iykyk).

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

ranges can also be prefixed by a value to give the increment for the values inside that range ✨

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

the mon and wday fields also let you use symbolic month or weekday names instead of numeric values 🗓️. heads up though: these names are always in the C locale, no matter what the system's locale settings say. so don't come at it with your fancy translated month names, she will not know her.

mon => "mar-sep"

wday => "mon,wed,fri"

specifying sun as the end of a wday range is supported too, and so is just giving the numeric value 7 🌞

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. (yes bestie, it literally says mday twice in the source. we simply do not question the ancestors 🙈.) if both mday and wday are specified, then matching either one is enough to count.

and as an extension 🌈 seconds may be provided, either by passing six space-separated fields in the crontab string, or as an extra sec field. if you don't provide it, it defaults to 0. if you do give six fields, the first one gives the seconds.

🦋 Time Base 🦋

Algorithm::Cron supports using either UTC or the local timezone when comparing against the given schedule. pick your fighter 💅.

---

👑 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. that's it, that's the choice.
• crontab => STRING — gives the crontab schedule in 5 or 6 space-separated fields 🗓️
• sec => STRING, min => STRING, ... mon => STRING — optional. gives the schedule as a set of individual fields, for when you didn't specify the crontab field 🎀

---

💅 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 come back as a plain list of numbers, no matter what form you originally gave them to the constructor. so like, your cute "mon-fri"? numbers now. slay.

also note (important, bestie, write this down 📝): the list of valid months will be 0-based (in the range 0 to 11) rather than 1-based, so that it matches the values used by localtime, gmtime, mktime and timegm. yes your brain wants January to be 1. no. it's 0. we cope 💀.

⭐ $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. she does her little calculation and goes right back to being unbothered. no baggage, only vibes 🫶.

---

🌈 AUTHOR 🌈

Paul Evans <leonerd@leonerd.org.uk> — thank you king, we are obsessed 👑

---

okay bestie that's the whole page, you ate that fr fr 🍓

perl v5.42.0 🌸 2025-07-25 — that's the source/version and the date right there, and this was Algorithm::Cron(3pm) 💖 mwah, go schedule something iconic 🎀✨