From 45bcbde502e07ad73b96039fcbb62471a3c94781 Mon Sep 17 00:00:00 2001
From: Lukasz Kasprzak <lukas@labunix.xyz>
Date: Wed, 19 Aug 2026 13:34:53 +0200
Subject: feat(naming): the language table

Maps strings to strings and nothing else -- no calendars, no dates, no
filesystem. That is what lets every command use it without the kernel
learning about presentation.

Every lookup is total, and a miss returns THE KEY rather than the empty
string. A partial translation is therefore usable from its first line,
and the fully-degraded case is exactly today's output (bare slugs) rather
than a blank page.

--raw is a real identity table, not a special case threaded through every
call site: one value the whole program passes around.

Reuses Overlay_ini's INI reader rather than growing a second one that
would drift in its comment, quoting and trimming rules; parse_sections is
exposed in the .mli for that, with no behaviour change.

Fixes one defect found while running the brief's own tests rather than
transcribing them blind: weekday's internal lookup key is an English
day-name word (month's is already the numeral string), so on a miss it
echoed that word instead of the documented numeral, breaking both the
0=Sunday convention and Lang.raw's own identity contract for weekday.
weekday/month now fall back to string_of_int n directly on a miss
instead of through get's generic echo-the-search-key path; month is
byte-identical since its key already equals string_of_int n.
---
 lib/naming/lang.mli | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)
 create mode 100644 lib/naming/lang.mli

(limited to 'lib/naming/lang.mli')

diff --git a/lib/naming/lang.mli b/lib/naming/lang.mli
new file mode 100644
index 0000000..c4432f6
--- /dev/null
+++ b/lib/naming/lang.mli
@@ -0,0 +1,44 @@
+(** A language table: strings to strings, nothing more.
+
+    Knows nothing about calendars, dates or rites, and never touches the
+    filesystem -- callers hand it text. That is what lets every command use it
+    without the kernel learning about presentation.
+
+    Every lookup is TOTAL. A key with no entry returns THE KEY ITSELF, never the
+    empty string: a partial translation must be usable from its first line, and
+    an untranslated day must still print something a reader can act on. This is
+    also why the pre-naming output (bare slugs) is exactly what an empty table
+    produces -- the degraded case is the old behaviour, not a blank page. *)
+
+type t
+
+(** Parse INI text. Never raises. [Error] on a malformed file or a missing
+    [\[meta\] lang]. *)
+val of_string : string -> (t, string) result
+
+val code : t -> string
+val fallback_code : t -> string option
+
+(** [with_fallback t base] resolves through [t] first, then [base], then the key. *)
+val with_fallback : t -> t -> t
+
+(** The identity table: every lookup returns its key. This is what [--raw] uses,
+    so raw output is one table passed around rather than a special case threaded
+    through every call site. *)
+val raw : t
+
+val celebration : t -> string -> string
+val season : t -> string -> string
+val rank : t -> string -> string
+val colour : t -> string -> string
+val term : t -> string -> string
+
+(** [weekday t n], 0 = Sunday. Out-of-range [n] returns [string_of_int n]. *)
+val weekday : t -> int -> string
+
+(** [month t n], 1 = January. Out-of-range [n] returns [string_of_int n]. *)
+val month : t -> int -> string
+
+(** Every (section-qualified key, value) pair, sorted. Used by [lang --dump] and
+    [lang --check]. Keys are qualified as e.g. ["celebration.ef-epiphany"]. *)
+val keys : t -> (string * string) list
-- 
cgit v1.3