balena-io-modules / balena-temen

Balena TEMplating ENgine

balena temen

A templating engine for JSON.

Provides facilities to:

• evaluate JSON
• evaluate JSON with custom evaluation keyword, functions and filters
• evaluate single expression (result is of any type)
• evaluate single logical expression (result is a boolean)
• retrieve AST of any expression / identifier

_{an open source 📡 project by balena.io}

Goal

balena-temen crate is one small piece of the balena.io configuration project. This project has no public / open specification yet, but we're working on it and it will be public once finished.

Supported platforms

This library is written in the Rust language and can be used:

• directly, as a Rust crate
• as an isomorphic NPM package (NodeJS & browser)

Documentation

• API documentation
• Expression language documentation
• Changelog

Breaking changes

Version 0.3

• Python style kwargs were removed in favor of positional arguments. All functions and filters do accept positional arguments only.
• NOW() function accepts one boolean argument only

Version 0.2

• All function and filter identifiers were uppercased
  • An example uuidv4() -> UUIDV4()

Version 0.1

$$eval keyword was renamed to $$formula. You can still use $$eval if you want by instantiating your own Engine with the EngineBuilder and custom eval keyword registration.

Usage

Rust

Add as a dependency to your Cargo.toml:

[dependencies]
balena-temen = "0.1"

Evaluate simple JSON:

use balena_temen::evaluate;
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);

Javascript

Install via npm

npm install --save balena-temen

Evaluate simple JSON:

const bt = require('balena-temen');

console.log(
    bt.evaluate({
        "ssid": "Some Cool SSID!",
        "id": {
            "$$formula": "super.ssid | slugify"
        }
    })
);

An example of using this module in nodeJS is available in the examples/node folder:

cd examples/node
npm install
npm start

An example of using this module in the browser is available in the examples/browser folder:

cd examples/browser
npm install
npm start

Open localhost:8080 in your browser and you should see evaluated JSON in the browser console.

Support

If you're having any problem, please raise an issue on GitHub or contact us, and the balena.io team will be happy to help.

License

balena-temen is open source software, and may be redistributed under the terms specified in the license.