Module agenda 

Calendars: events from iCalendar files (RFC 5545), one event and its exceptions per file as CalDAV keeps them (RFC 4791 §4.1).

What comes is computed for a stretch of days: repeating events are expanded (RRULE, RDATE, EXDATE and changed occurrences, calcard’s expand_dates), each in its own time zone, then shown in yours. Nothing is “late” or “overdue”: the past is simply not shown (docs/client.md, rule 9).

Events are changed line by line (lines): what Sioul does not edit (alarms, guests, another application’s fields) is kept exactly. New events are written in UTC; a repeating one keeps its local time across the change of hour with its time zone, written out in a VTIMEZONE.

Structs

Attendee

Someone invited, and what they answered.

Changed 🔒

What the form changed, field by field: a field unchanged keeps its line.

EventEdit

What the event form gives back. Times are local, in your time zone.

EventRef

What an event file ties to: its links (LINK, RELATED-TO), its projects (REFID) and its guests, read from its main VEVENT.

Invitation

An invitation (iTIP, RFC 5546) carried by a message.

Occurrence

One occurrence of an event, as the agenda shows it.

Enums

MoveProblem

Why an event stayed where it was (moved).

Constants

EDITED 🔒

Lines of the main event (not a changed occurrence) rewritten at every change.

EXPANSION_LIMIT 🔒

Occurrences of a repeating event looked at, at most, per file: a safety net. Expansion starts just before the stretch asked for (from_window), so an event repeating every hour for years still reaches today.

FIRST_LOOKED_AT 🔒

Occurrences looked at to find an event’s first one still there: occurrences left out (EXDATE) count against the limit, so one would find none when the first was removed, and the event could no longer be opened.

TIMES 🔒

Rewritten only when the form changed the time: an event written in another zone keeps it, and so does its time.

Functions

add_lines

The event with added lines in its main VEVENT (a LINK, a REFID), those not there yet, before its alarms; None when it holds no event. Nothing else changes: the stamps stay, as a link is not a change of the event.

address 🔒

“mailto:jane@example.org” → “jane@example.org”.

alarms_of 🔒

An event’s alarms, in seconds from its start (length turns those set from its end); one set at a fixed time counts only for an event that does not repeat.

answers

Each guest’s answer in an event, by address (lower case): its PARTSTAT, “NEEDS-ACTION” when it says none; the event’s own guests, not those of a changed occurrence. Empty for what has no guests (a contact, a task).

apply

The event’s text with what the form edits changed in its main VEVENT; the rest, changed occurrences and alarms included, kept as it was. The times and the repeat rule are written again only when they changed: a rule the form cannot show (“every other Monday and Wednesday”) stays whole while the title changes. The SEQUENCE goes up, as RFC 5545 §3.8.7.4 asks.

calcard_zone 🔒

A zone as calcard knows it: times written without a zone are taken in it.

content_lines 🔒

SUMMARY, LOCATION, DESCRIPTION and the repeat rule, those that changed.

default_calendar

Where a new event goes: the first calendar that can be written to and takes events, the one made for time blocks last (blocks::CALENDAR).

demands_of 🔒

Its margins, costs and gain, from Sioul’s own properties (demands).

edit_of

An event as the form shows it, from its file, in your time zone.

edit_of_text

An event as the form shows it, from its text, in zone.

event_ranges 🔒

The text’s VEVENTs, BEGIN to END, in order (their alarms inside them).

event_ref

The ties of one event’s text; None when it holds no event.

event_refs

The ties of every event, in every calendar.

file_occurrences

The occurrences of one file’s events between from and to (Unix seconds); times written without a zone are taken in zone, yours. Expanded from just before from (from_window), not from each event’s start.

first_times

The main event’s first occurrence still there, as the agenda shows it: (start, end) in Unix seconds, to the second; None when the text holds no event. Times without a zone are in zone.

for_expansion 🔒

The text as calcard should expand it. calcard puts a changed occurrence (RECURRENCE-ID) in place of its time in the series only when both have the same SEQUENCE, where RFC 5545 matches them by RECURRENCE-ID alone: a series edited since, or an occurrence changed by an application that counts its own changes, would show twice, at its old time and its new one. So each changed occurrence is read with the series’ SEQUENCE; the file is left as it is.

from_window 🔒

The text as calcard should expand it for occurrences from from (Unix seconds) on. calcard expands a repeating event from its start, at most EXPANSION_LIMIT occurrences, so an event repeating every hour begun years ago would never reach today. Its start (and its end) moved forward by whole periods of its rule, to a couple of days and a period before from, give the same occurrences from there on: done for rules repeating by the second, minute, hour, day or week (their periods are all as long; a month or a year reaches far enough from the start), without COUNT (counted from the true start), and without a change to “this and those after” (RANGE, whose offset starts at its own occurrence). A start without a time, or one that does not read, is left as it is. The file is left as it is.

