Struct LuaState 

pub struct LuaState<'scope, 'template, 'env>(/* private fields */);

A mlua::UserData wrapper around a mutable minijinja::State.

It can only be initialized within an mlua::Lua::scope callback, as it is not 'static

Methods from Deref<Target = State<'template, 'env>>

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

Returns a reference to the current environment.

pub fn name(&self) -> &str

Returns the name of the current template.

pub fn auto_escape(&self) -> &AutoEscape

Returns the current value of the auto escape flag.

pub fn undefined_behavior(&self) -> UndefinedBehavior

Returns the current undefined behavior.

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

Returns the name of the innermost block.

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

Looks up a variable by name in the context.

Note on Closures

Macros and call blocks analyze which variables are referenced and create closures for them. This means that unless a variable is defined as a global in the environment, was passed in the initial render context, or was referenced by a macro, this method won’t be able to find it.

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

Looks up a global macro and calls it.

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

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

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 mut rendered = tmpl
    .render_captured(context!(name => "John"))?;
let rv = rendered.with_state_mut(|state| state.render_block("hi"))?;
println!("{}", rv);

Rendering a block is a stateful operation and therefore requires mutable access to the state. Filters and functions can request this by taking &mut State as their first parameter. Execution frames are restored if rendering fails, while explicit mutations to temps or extensions remain.

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

where W: Write,

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

For details see render_block.

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

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

pub fn known_variables(&self) -> Vec<Cow<'_, str>>

Returns a list of all known variables.

This list contains all variables that are currently known to the state. To retrieve the values you can use lookup. This will include all the globals of the environment. Note that if the context has been initialized with an object that lies about variables (eg: it does not correctly implement enumeration), the returned list might not be complete.

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.

pub fn apply_filter( &mut 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"));

pub fn perform_test( &mut 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);

pub fn format(&mut 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");

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

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.

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

Looks up a temp and returns it.

Temps are similar to context values but the engine never looks them up on their own and they are not scoped. The lifetime of temps is limited to the rendering process of a template. Temps are useful so that filters and other things can temporarily stash away state without having to resort to thread locals which are hard to manage. Unlike context variables, temps can also be modified during evaluation by filters and functions.

Temps are useful for dynamically named data that needs to be represented as a Value. For ordinary typed Rust state, prefer get_or_insert_extension, which avoids object wrappers and interior mutability.

Example

use minijinja::{Value, State};

fn inc(state: &mut State) -> Value {
    let old = state
        .get_temp("my_counter")
        .unwrap_or_else(|| Value::from(0i64));
    let new = Value::from(i64::try_from(old).unwrap() + 1);
    state.set_temp("my_counter", new.clone());
    new
}

pub fn set_temp(&mut self, name: &str, value: Value) -> Option<Value>

Inserts a temp and returns the old temp.

For more information see get_temp.

pub fn get_extension<T>(&self) -> Option<&T>

where T: Send + 'static,

Returns a reference to a typed render-local extension.

Extensions are similar to temps, but store ordinary Rust values keyed by their type. They are useful for state that should be shared by filters and functions for the duration of a render without requiring a Value, crate::value::Object, or interior mutability. There can be one extension of each concrete type; use a newtype when independent values have the same underlying type. Extension values must be Send because states can be moved between threads.

Extensions are preserved across nested evaluation, including includes, blocks, and macro calls. They are dropped together with the state.

pub fn get_extension_mut<T>(&mut self) -> Option<&mut T>

where T: Send + 'static,

Returns a mutable reference to a typed render-local extension.

For more information see get_extension.

pub fn get_or_insert_extension<T>(&mut self, value: T) -> &mut T

where T: Send + 'static,

Returns a mutable extension, inserting it if necessary.

If an extension of type T is already present, value is not inserted. Extensions require mutable state so that stored values do not need a mutex or other interior mutability.

Example

use minijinja::State;

#[derive(Default)]
struct Counter(usize);

fn next(state: &mut State) -> usize {
    let counter = state.get_or_insert_extension(Counter::default());
    counter.0 += 1;
    counter.0
}

pub fn get_or_insert_extension_with<T, F>(&mut self, f: F) -> &mut T

where T: Send + 'static, F: FnOnce() -> T,

Returns a mutable extension, inserting one from f if necessary.

For more information see get_or_insert_extension.

Trait Implementations

impl<'scope, 'template, 'env> Debug for LuaState<'scope, 'template, 'env>

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

Formats the value using the given formatter.

impl<'scope, 'template, 'env> Deref for LuaState<'scope, 'template, 'env>

type Target = State<'template, 'env>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'scope, 'template, 'env> DerefMut for LuaState<'scope, 'template, 'env>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'scope, 'template, 'env> Display for LuaState<'scope, 'template, 'env>

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

Formats the value using the given formatter.

impl<'scope, 'template, 'env> From<&'scope mut State<'template, 'env>> for LuaState<'scope, 'template, 'env>

fn from(value: &'scope mut State<'template, 'env>) -> Self

Converts to this type from the input type.

impl<'scope, 'template, 'env> From<LuaState<'scope, 'template, 'env>> for &'scope mut State<'template, 'env>

fn from(value: LuaState<'scope, 'template, 'env>) -> Self

Converts to this type from the input type.

impl<'scope, 'template, 'env> UserData for LuaState<'scope, 'template, 'env>

fn add_fields<F: UserDataFields<Self>>(fields: &mut F)

Adds custom fields specific to this userdata.

fn add_methods<M: UserDataMethods<Self>>(methods: &mut M)

Adds custom methods and operators specific to this userdata.

fn register(registry: &mut UserDataRegistry<Self>)

Registers this type for use in Lua.