zigfsm

zigfsm is a finite state machine library for Zig that supports versions from 0.12.x up to 0.16. It is designed for high performance and low overhead. Key features include:

• Zero Allocation: The library never performs heap allocations.
• Hybrid Execution: Works at both comptime and runtime.
• Efficiency: Fast transition validation and a compact memory representation.
• Visualization: State machines can be exported to Graphviz DOT format for visualization.
• Flexible Definition: Define machines programmatically or by importing Graphviz or libfsm text (even at comptime).
• Automation: Imported machines can autogenerate state and event enums.
• Extensibility: Optional event listeners allow for adding functionality or canceling transitions.
• Advanced Patterns: Easy to wrap for push-down automata (e.g., GameState pattern).

Supported platforms: Linux, macOS, FreeBSD, and Windows.

You can intercept state transitions by providing a list of Handler objects via setTransitionHandlers(). Handlers are called during transitionTo() or do() calls.

Each handler's onTransition function receives the event (if any), the source state, and the destination state. The return value of the handler determines the outcome:

• HandlerResult.Continue: The transition proceeds normally.
• HandlerResult.Cancel: The transition is aborted, and the method returns StateError.Canceled.
• HandlerResult.CancelNoError: The transition is aborted, but no error is returned.

Example

const MyHandler = struct {
    onTransition: *const fn (self: *MyHandler, event: ?Event, from: State, to: State) HandlerResult,
};

var my_handler = MyHandler{
    .onTransition = struct {
        fn handle(self: *MyHandler, event: ?Event, from: State, to: State) HandlerResult {
            std.debug.print("Transitioning from {s} to {s}\n", .{ @tagName(from), @tagName(to) });
            return .Continue;
        }
    }.handle,
};

fsm.setTransitionHandlers(&.{ &my_handler });

// Define a handler implementation
const MyHandler = struct {
    onTransition: *const fn (self: *MyHandler, event: ?Event, from: State, to: State) HandlerResult,
};

// Create an instance of the handler
var handler_inst = MyHandler{
    .onTransition = struct {
        fn onTransition(self: *MyHandler, event: ?Event, from: State, to: State) HandlerResult {
            if (to == .error_state) return .Cancel;
            return .Continue;
        }
    }.onTransition,
};

fsm.setTransitionHandlers(&.{ &handler_inst });

You can define state machines using a simple text format (compatible with Graphviz or libfsm) and import them at runtime or compile-time.

Supported Formats

• Transitions: a -> b, "a" -> "b", a -> b [label="event"], a -> b "event"
• Start State: start: a; or start: -> "a";
• Final States: end: "a" b c; or end: -> "X" Y;

Methods

1. initFrom(input: []const u8): Creates a new instance at runtime by parsing the provided text buffer.
2. instanceFromText(comptime input: []const u8): A powerful compile-time function. It parses the text and generates the necessary State and Event enum types for you. This is ideal for using @embedFile to bake a state machine definition directly into your binary.

Example (Compile-time generation)

const FSM_TYPE = @import(

// Using @embedFile to generate a type and instance at compile time const MyFSM = @import(

The following methods allow you to inspect and control the current state of an FSM instance:

• currentState(): Returns the current StateType.
• isCurrently(requested_state): Returns true if the current state matches the requested one.
• isInStartState(): Returns true if the current state is the initial state.
• isInFinalState(): Returns true if the current state is one of the defined final states.
• isFinalState(state): Checks if a specific state is marked as a final state.
• restart(): Unconditionally resets the current state to the initial start state.
• safeRestart(): Resets to the start state, but returns StateError.Invalid if the machine is not currently in a final state or the start state.
• setStartState(state): Changes the start state and immediately sets it as the current state.

Example

if (fsm.isInFinalState()) {
    fsm.restart();
}

if (fsm.isCurrently(.running)) {
    // do something
}

if (fsm.isInFinalState()) {
    fsm.safeRestart() catch |err| {
        // handle error if not in a valid state to restart
    };
}