ravenous_typst/setup/generation/glossary.typ

210 lines
5.5 KiB
Plaintext

#import "../core/macros.typ" as macros
#import "../core/limits.typ": hunbal
// 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,
scope: macros.bigscope,
mode: mode,
)
}
/// 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) = {
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 -----
let sort_key = ""
for (key, value) in entry {
result.insert(
key,
if key == "custom" and type(value) == dictionary {
let custom = value
let category = custom.at("category", default: none)
if type(category) == str {
custom.insert("category", eval-typst(category, mode: "markup"))
}
custom
} else if type(value) == dictionary
and value.at("typst", default: none) != none {
eval-typst(value.typst)
} else if key == "short" {
if value == none {
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
} else if key == "description" {
if value == none {
none
} else if type(value) == str {
eval-typst(value, mode: "markup")
} else {
value
}
} else {
value
},
)
}
//----- 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(
"Glossary entry `"
+ result.key
+ "` in `"
+ str(file)
+ "` is missing the `short` field",
)
}
if "sort" not in result {
if "long" in result {
result.insert("sort", result.long)
} else {
result.insert("sort", sort_key)
}
}
let custom = result.at("custom", default: none)
if (
custom != none
and custom.at("resisted_by", default: none) != none
and custom.at("difficulty", default: none) == none
) {
panic(
"Glossary entry `"
+ result.key
+ "` in `"
+ str(file)
+ "` defines `custom.resisted_by` without `custom.difficulty`",
)
}
// if "long" not in result {
// result.insert("long", "")
// }
normalized.push(result)
}
normalized
}
/// 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 {
files = (files,)
}
for file in files {
let new = read-glossary-entries(file)
for entry in new {
let previous_file = key_sources.at(entry.key, default: none)
if previous_file != none {
panic(
"Duplicate glossary key `"
+ entry.key
+ "` in `"
+ str(file)
+ "`; first defined in `"
+ previous_file
+ "`",
)
}
key_sources.insert(entry.key, str(file))
entries.push(entry)
}
}
entries
}
//----- Load all project glossaries -----
#let glossary = read-glossary((
"/data/src/glossaries/general.yml",
"/data/src/glossaries/classes.yml",
"/data/src/glossaries/alterations.yml",
"/data/src/glossaries/creature.yml",
"/data/src/glossaries/terms.yml",
"/data/src/glossaries/folklore.yml",
"/data/src/glossaries/rules.yml",
"/data/src/glossaries/character.yml",
"/data/src/glossaries/elements.yml",
))