ICal - An ICalendar library

News Announcing
,
1

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

20 Likes
2

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 :slight_smile: 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.

8 Likes
3

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

1 Like
4

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!

5

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

6

Woops! You should be able to access it now.

1 Like
7

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 :slight_smile:

11 Likes
8

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!

2 Likes
9

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 (https://github.com/matthewlehner/icalendar/commits/main/)

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.

2 Likes
10

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!

11

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?

12

Smaller PRs are always easier to review and can help prevent spending too much time/effort working down a “wrong” direction. I’m a big fan of stacked PRs for this reason :slight_smile:

I’m also happy to review bigger PRs if needed, though. Whichever is more comfortable for you.

2 Likes
13

@mpl I would be happy to collaborate with you on this if I can be of any assistance.

14

Please feel free to contribute PRs removing specific Timex calls. This really does not (should not!) be done all at once. One task, for instance, might be to remove use of Timex.to_date Timex.to_datetime in tests. This would leave other uses of Timex in tests, but it would get rid of one class of them. Doing this one-bite at a time is both faster per-PR and a bit safer as we can more easily test each set of changes in isolation.

1 Like
15

Will get to it this weekend!!

1 Like
16

I created this issue to help track that work: Remove Timex dependency · Issue #32 · expothecary/ical · GitHub

The way this is restructured is really nice to work with! (especially after doing stuff with the original lib).

17

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.

8 Likes
18

This sounds amazing. Can’t wait to try it. Thanks for the hard work.

I know this comment is a bit pointless, but I’ve been struggling with bad ical-parsing (esp. recurrence) in an existing non-elixir application, and not been sure about which direction to move in. I saw your thread here some time ago, and just randomly tried finding it again today to see if there had been progress on recurrence. What luck.

Thanks.

1 Like
19

Many thanks for this library, it will come in handy!

1 Like
20

Sometimes it really is all about timing :wink:

(excuse the horrible pun)

If you do find any issues whatsoever with the recurrence, please drop an issue on the repo and I’ll get it taken care of. Happy hacking!

1 Like