Notes for developers

If you want to hack on khal, the notes below might be of some interest to you.

iCalendar peculiarities

A single .ics can contain several VEVENTS, which might or might not be the part of the same event. This can lead to issues with straight forward implementations. Some of these, and the way khal is dealing with them, are described below.

While one would expect every VEVENT to have its own unique UID (for what it’s worth they are named unique identifier), there is a case where several VEVENTS have the same UID, but do describe the same (recurring) event. In this case, one VEVENT, containing an RRULE or RDATE element would be the proto event, from which all recurrence instances are derived. All other VEVENTS with the same UID would then have a RECURRENCE-ID element (I’ll call them child event from now on) and describe deviations of at least one recurrence instance (RECURRENCE-ID elements can also have the added property RANGE=THISANDFUTURE, meaning the deviations described by this child event also apply to all further recurrence instances.

Because it is possible that an event already in the database consists of a master event and at least one child event gets updated and than consists only of a master event, we currently delete all events with the same UID from the database when inserting or updating a new event. But this means that we need to update an event always at once (master and all child events) at the same time (using Calendar.update() or in this case)

As this wouldn’t be bad enough, the standard looses no words on the ordering on those VEVENTS in any given .ics file (at least I didn’t find any). Not only can the proto event be behind any or all RECURRENCE-ID events, but also events with different UIDs can be in between.

We therefore currently first collect all events with the same UID and than sort those by their type (proto or child), and the children by the value of the RECURRENCE-ID property.