Module value

Provides a dynamic value type abstraction.

This module gives access to a dynamically typed value which is used by the template engine during execution.

For the most part the existence of the value type can be ignored as MiniJinja will perform the necessary conversions for you. For instance if you write a filter that converts a string you can directly declare the filter to take a String. However for some more advanced use cases it’s useful to know that this type exists.

Basic Value Conversions

Values are typically created via the From trait:

let int_value = Value::from(42);
let none_value = Value::from(());
let true_value = Value::from(true);

Or via the FromIterator trait which can create sequences or maps:

// collection into a sequence
let value: Value = (1..10).into_iter().collect();

// collection into a map
let value: Value = [("key", "value")].into_iter().collect();

For certain types of iterators (Send + Sync + 'static) it’s also possible to make the value lazily iterate over the value by using the Value::make_iterable function instead. Whenever the value requires iteration, the function is called to create that iterator.

let value: Value = Value::make_iterable(|| 1..10);

To to into the inverse directly the various TryFrom implementations can be used:

use std::convert::TryFrom;
let v = u64::try_from(Value::from(42)).unwrap();

The special Undefined value also exists but does not have a rust equivalent. It can be created via the UNDEFINED constant.

Serde Conversions

MiniJinja will usually however create values via an indirection via serde when a template is rendered or an expression is evaluated. This can also be triggered manually by using the Value::from_serializable method:

let value = Value::from_serializable(&[1, 2, 3]);

The inverse of that operation is to pass a value directly as serializer to a type that supports deserialization. This requires the deserialization feature.

use serde::Deserialize;
let value = Value::from(vec![1, 2, 3]);
let vec = Vec::<i32>::deserialize(value).unwrap();

Value Function Arguments

Filters and tests can take values as arguments but optionally also rust types directly. This conversion for function arguments is performed by the FunctionArgs and related traits (ArgType, FunctionResult).

Memory Management

Values are immutable objects which are internally reference counted which means they can be copied relatively cheaply. Special care must be taken so that cycles are not created to avoid causing memory leaks.

HTML Escaping

MiniJinja inherits the general desire to be clever about escaping. For this purpose a value will (when auto escaping is enabled) always be escaped. To prevent this behavior the safe filter can be used in the template. Outside of templates the Value::from_safe_string method can be used to achieve the same result.

Dynamic Objects

Values can also hold “dynamic” objects. These are objects which implement the Object trait. These can be used to implement dynamic functionality such as stateful values and more. Dynamic objects are internally also used to implement the special loop variable, macros and similar things.

To create a Value from a dynamic object use Value::from_object, Value::from_dyn_object:

#[derive(Debug)]
struct Foo;

impl Object for Foo {
    /* implementation */
}

let value = Value::from_object(Foo);
let value = Value::from_dyn_object(Arc::new(Foo));

Structs

DynObject

Typed-erased version of Object

Kwargs

Utility to accept keyword arguments.

Rest

Utility type to capture remaining arguments.

Value

Represents a dynamically typed value in the template engine.

ValueIter

Utility to iterate over values.

ViaDeserialize

Utility type to deserialize an argument.

Enums

Enumerator

Enumerators help define iteration behavior for Objects.

ObjectRepr

Defines the natural representation of this object.

ValueKind

Describes the kind of value.

Traits

ArgType

A trait implemented by all filter/test argument types.

FunctionArgs

Helper trait representing valid filter, test and function arguments.

FunctionResult

A utility trait that represents the return value of functions and filters.

Object

A trait that represents a dynamic object.

ObjectExt

Provides utility methods for working with objects.

Functions

from_args

Utility function to convert a slice of values into arguments.

intern

Intern a string.

serializing_for_value

Function that returns true when serialization for Value is taking place.