ExCellerate is a high-performance expression evaluation engine for Elixir.

It parses text expressions into an intermediate representation (IR), compiles the IR into Elixir AST, and builds a reusable function from it. Compiled functions are cached (keyed by expression and registry), so re-evaluating the same expression skips parsing and compilation.

Operators

• Arithmetic: +, -, *, /, ^ (power), % (modulo), n! (factorial)
• Comparison: ==, !=, <, <=, >, >=
• Logical: &&, ||, not
• Bitwise: &, |, |^ (xor), <<, >>, ~ (bnot)
• Ternary: condition ? true_val : false_val
• Data access: user.profile.name, list[0], list[-1], list[*].field (spread)

Built-in Functions

Math

String

Utility

Date & Time

Units for datedif and dateadd (singular or plural): "year(s)", "month(s)", "day(s)", "hour(s)", "minute(s)", "second(s)", "millisecond(s)".

All date functions accept Date, NaiveDateTime, and DateTime structs.

Special Forms

Custom functions can be added via the ExCellerate.Registry system.

Multi-line Expressions

Expressions can be formatted across multiple lines for readability. Newlines are treated as whitespace by the parser:

expr = """
ifs(
  score > 90, 'A',
  score > 80, 'B',
  score > 70, 'C',
  true, 'F'
)
"""

ExCellerate.eval!(expr, %{"score" => 85})
# => "B"

This works with validate/2 and compile/2 as well.

Nil Propagation

Dot and bracket access use nil propagation: if any key in a path is missing or the target is nil, the entire expression returns nil instead of raising an error. This mirrors how spreadsheets treat empty cells and avoids the need for defensive checks at every level of a nested path.

ExCellerate.eval!("user.profile.name", %{"user" => %{}})
# => nil  (profile is missing, so .name is never attempted)

ExCellerate.eval!("user.name", %{"user" => nil})
# => nil  (user is nil, short-circuits)

ExCellerate.eval!("list[99]", %{"list" => [1, 2, 3]})
# => nil  (index out of bounds)

Negative indices count from the end of the list, the same way they work in Elixir:

ExCellerate.eval!("items[-1]", %{"items" => [1, 2, 3]})
# => 3  (last element)

ExCellerate.eval!("items[-2]", %{"items" => [1, 2, 3]})
# => 2  (second to last)

Use ifnull/2, coalesce/2+, or a ternary to provide defaults:

ExCellerate.eval!("ifnull(user.name, 'anonymous')", %{"user" => %{}})
# => "anonymous"

Root variable lookup still raises. Referencing a variable that doesn't exist in the scope at all (e.g., unknown_var) is treated as a likely typo and returns {:error, %ExCellerate.Error{}}:

ExCellerate.eval("totally_unknown", %{})
# => {:error, %ExCellerate.Error{message: "variable not found: totally_unknown"}}

Examples

iex> ExCellerate.eval!("1 + 2 * 3")
7

iex> ExCellerate.eval("a + b", %{"a" => 10, "b" => 20})
{:ok, 30}

iex> ExCellerate.eval!("user.name", %{"user" => %{"name" => "Alice"}})
"Alice"

Column Spread ([*])

The [*] operator extracts a field from every element of a list, returning a new list of values. This enables column-oriented operations on lists of maps, structs, or nested lists:

# Given a list of maps in scope
scope = %{"orders" => [
  %{"product" => "Widget", "price" => 10, "qty" => 2},
  %{"product" => "Gadget", "price" => 25, "qty" => 1}
]}

ExCellerate.eval!("orders[*].product", scope)
# => ["Widget", "Gadget"]

ExCellerate.eval!("sum(orders[*].price)", scope)
# => 35

Spread results work with any function that accepts a list: sum, avg, max, min, len, and textjoin. Subsequent access chains apply to each element:

ExCellerate.eval!("orders[*].price", scope)       # => [10, 25]
ExCellerate.eval!("users[*].profile.name", scope)  # deep access

Bracket indexing after a spread selects a specific position from each element's sub-list:

# scores[1] from each row
ExCellerate.eval!("rows[*].scores[1]", scope)

