README.md — sigil-caldav

1# sigil-caldav

A [Sigil](https://codeberg.org/sigil/sigil) library for CalDAV calendaring (RFC 4791) and iCalendar parsing (RFC 5545). Works with Fastmail, Nextcloud, Radicale, and other CalDAV servers.

5## Features

7- **Server discovery** -- principal URL and calendar home set via WebDAV

8- **Calendar operations** -- list, find by name, create, delete

9- **Event CRUD** -- create, read, update, delete calendar events

10- **Date range queries** -- fetch events within a time window

11- **Recurrence expansion** -- DAILY, WEEKLY, MONTHLY RRULE support with exception handling

12- **iCalendar parsing** -- full VEVENT support including folded lines, attendees, timezones

13- **iCalendar generation** -- create valid iCalendar text from event structs

14- **Timezone handling** -- UTC and local timezone with DST-aware offset calculation

15- **Authentication** -- HTTP Basic or Bearer token

17## Usage

19Add `sigil-caldav` as a dependency in your `package.sgl`:

21```scheme

22(from-git url: "codeberg:sigil/sigil-caldav" package: "sigil-caldav")

23```

25Then connect and manage calendars:

27```scheme

28(import (sigil caldav))

30(define client (caldav-connect

31 url: "https://caldav.fastmail.com"

32 username: "[email protected]"

33 password: (getenv "CALDAV_PASSWORD")))

35;; List calendars

36(define calendars (caldav-calendars client))

38;; Get events in a date range

39(define events (caldav-events client (car calendars)

40 start: "20260301T000000Z"

41 end: "20260401T000000Z"))

43;; Create an event

44(caldav-event-create! client (car calendars)

45 (ical-event summary: "Meeting"

46 dtstart: "20260315T100000Z"

47 dtend: "20260315T110000Z"))

48```

50## Modules

52| Module | Description |

53|--------|-------------|

54| `(sigil caldav)` | Top-level re-exports |

55| `(sigil caldav client)` | WebDAV discovery, PROPFIND, REPORT, PUT, DELETE |

56| `(sigil caldav ical)` | iCalendar parsing, generation, datetime handling |

57| `(sigil caldav calendar)` | Calendar listing, creation, deletion |

58| `(sigil caldav event)` | Event CRUD with date range queries |

60## Dependencies

62- sigil-stdlib

63- sigil-http

64- sigil-sxml

65- sigil-crypto

67## Building

69```bash

70sigil deps install

71sigil build

72sigil test

73```

75## License

77BSD-3-Clause