// 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, /// 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, /// The printed questions, in printed order. pub questions: Vec, /// 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, /// Whatever the render config's `extra` block held. #[serde(skip_serializing_if = "BTreeMap::is_empty")] pub extra: BTreeMap, } /// 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, /// Instructors of record. #[serde(skip_serializing_if = "Vec::is_empty")] pub instructors: Vec, /// 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, /// 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, /// Time allowed, in minutes. #[serde(skip_serializing_if = "Option::is_none")] pub minutes_allowed: Option, /// Instructions printed at the top of the paper. #[serde(skip_serializing_if = "Option::is_none")] pub instructions: Option, /// Instructor notes. Emitted only when the render config reveals rationale. #[serde(skip_serializing_if = "Option::is_none")] pub notes: Option, } /// 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, } /// 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, } /// 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, /// A path to an image or data file, relative to the course root. #[serde(skip_serializing_if = "Option::is_none")] pub asset: Option, } /// 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, /// A caption. #[serde(skip_serializing_if = "Option::is_none")] pub caption: Option, } /// 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, /// The item's short title. #[serde(skip_serializing_if = "Option::is_none")] pub title: Option, /// Point value. #[serde(skip_serializing_if = "Option::is_none")] pub points: Option, /// 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, /// The level's name. #[serde(skip_serializing_if = "Option::is_none")] pub level_name: Option, /// 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, /// The stimulus itself, when the config repeats it with each item. #[serde(skip_serializing_if = "Option::is_none")] pub stimulus: Option, /// The options in printed order. pub options: Vec, /// 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>, /// 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>, /// Learning target ids. #[serde(skip_serializing_if = "Vec::is_empty")] pub learning_targets: Vec, /// Topic tags. #[serde(skip_serializing_if = "Vec::is_empty")] pub topics: Vec, /// Figures and data files. #[serde(skip_serializing_if = "Vec::is_empty")] pub assets: Vec, /// Authored predictions, when the field is enabled. #[serde(skip_serializing_if = "Option::is_none")] pub design: Option>, /// Pooled statistics, when the field is enabled. #[serde(skip_serializing_if = "Option::is_none")] pub calibration: Option>, } /// 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, /// 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, /// Credit this option earns, from 0 to 1. Absent unless the key is revealed. #[serde(skip_serializing_if = "Option::is_none")] pub credit: Option, /// Whether a wrong option was judged defensible. #[serde(skip_serializing_if = "Option::is_none")] pub defensible: Option, /// Instructor rationale. Absent unless the config reveals rationale. #[serde(skip_serializing_if = "Option::is_none")] pub explanation: Option, /// The misconception this distractor targets. #[serde(skip_serializing_if = "Option::is_none")] pub misconception: Option, /// The category of that error. #[serde(skip_serializing_if = "Option::is_none")] pub error_type: Option, /// Text written to be released to students afterwards. #[serde(skip_serializing_if = "Option::is_none")] pub feedback: Option, } /// 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 { let course = &catalog.course; let default_points = course.policy.points_per_item; let mut questions = Vec::new(); let mut objective_ids: BTreeSet = BTreeSet::new(); let mut stimulus_ids: BTreeSet = 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 = 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 { 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> { 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> { 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 { 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 { 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) -> 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 { 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")); } }