Struct Template

pub struct Template<'env, 'source>
where
    'env: 'source,
{ /* private fields */ }

Represents a handle to a template.

Templates are stored in the [Environment] as bytecode instructions. With the [Environment::get_template] method that is looked up and returned in form of this handle. Such a template can be cheaply copied as it only holds references.

To render the render method can be used.

Implementations

impl<'env, 'source> Template<'env, 'source>

pub fn name(&self) -> &str

Returns the name of the template.

pub fn source(&self) -> &str

Returns the source code of the template.

pub fn render<S>(&self, ctx: S) -> Result<String, Error>

where S: Serialize,

Renders the template into a string.

The provided value is used as the initial context for the template. It can be any object that implements Serialize. You can either create your own struct and derive Serialize for it or the context! macro can be used to create an ad-hoc context.

For very large contexts and to avoid the overhead of serialization of potentially unused values, you might consider using a dynamic Object as value. For more information see Map as Context.

let tmpl = env.get_template("hello").unwrap();
println!("{}", tmpl.render(context!(name => "John")).unwrap());

To render a single block use eval_to_state in combination with [State::render_block].

Note on values: The Value type implements Serialize and can be efficiently passed to render. It does not undergo actual serialization.

pub fn render_and_return_state<S>( &self, ctx: S, ) -> Result<(String, State<'_, 'env>), Error>

where S: Serialize,

Like render but also return the evaluated [State].

This can be used to inspect the [State] of the template post evaluation for instance to get fuel consumption numbers or to access globally set variables.

let tmpl = env.template_from_str("{% set x = 42 %}Hello {{ what }}!").unwrap();
let (rv, state) = tmpl.render_and_return_state(context!{ what => "World" }).unwrap();
assert_eq!(rv, "Hello World!");
assert_eq!(state.lookup("x"), Some(Value::from(42)));

Note on values: The Value type implements Serialize and can be efficiently passed to render. It does not undergo actual serialization.

pub fn render_to_write<S, W>( &self, ctx: S, w: W, ) -> Result<State<'_, 'env>, Error>

where S: Serialize, W: Write,

Renders the template into an io::Write.

This works exactly like render but instead writes the template as it’s evaluating into an io::Write. It also returns the [State] like render_and_return_state does.

use std::io::stdout;

let tmpl = env.get_template("hello").unwrap();
tmpl.render_to_write(context!(name => "John"), &mut stdout()).unwrap();

Note on values: The Value type implements Serialize and can be efficiently passed to render. It does not undergo actual serialization.

pub fn eval_to_state<S>(&self, ctx: S) -> Result<State<'_, 'env>, Error>

where S: Serialize,

Evaluates the template into a [State].

This evaluates the template, discards the output and returns the final State for introspection. From there global variables or blocks can be accessed. What this does is quite similar to how the engine internally works with templates that are extended or imported from.

let tmpl = env.get_template("hello")?;
let state = tmpl.eval_to_state(context!(name => "John"))?;
println!("{:?}", state.exports());

If you also want to render, use render_and_return_state.

For more information see [State].

pub fn undeclared_variables(&self, nested: bool) -> HashSet<String>

Returns a set of all undeclared variables in the template.

This returns a set of all variables that might be looked up at runtime by the template. Since this is runs a static analysis, the actual control flow is not considered. This also cannot take into account what happens due to includes, imports or extending. If nested is set to true, then also nested trivial attribute lookups are considered and returned.

let mut env = Environment::new();
env.add_template("x", "{% set x = foo %}{{ x }}{{ bar.baz }}").unwrap();
let tmpl = env.get_template("x").unwrap();
let undeclared = tmpl.undeclared_variables(false);
// returns ["foo", "bar"]
let undeclared = tmpl.undeclared_variables(true);
// returns ["foo", "bar.baz"]

pub fn new_state(&self) -> State<'_, 'env>

Creates an empty [State] for this template.

It’s very rare that you need to actually do this but it can be useful when testing values or working with macros or other callable objects from outside the template environment.

Trait Implementations

impl<'env, 'source> Clone for Template<'env, 'source>

where 'env: 'source,

fn clone(&self) -> Template<'env, 'source>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'env, 'source> Debug for Template<'env, 'source>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.