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.
1240 lines
42 KiB
Rust
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"));
|
|
}
|
|
}
|