Files
coursebank/src/export/typst/template.rs
T
alexmandClaude c8d6f4a5dd
Pipeline / check (pull_request) Successful in 12m21s
Pipeline / docs (pull_request) Skipped
Pipeline / nightly (pull_request) Skipped
Pipeline / release (pull_request) Skipped
Name Scienting as the copyright holder and contributor
Replace 'Scientific Computing Studio' in the source headers, the Cargo.toml
authors, and the LICENSE contributor line. pixi.toml still has the old
authors line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014zNf4shD4zaCKLucZWPYL9
2026-10-20 00:21:19 -04:00

758 lines
26 KiB
Rust

// SPDX-License-Identifier: Prosperity-3.0.0
// Copyright Scienting
// Source: https://git.scient.ing/education/coursebank
//! Loading a Typst file and splicing generated data into it.
//!
//! The previous version of this module built a document with `format!`. That made
//! every layout decision a code change, which is the wrong place for a decision
//! about where the points label sits. So the tool no longer writes documents; it
//! writes *data into* a document you own.
//!
//! ## Markers
//!
//! A template marks its injection points with Typst line comments, which means a
//! template is a valid `.typ` file that compiles on its own and can be styled
//! without this tool in the loop:
//!
//! ```typst
//! // coursebank:begin questions
//! #render-question((number: 1, stem: [Sample.], options: ()))
//! // coursebank:end questions
//! ```
//!
//! Everything between the `begin` and `end` lines is replaced; the marker lines
//! themselves survive. That has two consequences worth stating plainly:
//!
//! * The bundled templates ship with sample data inside their regions, so
//! `typst compile templates/exam.typ` works before any export has happened.
//! * An exported document is itself a valid template. Re-exporting into a file you
//! have since restyled replaces the questions and leaves your edits alone, which
//! is the difference between a generator you can use twice and one you copy out
//! of once.
//!
//! A bare `// coursebank:questions` with no region also works. It is rewritten
//! into a region on output, so the second export behaves like every subsequent one.
//!
//! ## Slots
//!
//! | Slot | Injected |
//! |:--|:--|
//! | `meta` | `#let cb-meta = (...)` — course, assessment, form, totals |
//! | `questions` | one `#render-question((...))` call per printed item |
//! | `data` | `#let cb-data = (...)` — metadata and questions together |
//!
//! `questions` unrolls the loop with the record's own numbering. `data` hands you
//! the array and gets out of the way. Templates are free to use either, both, or
//! neither; only slots the template actually contains are rendered, so nothing
//! costs anything until it is asked for.
//!
//! ## Lookup order
//!
//! 1. an explicit `--template` path, or `template:` in the render config
//! 2. `templates/<assessment-id>-<variant>.typ`, for a one-off layout
//! 3. `templates/<variant>.typ`, the course's own default
//! 4. the template compiled into this binary
//!
//! `coursebank template dump` writes step 4 into step 3 so that customizing means
//! editing a file rather than reading this documentation.
use std::path::{Path, PathBuf};
use crate::Layout;
use crate::error::{Error, Result};
use super::config::Variant;
/// The prefix every marker comment carries.
const MARKER: &str = "coursebank:";
/// The bundled exam paper template.
const EMBEDDED_EXAM: &str = include_str!("templates/exam.typ");
/// The bundled answer key template.
const EMBEDDED_KEY: &str = include_str!("templates/key.typ");
/// The bundled answer sheet template.
const EMBEDDED_ANSWER_SHEET: &str = include_str!("templates/answer-sheet.typ");
/// The bundled student diagnostic template.
const EMBEDDED_STUDENT_REPORT: &str = include_str!("templates/student-report.typ");
/// The bundled class diagnostic template.
const EMBEDDED_COHORT_REPORT: &str = include_str!("templates/cohort-report.typ");
/// An injection point a template can declare.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum Slot {
/// Course, assessment, form, and totals, as a `#let` binding.
Meta,
/// One call per printed item.
Questions,
/// Metadata and questions together, as a `#let` binding.
Data,
}
impl Slot {
/// Every slot.
pub const ALL: [Slot; 3] = [Slot::Meta, Slot::Questions, Slot::Data];
/// The name used in a marker comment.
pub fn as_str(self) -> &'static str {
match self {
Slot::Meta => "meta",
Slot::Questions => "questions",
Slot::Data => "data",
}
}
/// The slot for a marker name.
fn parse(s: &str) -> Option<Slot> {
Slot::ALL.iter().copied().find(|slot| slot.as_str() == s)
}
/// A comma-separated list of every slot name, for error messages.
fn names() -> String {
Slot::ALL
.iter()
.map(|s| s.as_str())
.collect::<Vec<_>>()
.join(", ")
}
}
/// Where a template came from.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Origin {
/// Compiled into the binary.
Embedded,
/// Read from disk.
File(PathBuf),
}
impl std::fmt::Display for Origin {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Origin::Embedded => f.write_str("built-in"),
Origin::File(path) => write!(f, "{}", path.display()),
}
}
}
/// A loaded template, with its markers already located.
#[derive(Debug, Clone)]
pub struct Template {
/// Which document this template produces.
pub variant: Variant,
/// Where it was loaded from.
pub origin: Origin,
/// The full source.
pub source: String,
/// The regions found, in the order they appear.
regions: Vec<Region>,
}
/// One located marker, as a half-open line range to replace.
#[derive(Debug, Clone)]
struct Region {
/// Which slot.
slot: Slot,
/// The marker line's leading whitespace, reapplied to every injected line so
/// data nested inside a Typst block stays readable.
indent: String,
/// First line index of the marker, which is the `begin` line for a region.
start: usize,
/// One past the `end` line index, or one past a bare point marker.
end: usize,
}
/// The source of the template compiled in for a variant.
///
/// # Arguments
///
/// * `variant` - which document.
///
/// # Returns
///
/// The bundled template source.
pub fn embedded(variant: Variant) -> &'static str {
match variant {
Variant::Exam => EMBEDDED_EXAM,
Variant::Key => EMBEDDED_KEY,
Variant::AnswerSheet => EMBEDDED_ANSWER_SHEET,
Variant::StudentReport => EMBEDDED_STUDENT_REPORT,
Variant::CohortReport => EMBEDDED_COHORT_REPORT,
}
}
/// The directory holding a course's template overrides.
///
/// # Arguments
///
/// * `layout` - the course layout.
///
/// # Returns
///
/// The `templates/` directory, which need not exist.
pub fn dir(layout: &Layout) -> PathBuf {
layout.templates()
}
/// The paths that are consulted for a variant, in order.
///
/// Exposed so `coursebank template list` can show where a template would be found
/// and why, rather than leaving the lookup order to be inferred.
///
/// # Arguments
///
/// * `layout` - the course layout.
/// * `variant` - which document.
/// * `assessment_id` - the assessment being exported, if one is in hand.
///
/// # Returns
///
/// Candidate paths, most specific first.
pub fn candidates(layout: &Layout, variant: Variant, assessment_id: Option<&str>) -> Vec<PathBuf> {
let base = dir(layout);
let mut paths = Vec::new();
if let Some(id) = assessment_id {
paths.push(base.join(format!("{id}-{}", variant.template_file())));
}
paths.push(base.join(variant.template_file()));
paths
}
/// Loads the template for a variant.
///
/// # Arguments
///
/// * `layout` - the course layout.
/// * `variant` - which document.
/// * `assessment_id` - the assessment being exported, if one is in hand.
/// * `explicit` - a path that overrides the lookup entirely.
///
/// # Returns
///
/// The loaded template.
///
/// # Errors
///
/// Returns [`Error::Io`] when an explicitly requested template cannot be read, and
/// [`Error::Invalid`] when the template's markers are malformed. A missing file in
/// the lookup chain is not an error; it just falls through to the next candidate.
pub fn load(
layout: &Layout,
variant: Variant,
assessment_id: Option<&str>,
explicit: Option<&Path>,
) -> Result<Template> {
if let Some(path) = explicit {
let source = std::fs::read_to_string(path).map_err(|e| Error::io(path, e))?;
return Template::parse(variant, Origin::File(path.to_path_buf()), source);
}
for path in candidates(layout, variant, assessment_id) {
if path.is_file() {
let source = std::fs::read_to_string(&path).map_err(|e| Error::io(&path, e))?;
return Template::parse(variant, Origin::File(path), source);
}
}
Template::parse(variant, Origin::Embedded, embedded(variant).to_string())
}
impl Template {
/// Parses a template, locating its markers.
///
/// # Arguments
///
/// * `variant` - which document.
/// * `origin` - where the source came from.
/// * `source` - the template source.
///
/// # Returns
///
/// The parsed template.
///
/// # Errors
///
/// Returns [`Error::Invalid`] listing every marker problem at once: an unknown
/// slot name, a `begin` with no `end`, an `end` with no `begin`, a nested
/// region, or the same slot claimed twice.
pub fn parse(variant: Variant, origin: Origin, source: String) -> Result<Template> {
let lines: Vec<&str> = source.lines().collect();
let mut regions: Vec<Region> = Vec::new();
let mut issues: Vec<String> = Vec::new();
let mut open: Option<(Slot, String, usize)> = None;
for (index, line) in lines.iter().enumerate() {
let Some(marker) = parse_marker(line) else {
continue;
};
let human = index + 1;
match marker.kind {
MarkerKind::Begin => {
if let Some((slot, _, at)) = &open {
issues.push(format!(
"line {human}: `begin {}` opens inside the region `{}` opened on line \
{}; regions cannot nest",
marker.name,
slot.as_str(),
at + 1
));
continue;
}
match Slot::parse(&marker.name) {
Some(slot) => open = Some((slot, marker.indent, index)),
None => issues.push(unknown_slot(human, &marker.name)),
}
}
MarkerKind::End => match open.take() {
Some((slot, indent, start)) => {
if slot.as_str() != marker.name {
issues.push(format!(
"line {human}: `end {}` closes the region `{}` opened on line \
{}",
marker.name,
slot.as_str(),
start + 1
));
}
regions.push(Region {
slot,
indent,
start,
end: index + 1,
});
}
None => issues.push(format!(
"line {human}: `end {}` has no matching `begin`",
marker.name
)),
},
MarkerKind::Point => {
if open.is_some() {
// A point marker inside a region would be overwritten by
// the region's own injection, so it is a mistake worth
// naming rather than silently dropping.
issues.push(format!(
"line {human}: the marker `{}` sits inside an open region and would be \
overwritten",
marker.name
));
continue;
}
match Slot::parse(&marker.name) {
Some(slot) => regions.push(Region {
slot,
indent: marker.indent,
start: index,
end: index + 1,
}),
None => issues.push(unknown_slot(human, &marker.name)),
}
}
}
}
if let Some((slot, _, start)) = open {
issues.push(format!(
"line {}: the region `{}` is never closed; add `// coursebank:end {}`",
start + 1,
slot.as_str(),
slot.as_str()
));
}
for slot in Slot::ALL {
let count = regions.iter().filter(|r| r.slot == slot).count();
if count > 1 {
issues.push(format!(
"the slot `{}` appears {count} times; each slot may be filled once",
slot.as_str()
));
}
}
if !issues.is_empty() {
issues.insert(0, format!("in the Typst template {origin}:"));
return Err(Error::Invalid(issues));
}
Ok(Template {
variant,
origin,
source,
regions,
})
}
/// Whether the template asks for a slot.
///
/// # Arguments
///
/// * `slot` - the slot to look for.
pub fn wants(&self, slot: Slot) -> bool {
self.regions.iter().any(|r| r.slot == slot)
}
/// The slots this template declares, in the order they appear.
pub fn slots(&self) -> Vec<Slot> {
self.regions.iter().map(|r| r.slot).collect()
}
/// Whether the template declares no markers at all.
pub fn is_inert(&self) -> bool {
self.regions.is_empty()
}
/// Renders the template with the given slot bodies.
///
/// # Arguments
///
/// * `bodies` - the Typst source to inject, by slot. A slot the template does
/// not declare is ignored; a slot the template declares but that has no body
/// is emitted as an empty region.
///
/// # Returns
///
/// The finished document. Every injected region is delimited by `begin`/`end`
/// markers, including regions that came from a bare point marker, so the
/// output can be used as the template for the next export.
pub fn render(&self, bodies: &[(Slot, String)]) -> String {
let lines: Vec<&str> = self.source.lines().collect();
let mut out = String::with_capacity(self.source.len() + 4096);
let mut cursor = 0usize;
// `parse` produced regions in source order and rejected overlaps, so a
// single forward pass is enough.
for region in &self.regions {
for line in &lines[cursor..region.start] {
out.push_str(line);
out.push('\n');
}
let body = bodies
.iter()
.find(|(slot, _)| *slot == region.slot)
.map(|(_, body)| body.as_str())
.unwrap_or("");
let name = region.slot.as_str();
let indent = region.indent.as_str();
out.push_str(indent);
out.push_str("// ");
out.push_str(MARKER);
out.push_str("begin ");
out.push_str(name);
out.push('\n');
for line in body.lines() {
if line.trim().is_empty() {
out.push('\n');
} else {
out.push_str(indent);
out.push_str(line);
out.push('\n');
}
}
out.push_str(indent);
out.push_str("// ");
out.push_str(MARKER);
out.push_str("end ");
out.push_str(name);
out.push('\n');
// Everything from the opening marker through the closing one has now
// been rewritten, so resume after it.
cursor = region.end;
}
for line in &lines[cursor..] {
out.push_str(line);
out.push('\n');
}
out
}
}
/// Writes the bundled templates into a directory.
///
/// # Arguments
///
/// * `dir` - the destination directory, created if absent.
/// * `variants` - which templates to write.
/// * `force` - whether to overwrite files that already exist.
///
/// # Returns
///
/// The paths written, and the paths skipped because they already existed.
///
/// # Errors
///
/// Returns [`Error::Io`] when the directory or a file cannot be written.
pub fn dump(dir: &Path, variants: &[Variant], force: bool) -> Result<(Vec<PathBuf>, Vec<PathBuf>)> {
std::fs::create_dir_all(dir).map_err(|e| Error::io(dir, e))?;
let mut written = Vec::new();
let mut skipped = Vec::new();
for variant in variants {
let path = dir.join(variant.template_file());
if path.exists() && !force {
// These are hand-edited files. Clobbering one is the sort of thing you
// discover after you have already lost the edit.
skipped.push(path);
continue;
}
crate::yaml::write_text(&path, embedded(*variant))?;
written.push(path);
}
Ok((written, skipped))
}
/// A marker comment, parsed.
struct Marker {
kind: MarkerKind,
name: String,
indent: String,
}
/// What a marker comment does.
enum MarkerKind {
/// Opens a replaceable region.
Begin,
/// Closes one.
End,
/// A standalone insertion point.
Point,
}
/// Parses one line as a marker comment, if it is one.
///
/// Recognized forms, with any leading whitespace and any run of `/` accepted:
///
/// ```text
/// // coursebank:questions
/// // coursebank:begin questions
/// // coursebank:end questions
/// ```
///
/// `begin`/`end` may also be spelled with a colon (`coursebank:begin:questions`),
/// because that is how people guess it.
fn parse_marker(line: &str) -> Option<Marker> {
let indent: String = line.chars().take_while(|c| c.is_whitespace()).collect();
let rest = line[indent.len()..].trim_end();
let rest = rest
.strip_prefix("//")?
.trim_start_matches('/')
.trim_start();
let rest = rest.strip_prefix(MARKER)?.trim();
if rest.is_empty() {
return None;
}
let (kind, name) = if let Some(name) = strip_word(rest, "begin") {
(MarkerKind::Begin, name)
} else if let Some(name) = strip_word(rest, "end") {
(MarkerKind::End, name)
} else {
(MarkerKind::Point, rest)
};
Some(Marker {
kind,
name: name.trim().to_ascii_lowercase(),
indent,
})
}
/// Strips a leading `begin`/`end` keyword, separated by whitespace or a colon.
fn strip_word<'a>(s: &'a str, word: &str) -> Option<&'a str> {
let rest = s.strip_prefix(word)?;
match rest.chars().next() {
Some(c) if c.is_whitespace() || c == ':' => Some(rest[c.len_utf8()..].trim_start()),
// `begin` alone, with no slot named.
None => Some(""),
// `beginning`, which is a slot name that happens to start with `begin`.
Some(_) => None,
}
}
/// The message for a marker naming a slot that does not exist.
fn unknown_slot(line: usize, name: &str) -> String {
format!(
"line {line}: unknown slot `{name}`; expected one of {}",
Slot::names()
)
}
#[cfg(test)]
mod tests {
use super::*;
fn parse(source: &str) -> Result<Template> {
Template::parse(Variant::Exam, Origin::Embedded, source.to_string())
}
#[test]
fn a_point_marker_is_replaced_and_becomes_a_region() {
// The second export has to behave like every one after it, so a point
// marker is rewritten into a region on the way out.
let template = parse("before\n// coursebank:questions\nafter\n").unwrap();
let out = template.render(&[(Slot::Questions, "#q(1)".to_string())]);
assert!(out.contains("before\n"));
assert!(out.contains("// coursebank:begin questions\n#q(1)\n"));
assert!(out.contains("// coursebank:end questions\n"));
assert!(out.contains("after\n"));
assert!(!out.contains("#q(1)\n#q(1)"));
}
#[test]
fn a_region_replaces_its_body_and_keeps_its_markers() {
let template = parse(
"head\n// coursebank:begin questions\nstale sample data\nmore stale\n// \
coursebank:end questions\ntail\n",
)
.unwrap();
let out = template.render(&[(Slot::Questions, "#q(1)".to_string())]);
assert!(!out.contains("stale"), "old body survived: {out}");
assert!(out.contains("#q(1)"));
assert!(out.contains("head\n"));
assert!(out.contains("tail\n"));
}
#[test]
fn rendering_is_idempotent() {
// Exporting into a file that was itself exported must replace the
// questions and leave the surrounding edits alone. This is the property
// that makes "restyle the output, then re-export" a workable habit.
let template = parse("// coursebank:questions\n").unwrap();
let first = template.render(&[(Slot::Questions, "#q(1)".to_string())]);
let again = parse(&first).unwrap();
let second = again.render(&[(Slot::Questions, "#q(2)".to_string())]);
assert!(second.contains("#q(2)"));
assert!(!second.contains("#q(1)"));
assert_eq!(second.matches("coursebank:begin questions").count(), 1);
assert_eq!(second.matches("coursebank:end questions").count(), 1);
}
#[test]
fn indentation_is_reapplied_to_injected_lines() {
let template = parse("#block[\n // coursebank:questions\n]\n").unwrap();
let out = template.render(&[(Slot::Questions, "#q(\n 1,\n)".to_string())]);
assert!(out.contains(" // coursebank:begin questions"), "{out}");
assert!(out.contains(" #q("), "{out}");
assert!(out.contains(" 1,"), "{out}");
}
#[test]
fn only_declared_slots_are_reported() {
let template = parse("// coursebank:meta\n// coursebank:questions\n").unwrap();
assert!(template.wants(Slot::Meta));
assert!(template.wants(Slot::Questions));
assert!(!template.wants(Slot::Data));
assert_eq!(template.slots(), vec![Slot::Meta, Slot::Questions]);
}
#[test]
fn a_template_with_no_markers_is_reported_as_inert() {
// Not an error: someone may want a fully hand-written paper. But the CLI
// warns, because silently writing a document with no questions in it is
// not a good afternoon.
let template = parse("#set page(paper: \"us-letter\")\n").unwrap();
assert!(template.is_inert());
}
#[test]
fn an_unknown_slot_names_the_valid_ones() {
let err = parse("// coursebank:qustions\n").unwrap_err();
let message = err.to_string();
assert!(message.contains("unknown slot `qustions`"), "{message}");
assert!(message.contains("questions"), "{message}");
}
#[test]
fn unbalanced_regions_are_reported_with_line_numbers() {
let err = parse("a\n// coursebank:begin questions\nb\n").unwrap_err();
assert!(err.to_string().contains("never closed"));
let err = parse("// coursebank:end questions\n").unwrap_err();
assert!(err.to_string().contains("no matching `begin`"));
}
#[test]
fn a_duplicated_slot_is_an_error() {
let err = parse("// coursebank:questions\n// coursebank:questions\n").unwrap_err();
assert!(err.to_string().contains("appears 2 times"));
}
#[test]
fn mismatched_region_names_are_reported() {
let err = parse("// coursebank:begin questions\n// coursebank:end meta\n").unwrap_err();
assert!(err.to_string().contains("closes the region"));
}
#[test]
fn every_problem_is_reported_in_one_pass() {
let err = parse("// coursebank:nope\n// coursebank:end data\n").unwrap_err();
let message = err.to_string();
assert!(message.contains("unknown slot"), "{message}");
assert!(message.contains("no matching `begin`"), "{message}");
}
#[test]
fn marker_spelling_is_forgiving() {
assert!(parse("// coursebank:begin:questions\n// coursebank:end:questions\n").is_ok());
assert!(parse(" // coursebank: questions\n").is_ok());
assert!(parse("/// coursebank:questions\n").is_ok());
assert!(parse("// coursebank:QUESTIONS\n").is_ok());
}
#[test]
fn ordinary_comments_are_left_alone() {
assert!(
parse("// nothing to see\n// coursebank\n")
.unwrap()
.is_inert()
);
// A word that merely starts with `begin` is a slot name, not a keyword.
let err = parse("// coursebank:beginning\n").unwrap_err();
assert!(err.to_string().contains("unknown slot `beginning`"));
}
#[test]
fn a_missing_body_leaves_an_empty_region() {
let template = parse("// coursebank:questions\n").unwrap();
let out = template.render(&[]);
assert!(out.contains("// coursebank:begin questions"));
assert!(out.contains("// coursebank:end questions"));
}
#[test]
fn every_bundled_template_parses_and_declares_slots() {
for variant in Variant::ALL {
let template =
Template::parse(variant, Origin::Embedded, embedded(variant).to_string())
.unwrap_or_else(|e| panic!("bundled {} template: {e}", variant.as_str()));
assert!(
!template.is_inert(),
"the bundled {} template declares no slots",
variant.as_str()
);
}
}
#[test]
fn the_lookup_order_is_most_specific_first() {
let layout = Layout::new("/course");
let paths = candidates(&layout, Variant::Key, Some("exam-2"));
assert_eq!(paths.len(), 2);
assert!(paths[0].ends_with("templates/exam-2-key.typ"));
assert!(paths[1].ends_with("templates/key.typ"));
}
}