scamper/config

Configuration builder for scamper finite state machines.

Build a config using the pipeline operator:

config.new(timestamp_fn)
|> config.add_transition(from: Idle, on: Start, to: Running)
|> config.add_guarded_transition(from: Running, on: Complete, guard: is_valid, to: Done)
|> config.set_final_states([Done, Failed])
|> config.set_on_enter(Running, start_handler)
|> config.set_event_policy(config.Ignore)
|> config.set_history_limit(100)

Types

Config

opaque </>

Opaque configuration for a finite state machine.

pub opaque type Config(state, context, event)

EventPolicy

</>

Policy for handling events that have no matching transition rule.

pub type EventPolicy {
  Reject
  Ignore
}

Constructors

```
Reject
```
Return an InvalidTransition error (default).
```
Ignore
```
Silently return the machine unchanged.

StateCallback

</>

Callback invoked when entering or exiting a state. Receives the state and current context, returns updated context or error.

pub type StateCallback(state, context) =
  fn(state, context) -> Result(context, String)

TransitionCallback

</>

Callback invoked during a transition. Receives (from, event, to, context), returns updated context or error.

pub type TransitionCallback(state, context, event) =
  fn(state, event, state, context) -> Result(context, String)

TransitionRule

</>

A single transition rule in the transition table.

pub type TransitionRule(state, context, event) {
  TransitionRule(
    from: state,
    on: event,
    to: state,
    guard: option.Option(fn(context, event) -> Bool),
  )
}

Constructors

TransitionRule(
  from: state,
  on: event,
  to: state,
  guard: option.Option(fn(context, event) -> Bool),
)

Values

add_global_on_enter

</>

pub fn add_global_on_enter(
  config: Config(state, context, event),
  callback: fn(state, context) -> Result(context, String),
) -> Config(state, context, event)

Add a global on_enter callback (runs for all transitions).

add_global_on_exit

</>

pub fn add_global_on_exit(
  config: Config(state, context, event),
  callback: fn(state, context) -> Result(context, String),
) -> Config(state, context, event)

Add a global on_exit callback (runs for all transitions).

add_global_on_transition

</>

pub fn add_global_on_transition(
  config: Config(state, context, event),
  callback: fn(state, event, state, context) -> Result(
    context,
    String,
  ),
) -> Config(state, context, event)

Add a global on_transition callback (runs for all transitions).

add_guarded_transition

</>

pub fn add_guarded_transition(
  config: Config(state, context, event),
  from from: state,
  on on: event,
  guard guard: fn(context, event) -> Bool,
  to to: state,
) -> Config(state, context, event)

Add a guarded transition rule.

add_invariant

</>

pub fn add_invariant(
  config: Config(state, context, event),
  invariant: fn(context) -> Result(Nil, String),
) -> Config(state, context, event)

Add a context invariant that is checked after every successful transition.

add_transition

</>

pub fn add_transition(
  config: Config(state, context, event),
  from from: state,
  on on: event,
  to to: state,
) -> Config(state, context, event)

Add a simple (unguarded) transition rule.

get_event_policy

</>

pub fn get_event_policy(
  config: Config(state, context, event),
) -> EventPolicy

Get the event policy.

get_final_states

</>

pub fn get_final_states(
  config: Config(state, context, event),
) -> List(state)

Get the final states list.

get_global_on_enter

</>

pub fn get_global_on_enter(
  config: Config(state, context, event),
) -> List(fn(state, context) -> Result(context, String))

Get global on_enter callbacks.

get_global_on_exit

</>

pub fn get_global_on_exit(
  config: Config(state, context, event),
) -> List(fn(state, context) -> Result(context, String))

Get global on_exit callbacks.

get_global_on_transition

</>

pub fn get_global_on_transition(
  config: Config(state, context, event),
) -> List(
  fn(state, event, state, context) -> Result(context, String),
)

Get global on_transition callbacks.

get_history_limit

</>

pub fn get_history_limit(
  config: Config(state, context, event),
) -> option.Option(Int)

Get the history limit.

get_history_snapshots

</>

pub fn get_history_snapshots(
  config: Config(state, context, event),
) -> Bool

Get whether history snapshots are enabled.

get_invariants

</>

pub fn get_invariants(
  config: Config(state, context, event),
) -> List(fn(context) -> Result(Nil, String))

Get context invariants.

get_on_enter

</>

pub fn get_on_enter(
  config: Config(state, context, event),
) -> List(#(state, fn(state, context) -> Result(context, String)))

Get state-specific on_enter callbacks.

get_on_exit

</>

pub fn get_on_exit(
  config: Config(state, context, event),
) -> List(#(state, fn(state, context) -> Result(context, String)))

Get state-specific on_exit callbacks.

get_on_transition_state

</>

pub fn get_on_transition_state(
  config: Config(state, context, event),
) -> List(
  #(
    state,
    fn(state, event, state, context) -> Result(context, String),
  ),
)

Get state-specific on_transition callbacks.

get_timeouts

</>

pub fn get_timeouts(
  config: Config(state, context, event),
) -> List(#(state, Int, event))

Get timeout declarations.

get_timestamp

</>

pub fn get_timestamp(
  config: Config(state, context, event),
) -> Int

Get the current timestamp by calling the configured timestamp function.

get_timestamp_fn

</>

pub fn get_timestamp_fn(
  config: Config(state, context, event),
) -> fn() -> Int

Get the timestamp function itself.

get_transitions

</>

pub fn get_transitions(
  config: Config(state, context, event),
) -> List(TransitionRule(state, context, event))

Get the transition rules list.

new

</>

pub fn new(
  timestamp_fn: fn() -> Int,
) -> Config(state, context, event)

Create a new empty configuration. The timestamp_fn is called to get the current time in milliseconds.

set_event_policy

</>

pub fn set_event_policy(
  config: Config(state, context, event),
  policy: EventPolicy,
) -> Config(state, context, event)

Set the event filtering policy.

set_final_states

</>

pub fn set_final_states(
  config: Config(state, context, event),
  states: List(state),
) -> Config(state, context, event)

Set the list of final (terminal) states.

set_history_limit

</>

pub fn set_history_limit(
  config: Config(state, context, event),
  limit: Int,
) -> Config(state, context, event)

Set the maximum number of history records to keep.

set_history_snapshots

</>

pub fn set_history_snapshots(
  config: Config(state, context, event),
  enabled: Bool,
) -> Config(state, context, event)

Set whether to include context snapshots in history records.

set_on_enter

</>

pub fn set_on_enter(
  config: Config(state, context, event),
  state: state,
  callback: fn(state, context) -> Result(context, String),
) -> Config(state, context, event)

Set a state-specific on_enter callback.

set_on_exit

</>

pub fn set_on_exit(
  config: Config(state, context, event),
  state: state,
  callback: fn(state, context) -> Result(context, String),
) -> Config(state, context, event)

Set a state-specific on_exit callback.

set_on_transition

</>

pub fn set_on_transition(
  config: Config(state, context, event),
  state: state,
  callback: fn(state, event, state, context) -> Result(
    context,
    String,
  ),
) -> Config(state, context, event)

Set a state-specific on_transition callback (keyed by from-state).

set_timeout

</>

pub fn set_timeout(
  config: Config(state, context, event),
  state: state,
  duration_ms: Int,
  timeout_event: event,
) -> Config(state, context, event)

Declare a timeout for a state. After duration_ms milliseconds in state, the timeout_event should be sent. The library only declares this — actual timer management is external.