Struct Environment

pub struct Environment<'source> { /* private fields */ }

An abstraction that holds the engine configuration.

This object holds the central configuration state for templates. It is also the container for all loaded templates.

The environment holds references to the source the templates were created from. This makes it very inconvenient to pass around unless the templates are static strings.

There are generally two ways to construct an environment:

• Environment::new creates an environment preconfigured with sensible defaults. It will contain all built-in filters, tests and globals as well as a callback for auto escaping based on file extension.
• Environment::empty creates a completely blank environment.

Implementations

impl<'source> Environment<'source>

pub fn new() -> Environment<'source>

Creates a new environment with sensible defaults.

This environment does not yet contain any templates but it will have all the default filters, tests and globals loaded. If you do not want any default configuration you can use the alternative empty method.

pub fn empty() -> Environment<'source>

Creates a completely empty environment.

This environment has no filters, no templates, no globals and no default logic for auto escaping configured.

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

Loads a template from a string into the environment.

The name parameter defines the name of the template which identifies it. To look up a loaded template use the get_template method.

let mut env = Environment::new();
env.add_template("index.html", "Hello {{ name }}!").unwrap();

Note that there are situations where the interface of this method is too restrictive as you need to hold on to the strings for the lifetime of the environment. This methodl fails if the template has a syntax error. To address this restriction use add_template_owned.

pub fn add_template_owned<N, S>( &mut self, name: N, source: S, ) -> Result<(), Error>

where N: Into<Cow<'source, str>>, S: Into<Cow<'source, str>>,

Adds a template without borrowing.

This lets you place an owned String in the environment rather than the borrowed &str without having to worry about lifetimes.

let mut env = Environment::new();
env.add_template_owned("index.html".to_string(), "Hello {{ name }}!".to_string()).unwrap();

Note: the name is a bit of a misnomer as this API also allows to borrow too as the parameters are actually Cow. This method fails if the template has a syntax error.

pub fn set_loader<F>(&mut self, f: F)

where F: Fn(&str) -> Result<Option<String>, Error> + Send + Sync + 'static,

Register a template loader as source of templates.

When a template loader is registered, the environment gains the ability to dynamically load templates. The loader is invoked with the name of the template. If this template exists Ok(Some(template_source)) has to be returned, otherwise Ok(None). Once a template has been loaded it’s stored on the environment. This means the loader is only invoked once per template name.

For loading templates from the file system, you can use the path_loader function.

Example

fn create_env() -> Environment<'static> {
    let mut env = Environment::new();
    env.set_loader(|name| {
        if name == "layout.html" {
            Ok(Some("...".into()))
        } else {
            Ok(None)
        }
    });
    env
}

pub fn set_keep_trailing_newline(&mut self, yes: bool)

Preserve the trailing newline when rendering templates.

The default is false, which causes a single newline, if present, to be stripped from the end of the template.

This setting is used whenever a template is loaded into the environment. Changing it at a later point only affects future templates loaded.

pub fn keep_trailing_newline(&self) -> bool

Returns the value of the trailing newline preservation flag.

pub fn set_trim_blocks(&mut self, yes: bool)

Remove the first newline after a block.

If this is set to true then the first newline after a block is removed (block, not variable tag!). Defaults to false.

pub fn trim_blocks(&self) -> bool

Returns the value of the trim blocks flag.

pub fn set_lstrip_blocks(&mut self, yes: bool)

Remove leading spaces and tabs from the start of a line to a block.

If this is set to true then leading spaces and tabs from the start of a line to the block tag are removed.

pub fn lstrip_blocks(&self) -> bool

Returns the value of the lstrip blocks flag.

pub fn remove_template(&mut self, name: &str)

Removes a template by name.

pub fn set_path_join_callback<F>(&mut self, f: F)

where F: for<'s> Fn(&'s str, &'s str) -> Cow<'s, str> + Send + Sync + 'static,

Sets a callback to join template paths.

By default this returns the template path unchanged, but it can be used to implement relative path resolution between templates. The first argument to the callback is the name of the template to be loaded, the second argument is the parent path.

The following example demonstrates how a basic path joining algorithm can be implemented.

env.set_path_join_callback(|name, parent| {
    let mut rv = parent.split('/').collect::<Vec<_>>();
    rv.pop();
    name.split('/').for_each(|segment| match segment {
        "." => {}
        ".." => { rv.pop(); }
        _ => { rv.push(segment); }
    });
    rv.join("/").into()
});

pub fn set_unknown_method_callback<F>(&mut self, f: F)

where F: Fn(&State<'_, '_>, &Value, &str, &[Value]) -> Result<Value, Error> + Sync + Send + 'static,

