Expression Language

Evaluate dynamic expressions using expr-lang syntax. Compile and execute safe expressions for filtering, validation, and rule evaluation without full Lua execution.

Caching

expr.eval keeps an internal LRU cache of compiled expressions (default capacity 1000). The cache is built into the module and requires no configuration.

Loading

local expr = require("expr")

Evaluating Expressions

Evaluate an expression string and return the result. Uses internal LRU cache for compiled expressions:

-- Simple math
local result = expr.eval("1 + 2 * 3")  -- 7

-- With variables
local total = expr.eval("price * quantity", {
    price = 29.99,
    quantity = 3
})  -- 89.97

-- Boolean expressions
local is_adult = expr.eval("age >= 18", {age = 21})  -- true

-- String operations
local greeting = expr.eval('name + " is " + status', {
    name = "Alice",
    status = "online"
})  -- "Alice is online"

-- Ternary operator
local label = expr.eval('score > 90 ? "A" : score > 80 ? "B" : "C"', {
    score = 85
})  -- "B"

-- Array operations
local has_admin = expr.eval('"admin" in roles', {
    roles = {"user", "admin", "viewer"}
})  -- true

Returns: any, error

Compiling Expressions

Compile an expression into a reusable Program object for repeated evaluation:

-- Compile once for repeated use
local discount_calc, err = expr.compile("price * (1 - discount_rate)")
if err then
    return nil, err
end

-- Reuse with different inputs
local price1 = discount_calc:run({price = 100, discount_rate = 0.1})  -- 90
local price2 = discount_calc:run({price = 50, discount_rate = 0.2})   -- 40
local price3 = discount_calc:run({price = 200, discount_rate = 0.15}) -- 170

Returns: Program, error

Running Compiled Programs

Execute a compiled expression with provided environment:

-- Validation rule
local validator, _ = expr.compile("len(password) >= 8 and len(password) <= 128")

local valid1 = validator:run({password = "short"})       -- false
local valid2 = validator:run({password = "securepass123"}) -- true

-- Pricing rule
local pricer, _ = expr.compile([[
    base_price * quantity * (1 - bulk_discount) + shipping
]])

local order_total = pricer:run({
    base_price = 25.00,
    quantity = 10,
    bulk_discount = 0.15,
    shipping = 12.50
})  -- 225.00

Returns: any, error

Built-in Functions

Expr-lang provides many built-in functions:

-- Math functions
expr.eval("max(1, 5, 3)")        -- 5
expr.eval("min(10, 2, 8)")       -- 2
expr.eval("abs(-42)")            -- 42
expr.eval("ceil(3.2)")           -- 4
expr.eval("floor(3.8)")          -- 3

-- String functions
expr.eval('len("hello")')        -- 5
expr.eval('upper("hello")')      -- "HELLO"
expr.eval('lower("HELLO")')      -- "hello"
expr.eval('trim("  hi  ")')      -- "hi"
expr.eval('"hello" contains "ell"')  -- true

-- Array functions
expr.eval("len(items)", {items = {1,2,3}})  -- 3
expr.eval("sum(values)", {values = {1,2,3,4}})  -- 10

Errors

See Error Handling for working with errors.