From 0a4bb4e6c3cbcafb302962d9d1e70b5a0bb554b8 Mon Sep 17 00:00:00 2001 From: Lukasz Kasprzak Date: Mon, 17 Aug 2026 17:46:31 +0200 Subject: feat(cli): --overlay FILE, so a local calendar can be supplied The Overlay algebra has been built and tested since Plan 2, and Date_spec grew movable variants last commit, but there was still no way to hand colitur a file: bin/main.ml applied exactly one overlay, the shipped data/ef/adjustments.sexp, with the path hardcoded. This is the plumbing. --overlay is repeatable and ordered, and applies ON TOP of the shipped adjustments rather than instead of them. That ordering is the whole point: adjustments.sexp carries RG 110's own 30 June companion, the Major Litanies, St Barbara and Rogation Wednesday, and a user file that replaced it would silently drop all four while appearing merely to add a local feast. Overlay.merge is last-writer-wins, so a local calendar can still override a universal entry deliberately, by naming its slug. The dispatch needed real argument parsing. It matched Sys.argv as an exact array, which does not survive a repeatable flag -- two --overlay arguments are a different array shape from one, and each further flag would multiply the patterns again. Flags are now stripped first and the remaining words matched as command plus year. Hand-rolled, because the dependency list is frozen and this is fifteen lines. One defect found by the cram suite on the first run: the unknown-option guard rejected --help and --version, having excluded only their short forms. Refused, not ignored, on easter and temporal. Neither reads sanctoral data -- temporal deliberately runs the cycle before any layer exists -- so accepting the flag there and silently doing nothing is the failure mode this project refuses everywhere else. A file that fails to load is fatal, exactly as the shipped overlay is; a directive naming a slug that does not exist warns on stderr and the run continues. The second matters more for a user file than for ours: a typo in a diocesan calendar should say so rather than quietly do nothing. test/fixtures/overlay-example-diocesan.sexp is a worked example and is labelled as invented, not calendar data. It carries both shapes a real local calendar needs: a fixed-date patron, and a dedication on "the first Sunday of October" -- which is the case the Date_spec work existed to unlock and which lands on 4 October in 2026, 3 October in 2027, 1 October in 2028. The dedication is I class because a church's own dedication anniversary is I class in that church; at III class it lost to the II-class Sunday every year, which a first draft demonstrated correctly and uselessly. The man page gains an OVERLAYS section saying plainly that an overlay is applied, NOT validated: the five test layers assert things about the shipped calendar and none of them can vouch for a file the user supplies. This is the first feature that lets someone change what colitur computes, and that distinction should not have to be inferred. --- man/colitur.1 | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) (limited to 'man') diff --git a/man/colitur.1 b/man/colitur.1 index c65cc58..a18b299 100644 --- a/man/colitur.1 +++ b/man/colitur.1 @@ -7,6 +7,12 @@ colitur \- deterministic liturgical calendar and lectionary engine (Roman rite, .I YEAR .br .B colitur +.BR day | readings +.I YEAR +.BI \-\-overlay " FILE" +.RI [ ... ] +.br +.B colitur .BR \-h | \-\-help .SH DESCRIPTION .B colitur @@ -59,8 +65,20 @@ occurrence, commemoration and transfer. .BI readings " YEAR" The Mass reading citations, one line per day. .TP +.BI \-\-overlay " FILE" +Apply a user calendar on top of the shipped one. Repeatable and ordered; +.B day +and +.B readings +only. See +.B OVERLAYS +below. +.TP .BR \-h ", " \-\-help Print a usage summary to standard output and exit 0. +.TP +.BR \-V ", " \-\-version +Print the version and exit 0. .SH OUTPUT FORMAT .SS day .RS @@ -114,6 +132,55 @@ Both reports are one line per day and ordered by date, so they compose with and .BR join (1) in the ordinary way. +.SH OVERLAYS +.TP +.BI \-\-overlay " FILE" +.RB ( \-o ) +Apply a user\-supplied calendar on top of the shipped universal one. Repeatable +and ordered. +.PP +Overlays are applied +.I on top of +the 1962 universal calendar, never instead of it. The shipped adjustments \(em +which carry the inseparable Peter/Paul commemoration, the Major Litanies, St +Barbara and Rogation Wednesday \(em are applied first, then each +.B \-\-overlay +in the order given. Last writer wins, so a later file may deliberately override +an earlier one, or a universal entry, by naming its slug. +.PP +An overlay is an S\-expression file with an +.I id +and a list of directives: +.BR Add ", " Suppress ", " Replace " and " Edit . +An added entry carries its own date specification, which may be a fixed +.RI ( month ", " day ) +pair, an +.I Easter_offset +in days, or an +.I Nth_weekday +of a month \(em so a patronal feast on "the first Sunday of October" or a +dedication anniversary reckoned from Easter are both expressible. See +.I test/fixtures/overlay\-example\-diocesan.sexp +in the source distribution for a worked example of both shapes. +.PP +Accepted on +.B day +and +.B readings +only. The other commands read no sanctoral data at all, so the flag would have +no effect there and is +.I refused +rather than silently ignored. +.PP +.B An overlay is applied, not validated. +This program's test layers \(em properties over every year in the domain, a +differential against a sibling engine, two published\-calendar oracles, and +hand\-verified pins \(em assert things about the +.I shipped +calendar. None of them can vouch for a file you supply. A directive naming a +slug that does not exist prints a warning to standard error and the run +continues, so a typo in a local calendar is visible rather than silent; a file +that fails to load is fatal. .SH ENVIRONMENT .TP .B COLITUR_DATA_DIR @@ -182,6 +249,15 @@ Days carrying at least one commemoration: .fi .RE .PP +A local calendar on top of the universal one: +.RS +.nf + +.B colitur day 2026 \-\-overlay ~/calendars/diocese.sexp +.B colitur day 2026 \-\-overlay ~/calendars/diocese.sexp \-\-overlay ~/calendars/parish.sexp +.fi +.RE +.PP Run against a checkout's data rather than the installed copy: .RS .nf -- cgit v1.3