Sets a callback invoked for unknown methods on objects.

This registers a function with the environment that is invoked when invoking a method on a value results in a UnknownMethod error. In that case the callback is invoked with State, the Value, the name of the method as &str as well as all arguments in a slice.

This for instance implements a .items() method that invokes the |items filter:

use minijinja::value::{ValueKind, from_args};
use minijinja::{Error, ErrorKind};

env.set_unknown_method_callback(|state, value, method, args| {
    if value.kind() == ValueKind::Map && method == "items" {
        let _: () = from_args(args)?;
        state.apply_filter("items", &[value.clone()])
    } else {
        Err(Error::from(ErrorKind::UnknownMethod))
    }
});

This can be used to increase the compatibility with Jinja2 templates that might call Python methods on objects which are not available in minijinja. A range of common Python methods is implemented in minijinja-contrib. For more information see minijinja_contrib::pycompat.

pub fn clear_templates(&mut self)

Removes all stored templates.

This method is mainly useful when combined with a loader as it causes the loader to “reload” templates. By calling this method one can trigger a reload.

pub fn templates(&self) -> impl Iterator<Item = (&str, Template<'_, '_>)>

Returns an iterator over the already loaded templates and their names.

Only templates that are already loaded will be returned.

let mut env = Environment::new();
env.add_template("hello.txt", "Hello {{ name }}!").unwrap();
env.add_template("goodbye.txt", "Goodbye {{ name }}!").unwrap();

for (name, tmpl) in env.templates() {
    println!("{}", tmpl.render(context!{ name => "World" }).unwrap());
}

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

Fetches a template by name.

This requires that the template has been loaded with add_template beforehand. If the template was not loaded an error of kind TemplateNotFound is returned. If a loader was added to the engine this can also dynamically load templates.

let mut env = Environment::new();
env.add_template("hello.txt", "Hello {{ name }}!").unwrap();
let tmpl = env.get_template("hello.txt").unwrap();
println!("{}", tmpl.render(context!{ name => "World" }).unwrap());

pub fn template_from_named_str( &self, name: &'source str, source: &'source str, ) -> Result<Template<'_, 'source>, Error>

Loads a template from a string.

In some cases you really only need to work with (eg: render) a template to be rendered once only.

let env = Environment::new();
let tmpl = env.template_from_named_str("template_name", "Hello {{ name }}").unwrap();
let rv = tmpl.render(context! { name => "World" });
println!("{}", rv.unwrap());

