Crate icalendar 

iCalendar in Rust

A builder and parser for rfc5545 iCalendar.

You want to help make this more mature? Please talk to me, Pull Requests and suggestions are very welcome.

Usage & Documentation

Please see the documentation for current examples.

Below are a few examples of how to use this library. See the examples directory as well as the documentation for many more.

Building a new Calendar

Use the builder-pattern to assemble the full calendar or event by event. Display printing produces the rfc5545 format.

use icalendar::{Calendar, CalendarDateTime, Class, Component, Event, EventLike, Property, Todo};
use chrono::{Duration, NaiveDate, NaiveTime, Utc};

// let's create a calendar
let my_calendar = Calendar::new()
    .name("example calendar")
    .push(
        // add an event
        Event::new()
            .summary("test event")
            .description("here I have something really important to do")
            .starts(Utc::now())
            .class(Class::Confidential)
            .ends(Utc::now() + Duration::days(1))
            .append_property(
                Property::new("TEST", "FOOBAR")
                    .add_parameter("IMPORTANCE", "very")
                    .add_parameter("DUE", "tomorrow")
            )
    )
    .push(
        // add a todo
        Todo::new()
            .summary("groceries")
            .description("Buy some milk")
    )
    .push(
        // add an all-day event
        Event::new()
            .all_day(NaiveDate::from_ymd_opt(2016, 3, 15).unwrap())
            .summary("My Birthday")
            .description("Hey, I'm gonna have a party\nBYOB: Bring your own beer.\nHendrik")
    )
    .push(
        // event with utc timezone
        Event::new()
            .starts(CalendarDateTime::from(
                NaiveDate::from_ymd_opt(2024, 10, 24).unwrap()
                    .and_time(NaiveTime::from_hms_opt(20, 10, 00).unwrap())
                    .and_utc()
            ))
            .summary("Birthday Party")
            .description("I'm gonna have a party\nBYOB: Bring your own beer.\nHendrik")
    )
    .done();

println!("{}", my_calendar);

Removing Properties from Components

You can remove properties from components when you need to update their state:

use icalendar::{Calendar, Component, Event, EventStatus, Todo, TodoStatus};
use chrono::Utc;

// Create a completed todo
let mut todo = Todo::new();
todo
    .summary("Buy milk")
    .completed(Utc::now())
    .percent_complete(100)
    .status(TodoStatus::Completed);

// Later, mark it as uncompleted by removing completion properties
todo.mark_uncompleted();
// This removes COMPLETED, PERCENT-COMPLETE, and STATUS properties

// For events, you can remove specific properties
let mut event = Event::new();
event
    .summary("Team Meeting")
    .status(EventStatus::Cancelled);

// Remove the cancelled status
event.remove_status();

// You can also remove any property directly
event.remove_property("LOCATION");

Parsing a Calendar

There is a feature called "parser" which allows you to read calendars again like this:

use std::fs::read_to_string;

use icalendar::{Calendar, CalendarComponent, Component};

let contents = read_to_string("fixtures/icalendar-rb/event.ics").unwrap();

let parsed_calendar: Calendar = contents.parse().unwrap();

for event in parsed_calendar.events() {
    println!("Event: {}", event.get_summary().unwrap())
}

Structure

A Calendar represents a full calendar, which contains multiple Components. These may be either Events, Todos, or Venues. Components in turn have Propertys, which may have Parameters.

RRule Support

Thanks to the rrule crate and friendly community contribution, you can also add recurrence rules to your events and todos. See the documentation for Event::recurrence and Todo::recurrence for details. We currently reexport a select subset of rrule types. Should you experience compatibility issues because the maintainer (me) has not yet updated icalendar to reexport the latest rrule version, please feel free to open a PR.

Contributing

Any help in form of descriptive and friendly issues or comprehensive pull requests are welcome!

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in icalendar by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Conventions

The Changelog of this library is generated from its commit log, there any commit message must conform with https://www.conventionalcommits.org/en/v1.0.0/. For simplicity you could make your commits with convco.

Recognition

Thanks goes to these wonderful people:

License

^{`icalendar` (this crate) is licensed under either of Apache License, Version 2.0 or MIT license at your option.}
_{Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.}

Re-exports

pub use rrule;

Modules

parser

Parsing iCalendar document parser

Structs

Alarm

VALARM (RFC 5545, Section 3.6.6 )

Attendee

RFC 5545, Section 3.8.4.1 Attendee (ATTENDEE)

Calendar

Represents a calendar

Event

VEVENT (RFC 5545, Section 3.6.1 )

Parameter

key-value pairs inside of Propertys

Property

key-value pairs inside of Components

RRule

Represents a complete RRULE property based on the iCalendar specification It has two stages, based on the attached type, Validated or Unvalidated.

RRuleSet

A validated Recurrence Rule that can be used to create an iterator.

Todo

VTODO (RFC 5545, Section 3.6.2 )

Venue

VVENUE (ical-venue)

Enums

CUType

RFC 5545, Section 3.2.3 Calendar User Type (CUTYPE)

CalendarComponent

Wrapper for Todo, Event or Venue

CalendarDateTime

Representation of various forms of DATE-TIME per RFC 5545, Section 3.3.5

Class

This property defines the access classification for a calendar component. RFC 5545, Section 3.8.1.3

DatePerhapsTime

Either a DATE-TIME or a DATE.

EventStatus

Encodes the status of an Event RFC 5545, Section 3.8.1.11

Frequency

The frequency of a recurrence.

NWeekday

This indicates the nth occurrence of a specific day within a MONTHLY or YEARLY RRULE.

PartStat

RFC 5545, Section 3.2.12 Participation Status (PARTSTAT)

RecurrenceError

Errors that can occur when setting or parsing recurrence rules.

Related

Alarm Trigger Relationship RFC 5545, Section 3.2.14

Role

RFC 5545, Section 3.2.16 Participation Role (ROLE)

TodoStatus

Encodes the status of a Todo RFC 5545, Section 3.8.1.11

Trigger

Describes when an alarm is supposed to occure.

Tz

A wrapper around chrono_tz::Tz that is able to represent Local timezone also.

ValueType

see 8.3.4. Value Data Types Registry

Weekday

The day of week.

Traits

Component

Implemented by everything that goes into a Calendar

EventLike

Common trait of Event and Todo

Functions

ymd_hm_tzid

will return None if date is not valid

Type Aliases

UnvalidatedRRule

A not-yet-validated recurrence rule. Alias for RRule<Unvalidated>.