Maxine (Maxine v0.2.6)

Functions for dealing with machines: to wit, generate/2, which creates an initial %State{} struct from a %Machine{}, and advance/3 (along with companion advance!/3) which transforms one %State{} into another one according to the rules given in the machine.

Link to this section Summary

Functions

Creates a new state record based on the current state, an event, and options (optionally).

Exception-raising wrapper (unwrapper?) for the advance/3.

Create a new state machine, optionally specifying a starting state other than the one given in the machine.

Link to this section Functions

Link to this function

advance(current, event, options \\ [])

Specs

advance(
  current :: %Maxine.State{
    data: term(),
    machine: term(),
    name: term(),
    previous: term()
  },
  event :: Maxine.Machine.event_name(),
  options :: Maxine.Machine.event_options()
) ::
  {:ok,
   %Maxine.State{data: term(), machine: term(), name: term(), previous: term()}}
  | {:error, Maxine.Errors.error()}

Creates a new state record based on the current state, an event, and options (optionally).

Parameters

  • current: A %State{} record; the current state
  • event: The name of the event you'd like to call (atom)
  • options: optional arguments to the event; will be preserved in state.data.options

Examples

iex> alias Maxine.Examples.Package
iex> state = Maxine.generate(Package.machine)
iex> {:ok, state = %Maxine.State{}} = Maxine.advance(state, :ship)
iex> state.name
:in_transit

iex> alias Maxine.Examples.Package
iex> state = Maxine.generate(Package.machine)
iex> {:ok, state = %Maxine.State{}} = Maxine.advance(state, :ship, foo: "bar")
iex> state.data.options[:foo]
"bar"
Link to this function

advance!(current, event, options \\ [])

Specs

advance!(
  current :: %Maxine.State{
    data: term(),
    machine: term(),
    name: term(),
    previous: term()
  },
  event :: Maxine.Machine.event_name(),
  options :: Maxine.Machine.event_options()
) ::
  %Maxine.State{data: term(), machine: term(), name: term(), previous: term()}
  | no_return()

Exception-raising wrapper (unwrapper?) for the advance/3.

Parameters

  • current: A %State{} record; the current state
  • event: The name of the event you'd like to call (atom)
  • options: optional arguments to the event; will be preserved

Examples

iex> alias Maxine.Examples.Package
iex> state = Maxine.generate(Package.machine)
iex> state = Maxine.advance!(state, :ship)
iex> state.name
:in_transit 
Link to this function

generate(machine, initial \\ nil)

Specs

generate(
  machine :: %Maxine.Machine{
    callbacks: term(),
    groups: term(),
    initial: term(),
    transitions: term()
  },
  initial :: Maxine.Machine.state_name()
) :: %Maxine.State{
  data: term(),
  machine: term(),
  name: term(),
  previous: term()
}

Create a new state machine, optionally specifying a starting state other than the one given in the machine.

Parameters

  • machine: An instance of %Machine{} that specifies events, transitions, states, callbacks
  • initial: An optional initial state, overriding the machine's default

Examples

iex> alias Maxine.Examples.Package
iex> Maxine.generate(Package.machine).name
:origin

iex> alias Maxine.Examples.Package
iex> Maxine.generate(Package.machine, :foobar).name
:foobar