Statifier.Evaluator (statifier v1.9.0)

View Source

Unified expression evaluation for SCXML using Predicator.

This module handles both condition evaluation (boolean results) and value evaluation (extracting actual values) for SCXML expressions. It supports:

  • Conditional expressions for transitions and guards
  • Value expressions for assignments and data manipulation
  • Location path resolution for assignments
  • Assignment operations with type-safe updates
  • Nested property access and mixed notation
  • SCXML built-in functions (In() for state checks)
  • Event data access and datamodel variables

Examples

# Condition evaluation
{:ok, compiled} = Statifier.Evaluator.compile_expression("score > 80")
result = Statifier.Evaluator.evaluate_condition(compiled, state_chart)
# => true or false

# Value evaluation
{:ok, compiled} = Statifier.Evaluator.compile_expression("user.name")
{:ok, value} = Statifier.Evaluator.evaluate_value(compiled, state_chart)
# => {:ok, "John Doe"}

# Assignment operations
{:ok, updated_datamodel} = Statifier.Evaluator.evaluate_and_assign(
  "user.profile.name",
  "'Jane Smith'",
  state_chart
)

Summary

Functions

assign_value(path_components, value, datamodel)

Assign a value to a location in the data model using the resolved path.

compile_expression(expression)

Compile an expression string into predicator instructions for reuse.

evaluate_and_assign(location_expr, value_expr, state_chart)

Evaluate an expression and assign its result to a location in the data model.

evaluate_and_assign(location_expr, value_expr, state_chart, compiled_expr)
evaluate_condition(compiled_cond, state_chart)

Evaluate a compiled condition with SCXML context.

evaluate_param(param, state_chart)

Evaluates a single SCXML parameter and returns its name-value pair.

evaluate_params(params, state_chart, opts \\ [])

Evaluates a list of SCXML parameters and returns a map of name-value pairs.

evaluate_value(compiled_expr, state_chart)

Evaluate a compiled expression to extract its value (not just boolean result).

resolve_location(location_expr)

Resolve a location path from a string expression only (without context validation).

resolve_location(location_expr, state_chart)

Resolve a location path for assignment operations using predicator v3.0's context_location.

Functions

assign_value(path_components, value, datamodel)

@spec assign_value([String.t()], term(), Statifier.Datamodel.t()) ::
  {:ok, Statifier.Datamodel.t()} | {:error, term()}

Assign a value to a location in the data model using the resolved path.

This performs the actual assignment operation after location validation.

compile_expression(expression)

@spec compile_expression(String.t() | nil) ::
  {:ok, term()} | {:error, term()} | {:ok, nil}

Compile an expression string into predicator instructions for reuse.

Returns {:ok, compiled} on success, {:error, reason} on failure.

evaluate_and_assign(location_expr, value_expr, state_chart)

@spec evaluate_and_assign(String.t(), String.t(), Statifier.StateChart.t()) ::
  {:ok, Statifier.Datamodel.t()} | {:error, term()}

Evaluate an expression and assign its result to a location in the data model.

This combines expression evaluation with location-based assignment. If a pre-compiled expression is provided, it will be used for better performance.

evaluate_and_assign(location_expr, value_expr, state_chart, compiled_expr)

@spec evaluate_and_assign(
  String.t(),
  String.t(),
  Statifier.StateChart.t(),
  term() | nil
) ::
  {:ok, Statifier.Datamodel.t()} | {:error, term()}

evaluate_condition(compiled_cond, state_chart)

@spec evaluate_condition(term() | nil, Statifier.StateChart.t()) :: boolean()

Evaluate a compiled condition with SCXML context.

Takes a StateChart to build evaluation context. Returns boolean result. On error, returns false per SCXML spec.

evaluate_param(param, state_chart)

@spec evaluate_param(Statifier.Actions.Param.t(), Statifier.StateChart.t()) ::
  {:ok, {String.t(), term()}} | {:error, String.t()}

Evaluates a single SCXML parameter and returns its name-value pair.

evaluate_params(params, state_chart, opts \\ [])

@spec evaluate_params(
  [Statifier.Actions.Param.t()],
  Statifier.StateChart.t(),
  keyword()
) ::
  {:ok, map()} | {:error, String.t()}

Evaluates a list of SCXML parameters and returns a map of name-value pairs.

Supports both strict mode (fail on first error) and lenient mode (skip failed params). This is the central parameter evaluation logic used by both SendAction and InvokeAction.

Options

  • :error_handling - :strict (InvokeAction style - fail on first error) or :lenient (SendAction style - skip failed params)

evaluate_value(compiled_expr, state_chart)

@spec evaluate_value(term() | nil, Statifier.StateChart.t()) ::
  {:ok, term()} | {:error, term()}

Evaluate a compiled expression to extract its value (not just boolean result).

Takes a StateChart to build evaluation context. Returns {:ok, value} on success, {:error, reason} on failure.

resolve_location(location_expr)

@spec resolve_location(String.t()) :: {:ok, [String.t()]} | {:error, term()}

Resolve a location path from a string expression only (without context validation).

This is useful when you need to determine the assignment path structure before evaluating against a specific context.

Returns {:ok, path_list} on success, {:error, reason} on failure.

resolve_location(location_expr, state_chart)

@spec resolve_location(String.t(), Statifier.StateChart.t()) ::
  {:ok, [String.t()]} | {:error, term()}

Resolve a location path for assignment operations using predicator v3.0's context_location.

This validates that the location is assignable and returns the path components for safe data model updates.

Returns {:ok, path_list} on success, {:error, reason} on failure.