Module minijinja::value

source ·
Expand description

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:

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

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

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.

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 prupose 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 and optionally SeqObject or StructObject 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 or macros.

To create a dynamic Value object, use Value::from_object, Value::from_seq_object, Value::from_struct_object or the From<Arc<T: Object>> implementations for Value:

#[derive(Debug)]
struct Foo;

impl Object for Foo {
    /* implementation */
}

let value = Value::from_object(Foo);
let value = Value::from(Arc::new(Foo));
let value = Value::from(Arc::new(Foo) as Arc<dyn Object>);

Structs

Enums

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 utility trait that represents a dynamic object.
  • SeqObject
    Provides the behavior of an Object holding sequence of values.
  • StructObject
    Provides the behavior of an Object holding a struct.

Functions