cellang 0.7.0

Interpreter for the CEL expression language
Documentation

Cellang

Cellang is an implementation of the CEL language interpreter in Rust.

Motivation

Motivation behind this project is to provide a way to evaluate CEL expressions in Rust, while allowing easier way to provide custom functions. This project is built for BountyHub project, but is open-source and can be used by anyone.

There is a great rust project called CEL Interpreter which I initially used.

However, I found that the project is not flexible enough for my needs. I needed to be able to:

  • Inspect the syntax tree during parsing for IDE/LSP support
  • Add slightly more complex functions on types
  • Robust error recovery for incomplete expressions

Therefore, the library exposes lower-level primitives that would allow you to do that.

Parser Architecture

Cellang uses a Rowan-based parser with a clean semantic boundary:

  1. Lexer (lexer) - Tokenizes source text into a stream of tokens
  2. Rowan Parser (parser::parse) - Builds a lossless concrete syntax tree (CST)
    • Preserves whitespace, comments, error tokens
    • Supports error recovery for IDE/LSP workflows
  3. HIR Lowering (parser::lower) - Converts CST to high-level intermediate representation
    • Strips away syntax noise (grouping parens, etc.)
    • Owned data structure suitable for semantic analysis
  4. Type Checking (parser::type_check) - Validates types and builds typed expression graph
  5. Interpreter (parser::eval) - Evaluates expressions against a runtime

Use only the canonical parser facade paths (cellang::parser::*) for parse/lower/type-check/eval pipeline access.

The separation between CST (syntax layer) and HIR (semantic layer) provides:

  • CST: Perfect for IDE tooling (preserves all source details, supports incremental parsing)
  • HIR: Perfect for semantic analysis (clean structure, no parser lifetimes)

Getting started

This library aims to be ergonomic without hiding the lower-level building blocks that make CEL powerful. The typical workflow is:

  1. Build a Runtime with variables, declared types, and native functions.
  2. Evaluate expressions against that runtime (or child runtimes that inherit the same environment).
use cellang::types::{FunctionDecl, OverloadDecl, Type};
use cellang::{Runtime, Value};

fn main() -> miette::Result<()> {
    let mut builder = Runtime::builder();
    builder.set_variable("first_name", "Ada")?;
    builder.set_variable("last_name", "Lovelace")?;
    builder.set_variable("roles", vec!["admin", "analyst"])?;

    let mut decl = FunctionDecl::new("full_name");
    decl.add_overload(OverloadDecl::new(
        "full_name_string_string",
        vec![Type::String, Type::String],
        Type::String,
    ))?;
    builder.add_function_decl(decl)?;
    builder.register_function("full_name", |first: String, last: String| {
        format!("{first} {last}")
    })?;

    let runtime = builder.build();
    let value = runtime.eval("full_name(first_name, last_name)")?;
    assert_eq!(value, Value::String("Ada Lovelace".into()));

    let is_admin = runtime.eval("'admin' in roles")?;
    assert_eq!(is_admin, Value::Bool(true));
    Ok(())
}

Runnable Examples

The examples in examples are written as user documentation and are also executed by cargo test, so they stay in sync with the public API.

Run all default-feature examples with:

cargo test -p cellang --examples

Run the derive-backed example with:

cargo test -p cellang --features derive --example user_role_derive

Good starting points:

Advanced Examples

For larger flows, prefer the checked examples over copying README snippets. examples/typed_environment.rs demonstrates explicit type metadata and compile-time rule validation, while examples/user_role_derive.rs demonstrates the optional derive feature for strongly typed Rust structs.

WebAssembly

Cellang can be compiled to wasm32-unknown-unknown behind the optional wasm feature. The bindings in src/wasm.rs expose an evaluateExpression helper and a reusable WasmRuntime class. Build the WebAssembly artifact with:

cargo build -p cellang --features wasm --target wasm32-unknown-unknown

For projects that expect JavaScript glue code, run wasm-pack build crates/cellang --features wasm --target web to generate the .wasm binary plus the corresponding JS module. JavaScript callers can then evaluate expressions provided that the environment is a JSON-serializable object:

import { evaluateExpression, WasmRuntime } from "cellang";

const result = await evaluateExpression("users.exists(u, u == name)", {
    users: ["alice", "bob"],
    name: "alice",
});

const runtime = new WasmRuntime({ greeting: "hello" });
const jsValue = runtime.evaluate("greeting.upperAscii() == 'HELLO'");

Both exports accept any value that serde_wasm_bindgen can convert (objects, arrays, scalars). Additional per-evaluation variables can be merged via runtime.withVariables({...}), which builds a scoped child runtime without mutating the original instance.