ExpressionParser Reference

Module defined in lua/common/jbeam/expressionParser.lua. Parses and evaluates $= expressions in JBeam data, providing a sandboxed math environment with variable substitution.

---

Exports

Functions

M.parseSafe(expr, vars)

Safely parses and evaluates a $= expression string. Strips the $= prefix, substitutes $ with var_ for Lua compatibility, validates no assignments exist, then evaluates in a sandboxed context. Catches errors via pcall.

• Parameters:
  • expr - string - Expression string starting with $= (e.g. "$=someVar * 2")
  • vars - table - Variable lookup table keyed by $name, values can be numbers or tables with .val field
• Returns: function - Compiled expression function

M.parse(expr, vars)

Parses and evaluates a $= expression without error protection (no pcall). Faster than parseSafe but will throw on errors.

• Parameters:
  • expr - string - Expression string starting with $=
  • vars - table - Variable lookup table keyed by $name
• Returns: any - Evaluated result (throws on error)

M.compileSafe(expr)

Compiles a $= expression into a reusable function without evaluating it. Creates an isolated context with its own variable wrapper so compiled functions can be re-evaluated with different variables.

• Parameters:
  • expr - string - Expression string starting with $=
• Returns: self (module table, for chaining)

Internal Notes

• The sandbox context includes: round, square, clamp, smoothstep, smootherstep, smoothmin, sign, case, vec3, quat, concat, include, print, and all math.* functions.
• The case(selector, ...) helper acts as a ternary for booleans or an n-way selector for integers.
• include(resourceURI, sheetName, cellRef) supports loading external .csv and .xlsx files into expressions.
• The $ character in expressions is rewritten to var_ prefix for Lua variable names. The metatable on context handles $variable lookups.
• Assignment detection: single = not preceded by <, >, ~, or = triggers an error to prevent code injection.
• Lazy-loads csvlib and xlsxlib on first use.

---

See Also

• Groups Reference - Related reference
• Interaction Reference - Related reference
• IO Reference - Related reference
• Common Libraries Overview - Guide