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 1326 22

2026-07-08 18:04:35 UTC

First 10 of 22 Posts!

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

kevinschweikert

If GitHub - wojtekmach/calendar_recurrence: Recurrence is an Elixir library for working with recurring dates · GitHub is helpful for ICal let me know and if you need any missing functionality!

Post #2

aseigo

ah, very nice!

I was kind of amazed how many recurrence libraries there are. It seems to be what a lot of people actually need/want?

I will definitely take a look through it, especially lib/calendar_recurrence/rrule.ex. The recurrence calculator in ical is currently what was in icalendar, but refactored for clarity / succinctness.

One of the goals is to expand recurrence support to cover the whole recurrence rule space. If you’d be interested in collaborating on that, I’d be very happy to do so!

Post #3

phcurado

Hi @aseigo, the github link is probably in a private repo. I cannot access it

Post #4

aseigo

Woops! You should be able to access it now.

Post #5

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

v1.1.1 is out. It is purely a bugfix release. No new functionality, only more .ics files that will successfully parse.

And a “thank-you” to @pedrogarrett for their contribution to this release!

Post #7

mpl

this is great news!
I’ve been using iCalendar for a couple years in a few hobby projects, and it’s mostly worked for my needs. more recently, I’ve needed to do some more robust things with it and needed to add some more to it and have been working from my own fork (Commits · matthewlehner/icalendar · GitHub)

I’d love to switch over to using ical – is there a chance you’d be open to removing Timex? I would be happy to send a PR of that work.

Post #8

aseigo

Absolutely! The fewer the dependencies the better. This is one we inherited from ICalendar, and it just hasn’t been an important enough thing to address.

But if you can work up a PR, I’ll absolutely get it reviewed and merged!

Post #9

mpl

amazing!

I just put up a PR to bump to 1.17 for the Date/DateTime.shift/2 functionality. If this is okay, I’ll start on the subsequent work to actually start removing it.

would you prefer a single large PR, or a few iterative?

Post #10

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