Jido. Expr
(Jido Action v3.0.0-beta.12)
View Source
Portable expressions and a shared, restricted helper DSL.
Expressions store fixed operators and data, never executable callbacks.
Host packages can share the same syntax through parse/2, then supply
their own reference parser, validator, and resolver. This module does not
depend on a host package or a reference namespace.
Author expressions
import Jido.Expr, only: [expr: 1]
calculation = expr(2 * 3 + 1)
{:ok, 7} = Jido.Expr.evaluate(calculation)Use ^value in expr/1 to insert a prebuilt value or host reference from
an Elixir variable. This is a trusted source-code boundary, not stored
expression syntax. Application calls, including calls inside a pin, are
rejected. A host parser does not accept pins by default.
The grammar supports ==, !=, <, <=, >, >=, in, and, or,
not, +, binary and unary -, *, /, div/2, rem/2, min/2,
max/2, abs/1, and <>. Supported operations follow native Elixir.
and and or require a Boolean left operand, short-circuit, and return the
evaluated right operand unchanged. not requires a Boolean. Parentheses
preserve native grouping and precedence; binary Boolean groups are not flattened.
Equality uses ==; list membership uses strict === and requires a proper
list. Ordering and min/max use Elixir term order, including mixed types.
Arithmetic accepts numbers; div and rem require integers. Concatenation
accepts binaries. There is no implicit conversion.
Literal data consists of atoms (including nil and Booleans), numbers,
binaries, proper lists, and maps with atom, integer, or binary keys. Host
references can supply data within the host's contract and the limits below.
Unsupported source forms, including tuples, ranges, arbitrary calls, unary
+, &&, ||, and strict equality syntax, are rejected.
The comparison aliases eq, neq, lt, lte, gt, and gte follow their
native counterparts. The separate all and any helpers accept a non-empty
list and require each evaluated operand to be Boolean. They short-circuit
and return a Boolean; they are not aliases for binary and and or.
These are V3 beta corrections. Stored Flow document versions stay unchanged.
Existing all and any records retain their strict helper behavior. Rebuild
earlier source expressions to obtain the binary and and or operators.
Existing membership, ordering, and min/max records use the corrected rules.
Resource limits
parse/2, validate/2, and evaluate/2 accept positive integer limits:
:max_depthdefaults to 64 nested data or expression levels.:max_nodesdefaults to 10,000 visited values, including resolved data and comparison work during evaluation.:max_binary_bytesdefaults to 1,048,576 cumulative bytes in visited binaries and generated results.:max_integer_bitsdefaults to 4,096 bits in each integer magnitude.
Limits cannot exceed 1,048,576,000. :max_integer_bits has a lower maximum
of 1,048,576 to keep the limit check itself bounded.
Limits apply to each call. Evaluation checks a Boolean group's operand-list shape within the remaining node limit before it short-circuits. A group with too many operands can fail even when its first operand determines the result. Skipped operands are not resolved or evaluated. Validation checks the complete tree. Resolve and validation callbacks belong to trusted host code and must themselves be bounded. Resolved values are checked as data and are never evaluated as expressions.
Summary
Types
Expression limits and trusted host integration callbacks.
One fixed operation with data or nested expression operands.
Functions
Evaluates an expression or data tree with bounded fixed operations.
Builds expression data from source; ^variable inserts trusted host data.
Constructs an expression after checking its operator and operand arity.
Constructs an expression, or raises Jido.Expr.Error.
Returns the closed list of canonical operator atoms.
Parses quoted source with the shared, inert expression grammar.
Parses quoted source, or raises on a parse failure.
Validates a complete expression or data tree without running operations.
Types
Functions
Evaluates an expression or data tree with bounded fixed operations.
A :resolve callback accepts a host struct and returns {:ok, value} or
{:error, error}. Unknown structs otherwise fail. Returned data is not
interpreted as expression code. Host errors pass through unchanged.
An arity-two callback also receives the current path. A returned
Jido.Expr.Error path is relative to that location.
Builds expression data from source; ^variable inserts trusted host data.
@spec new(atom(), [term()]) :: {:ok, t()} | {:error, Jido.Expr.Error.t()}
Constructs an expression after checking its operator and operand arity.
Constructs an expression, or raises Jido.Expr.Error.
@spec operators() :: [atom()]
Returns the closed list of canonical operator atoms.
Parses quoted source with the shared, inert expression grammar.
:leaf_parser can be a function that accepts an unknown AST node and
returns {:ok, host_value}, :error, or {:error, error}. The fixed
operator grammar takes precedence. Host errors pass through unchanged;
a returned Jido.Expr.Error path is relative to the parsed location.
The callback is trusted authoring code, not stored in the result. Neither
this function nor its default grammar evaluates source.
Parses quoted source, or raises on a parse failure.
Validates a complete expression or data tree without running operations.
A :validate_leaf callback can accept a host struct and return :ok or
{:error, error}. Unknown structs otherwise fail validation. Callback
errors pass through unchanged; expression errors include their tree path.
An arity-two callback also receives the current path. A returned
Jido.Expr.Error path is relative to that location.