ICal

A library for reading and writing iCalendar data.

Features

• Parsing iCalendar data from strings or files
• Serializing iCalendar data to iolists suitable for writing out to files, send over the network, etc.
• Integration with Plug / Phoenix via ICal.encode_to_iodata
• Components supported
  • Events (with alarms)
  • Todos (with alarms)
  • Journals
  • Timezones
  • Alarms
• Recurrence calculations (currrently only BYDAY is supported)
• Compatibility
  • RFC 5545 compliant
  • Support for common non-standard properties, including:
    • X-WR-TIMEZONE
    • X-WR-CALNAME/NAME
  • Timezones are resolved using the system timezone library, supporting variants seen in the wild
  • AllX-* fields and valid-by-not-yet-supported fields are retained

Future work

Components that will eventually be supported (in rough order):

• Free/busy (VFREEBUSY)

Planned features:

• Alarm calculation
• Expanded recurrency calculation

Usage

Full documentation can be found on Hexdocs.

The primary entry points are ICal.from_ics/1 and ICal.from_file/1 for parsing iCalendar data, and ICal.to_ics/1 for serializing an %ICal{} to an iodata ready for writing to a file, sending over the network, etc.

Individual calendar entries (e.g. %ICal.Event{}) can also be de/serialized via their respective modules.

calendar = ICal.from_file(ical_path)
%ICal{events: events} = calendar
ics_iodata = ICal.to_ics(calendar)

Recurrences may be calculated from a calendar component up to a given future date:

  reccurences =
    event
    |> ICalendar.Recurrence.get_recurrences(~U[2027-01-01 00:00:00Z])
    |> Enum.take(4)

Inline attachments can be decoded via ICal.Attachment.decoded_data/1.

Goals

• corrrect: support the iCalendar (and its related) RFCs for standards-compliance
• useful: handle real-world data (such as produced by other clients) gracefully, do not lose data while parsing (including fields not supported by / used in this library)
• good DevExp
  • parsed results should be easy to use, even if iCalednar is a complex format
  • typed structs and clear APIs
  • good doucmentation
• resource friendly: be performant in parsing and serializing
• reliable: be well-tested, beyond just code coverage

Installation

The package can be installed by adding :ical to your list of dependencies in mix.exs:

def deps do
  [
    {:ical, "~> 1.0"}
  ]
end

Participating in develpoment

Visit the issue tracker to see what tasks are outstanding. You are welcome to file new issues, as well!

PRs are welcome and responded to in a timely fashion.

Benchee is used for benchmarking, credo for linting, and the test suite must pass before PRs are merged. New functionality and bug fixes must have accompanying unit tests.