DateTi...t::Cron(3pm)

✨ DateTime::Event::Cron ✨

okay bestie, you just opened DateTi...t::Cron(3pm) — that's the User Contributed Perl Documentation, section 3pm, and it's literally the moment cron stops being a mystery. 💅

---

🌸 NAME 🌸

DateTime::Event::Cron — a DateTime extension for generating recurrence sets from crontab lines and files. no cap, that's the whole vibe. 🦋

---

🎀 SYNOPSIS 🎀

  use DateTime::Event::Cron;

  # check if a date matches (defaults to current time)
  my $c = DateTime::Event::Cron->new('* 2 * * *');
  if ($c->match) {
    # do stuff
  }
  if ($c->match($date)) {
    # do something else for datetime $date
  }

  # DateTime::Set construction from crontab line
  $crontab = '*/3 15 1-10 3,4,5 */2';
  $set = DateTime::Event::Cron->from_cron($crontab);
  $iter = $set->iterator(after => DateTime->now);
  while (1) {
    my $next = $iter->next;
    my $now  = DateTime->now;
    sleep(($next->subtract_datetime_absolute($now))->seconds);
    # do stuff...
  }

  # List of DateTime::Set objects from crontab file
  @sets = DateTime::Event::Cron->from_crontab(file => '/etc/crontab');
  $now = DateTime->now;
  print "Now: ", $now->datetime, "\n";
  foreach (@sets) {
    my $next = $_->next($now);
    print $next->datetime, "\n";
  }

  # DateTime::Set parameters
  $crontab = '* * * * *';

  $now = DateTime->now;
  %set_parms = ( after => $now );
  $set = DateTime::Event::Cron->from_cron(cron => $crontab, %set_parms);
  $dt = $set->next;
  print "Now: ", $now->datetime, " and next: ", $dt->datetime, "\n";

  # Spans for DateTime::Set
  $crontab = '* * * * *';
  $now = DateTime->now;
  $now2 = $now->clone;
  $span = DateTime::Span->from_datetimes(
            start => $now->add(minutes => 1),
            end   => $now2->add(hours => 1),
          );
  %parms = (cron => $crontab, span => $span);
  $set = DateTime::Event::Cron->from_cron(%parms);
  # ...do things with the DateTime::Set

  # Every RTFCT relative to 12am Jan 1st this year
  $crontab = '7-10 6,12-15 10-28/2 */3 3,4,5';
  $date = DateTime->now->truncate(to => 'year');
  $set = DateTime::Event::Cron->from_cron(cron => $crontab, after => $date);

  # Rather than generating DateTime::Set objects, next/prev
  # calculations can be made directly:

  # Every day at 10am, 2pm, and 6pm. Reference date
  # defaults to DateTime->now.
  $crontab = '10,14,18 * * * *';
  $dtc = DateTime::Event::Cron->new_from_cron(cron => $crontab);
  $next_datetime = $dtc->next;
  $last_datetime = $dtc->previous;
  ...

  # List of DateTime::Event::Cron objects from
  # crontab file
  @dtc = DateTime::Event::Cron->new_from_crontab(file => '/etc/crontab');

  # Full cron lines with user, such as from /etc/crontab
  # or files in /etc/cron.d, are supported and auto-detected:
  $crontab = '* * * * * gump /bin/date';
  $dtc = DateTime::Event::Cron->new(cron => $crontab);

  # Auto-detection of users is disabled if you explicitly
  # enable/disable via the user_mode parameter:
  $dtc = DateTime::Event::Cron->new(cron => $crontab, user_mode => 1);
  my $user = $dtc->user;
  my $command = $dtc->command;

  # Unparsed original cron entry
  my $original = $dtc->original;

like… look at that. iconic. 🔥

---

💖 DESCRIPTION 💖

DateTime::Event::Cron generated DateTime events or DateTime::Set objects based on crontab-style entries. that's the whole thesis bestie, everything else is just how you tell it which entries. 💜

---

👑 METHODS 👑

