Files
coursebank/src/export/typst/payload.rs
T
alexm abae39bd54
Pipeline / check (pull_request) Failing after 12m11s
Pipeline / docs (pull_request) Skipped
Pipeline / nightly (pull_request) Skipped
Pipeline / release (pull_request) Skipped
chore: relicense under Apache-2.0
Replace the Prosperity Public License 3.0.0 with the Apache License 2.0:
LICENSE.md, a new NOTICE.md, the Cargo license field, every SPDX header,
and the README's license and contributing sections.
2026-11-18 18:57:08 -05:00

1240 lines
42 KiB
Rust

// SPDX-License-Identifier: Apache-2.0
// Copyright Scienting
// Source: https://git.scient.ing/education/coursebank
//! The data a template is given.
//!
//! One structure, built once, emitted three ways: as a Typst dictionary for the
//! `meta` and `data` slots, as a sequence of function calls for the `questions`
//! slot, and as JSON for a template that would rather call `json("...")` — which
//! is the shape a hand-written Typst exam usually already has.
//!
//! Because it is built once, the paper, the key, and the answer sheet cannot
//! disagree about what form B looked like. That was already the rule and it still
//! is: option order comes from [`select::option_order`] against the form's
//! recorded seed, never from anything stored, so every export of a form agrees
//! with every other export of that form. A key that disagrees with its paper is
//! discovered by the whole room at once.
//!
//! What does *not* appear here is anything about appearance. There is no `paper`
//! size, no font, no margin. Those were arguments to the old renderer and are now
//! either a `#set` rule in the template or a value under
//! [`RenderConfig::extra`](super::config::RenderConfig::extra).
use std::collections::{BTreeMap, BTreeSet};
use serde::Serialize;
use crate::assessment::{AssessmentFile, Form, Placement, Platform};
use crate::catalog::Catalog;
use crate::error::Result;
use crate::item::{Choice, Item};
use crate::markup;
use crate::select;
use crate::taxonomy::{Format, Level};
use super::config::{RenderConfig, StimulusMode};
use super::value::{self, Value};
/// Everything a template is told about one rendering.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct Payload {
/// Which tool produced this, and when.
pub generator: Generator,
/// Course identity.
pub course: Course,
/// The administration.
pub assessment: Assessment,
/// The form being rendered.
pub form: FormInfo,
/// Counts and sums, so a template does not have to derive them.
pub totals: Totals,
/// Learning objectives and targets referenced by the printed items, by id.
#[serde(skip_serializing_if = "BTreeMap::is_empty")]
pub objectives: BTreeMap<String, Objective>,
/// Shared stimuli, by id. Populated when the render config says stimuli are
/// shared rather than repeated with each item.
#[serde(skip_serializing_if = "BTreeMap::is_empty")]
pub stimuli: BTreeMap<String, Stimulus>,
/// The printed questions, in printed order.
pub questions: Vec<Question>,
/// Recorded numbers that were dropped after administration and are therefore
/// not printed. Worth naming on a key so a grader is not left wondering.
#[serde(skip_serializing_if = "Vec::is_empty")]
pub dropped: Vec<u32>,
/// Whatever the render config's `extra` block held.
#[serde(skip_serializing_if = "BTreeMap::is_empty")]
pub extra: BTreeMap<String, serde_yaml_ng::Value>,
}
/// Provenance, so a printed paper found in a drawer can be traced.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct Generator {
/// The tool name.
pub tool: String,
/// The tool version.
pub version: String,
}
/// Course identity.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct Course {
/// Catalog code.
pub code: String,
/// Full title.
pub title: String,
/// The term the course instance runs in.
pub term: String,
/// Granting institution.
#[serde(skip_serializing_if = "Option::is_none")]
pub institution: Option<String>,
/// Instructors of record.
#[serde(skip_serializing_if = "Vec::is_empty")]
pub instructors: Vec<String>,
/// The filesystem-safe short name.
pub slug: String,
}
/// The administration being rendered.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct Assessment {
/// Stable id.
pub id: String,
/// Human title as printed.
pub title: String,
/// The term this administration belongs to.
pub term: String,
/// What kind of assessment.
pub kind: String,
/// Where it was administered.
pub platform: String,
/// The date as `YYYY-MM-DD`, when recorded.
#[serde(skip_serializing_if = "Option::is_none")]
pub date: Option<String>,
/// The date's parts, so a template can format it however it likes rather than
/// parsing the string back apart.
#[serde(skip_serializing_if = "Option::is_none")]
pub date_parts: Option<DateParts>,
/// Time allowed, in minutes.
#[serde(skip_serializing_if = "Option::is_none")]
pub minutes_allowed: Option<f64>,
/// Instructions printed at the top of the paper.
#[serde(skip_serializing_if = "Option::is_none")]
pub instructions: Option<String>,
/// Instructor notes. Emitted only when the render config reveals rationale.
#[serde(skip_serializing_if = "Option::is_none")]
pub notes: Option<String>,
}
/// A date split into its parts.
#[derive(Debug, Clone, Copy, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct DateParts {
/// Year.
pub year: i32,
/// Month, 1 through 12.
pub month: u32,
/// Day of month.
pub day: u32,
}
/// The form being rendered.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct FormInfo {
/// The form id, e.g. `A`.
pub id: String,
/// The seed that produced this form's permutation.
pub seed: u64,
/// Whether item order was shuffled.
pub shuffle_items: bool,
/// Whether option order was shuffled.
pub shuffle_options: bool,
/// How many forms the record declares. A template usually prints the form
/// label only when there is more than one.
pub count: usize,
}
/// Counts and sums a template would otherwise compute.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct Totals {
/// Printed questions, bonus included.
pub questions: usize,
/// Printed scored questions.
pub scored: usize,
/// Printed bonus questions.
pub bonus: usize,
/// Summed points of the scored questions. This is the number that goes on the
/// cover, and it excludes bonus by definition.
pub points: f64,
/// Summed points of the bonus questions.
pub bonus_points: f64,
/// How many printed scored questions sit at each level, keyed by level code.
pub level_counts: BTreeMap<u8, usize>,
}
/// A learning objective, denormalized for printing.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct Objective {
/// The objective text.
pub text: String,
/// The unit it belongs to.
#[serde(skip_serializing_if = "Option::is_none")]
pub unit: Option<String>,
}
/// A shared stimulus.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct Stimulus {
/// The vignette body.
pub body: String,
/// A caption for the asset.
#[serde(skip_serializing_if = "Option::is_none")]
pub caption: Option<String>,
/// A path to an image or data file, relative to the course root.
#[serde(skip_serializing_if = "Option::is_none")]
pub asset: Option<String>,
}
/// A figure or data file printed with an item.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct Asset {
/// Path relative to the course root.
pub path: String,
/// Alt text.
#[serde(skip_serializing_if = "Option::is_none")]
pub alt: Option<String>,
/// A caption.
#[serde(skip_serializing_if = "Option::is_none")]
pub caption: Option<String>,
}
/// One printed question.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct Question {
/// The number as printed. By default this is the number recorded in the
/// assessment record, not the position on the page, because it is the join key
/// to every grading export and response row.
pub number: u32,
/// The one-based position on the page, which differs from `number` whenever an
/// item has been dropped.
pub position: usize,
/// The item's global id, `bank::item`. Omitted unless the field is enabled.
#[serde(skip_serializing_if = "Option::is_none")]
pub uid: Option<String>,
/// The item's short title.
#[serde(skip_serializing_if = "Option::is_none")]
pub title: Option<String>,
/// Point value.
#[serde(skip_serializing_if = "Option::is_none")]
pub points: Option<f64>,
/// Whether this is scored outside the graded total.
pub bonus: bool,
/// Cognitive level code, 1 through 5.
#[serde(skip_serializing_if = "Option::is_none")]
pub level: Option<u8>,
/// The level's name.
#[serde(skip_serializing_if = "Option::is_none")]
pub level_name: Option<String>,
/// The item's response format.
pub format: String,
/// Whether more than one option is keyed correct, which a paper has to say out
/// loud or students will assume otherwise.
pub multi_select: bool,
/// The prompt, as Typst markup.
pub stem: String,
/// The id of a shared stimulus, when the config keeps stimuli shared.
#[serde(skip_serializing_if = "Option::is_none")]
pub stimulus_id: Option<String>,
/// The stimulus itself, when the config repeats it with each item.
#[serde(skip_serializing_if = "Option::is_none")]
pub stimulus: Option<Stimulus>,
/// The options in printed order.
pub options: Vec<Opt>,
/// The keyed letters *as printed on this form*. Omitted unless the config
/// reveals the key.
#[serde(skip_serializing_if = "Option::is_none")]
pub key: Option<Vec<String>>,
/// Credit awarded to non-keyed letters after administration, by printed
/// letter. Omitted unless the config reveals the key.
#[serde(skip_serializing_if = "Option::is_none")]
pub credit_overrides: Option<BTreeMap<String, f64>>,
/// Learning target ids.
#[serde(skip_serializing_if = "Vec::is_empty")]
pub learning_targets: Vec<String>,
/// Topic tags.
#[serde(skip_serializing_if = "Vec::is_empty")]
pub topics: Vec<String>,
/// Figures and data files.
#[serde(skip_serializing_if = "Vec::is_empty")]
pub assets: Vec<Asset>,
/// Authored predictions, when the field is enabled.
#[serde(skip_serializing_if = "Option::is_none")]
pub design: Option<BTreeMap<String, f64>>,
/// Pooled statistics, when the field is enabled.
#[serde(skip_serializing_if = "Option::is_none")]
pub calibration: Option<BTreeMap<String, f64>>,
}
/// One printed option.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct Opt {
/// The label as printed, generated from the printed position.
pub letter: String,
/// The one-based printed position.
pub position: usize,
/// The letter this option carries in the bank, before shuffling. Omitted
/// unless the field is enabled; it belongs on a review copy, not a paper.
#[serde(skip_serializing_if = "Option::is_none")]
pub source_letter: Option<String>,
/// The option text, as Typst markup.
pub text: String,
/// Whether this option is keyed correct. **Absent entirely** unless the config
/// reveals the key, rather than present and false.
#[serde(skip_serializing_if = "Option::is_none")]
pub correct: Option<bool>,
/// Credit this option earns, from 0 to 1. Absent unless the key is revealed.
#[serde(skip_serializing_if = "Option::is_none")]
pub credit: Option<f64>,
/// Whether a wrong option was judged defensible.
#[serde(skip_serializing_if = "Option::is_none")]
pub defensible: Option<bool>,
/// Instructor rationale. Absent unless the config reveals rationale.
#[serde(skip_serializing_if = "Option::is_none")]
pub explanation: Option<String>,
/// The misconception this distractor targets.
#[serde(skip_serializing_if = "Option::is_none")]
pub misconception: Option<String>,
/// The category of that error.
#[serde(skip_serializing_if = "Option::is_none")]
pub error_type: Option<String>,
/// Text written to be released to students afterwards.
#[serde(skip_serializing_if = "Option::is_none")]
pub feedback: Option<String>,
}
/// Builds the payload for one form.
///
/// # Arguments
///
/// * `catalog` - the loaded course.
/// * `record` - the assessment record.
/// * `form` - the form to render.
/// * `config` - what to include, and how.
///
/// # Returns
///
/// The payload. Dropped placements are excluded from `questions` and listed in
/// `dropped`.
///
/// # Errors
///
/// Returns [`Error::Unresolved`](crate::error::Error::Unresolved) when a placement
/// references an item that is not in the catalog.
pub fn build(
catalog: &Catalog,
record: &AssessmentFile,
form: &Form,
config: &RenderConfig,
) -> Result<Payload> {
let course = &catalog.course;
let default_points = course.policy.points_per_item;
let mut questions = Vec::new();
let mut objective_ids: BTreeSet<String> = BTreeSet::new();
let mut stimulus_ids: BTreeSet<String> = BTreeSet::new();
let mut totals = Totals {
questions: 0,
scored: 0,
bonus: 0,
points: 0.0,
bonus_points: 0.0,
level_counts: BTreeMap::new(),
};
for placement in select::layout(record, form) {
if placement.dropped {
continue;
}
let entry = catalog.require(&placement.item)?;
let item = &entry.item;
let position = questions.len() + 1;
let points = placement
.points
.unwrap_or_else(|| item.points(default_points));
totals.questions += 1;
if placement.bonus {
totals.bonus += 1;
totals.bonus_points += points;
} else {
totals.scored += 1;
totals.points += points;
*totals
.level_counts
.entry(placement_level(&placement, item).code())
.or_insert(0) += 1;
}
let objectives = if placement.learning_targets.is_empty() {
item.learning_targets.clone()
} else {
placement.learning_targets.clone()
};
if config.fields.objectives {
objective_ids.extend(objectives.iter().cloned());
}
let (stimulus_id, stimulus) = match (&item.stimulus, config.stimulus) {
(Some(id), StimulusMode::Inline) => (
None,
course.stimuli.get(id).map(|s| Stimulus {
body: markup::to_typst(&s.body),
caption: s.caption.as_deref().map(markup::to_typst),
asset: s.asset.clone(),
}),
),
(Some(id), StimulusMode::Shared) => {
stimulus_ids.insert(id.clone());
(Some(id.clone()), None)
}
_ => (None, None),
};
let shown = item.administered(&placement.key, &placement.distractors);
let order = select::option_order(form, &placement.item, shown.len());
let options: Vec<Opt> = order
.iter()
.enumerate()
.map(|(position, source_index)| option(shown[*source_index], position, config))
.collect();
let key = if config.reveal.shows_key() {
Some(
options
.iter()
.filter(|o| o.correct == Some(true))
.map(|o| o.letter.clone())
.collect(),
)
} else {
None
};
// Overrides are recorded against the letters the students saw, which are
// this form's printed letters, so they need no remapping.
let has_overrides = !placement.credit_overrides.is_empty();
let credit_overrides = if config.reveal.shows_key() && has_overrides {
Some(placement.credit_overrides.clone())
} else {
None
};
let level = placement_level(&placement, item);
questions.push(Question {
number: if config.number_from_record {
placement.number
} else {
position as u32
},
position,
uid: config.fields.uid.then(|| entry.uid.clone()),
title: config
.fields
.title
.then(|| item.title.clone())
.flatten()
.map(|t| markup::to_typst(&t)),
points: config.fields.points.then_some(points),
bonus: placement.bonus,
level: config.fields.level.then(|| level.code()),
level_name: config.fields.level.then(|| level.name().to_string()),
format: format_token(item.format).to_string(),
multi_select: item.is_multi_key(),
stem: markup::to_typst(&item.stem),
stimulus_id,
stimulus,
options,
key,
credit_overrides,
learning_targets: if config.fields.objectives {
objectives
} else {
Vec::new()
},
topics: if config.fields.topics {
item.topics.clone()
} else {
Vec::new()
},
assets: if config.fields.assets {
item.assets
.iter()
.map(|a| Asset {
path: a.path.clone(),
alt: a.alt.clone(),
caption: a.caption.as_deref().map(markup::to_typst),
})
.collect()
} else {
Vec::new()
},
design: config.fields.design.then(|| design(item)).flatten(),
calibration: config
.fields
.calibration
.then(|| calibration(item))
.flatten(),
});
}
let objectives = objective_ids
.into_iter()
.filter_map(|id| {
(course.is_objective(&id) || course.is_target(&id)).then(|| {
let text = markup::to_typst(&course.text_for(&id));
let unit = course.objective_unit(&id).map(str::to_string);
(id, Objective { text, unit })
})
})
.collect();
let stimuli = stimulus_ids
.into_iter()
.filter_map(|id| {
course.stimuli.get(&id).map(|s| {
(
id,
Stimulus {
body: markup::to_typst(&s.body),
caption: s.caption.as_deref().map(markup::to_typst),
asset: s.asset.clone(),
},
)
})
})
.collect();
Ok(Payload {
generator: Generator {
tool: "coursebank".to_string(),
version: crate::VERSION.to_string(),
},
course: Course {
code: course.course.code.clone(),
title: course.course.title.clone(),
term: course.course.term.clone(),
institution: course.course.institution.clone(),
instructors: course.course.instructors.clone(),
slug: course.course.slug(),
},
assessment: Assessment {
id: record.assessment.id.clone(),
title: record.assessment.title.clone(),
term: record
.assessment
.term
.clone()
.unwrap_or_else(|| course.course.term.clone()),
kind: record.assessment.kind.as_str().to_string(),
platform: platform_token(record.assessment.platform).to_string(),
date: record.assessment.date.map(|d| d.to_string()),
date_parts: record.assessment.date.map(|d| DateParts {
year: d.year,
month: d.month,
day: d.day,
}),
minutes_allowed: record.assessment.minutes_allowed,
instructions: record
.assessment
.instructions
.as_deref()
.map(markup::to_typst),
notes: if config.reveal.shows_rationale() {
record.assessment.notes.as_deref().map(markup::to_typst)
} else {
None
},
},
form: FormInfo {
id: form.id.clone(),
seed: form.seed,
shuffle_items: form.shuffle_items,
shuffle_options: form.shuffle_options,
count: record.forms.len().max(1),
},
totals,
objectives,
stimuli,
questions,
dropped: dropped_numbers(record),
extra: config.extra.clone(),
})
}
/// Builds one printed option.
fn option(choice: &Choice, position: usize, config: &RenderConfig) -> Opt {
let reveal = config.reveal;
Opt {
letter: config.letters.label(position),
position: position + 1,
source_letter: config.fields.source_letters.then(|| choice.id.clone()),
text: markup::to_typst(&choice.text),
// These four are the ones that must be genuinely absent rather than
// present-and-falsy on a student paper.
correct: reveal.shows_key().then_some(choice.correct),
credit: reveal.shows_key().then(|| choice.credit()),
defensible: reveal.shows_key().then_some(choice.defensible),
explanation: reveal
.shows_rationale()
.then(|| choice.explanation.as_deref().map(markup::to_typst))
.flatten(),
misconception: reveal
.shows_rationale()
.then(|| choice.misconception.as_deref().map(markup::to_typst))
.flatten(),
error_type: reveal
.shows_rationale()
.then(|| choice.error_type.map(|e| e.as_str().to_string()))
.flatten(),
feedback: reveal
.shows_rationale()
.then(|| choice.feedback_student.as_deref().map(markup::to_typst))
.flatten(),
}
}
/// The recorded numbers that were dropped after administration.
fn dropped_numbers(record: &AssessmentFile) -> Vec<u32> {
record
.items
.iter()
.filter(|p| p.dropped)
.map(|p| p.number)
.collect()
}
/// The numeric parts of an item's `design` block, if it has any.
fn design(item: &Item) -> Option<BTreeMap<String, f64>> {
let design = item.design.as_ref()?;
let mut map = BTreeMap::new();
if let Some(v) = design.expected_difficulty {
map.insert("expected-difficulty".to_string(), v);
}
if let Some(v) = design.expected_time_seconds {
map.insert("expected-time-seconds".to_string(), v);
}
(!map.is_empty()).then_some(map)
}
/// The numeric parts of an item's pooled statistics, if it has any.
fn calibration(item: &Item) -> Option<BTreeMap<String, f64>> {
let calibration = item.calibration.as_ref()?;
let mut map = BTreeMap::new();
if let Some(v) = calibration.p_value {
map.insert("p-value".to_string(), v);
}
if let Some(v) = calibration.point_biserial {
map.insert("point-biserial".to_string(), v);
}
if let Some(v) = calibration.discrimination_index {
map.insert("discrimination-index".to_string(), v);
}
if let Some(n) = calibration.n_examinees {
map.insert("n-examinees".to_string(), n as f64);
}
(!map.is_empty()).then_some(map)
}
/// The token for a response format.
fn format_token(format: Format) -> &'static str {
format.as_str()
}
/// The token for an administration platform.
fn platform_token(platform: Platform) -> &'static str {
match platform {
Platform::Paper => "paper",
Platform::Canvas => "canvas",
Platform::Other => "other",
}
}
/// Whether a placement contributes a level to the counts.
///
/// Kept as a named helper so the fallback from placement to item is stated once.
fn placement_level(placement: &Placement, item: &Item) -> Level {
placement.level.unwrap_or(item.level)
}
impl Payload {
/// The metadata half of the payload, as a Typst dictionary.
///
/// # Arguments
///
/// * `config` - governs whether markup becomes content blocks or strings.
///
/// # Returns
///
/// A Typst value with everything except `questions`.
pub fn meta_value(&self, config: &RenderConfig) -> Value {
let content = config.content.is_content();
let mut root = Value::dict();
let mut generator = Value::dict();
generator.insert("tool", Value::str(self.generator.tool.as_str()));
generator.insert("version", Value::str(self.generator.version.as_str()));
root.insert("generator", generator);
let mut course = Value::dict();
course.insert("code", Value::str(self.course.code.as_str()));
course.insert("title", Value::str(self.course.title.as_str()));
course.insert("term", Value::str(self.course.term.as_str()));
course.insert("slug", Value::str(self.course.slug.as_str()));
course.insert_some(
"institution",
self.course
.institution
.as_ref()
.map(|s| Value::str(s.as_str())),
);
course.insert(
"instructors",
Value::Array(
self.course
.instructors
.iter()
.map(|s| Value::str(s.as_str()))
.collect(),
),
);
root.insert("course", course);
let a = &self.assessment;
let mut assessment = Value::dict();
assessment.insert("id", Value::str(a.id.as_str()));
assessment.insert("title", Value::str(a.title.as_str()));
assessment.insert("term", Value::str(a.term.as_str()));
assessment.insert("kind", Value::str(a.kind.as_str()));
assessment.insert("platform", Value::str(a.platform.as_str()));
assessment.insert_some("date", a.date.as_ref().map(|s| Value::str(s.as_str())));
assessment.insert_some(
"date-parts",
a.date_parts.map(|d| {
let mut parts = Value::dict();
parts.insert("year", Value::Int(i64::from(d.year)));
parts.insert("month", Value::Int(i64::from(d.month)));
parts.insert("day", Value::Int(i64::from(d.day)));
parts
}),
);
assessment.insert_some("minutes-allowed", a.minutes_allowed.map(Value::Float));
assessment.insert_some(
"instructions",
a.instructions.as_ref().map(|s| markup_value(s, content)),
);
assessment.insert_some("notes", a.notes.as_ref().map(|s| markup_value(s, content)));
root.insert("assessment", assessment);
let mut form = Value::dict();
form.insert("id", Value::str(self.form.id.as_str()));
// Seeds exceed `i64` range in practice, so they travel as strings. A
// template prints them for provenance and never does arithmetic on them.
form.insert("seed", Value::str(self.form.seed.to_string()));
form.insert("shuffle-items", Value::Bool(self.form.shuffle_items));
form.insert("shuffle-options", Value::Bool(self.form.shuffle_options));
form.insert("count", Value::Int(self.form.count as i64));
root.insert("form", form);
let t = &self.totals;
let mut totals = Value::dict();
totals.insert("questions", Value::Int(t.questions as i64));
totals.insert("scored", Value::Int(t.scored as i64));
totals.insert("bonus", Value::Int(t.bonus as i64));
totals.insert("points", Value::Float(t.points));
totals.insert("bonus-points", Value::Float(t.bonus_points));
totals.insert(
"level-counts",
Value::Dict(
t.level_counts
.iter()
.map(|(level, count)| (level.to_string(), Value::Int(*count as i64)))
.collect(),
),
);
root.insert("totals", totals);
if !self.objectives.is_empty() {
root.insert(
"objectives",
Value::Dict(
self.objectives
.iter()
.map(|(id, objective)| {
let mut entry = Value::dict();
entry.insert("text", markup_value(&objective.text, content));
entry.insert_some(
"unit",
objective.unit.as_ref().map(|s| Value::str(s.as_str())),
);
(id.clone(), entry)
})
.collect(),
),
);
}
if !self.stimuli.is_empty() {
root.insert(
"stimuli",
Value::Dict(
self.stimuli
.iter()
.map(|(id, stimulus)| (id.clone(), stimulus_value(stimulus, content)))
.collect(),
),
);
}
root.insert(
"dropped",
Value::Array(
self.dropped
.iter()
.map(|n| Value::Int(i64::from(*n)))
.collect(),
),
);
root.insert(
"extra",
Value::Dict(
self.extra
.iter()
.map(|(key, val)| (key.clone(), value::from_yaml(val, false)))
.collect(),
),
);
root
}
/// One question, as a Typst dictionary.
///
/// # Arguments
///
/// * `index` - which question.
/// * `config` - governs whether markup becomes content blocks or strings.
///
/// # Returns
///
/// The Typst value, or `None` when the index is out of range.
pub fn question_value(&self, index: usize, config: &RenderConfig) -> Option<Value> {
let question = self.questions.get(index)?;
Some(question_value(question, config))
}
/// Every question, as a Typst array.
///
/// # Arguments
///
/// * `config` - governs whether markup becomes content blocks or strings.
pub fn questions_value(&self, config: &RenderConfig) -> Value {
Value::Array(
self.questions
.iter()
.map(|q| question_value(q, config))
.collect(),
)
}
/// The whole payload, as one Typst dictionary.
///
/// # Arguments
///
/// * `config` - governs whether markup becomes content blocks or strings.
pub fn data_value(&self, config: &RenderConfig) -> Value {
let mut root = self.meta_value(config);
root.insert("questions", self.questions_value(config));
root
}
/// The payload as pretty-printed JSON.
///
/// For a template that prefers `json("questions.json")`, which is how a
/// hand-written Typst exam usually already reads its data. Note that JSON has
/// no content type, so a template consuming this has to `eval` the markup
/// fields; setting `content: str` in the render config keeps the Typst path
/// and the JSON path shaped identically.
///
/// # Returns
///
/// The JSON text.
///
/// # Errors
///
/// Returns [`Error::Other`](crate::error::Error::Other) if serialization
/// fails, which would mean a non-finite float reached the payload.
pub fn to_json(&self) -> Result<String> {
serde_json::to_string_pretty(self).map_err(crate::error::Error::other)
}
}
/// Builds one question dictionary.
fn question_value(question: &Question, config: &RenderConfig) -> Value {
let content = config.content.is_content();
let mut root = Value::dict();
root.insert("number", Value::Int(i64::from(question.number)));
root.insert("position", Value::Int(question.position as i64));
root.insert_some("uid", question.uid.as_ref().map(|s| Value::str(s.as_str())));
root.insert_some(
"title",
question.title.as_ref().map(|t| markup_value(t, content)),
);
root.insert_some("points", question.points.map(Value::Float));
root.insert("bonus", Value::Bool(question.bonus));
root.insert_some("level", question.level.map(|l| Value::Int(i64::from(l))));
root.insert_some(
"level-name",
question.level_name.as_ref().map(|s| Value::str(s.as_str())),
);
root.insert("format", Value::str(question.format.as_str()));
root.insert("multi-select", Value::Bool(question.multi_select));
root.insert("stem", markup_value(&question.stem, content));
root.insert_some(
"stimulus-id",
question
.stimulus_id
.as_ref()
.map(|s| Value::str(s.as_str())),
);
root.insert_some(
"stimulus",
question
.stimulus
.as_ref()
.map(|s| stimulus_value(s, content)),
);
root.insert(
"options",
Value::Array(
question
.options
.iter()
.map(|o| option_value(o, content))
.collect(),
),
);
root.insert_some(
"key",
question
.key
.as_ref()
.map(|letters| Value::Array(letters.iter().map(|s| Value::str(s.as_str())).collect())),
);
root.insert_some(
"credit-overrides",
question.credit_overrides.as_ref().map(|map| {
Value::Dict(
map.iter()
.map(|(letter, credit)| (letter.clone(), Value::Float(*credit)))
.collect(),
)
}),
);
if !question.learning_targets.is_empty() {
root.insert(
"learning-targets",
Value::Array(
question
.learning_targets
.iter()
.map(|s| Value::str(s.as_str()))
.collect(),
),
);
}
if !question.topics.is_empty() {
root.insert(
"topics",
Value::Array(
question
.topics
.iter()
.map(|s| Value::str(s.as_str()))
.collect(),
),
);
}
if !question.assets.is_empty() {
root.insert(
"assets",
Value::Array(
question
.assets
.iter()
.map(|a| {
let mut asset = Value::dict();
asset.insert("path", Value::str(a.path.as_str()));
asset.insert_some("alt", a.alt.as_ref().map(|s| Value::str(s.as_str())));
asset.insert_some(
"caption",
a.caption.as_ref().map(|c| markup_value(c, content)),
);
asset
})
.collect(),
),
);
}
root.insert_some("design", question.design.as_ref().map(numeric_map));
root.insert_some(
"calibration",
question.calibration.as_ref().map(numeric_map),
);
root
}
/// Builds one option dictionary.
fn option_value(opt: &Opt, content: bool) -> Value {
let mut root = Value::dict();
root.insert("letter", Value::str(opt.letter.as_str()));
root.insert("position", Value::Int(opt.position as i64));
root.insert_some(
"source-letter",
opt.source_letter.as_ref().map(|s| Value::str(s.as_str())),
);
root.insert("text", markup_value(&opt.text, content));
root.insert_some("correct", opt.correct.map(Value::Bool));
root.insert_some("credit", opt.credit.map(Value::Float));
root.insert_some("defensible", opt.defensible.map(Value::Bool));
root.insert_some(
"explanation",
opt.explanation.as_ref().map(|s| markup_value(s, content)),
);
root.insert_some(
"misconception",
opt.misconception.as_ref().map(|s| markup_value(s, content)),
);
root.insert_some(
"error-type",
opt.error_type.as_ref().map(|s| Value::str(s.as_str())),
);
root.insert_some(
"feedback",
opt.feedback.as_ref().map(|s| markup_value(s, content)),
);
root
}
/// Builds a stimulus dictionary.
fn stimulus_value(stimulus: &Stimulus, content: bool) -> Value {
let mut root = Value::dict();
root.insert("body", markup_value(&stimulus.body, content));
root.insert_some(
"caption",
stimulus.caption.as_ref().map(|c| markup_value(c, content)),
);
root.insert_some(
"asset",
stimulus.asset.as_ref().map(|s| Value::str(s.as_str())),
);
root
}
/// Builds a dictionary of floats.
fn numeric_map(map: &BTreeMap<String, f64>) -> Value {
Value::Dict(
map.iter()
.map(|(key, val)| (key.clone(), Value::Float(*val)))
.collect(),
)
}
/// Emits one markup-bearing field for a diagnostic report.
///
/// The conversion itself lives in [`markup::to_typst`], which is the single
/// entry point for turning authoring markup into Typst: it rewrites inline
/// LaTeX math, routes mhchem through whalogen, and escapes the characters Typst
/// treats specially in content mode. This path used to carry its own copy of
/// the math rewriting, which drifted — the reports escaped nothing outside math
/// and silently disagreed with the exam papers about an unmatched `$`.
///
/// # Arguments
///
/// * `source` - the authoring source.
/// * `content` - whether to emit a content block rather than a quoted string.
/// A string is evaluated by the template with `eval(.., mode: "markup")`, so
/// both modes need the same escaping.
///
/// # Returns
///
/// The value to place in the payload.
pub(crate) fn markup_value(source: &str, content: bool) -> Value {
let source = markup::to_typst(source);
if content {
Value::content(source)
} else {
Value::str(source)
}
}
/// Emits the `questions` slot: one call per question.
///
/// # Arguments
///
/// * `payload` - the built payload.
/// * `config` - supplies the function name and the content mode.
///
/// # Returns
///
/// Typst source. Each question is passed as a single positional dictionary rather
/// than as named arguments, so a template's function signature does not have to
/// change every time a field is enabled or disabled in the config.
pub fn questions_body(payload: &Payload, config: &RenderConfig) -> String {
let mut out = String::new();
for (index, question) in payload.questions.iter().enumerate() {
if index > 0 {
out.push('\n');
}
out.push('#');
out.push_str(&config.question_fn);
out.push('(');
out.push_str(&question_value(question, config).to_typst(0));
out.push_str(")\n");
}
out
}
/// Emits the `meta` slot.
///
/// # Arguments
///
/// * `payload` - the built payload.
/// * `config` - supplies the binding name and the content mode.
pub fn meta_body(payload: &Payload, config: &RenderConfig) -> String {
format!(
"#let {} = {}\n",
config.meta_binding,
payload.meta_value(config).to_typst(0)
)
}
/// Emits the `data` slot.
///
/// # Arguments
///
/// * `payload` - the built payload.
/// * `config` - supplies the binding name and the content mode.
pub fn data_body(payload: &Payload, config: &RenderConfig) -> String {
format!(
"#let {} = {}\n",
config.data_binding,
payload.data_value(config).to_typst(0)
)
}
/// Checks emitted markup for problems a Typst compile would report obscurely.
///
/// Content blocks carry authored markup through verbatim, which is what makes
/// `*bold*` work in a stem. The cost is that an unbalanced `[` in a stem becomes a
/// parse error somewhere downstream of the item that caused it, and the compiler
/// has no way to name the question. Naming it here is much cheaper than finding it
/// there.
///
/// # Arguments
///
/// * `payload` - the built payload.
/// * `config` - only content mode is consulted; string mode cannot have this
/// problem and returns nothing.
///
/// # Returns
///
/// One message per suspect field. Advisory: these are warnings, since a stem may
/// legitimately contain Typst code with brackets this scan cannot follow.
pub fn check(payload: &Payload, config: &RenderConfig) -> Vec<String> {
if !config.content.is_content() {
return Vec::new();
}
let mut issues = Vec::new();
for question in &payload.questions {
let label = format!(
"question {}{}",
question.number,
question
.uid
.as_ref()
.map(|u| format!(" ({u})"))
.unwrap_or_default()
);
if !balanced(&question.stem) {
issues.push(format!("{label}: the stem has unbalanced square brackets"));
}
for opt in &question.options {
if !balanced(&opt.text) {
issues.push(format!(
"{label}, option {}: unbalanced square brackets",
opt.letter
));
}
}
}
issues
}
/// Whether square brackets balance, ignoring escaped ones and raw spans.
fn balanced(source: &str) -> bool {
let mut depth = 0i32;
let mut chars = source.chars().peekable();
let mut in_raw = false;
while let Some(ch) = chars.next() {
match ch {
'\\' => {
// An escaped bracket is literal text, not a delimiter.
chars.next();
}
'`' => in_raw = !in_raw,
'[' if !in_raw => depth += 1,
']' if !in_raw => {
depth -= 1;
if depth < 0 {
return false;
}
}
_ => {}
}
}
depth == 0
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn bracket_balance_ignores_escapes_and_raw_spans() {
assert!(balanced("plain text"));
assert!(balanced("#text(red)[ok]"));
assert!(balanced("an escaped \\[ bracket"));
assert!(balanced("code `a[0]` inline"));
assert!(!balanced("#text(red)[oops"));
assert!(!balanced("closing ] first"));
}
}