Struct Engine 

pub struct Engine { /* private fields */ }

A template engine that compiles templates into an AST and renders them.

Templates are added by name and can reference each other via {% include %} and {% extends %} / {% block %}.

Trust model

Templates are trusted code, exactly like Jinja2 or MiniJinja: a template can read any variable in the rendering context and can consume CPU/memory within the configured limits. Never feed untrusted template source to add_template. User data belongs in the context, which is escaped automatically in EscapeMode::Html.

Implementations

impl Engine

pub fn new(mode: EscapeMode) -> Self

Create a new engine with the given escaping mode.

pub fn set_range_limit(&mut self, limit: usize)

Set the maximum number of items a range() call may produce.

Defaults to [DEFAULT_RANGE_LIMIT]. Calls that would exceed the limit return a render error instead of allocating an unbounded amount of memory.

pub fn range_limit(&self) -> usize

Return the current range() item limit.

pub fn add_template(&mut self, name: &str, source: &str) -> Result<(), Error>

Compile and register a template by name.

Returns an error if the template source contains invalid syntax (e.g. unclosed {{ }}, mismatched {% if %} / {% endif %}), exceeded nesting limits, statically-detectable type errors, or if a template with the same name already exists.

pub fn render( &self, name: &str, context: impl IntoContext, ) -> Result<String, Error>

Render a named template with the given context variables.

Pass a Context built with the [context!] macro, or a reference to any type that implements Serialize (requires the std feature). Non-map values such as plain strings or numbers produce a render error.

use template::{Engine, EscapeMode, context};

let mut engine = Engine::new(EscapeMode::Text);
engine.add_template("t", "Hello, {{ name }}!").unwrap();
let result = engine.render("t", context! { name: "World" }).unwrap();
assert_eq!(result, "Hello, World!");

Returns an error if the template name is not registered or if an expression fails during rendering.

pub fn render_to( &self, name: &str, context: impl IntoContext, out: &mut impl Write, ) -> Result<(), Error>

Render a named template directly into any fmt::Write sink.

This is the allocation-friendly counterpart of Engine::render: output can be streamed into an existing String, a Vec<u8> wrapper, or any other fmt::Write implementation without building an intermediate buffer.