Command-line and Emacs Calendar Client
ryan.freumh.org
1(** Core event functionality and data access *)
2
3type event_id = string
4(** Event ID type *)
5
6type t
7(** Event type representing a calendar event *)
8
9type date_error = [ `Msg of string ]
10
11(** {2 Events} *)
12
13val create :
14 fs:Eio.Fs.dir_ty Eio.Path.t ->
15 calendar_dir_path:string ->
16 summary:string ->
17 start:Icalendar.params * Icalendar.date_or_datetime ->
18 ?end_:
19 [ `Duration of Icalendar.params * Ptime.Span.t
20 | `Dtend of Icalendar.params * Icalendar.date_or_datetime ] ->
21 ?location:string ->
22 ?description:string ->
23 ?recurrence:Icalendar.recurrence ->
24 string ->
25 (t, [> `Msg of string ]) result
26(** Create a new event with required properties.
27
28 The start and end times can be specified as Icalendar.timestamp values,
29 which allows for directly using any of the three RFC5545 time formats:
30 - `Utc time: Fixed to absolute UTC time
31 - `Local time: Floating local time (follows user's timezone)
32 - `With_tzid (time, timezone): Local time with timezone reference *)
33
34val edit :
35 ?summary:string ->
36 ?start:Icalendar.params * Icalendar.date_or_datetime ->
37 ?end_:
38 [ `Duration of Icalendar.params * Ptime.Span.t
39 | `Dtend of Icalendar.params * Icalendar.date_or_datetime ] ->
40 ?location:string ->
41 ?description:string ->
42 ?recurrence:Icalendar.recurrence ->
43 t ->
44 (t, [> `Msg of string ]) result
45(** Edit an existing event. *)
46
47val events_of_icalendar :
48 string -> file:Eio.Fs.dir_ty Eio.Path.t -> Icalendar.calendar -> t list
49
50val to_ical_event : t -> Icalendar.event
51val to_ical_calendar : t -> Icalendar.calendar
52val get_id : t -> event_id
53val get_summary : t -> string option
54
55val get_start : t -> Ptime.t
56(** Get the start time of an event. Note that local times are converted to UTC
57 based on their timezone information. If no timezone is specified, the system
58 timezone is used. *)
59
60val get_end : t -> Ptime.t option
61(** Get the end time of an event. Like get_start, times are converted to UTC
62 based on timezone information. Returns None if the event doesn't have an end
63 time. *)
64
65val is_date : t -> bool
66(** Returns true if either the start or end timestamp is specified as a date
67 instead of a datetime. *)
68
69val get_start_timezone : t -> string option
70val get_end_timezone : t -> string option
71val get_duration : t -> Ptime.span option
72val get_location : t -> string option
73val get_description : t -> string option
74val get_recurrence : t -> Icalendar.recurrence option
75val get_calendar_name : t -> string
76val get_file : t -> Eio.Fs.dir_ty Eio.Path.t
77val expand_recurrences : from:Ptime.t option -> to_:Ptime.t -> t -> t list
78
79(** {2 Comparators} *)
80
81type comparator = t -> t -> int
82(** Event comparator function type *)
83
84val by_start : comparator
85(** Compare events by start time, earlier times come first *)
86
87val by_end : comparator
88(** Compare events by end time, earlier times come first. Events with end times
89 come after those without *)
90
91val by_summary : comparator
92(** Compare events by summary alphabetically. Events with summaries come before
93 those without *)
94
95val by_location : comparator
96(** Compare events by location alphabetically. Events with locations come before
97 those without *)
98
99val by_calendar_name : comparator
100(** Compare events by calendar_name name alphabetically *)
101
102val descending : comparator -> comparator
103(** Reverse the order of a comparator *)
104
105val chain : comparator -> comparator -> comparator
106(** Chain two comparators together, using the second one as a tiebreaker when
107 the first one returns equality (0) *)
108
109(** 2 Formatting *)
110
111type format = [ `Text | `Entries | `Json | `Csv | `Ics | `Sexp ]
112(** Format type for output *)
113
114val format_event : ?format:format -> ?tz:Timedesc.Time_zone.t -> t -> string
115(** Format a single event, optionally using the specified timezone *)
116
117val format_events :
118 ?format:format -> ?tz:Timedesc.Time_zone.t -> t list -> string
119(** Format a list of events, optionally using the specified timezone *)
120
121val sexp_of_t : t -> Sexplib0.Sexp.t
122
123(** 3 Queries *)
124
125(** Filter-based searching and querying of calendar events *)
126
127type filter = t -> bool
128
129val summary_contains : string -> filter
130val description_contains : string -> filter
131val location_contains : string -> filter
132val in_calendars : string list -> filter
133val recurring_only : unit -> filter
134val non_recurring_only : unit -> filter
135val with_id : event_id -> filter
136val and_filter : filter list -> filter
137val or_filter : filter list -> filter
138val not_filter : filter -> filter
139
140val query_without_recurrence :
141 t list ->
142 ?filter:filter ->
143 ?comparator:comparator ->
144 ?limit:int ->
145 unit ->
146 t list
147(** Find events without expansion of recurring events. Returns Ok with the list
148 of events, or Error with a message. *)
149
150val query :
151 t list ->
152 ?filter:filter ->
153 from:Ptime.t option ->
154 to_:Ptime.t ->
155 ?comparator:comparator ->
156 ?limit:int ->
157 unit ->
158 t list
159(** Find events with expansion of recurring events. Returns Ok with the list of
160 events, or Error with a message. *)
161
162(* Test-only helper functions *)
163val matches_filter : t -> filter -> bool
164(** Check if an event matches the given filter *)