so the cron fields here are your typical crontab-style entries. for more info, go peek at crontab(5) and the extensions described over in Set::Crontab. the fields can be handed over as a single string, or as a reference to an array holding each field. only the first five fields are retained — that's the rule, no exceptions. 🌈

okay so quick heads up: new() keeps showing up in the synopsis and from_cron name-drops it, but this page doesn't give new() its own little entry. that's just how this page is. iykyk. 🙈

---

🎀 DateTime::Set Factories 🎀

peep DateTime::Set for all the methods that Set objects hand you, like next() and previous(). 💅

• from_cron($cronline)
• from_cron(cron => $cronline, %parms, %set_parms) — Generates a DateTime::Set recurrence for the cron line you gave it. check out new() for the deets on %parms. it'll also optionally take parameters for DateTime::Set. ✨
• from_crontab(file => $crontab_fh, %parms, %set_parms) — hands you back a list of DateTime::Set recurrences based on the lines of a crontab file. $crontab_fh can be either a filename or a filehandle reference, whichever you're feeling. check out new() for the deets on %parm. it'll optionally take parameters for DateTime::Set too, and those get passed along to every set, once per line. 🎀
• as_set(%set_parms) — Generates a DateTime::Set recurrence from an existing DateTime::Event::Cron object. glow-up but for objects. 💖

---

🦋 Constructors 🦋

• new_from_cron(cron => $cronstring, %parms) — Returns a DateTime::Event::Cron object built off the cron specification. optional params include the boolean 'user_mode', which is your little flag saying "hey, this crontab entry has a username column sitting before the command". 👑
• new_from_crontab(file => $fh, %parms) — Returns a list of DateTime::Event::Cron objects based on the lines of a crontab file. $fh can be either a filename or a filehandle reference. optional params include the boolean 'user_mode' like we just talked about above. 💜

---

🌸 Other methods 🌸

• next() / next($date) — Returns the next valid datetime according to the cron specification. $date defaults to DateTime->now unless you hand one over. ⭐
• previous() / previous($date) — Returns the previous valid datetime according to the cron specification. $date defaults to DateTime->now unless you hand one over. 🌙
• increment($date) / decrement($date) — Same as next() and previous(), except the datetime you provided gets modified to become the new datetime. yes, in place. she's not a clone, she's the real thing. 💅
• match($date) — Returns whether or not the given datetime (defaults to current time) matches the current cron specification. dates get truncated down to minute resolution. 🎀
• valid($date) — a more strict version of match(). Returns whether the given datetime is valid under the current cron specification. cron dates are only accurate to the minute — datetimes with seconds greater than 0 are invalid by default. (note: never fear, all methods accepting dates will accept invalid dates — they will simply be rounded to the next nearest valid date in all cases except this particular method) 🫶
• command() — Returns the command string, if any, from the original crontab entry. currently no expansion is performed, so no resolving environment variables or anything like that, etc. 🐚
• user() — Returns the username under which this cron command was to be executed — assuming such a field was actually present in the original cron entry. 👤
• original() — Returns the original, unparsed cron string, including any user or command fields. the raw source material, untouched. 😭

---

🌟 AUTHOR 🌟

Matthew P. Sisk <sisk@mojotoad.com> — king behavior. 👑

---

💜 COPYRIGHT 💜

Copyright (c) 2003 Matthew P. Sisk. All rights reserved. All wrongs revenged. This program is free software; you can distribute it and/or modify it under the same terms as Perl itself.

"all wrongs revenged" is genuinely the most main character energy line in any manpage and i'm obsessed. 🔥

---

🌈 SEE ALSO 🌈

DateTime(3), DateTime::Set(3), DateTime::Event::Recurrence(3), DateTime::Event::ICal(3), DateTime::Span(3), Set::Crontab(3), crontab(5)

---

and that's the page bestie!! 💖 this lil' slice of lore was perl v5.34.0, dated 2022-06-13, and it lives under the DateTi...t::Cron(3pm) footer. go schedule something iconic. periodt. ✨🦋🎀