aboutsummaryrefslogtreecommitdiff
path: root/lib/render/escape.mli
diff options
context:
space:
mode:
authorLukasz Kasprzak <lukas@labunix.xyz>2026-08-19 11:48:30 +0200
committerLukasz Kasprzak <lukas@labunix.xyz>2026-08-19 11:48:30 +0200
commit6762ce46af3cb12bc6ae37cda762c5d95add7903 (patch)
treebc1d8c86050d0149ff961a9a4ff838f9c474ac2a /lib/render/escape.mli
parent897c274fd28402159ca6d45eedc1257b1ce98696 (diff)
parent390bc6ac5196a946c473d0dbe7760fa41837c428 (diff)
downloadcolitur-6762ce46af3cb12bc6ae37cda762c5d95add7903.tar.gz
colitur-6762ce46af3cb12bc6ae37cda762c5d95add7903.zip
feat: output, rendering and publishing
Gives colitur a publishable exit. Until now its only output was terminal rows; it can now print an ordo booklet and a wall calendar, publish an iCalendar feed people subscribe to, and serve a static JSON/XML API. lib/render escaping (six flavours + RFC 5545 folding), a deliberately logic-less template engine, the view model, and five emitters (CSV, JSON, XML, iCalendar, S-expression) CLI emit, table, render, publish -- all accepting --overlay templates ordo booklet in six flavours, wall grid in three schema day-v1.json and colitur-v1.xsd, the published contract man colitur-templates.5, plus colitur.1 updates The view model is why the engine can stay logic-less: a month grid needs leading blank cells, week bucketing and an in-month test, and a logic-less template can compute none of it. Shaping the data in OCaml keeps the engine safe for untrusted templates and makes the grid trivial. Formats split by whether correctness is mechanical. Presentation goes through templates; iCalendar and XML get dedicated emitters, because folding, exclusive DTEND, stable UIDs and schema fidelity are rules a template cannot enforce and each fails silently in a subscriber's client rather than loudly at generation. publish is deterministic and non-destructive: two runs produce a byte-identical tree, and --prune removes only files a previous run created, refusing any manifest entry that escapes the output directory. No new dependencies. The kernel and rite modules are untouched, and colitur day and colitur readings remain byte-identical.
Diffstat (limited to 'lib/render/escape.mli')
-rw-r--r--lib/render/escape.mli28
1 files changed, 28 insertions, 0 deletions
diff --git a/lib/render/escape.mli b/lib/render/escape.mli
new file mode 100644
index 0000000..97cf050
--- /dev/null
+++ b/lib/render/escape.mli
@@ -0,0 +1,28 @@
+(** Per-flavour escaping for the template engine, plus RFC 5545 line folding.
+
+ Knows nothing about calendars. Pure and total: every function is defined on
+ every string, and none reads the clock, the environment or the filesystem. *)
+
+(** The six escaping modes. Markdown, AsciiDoc and plain text all use [None_]:
+ their metacharacter sets are context-dependent, and escaping them
+ aggressively produces worse output than not escaping at all (spec section 5).
+ This is a documented limitation of those flavours. *)
+type flavour = Latex | Groff | Html | Xml | Ics | None_
+
+val all : flavour list
+val to_string : flavour -> string
+val of_string : string -> flavour option
+
+(** [of_extension ".tex"] is [Some Latex]. Returns [None] for an unrecognised
+ extension: the caller must treat that as an error, never as a fallback to
+ [None_] (spec section 5 -- guessing wrong here produces malformed output
+ that looks fine until it does not). *)
+val of_extension : string -> flavour option
+
+(** Escape one interpolated value for [flavour]. *)
+val apply : flavour -> string -> string
+
+(** Fold one unfolded content line per RFC 5545 section 3.1: at most 75 octets
+ per line, continuation lines prefixed with one space, CRLF terminators,
+ never splitting a UTF-8 sequence. The returned string ends with CRLF. *)
+val fold_ics : string -> string