#mbel — Expression Engine for MoonBit

#Quick start (CLI)

$ moon run cmd/main -- "1 + 2 * 3"
7

$ moon run cmd/main -- "'hello' + ' ' + 'world'"
"hello world"

$ moon run cmd/main -- "6+x*2>10 ? 'big' : 'small'" '{"x": 3}'
"big"

$ moon run cmd/main -- "age * (3 - 1)" '{"age": 36}'
72

$ moon run cmd/main -- 'assoc[.first == "Lana"].last' \
  '{"assoc": [{"first": "Lana", "last": "Kane"}, {"first": "Cyril", "last": "Figgis"}]}'
"Kane"

$ moon run cmd/main -- "user.name + ' scored ' + (score * 10)" \
  '{"user": {"name": "alice"}, "score": 8.5}'
"alice scored 85"

$ moon run cmd/main -- "items[.price <= 2].name" \
  '{"items": [{"name": "apple", "price": 1.5}, {"name": "pear", "price": 3}]}'
"apple"

$ moon run cmd/main -- "map(nums, # * 2)" '{"nums": [1, 2, 3, 4, 5]}'
[2,4,6,8,10]

$ moon run cmd/main -- "filter(users, .age >= 18)[0].name" \
  '{"users": [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 15}]}'
"Alice"

$ moon run cmd/main -- "sum(1..100)"
5050

$ moon run cmd/main -- "count(users, .age >= 18)" \
  '{"users": [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 15}, {"name": "Cyx", "age": 24}]}'
2

$ moon run cmd/main -- "groupBy(nums, # % 2)" '{"nums": [1, 2, 3, 4, 5]}'
{"1":[1,3,5],"0":[2,4]}

$ moon run cmd/main -- "reduce(nums, #acc + #, 100)" '{"nums": [1, 2, 3, 4, 5]}'
115

$ moon run cmd/main -- "[1,2,3]|first"
1

$ moon run cmd/main -- "5|dbl|dbl"
20

#Using mbel as a library

import {
  "dimon-83/mbel/ast",
  "dimon-83/mbel/evaluator",
  "dimon-83/mbel/engine",
}

let inst = @engine.new()

// Evaluate against a context
let ctx = @ast.ObjectVal([
  ("user", @ast.ObjectVal([("age", @ast.NumVal(36.0))])),
])
let v = try {
  @engine.Engine::eval(inst, "user.age > 18 ? 'adult' : 'minor'", ctx)
} catch {
  @engine.EngineErr(msg) => abort(msg)
} // StrVal("adult")

// Register transforms / functions / operators
@engine.Engine::add_transform(
  inst,
  "dbl",
  fn(args : Array[@ast.Value]) -> @ast.Value {
    @ast.NumVal(@evaluator.to_number(args[0]) * 2.0)
  },
)
let doubled = try {
  @engine.Engine::eval(inst, "21|dbl", @ast.ObjectVal([]))
} catch {
  @engine.EngineErr(msg) => abort(msg)
} // NumVal(42.0)

// expr-style resource budgets: nodes at parse time, depth + steps at
// eval time (0 disables a limit)
@engine.Engine::set_limits(inst, 10000, 10000, 1000000)

#Choosing an engine: Walk (tree-walk) or Vm (bytecode)

// Walk — the reference tree-walk interpreter (default)
let walk_inst = @engine.new()
@engine.Engine::set_engine(walk_inst, Walk)

// Vm — compiles the (constant-folded) AST to bytecode once per
// Expression, caches the program, and runs a 16-opcode stack machine
let vm_inst = @engine.new()
@engine.Engine::set_engine(vm_inst, Vm)

// Both engines run the same expressions, transforms, and budgets
let ctx = @ast.ObjectVal([("x", @ast.NumVal(3.0))])
let a = @engine.Engine::eval(walk_inst, "6+x*2>10 ? 'big' : 'small'", ctx)
let b = @engine.Engine::eval(vm_inst, "6+x*2>10 ? 'big' : 'small'", ctx)
// value_equal(a, b) — always true; vm_parity tests enforce it

