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

📦

version 0.13 · 6 versions

0.13 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
0.13 · epel 9
0.13 · arch rolling
0.13 · fedora 43
0.13 · ubuntu jammy
0.13 · fedora 44

, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

DateTime::Event::ICal — a Perl DateTime extension for computing rfc2445 recurrences. that's the whole vibe, she's a recurrence girlie 🦋

🌸 SYNOPSIS 🌸

use DateTime;
use DateTime::Event::ICal;

my $dt = DateTime->new( year   => 2000,
                        month  => 6,
                        day    => 20,
                      );

my $set = DateTime::Event::ICal->recur(
     dtstart => $dt,
     freq =>    'daily',
     bymonth => [ 10, 12 ],
     byhour =>  [ 10 ]
);

my $dt_next = $set->next( $dt );

my $dt_previous = $set->previous( $dt );

my $bool = $set->contains( $dt );

my @days = $set->as_list( start => $dt1, end => $dt2 );

my $iter = $set->iterator;

while ( my $dt = $iter->next ) {
    print ' ', $dt->datetime;
}

like… you build a DateTime, you ask for a recur, and the set it hands back will give you next, previous, contains, as_list, or an iterator to loop over. main character energy fr ✨

🎀 DESCRIPTION 🎀

okay so here's the tea, bestie: this module gives you convenience methods that let you easily build DateTime::Set objects for rfc2445 style recurrences. it's giving "I don't wanna hand-roll recurrence math" and honestly? iconic. 💅

🦋 USAGE 🦋

✨ `recur` ✨

this method returns a DateTime::Set object representing the recurrence you asked for. obsessed.

my $set = DateTime::Event::ICal->recur( %args );

it takes parameters that correspond to the rule parts spelled out in section 4.3.10 of RFC 2445. and no, I'm not gonna rewrite that RFC here (imagine 😭) — you're encouraged to read that first if you actually want to understand what all these parameters represent. iykyk.

dtstart — a DateTime object, and it's the start date. heads up though: this datetime is not included in the recurrence, unless it satisfies the recurrence's rules. so a set can be used for creating exclusion rules (rfc2445 calls it "exrule"), which don't include dtstart. 🫶
until — a DateTime object that specifies the recurrence's end date. you can also spell it dtend.
count — a positive number indicating the total number of recurrences. giving both a count and an until parameter is pointless, though it is currently allowed. so like, you can, but why bestie 😭
freq — one of:

"yearly", "monthly", "weekly", "daily",
"hourly", "minutely", "secondly"

see the DateTime::Event::Recurrence documentation for more details on what these mean.

interval — the interval between recurrences. it's a multiplier for the value specified by freq, and it defaults to 1. so if you set a freq of yearly and an interval of 3, that means a recurrence that happens every three years. math is mathing ✨
wkst — week start day. this can be one of: mo, tu, we, th, fr, sa, su. the default is Monday (mo).

note: this parameter is not yet implemented 🫠

bysecond => [ list ], byminute => [ list ], byhour => [ list ] — this should be one or more positive numbers, specified as a scalar or array reference. each number represents a second/minute/hour.