SC.ValueEvaluator (sc v1.0.2)

View Source

Handles compilation and evaluation of SCXML value expressions using Predicator v3.0.

This module extends beyond boolean conditions to evaluate actual values from expressions, supporting nested property access, assignments, and complex data model operations.

Key features:

  • Value evaluation (not just boolean conditions)
  • Nested property access (user.profile.name)
  • Location path validation for assignments
  • Mixed access patterns (dot and bracket notation)
  • Type-safe value extraction

Examples

# Value evaluation
{:ok, compiled} = SC.ValueEvaluator.compile_expression("user.profile.name")
{:ok, value} = SC.ValueEvaluator.evaluate_value(compiled, context)
# => {:ok, "John Doe"}

# Location path validation for assignments
{:ok, path} = SC.ValueEvaluator.resolve_location("user.settings.theme", context)
# => {:ok, ["user", "settings", "theme"]}

Summary

Functions

assign_value(path_components, value, data_model)

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

compile_expression(expression)

Compile a value expression string into predicator instructions.

evaluate_and_assign(location_expr, value_expr, context)

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

evaluate_and_assign(location_expr, value_expr, context, compiled_expr)
evaluate_value(compiled_expr, context)

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, context)

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

Functions

assign_value(path_components, value, data_model)

@spec assign_value([String.t()], term(), map()) :: {:ok, map()} | {: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 a value expression string into predicator instructions.

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

evaluate_and_assign(location_expr, value_expr, context)

@spec evaluate_and_assign(String.t(), String.t(), map()) ::
  {:ok, map()} | {: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, context, compiled_expr)

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

evaluate_value(compiled_expr, context)

@spec evaluate_value(term() | nil, map()) :: {:ok, term()} | {:error, term()}

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

Context includes:

  • Current state configuration
  • Current event
  • Data model variables

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, context)

@spec resolve_location(String.t(), map()) :: {: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.