Struct minijinja::State

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

Provides access to the current execution state of the engine.

A read only reference is passed to filter functions and similar objects to allow limited interfacing with the engine. The state is useful to look up information about the engine in filter, test or global functions. It not only provides access to the template environment but also the context variables of the engine, the current auto escaping behavior as well as the auto escape flag.

In some testing scenarios or more advanced use cases you might need to get a State. The state is managed as part of the template execution but the initial state can be retrieved via Template::new_state. The most common way to get hold of the state however is via functions of filters.

Notes on lifetimes: the state object exposes some of the internal lifetimes through the type. You should always elide these lifetimes as there might be lifetimes added or removed between releases.

Implementations§

source§

impl<'template, 'env> State<'template, 'env>

source

pub fn env(&self) -> &Environment<'_>

Returns a reference to the current environment.

source

pub fn name(&self) -> &str

Returns the name of the current template.

source

pub fn auto_escape(&self) -> AutoEscape

Returns the current value of the auto escape flag.

source

pub fn undefined_behavior(&self) -> UndefinedBehavior

Returns the current undefined behavior.

source

pub fn current_block(&self) -> Option<&str>

Returns the name of the innermost block.

source

pub fn lookup(&self, name: &str) -> Option<Value>

Looks up a variable by name in the context.

source

pub fn call_macro(&self, name: &str, args: &[Value]) -> Result<String, Error>

Available on crate feature macros only.

Looks up a global macro and calls it.

This looks up a value as lookup does and calls it with the passed args.

source

pub fn render_block(&mut self, block: &str) -> Result<String, Error>

Available on crate feature multi_template only.

Renders a block with the given name into a string.

This method works like Template::render but it only renders a specific block in the template. The first argument is the name of the block.

This renders only the block hi in the template:

let tmpl = env.get_template("hello")?;
let rv = tmpl
    .eval_to_state(context!(name => "John"))?
    .render_block("hi")?;
println!("{}", rv);

Note that rendering a block is a stateful operation. If an error is returned the module has to be re-created as the internal state can end up corrupted. This also means you can only render blocks if you have a mutable reference to the state which is not possible from within filters or similar.

source

pub fn render_block_to_write<W>( &mut self, block: &str, w: W, ) -> Result<(), Error>
where W: Write,

Available on crate feature multi_template only.

Renders a block with the given name into an io::Write.

For details see render_block.

source

pub fn exports(&self) -> Vec<&str>

Returns a list of the names of all exports (top-level variables).

source

pub fn get_template(&self, name: &str) -> Result<Template<'env, 'env>, Error>

Fetches a template by name with path joining.

This works like Environment::get_template with the difference that the lookup undergoes path joining. If the environment has a configured path joining callback, it will be invoked with the name of the current template as parent template.

For more information see Environment::set_path_join_callback.

source

pub fn apply_filter(&self, filter: &str, args: &[Value]) -> Result<Value, Error>

Invokes a filter with some arguments.

let rv = state.apply_filter("upper", &["hello world".into()]).unwrap();
assert_eq!(rv.as_str(), Some("HELLO WORLD"));
source

pub fn perform_test(&self, test: &str, args: &[Value]) -> Result<bool, Error>

Invokes a test function on a value.

let rv = state.perform_test("even", &[42i32.into()]).unwrap();
assert!(rv);
source

pub fn format(&self, value: Value) -> Result<String, Error>

Formats a value to a string using the formatter on the environment.

let rv = state.format(Value::from(42)).unwrap();
assert_eq!(rv, "42");
source

pub fn fuel_levels(&self) -> Option<(u64, u64)>

Available on crate feature fuel only.

Returns the fuel levels.

When the fuel feature is enabled, during evaluation the template will keep track of how much fuel it has consumed. If the fuel tracker is turned on the returned value will be Some((consumed, remaining)). If fuel tracking is not enabled, None is returned instead.

Trait Implementations§

source§

impl<'a> ArgType<'a> for &State<'_, '_>

§

type Output = &'a State<'a, 'a>

The output type of this argument.
source§

impl<'template, 'env> Debug for State<'template, 'env>

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<'template, 'env> Freeze for State<'template, 'env>

§

impl<'template, 'env> !RefUnwindSafe for State<'template, 'env>

§

impl<'template, 'env> Send for State<'template, 'env>

§

impl<'template, 'env> Sync for State<'template, 'env>

§

impl<'template, 'env> Unpin for State<'template, 'env>

§

impl<'template, 'env> !UnwindSafe for State<'template, 'env>

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> 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, 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.