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
Structs
An evaluation context
An expression evaluation engine
A custom engine builder
Enums
Represents any valid JSON value.
Functions
evalDeprecated
eval_with_engineDeprecated
Evaluates the whole JSON
Evaluates the whole JSON with custom
Engine
Type Definitions
Evaluation engine filter signature
Evaluation engine function signature