[−][src]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 |
Type Definitions
FilterFn | Evaluation engine filter signature |
FunctionFn | Evaluation engine function signature |