Crate balena_temen

source ·
Expand description

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": {
            "$$eval": "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

An expression Abstract Syntax Tree
Error handling

Structs

An evaluation context
An expression evaluation engine
A custom engine builder

Enums

Represents any valid JSON value.

Functions

evalDeprecated
Evaluates the whole JSON
Evaluates the whole JSON with custom Engine

Type Definitions

Evaluation engine filter signature
Evaluation engine function signature