feat: initial package draft
This commit is contained in:
@@ -0,0 +1,686 @@
|
||||
//! Exporting an assessment as a Canvas-importable QTI 1.2 package.
|
||||
//!
|
||||
//! QTI 1.2 is a fussy, half-abandoned standard, and Canvas reads a particular
|
||||
//! dialect of it. Two details are worth recording because they are easy to get
|
||||
//! wrong and produce silent misbehavior rather than an import error.
|
||||
//!
|
||||
//! First, question HTML lives inside `<mattext texttype="text/html">` as
|
||||
//! character data, which means it is escaped once on the way in and unescaped
|
||||
//! once by Canvas. So `→` is written as `&rarr;`. Skipping that step
|
||||
//! produces XML that parses and renders as literal `→` to students.
|
||||
//!
|
||||
//! Second, identifiers must be stable. Canvas keys re-imports and question banks
|
||||
//! off them, so a package regenerated after a typo fix should carry the same ids
|
||||
//! as the original. Every id here is derived by hashing the assessment id
|
||||
//! together with the item's global id, never from a clock or a counter.
|
||||
//!
|
||||
//! Option order comes from the form, so exporting form A and form B of the same
|
||||
//! assessment gives two packages that ask the same questions in different orders,
|
||||
//! and the answer keys are guaranteed to agree with what was printed.
|
||||
|
||||
use crate::assessment::{AssessmentFile, Form, ScoringPolicy};
|
||||
use crate::catalog::Catalog;
|
||||
use crate::error::{Error, Result};
|
||||
use crate::hash::{hex, sha256};
|
||||
use crate::item::Item;
|
||||
use crate::markup;
|
||||
use crate::select;
|
||||
use crate::taxonomy::Format;
|
||||
use crate::zipfile::ZipBuilder;
|
||||
|
||||
/// The QTI 1.2 namespace.
|
||||
const QTI_NS: &str = "http://www.imsglobal.org/xsd/ims_qtiasiv1p2";
|
||||
/// The schema location Canvas expects alongside it.
|
||||
const QTI_SCHEMA: &str = "http://www.imsglobal.org/xsd/ims_qtiasiv1p2 \
|
||||
http://www.imsglobal.org/xsd/ims_qtiasiv1p2p1.xsd";
|
||||
/// The XML Schema instance namespace.
|
||||
const XSI_NS: &str = "http://www.w3.org/2001/XMLSchema-instance";
|
||||
/// The IMS content packaging namespace.
|
||||
const IMSCP_NS: &str = "http://www.imsglobal.org/xsd/imscp_v1p1";
|
||||
/// The IMS metadata namespace.
|
||||
const IMSMD_NS: &str = "http://www.imsglobal.org/xsd/imsmd_v1p2";
|
||||
/// The content packaging schema location.
|
||||
const IMSCP_SCHEMA: &str = "http://www.imsglobal.org/xsd/imscp_v1p1 imscp_v1p1.xsd \
|
||||
http://www.imsglobal.org/xsd/imsmd_v1p2 imsmd_v1p2p2.xsd";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// A very small XML tree
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// One XML element.
|
||||
#[derive(Debug, Clone)]
|
||||
struct Node {
|
||||
tag: String,
|
||||
attrs: Vec<(String, String)>,
|
||||
text: Option<String>,
|
||||
children: Vec<Node>,
|
||||
}
|
||||
|
||||
impl Node {
|
||||
/// Creates an element with no attributes, text, or children.
|
||||
fn new(tag: &str) -> Node {
|
||||
Node {
|
||||
tag: tag.to_string(),
|
||||
attrs: Vec::new(),
|
||||
text: None,
|
||||
children: Vec::new(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Adds an attribute, returning self for chaining.
|
||||
fn attr(mut self, k: &str, v: impl Into<String>) -> Node {
|
||||
self.attrs.push((k.to_string(), v.into()));
|
||||
self
|
||||
}
|
||||
|
||||
/// Sets the element text, returning self for chaining.
|
||||
fn text(mut self, t: impl Into<String>) -> Node {
|
||||
self.text = Some(t.into());
|
||||
self
|
||||
}
|
||||
|
||||
/// Appends a child, returning self for chaining.
|
||||
fn child(mut self, c: Node) -> Node {
|
||||
self.children.push(c);
|
||||
self
|
||||
}
|
||||
|
||||
/// Appends several children, returning self for chaining.
|
||||
fn children(mut self, cs: Vec<Node>) -> Node {
|
||||
self.children.extend(cs);
|
||||
self
|
||||
}
|
||||
|
||||
/// Renders the element and its subtree.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `depth` - the indentation level.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// Indented XML, newline-terminated.
|
||||
fn render(&self, depth: usize) -> String {
|
||||
let pad = " ".repeat(depth);
|
||||
let mut attrs = String::new();
|
||||
for (k, v) in &self.attrs {
|
||||
attrs.push_str(&format!(" {k}=\"{}\"", escape_attr(v)));
|
||||
}
|
||||
|
||||
if self.children.is_empty() {
|
||||
match &self.text {
|
||||
None => format!("{pad}<{}{attrs}/>\n", self.tag),
|
||||
Some(t) => format!(
|
||||
"{pad}<{}{attrs}>{}</{}>\n",
|
||||
self.tag,
|
||||
escape_text(t),
|
||||
self.tag
|
||||
),
|
||||
}
|
||||
} else {
|
||||
let mut out = format!("{pad}<{}{attrs}>\n", self.tag);
|
||||
if let Some(t) = &self.text {
|
||||
out.push_str(&format!("{pad} {}\n", escape_text(t)));
|
||||
}
|
||||
for c in &self.children {
|
||||
out.push_str(&c.render(depth + 1));
|
||||
}
|
||||
out.push_str(&format!("{pad}</{}>\n", self.tag));
|
||||
out
|
||||
}
|
||||
}
|
||||
|
||||
/// Renders a complete document with an XML declaration.
|
||||
fn document(&self) -> String {
|
||||
format!(
|
||||
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n{}",
|
||||
self.render(0)
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
/// Escapes text content.
|
||||
fn escape_text(s: &str) -> String {
|
||||
s.replace('&', "&")
|
||||
.replace('<', "<")
|
||||
.replace('>', ">")
|
||||
}
|
||||
|
||||
/// Escapes an attribute value.
|
||||
fn escape_attr(s: &str) -> String {
|
||||
escape_text(s).replace('"', """)
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Package construction
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Options for a QTI export.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct QtiOptions {
|
||||
/// Which form's option order to use.
|
||||
pub form: Form,
|
||||
/// Whether to include per-option feedback. Turn it off for a practice quiz
|
||||
/// you intend to reuse as a graded one, since Canvas shows this feedback
|
||||
/// immediately.
|
||||
pub include_feedback: bool,
|
||||
/// Whether to let Canvas shuffle answers on top of the form's own order.
|
||||
pub shuffle_in_canvas: bool,
|
||||
/// Maximum attempts; `-1` for unlimited.
|
||||
pub attempts: i64,
|
||||
/// How repeated attempts are scored.
|
||||
pub scoring_policy: ScoringPolicy,
|
||||
}
|
||||
|
||||
impl Default for QtiOptions {
|
||||
fn default() -> QtiOptions {
|
||||
QtiOptions {
|
||||
form: Form {
|
||||
id: "A".to_string(),
|
||||
seed: 0,
|
||||
shuffle_items: false,
|
||||
shuffle_options: false,
|
||||
},
|
||||
include_feedback: true,
|
||||
shuffle_in_canvas: false,
|
||||
attempts: 1,
|
||||
scoring_policy: ScoringPolicy::KeepHighest,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// A rendered QTI package, ready to write.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct Package {
|
||||
/// The name of the quiz XML file inside the archive.
|
||||
pub quiz_filename: String,
|
||||
/// The quiz XML.
|
||||
pub quiz_xml: String,
|
||||
/// The manifest XML.
|
||||
pub manifest_xml: String,
|
||||
}
|
||||
|
||||
impl Package {
|
||||
/// Writes the package as a Canvas-importable zip.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `path` - the destination `.zip` path.
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// Returns [`Error::Io`] on a write failure.
|
||||
pub fn write_zip(&self, path: &std::path::Path) -> Result<()> {
|
||||
let mut z = ZipBuilder::new();
|
||||
// Canvas only recognizes the archive as QTI when the manifest sits at the
|
||||
// root rather than inside a directory.
|
||||
z.add_text("imsmanifest.xml", &self.manifest_xml);
|
||||
z.add_text(&self.quiz_filename, &self.quiz_xml);
|
||||
z.write_to(path)
|
||||
}
|
||||
}
|
||||
|
||||
/// Builds a QTI package for an assessment.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `catalog` - the loaded course, for resolving items.
|
||||
/// * `record` - the assessment record.
|
||||
/// * `opts` - export options.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// The rendered package.
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// Returns [`Error::Unresolved`] when a placement references a missing item, and
|
||||
/// [`Error::Invalid`] when an item cannot be represented in QTI, such as one with
|
||||
/// no keyed option.
|
||||
pub fn build(catalog: &Catalog, record: &AssessmentFile, opts: &QtiOptions) -> Result<Package> {
|
||||
let assessment_id = qti_id(&format!("{}/assessment", record.assessment.id));
|
||||
let default_points = catalog.course.policy.points_per_item;
|
||||
|
||||
let mut problems = Vec::new();
|
||||
let mut items = Vec::new();
|
||||
|
||||
for placement in select::layout(record, &opts.form) {
|
||||
let entry = catalog.require(&placement.item)?;
|
||||
let item = &entry.item;
|
||||
if item.key_indices().is_empty() {
|
||||
problems.push(format!(
|
||||
"question {} ({}) has no keyed option, so Canvas cannot score it",
|
||||
placement.number, placement.item
|
||||
));
|
||||
continue;
|
||||
}
|
||||
let points = placement
|
||||
.points
|
||||
.unwrap_or_else(|| item.points(default_points));
|
||||
items.push(build_item(
|
||||
&record.assessment.id,
|
||||
&placement.item,
|
||||
item,
|
||||
points,
|
||||
opts,
|
||||
));
|
||||
}
|
||||
|
||||
if !problems.is_empty() {
|
||||
return Err(Error::Invalid(problems));
|
||||
}
|
||||
|
||||
let metadata = vec![
|
||||
metadata_field("cc_maxattempts", &opts.attempts.to_string()),
|
||||
metadata_field("cc_quiz_scoring_policy", opts.scoring_policy.as_str()),
|
||||
metadata_field(
|
||||
"cc_shuffle_answers",
|
||||
if opts.shuffle_in_canvas {
|
||||
"true"
|
||||
} else {
|
||||
"false"
|
||||
},
|
||||
),
|
||||
];
|
||||
|
||||
let title = if record.forms.len() > 1 {
|
||||
format!("{} (form {})", record.assessment.title, opts.form.id)
|
||||
} else {
|
||||
record.assessment.title.clone()
|
||||
};
|
||||
|
||||
let assessment = Node::new("assessment")
|
||||
.attr("ident", assessment_id.clone())
|
||||
.attr("title", title.clone())
|
||||
.child(Node::new("qtimetadata").children(metadata))
|
||||
.child(
|
||||
Node::new("section")
|
||||
.attr("ident", "root_section")
|
||||
.children(items),
|
||||
);
|
||||
|
||||
let root = Node::new("questestinterop")
|
||||
.attr("xmlns", QTI_NS)
|
||||
.attr("xmlns:xsi", XSI_NS)
|
||||
.attr("xsi:schemaLocation", QTI_SCHEMA)
|
||||
.child(assessment);
|
||||
|
||||
let quiz_filename = format!("{}.xml", slug_filename(&record.assessment.id));
|
||||
let manifest = build_manifest(
|
||||
&quiz_filename,
|
||||
&assessment_id,
|
||||
&title,
|
||||
&record.assessment.id,
|
||||
);
|
||||
|
||||
Ok(Package {
|
||||
quiz_filename,
|
||||
quiz_xml: root.document(),
|
||||
manifest_xml: manifest.document(),
|
||||
})
|
||||
}
|
||||
|
||||
/// Builds one `<item>` element.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `assessment_id` - salts the generated ids.
|
||||
/// * `uid` - the item's global id.
|
||||
/// * `item` - the item.
|
||||
/// * `points` - points as administered.
|
||||
/// * `opts` - export options.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// The element.
|
||||
fn build_item(assessment_id: &str, uid: &str, item: &Item, points: f64, opts: &QtiOptions) -> Node {
|
||||
let order = select::option_order(&opts.form, uid, item.options.len());
|
||||
let ordered: Vec<&crate::item::Choice> = order.iter().map(|i| &item.options[*i]).collect();
|
||||
|
||||
// Option identifiers are numeric, mirroring Canvas's own exports, and are
|
||||
// derived from the item id so they survive regeneration.
|
||||
let opt_ids: Vec<String> = ordered
|
||||
.iter()
|
||||
.map(|o| short_id(&format!("{assessment_id}/{uid}/{}", o.id)))
|
||||
.collect();
|
||||
|
||||
let item_meta = Node::new("itemmetadata").child(Node::new("qtimetadata").children(vec![
|
||||
metadata_field("question_type", item.format.qti_type()),
|
||||
metadata_field("points_possible", &format!("{points:.2}")),
|
||||
metadata_field("original_answer_ids", &opt_ids.join(",")),
|
||||
metadata_field("assessment_question_identifierref", &qti_id(uid)),
|
||||
]));
|
||||
|
||||
let cardinality = if item.format == Format::MultipleResponse {
|
||||
"Multiple"
|
||||
} else {
|
||||
"Single"
|
||||
};
|
||||
|
||||
let labels: Vec<Node> = ordered
|
||||
.iter()
|
||||
.zip(opt_ids.iter())
|
||||
.map(|(o, id)| {
|
||||
Node::new("response_label")
|
||||
.attr("ident", id.clone())
|
||||
.child(mattext(&markup::to_html(&o.text)))
|
||||
})
|
||||
.collect();
|
||||
|
||||
let presentation = Node::new("presentation")
|
||||
.child(mattext(&format!(
|
||||
"<div>{}</div>",
|
||||
markup::to_html(&item.stem)
|
||||
)))
|
||||
.child(
|
||||
Node::new("response_lid")
|
||||
.attr("ident", "response1")
|
||||
.attr("rcardinality", cardinality)
|
||||
.child(Node::new("render_choice").children(labels)),
|
||||
);
|
||||
|
||||
// --- response processing ---
|
||||
let mut resprocessing = Node::new("resprocessing").child(
|
||||
Node::new("outcomes").child(
|
||||
Node::new("decvar")
|
||||
.attr("maxvalue", "100")
|
||||
.attr("minvalue", "0")
|
||||
.attr("varname", "SCORE")
|
||||
.attr("vartype", "Decimal"),
|
||||
),
|
||||
);
|
||||
|
||||
// A pass-through condition per option, so choosing anything triggers its
|
||||
// feedback. `continue="Yes"` is what allows scoring to be evaluated after.
|
||||
if opts.include_feedback {
|
||||
for (o, id) in ordered.iter().zip(opt_ids.iter()) {
|
||||
if o.student_text().is_none() {
|
||||
continue;
|
||||
}
|
||||
resprocessing = resprocessing.child(
|
||||
Node::new("respcondition")
|
||||
.attr("continue", "Yes")
|
||||
.child(
|
||||
Node::new("conditionvar").child(
|
||||
Node::new("varequal")
|
||||
.attr("respident", "response1")
|
||||
.text(id.clone()),
|
||||
),
|
||||
)
|
||||
.child(
|
||||
Node::new("displayfeedback")
|
||||
.attr("feedbacktype", "Response")
|
||||
.attr("linkrefid", format!("{id}_fb")),
|
||||
),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
let correct: Vec<&String> = ordered
|
||||
.iter()
|
||||
.zip(opt_ids.iter())
|
||||
.filter(|(o, _)| o.correct)
|
||||
.map(|(_, id)| id)
|
||||
.collect();
|
||||
let incorrect: Vec<&String> = ordered
|
||||
.iter()
|
||||
.zip(opt_ids.iter())
|
||||
.filter(|(o, _)| !o.correct)
|
||||
.map(|(_, id)| id)
|
||||
.collect();
|
||||
|
||||
let condition = if item.format == Format::MultipleResponse {
|
||||
// Full credit only for the exact set: every keyed option chosen and no
|
||||
// unkeyed one. Without the negations, checking every box scores 100.
|
||||
let mut and = Node::new("and");
|
||||
for id in &correct {
|
||||
and = and.child(
|
||||
Node::new("varequal")
|
||||
.attr("respident", "response1")
|
||||
.text((*id).clone()),
|
||||
);
|
||||
}
|
||||
for id in &incorrect {
|
||||
and = and.child(
|
||||
Node::new("not").child(
|
||||
Node::new("varequal")
|
||||
.attr("respident", "response1")
|
||||
.text((*id).clone()),
|
||||
),
|
||||
);
|
||||
}
|
||||
Node::new("conditionvar").child(and)
|
||||
} else {
|
||||
Node::new("conditionvar").child(
|
||||
Node::new("varequal")
|
||||
.attr("respident", "response1")
|
||||
.text(correct.first().map(|s| (*s).clone()).unwrap_or_default()),
|
||||
)
|
||||
};
|
||||
|
||||
resprocessing = resprocessing.child(
|
||||
Node::new("respcondition")
|
||||
.attr("continue", "No")
|
||||
.child(condition)
|
||||
.child(
|
||||
Node::new("setvar")
|
||||
.attr("action", "Set")
|
||||
.attr("varname", "SCORE")
|
||||
.text("100"),
|
||||
),
|
||||
);
|
||||
|
||||
let mut node = Node::new("item")
|
||||
.attr("ident", qti_id(&format!("{assessment_id}/{uid}")))
|
||||
.attr("title", item.display_title())
|
||||
.child(item_meta)
|
||||
.child(presentation)
|
||||
.child(resprocessing);
|
||||
|
||||
if opts.include_feedback {
|
||||
for (o, id) in ordered.iter().zip(opt_ids.iter()) {
|
||||
if let Some(text) = o.student_text() {
|
||||
node = node.child(
|
||||
Node::new("itemfeedback")
|
||||
.attr("ident", format!("{id}_fb"))
|
||||
.child(
|
||||
Node::new("flow_mat")
|
||||
.child(mattext(&format!("<div>{}</div>", markup::to_html(text)))),
|
||||
),
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
node
|
||||
}
|
||||
|
||||
/// A `<material><mattext texttype="text/html">` pair.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `html` - the HTML fragment, which is escaped on the way in.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// The element.
|
||||
fn mattext(html: &str) -> Node {
|
||||
Node::new("material").child(
|
||||
Node::new("mattext")
|
||||
.attr("texttype", "text/html")
|
||||
.text(html),
|
||||
)
|
||||
}
|
||||
|
||||
/// A `<qtimetadatafield>` pair.
|
||||
fn metadata_field(label: &str, entry: &str) -> Node {
|
||||
Node::new("qtimetadatafield")
|
||||
.child(Node::new("fieldlabel").text(label))
|
||||
.child(Node::new("fieldentry").text(entry))
|
||||
}
|
||||
|
||||
/// Builds the IMS content package manifest.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `quiz_filename` - the quiz XML file name.
|
||||
/// * `assessment_id` - the assessment identifier, reused as the resource id.
|
||||
/// * `title` - the human title.
|
||||
/// * `salt` - salts the manifest identifier.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// The manifest element.
|
||||
fn build_manifest(quiz_filename: &str, assessment_id: &str, title: &str, salt: &str) -> Node {
|
||||
let lom = Node::new("imsmd:lom").child(
|
||||
Node::new("imsmd:general").child(
|
||||
Node::new("imsmd:title").child(
|
||||
Node::new("imsmd:langstring")
|
||||
.attr("xml:lang", "en-US")
|
||||
.text(title),
|
||||
),
|
||||
),
|
||||
);
|
||||
|
||||
Node::new("manifest")
|
||||
.attr("identifier", format!("man{}", qti_id(salt)))
|
||||
.attr("xmlns", IMSCP_NS)
|
||||
.attr("xmlns:imsmd", IMSMD_NS)
|
||||
.attr("xmlns:xsi", XSI_NS)
|
||||
.attr("xsi:schemaLocation", IMSCP_SCHEMA)
|
||||
.child(
|
||||
Node::new("metadata")
|
||||
.child(Node::new("schema").text("IMS Content"))
|
||||
.child(Node::new("schemaversion").text("1.1.3"))
|
||||
.child(lom),
|
||||
)
|
||||
.child(
|
||||
Node::new("organizations").attr("default", "root").child(
|
||||
Node::new("organization")
|
||||
.attr("identifier", "root")
|
||||
.attr("structure", "rooted"),
|
||||
),
|
||||
)
|
||||
.child(
|
||||
Node::new("resources").child(
|
||||
Node::new("resource")
|
||||
.attr("identifier", assessment_id)
|
||||
.attr("type", "imsqti_xmlv1p2")
|
||||
.attr("href", quiz_filename)
|
||||
.child(Node::new("file").attr("href", quiz_filename)),
|
||||
),
|
||||
)
|
||||
}
|
||||
|
||||
/// A deterministic QTI identifier: `g` followed by 32 hex characters.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `key` - the stable string to derive from.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// The identifier.
|
||||
fn qti_id(key: &str) -> String {
|
||||
let digest = hex(&sha256(key.as_bytes()));
|
||||
format!("g{}", &digest[..32])
|
||||
}
|
||||
|
||||
/// A deterministic short numeric identifier, as Canvas uses for answers.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `key` - the stable string to derive from.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// A four-digit numeric string.
|
||||
fn short_id(key: &str) -> String {
|
||||
let d = sha256(key.as_bytes());
|
||||
let n = u32::from_be_bytes([d[0], d[1], d[2], d[3]]);
|
||||
// 1000..9999 keeps the width fixed, which some Canvas importers prefer.
|
||||
format!("{}", 1000 + (n % 9000))
|
||||
}
|
||||
|
||||
/// Makes a file-name-safe slug.
|
||||
fn slug_filename(s: &str) -> String {
|
||||
let mut out = String::new();
|
||||
for ch in s.chars() {
|
||||
if ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' {
|
||||
out.push(ch);
|
||||
} else {
|
||||
out.push('_');
|
||||
}
|
||||
}
|
||||
if out.is_empty() {
|
||||
"quiz".to_string()
|
||||
} else {
|
||||
out
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn escapes_html_once_inside_mattext() {
|
||||
let n = mattext("<p>a → b</p>");
|
||||
let xml = n.render(0);
|
||||
// The HTML is character data, so its markup is escaped.
|
||||
assert!(xml.contains("<p>a &rarr; b</p>"), "{xml}");
|
||||
assert!(!xml.contains("<p>"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn attributes_are_escaped() {
|
||||
let xml = Node::new("item")
|
||||
.attr("title", "a \"quoted\" & <angled>")
|
||||
.render(0);
|
||||
assert!(xml.contains(""quoted""));
|
||||
assert!(xml.contains("&"));
|
||||
assert!(!xml.contains("<angled>"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ids_are_deterministic_and_well_formed() {
|
||||
assert_eq!(qti_id("a"), qti_id("a"));
|
||||
assert_ne!(qti_id("a"), qti_id("b"));
|
||||
let id = qti_id("exam-4/assessment");
|
||||
assert_eq!(id.len(), 33);
|
||||
assert!(id.starts_with('g'));
|
||||
assert!(id[1..].chars().all(|c| c.is_ascii_hexdigit()));
|
||||
|
||||
let s = short_id("x");
|
||||
assert_eq!(s.len(), 4);
|
||||
assert!(s.parse::<u32>().unwrap() >= 1000);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn empty_element_renders_self_closing() {
|
||||
assert_eq!(
|
||||
Node::new("file").attr("href", "q.xml").render(0),
|
||||
"<file href=\"q.xml\"/>\n"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn document_has_a_declaration() {
|
||||
let doc = Node::new("root").document();
|
||||
assert!(doc.starts_with("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn manifest_points_at_the_quiz_file() {
|
||||
let m = build_manifest("exam-4.xml", "gabc", "Exam 4", "exam-4").render(0);
|
||||
assert!(m.contains("imsqti_xmlv1p2"));
|
||||
assert!(m.contains("href=\"exam-4.xml\""));
|
||||
assert!(m.contains("Exam 4"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn slug_filename_is_safe() {
|
||||
assert_eq!(slug_filename("exam-4 2026s"), "exam-4_2026s");
|
||||
assert_eq!(slug_filename(""), "quiz");
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,518 @@
|
||||
//! Rendering a printed exam with Typst.
|
||||
//!
|
||||
//! Typst rather than LaTeX because the toolchain is one binary with no package
|
||||
//! manager, the error messages point at a line, and the compile is fast enough to
|
||||
//! iterate on. `pixi run -e docs typst compile` turns the output of this module
|
||||
//! into a PDF.
|
||||
//!
|
||||
//! The emitted document is deliberately plain and self-contained: no imports, no
|
||||
//! template packages, nothing that can break because a package version moved. It
|
||||
//! is also meant to be edited. A generated exam is a starting point, and the
|
||||
//! output is formatted so that a human can reasonably open it and adjust spacing
|
||||
//! before printing.
|
||||
//!
|
||||
//! Every export takes a form, so form B's answer key is generated from the same
|
||||
//! permutation that produced form B's question paper. Keeping the key and the
|
||||
//! paper in one code path is the only way to be sure they agree — a mismatch is
|
||||
//! discovered by twenty-five students at once.
|
||||
|
||||
use crate::assessment::{AssessmentFile, Form};
|
||||
use crate::catalog::Catalog;
|
||||
use crate::course::CourseFile;
|
||||
use crate::error::{Error, Result};
|
||||
use crate::markup;
|
||||
use crate::select;
|
||||
|
||||
/// Options for a printed exam.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct Options {
|
||||
/// Which form to render.
|
||||
pub form: Form,
|
||||
/// Whether to leave a name and student-id block at the top.
|
||||
pub name_block: bool,
|
||||
/// Whether to show the points each question is worth.
|
||||
pub show_points: bool,
|
||||
/// Whether to start each question on a new page. Occasionally worth it for an
|
||||
/// exam with long stimuli.
|
||||
pub page_per_item: bool,
|
||||
/// Paper size, as Typst names it.
|
||||
pub paper: String,
|
||||
/// Base font size.
|
||||
pub font_size: String,
|
||||
}
|
||||
|
||||
impl Default for Options {
|
||||
fn default() -> Options {
|
||||
Options {
|
||||
form: Form {
|
||||
id: "A".to_string(),
|
||||
seed: 0,
|
||||
shuffle_items: false,
|
||||
shuffle_options: false,
|
||||
},
|
||||
name_block: true,
|
||||
show_points: true,
|
||||
page_per_item: false,
|
||||
paper: "us-letter".to_string(),
|
||||
font_size: "11pt".to_string(),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Renders the question paper.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `catalog` - the loaded course.
|
||||
/// * `record` - the assessment record.
|
||||
/// * `opts` - rendering options.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// A complete Typst document.
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// Returns [`Error::Unresolved`] when a placement references a missing item.
|
||||
pub fn exam(catalog: &Catalog, record: &AssessmentFile, opts: &Options) -> Result<String> {
|
||||
let course = &catalog.course;
|
||||
let mut out = String::new();
|
||||
out.push_str(&preamble(course, record, opts));
|
||||
|
||||
if opts.name_block {
|
||||
out.push_str(
|
||||
"#block(above: 1em, below: 1.5em)[\n \
|
||||
#grid(columns: (auto, 1fr, auto, 1fr), gutter: 0.6em,\n \
|
||||
[*Name*], [#box(width: 100%, repeat[.])],\n \
|
||||
[*Student ID*], [#box(width: 100%, repeat[.])],\n )\n]\n\n",
|
||||
);
|
||||
}
|
||||
|
||||
if let Some(instructions) = &record.assessment.instructions {
|
||||
out.push_str(&format!(
|
||||
"#block(fill: luma(245), inset: 8pt, radius: 3pt, width: 100%)[\n {}\n]\n\n",
|
||||
markup::to_typst(instructions)
|
||||
));
|
||||
}
|
||||
|
||||
let default_points = course.policy.points_per_item;
|
||||
let mut printed = 0usize;
|
||||
|
||||
for placement in select::layout(record, &opts.form) {
|
||||
if placement.dropped {
|
||||
continue;
|
||||
}
|
||||
let entry = catalog.require(&placement.item)?;
|
||||
let item = &entry.item;
|
||||
printed += 1;
|
||||
|
||||
if opts.page_per_item && printed > 1 {
|
||||
out.push_str("#pagebreak()\n\n");
|
||||
}
|
||||
|
||||
// A stimulus shared by several items is printed with each of them. That
|
||||
// repeats material, but a student should never have to flip pages to find
|
||||
// the passage a question refers to.
|
||||
if let Some(id) = &item.stimulus {
|
||||
if let Some(stimulus) = course.stimuli.get(id) {
|
||||
out.push_str(&format!(
|
||||
"#block(stroke: 0.5pt + luma(180), inset: 8pt, radius: 3pt, width: 100%)[\n \
|
||||
{}\n]\n",
|
||||
markup::to_typst(&stimulus.body)
|
||||
));
|
||||
if let Some(caption) = &stimulus.caption {
|
||||
out.push_str(&format!(
|
||||
"#block(above: 0.3em)[#text(size: 0.85em, style: \"italic\")[{}]]\n",
|
||||
markup::to_typst(caption)
|
||||
));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let points = placement
|
||||
.points
|
||||
.unwrap_or_else(|| item.points(default_points));
|
||||
let label = if placement.bonus {
|
||||
if opts.show_points {
|
||||
format!(
|
||||
" #text(fill: rgb(\"#666666\"))[(bonus, {})]",
|
||||
plural_points(points)
|
||||
)
|
||||
} else {
|
||||
" #text(fill: rgb(\"#666666\"))[(bonus)]".to_string()
|
||||
}
|
||||
} else if opts.show_points {
|
||||
format!(
|
||||
" #text(fill: rgb(\"#666666\"))[({})]",
|
||||
plural_points(points)
|
||||
)
|
||||
} else {
|
||||
String::new()
|
||||
};
|
||||
|
||||
// The question number is the recorded one, not the printed position, so a
|
||||
// scanned answer sheet still joins to the assessment record.
|
||||
out.push_str(&format!(
|
||||
"#block(above: 1.2em, below: 0.5em)[*{}.*{label} {}]\n",
|
||||
placement.number,
|
||||
markup::to_typst(&item.stem)
|
||||
));
|
||||
|
||||
if item.is_multi_key() {
|
||||
out.push_str(
|
||||
"#block(below: 0.4em)[#text(size: 0.9em, style: \"italic\")[Select all that \
|
||||
apply.]]\n",
|
||||
);
|
||||
}
|
||||
|
||||
let order = select::option_order(&opts.form, &placement.item, item.options.len());
|
||||
out.push_str("#block(inset: (left: 1.2em))[\n");
|
||||
for (position, source_index) in order.iter().enumerate() {
|
||||
let choice = &item.options[*source_index];
|
||||
// Options are relabeled by printed position, so a shuffled form still
|
||||
// reads A, B, C, D.
|
||||
let letter = (b'A' + position as u8) as char;
|
||||
out.push_str(&format!(
|
||||
" #grid(columns: (1.4em, 1fr), gutter: 0.2em)[{letter}.][{}]\n",
|
||||
markup::to_typst(&choice.text)
|
||||
));
|
||||
}
|
||||
out.push_str("]\n\n");
|
||||
}
|
||||
|
||||
if printed == 0 {
|
||||
return Err(Error::Invalid(vec![
|
||||
"this assessment has no printable items; every placement is marked dropped".to_string(),
|
||||
]));
|
||||
}
|
||||
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
/// Renders the answer key.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `catalog` - the loaded course.
|
||||
/// * `record` - the assessment record.
|
||||
/// * `opts` - rendering options, whose form determines the letters.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// A complete Typst document.
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// Returns [`Error::Unresolved`] when a placement references a missing item.
|
||||
pub fn answer_key(catalog: &Catalog, record: &AssessmentFile, opts: &Options) -> Result<String> {
|
||||
let mut out = String::new();
|
||||
out.push_str(&format!(
|
||||
"#set page(paper: \"{}\", margin: 2cm)\n#set text(size: 10pt)\n\n\
|
||||
= {} — answer key (form {})\n\n",
|
||||
opts.paper,
|
||||
escape(&record.assessment.title),
|
||||
opts.form.id
|
||||
));
|
||||
|
||||
out.push_str(
|
||||
"#text(size: 0.9em, style: \"italic\")[Letters below are the letters *as printed on this \
|
||||
form*. Do not use this key on another form.]\n\n",
|
||||
);
|
||||
|
||||
out.push_str(
|
||||
"#table(\n columns: (auto, auto, auto, 1fr),\n align: (right, center, center, left),\n \
|
||||
table.header([*\\#*], [*Key*], [*Level*], [*Objectives*]),\n",
|
||||
);
|
||||
|
||||
for placement in select::layout(record, &opts.form) {
|
||||
if placement.dropped {
|
||||
continue;
|
||||
}
|
||||
let entry = catalog.require(&placement.item)?;
|
||||
let item = &entry.item;
|
||||
let order = select::option_order(&opts.form, &placement.item, item.options.len());
|
||||
|
||||
// Map the source option index to the letter it was printed as.
|
||||
let mut printed_letters = Vec::new();
|
||||
for (position, source_index) in order.iter().enumerate() {
|
||||
if item.options[*source_index].correct {
|
||||
printed_letters.push(((b'A' + position as u8) as char).to_string());
|
||||
}
|
||||
}
|
||||
|
||||
let objectives = if placement.learning_objectives.is_empty() {
|
||||
item.learning_objectives.join(", ")
|
||||
} else {
|
||||
placement.learning_objectives.join(", ")
|
||||
};
|
||||
|
||||
out.push_str(&format!(
|
||||
" [{}], [*{}*], [{}], [{}],\n",
|
||||
placement.number,
|
||||
printed_letters.join(""),
|
||||
placement
|
||||
.level
|
||||
.map(|l| l.code().to_string())
|
||||
.unwrap_or_else(|| "-".into()),
|
||||
escape(&objectives)
|
||||
));
|
||||
}
|
||||
out.push_str(")\n\n");
|
||||
|
||||
// Partial credit decisions belong on the key, where the grader will see them.
|
||||
let overrides: Vec<String> = record
|
||||
.items
|
||||
.iter()
|
||||
.filter(|p| !p.credit_overrides.is_empty())
|
||||
.map(|p| {
|
||||
let list: Vec<String> = p
|
||||
.credit_overrides
|
||||
.iter()
|
||||
.map(|(letter, credit)| format!("{letter} = {:.0}%", credit * 100.0))
|
||||
.collect();
|
||||
format!("Question {}: {}", p.number, list.join(", "))
|
||||
})
|
||||
.collect();
|
||||
if !overrides.is_empty() {
|
||||
out.push_str("== Partial credit\n\n");
|
||||
for line in overrides {
|
||||
out.push_str(&format!("- {}\n", escape(&line)));
|
||||
}
|
||||
out.push('\n');
|
||||
}
|
||||
|
||||
let dropped: Vec<String> = record
|
||||
.items
|
||||
.iter()
|
||||
.filter(|p| p.dropped)
|
||||
.map(|p| p.number.to_string())
|
||||
.collect();
|
||||
if !dropped.is_empty() {
|
||||
out.push_str(&format!(
|
||||
"== Dropped\n\nQuestion(s) {} were dropped and are not printed.\n\n",
|
||||
dropped.join(", ")
|
||||
));
|
||||
}
|
||||
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
/// Renders a bubble sheet matching the form.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `catalog` - the loaded course, for option counts.
|
||||
/// * `record` - the assessment record.
|
||||
/// * `opts` - rendering options.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// A complete Typst document.
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// Returns [`Error::Unresolved`] when a placement references a missing item.
|
||||
pub fn bubble_sheet(catalog: &Catalog, record: &AssessmentFile, opts: &Options) -> Result<String> {
|
||||
let mut out = format!(
|
||||
"#set page(paper: \"{}\", margin: 1.5cm)\n#set text(size: 10pt)\n\n\
|
||||
= {} — answer sheet (form {})\n\n\
|
||||
#grid(columns: (auto, 1fr, auto, 1fr), gutter: 0.6em,\n \
|
||||
[*Name*], [#box(width: 100%, repeat[.])],\n \
|
||||
[*Student ID*], [#box(width: 100%, repeat[.])],\n)\n\n\
|
||||
#v(1em)\n",
|
||||
opts.paper,
|
||||
escape(&record.assessment.title),
|
||||
opts.form.id
|
||||
);
|
||||
|
||||
out.push_str("#columns(2)[\n");
|
||||
for placement in select::layout(record, &opts.form) {
|
||||
if placement.dropped {
|
||||
continue;
|
||||
}
|
||||
let entry = catalog.require(&placement.item)?;
|
||||
let count = entry.item.options.len();
|
||||
let bubbles: Vec<String> = (0..count)
|
||||
.map(|i| {
|
||||
let letter = (b'A' + i as u8) as char;
|
||||
format!("#circle(radius: 0.42em, stroke: 0.5pt)[#align(center + horizon)[#text(size: 0.7em)[{letter}]]]")
|
||||
})
|
||||
.collect();
|
||||
out.push_str(&format!(
|
||||
" #block(below: 0.45em)[#box(width: 2em)[{}.] {}]\n",
|
||||
placement.number,
|
||||
bubbles.join(" ")
|
||||
));
|
||||
}
|
||||
out.push_str("]\n");
|
||||
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
/// Builds the document preamble.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `course` - the course.
|
||||
/// * `record` - the assessment record.
|
||||
/// * `opts` - rendering options.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// Typst setup and a title block.
|
||||
fn preamble(course: &CourseFile, record: &AssessmentFile, opts: &Options) -> String {
|
||||
let form_note = if record.forms.len() > 1 {
|
||||
format!(" · Form {}", opts.form.id)
|
||||
} else {
|
||||
String::new()
|
||||
};
|
||||
let date = record
|
||||
.assessment
|
||||
.date
|
||||
.map(|d| d.to_string())
|
||||
.unwrap_or_default();
|
||||
let minutes = record
|
||||
.assessment
|
||||
.minutes_allowed
|
||||
.map(|m| format!(" · {m:.0} minutes"))
|
||||
.unwrap_or_default();
|
||||
|
||||
format!(
|
||||
"#set page(\n paper: \"{paper}\",\n margin: 2cm,\n \
|
||||
header: [#text(size: 0.85em)[{code} · {title}{form_note}]],\n \
|
||||
footer: context [#text(size: 0.85em)[Page #counter(page).display() of \
|
||||
#counter(page).final().first()]],\n)\n\
|
||||
#set text(size: {size})\n\
|
||||
#set par(justify: false, leading: 0.65em)\n\n\
|
||||
#align(center)[\n #text(size: 1.4em, weight: \"bold\")[{title}]\n \\\n \
|
||||
#text(size: 0.95em)[{code} — {course_title} · {term}]\n \\\n \
|
||||
#text(size: 0.9em)[{date}{minutes}]\n]\n\n",
|
||||
paper = opts.paper,
|
||||
size = opts.font_size,
|
||||
code = escape(&course.course.code),
|
||||
course_title = escape(&course.course.title),
|
||||
term = escape(
|
||||
record
|
||||
.assessment
|
||||
.term
|
||||
.as_deref()
|
||||
.unwrap_or(&course.course.term)
|
||||
),
|
||||
title = escape(&record.assessment.title),
|
||||
form_note = form_note,
|
||||
date = date,
|
||||
minutes = minutes,
|
||||
)
|
||||
}
|
||||
|
||||
/// Formats a point value with the right plural.
|
||||
fn plural_points(points: f64) -> String {
|
||||
if (points - 1.0).abs() < 1e-9 {
|
||||
"1 point".to_string()
|
||||
} else if (points.fract()).abs() < 1e-9 {
|
||||
format!("{points:.0} points")
|
||||
} else {
|
||||
format!("{points} points")
|
||||
}
|
||||
}
|
||||
|
||||
/// Escapes text for Typst content mode.
|
||||
fn escape(s: &str) -> String {
|
||||
markup::to_typst(s)
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::assessment::Placement;
|
||||
|
||||
#[test]
|
||||
fn point_labels_are_pluralized() {
|
||||
assert_eq!(plural_points(1.0), "1 point");
|
||||
assert_eq!(plural_points(2.0), "2 points");
|
||||
assert_eq!(plural_points(1.5), "1.5 points");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn escaping_protects_typst_syntax() {
|
||||
assert_eq!(escape("email me @ home"), "email me \\@ home");
|
||||
assert_eq!(escape("a < b"), "a \\< b");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_key_reports_letters_as_printed() {
|
||||
// Shuffling must relabel the key: if the correct option moves to the third
|
||||
// printed position, the key says C.
|
||||
let form = Form {
|
||||
id: "B".into(),
|
||||
seed: 99,
|
||||
shuffle_items: false,
|
||||
shuffle_options: true,
|
||||
};
|
||||
let order = select::option_order(&form, "bank::q-1", 4);
|
||||
let correct_source = 0usize;
|
||||
let printed_position = order.iter().position(|i| *i == correct_source).unwrap();
|
||||
let letter = (b'A' + printed_position as u8) as char;
|
||||
assert!(('A'..='D').contains(&letter));
|
||||
// And it is reproducible.
|
||||
let again = select::option_order(&form, "bank::q-1", 4);
|
||||
assert_eq!(order, again);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn dropped_items_are_not_printed() {
|
||||
let record = AssessmentFile {
|
||||
schema_version: "1.0".into(),
|
||||
assessment: crate::assessment::Assessment {
|
||||
id: "e1".into(),
|
||||
title: "Exam 1".into(),
|
||||
term: None,
|
||||
kind: crate::assessment::Kind::Exam,
|
||||
date: None,
|
||||
platform: crate::assessment::Platform::Paper,
|
||||
minutes_allowed: None,
|
||||
attempts: None,
|
||||
shuffle: None,
|
||||
scoring_policy: None,
|
||||
instructions: None,
|
||||
notes: None,
|
||||
},
|
||||
blueprint: None,
|
||||
forms: Vec::new(),
|
||||
items: vec![
|
||||
Placement {
|
||||
number: 1,
|
||||
item: "b::q-1".into(),
|
||||
version: None,
|
||||
fingerprint: None,
|
||||
points: None,
|
||||
bonus: false,
|
||||
key: vec!["A".into()],
|
||||
level: None,
|
||||
learning_objectives: Vec::new(),
|
||||
credit_overrides: Default::default(),
|
||||
dropped: true,
|
||||
},
|
||||
Placement {
|
||||
number: 2,
|
||||
item: "b::q-2".into(),
|
||||
version: None,
|
||||
fingerprint: None,
|
||||
points: None,
|
||||
bonus: false,
|
||||
key: vec!["B".into()],
|
||||
level: None,
|
||||
learning_objectives: Vec::new(),
|
||||
credit_overrides: Default::default(),
|
||||
dropped: false,
|
||||
},
|
||||
],
|
||||
};
|
||||
let printable: Vec<u32> = select::layout(&record, &Options::default().form)
|
||||
.into_iter()
|
||||
.filter(|p| !p.dropped)
|
||||
.map(|p| p.number)
|
||||
.collect();
|
||||
assert_eq!(printable, vec![2]);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user