### Add zigfsm import to build.zig Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Example of how to update your `build.zig` file to include `zigfsm` as an importable module for your executable. ```Zig exe.root_module.addImport("zigfsm", b.dependency("zigfsm", .{}).module("zigfsm")); ``` -------------------------------- ### Instantiate a StateMachine with anonymous enums Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Provides an example of creating a state machine instance using anonymous state and event enums directly within the `StateMachine` constructor. ```Zig var fsm = zigfsm.StateMachine(enum { on, off }, enum { click }, .off).init(); ``` -------------------------------- ### Probing Current State in Zig FSM Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Describes functions available for querying the current state of the state machine. This includes retrieving the current state, checking against specific states, and determining if the state machine is in a final or start state. ```APIDOC Functions for Probing State: currentState(): Returns the current state of the FSM. isCurrently(state: any): Checks if the FSM's current state matches the provided state. isInFinalState(): Checks if the FSM's current state is one of the defined final states. isInStartState(): Checks if the FSM's current state is the initial start state. ``` -------------------------------- ### Build, Test, and Benchmark zigfsm Source: https://github.com/cryptocode/zigfsm/blob/main/README.md This snippet provides the command-line instructions to build, test, and benchmark the zigfsm library using the Zig build system. The build command optimizes for ReleaseFast, and the benchmark command automatically uses ReleaseFast optimization. ```Shell zig build -Doptimize=ReleaseFast zig build test zig build benchmark ``` -------------------------------- ### Instantiate a StateMachine from its type Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Demonstrates creating an instance of a previously defined state machine type using the `init()` method. ```Zig var fsm = FSM.init(); ``` -------------------------------- ### Import zigfsm and implement a Moore machine Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Demonstrates importing the `zigfsm` library and implementing a simple Moore machine (a three-level intensity lightswitch) with state and event definitions, transitions, and state assertions. ```Zig // This example implements a simple Moore machine: a three-level intensity lightswitch const std = @import("std"); const zigfsm = @import("zigfsm"); pub fn main() !void { // A state machine type is defined using state enums and, optionally, event enums. // An event takes the state machine from one state to another, but you can also switch to // other states without using events. // // State and event enums can be explicit enum types, comptime generated enums, or // anonymous enums like in this example. // // If you don't want to use events, simply pass null to the second argument. // We also define what state is the initial one, in this case .off var fsm = zigfsm.StateMachine(enum { off, dim, medium, bright }, enum { click }, .off).init(); // There are many ways to define transitions (and optionally events), including importing // from Graphviz. In this example we use a simple API to add events and transitions. try fsm.addEventAndTransition(.click, .off, .dim); try fsm.addEventAndTransition(.click, .dim, .medium); try fsm.addEventAndTransition(.click, .medium, .bright); try fsm.addEventAndTransition(.click, .bright, .off); std.debug.assert(fsm.isCurrently(.off)); // Do a full cycle: off -> dim -> medium -> bright -> off _ = try fsm.do(.click); _ = try fsm.do(.click); _ = try fsm.do(.click); _ = try fsm.do(.click); // Make sure we're in the expected state std.debug.assert(fsm.isCurrently(.off)); std.debug.assert(fsm.canTransitionTo(.dim)); } ``` -------------------------------- ### Add zigfsm to zon file Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Instructions to add `zigfsm` as a Zig package dependency to your `zon` file using `zig fetch`. ```Bash zig fetch --save git+https://github.com/cryptocode/zigfsm ``` -------------------------------- ### Instantiate a StateMachine with anonymous type definition Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Shows a concise way to define the state machine type and create an instance in a single line, without needing to reference the type explicitly. ```Zig var fsm = zigfsm.StateMachine(State, Event, .off).init(); ``` -------------------------------- ### Directly Transitioning State in Zig FSM Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Demonstrates how to directly transition the state machine to a specific state using `fsm.transitionTo`. This operation will fail with `StateError.Invalid` if the transition is not permitted from the current state. ```Zig try fsm.transitionTo(.on); ``` -------------------------------- ### Define events and transitions simultaneously Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Introduces the `addEventAndTransition` helper function, which simplifies defining both an event and its corresponding state transition in a single call. ```Zig try fsm.addEventAndTransition(.click, .on, .off); try fsm.addEventAndTransition(.click, .off, .on); ``` -------------------------------- ### Inspecting Transition Details in Zig FSM Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Demonstrates how to capture and inspect the details of a state transition after an event is processed. The `transition` object provides `from`, `to`, and `event` fields, useful for conditional logic based on the specific state change. ```Zig const transition = try fsm.do(.identifier); if (transition.to == .jumping and transition.from == .running) { ... } ``` -------------------------------- ### Define state transitions via events Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Shows how to associate events with state transitions using `addEvent`, where the same event can trigger different transitions based on the current state. ```Zig try fsm.addEvent(.click, .on, .off); try fsm.addEvent(.click, .off, .on); ``` -------------------------------- ### Add direct state transitions Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Explains how to define direct state transitions between states using the `addTransition` method, allowing state changes without explicit events. ```Zig try fsm.addTransition(.on, .off); try fsm.addTransition(.off, .on); ``` -------------------------------- ### Changing State via Events in Zig FSM Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Illustrates how to change the state of the state machine by applying an event using `fsm.do`. Multiple event applications are shown, simulating a light switch being flipped on and off. This method also fails with `StateError.Invalid` for invalid transitions. ```Zig try fsm.do(.click); try fsm.do(.click); try fsm.do(.click); ``` -------------------------------- ### Adding Transition Handlers in Zig FSM Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Illustrates how to register a custom handler to be called whenever a state transition occurs. Handlers allow for additional logic, such as tracking transition counts or maintaining auxiliary state, and can also be used to cancel transitions. ```Zig var countingHandler = CountingHandler.init(); try fsm.addTransitionHandler(&countingHandler.handler); ``` -------------------------------- ### Define a StateMachine type with states and events Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Shows how to define a state machine type using explicit state and event enums for a button that flips between on and off states, with an initial state of `.off`. ```Zig const State = enum { on, off }; const Event = enum { click }; const FSM = zigfsm.StateMachine(State, Event, .off); ``` -------------------------------- ### Generic State Change with `apply` in Zig FSM Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Shows the use of the generic `fsm.apply` function to change the state. It can accept either a new state or an event, providing a flexible way to trigger transitions. ```Zig try fsm.apply(.{ .state = .on }); try fsm.apply(.{ .event = .click }); ``` -------------------------------- ### Define StateMachine transitions from a table Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Demonstrates using `StateMachineFromTable` to define all event and state transitions from a structured table, offering an alternative to individual `addTransition` or `addEvent` calls. The event field is optional for transition validation. ```Zig const State = enum { on, off }; const Event = enum { click }; const definition = [_]Transition(State, Event){ .{ .event = .click, .from = .on, .to = .off }, .{ .event = .click, .from = .off, .to = .on }, }; var fsm = zigfsm.StateMachineFromTable(State, Event, &definition, .off, &.{}).init(); ``` -------------------------------- ### Importing State Machines from Text in Zig FSM Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Explains how to import state machine definitions from external text files (Graphviz or libfsm format) into a Zig FSM. It differentiates between `importText` (for existing enums or runtime definition) and `generateStateMachineFromText` (for compiler-generated enums), highlighting their trade-offs. ```APIDOC Functions for Importing State Machines: importText(source: string): Purpose: Parses a Graphviz or libfsm text file to define state transitions. Usage: Can be called at compile time or runtime. Requirement: State and event enums must be already defined in Zig. generateStateMachineFromText(source: string): Purpose: Generates state and event enums from a Graphviz or libfsm text file. Usage: Performed at compile time. Note: Saves manual enum definition but may impact editor autocomplete for generated types. Source Input: Can be a string literal or brought in by @embedFile. ``` -------------------------------- ### Iterating Through Valid Next States in Zig FSM Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Shows how to use an iterator to discover all states that are reachable from the current state. This is useful for dynamic state machine analysis or UI generation. ```Zig while (fsm.validNextStatesIterator()) |valid_next_state| { ... } ``` -------------------------------- ### Define a StateMachine type without events Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Illustrates how to define a state machine type when events are not required, by passing `null` as the event enum argument. ```Zig const FSM = zigfsm.StateMachine(State, null, .off); ``` -------------------------------- ### Canceling Transitions with Handlers in Zig FSM Source: https://github.com/cryptocode/zigfsm/blob/main/README.md Details how transition handlers can prevent a transition from completing. Returning `HandlerResult.Cancel` will cause the original `transitionTo` or `do` call to fail with `StateError.Invalid`. Alternatively, `HandlerResult.CancelNoError` can be used to cancel the transition without propagating an error, leaving the current state unchanged but allowing the callsite to succeed. ```APIDOC HandlerResult Values for Transition Cancellation: HandlerResult.Cancel: Effect: Cancels the transition. Outcome: The callsite of 'transitionTo' or 'do' will fail with 'StateError.Invalid'. HandlerResult.CancelNoError: Effect: Cancels the transition without causing a failure. Outcome: The current state remains unchanged, and the callsite succeeds. ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.