Struct minijinja::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. 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>>,

Available on crate feature loader only.

Adds a template without 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.

pub fn set_loader<F>(&mut self, f: F)where F: Fn(&str) -> Result<Option<String>, Error> + Send + Sync + 'static,

Available on crate feature loader only.

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 remove_template(&mut self, name: &str)

Removes a template by name.

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 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 loaded 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: Serialize>( &self, name: &str, source: &str, ctx: S ) -> Result<String, Error>

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: Serialize>( &self, source: &str, ctx: S ) -> Result<String, Error>

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 from 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)

Available on crate feature debug only.

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_syntax(&mut self, syntax: Syntax) -> Result<(), Error>

Available on crate feature custom_syntax only.

Sets the syntax for the environment.

Note that when source is used, the syntax is held on the underlying source which means that the actual source needs to have it’s syntax changed.

See Syntax for more information.

pub fn syntax(&self) -> &Syntax

Available on crate feature custom_syntax only.

Returns the current syntax.

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

Formats the value using the given formatter.

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

fn default() -> Self

Returns the “default value” for a type.