use std::collections::{BTreeMap, BTreeSet};
use std::fmt;
use minijinja::{Environment, UndefinedBehavior};
use serde::de::{self, Deserializer, MapAccess, Visitor};
use serde::{Deserialize, Serialize};
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum TemplateSource {
Inline(String),
File(String),
}
impl<'de> Deserialize<'de> for TemplateSource {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
struct TemplateVisitor;
impl<'de> Visitor<'de> for TemplateVisitor {
type Value = TemplateSource;
fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str("a template string or a table `{ file = \"path\" }`")
}
fn visit_str<E: de::Error>(self, value: &str) -> Result<Self::Value, E> {
Ok(TemplateSource::Inline(value.to_owned()))
}
fn visit_string<E: de::Error>(self, value: String) -> Result<Self::Value, E> {
Ok(TemplateSource::Inline(value))
}
fn visit_map<A: MapAccess<'de>>(self, mut map: A) -> Result<Self::Value, A::Error> {
let mut file = None;
let mut extra = BTreeMap::new();
while let Some(key) = map.next_key::<String>()? {
let value: String = map.next_value()?;
match key.as_str() {
"file" => file = Some(value),
other => {
extra.insert(other.to_owned(), value);
}
}
}
if extra.contains_key("command") {
return Err(de::Error::custom(
"templates render; they do not execute (ADR-0006)",
));
}
if !extra.is_empty() {
let keys: Vec<_> = extra.keys().map(String::as_str).collect();
return Err(de::Error::custom(format!(
"unknown template table key `{}`; only `file` is allowed",
keys[0]
)));
}
let Some(path) = file else {
return Err(de::Error::custom(
"template table needs `file`; inline templates are a bare string",
));
};
if path.trim().is_empty() {
return Err(de::Error::custom("`file` is empty"));
}
Ok(TemplateSource::File(path))
}
}
deserializer.deserialize_any(TemplateVisitor)
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RenderError {
message: String,
}
impl fmt::Display for RenderError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&self.message)
}
}
impl std::error::Error for RenderError {}
pub fn render(name: &str, source: &str, context: impl Serialize) -> Result<String, RenderError> {
let mut env = Environment::new();
env.set_undefined_behavior(UndefinedBehavior::SemiStrict);
env.set_auto_escape_callback(|_| minijinja::AutoEscape::None);
env.add_template(name, source)
.map_err(|err| render_error(&err))?;
let template = env.get_template(name).map_err(|err| render_error(&err))?;
let context = minijinja::Value::from(minijinja::value::Serde(context));
template.render(&context).map_err(|err| {
let mut failure = render_error(&err);
if err.kind() == minijinja::ErrorKind::UndefinedError {
let ambient: BTreeSet<String> =
env.globals().map(|(name, _)| name.to_owned()).collect();
failure.message.push_str(": ");
failure
.message
.push_str(&undefined_detail(&template, &context, &ambient));
}
failure
})
}
fn undefined_detail(
template: &minijinja::Template<'_, '_>,
context: &minijinja::Value,
ambient: &BTreeSet<String>,
) -> String {
let Some(provided) = context_keys(context) else {
return String::from("oakum could not list the variables this template receives");
};
let mut unsupplied: Vec<String> = template
.undeclared_variables(true)
.into_iter()
.filter(|name| !resolves(context, name) && !resolves_ambient(ambient, name))
.collect();
unsupplied.sort();
let reads = if unsupplied.is_empty() {
String::from("a variable this template reads is not defined here")
} else {
format!(
"this template reads {}, which the context does not supply",
quoted(&unsupplied)
)
};
if provided.is_empty() {
return format!("{reads}; it receives no variables");
}
format!("{reads}; it receives {}", quoted(&provided))
}
fn resolves(context: &minijinja::Value, name: &str) -> bool {
let mut at = context.clone();
for segment in name.split('.') {
let Ok(next) = at.get_attr(segment) else {
return false;
};
if next.is_undefined() {
return false;
}
at = next;
}
true
}
fn resolves_ambient(ambient: &BTreeSet<String>, name: &str) -> bool {
ambient.contains(name)
}
fn context_keys(context: &minijinja::Value) -> Option<BTreeSet<String>> {
if context.kind() != minijinja::value::ValueKind::Map {
return None;
}
Some(
context
.try_iter()
.ok()?
.map(|key| key.to_string())
.collect(),
)
}
pub fn quoted<T: fmt::Display>(names: impl IntoIterator<Item = T>) -> String {
names
.into_iter()
.map(|name| format!("`{name}`"))
.collect::<Vec<_>>()
.join(", ")
}
pub fn reads_any(source: &str, names: &[&str]) -> Result<bool, RenderError> {
let mut env = Environment::new();
env.add_template("probe", source)
.map_err(|err| render_error(&err))?;
let template = env
.get_template("probe")
.map_err(|err| render_error(&err))?;
let read = template.undeclared_variables(false);
Ok(names.iter().any(|name| read.contains(*name)))
}
fn render_error(err: &minijinja::Error) -> RenderError {
RenderError {
message: err.to_string(),
}
}
#[cfg(test)]
mod tests {
use super::{render, TemplateSource};
use minijinja::context;
use serde::Deserialize;
#[derive(Debug, Deserialize)]
struct Wrap {
template: TemplateSource,
}
#[test]
fn inline_source_round_trips_from_toml() {
let wrap: Wrap = toml::from_str("template = \"hello {{ name }}\"\n").expect("inline");
assert_eq!(
wrap.template,
TemplateSource::Inline(String::from("hello {{ name }}"))
);
}
#[test]
fn file_table_is_a_path() {
let wrap: Wrap = toml::from_str("template = { file = \"notes.md\" }\n").expect("file");
assert_eq!(
wrap.template,
TemplateSource::File(String::from("notes.md"))
);
}
#[test]
fn command_table_is_refused() {
let err =
toml::from_str::<Wrap>("template = { command = \"pandoc\" }\n").expect_err("command");
assert!(err.to_string().contains("do not execute"), "{err}");
}
#[test]
fn empty_file_and_unknown_keys_are_refused() {
toml::from_str::<Wrap>("template = { file = \"\" }\n").expect_err("empty");
toml::from_str::<Wrap>("template = { file = \" \" }\n").expect_err("blank");
toml::from_str::<Wrap>("template = {}\n").expect_err("empty table");
toml::from_str::<Wrap>("template = { file = \"a.md\", extra = \"x\" }\n")
.expect_err("extra");
}
#[test]
fn renders_a_defined_value() {
let out = render("t", "v={{ version }}", context!(version => "1.2.3")).expect("render");
assert_eq!(out, "v=1.2.3");
}
#[test]
fn undefined_print_is_an_error() {
let err = render("t", "{{ missing }}", context!()).expect_err("undef");
assert!(
err.to_string().contains("undefined") || err.to_string().contains("missing"),
"{err}"
);
}
#[test]
fn an_undefined_variable_names_itself_and_the_scope() {
let err = render(
"tag-format",
"{{ name }}",
context!(version => "1.2.3", package => "demo"),
)
.expect_err("undefined")
.to_string();
assert!(
err.contains("this template reads `name`, which the context does not supply"),
"{err}"
);
assert!(err.contains("it receives `package`, `version`"), "{err}");
}
#[test]
fn the_scope_is_read_from_the_context_not_a_list() {
let err = render(
"title",
"{{ nope }}{{ repo.slug }}",
context!(version => "1"),
)
.expect_err("undefined")
.to_string();
assert!(
err.contains("reads `nope`, `repo.slug`, which the context does not supply"),
"{err}"
);
assert!(err.contains("it receives `version`"), "{err}");
let empty = render("title", "{{ nope }}", context!())
.expect_err("undefined")
.to_string();
assert!(empty.contains("it receives no variables"), "{empty}");
}
#[test]
fn a_name_the_context_supplies_is_not_named_as_missing() {
let err = render("t", "{{ version }}{{ nope }}", context!(version => "1.2.3"))
.expect_err("undefined")
.to_string();
assert!(
err.contains("reads `nope`, which the context does not supply"),
"{err}"
);
assert!(
!err.contains("`nope`, `version`"),
"a provided name is not missing: {err}"
);
assert!(err.contains("it receives `version`"), "{err}");
}
#[test]
fn a_nested_attribute_the_context_supplies_is_not_named_as_missing() {
let err = render(
"t",
"{{ repo.url }}{{ nope }}",
context!(repo => context!(url => "https://x/y"), version => "1"),
)
.expect_err("undefined")
.to_string();
assert!(
err.contains("reads `nope`, which the context does not supply"),
"{err}"
);
assert!(!err.contains("repo.url"), "a supplied nested read: {err}");
}
#[test]
fn a_nested_attribute_the_context_lacks_names_itself() {
let err = render(
"changelog",
"{{ repo.nope }}",
context!(repo => context!(url => "https://x/y"), version => "1"),
)
.expect_err("undefined")
.to_string();
assert!(
err.contains("this template reads `repo.nope`, which the context does not supply"),
"{err}"
);
assert!(
!err.contains("a variable this template reads is not defined here"),
"the generic sentence is the fallback, not the answer: {err}"
);
}
#[test]
fn a_template_global_is_not_reported_as_undefined() {
let err = render(
"t",
"{% for i in range(3) %}{{ nope }}{% endfor %}",
context!(version => "1"),
)
.expect_err("undefined")
.to_string();
assert!(
err.contains("reads `nope`, which the context does not supply"),
"{err}"
);
assert!(!err.contains("range"), "a global is not missing: {err}");
assert!(err.contains("it receives `version`"), "{err}");
}
#[test]
fn the_message_states_a_set_not_a_cause() {
let err = render(
"t",
"{% if false %}{{ ghost }}{% endif %}{{ nope }}",
context!(version => "1"),
)
.expect_err("undefined")
.to_string();
assert!(
err.contains("this template reads `ghost`, `nope`, which the context does not supply"),
"{err}"
);
assert!(
!err.contains("is not defined here"),
"a set of names takes no singular verb: {err}"
);
}
#[test]
fn a_context_that_is_not_a_map_is_not_reported_as_empty() {
for shape in [
minijinja::Value::from(vec!["alpha", "beta"]),
minijinja::Value::from("a string"),
] {
let err = render("t", "{{ nope }}", shape.clone())
.expect_err("undefined")
.to_string();
assert!(
err.contains("could not list the variables this template receives"),
"{shape:?}: {err}"
);
assert!(
!err.contains("it receives no variables"),
"{shape:?}: {err}"
);
assert!(!err.contains("alpha"), "elements are not names: {err}");
}
}
#[test]
fn other_render_failures_gain_no_scope_sentence() {
let err = render(
"t",
"{{ version | nosuchfilter }}",
context!(version => "1"),
)
.expect_err("unknown filter")
.to_string();
assert!(!err.contains("it receives"), "{err}");
}
#[test]
fn undefined_in_if_is_false() {
let out = render(
"t",
"{% if missing %}yes{% else %}no{% endif %}",
context!(),
)
.expect("if");
assert_eq!(out, "no");
}
#[test]
fn include_without_a_loader_fails() {
let err = render("t", "{% include 'other.md' %}", context!()).expect_err("include");
assert!(!err.to_string().is_empty(), "{err}");
}
#[test]
fn reads_any_sees_only_top_level_names() {
assert!(super::reads_any("{{ repo.url }}", &["repo", "changes"]).unwrap());
assert!(super::reads_any(
"{% for c in changes %}{{ c.note }}{% endfor %}",
&["repo", "changes"]
)
.unwrap());
assert!(!super::reads_any("{{ version }} {{ notes[0] }}", &["repo", "changes"]).unwrap());
assert!(super::reads_any("{{", &["repo"]).is_err());
}
}