FSM Guide
FSM Programming Guide
fsm
is an auto-preluded standard-library macro. It expands to an ordinary
lift module
with a checked
gen_statem
callback surface; the compiler does
not contain a separate FSM parser or object class.
Std.Fsm
declares two
fsm
macros over one shared callback floor:
-
The transition graph surface
(
fsm Name with Data) — a graph ofFrom --Event--> Torows, verified at compile time and compiled to a totaldecide/3. This is the preferred surface for anything shaped like a state machine, and the one that derives a full typedsend/startAPI. -
The structured event-body surface
(
fsm Namewithstate/events) — a lower-level shape that maps event patterns directly to callback results (or, in its typed form, toFsmActionvalues). Use it when you want to write agen_statemcallback body by hand, or need the enclosing module to see the state/event type names.
Both require
use Std.Fsm
. A bare module name is relative to its lexical owner;
a dotted name is absolute within the Cure source namespace. Source never needs
to spell the emitter-owned
Cure.
prefix.
Defining An FSM
The transition graph is the preferred surface:
use Std.Fsm
fsm Turnstile with Int
Locked --Coin--> Unlocked
update data + 1
Unlocked --Push--> Locked
Unlocked --Coin--> Unlocked
update data + 1
Locked --Push--> Locked
with Int
declares the machine's data type — any Cure type works here,
including a record or a
Tuple(...)
, not just a primitive. The macro catalogs
every endpoint into a nominal
State
type (
Locked | Unlocked
) and every label
into a nominal
Event
type (
Coin | Push
). Without an explicit
initial
row
(below), the source state of the first written edge is the initial state; a
wildcard row's source (
*
) is never eligible for this.
An edge preserves
data
unless it has an indented
update
expression. The
expression is checked as the declared data type and may refer to
data
; the
target state is already fixed by the edge and is not repeated in callback
tuples.
Record data uses Cure's ordinary typed record-update syntax. Fields not named after the bar are preserved:
use Std.Fsm
rec TurnstileData
coins: Int
pushes: Int
enabled: Bool
fsm Turnstile with TurnstileData
Locked --Coin--> Unlocked
update TurnstileData{
data
| coins: data.coins + 1,
enabled: true
}
Unlocked --Push--> Locked
update TurnstileData{data | pushes: data.pushes + 1}
Unlocked --Coin--> Unlocked
update TurnstileData{data | coins: data.coins + 1}
Locked --Push--> Locked
The
|
may instead occupy its own line before the first field; both layouts
parse as the same typed record update, and either may update more than one field
at once.
Why It Is Checked
Because the transition table is a declaration rather than a callback body, the
compiler can verify properties that a hand-written
gen_statem
cannot express:
- every event is declared for every state it can arrive in, or explicitly wildcarded;
-
the generated
decide/3is total over the declared state/event product; -
updateexpressions are checked against the declared data type.
The Structured Surface
The lower-level form maps event patterns directly to callback results, and is what the tutorial shows:
fsm Turnstile
state Int
events
Coin -> :keep_state_and_data
Each event branch is checked as an
FsmAction
(
Keep
,
Next
, or
Stop
).
Transition tables are a library-level macro over the same generated
gen_statem
substrate rather than compiler syntax.
See Supervision for the surrounding actor and supervisor vocabulary, and Applications for wiring an FSM into a release.