diff --git a/setup/glossary.typ b/setup/glossary.typ index 5915d5c..8146f48 100644 --- a/setup/glossary.typ +++ b/setup/glossary.typ @@ -1,6 +1,19 @@ #import "macros.typ" as macros #import "limits.typ": hunbal -// ----- Safely evaluate trusted Typst expressions from data files passing needed macros ----- + +// Glossary loading helpers. +// +// Glossary files are YAML arrays whose items must contain unique `key` and +// non-null `short` fields. Empty YAML files are treated like empty arrays. +// Values wrapped in a `typst` mapping and string-valued `short` and +// `description` fields are evaluated as Typst, so glossary files must be +// trusted input. + +/// Evaluates a trusted Typst expression with the project's glossary macros in +/// scope. +/// +/// `mode` accepts the same values as Typst's `eval` function and defaults to +/// code mode. #let eval-typst(value, mode: "code") = { eval( value, @@ -9,9 +22,34 @@ ) } -// ----- Read and normalize glossary entries from a YAML file ----- +/// Reads and normalizes the entries in one YAML glossary file. +/// +/// An empty file (which Typst decodes as `none`) produces an empty array. +/// Non-empty files must contain an array of dictionaries. Every dictionary +/// requires a string `key` and a non-null `short` value. Missing `sort` values +/// fall back to `long`, or to the original string value of `short`. #let read-glossary-entries(file) = { - yaml(file).map(entry => { + let imported = yaml(file) + + if imported == none { + return () + } + if type(imported) != array { + panic("Glossary file `" + str(file) + "` must contain a YAML array") + } + + let normalized = () + for (index, entry) in imported.enumerate() { + if type(entry) != dictionary { + panic( + "Glossary entry " + + str(index + 1) + + " in `" + + str(file) + + "` must be a dictionary", + ) + } + let result = (:) // ----- Convert each YAML field to its Typst representation ----- @@ -24,10 +62,18 @@ eval-typst(value.typst) } else if key == "short" { if value == none { - panic("Short key cannot be null") + panic( + "Glossary entry " + + str(index + 1) + + " in `" + + str(file) + + "` has a null `short` field", + ) } else if type(value) == str { sort_key = value eval(value, mode: "markup") + } else { + value } } else if key == "long" { value @@ -46,8 +92,32 @@ } // ----- Fill in missing optional fields ----- + if "key" not in result { + panic( + "Glossary entry " + + str(index + 1) + + " in `" + + str(file) + + "` is missing the `key` field", + ) + } + if type(result.key) != str or result.key == "" { + panic( + "Glossary entry " + + str(index + 1) + + " in `" + + str(file) + + "` must have a non-empty string `key`", + ) + } if "short" not in result { - panic("Missing key short for:", result) + panic( + "Glossary entry `" + + result.key + + "` in `" + + str(file) + + "` is missing the `short` field", + ) } if "sort" not in result { if "long" in result { @@ -59,13 +129,20 @@ // if "long" not in result { // result.insert("long", "") // } - result - }) + normalized.push(result) + } + + normalized } -// ----- Load glossary entries from one or more YAML files ----- +/// Loads glossary entries from one file or an array of files. +/// +/// Files are combined in the supplied order. Empty files are ignored. A +/// duplicate `key`, whether it occurs in one file or across multiple files, +/// causes an error naming both sources. #let read-glossary(files) = { let entries = () + let key_sources = (:) // ----- Normalize a single file into an array ----- if type(files) != array { @@ -75,18 +152,23 @@ for file in files { let new = read-glossary-entries(file) - // ----- Reject duplicate glossary keys ----- for entry in new { - let duplicate = entries.find(e => e.key == entry.key) - - if duplicate != none { + let previous_file = key_sources.at(entry.key, default: none) + if previous_file != none { panic( - "Found duplicate key `" + entry.key + "` in files `" + file + "`", + "Duplicate glossary key `" + + entry.key + + "` in `" + + str(file) + + "`; first defined in `" + + previous_file + + "`", ) } - } - entries += new + key_sources.insert(entry.key, str(file)) + entries.push(entry) + } } entries @@ -99,7 +181,7 @@ "../data/src/glossaries/alterations.yml", "../data/src/glossaries/terms.yml", "../data/src/glossaries/folklore.yml", - // "../data/src/glossaries/rules.yml", - // "../data/src/glossaries/character.yml", + "../data/src/glossaries/rules.yml", + "../data/src/glossaries/character.yml", "../data/src/glossaries/elements.yml", ))