Command-line and Emacs Calendar Client
ryan.freumh.org
1val default_timezone : (unit -> Timedesc.Time_zone.t) ref
2(** Default timezone to use for date operations. Defaults to the local timezone
3 of the system, falling back to UTC if local timezone cannot be determined.
4*)
5
6val timedesc_to_ptime : Timedesc.t -> Ptime.t
7(** Convert a Timedesc.t to a Ptime.t. *)
8
9val ptime_to_timedesc : ?tz:Timedesc.Time_zone.t -> Ptime.t -> Timedesc.t
10(** Convert a Ptime.t to a Timedesc.t with the specified timezone. If no
11 timezone is provided, uses the default_timezone. *)
12
13val get_today : (?tz:Timedesc.Time_zone.t -> unit -> Ptime.t) ref
14(** Get the current date at midnight in the specified timezone. If no timezone
15 is provided, uses the default_timezone. This is a reference to support
16 testing. Returns the date or raises an exception if the date cannot be
17 determined. *)
18
19val to_end_of_day : Ptime.t -> Ptime.t
20(** Converts a date with midnight time (00:00:00) to the same date with
21 end-of-day time (23:59:59). This is particularly useful for making "to"
22 dates in a range inclusive, addressing the common UX expectation that
23 specifying "--to 2025-04-01" would include events occurring on April 1st. *)
24
25val add_days : Ptime.t -> int -> Ptime.t
26(** Add specified number of days to a date. Raises an exception if the date
27 cannot be calculated. *)
28
29val add_weeks : Ptime.t -> int -> Ptime.t
30(** Add specified number of weeks to a date. Raises an exception if the date
31 cannot be calculated. *)
32
33val add_months : Ptime.t -> int -> Ptime.t
34(** Add specified number of months to a date. Raises an exception if the date
35 cannot be calculated. *)
36
37val add_years : Ptime.t -> int -> Ptime.t
38(** Add specified number of months to a date. Raises an exception if the date
39 cannot be calculated. *)
40
41val get_start_of_week : Ptime.t -> Ptime.t
42(** Get the start of the week (Monday) for the given date. Raises an exception
43 if the date cannot be calculated. *)
44
45val get_start_of_current_week : ?tz:Timedesc.Time_zone.t -> unit -> Ptime.t
46(** Get the start of the current week in the specified timezone. If no timezone
47 is provided, uses the default_timezone. Raises an exception if the date
48 cannot be calculated. *)
49
50val get_start_of_next_week : ?tz:Timedesc.Time_zone.t -> unit -> Ptime.t
51(** Get the start of next week in the specified timezone. If no timezone is
52 provided, uses the default_timezone. Raises an exception if the date cannot
53 be calculated. *)
54
55val get_end_of_week : Ptime.t -> Ptime.t
56(** Get the end of the week (Monday) for the given date. Raises an exception if
57 the date cannot be calculated. *)
58
59val get_end_of_current_week : ?tz:Timedesc.Time_zone.t -> unit -> Ptime.t
60(** Get the end of the current week in the specified timezone. If no timezone is
61 provided, uses the default_timezone. Raises an exception if the date cannot
62 be calculated. *)
63
64val get_end_of_next_week : ?tz:Timedesc.Time_zone.t -> unit -> Ptime.t
65(** Get the end of next week in the specified timezone. If no timezone is
66 provided, uses the default_timezone. Raises an exception if the date cannot
67 be calculated. *)
68
69val get_start_of_month : Ptime.t -> Ptime.t
70(** Get the start of the month for the given date. Raises an exception if the
71 date cannot be calculated. *)
72
73val get_start_of_current_month : ?tz:Timedesc.Time_zone.t -> unit -> Ptime.t
74(** Get the start of the current month in the specified timezone. If no timezone
75 is provided, uses the default_timezone. Raises an exception if the date
76 cannot be calculated. *)
77
78val get_start_of_next_month : ?tz:Timedesc.Time_zone.t -> unit -> Ptime.t
79(** Get the start of next month in the specified timezone. If no timezone is
80 provided, uses the default_timezone. Raises an exception if the date cannot
81 be calculated. *)
82
83val get_end_of_current_month : ?tz:Timedesc.Time_zone.t -> unit -> Ptime.t
84(** Get the end of the current month in the specified timezone. If no timezone
85 is provided, uses the default_timezone. Raises an exception if the date
86 cannot be calculated. *)
87
88val get_end_of_next_month : ?tz:Timedesc.Time_zone.t -> unit -> Ptime.t
89(** Get the end of next month in the specified timezone. If no timezone is
90 provided, uses the default_timezone. Raises an exception if the date cannot
91 be calculated. *)
92
93val get_end_of_month : Ptime.t -> Ptime.t
94(** Get the end of the month for the given date. Raises an exception if the date
95 cannot be calculated. *)
96
97val get_start_of_year : Ptime.t -> Ptime.t
98(** Get the start of the year (Jan 1) for the given date. Raises an exception if
99 the date cannot be calculated. *)
100
101val get_start_of_current_year : ?tz:Timedesc.Time_zone.t -> unit -> Ptime.t
102(** Get the start of the current year in the specified timezone. If no timezone
103 is provided, uses the default_timezone. Raises an exception if the date
104 cannot be calculated. *)
105
106val get_start_of_next_year : ?tz:Timedesc.Time_zone.t -> unit -> Ptime.t
107(** Get the start of next year in the specified timezone. If no timezone is
108 provided, uses the default_timezone. Raises an exception if the date cannot
109 be calculated. *)
110
111val get_end_of_year : Ptime.t -> Ptime.t
112(** Get the end of the year (Dec 31, 23:59:59) for the given date. Raises an
113 exception if the date cannot be calculated. *)
114
115val get_end_of_current_year : ?tz:Timedesc.Time_zone.t -> unit -> Ptime.t
116(** Get the end of the current year in the specified timezone. If no timezone is
117 provided, uses the default_timezone. Raises an exception if the date cannot
118 be calculated. *)
119
120val get_end_of_next_year : ?tz:Timedesc.Time_zone.t -> unit -> Ptime.t
121(** Get the end of next year in the specified timezone. If no timezone is
122 provided, uses the default_timezone. Raises an exception if the date cannot
123 be calculated. *)
124
125val convert_relative_date_formats :
126 ?tz:Timedesc.Time_zone.t ->
127 today:bool ->
128 tomorrow:bool ->
129 week:bool ->
130 month:bool ->
131 unit ->
132 (Ptime.t * Ptime.t) option
133(** Converts relative date formats to determine from/to dates in the specified
134 timezone. If no timezone is provided, uses the default_timezone. Returns a
135 tuple of (start_date, end_date) or raises an exception if the dates could
136 not be determined. **)
137
138val parse_date :
139 ?tz:Timedesc.Time_zone.t ->
140 string ->
141 [ `To | `From ] ->
142 (Ptime.t, [> `Msg of string ]) result
143(** Parse a date string that could be ISO format (YYYY-MM-DD) or a relative
144 expression in the specified timezone. If no timezone is provided, uses the
145 default_timezone.
146
147 Supported formats:
148 - ISO format:
149 - "YYYY-MM-DD" (full date)
150 - "YYYY-MM" (partial date)
151 - For --from: defaults to first day of month
152 - For --to: defaults to last day of month
153 - "YYYY" (partial date)
154 - For --from: defaults to January 1st of year
155 - For --to: defaults to December 31st of year
156 - Relative expressions:
157 - "today" - Current day
158 - "tomorrow" - Next day
159 - "yesterday" - Previous day
160 - "this-week" - Start of current week
161 - "next-week" - Start of next week
162 - "this-month" - Start of current month
163 - "next-month" - Start of next month
164 - "+Nd" - N days from today (e.g., "+7d" for a week from today)
165 - "-Nd" - N days before today (e.g., "-7d" for a week ago)
166 - "+Nw" - N weeks from today
167 - "+Nm" - N months from today
168 - "+Ny" - N years from today *)
169
170val parse_time : string -> (int * int * int, [> `Msg of string ]) result
171(** Parse a time string in HH:MM or HH:MM:SS format. Returns Ok with (hour,
172 minute, second) or Error with a message. **)
173
174val parse_date_time :
175 ?tz:Timedesc.Time_zone.t ->
176 date:string ->
177 time:string ->
178 [ `To | `From ] ->
179 (Ptime.t, [> `Msg of string ]) result
180(** Parse a date and time string in the specified timezone. If no timezone is
181 provided, uses the default_timezone. *)
182
183val ptime_of_ical : Icalendar.date_or_datetime -> Ptime.t