NAME
Text::JSCalendar - convert between iCalendar and JSCalendar
VERSION
Version 0.11
SYNOPSIS
This module implements a perl mapping between iCalendar:
https://tools.ietf.org/html/rfc5545
and JSCalendar:
https://datatracker.ietf.org/doc/draft-ietf-calext-jscalendar/
SUBROUTINES/METHODS
Synthetic masters
An iCalendar object may hold only some instances of a recurring event (RECURRENCE-ID components without their master, as a CalDAV server gives an attendee invited to one occurrence: jscalendar-icalendar-29 calls them stand-alone recurrence instances). vcalendarToEvents returns a single object per UID, so it makes up a master for them: its start, timeZone, updated and the properties an override may not change come from the first instance, and every instance is one of its recurrenceOverrides (even one that patches nothing).
Such a master is marked with the vendor-specific property
"jscalendar.fastmail.com:syntheticMaster": true
(jscalendarbis-22 1.8.1, so it cannot collide with a JSCalendar property, and JSCalendar implementations must preserve it). The name is the constant Text::JSCalendar::SYNTHETIC_MASTER. It is in the object rather than beside it so that it survives being stored and read back before the object is written again.
eventsToVCalendar writes only the instances of a marked master, each as a RECURRENCE-ID component (an excluded one is not written), and never a component for the master itself. Every other object is written whole. To turn a synthetic master into a real one, delete the property. occurrences of a synthetic master are its override keys, and instance gives the instance with the property removed.
Text::JSCalendar->isSyntheticMaster($Event)
True if $Event is a master made up by the reader (see above). May also be called on an object or as a function.
$self->errors()
What the last call to vcalendarToEvents or eventsToVCalendar (or _argsToVCalendar) had to drop. Neither dies because one component is bad: an iCalendar VEVENT or VTODO, VALARM or RRULE that cannot be converted is left out of the result, and so is a JSCalendar object or alert that cannot be written. The rest of the calendar converts as usual.
Returns a list of hashes, empty when nothing was dropped:
{
uid => 'abc@example.com', # the object's UID (undef if it had none)
component => 'RRULE', # what was dropped: VEVENT, VTODO,
# VALARM, RRULE (reading), or
# Event, Task, Alert (writing)
id => 'alarm-1', # the alarm or alert id, if known
message => 'Invalid recurrence FREQ (fortnightly)',
}
The list is reset at the start of each of those calls, and so is warnings.
$self->warnings()
What the last call to vcalendarToEvents or eventsToVCalendar (or _argsToVCalendar) found odd but converted anyway: an iCalendar component with both DTEND and DURATION, a second component of one UID without RECURRENCE-ID, a property Data::ICal says is missing. The same shape as errors, and reset with it. The module never writes these to STDERR.
$self->tz($name)
Returns a DateTime::TimeZone object for the given name, but caches the result for speed.
$NewEvent = Text::JSCalendar->NormaliseEvent($Event);
Returns a copy of the event (the original is not changed) in a canonical form for comparison: every property whose value is its default (jscalendarbis-22, or RFC 8984 for the properties -22 reserved) is removed, and so is an @type that only repeats the type its position already implies. Empty maps and arrays are removed. Everything else is kept as it is: a property this module does not know, the contents of a recurrenceOverrides patch, and the @type of the Event or Task and of any trigger that is not an OffsetTrigger.
Inside a recurrence override, a patch whose path names a known object (participants/p1, alerts/a1/trigger, locations) has that object normalised the same way. A patched value is never removed for being the default: in a patch it overrides the master, so "status": "confirmed" says something that {} does not.
Text::JSCalendar->CompareEvents($Event1, $Event2);
Returns true if the events are the same once normalised (see NormaliseEvent).
$self->eventsToVCalendar(@Events)
Convert a set of events (one or multiple) into an ical file)
Returns a string
e.g.
print $jscal->eventsToVCalendar(@Events);
$self->vcalendarToEvents($Data)
Convert a text vcalendar (either a single event or an entire ical file) into an array of events.
Returns an array (not arrayref) of Events in UID order.
e.g.
foreach my $Event ($CalDAV->vcalendarToEvents($Data)) {
# ...
}
$self->instance($Event, $recurrenceId)
The occurrence of $Event with the given recurrence id (a LocalDateTime as used for recurrenceOverrides keys, YYYY-MM-DDTHH:MM:SS), as an object of its own: a copy of the master with the override patch for that id, if any, applied (PatchObject paths such as participants/p1/participationStatus included, as the writer applies them), recurrenceId set, recurrenceIdTimeZone set to the master's timeZone if it has one, start the patch's if it moves the occurrence and the recurrence id otherwise, and recurrenceRule and recurrenceOverrides removed. A patch cannot change the properties an occurrence must share with its master (uid, @type, recurrenceRule, ...; the same ones the writer ignores).
Returns undef if the occurrence is excluded, or if $Event is a synthetic master (see above) and the id is not one of its instances. It does not check that the id is an occurrence of the rule: that is what occurrences is for. $Event is not changed. May be called as a class method.
$self->occurrences($Event, after => $from, before => $to, max => $n)
The recurrence ids of $Event (LocalDateTimes, YYYY-MM-DDTHH:MM:SS, the form of recurrenceOverrides keys) that are at or after after and before before, in order. Both bounds are LocalDateTimes in the event's own time zone (a trailing Z is ignored, a bare date means its midnight) and either may be left out. These are:
the event's
start, which is always the first occurrence (jscalendarbis-22 3.3.3.1), and for arecurrenceRuleevery date-time the rule produces from it, with every rule property this module reads:frequency,interval,firstDayOfWeek,byDay(withnthOfPeriod),byMonthDay,byMonth,byYearDay,byWeekNo,byHour,byMinute,bySecond,bySetPosition,count,until, andskip(rscalemust begregorian, the default; another one dies),plus every
recurrenceOverrideskey that is not excluded and that the rule does not produce (an added occurrence, iCalendar's RDATE),minus every key whose patch sets
excluded.
For a synthetic master (see above) they are its instances: its override keys, minus the excluded ones.
max (default 5000) bounds the number returned, so an unbounded rule without before still ends; a rule that stops matching (byMonthDay 30 in byMonth 2) ends once 400 years pass without an occurrence. Returns an empty list for an event without start. May be called as a class method.
AUTHOR
Bron Gondwana, <brong at cpan.org>
LICENSE AND COPYRIGHT
Copyright 2019-2026 Fastmail Pty Ltd.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself; that is, either the GNU General Public License as published by the Free Software Foundation (version 1, or at your option any later version), or the Artistic License.
See http://dev.perl.org/licenses/ and the LICENSE file included with this distribution for more information.