Struct minijinja::Template

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

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§

source§

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

source

pub fn name(&self) -> &str

Returns the name of the template.

source

pub fn source(&self) -> &str

Returns the source code of the template.

source

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

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.

source

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

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.

source

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

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.

source

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

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.

source

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"]
source

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§

source§

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

source§

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

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

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

§

impl<'env, 'source> !RefUnwindSafe for Template<'env, 'source>

§

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

§

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

§

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

§

impl<'env, 'source> !UnwindSafe for Template<'env, 'source>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.