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

evalDeprecated

eval_with_engineDeprecated

evaluate

Evaluates the whole JSON

evaluate_with_engine

Evaluates the whole JSON with custom Engine

Type Aliases

FilterFn

Evaluation engine filter signature

FunctionFn

Evaluation engine function signature