Statifier.Interpreter (statifier v1.9.0)

View Source

Core interpreter for SCXML state charts.

Provides a synchronous, functional API for state chart execution. Documents from Statifier.parse are used as-is (already validated). Unvalidated documents are automatically validated for backward compatibility.

Summary

Functions

active?(state_chart, state_id)

Check if a specific state is currently active (including ancestors).

initialize(document)

Initialize a state chart from a parsed document.

initialize(document, opts)
send_event(state_chart, event)

Send an event to the state chart and return the new state (macrostep execution).

Functions

active?(state_chart, state_id)

@spec active?(Statifier.StateChart.t(), String.t()) :: boolean()

Check if a specific state is currently active (including ancestors).

initialize(document)

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

Initialize a state chart from a parsed document.

Documents from Statifier.parse are used directly (already validated). Unvalidated documents are validated automatically for backward compatibility.

Options

  • :log_adapter - Logging adapter configuration. Can be:

    • An adapter struct (e.g., %TestAdapter{max_entries: 100})
    • A tuple {AdapterModule, opts} (e.g., {TestAdapter, [max_entries: 50]})
    • If not provided, uses environment-specific defaults

  • :log_level - Minimum log level (:trace, :debug, :info, :warn, :error)

    • Defaults to :debug in test environment, :info otherwise

Examples

# Use default configuration
{:ok, state_chart} = Interpreter.initialize(document)

# Configure logging explicitly
{:ok, state_chart} = Interpreter.initialize(document, [
  log_adapter: {TestAdapter, [max_entries: 100]},
  log_level: :debug
])

initialize(document, opts)

@spec initialize(
  Statifier.Document.t(),
  keyword()
) :: {:ok, Statifier.StateChart.t()} | {:error, [String.t()], [String.t()]}

send_event(state_chart, event)

@spec send_event(Statifier.StateChart.t(), Statifier.Event.t()) ::
  {:ok, Statifier.StateChart.t()}

Send an event to the state chart and return the new state (macrostep execution).

Processes the event according to SCXML semantics:

  1. Find enabled transitions for the current configuration
  2. Execute the optimal transition set as a microstep
  3. Execute any resulting eventless transitions (additional microsteps)
  4. Return stable configuration (end of macrostep)

Returns the updated state chart. If no transitions match, returns the state chart unchanged (silent handling as discussed).