pub fn template_from_str( &self, source: &'source str, ) -> Result<Template<'_, 'source>, Error>

Loads a template from a string, with name <string>.

This is a shortcut to template_from_named_str with name set to <string>.

pub fn render_named_str<S>( &self, name: &str, source: &str, ctx: S, ) -> Result<String, Error>

where S: Serialize,

Parses and renders a template from a string in one go with name.

Like render_str, but provide a name for the template to be used instead of the default <string>. This is an alias for template_from_named_str paired with render.

let env = Environment::new();
let rv = env.render_named_str(
    "template_name",
    "Hello {{ name }}",
    context!{ name => "World" }
);
println!("{}", rv.unwrap());

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

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

where S: Serialize,

Parses and renders a template from a string in one go.

In some cases you really only need a template to be rendered once from a string and returned. The internal name of the template is <string>.

This is an alias for template_from_str paired with render.

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

pub fn set_auto_escape_callback<F>(&mut self, f: F)

where F: Fn(&str) -> AutoEscape + 'static + Sync + Send,

Sets a new function to select the default auto escaping.

This function is invoked when templates are loaded into the environment to determine the default auto escaping behavior. The function is invoked with the name of the template and can make an initial auto escaping decision based on that. The default implementation (default_auto_escape_callback) turn on escaping depending on the file extension.

env.set_auto_escape_callback(|name| {
    if matches!(name.rsplit('.').next().unwrap_or(""), "html" | "htm" | "aspx") {
        AutoEscape::Html
    } else {
        AutoEscape::None
    }
});

pub fn set_undefined_behavior(&mut self, behavior: UndefinedBehavior)

Changes the undefined behavior.

This changes the runtime behavior of undefined values in the template engine. For more information see UndefinedBehavior. The default is UndefinedBehavior::Lenient.

pub fn undefined_behavior(&self) -> UndefinedBehavior

Returns the current undefined behavior.

This is particularly useful if a filter function or similar wants to change its behavior with regards to undefined values.

pub fn set_formatter<F>(&mut self, f: F)

where F: Fn(&mut Output<'_>, &State<'_, '_>, &Value) -> Result<(), Error> + 'static + Sync + Send,

Sets a different formatter function.

The formatter is invoked to format the given value into the provided Output. The default implementation is escape_formatter.

When implementing a custom formatter it depends on if auto escaping should be supported or not. If auto escaping should be supported then it’s easiest to just wrap the default formatter. The following example swaps out None values before rendering for Undefined which renders as an empty string instead.

The current value of the auto escape flag can be retrieved directly from the State.

use minijinja::escape_formatter;
use minijinja::value::Value;

env.set_formatter(|out, state, value| {
    escape_formatter(
        out,
        state,
        if value.is_none() {
            &Value::UNDEFINED
        } else {
            value
        },
    )
});

pub fn set_debug(&mut self, enabled: bool)

Enable or disable the debug mode.

When the debug mode is enabled the engine will dump out some of the execution state together with the source information of the executing template when an error is created. The cost of this is relatively high as the data including the template source is cloned.

When this is enabled templates will print debug information with source context when the error is printed.

This requires the debug feature. This is enabled by default if debug assertions are enabled and false otherwise.

pub fn debug(&self) -> bool

Returns the current value of the debug flag.

pub fn set_recursion_limit(&mut self, level: usize)

Reconfigures the runtime recursion limit.

This defaults to 500. Raising it above that level requires the stacker feature to be enabled. Otherwise the limit is silently capped at that safe maximum. Note that the maximum is not necessarily safe if the thread uses a lot of stack space already, it’s just a value that was validated once to provide basic protection.

Every operation that requires recursion in MiniJinja increments an internal recursion counter. The actual cost attributed to that recursion depends on the cost of the operation. If statements and for loops for instance only increase the counter by 1, whereas template includes and macros might increase it to 10 or more.

Note on stack growth: even if the stacker feature is enabled it does not mean that in all cases stack can grow to the limits desired. For instance in WASM the maximum limits are additionally enforced by the runtime.

pub fn recursion_limit(&self) -> usize

Returns the current max recursion limit.

pub fn compile_expression( &self, expr: &'source str, ) -> Result<Expression<'_, 'source>, Error>

Compiles an expression.

This lets one compile an expression in the template language and receive the output. This lets one use the expressions of the language be used as a minimal scripting language. For more information and an example see Expression.

pub fn compile_expression_owned<E>( &self, expr: E, ) -> Result<Expression<'_, 'source>, Error>

where E: Into<Cow<'source, str>>,

Compiles an expression without capturing the lifetime.

This works exactly like compile_expression but lets you pass an owned string without capturing the lifetime.

pub fn add_filter<N, F, Rv, Args>(&mut self, name: N, f: F)

where N: Into<Cow<'source, str>>, F: Filter<Rv, Args> + for<'a> Filter<Rv, <Args as FunctionArgs<'a>>::Output>, Rv: FunctionResult, Args: for<'a> FunctionArgs<'a>,

Adds a new filter function.

Filter functions are functions that can be applied to values in templates. For details about filters have a look at Filter.

pub fn remove_filter(&mut self, name: &str)

Removes a filter by name.

pub fn add_test<N, F, Rv, Args>(&mut self, name: N, f: F)

where N: Into<Cow<'source, str>>, F: Test<Rv, Args> + for<'a> Test<Rv, <Args as FunctionArgs<'a>>::Output>, Rv: TestResult, Args: for<'a> FunctionArgs<'a>,

Adds a new test function.

Test functions are similar to filters but perform a check on a value where the return value is always true or false. For details about tests have a look at Test.

pub fn remove_test(&mut self, name: &str)

Removes a test by name.

pub fn add_function<N, F, Rv, Args>(&mut self, name: N, f: F)

where N: Into<Cow<'source, str>>, F: Function<Rv, Args> + for<'a> Function<Rv, <Args as FunctionArgs<'a>>::Output>, Rv: FunctionResult, Args: for<'a> FunctionArgs<'a>,

Adds a new global function.

For details about functions have a look at functions. Note that functions and other global variables share the same namespace. For more details about functions have a look at Function.

pub fn add_global<N, V>(&mut self, name: N, value: V)

where N: Into<Cow<'source, str>>, V: Into<Value>,

Adds a global variable.

pub fn remove_global(&mut self, name: &str)

Removes a global function or variable by name.

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

Returns an empty State for testing purposes and similar.

Trait Implementations

impl<'source> Clone for Environment<'source>

fn clone(&self) -> Environment<'source>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'source> Debug for Environment<'source>

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

Formats the value using the given formatter.

impl<'source> Default for Environment<'source>

fn default() -> Environment<'source>

Returns the “default value” for a type.