// The CLI can run either engine too:
//   moon run cmd/main -- "2+2*3" "" vm

#Current capabilities (Jexl parity)

• Literals: numbers, single/double-quoted strings with escapes, booleans; array and object literals ({a: 1, "b": 2}).
• Operators: arithmetic + - * / // % ^, comparison == != > >= < <= with JavaScript coercion semantics, logic && || !, in (substring / array membership), ternary ?: including the a ?: b form.
• Access: dotted chains a.b.c, computed keys obj["k"], array indexing, relative filters arr[.x == 1] with element-0 drill semantics, transforms via | pipes (foo|toUpper), and custom function calls f(x).
• Extensibility: add_transform, add_function, add_binary_op (incl. manual/lazy operand evaluation), add_unary_op, remove_op, get_transform / get_function — each Jexl instance owns an isolated grammar (elements can be added and removed per instance).
• Safety: configurable node limit (default 10 000), sub-expression nesting limit, eval depth and shared step budgets — the expr-style protections that plain Jexl lacks.
• Verification: 111 MoonBit tests mirror the Jexl Jest suites (lexer/parser/evaluator/API), and a differential harness runs 3 300+ expressions (hand-written corpus, generated fuzz, JSON-context corpus) through both mbel and the real Jexl, requiring byte-identical output (tools/, docs/parity-contract.md).

#expr-lang builtins already available

$ moon run cmd/main -- "median([1, 9, 5])"
5

$ moon run cmd/main -- "fromBase64(toBase64("héllo ✓"))"
"héllo ✓"

$ moon run cmd/main -- "missing ?? 'fallback'"
"fallback"

$ moon run cmd/main -- "sort([3,1,2]) | first"
1

#Roadmap — aligning with expr-lang

• Language front-end (4.4 remainder): {expr} brace-wrapped predicate blocks, if/else blocks, let declarations + sequences, slices [:], optional chaining ?., chained comparisons, not in, right-assoc **, hex/oct/binary/exponent literals, raw strings and byte strings, comments, $env, int/float type system + static type checker with 行:列 error locations.
• Dependencies (4.5): full RE2-style regex for matches (the MoonBit core regex is literal-only), full time objects/timezones.
• Vm v2 remainder: let variable slots, slice/optional-chain instructions, disassembler output.
• Strings: trim, upper/lower, split, replace, repeat, indexOf, hasPrefix/hasSuffix, and regex matching matches.
• Date & time: now(), duration(), date() (multiple layouts, timezones), timezone(), date arithmetic and comparison.
• Numbers: max/min/abs, ceil/floor/round, array statistics sum/mean/median.
• Arrays & collections: predicates all/any/one/none, map/filter, find/findIndex/..., groupBy, count, concat, flatten, uniq, join, reduce, sort/sortBy, reverse, first/last/take. — DELIVERED 4.4.2 (57/64 builtins total).
• Maps: keys, values, toPairs/fromPairs.
• Type & encoding: type(), int/float/string conversions, toJSON/fromJSON, toBase64/fromBase64.
• Bitwise: bitand/bitor/bitxor/bitnand/bitnot/bitshl/bitshr/bitushr.
• Variables & scope: let declarations, $env, predicate expressions with # / #acc / #index.

#Performance & stability report (Walk vs Vm)

⚠️ The Vm columns of earlier reports (2026-09-06, incl. the tables in docs/perf-report.md) are invalid: the end-to-end Expression::eval never dispatched to the Vm engine until f37f10d, so those "Vm" measurements were the tree-walk engine. The tables below and docs/coverage-vs-expr.md §7 are the first genuine dual-engine data.

#Development

moon test                       # 168 unit/parity tests (add --target native|js)
moon run cmd/main -- "2+2"      # expression runner
./tools/run_diff.sh tools/corpus.txt      # differential check vs Jexl
./tools/run_diff.sh tools/corpus_ctx.txt  # JSON-context corpus