aseigo

ICal - An ICalendar library

ICal is a library for interacting with iCalendar data. It parses iCalendars into typed Elixir structs via ICal.from_ics, and can prepare those same structs for writing out to files, the network, etc. via ICal.to_ics It has convenient Phoenix support via ICal.encode_to_iodata/2.

Real World Calendaring

The power of a calendar format standards is interoperability. So one of the primary goals of this library is to support real-world calendaring use cases. This means preserving the semantic content of calendars produced by other software, and certainly being able to parse them correctly.

Another main goal is a good developer experience. Nearly everything is parsed into typed structs, and functionality for recurrence and alarm calculations are within the scope of this library as well. It should be easy to use calendaring data, both reading in data as well as producing well-formed content.

Current Status

Currently the following components are supported:

Events
Alarms

Commonly used, though non-standard, properties for things such as a default timezone are supported, as are timezones, multi-line entries, etc. that are seen in real-world iCalendar files.

Recurrence calculations are also supported, though currently only for BYDAY recurrences.

Custom properties and components which are not yet supported are retained during parsing and written out when serializing.

Additional components and features are planned as documented in the README.me and in the library’s issue tracker. There’s certainly more to do, and participation is welcome!

https://github.com/expothecary/ical

22 comments

#library #calendars

20 1327 22

2026-07-08 18:04:35 UTC

Most Liked

aseigo

Happy to share with you that v1.1.0 has been released!

This release brings a number of bug fixes as well as support for Todos, Journals, and Timezones. This only leaves free/busy components left in order to be fully RFC5545 compliant

Post #6

aseigo

Version 2.0 has been released!

This is a major release which drops support for Elixir versions older than 1.17, but also drops the dependency on Timex which will make it easier to use in a greater variety of applications.

Aside from a handful of bugfixes to the prior release (v1.1.2) and documentation improvements, the headline improvement is full recurrence support. This also unlocked the ability to properly determine when the next alarms should be triggered for the user.

Recurrence

The recurrence implementation implements the full RFC5545 recurrence rule specification. To my knowledge, this is the first such implementation done without external dependencies and in pure Elixir.

Its test suite includes every recurrence rule example in the RFC, and (of course) passes them.

Performance is acceptable: most recurrences are fully calculated in 50-200 microseconds on a Core i7-9700F @ 3Ghz (a seven year-old processor at this point), though some of the examples from the RFC take up 3ms on the same system.

Acknowledgements

A massive thank-you to all the contributors of code and PR review, including @W3NDO, @mpl,and Max Salminen, as well as those who reported issues.

We also welcomed @mpl as a new collaborator to the git repository, as they helped move things forward towards this significant release.

Post #16

aseigo

To address the elephant in the room: why another ics-parsing library?

The existing libraries are either unmaintained, do not work well with real-world data, have poor D/X, or some combination of those things.

Using the existing library options in production has always entailed compromises, and the most-used libraries have not been developed for years despite the PRs piling up. So myself and Max Salminen decided to do something about it.

We merged the outstanding PRs and then started refactoring the library for correctness, usability, and feature completeness.

There are still a number of components to add support for (todos, journals, timezone entries), but those are the less used components compared to events and alarms. We’ll get there, though My current plan is to add one component per minor release until the whole RFC is covered.

What we have now is a reasonable foundation to build off of that handles the worst details of dates, datetimes, durations, parmeters, recurrance rules, etc. that makes adding what is missing much easier.

I’m already using it to parse and work with my own personal calendars with hundreds of events, both from calendaring servers and as exported by clients such as Thunderbird. This already puts ICal ahead in terms of utility relative to the other options.

So while we really don’t need a bunch of ICalendar libraries, we do need at least one good one. And that is why ICal exists, to provide a good choice that is feature rich, easy and pleasant to use, welcoming of contributions, and maintained.

Post #1

Last Post!

aseigo

Version 3.0 has been release.

The major version bump is due to necessary changes in return types of some functions. This is due to the main feature of this release, namely:

ICal now properly supports “floating” datetimes, which are datetimes in the ICalendar data which explicitly do not have a timezone. They are equivalent to NaiveDateTimes.

This expands the compatibility of ICal with other ICalendar software and data files.

Thanks to Girish Gopaul for contributing to this release!

Post #22