minijinja 2.19.0

a powerful template engine for Rust with minimal dependencies
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

use std::collections::{BTreeMap, HashSet};
use std::fmt;

use serde::Serialize;

use crate::compiler::ast;
use crate::compiler::instructions::Instructions;
use crate::compiler::meta::find_undeclared;
use crate::compiler::parser::parse_expr;
use crate::environment::Environment;
use crate::error::Error;
use crate::output::Output;
use crate::value::Value;
use crate::vm::Vm;

/// A handle to a compiled expression.
///
/// An expression is created via the
/// [`compile_expression`](Environment::compile_expression) method.  It provides
/// a method to evaluate the expression and return the result as value object.
/// This for instance can be used to evaluate simple expressions from user
/// provided input to implement features such as dynamic filtering.
///
/// This is usually best paired with [`context`](crate::context!) to pass
/// a single value to it.
///
/// # Example
///
/// ```rust
/// # use minijinja::{Environment, context};
/// let env = Environment::new();
/// let expr = env.compile_expression("number > 10 and number < 20").unwrap();
/// let rv = expr.eval(context!(number => 15)).unwrap();
/// assert!(rv.is_true());
/// ```
pub struct Expression<'env, 'source> {
    env: &'env Environment<'source>,
    instr: ExpressionBacking<'source>,
}

enum ExpressionBacking<'source> {
    Borrowed(Instructions<'source>),
    Owned(crate::loader::OwnedInstructions),
}

impl fmt::Debug for Expression<'_, '_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Expression")
            .field("env", &self.env)
            .finish()
    }
}

impl<'env, 'source> Expression<'env, 'source> {
    pub(crate) fn new(
        env: &'env Environment<'source>,
        instructions: Instructions<'source>,
    ) -> Expression<'env, 'source> {
        Expression {
            env,
            instr: ExpressionBacking::Borrowed(instructions),
        }
    }

    pub(crate) fn new_owned(
        env: &'env Environment<'source>,
        instructions: crate::loader::OwnedInstructions,
    ) -> Expression<'env, 'source> {
        Expression {
            env,
            instr: ExpressionBacking::Owned(instructions),
        }
    }

    fn instructions(&self) -> &Instructions<'_> {
        match self.instr {
            ExpressionBacking::Borrowed(ref x) => x,
            ExpressionBacking::Owned(ref x) => x.borrow_dependent(),
        }
    }

    /// Evaluates the expression with some context.
    ///
    /// The result of the expression is returned as [`Value`].
    pub fn eval<S: Serialize>(&self, ctx: S) -> Result<Value, Error> {
        // reduce total amount of code falling under mono morphization into
        // this function, and share the rest in _eval.
        self._eval(Value::from_serialize(&ctx))
    }

    /// Returns a set of all undeclared variables in the expression.
    ///
    /// This works the same as
    /// [`Template::undeclared_variables`](crate::Template::undeclared_variables).
    pub fn undeclared_variables(&self, nested: bool) -> HashSet<String> {
        match parse_expr(self.instructions().source()) {
            Ok(expr) => find_undeclared(
                &ast::Stmt::EmitExpr(ast::Spanned::new(
                    ast::EmitExpr { expr },
                    Default::default(),
                )),
                nested,
            ),
            Err(_) => HashSet::new(),
        }
    }

    fn _eval(&self, root: Value) -> Result<Value, Error> {
        Ok(ok!(Vm::new(self.env).eval(
            self.instructions(),
            root,
            &BTreeMap::new(),
            &mut Output::null(),
            crate::AutoEscape::None,
        ))
        .0
        .expect("expression evaluation did not leave value on stack"))
    }
}