#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

#Playground (browser WASM)

cd playground && python3 -m http.server 8000   # then open http://localhost:8000

• standard dialect · Eval mode — recommended; typed runtime semantics.
• standard dialect · Compile mode (strict) — the static checker runs first.
• classic dialect (legacy) — the v0.2 JS-semantics dialect; corpus-locked and receiving no new features.

moon build --target wasm-gc --release
cp _build/wasm-gc/release/build/playground/web/web.wasm playground/mbel.wasm

#User documentation

• English: docs/en (getting-started, environment & configuration, custom functions, visitor, patch, language definition)
• 中文: docs/zh(快速上手、环境与配置、自定义函数、visitor、patch、语言定义)

#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)

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

#Expression-defined user functions (JSON)

// params omitted: auto-extracted from the body's free identifiers
let resolved = @engine.Engine::add_expression_functions(
  inst,
  [{ name: "tax", params: None, body: "price * rate" }],
  Some(ctx), // unpassed params fall back to same-named env keys
)
// resolved == [("tax", ["price", "rate"])] — usable as tax(…), x | tax(),
// and (classic dialect) x|tax; pass None instead for purely lexical params

#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 26-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

#Dialects and evaluation modes (stage 4.4.5)

• Engine::eval(inst, src, ctx) — classic dialect (legacy): the v0.2 grammar, JS dynamic semantics (numbers are doubles, loose ==, substring in), locked by the compatibility differential corpus and the legacy test suites.
• Engine::eval_expr(inst, src, ctx) — standard dialect, Eval mode: full modern syntax, typed runtime semantics — integer literals and integer arithmetic are typed IntVal (int64, Go wrap), / is always float division (7/2 = 3.5, 1/0 = +Inf), % is integer-only, cross-kind comparisons/+ raise invalid operation: ... at runtime. No static checks.
• Engine::eval_expr_checked(inst, src, ctx) — standard dialect, Compile mode: runs the static checker first; statically-known type violations surface compile-mode messages (invalid operation: +(mismatched types int and string), non-bool expression (type int)used as condition).

#Current capabilities (classic dialect)

• 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 engine 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 — safety protections beyond the classic baseline.
• Verification: 111 MoonBit tests mirror the original Jest suites (lexer/parser/evaluator/API), and a differential harness runs 3 300+ expressions (hand-written corpus, generated fuzz, JSON-context corpus) against the original JavaScript implementation, requiring byte-identical output (tools/, docs/parity-contract.md).

#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

• 4.4 close-out: byte-string evaluation, position-carrying checker errors (行:列 with caret), classic-package physical split, Options alignment (env whitelist, AsBool), and the reference TestExpr 167-line want-table transcription.
• 4.5: full regex for matches (the MoonBit core regex is literal-only), full time objects/timezones, and implicit time-string arithmetic (request.Time - resource.Age < duration("24h")).

#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 original runtime
./tools/run_diff.sh tools/corpus_ctx.txt  # JSON-context corpus