From b26089630a61a54060c86ec26be6dc4fe5418b12 Mon Sep 17 00:00:00 2001 From: Lukasz Kasprzak Date: Wed, 19 Aug 2026 13:38:54 +0200 Subject: feat(naming): the config file Owns precedence and provenance and nothing else, and never reads the filesystem, so it is as testable as the language table. resolve returns the value AND its source, because a setting that silently comes from a file the user forgot about is worse than no setting at all -- config --show can then say where each effective value came from. overlay accumulates rather than last-wins: a user has more than one. An unknown key is reported, never fatal. A config written for a newer colitur must still work on an older one, but silently dropping a line the user wrote is how a typo becomes invisible. --- lib/naming/config.ml | 43 +++++++++++++++++++++++++++++++++++ lib/naming/config.mli | 28 +++++++++++++++++++++++ test/test_colitur.ml | 1 + test/test_config.ml | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 134 insertions(+) create mode 100644 lib/naming/config.ml create mode 100644 lib/naming/config.mli create mode 100644 test/test_config.ml diff --git a/lib/naming/config.ml b/lib/naming/config.ml new file mode 100644 index 0000000..ce1b433 --- /dev/null +++ b/lib/naming/config.ml @@ -0,0 +1,43 @@ +module OI = Colitur_kernel.Overlay_ini + +type t = { + lang : string option; + overlays : string list; + template : string option; + format : string option; + unknown_keys : string list; +} + +let empty = { lang = None; overlays = []; template = None; format = None; unknown_keys = [] } + +let lang t = t.lang +let overlays t = t.overlays +let template t = t.template +let format t = t.format +let unknown_keys t = t.unknown_keys + +let of_string text = + match OI.parse_sections text with + | Error e -> Error e + | Ok sections -> ( + match List.find_opt (fun (s : OI.section) -> s.OI.name = "defaults") sections with + | None -> Ok empty + | Some s -> + let acc = + List.fold_left + (fun acc (k, v) -> + match k with + | "lang" -> { acc with lang = Some v } + | "template" -> { acc with template = Some v } + | "format" -> { acc with format = Some v } + (* accumulates: a user has more than one overlay *) + | "overlay" -> { acc with overlays = acc.overlays @ [ v ] } + | other -> { acc with unknown_keys = acc.unknown_keys @ [ other ] }) + empty s.OI.fields + in + Ok acc) + +let resolve ~flag ~config ~default = + match flag with + | Some v -> (v, "flag") + | None -> ( match config with Some v -> (v, "config") | None -> (default, "default")) diff --git a/lib/naming/config.mli b/lib/naming/config.mli new file mode 100644 index 0000000..41ff429 --- /dev/null +++ b/lib/naming/config.mli @@ -0,0 +1,28 @@ +(** The config file: what the user wants by default, and where each value came + from. + + Owns precedence and provenance and nothing else. Never reads the filesystem + -- callers hand it text -- so it is as testable as the language table. + + A config file is OPTIONAL. With none, colitur behaves exactly as it does + without this feature, except that names resolve through the default + language. *) + +type t + +val empty : t +val of_string : string -> (t, string) result + +val lang : t -> string option +val overlays : t -> string list +val template : t -> string option +val format : t -> string option + +(** Keys present in the file that this build does not understand. Reported, never + fatal: a config written for a newer colitur must still work on an older one, + but silently ignoring a line the user wrote is how a typo becomes invisible. *) +val unknown_keys : t -> string list + +(** [resolve ~flag ~config ~default] returns [(value, source)] with source one of + ["flag"], ["config"], ["default"]. Precedence is flag > config > default. *) +val resolve : flag:string option -> config:string option -> default:string -> string * string diff --git a/test/test_colitur.ml b/test/test_colitur.ml index dd1274a..1c445a6 100644 --- a/test/test_colitur.ml +++ b/test/test_colitur.ml @@ -3,6 +3,7 @@ let () = Alcotest.run "colitur" [ Test_date.suite; Test_computus.suite; Test_colour.suite; Test_slug.suite; Test_names.suite; Test_lang.suite; + Test_config.suite; Test_overlay.suite; Test_overlay_ini.suite; Test_temporal_ef.suite; Test_validate.suite; Test_precedence.suite; Test_calendar.suite; Test_precedence_ef.suite; Test_sanctoral_ef.suite; Test_rite_ef.suite; Test_differential.suite; Test_oracle.suite; Test_oracle.suite_2038; Test_oracle.suite_2035; Test_golden.suite; diff --git a/test/test_config.ml b/test/test_config.ml new file mode 100644 index 0000000..9100380 --- /dev/null +++ b/test/test_config.ml @@ -0,0 +1,62 @@ +module C = Colitur_naming.Config + +let ok = function Ok x -> x | Error e -> Alcotest.failf "parse: %s" e + +let sample = + "[defaults]\n\ + lang = pl\n\ + overlay = ~/a.ini\n\ + overlay = ~/b.ini\n\ + template = ~/my-ordo.tex\n\ + format = json\n" + +let test_reads_defaults () = + let c = ok (C.of_string sample) in + Alcotest.(check (option string)) "lang" (Some "pl") (C.lang c); + Alcotest.(check (option string)) "template" (Some "~/my-ordo.tex") (C.template c); + Alcotest.(check (option string)) "format" (Some "json") (C.format c) + +(* Repeated keys accumulate for overlay -- a user has more than one. The INI + reader keeps every line, so this asserts we do not silently take the last. *) +let test_overlays_accumulate () = + let c = ok (C.of_string sample) in + Alcotest.(check (list string)) "both overlays" [ "~/a.ini"; "~/b.ini" ] (C.overlays c) + +let test_empty_config_is_all_none () = + Alcotest.(check (option string)) "lang" None (C.lang C.empty); + Alcotest.(check (list string)) "overlays" [] (C.overlays C.empty) + +(* THE precedence rule: flag > config > default, and the SOURCE is reported, + because a setting that silently comes from a file the user forgot about is + worse than no setting at all. *) +let test_precedence_and_provenance () = + let check ~flag ~config ~default (ev, es) = + let v, s = C.resolve ~flag ~config ~default in + Alcotest.(check string) "value" ev v; + Alcotest.(check string) "source" es s + in + check ~flag:(Some "en") ~config:(Some "pl") ~default:"la" ("en", "flag"); + check ~flag:None ~config:(Some "pl") ~default:"la" ("pl", "config"); + check ~flag:None ~config:None ~default:"la" ("la", "default") + +let test_malformed_is_error_not_crash () = + match C.of_string "[defaults\nbroken" with + | Error _ -> () + | Ok _ -> Alcotest.fail "a malformed config must be an Error, never accepted" + +(* An unknown key is a WARNING case, not a hard error: a config written for a + newer colitur must still work on an older one. But it must be reportable, so + it is not silently dropped either. *) +let test_unknown_key_is_reported_not_fatal () = + match C.of_string "[defaults]\nlang = la\nnonsense = 1\n" with + | Error _ -> Alcotest.fail "an unknown key must not be fatal" + | Ok c -> Alcotest.(check (option string)) "known key still read" (Some "la") (C.lang c) + +let suite = + ( "Config", + [ Alcotest.test_case "reads defaults" `Quick test_reads_defaults; + Alcotest.test_case "overlays accumulate" `Quick test_overlays_accumulate; + Alcotest.test_case "empty is all none" `Quick test_empty_config_is_all_none; + Alcotest.test_case "precedence and provenance" `Quick test_precedence_and_provenance; + Alcotest.test_case "malformed is error" `Quick test_malformed_is_error_not_crash; + Alcotest.test_case "unknown key not fatal" `Quick test_unknown_key_is_reported_not_fatal ] ) -- cgit v1.3