ExGram.FSM.Flow behaviour (ExGram FSM v0.1.0)

Behaviour and DSL for declaring a named FSM conversation flow.

Each flow is an independent module that bundles a name, optional default state, and state/transition declarations. Register flows with use ExGram.FSM, flows: [MyBot.RegistrationFlow, MyBot.SettingsFlow].

Usage

defmodule MyBot.RegistrationFlow do
  use ExGram.FSM.Flow, name: :registration

  defstates do
    state :get_name,  to: [:get_email]
    state :get_email, to: [:confirm, :get_name]
    state :confirm,   to: []
  end

  # Optional: define the starting state when start_flow/2 is called.
  # If not defined, flow starts with state: nil (you must set it manually).
  def default_state, do: :get_name
end

Callbacks

Callback	Returns	Description
`flow_name/0`	`atom()`	The unique flow name atom
`default_state/0`	`atom() \| nil`	Initial state when flow starts (override if needed)
`states/0`	`[atom()]`	All valid state atoms
`transitions/0`	`%{atom() => [atom()]} \| :any`	Allowed transitions

Notes

flow_name/0 is generated from the :name option and cannot be overridden.
default_state/0 defaults to nil; override with your own def default_state, do: :get_name.
states/0 and transitions/0 are generated by the defstates block (same as ExGram.FSM.States).
The :name option is required. A CompileError is raised if omitted.

Summary

Callbacks

default_state()

Returns the initial state atom when start_flow/2 is called, or nil to start with no state set (you must call transition/2 or set_state/2 manually).

flow_name()

Returns the unique name atom for this flow.

states()

Returns all valid state atoms declared in the defstates block.

transitions()

Returns the allowed transitions map, or :any if all transitions are allowed.

Callbacks

default_state()

@callback default_state() :: atom() | nil

Returns the initial state atom when start_flow/2 is called, or nil to start with no state set (you must call transition/2 or set_state/2 manually).

flow_name()

@callback flow_name() :: atom()

Returns the unique name atom for this flow.

states()

@callback states() :: [atom()]

Returns all valid state atoms declared in the defstates block.

transitions()

@callback transitions() :: %{required(atom()) => [atom()]} | :any

Returns the allowed transitions map, or :any if all transitions are allowed.

When returning a map, keys are source states and values are lists of allowed target states. Transitions not in the map are invalid.