Crate balena_temen

balena templating engine

A crate that provides facilities to:

• parse an expression
• evaluate an expression
• evaluate an expression as a boolean (logical expressions)
• register custom functions and filters

Expression language documentation.

Versioning

This crate is being actively developed and it does NOT follow Semantic Versioning yet. It will follow semantic versioning when it reaches version 1.0.

MINOR version changes denotes incompatible API changes and PATCH version changes denotes both new functionality in a backwards-compatible manner and backwards-compatible bug fixes.

Examples

Helpers

JSON evaluation

use balena_temen::{evaluate, Value};
use serde_json::json;

let data = json!({
    "wifi": {
        "ssid": "Balena Ltd",
        "id": {
            "$$formula": "super.ssid | SLUGIFY"
        }
    }
});
let evaluated = json!({
    "wifi": {
        "ssid": "Balena Ltd",
        "id": "balena-ltd"
    }
});
assert_eq!(evaluate(data).unwrap(), evaluated);

JSON with custom evaluation keyword

use balena_temen::{Context, Engine, EngineBuilder, evaluate_with_engine, Value};
use serde_json::json;

let data = json!({
    "evalMePlease": "3 + 5 * 2"
});
let evaluated = json!(13);

let mut ctx = Context::default();
let engine: Engine = EngineBuilder::default()
    .eval_keyword("evalMePlease")
    .into();

assert_eq!(evaluate_with_engine(data, &engine, &mut ctx).unwrap(), evaluated);

Intermediate

Single expression evaluation

use balena_temen::{
    ast::Identifier,
    Engine, Context, Value
};
use serde_json::json;

let engine = Engine::default();       // Default functions, filters
let mut ctx = Context::default();     // Default context
let position = Identifier::default(); // Evaluate from the root
let data = Value::Null;

assert_eq!(
    engine.eval("2 + 3", &position, &data, &mut ctx).unwrap(),
    json!(5)
);

assert_eq!(
    engine.eval("`Balena templating engine!` | SLUGIFY", &position, &data, &mut ctx).unwrap(),
    json!("balena-templating-engine")
);

Single logical expression evaluation

use balena_temen::{
    ast::Identifier,
    Engine, Context, Value
};
use serde_json::json;

let engine = Engine::default();       // Default functions, filters
let mut ctx = Context::default();     // Default context
let position = Identifier::default(); // Evaluate from the root
let data = Value::Null;

assert_eq!(
    engine.eval_as_bool("1 == 1", &position, &data, &mut ctx).unwrap(),
    json!(true)
);

assert_eq!(
    engine.eval_as_bool("2 > 4", &position, &data, &mut ctx).unwrap(),
    json!(false)
);

assert_eq!(
    engine.eval_as_bool("1 > 4 or 3 > 2", &position, &data, &mut ctx).unwrap(),
    json!(true)
);

Advanced

Custom functions and filters

Visit EngineBuilder::function and EngineBuilder::filter methods documentation for examples.

Expression parsing

use balena_temen::ast::*;

// Parse expression automatically
let parsed: Expression = "1 + 2 == 3".parse().unwrap();

// Construct expression manually
let lhs = Expression::new(
    ExpressionValue::Math(
        MathExpression::new(
            Expression::new(ExpressionValue::Integer(1)),
            Expression::new(ExpressionValue::Integer(2)),
            MathOperator::Addition
        )
    )
);
let rhs = Expression::new(
    ExpressionValue::Integer(3)
);
let full_expression = Expression::new(
    ExpressionValue::Logical(
        LogicalExpression::new(
            lhs, rhs, LogicalOperator::Equal
        )
    )
);

// Compare and check that the expression was parsed correctly
assert_eq!(parsed, full_expression);

Visit ast module documentation for more info.

Identifier parsing

use balena_temen::ast::*;

let s = "wifi.networks[0].ssid";

// Parse it
let parsed: Identifier = s.parse().unwrap();

// Create manually
let manual = Identifier::default()
    .name("wifi")
    .name("networks")
    .index(0)
    .name("ssid");

assert_eq!(parsed, manual);

Modules

ast	An expression Abstract Syntax Tree
error	Error handling

Structs

Context	An evaluation context
Engine	An expression evaluation engine
EngineBuilder	A custom engine builder

Enums

Value

Represents any valid JSON value.

Functions

eval	Deprecated
eval_with_engine	Deprecated
evaluate	Evaluates the whole JSON
evaluate_with_engine	Evaluates the whole JSON with custom Engine

Type Definitions

FilterFn	Evaluation engine filter signature
FunctionFn	Evaluation engine function signature