Expressions

An ordered array of plugins that extend the evaluator's tokenization, parsing, optimization, and evaluation capabilities. LyteNyte Grid tries plugins in the order they appear. The first plugin that returns a non-null result for a given node or token takes precedence. Omit this argument to create a minimal evaluator that supports arithmetic only.

Parses and optimizes an expression string and returns the resulting ASTNode. Use this to separate the parse step from evaluation when the expression is evaluated repeatedly. The returned node can be passed directly to run.

Throws ExpressionError if the expression is syntactically invalid.

Evaluates an expression and returns its result. Accepts either a raw expression string or a pre-parsed ASTNode. Pass a pre-parsed AST to skip re-parsing when the same expression is evaluated many times (e.g. once per row in a filter or computed field).

Throws ExpressionError if the expression is syntactically invalid or references an identifier that is not present in the context. Set options.undefinedIdentifierFallback to suppress identifier errors and return a fallback value instead.

Tokenizes an expression string and returns the token array. Throws ExpressionError on the first invalid character or token sequence. Prefer tokensSafe when using the result for syntax highlighting, where partial or invalid input is expected.

Tokenizes an expression string without throwing when it encounters invalid input. When the tokenizer finds an unrecognized character, it emits an ExpressionError token and continues tokenizing the rest of the string. The returned array includes tokens that span the full input string.

Pass tokenizeWhitespace: true to include whitespace tokens in the output. ExpressionEditor requires whitespace tokens when using the token array for syntax highlighting.

The fallback value the evaluator returns when an identifier is missing from the context. Without this fallback, the evaluator throws an error.

Set undefinedIdentifierFallback to true in filter functions so partially typed expressions pass all rows instead of crashing. Set it to undefined in computed field functions so cells render empty values for unknown identifiers.

A human-friendly display name for the column.

Evaluation hook. Called for each AST node at runtime. The third argument is a recursive evaluator; call it on child nodes to compute their values. Return value: result to claim the node, or null to pass to the next plugin. The value wrapper is required to distinguish a result of undefined from a null "not handled" signal.

Returns the binding precedence of the infix operator at the current token position, or undefined if the current token is not handled by this plugin. Required whenever parseInfix is implemented; the parser will not call parseInfix unless infixPrecedence returns a number first.

Optimization hook. Called on each AST node after parsing. Use it to constant-fold or simplify your custom node types before evaluation. The second argument is a recursive optimizer; call it on child nodes to propagate optimization through the tree. Return the (possibly modified) node, or null to leave the node unhandled.

Parsing hook for binary operators that sit between two terms. Called with the left operand already parsed. Use alongside infixPrecedence to declare the operator's binding strength. Check prec < minPrec before consuming anything and return null if the operator should not bind at the current precedence level.

Parsing hook for forms that trail a completed term: member access (.), computed access ([]), optional chaining (?.), and function calls (()) are all implemented as postfix hooks. Called repeatedly after a primary expression is parsed, as long as at least one plugin returns a non-null value.

Parsing hook for expression forms that begin a new term: literals, prefix operators, parenthesised groups, and any other syntax that starts with a known token. Called when the parser needs a primary expression. Inspect current(ctx) to decide whether to handle the token; advance past consumed tokens with advance(ctx). Return an ASTNode to claim the term, or null to pass.

Parsing hook for unary wrappers that consume the next term. Receives a parseNext function to parse the operand. Most unary operators fit parsePrefix instead; use this hook only when you need to wrap the entire subsequent parse step rather than just the next primary expression.

Tokenization hook. Called at each source position the built-in tokenizer does not recognise. Return a token descriptor to claim the characters starting at pos, or null to pass. The end field in the return value is a source position (not a length); it must point to the first character after the consumed token.