parsing/expression_evaluator_utils library

Safe expression evaluator (arithmetic + boolean) — roadmap #634.

Evaluates a string expression over a supplied variable map, with NO access to the host program — no function calls, no property access, no eval. Only numbers, strings, booleans, the named variables you pass in, and a fixed set of operators are understood, so untrusted formula input (a rule, a computed column, a feature flag condition) can be evaluated without executing arbitrary code.

Grammar (precedence low→high): ||, &&, == !=, < <= > >=, + -, * / %, unary ! -, then primaries: number, 'string'/"string", true, false, variable, ( … ). Lexing reuses the tokenize pipeline (#434). Any malformed input or type mismatch throws a FormatException; evaluation is eager (both sides of &&/|| are computed — fine for these side-effect- free operands).

Functions

evaluateBool(String expression, {Map<String, Object?> variables = const <String, Object?>{}}) → bool

Evaluates expression expecting a boolean result (the common case for a filter/condition); throws FormatException if it isn't boolean. Audited: 2026-06-12 11:26 EDT

evaluateExpression(String expression, {Map<String, Object?> variables = const <String, Object?>{}}) → Object?

Evaluates expression against variables, returning the result (a num, bool, or String). Throws FormatException on a syntax error, an unknown variable, or a type mismatch (e.g. adding a string).