head_of 🔒

A line’s name and parameters, as written: “DTSTART;TZID=Europe/Paris”.

instants 🔒

The start and end the form means, in your time zone.

invitation

What an invitation asks, from the text of its text/calendar part; times without a zone are taken in zone, yours.

is_all_day 🔒

A date without a time: the event lasts whole days.

mark_declined

Each event own (your addresses) declined marked so (Occurrence::declined).

master_range 🔒

The lines of the main VEVENT, BEGIN to END.

moment_in 🔒

The moment one value of line means (a DATE-TIME list’s item): in its TZID, UTC with a Z, a date at midnight; a time without a zone, in zone.

moved

The event moved as a drag in the agenda asks: its occurrence starting at start (Unix seconds, as shown) now from new_start to new_end. A single event takes the new times. A repeating one moves that time alone (only_this: a changed occurrence, RECURRENCE-ID, RFC 5545 §3.8.4.4; one changed already is changed again), or every time by as much on the clock: its first time, the times left out (EXDATE) and added (RDATE), and the times its changed occurrences replace go together, a weekly rule’s days with them; the changed occurrences keep their own times, but the one moved. What Sioul does not edit is kept (apply); times without a zone are in zone.

new_event

A new event from the form, its times in zone (yours), with its own UID.

new_path

The file a new event gets in a calendar.

occurrence_at 🔒

Which occurrence of a file’s event starts at start (Unix seconds), as the agenda shows it: the place of the VEVENT holding it among the text’s VEVENTs (calcard keeps them in the text’s order), and whether that one is a changed occurrence (RECURRENCE-ID). Times without a zone are in zone.

occurrences

Everything between from and to, from every calendar, by start; those you declined marked (declined), by your accounts’ addresses.

parse

Parses an iCalendar object.

people 🔒

remind_of 🔒

What an occurrence says of its reminder: its own, else, a changed one (RECURRENCE-ID) saying nothing, its series’.

remind_word 🔒

An event’s reminder before (reminders::REMIND), as the form says it: “” as usual, “none”, or minutes (“15”).

remove_lines

The main VEVENT without the lines drop picks (its alarms untouched); None when the text holds no event.

reply

Your answer to an invitation (iTIP REPLY, RFC 5546 §3.2.3): the event with you alone among the guests, your answer in PARTSTAT. answer: “ACCEPTED”, “DECLINED” or “TENTATIVE”.

retimed 🔒

A VEVENT’s lines with its own times set: from to to, written as its DTSTART was (like), DURATION replaced by DTEND; its stamps written again. Its SEQUENCE goes one up (RFC 5545 §3.8.7.4), unless recurrence makes it a new changed occurrence of the series: then it keeps the series’ own, as readers that match the two by it want (calcard). Its alarms are kept as they are; drop names the other lines left out (a new changed occurrence leaves the rule).

rule_line 🔒

rule_moved 🔒

A repeating event’s rule, its occurrences moved by span on the clock: a weekly rule’s days (BYDAY=MO,WE) move with them, and its end (UNTIL) by as much. None when the move would not keep what the rule says: days set otherwise (a day of the month, “the first Monday”) moved to another day, or hours set in the rule (BYHOUR) moved to another time.

skip_occurrence

Leaves one occurrence of a repeating event out (EXDATE), in the form DTSTART is written. One changed already (RECURRENCE-ID: moved by a drag in the agenda, or by another application) goes with its change: its own VEVENT is taken out, and the time it replaced in the series is left out.

stored

Adds an invitation’s event to a calendar file, as the organizer sent it, METHOD removed (RFC 4791 §4.1 forbids it in stored objects).

stored_answered

An invitation’s event as your calendar keeps it once you answered: as the organizer sent it (stored), your own line among the guests (me, by address) saying your answer (“ACCEPTED”, “TENTATIVE”), as an attendee’s copy says it (RFC 5546 §3.2.3). Your other devices, and any calendar reading the server, then know what you answered; two devices answering the same invitation can tell whether they said the same (answers). Unchanged but for METHOD when you are not among the guests by that address.

text_of 🔒

time_lines 🔒

DTSTART and DTEND lines for the form’s times: dates for whole days; UTC for one-off events; local time with the zone for repeating ones.

utc 🔒

vtimezone

The VTIMEZONE of a zone, as its changes of hour go this year: one STANDARD and one DAYLIGHT part, each repeating yearly on the same weekday of the same month (“last Sunday of October”); a single part when it has no summer time.

with_answer 🔒

A guest’s line with answer in its PARTSTAT, RSVP dropped: an answer asks for none. A line without its colon (a broken file) has no value: all of it is the head.

written_like 🔒

A line name for at, with like’s parameters, written as like writes its time.

written_value 🔒

at as like writes its time (a DTSTART line): a date, UTC, or the clock in its TZID; a time without a zone, on the clock in zone.