Nested [*] operators flatten across levels:

 # departments[*].employees[*].name => all employee names, flattened

Computed Spread (.(expr))

To evaluate an expression per element of a spread, use the .(expr) syntax. Inside the parentheses, bare variable names resolve against each element rather than the outer scope:

ExCellerate.eval!("orders[*].(qty * price)", scope)
# => [20, 25]   (per-row product)

ExCellerate.eval!("sum(orders[*].(qty * price))", scope)
# => 45          (total of per-row products)

Computed spreads also compose with nested [*]:

# departments[*].employees[*].(salary * 12)  => annualised salaries, flattened

Let, Filter, and Table

let/3 introduces a lexical binding that is visible only inside the body expression; it does not mutate the outer scope:

# Given scope = %{"orders" => [%{"price" => 10, "qty" => 2}, ...]}
let(total, sum(orders[*].price), total + 5)

filter/2 selects items from a list using a boolean list produced by a computed spread. The predicate list must be the same length as the input list:

filter(orders, orders[*].(qty > 1))

table builds a list of maps from alternating key/list pairs. Use spread or computed spread to produce the list columns:

table('product', orders[*].product, 'total', orders[*].(qty * price))
# => [%{"product" => "Widget", "total" => 20}, ...]

These compose naturally — filter first, then build a summary table:

let(big, filter(orders, orders[*].(qty > 1)),
  table('product', big[*].product, 'total', big[*].(qty * price)))

Take and Slice

take/2 and take/3 extract rows, columns, or both from a list or 2D array. Positive counts take from the beginning, negative from the end. Pass null to skip a dimension:

take(data, 3)          # first 3 rows
take(data, -3)         # last 3 rows
take(data, null, 2)    # first 2 columns (all rows)
take(data, 2, 2)       # first 2 rows and 2 columns

slice/2 and slice/3 extract a contiguous section of a list by start index and optional length. The start index is zero-based, and negative indices count from the end:

slice(items, 1)        # from index 1 to end
slice(items, 1, 3)     # 3 elements starting at index 1
slice(items, -2)       # last 2 elements

Resource Limits

When evaluating untrusted expression strings, two guards bound the work a single expression can trigger. Both are configurable and fall back to safe defaults:

config :excellerate,
  max_expression_length: 10_000,  # max raw input size in bytes
  max_expression_depth: 100,       # max nesting depth of the parsed tree
  max_factorial_input: 10_000      # max operand for the `!` operator

Oversized input is rejected before parsing (a :parser error); expressions nested beyond max_expression_depth are rejected before compilation (a :compiler error); a factorial operand above max_factorial_input is rejected at evaluation (a :runtime error). Raise the limits if your expressions are legitimately large, deeply nested, or need large factorials.

Compilation Strategies

How an expression is executed is a pluggable strategy (ExCellerate.Compilation.Strategy). Two are built in:

• ExCellerate.Compilation.Interpreted (default) — evaluates via an interpreted Code.eval_quoted/3 closure. No atoms per expression. Safe for any input, and best for expressions evaluated only a few times where native's one-time compile cost would not amortize.
• ExCellerate.Compilation.NativeCompiled — compiles each expression into a real BEAM module and evaluates it as compiled code: substantially faster on the warm path with much lower per-call allocation. Each distinct compiled expression permanently consumes ~1 atom (an artifact of runtime module creation — the module pool bounds live module memory, not the atom table), so use it for a bounded, trusted set of expressions.

Opt into native compilation globally or per-registry:

config :excellerate, compilation: ExCellerate.Compilation.NativeCompiled

use ExCellerate.Registry, compilation: ExCellerate.Compilation.NativeCompiled

The ExCellerate.NativeCompiler process it needs is started on demand the first time a native compile happens (supervised by the :excellerate application), so there is no supervision wiring and it works whether native is selected globally or only on a single registry. Nothing is started for interpreted-only use.

The ExCellerate.Cache (compiled-function cache) is separate and opt-in — add it to your own supervision tree. See the README for the native_module_limit / native_purge_grace_ms knobs.