tabulon

A high-performance, JIT-compiled expression evaluation engine for Rust, built on Cranelift.

tabulon parses simple arithmetic and boolean expressions and compiles them to native machine code at runtime. It is designed for applications like game servers, configuration scripts, or anywhere you need to safely and repeatedly evaluate user-provided expressions with maximum performance.

Features

• High-Performance JIT Compilation: Expressions are compiled to native machine code for near-native performance, powered by Cranelift.
• Rich Operator Support: Full support for arithmetic (+, -, *, /), comparison (==, !=, <, <=, >, >=), and logical (&&, ||) operators.
• Efficient & Safe:
  • Short-circuiting for if(...), &&, and || operators avoids unnecessary computation.
  • AST-level optimizations like constant folding are performed automatically.
  • All execution is sandboxed within the JIT engine.
• Extensible: Register your own custom Rust functions to be called from within an expression.
• Flexible: Use custom resolvers to map variables to your application's specific data structures.

Quick Start

Use the engine to compile and evaluate an expression:

use tabulon::Tabula;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a new engine instance
    let mut engine = Tabula::new();

    // Compile an expression
    let expr = engine.compile("power > 9000 && is_angry * 10")?;

    // `ordered_vars` shows the order variables must be supplied in.
    // Here it would be: ["power", "is_angry"]
    assert_eq!(expr.vars(), &["power", "is_angry"]);

    // Prepare variables for evaluation
    let power_level = 9001.0;
    let is_angry_val = 1.0; // Use 1.0 for true, 0.0 for false

    // `eval` takes a slice of your f64 variables
    let result = expr.eval(&[power_level, is_angry_val])?;

    // The expression "(9001 > 9000) && (1.0 * 10)" short-circuits AND and returns the
    // truthy RHS value (10.0) when both sides are true.
    assert_eq!(result, 10.0);
    println!("It's over 9000! Result: {}", result);

    Ok(())
}

Custom Functions

You can easily register your own Rust functions to be used in expressions.

use tabulon::{Tabula, function, register_functions};

// Use the `#[function]` attribute to make a function discoverable.
#[function]
pub fn custom_max(a: f64, b: f64) -> f64 {
    if a > b { a } else { b }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut engine = Tabula::new();

    // Register the function with the engine instance.
    register_functions!(engine, custom_max)?;

    let expr = engine.compile("custom_max(player_score, high_score) * 1.1")?;
    
    let player_score = 120.0;
    let high_score = 150.0;

    let result = expr.eval(&[player_score, high_score])?;

    assert_eq!(result, 165.0);
    println!("Potential new high score: {}", result);

    Ok(())
}

Built-in Functions and Operators

tabulon supports a rich set of built-in operators and functions.

Operators

Built-in Functions & Constructs

Boolean logic in tabulon follows the convention where 1.0 is true and 0.0 is false.

Examples

use tabulon::Tabula;

let mut engine = Tabula::new();

// Using the `if` function
let expr_if = engine.compile("if(health > 50, 100, 20)").unwrap();
let health = 75.0;
assert_eq!(expr_if.eval(&[health]).unwrap(), 100.0);

// Using `ifs` for multiple conditions
let expr_ifs = engine.compile("ifs(score > 90, 1, score > 50, 0.5, 0)").unwrap();
let score = 70.0;
assert_eq!(expr_ifs.eval(&[score]).unwrap(), 0.5);

// Using `min` and `max`
let expr_minmax = engine.compile("min(max(a, b), 100)").unwrap();
let a = 50.0;
let b = 120.0;
assert_eq!(expr_minmax.eval(&[a, b]).unwrap(), 100.0);

Performance

tabulon is designed for speed. By compiling expressions down to a few simple machine instructions, it can evaluate them orders of magnitude faster than a tree-walking interpreter. Benchmarks are included in the repository (cargo bench).

License

This project is licensed under the MIT License.