Recurring events in calendar.txt (#1153)
How an event in calendar.txt repeats: the rule it is written with, the
days it is shown on, skipping, moving and changing occurrences, its
reminders, and the sync merge. Written before the code (2026-10-26), as
the plan the work follows. The grammar of rec: is the one tasks use,
settled in recurring-tasks.md; the file’s format and
its merge are in calendar-txt.md.
calendar.txt has no recurrence of its own — one line per day, an event
on the line it is written on — and the constraint stays the one that
record keeps: the file is the user’s, other tools read it, and Niman
writes only the line it was asked to change.
Options weighed
- Expand ahead: write the occurrences into the file for a horizon. Every reader sees them, but the file grows, the rule has to live somewhere else, and editing “all occurrences” means rewriting many lines another device may be editing too. Rejected.
- A rule on the event, read virtually. Chosen (below).
- A separate rules file (
.niman/recurring.txt):calendar.txtstays untouched, but part of the calendar is then state that is not in the plain file, which the design rules forbid. Rejected.
Decisions (2026-10-26)
-
The rule is a
rec:token on the event, on the day line of its first occurrence:2026-10-21 Wed w43 9-9:30 Standup @work rec:1w. 17-18 joggingNiman shows the event on every day the rule matches, from that day on, and never writes the occurrences out. Another calendar.txt reader sees it once, on its first day, with one more word in it. A
rec:+is the same asrec:here: an event is never completed, so there is no completion date to count from. - Occurrences are counted from the first day, not from the previous
occurrence: the k-th is the first day plus k steps, so a monthly event
on the 31st falls on the last day of a short month and is back on the
31st after it — no drift, unlike a task’s chain.
rec:1bis every weekday; the extensions (rec:1w;mo,we,rec:1m;2tu,rec:1m;-1fr) are the weekly-on-days and Nth-weekday presets. - Exceptions are tokens on the rule, after RFC 5545:
until:2026-12-31— the last day an occurrence may fall on, inclusive;except:2026-11-04,2026-11-18— occurrences that do not happen, a comma-separated list of the dates they would have fallen on.
The actions are made of those two and of ordinary events:
- Skip this occurrence: add its date to
except:. - Move or edit this occurrence:
except:its date, and write a plain event (norec:) on the new day with the change. It is an ordinary event from then on. - This and following:
until:the day before on the rule, and a new rule event, changed, on the occurrence’s own day line. - All occurrences: edit the rule event itself.
- Delete offers the same three: this one (skip), this and following
(
until:), all (the rule’s event is deleted).
An
except:list grows by a date per skip; a rule that has run for years with many skips is ended and restarted by This and following, which drops the past list. - “Done” means nothing for an event. Events are not completed; only their reminders recur.
- Every occurrence is shown everywhere an event is: the journal’s events dot in the day cell, the dock pane and the phone’s day card, the Home tile Events today. An occurrence carries the repeat icon (outline) and the rule in words. The lone-token search lists the rule’s line once, with the rule in words — it is one line in the file.
- Reminders keep a short horizon. A rule event with
rem:schedules every occurrence that falls in the next 14 days, and every reconciliation (app start, file change, a fired reminder handled) recomputes that set — so the alarms run on for days without the app being opened. A clockrem:16:30is that time on each occurrence’s day; a fullrem:date-time keeps its offset from the first day. Ids come from the event’s namespace salted with the occurrence’s date, so each occurrence is its own alarm and a skip cancels exactly one. The existing soonest-pendingLimitcut remains the backstop. - The editor. The event form gets the Repeat row tasks get (Never,
Daily, Weekdays, Weekly on this day, Monthly on this day / on the Nth
weekday, Yearly, Custom) and an Ends row (never, on a date). Opening
an occurrence — the dock’s context menu on the desktop, the event sheet
on a phone — offers Edit, Skip, Delete and Open in calendar.txt; Edit
and Delete then ask This event / This and following / All events.
Open in calendar.txt goes to the rule’s line. The source editor colours
rec:,until:andexcept:as it coloursrem:. - Sync: rule events are paired by identity, and their exceptions
merged. The calendar merge (
calendar-txt.md, decision 2B) merges a day’s events as a set, so two devices each skipping a different occurrence of the same rule would leave two rule events — and every occurrence shown twice. The merge therefore pairs the rule events of a day line by the event withexcept:anduntil:taken out; a pair merges into one event whoseexcept:is the union and whoseuntil:is the earlier of the two. Any other difference is a real edit, and both are kept, as for any event.
Where it lives
The rule model and its arithmetic are lib/src/core/recurrence/, shared
with tasks. lib/src/calendar/ gains the expansion — occurrences of every
rule in a date range, from the parsed file, for the journal’s visible
month and the dock — the writer’s actions above, and the merge’s rule
pairing. The reminder horizon extends the calendar half of
lib/src/todo/reminders.dart.
Risks
- Other readers see a rule event once. That is the price of keeping
the file as written; the user guide says so, and that
grepfinds the rule on its first day. - Android caps an app’s pending alarms (500 per app), and no backend
reports that cap today (
pendingLimitis null on Android). The horizon keeps recurring alarms bounded — at most 4 per rule — but the Android backend should report a limit below the cap, so a library with many rules degrades to “the soonest are scheduled” instead of an exception. Ztimes and occurrences across midnight follow the existing rule: an occurrence stays on its day, and the reminder fires at the right instant.- A rule event moved by hand to a later day line simply starts there;
its
except:dates before that day no longer matter. - 37 locale files for the presets, the rule in words and the three-way choice.
As built: skip, move, this and following, merge (#1191, 2026-10-26)
What the code does where the plan left a choice, or where the plan met the file.
- The actions are pure line transformations
(
lib/src/calendar/calendar_occurrence_edits.dart), one per action and scope, over the file’s lines with their own endings;calendar_rule_tokens.dartrewrites oneuntil:orexcept:in an event in place (or closes the event with a new one), andcalendar_splice.dartholds the line-level helpers both writers share. Each answers null — a no-op, nothing written — when the file no longer holds the event, or when the rule does not reach the day it was asked about (a skip of a day already skipped, say), so a double tap or a file moved under the screen never edits the wrong thing. except:is sorted and kept in one token. A skip rewrites the first readableexcept:of the event as the sorted union with the new day, or closes the event with a new token when it has none; anexcept:it cannot read is left as written.- Edit this one writes the plain event on the day the form’s Day row says: the occurrence’s own by default, or another day, which is the move.
- The Day row is the task dialog’s due-date pattern: the calendar in place
on a window with the room, the system’s date picker elsewhere. The draft
carries the day (
CalendarEventDraft.day, null when the form did not say), and the writer reads it: an added event goes there, a plain event that is edited leaves its line for that day’s (two lines change, the new one made in date order when missing), and one occurrence isexcept:ed and written there. An event that does not repeat is edited with no scope (nothing to ask). The preview shows every line the write changes, not only the day’s. The row is on for every scope and what it moves is the scope’s (#1225): the one occurrence, written as a plain event on the new day; the new rule event of This and following, which starts there while the old rule still ends the day before the occurrence; the rule event of All events, whose first day, and so every occurrence, moves. What was picked is what is written: the day was once honoured only for one occurrence, and a series saved with another day lost it without a word. - Edit this and following from the rule’s first day is the same as All
events (
until:the day before would end the rule before it began), and so is a Delete of this and following, which deletes the event instead. - The draft carries the rule.
CalendarEventDrafthas arecurrence(rule, end, skipped days); an edit reads an event into a draft without itsrec:,until:,except:and clockrem:in the text, the form shows and changes them apart, and the writer puts them back after the text. That also ends a bug of the old edit, which left arem:in the text and wrote a second one from the reminder. - Ask first, then the form. Edit and Delete ask the scope before anything else, so the form’s preview is the writer’s own answer for that scope. For this event the form’s Repeat and Ends rows are off and say Never — the event becomes a plain one. Ends is off while there is no rule to end; neither row is ever hidden.
- The three-way question is the app’s list of choices
(
showActionSheet): a sheet on a phone and a small menu at the pointer on a window, as every other list of choices is, not a dialog over the calendar (#712). The dock’s context menu is the same: right click an event, or long press it on a touch screen that has the dock, whose tap still opens the file. - Skip is on every event’s menu and off for one that does not repeat, so the rows do not move with the event shown.
- The presets of an event are Daily, Weekdays, Weekly on the day, Monthly on the date, Monthly on the Nth weekday (the last, when the day is a fifth), Yearly — none strict, and the custom editor has no “from the due date or the completion” choice: it is the task’s row, with those two options turned off.
- The merge pairs by the event without
until:andexcept:(spaces normalised), and only when everyuntil:andexcept:of both copies can be read.except:is a three-way set merge — a day either side added is in, and a day the base had is out when either side took it away — which is the plan’s union whenever nobody un-skips.until:follows the side that changed it; when both did, or there is no base, the earlier wins and no end counts as later than any. A side that left the event as the base had it gives the other’s text to the character. Everything else stays the set merge: a different text, time or rule is a different event and both are kept.
As built: reminders (#1192, 2026-10-26)
What the code does where the plan left a choice.
- The window is the occurrence’s day, today to today + 13 (fourteen days,
today included), minus the occurrences whose reminder is more than
reminderGracebehind. Every one of them is wanted: there is no count per rule (#1228; #1192 first kept the soonest four, which left a daily event with four days of alarms on Android and Apple, not the fourteen promised). The first day itself is an occurrence like the others, and behaves as a plain event does. - Ids. The rule’s first day keeps the id the event always had
(
calendarReminderId(day, text)), so an event that gains arec:does not re-arm its first alarm; the later occurrences are salted with the series’ first day and their own date (calendarOccurrenceReminderId). The text the id comes from is the event’s withoutuntil:andexcept:: a skip or an end rewrites those words, and the alarms that remain must keep their ids, or a skip would cancel and re-arm every one instead of cancelling one. (An event with neither word has exactly the old id.) - A full
rem:date-time on an event is read — it was ignored before, for any event. A plain event fires at that stamp; a rule’s keeps its distance in calendar days from the first day. A distance after the occurrence widens the window backwards by as many days, so a reminder still ahead is not lost when its occurrence is behind. The notification opens the journal on the occurrence’s day. - The horizon moves forward from the triggers that already exist.
Reconciliation runs at app start (the shell opens the controller), on every
return to the foreground, and on every change of
todo.txtorcalendar.txt, and each computes the window from the clock. A notification tap that starts the app is an app start, and one while it runs returns it to the foreground. What was missing was a desktop left running: its timers fire in the process and nothing else touches it, so the window would run dry after a few days. The backends gain afiredstream — the desktop’s emits after a notification is shown, the OS-alarm backends never do — and the todo controller reconciles on it. No timer, no background job. On Android and Apple, with the app closed, nothing runs: the user guide says to open the app every two weeks. - Android’s limit is 400,
androidPendingAlarmLimit, below the 500 concurrent alarms per app. OnlyPluginReminderBackend(Android) reports it; iOS keeps 64 and the desktops none. - The cap is one for the whole app (#1228).
LocalReminderServicecuts the one wanted set — tasks, plain events and every occurrence of every rule — to its soonestpendingLimitby moment (ties by id, so the cut is the same every time). So a library under the cap holds all fourteen days of every rule, and one over it keeps the days that fit, soonest first, across all the rules: a rule is never starved to give another its full window, and the days cut are always the furthest ones. The rest are not scheduled at all until a later reconcile brings them under the cap. - What happens when the cap is reached, per platform. The desktops have
no cap (in-process timers; the
firedstream reconciles as each one is shown, which moves the window on). Android and Apple deliver with the app closed but nothing reconciles as an alarm fires —firednever emits there — so the days cut stay unscheduled until the app next starts, resumes or sees a file change. A library that crosses the cap (about 28 daily events on Android, 4 on iOS) therefore runs dry sooner than two weeks after the last open: when the soonest alarms have all fired. The user guide says so. Topping the window up from the background (WorkManager on Android, a background refresh on iOS) is not built.
As built: review fixes (#1218-#1227, 2026-10-27)
What the review of the first release of the editor changed.
- The form’s rule is the only rule in the line (#1227). A draft that
carries a rule writes its
rec:,until:andexcept:and takes every such token out of its text first, readable or not. The firstrec:and the firstuntil:of an event are the ones read, so anuntil:2026-1-31the grammar cannot read, left in the text, used to win over the end the form wrote (and the event ran for ever); a secondrec:oruntil:typed by hand is replaced, not kept beside the form’s. A draft with no rule leaves the text as it is: arec:nobody can read is kept and flagged. - A reminder survives an edit (#1226). A clock
rem:is read out of the text and shown as a lead only when the event has a start to count it from; on an event with no time it stays in the text, as written, and is written back (it used to be cut, and an edit then dropped it while the switch still read on). A full-stamprem:names its own day, so a copy of the event on another day takes the stamp with the same distance from it: This one and This and following re-base it from the rule’s first day onto the day written, and an event that moves, a plain one or the rule event, takes it along. A stamp the user typed into the form is theirs and is not moved. The form’s lead never lands on the day before: the offered leads are the ones that fit, a lead that no longer fits after the start moved earlier becomes the longest that does, and at midnight the switch is off. - This and following keeps the series’ day (#1224). A monthly rule on the
date and a yearly one have no day of their own in the token:
rec:1mis the first day plus k months, each clamped, so the 31st is the 30th in April and the 31st again in May. A new series anchored on the clamped occurrence would take the 30th for good (and a series begun on 29 February would never reach it again), andrec:has no syntax to say “the 31st” apart from the first day. So when the edit leaves such a rule of the same kind and the occurrence is not on the first day’s own day, the new series begins on the first occurrence that is (31 May; 29 February 2032), and the clamped occurrences before it, the one edited included, are written as the plain events This event writes: the edited event, once each, on its day. Every other case anchors the new series on the occurrence, as before, and so does an edit that picks another day: the user’s day is the new first day. - The dock’s form is keyed on what it edits (#1218). The form reads its draft once, when its state is made, so the inline form of the dock — which stays on screen while another Edit or Add event arrives — is given a key made of the event’s line, its start, the occurrence’s day and the scope, so a new target is a new form. Without it, Edit on a second event kept the first one’s fields and saved them over the second.
- The form opens on the day it writes (#1221). Edit all writes the rule event on its own line, so its form opens on the series’ first day: the Ends row can end the series as early as that day, and the weekly and Nth-weekday presets are taken from the day the rule began, not from the occurrence that happened to be tapped. This one and This and following open on the occurrence, the day the changed event or the new series starts on. The form’s preview is given the occurrence apart from the form’s day, so it is the writer’s answer for the scope in both cases.
- Moving the Day follows through the rows (#1219). The Ends picker is
bounded by the day when it opens, and a preset is a rule worked out from the
day, so a Day changed afterwards left both stale: an
until:before the new first day madeoccurrencesyield nothing, and the event stayed in the file and never showed; a weekly preset stayed on the old weekday. The form now drops an end that falls before the new day (the Ends row says Never ends), and a rule that is one of the presets of the old day becomes the same preset of the new one (eventRuleOnDay); a rule that no preset says is the user’s own and stays. The open custom editor follows the rule (#1220).