Struct Machine 

pub struct Machine<S, E> { /* private fields */ }

A generic finite state machine.

Type Parameters

• S: The state type. Must implement Eq + Hash + Clone.
• E: The event type. Must implement Eq + Hash + Clone.

Implementations

impl<S, E> Machine<S, E>

pub fn new(initial_state: S) -> Self

Create a new state machine with the given initial state.

Examples found in repository

examples/callbacks.rs (line 6)

fn main() {
    let mut nano = Machine::new("locked");

    // Define valid transitions.
    nano.when("insert coin", "locked", "unlocked");
    nano.when("turn knob", "unlocked", "locked");

    // State-specific callbacks without payload.
    nano.on_enter("unlocked", |e| println!("Unlocked via {:?}", e));
    nano.on_enter("locked", |e| println!("Locked via {:?}", e));

    // State-specific callback with a u32 payload.
    nano.on_enter_with("unlocked", |e, amount: &u32| {
        println!("Received {} cents via {:?}", amount, e);
    });

    // Global callbacks.
    nano.on_transition(|e| println!("Global - event {:?}", e));
    nano.on_transition_with(|e, amount: &u32| {
        println!("Global - saw {} cents via {:?}", amount, e);
    });
    nano.on_transition_with(|e, msg: &String| {
        println!("Global - saw \"{}\" via {:?}", msg, e);
    });

    // Prints:
    //   Unlocked via "insert coin"
    //   Global - event "insert coin"
    nano.trigger(&"insert coin").unwrap();

    // Prints:
    //   Locked via "turn knob"
    //   Global - event "turn knob"
    //   Global - saw "voucher" via "turn knob"
    nano.trigger_with(&"turn knob", &"voucher".to_string()).unwrap();

    // Prints:
    //   Unlocked via "insert coin"
    //   Received 50 cents via "insert coin"
    //   Global - event "insert coin"
    //   Global - saw 50 cents via "insert coin"
    nano.trigger_with(&"insert coin", &50u32).unwrap();

    // Final state: "unlocked"
    println!("Final state: {:?}", nano.state());
}

examples/order.rs (line 26)

fn main() {
    // Create the machine in the Created state.
    let mut nano = Machine::new(OrderState::Created);

    // Define transitions one-by-one.
    nano.when(OrderEvent::Pay, OrderState::Created, OrderState::Paid);
    nano.when(OrderEvent::Ship, OrderState::Paid, OrderState::Shipped);
    nano.when(OrderEvent::Deliver, OrderState::Shipped, OrderState::Delivered);

    // Define Cancel for both Created and Paid using when_iter.
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );

    // ─── State-specific hooks ───────────────────────────────────────────────
    // On Paid: log payment amount.
    nano.on_enter_with(OrderState::Paid, |evt, amount: &u32| {
        println!("✔ Payment {:?}: {}¢ received", evt, amount);
    });

    // On Shipped: log tracking code.
    nano.on_enter_with(OrderState::Shipped, |_evt, tracking: &String| {
        println!("🚚 Order shipped! Tracking code: {}", tracking);
    });

    // On Delivered: confirmation.
    nano.on_enter_with(OrderState::Delivered, |_evt, _: &()| {
        println!("📦 Order delivered. Thank you!");
    });

    // On Cancelled: show cancellation reason.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("❌ Order cancelled: {}", reason);
    });

    // ─── Global hooks ───────────────────────────────────────────────────────
    // Fires on *every* transition (no payload).
    nano.on_transition(|evt| {
        println!("🔄 Transition via event: {:?}", evt);
    });

    // Fires on *every* transition *with* a u32 payload (e.g. payments).
    nano.on_transition_with(|evt, amount: &u32| {
        println!("🌐 Global saw {}¢ payment via {:?}", amount, evt);
    });

    // Fires on *every* transition *with* a String payload
    // (e.g. tracking codes or cancellation reasons).
    nano.on_transition_with(|evt, text: &String| {
        println!("🌐 Global saw string payload {:?}: {}", evt, text);
    });
    // Inspect machine metadata:
    println!("All states: {:?}", nano.states().cloned().collect::<Vec<_>>());
    println!("All events: {:?}", nano.events().cloned().collect::<Vec<_>>());
    println!(
        "Triggerable now ({:?}): {:?}",
        nano.state(),
        nano.triggerable_events().cloned().collect::<Vec<_>>()
    );
    println!();

    // Simulate a successful order:
    //    Pay with payload.
    nano.trigger_with(&OrderEvent::Pay, &2_500u32)
        .expect("Should transition to Paid");
    //    Ship with payload.
    nano.trigger_with(&OrderEvent::Ship, &"TRACK1234".to_string())
        .expect("Should transition to Shipped");
    //    Deliver without payload.
    nano.trigger(&OrderEvent::Deliver).expect("Should transition to Delivered");
    println!("\nFinal state: {:?}\n", nano.state());

    // Attempt an invalid transition (Pay after Delivered).
    match nano.trigger(&OrderEvent::Pay) {
        Ok(_) => println!("Unexpectedly succeeded!"),
        Err(e) => println!("Error trying to pay in {:?}: {}", nano.state(), e),
    }

    // Create a fresh order and cancel it early.
    let mut nano = Machine::new(OrderState::Created);
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );
    // Re-attach only the Cancel callback.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("Order #2 cancelled reason: {}", reason);
    });
    // Cancel with a payload.
    nano.trigger_with(
        &OrderEvent::Cancel,
        &"Customer changed mind".to_string(),
    )
    .unwrap();

    println!("Order #2 final: {:?}", nano.state());
}

pub fn state(&self) -> &S

A reference to the current state of the machine.

Examples found in repository

examples/callbacks.rs (line 49)

fn main() {
    let mut nano = Machine::new("locked");

    // Define valid transitions.
    nano.when("insert coin", "locked", "unlocked");
    nano.when("turn knob", "unlocked", "locked");

    // State-specific callbacks without payload.
    nano.on_enter("unlocked", |e| println!("Unlocked via {:?}", e));
    nano.on_enter("locked", |e| println!("Locked via {:?}", e));

    // State-specific callback with a u32 payload.
    nano.on_enter_with("unlocked", |e, amount: &u32| {
        println!("Received {} cents via {:?}", amount, e);
    });

    // Global callbacks.
    nano.on_transition(|e| println!("Global - event {:?}", e));
    nano.on_transition_with(|e, amount: &u32| {
        println!("Global - saw {} cents via {:?}", amount, e);
    });
    nano.on_transition_with(|e, msg: &String| {
        println!("Global - saw \"{}\" via {:?}", msg, e);
    });

    // Prints:
    //   Unlocked via "insert coin"
    //   Global - event "insert coin"
    nano.trigger(&"insert coin").unwrap();

    // Prints:
    //   Locked via "turn knob"
    //   Global - event "turn knob"
    //   Global - saw "voucher" via "turn knob"
    nano.trigger_with(&"turn knob", &"voucher".to_string()).unwrap();

    // Prints:
    //   Unlocked via "insert coin"
    //   Received 50 cents via "insert coin"
    //   Global - event "insert coin"
    //   Global - saw 50 cents via "insert coin"
    nano.trigger_with(&"insert coin", &50u32).unwrap();

    // Final state: "unlocked"
    println!("Final state: {:?}", nano.state());
}

examples/order.rs (line 84)

fn main() {
    // Create the machine in the Created state.
    let mut nano = Machine::new(OrderState::Created);

    // Define transitions one-by-one.
    nano.when(OrderEvent::Pay, OrderState::Created, OrderState::Paid);
    nano.when(OrderEvent::Ship, OrderState::Paid, OrderState::Shipped);
    nano.when(OrderEvent::Deliver, OrderState::Shipped, OrderState::Delivered);

    // Define Cancel for both Created and Paid using when_iter.
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );

    // ─── State-specific hooks ───────────────────────────────────────────────
    // On Paid: log payment amount.
    nano.on_enter_with(OrderState::Paid, |evt, amount: &u32| {
        println!("✔ Payment {:?}: {}¢ received", evt, amount);
    });

    // On Shipped: log tracking code.
    nano.on_enter_with(OrderState::Shipped, |_evt, tracking: &String| {
        println!("🚚 Order shipped! Tracking code: {}", tracking);
    });

    // On Delivered: confirmation.
    nano.on_enter_with(OrderState::Delivered, |_evt, _: &()| {
        println!("📦 Order delivered. Thank you!");
    });

    // On Cancelled: show cancellation reason.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("❌ Order cancelled: {}", reason);
    });

    // ─── Global hooks ───────────────────────────────────────────────────────
    // Fires on *every* transition (no payload).
    nano.on_transition(|evt| {
        println!("🔄 Transition via event: {:?}", evt);
    });

    // Fires on *every* transition *with* a u32 payload (e.g. payments).
    nano.on_transition_with(|evt, amount: &u32| {
        println!("🌐 Global saw {}¢ payment via {:?}", amount, evt);
    });

    // Fires on *every* transition *with* a String payload
    // (e.g. tracking codes or cancellation reasons).
    nano.on_transition_with(|evt, text: &String| {
        println!("🌐 Global saw string payload {:?}: {}", evt, text);
    });
    // Inspect machine metadata:
    println!("All states: {:?}", nano.states().cloned().collect::<Vec<_>>());
    println!("All events: {:?}", nano.events().cloned().collect::<Vec<_>>());
    println!(
        "Triggerable now ({:?}): {:?}",
        nano.state(),
        nano.triggerable_events().cloned().collect::<Vec<_>>()
    );
    println!();

    // Simulate a successful order:
    //    Pay with payload.
    nano.trigger_with(&OrderEvent::Pay, &2_500u32)
        .expect("Should transition to Paid");
    //    Ship with payload.
    nano.trigger_with(&OrderEvent::Ship, &"TRACK1234".to_string())
        .expect("Should transition to Shipped");
    //    Deliver without payload.
    nano.trigger(&OrderEvent::Deliver).expect("Should transition to Delivered");
    println!("\nFinal state: {:?}\n", nano.state());

    // Attempt an invalid transition (Pay after Delivered).
    match nano.trigger(&OrderEvent::Pay) {
        Ok(_) => println!("Unexpectedly succeeded!"),
        Err(e) => println!("Error trying to pay in {:?}: {}", nano.state(), e),
    }

    // Create a fresh order and cancel it early.
    let mut nano = Machine::new(OrderState::Created);
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );
    // Re-attach only the Cancel callback.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("Order #2 cancelled reason: {}", reason);
    });
    // Cancel with a payload.
    nano.trigger_with(
        &OrderEvent::Cancel,
        &"Customer changed mind".to_string(),
    )
    .unwrap();

    println!("Order #2 final: {:?}", nano.state());
}

impl<S, E> Machine<S, E>

where S: Eq + Hash + Clone, E: Eq + Hash + Clone,

pub fn states(&self) -> impl Iterator<Item = &S>

Returns an iterator over all states known to the machine.

Examples found in repository

examples/order.rs (line 80)

fn main() {
    // Create the machine in the Created state.
    let mut nano = Machine::new(OrderState::Created);

    // Define transitions one-by-one.
    nano.when(OrderEvent::Pay, OrderState::Created, OrderState::Paid);
    nano.when(OrderEvent::Ship, OrderState::Paid, OrderState::Shipped);
    nano.when(OrderEvent::Deliver, OrderState::Shipped, OrderState::Delivered);

    // Define Cancel for both Created and Paid using when_iter.
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );

    // ─── State-specific hooks ───────────────────────────────────────────────
    // On Paid: log payment amount.
    nano.on_enter_with(OrderState::Paid, |evt, amount: &u32| {
        println!("✔ Payment {:?}: {}¢ received", evt, amount);
    });

    // On Shipped: log tracking code.
    nano.on_enter_with(OrderState::Shipped, |_evt, tracking: &String| {
        println!("🚚 Order shipped! Tracking code: {}", tracking);
    });

    // On Delivered: confirmation.
    nano.on_enter_with(OrderState::Delivered, |_evt, _: &()| {
        println!("📦 Order delivered. Thank you!");
    });

    // On Cancelled: show cancellation reason.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("❌ Order cancelled: {}", reason);
    });

    // ─── Global hooks ───────────────────────────────────────────────────────
    // Fires on *every* transition (no payload).
    nano.on_transition(|evt| {
        println!("🔄 Transition via event: {:?}", evt);
    });

    // Fires on *every* transition *with* a u32 payload (e.g. payments).
    nano.on_transition_with(|evt, amount: &u32| {
        println!("🌐 Global saw {}¢ payment via {:?}", amount, evt);
    });

    // Fires on *every* transition *with* a String payload
    // (e.g. tracking codes or cancellation reasons).
    nano.on_transition_with(|evt, text: &String| {
        println!("🌐 Global saw string payload {:?}: {}", evt, text);
    });
    // Inspect machine metadata:
    println!("All states: {:?}", nano.states().cloned().collect::<Vec<_>>());
    println!("All events: {:?}", nano.events().cloned().collect::<Vec<_>>());
    println!(
        "Triggerable now ({:?}): {:?}",
        nano.state(),
        nano.triggerable_events().cloned().collect::<Vec<_>>()
    );
    println!();

    // Simulate a successful order:
    //    Pay with payload.
    nano.trigger_with(&OrderEvent::Pay, &2_500u32)
        .expect("Should transition to Paid");
    //    Ship with payload.
    nano.trigger_with(&OrderEvent::Ship, &"TRACK1234".to_string())
        .expect("Should transition to Shipped");
    //    Deliver without payload.
    nano.trigger(&OrderEvent::Deliver).expect("Should transition to Delivered");
    println!("\nFinal state: {:?}\n", nano.state());

    // Attempt an invalid transition (Pay after Delivered).
    match nano.trigger(&OrderEvent::Pay) {
        Ok(_) => println!("Unexpectedly succeeded!"),
        Err(e) => println!("Error trying to pay in {:?}: {}", nano.state(), e),
    }

    // Create a fresh order and cancel it early.
    let mut nano = Machine::new(OrderState::Created);
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );
    // Re-attach only the Cancel callback.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("Order #2 cancelled reason: {}", reason);
    });
    // Cancel with a payload.
    nano.trigger_with(
        &OrderEvent::Cancel,
        &"Customer changed mind".to_string(),
    )
    .unwrap();

    println!("Order #2 final: {:?}", nano.state());
}

pub fn events(&self) -> impl Iterator<Item = &E>

Returns an iterator over all events the machine can react to.

Examples found in repository

examples/order.rs (line 81)

fn main() {
    // Create the machine in the Created state.
    let mut nano = Machine::new(OrderState::Created);

    // Define transitions one-by-one.
    nano.when(OrderEvent::Pay, OrderState::Created, OrderState::Paid);
    nano.when(OrderEvent::Ship, OrderState::Paid, OrderState::Shipped);
    nano.when(OrderEvent::Deliver, OrderState::Shipped, OrderState::Delivered);

    // Define Cancel for both Created and Paid using when_iter.
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );

    // ─── State-specific hooks ───────────────────────────────────────────────
    // On Paid: log payment amount.
    nano.on_enter_with(OrderState::Paid, |evt, amount: &u32| {
        println!("✔ Payment {:?}: {}¢ received", evt, amount);
    });

    // On Shipped: log tracking code.
    nano.on_enter_with(OrderState::Shipped, |_evt, tracking: &String| {
        println!("🚚 Order shipped! Tracking code: {}", tracking);
    });

    // On Delivered: confirmation.
    nano.on_enter_with(OrderState::Delivered, |_evt, _: &()| {
        println!("📦 Order delivered. Thank you!");
    });

    // On Cancelled: show cancellation reason.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("❌ Order cancelled: {}", reason);
    });

    // ─── Global hooks ───────────────────────────────────────────────────────
    // Fires on *every* transition (no payload).
    nano.on_transition(|evt| {
        println!("🔄 Transition via event: {:?}", evt);
    });

    // Fires on *every* transition *with* a u32 payload (e.g. payments).
    nano.on_transition_with(|evt, amount: &u32| {
        println!("🌐 Global saw {}¢ payment via {:?}", amount, evt);
    });

    // Fires on *every* transition *with* a String payload
    // (e.g. tracking codes or cancellation reasons).
    nano.on_transition_with(|evt, text: &String| {
        println!("🌐 Global saw string payload {:?}: {}", evt, text);
    });
    // Inspect machine metadata:
    println!("All states: {:?}", nano.states().cloned().collect::<Vec<_>>());
    println!("All events: {:?}", nano.events().cloned().collect::<Vec<_>>());
    println!(
        "Triggerable now ({:?}): {:?}",
        nano.state(),
        nano.triggerable_events().cloned().collect::<Vec<_>>()
    );
    println!();

    // Simulate a successful order:
    //    Pay with payload.
    nano.trigger_with(&OrderEvent::Pay, &2_500u32)
        .expect("Should transition to Paid");
    //    Ship with payload.
    nano.trigger_with(&OrderEvent::Ship, &"TRACK1234".to_string())
        .expect("Should transition to Shipped");
    //    Deliver without payload.
    nano.trigger(&OrderEvent::Deliver).expect("Should transition to Delivered");
    println!("\nFinal state: {:?}\n", nano.state());

    // Attempt an invalid transition (Pay after Delivered).
    match nano.trigger(&OrderEvent::Pay) {
        Ok(_) => println!("Unexpectedly succeeded!"),
        Err(e) => println!("Error trying to pay in {:?}: {}", nano.state(), e),
    }

    // Create a fresh order and cancel it early.
    let mut nano = Machine::new(OrderState::Created);
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );
    // Re-attach only the Cancel callback.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("Order #2 cancelled reason: {}", reason);
    });
    // Cancel with a payload.
    nano.trigger_with(
        &OrderEvent::Cancel,
        &"Customer changed mind".to_string(),
    )
    .unwrap();

    println!("Order #2 final: {:?}", nano.state());
}

pub fn triggerable_events(&self) -> impl Iterator<Item = &E>

Returns an iterator over events valid from the current state.

Only events that have a defined transition from the machine’s current state are included.

Examples found in repository

examples/order.rs (line 85)

fn main() {
    // Create the machine in the Created state.
    let mut nano = Machine::new(OrderState::Created);

    // Define transitions one-by-one.
    nano.when(OrderEvent::Pay, OrderState::Created, OrderState::Paid);
    nano.when(OrderEvent::Ship, OrderState::Paid, OrderState::Shipped);
    nano.when(OrderEvent::Deliver, OrderState::Shipped, OrderState::Delivered);

    // Define Cancel for both Created and Paid using when_iter.
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );

    // ─── State-specific hooks ───────────────────────────────────────────────
    // On Paid: log payment amount.
    nano.on_enter_with(OrderState::Paid, |evt, amount: &u32| {
        println!("✔ Payment {:?}: {}¢ received", evt, amount);
    });

    // On Shipped: log tracking code.
    nano.on_enter_with(OrderState::Shipped, |_evt, tracking: &String| {
        println!("🚚 Order shipped! Tracking code: {}", tracking);
    });

    // On Delivered: confirmation.
    nano.on_enter_with(OrderState::Delivered, |_evt, _: &()| {
        println!("📦 Order delivered. Thank you!");
    });

    // On Cancelled: show cancellation reason.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("❌ Order cancelled: {}", reason);
    });

    // ─── Global hooks ───────────────────────────────────────────────────────
    // Fires on *every* transition (no payload).
    nano.on_transition(|evt| {
        println!("🔄 Transition via event: {:?}", evt);
    });

    // Fires on *every* transition *with* a u32 payload (e.g. payments).
    nano.on_transition_with(|evt, amount: &u32| {
        println!("🌐 Global saw {}¢ payment via {:?}", amount, evt);
    });

    // Fires on *every* transition *with* a String payload
    // (e.g. tracking codes or cancellation reasons).
    nano.on_transition_with(|evt, text: &String| {
        println!("🌐 Global saw string payload {:?}: {}", evt, text);
    });
    // Inspect machine metadata:
    println!("All states: {:?}", nano.states().cloned().collect::<Vec<_>>());
    println!("All events: {:?}", nano.events().cloned().collect::<Vec<_>>());
    println!(
        "Triggerable now ({:?}): {:?}",
        nano.state(),
        nano.triggerable_events().cloned().collect::<Vec<_>>()
    );
    println!();

    // Simulate a successful order:
    //    Pay with payload.
    nano.trigger_with(&OrderEvent::Pay, &2_500u32)
        .expect("Should transition to Paid");
    //    Ship with payload.
    nano.trigger_with(&OrderEvent::Ship, &"TRACK1234".to_string())
        .expect("Should transition to Shipped");
    //    Deliver without payload.
    nano.trigger(&OrderEvent::Deliver).expect("Should transition to Delivered");
    println!("\nFinal state: {:?}\n", nano.state());

    // Attempt an invalid transition (Pay after Delivered).
    match nano.trigger(&OrderEvent::Pay) {
        Ok(_) => println!("Unexpectedly succeeded!"),
        Err(e) => println!("Error trying to pay in {:?}: {}", nano.state(), e),
    }

    // Create a fresh order and cancel it early.
    let mut nano = Machine::new(OrderState::Created);
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );
    // Re-attach only the Cancel callback.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("Order #2 cancelled reason: {}", reason);
    });
    // Cancel with a payload.
    nano.trigger_with(
        &OrderEvent::Cancel,
        &"Customer changed mind".to_string(),
    )
    .unwrap();

    println!("Order #2 final: {:?}", nano.state());
}

impl<S, E> Machine<S, E>

where S: Eq + Hash + Clone, E: Eq + Hash + Clone,

pub fn when(&mut self, event: E, state: S, new_state: S)

When event occurs in state, move to new_state.

Multiple calls to when for the same (event, state) will overwrite the previous new_state.

Examples found in repository

examples/callbacks.rs (line 9)

fn main() {
    let mut nano = Machine::new("locked");

    // Define valid transitions.
    nano.when("insert coin", "locked", "unlocked");
    nano.when("turn knob", "unlocked", "locked");

    // State-specific callbacks without payload.
    nano.on_enter("unlocked", |e| println!("Unlocked via {:?}", e));
    nano.on_enter("locked", |e| println!("Locked via {:?}", e));

    // State-specific callback with a u32 payload.
    nano.on_enter_with("unlocked", |e, amount: &u32| {
        println!("Received {} cents via {:?}", amount, e);
    });

    // Global callbacks.
    nano.on_transition(|e| println!("Global - event {:?}", e));
    nano.on_transition_with(|e, amount: &u32| {
        println!("Global - saw {} cents via {:?}", amount, e);
    });
    nano.on_transition_with(|e, msg: &String| {
        println!("Global - saw \"{}\" via {:?}", msg, e);
    });

    // Prints:
    //   Unlocked via "insert coin"
    //   Global - event "insert coin"
    nano.trigger(&"insert coin").unwrap();

    // Prints:
    //   Locked via "turn knob"
    //   Global - event "turn knob"
    //   Global - saw "voucher" via "turn knob"
    nano.trigger_with(&"turn knob", &"voucher".to_string()).unwrap();

    // Prints:
    //   Unlocked via "insert coin"
    //   Received 50 cents via "insert coin"
    //   Global - event "insert coin"
    //   Global - saw 50 cents via "insert coin"
    nano.trigger_with(&"insert coin", &50u32).unwrap();

    // Final state: "unlocked"
    println!("Final state: {:?}", nano.state());
}

examples/order.rs (line 29)

fn main() {
    // Create the machine in the Created state.
    let mut nano = Machine::new(OrderState::Created);

    // Define transitions one-by-one.
    nano.when(OrderEvent::Pay, OrderState::Created, OrderState::Paid);
    nano.when(OrderEvent::Ship, OrderState::Paid, OrderState::Shipped);
    nano.when(OrderEvent::Deliver, OrderState::Shipped, OrderState::Delivered);

    // Define Cancel for both Created and Paid using when_iter.
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );

    // ─── State-specific hooks ───────────────────────────────────────────────
    // On Paid: log payment amount.
    nano.on_enter_with(OrderState::Paid, |evt, amount: &u32| {
        println!("✔ Payment {:?}: {}¢ received", evt, amount);
    });

    // On Shipped: log tracking code.
    nano.on_enter_with(OrderState::Shipped, |_evt, tracking: &String| {
        println!("🚚 Order shipped! Tracking code: {}", tracking);
    });

    // On Delivered: confirmation.
    nano.on_enter_with(OrderState::Delivered, |_evt, _: &()| {
        println!("📦 Order delivered. Thank you!");
    });

    // On Cancelled: show cancellation reason.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("❌ Order cancelled: {}", reason);
    });

    // ─── Global hooks ───────────────────────────────────────────────────────
    // Fires on *every* transition (no payload).
    nano.on_transition(|evt| {
        println!("🔄 Transition via event: {:?}", evt);
    });

    // Fires on *every* transition *with* a u32 payload (e.g. payments).
    nano.on_transition_with(|evt, amount: &u32| {
        println!("🌐 Global saw {}¢ payment via {:?}", amount, evt);
    });

    // Fires on *every* transition *with* a String payload
    // (e.g. tracking codes or cancellation reasons).
    nano.on_transition_with(|evt, text: &String| {
        println!("🌐 Global saw string payload {:?}: {}", evt, text);
    });
    // Inspect machine metadata:
    println!("All states: {:?}", nano.states().cloned().collect::<Vec<_>>());
    println!("All events: {:?}", nano.events().cloned().collect::<Vec<_>>());
    println!(
        "Triggerable now ({:?}): {:?}",
        nano.state(),
        nano.triggerable_events().cloned().collect::<Vec<_>>()
    );
    println!();

    // Simulate a successful order:
    //    Pay with payload.
    nano.trigger_with(&OrderEvent::Pay, &2_500u32)
        .expect("Should transition to Paid");
    //    Ship with payload.
    nano.trigger_with(&OrderEvent::Ship, &"TRACK1234".to_string())
        .expect("Should transition to Shipped");
    //    Deliver without payload.
    nano.trigger(&OrderEvent::Deliver).expect("Should transition to Delivered");
    println!("\nFinal state: {:?}\n", nano.state());

    // Attempt an invalid transition (Pay after Delivered).
    match nano.trigger(&OrderEvent::Pay) {
        Ok(_) => println!("Unexpectedly succeeded!"),
        Err(e) => println!("Error trying to pay in {:?}: {}", nano.state(), e),
    }

    // Create a fresh order and cancel it early.
    let mut nano = Machine::new(OrderState::Created);
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );
    // Re-attach only the Cancel callback.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("Order #2 cancelled reason: {}", reason);
    });
    // Cancel with a payload.
    nano.trigger_with(
        &OrderEvent::Cancel,
        &"Customer changed mind".to_string(),
    )
    .unwrap();

    println!("Order #2 final: {:?}", nano.state());
}

pub fn when_iter<I>(&mut self, event: E, mapping: I)

where I: IntoIterator<Item = (S, S)>,

Define multiple transitions for a single event.

The mapping iterator should yield (from_state, to_state) pairs.

Examples found in repository

examples/order.rs (lines 34-40)

fn main() {
    // Create the machine in the Created state.
    let mut nano = Machine::new(OrderState::Created);

    // Define transitions one-by-one.
    nano.when(OrderEvent::Pay, OrderState::Created, OrderState::Paid);
    nano.when(OrderEvent::Ship, OrderState::Paid, OrderState::Shipped);
    nano.when(OrderEvent::Deliver, OrderState::Shipped, OrderState::Delivered);

    // Define Cancel for both Created and Paid using when_iter.
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );

    // ─── State-specific hooks ───────────────────────────────────────────────
    // On Paid: log payment amount.
    nano.on_enter_with(OrderState::Paid, |evt, amount: &u32| {
        println!("✔ Payment {:?}: {}¢ received", evt, amount);
    });

    // On Shipped: log tracking code.
    nano.on_enter_with(OrderState::Shipped, |_evt, tracking: &String| {
        println!("🚚 Order shipped! Tracking code: {}", tracking);
    });

    // On Delivered: confirmation.
    nano.on_enter_with(OrderState::Delivered, |_evt, _: &()| {
        println!("📦 Order delivered. Thank you!");
    });

    // On Cancelled: show cancellation reason.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("❌ Order cancelled: {}", reason);
    });

    // ─── Global hooks ───────────────────────────────────────────────────────
    // Fires on *every* transition (no payload).
    nano.on_transition(|evt| {
        println!("🔄 Transition via event: {:?}", evt);
    });

    // Fires on *every* transition *with* a u32 payload (e.g. payments).
    nano.on_transition_with(|evt, amount: &u32| {
        println!("🌐 Global saw {}¢ payment via {:?}", amount, evt);
    });

    // Fires on *every* transition *with* a String payload
    // (e.g. tracking codes or cancellation reasons).
    nano.on_transition_with(|evt, text: &String| {
        println!("🌐 Global saw string payload {:?}: {}", evt, text);
    });
    // Inspect machine metadata:
    println!("All states: {:?}", nano.states().cloned().collect::<Vec<_>>());
    println!("All events: {:?}", nano.events().cloned().collect::<Vec<_>>());
    println!(
        "Triggerable now ({:?}): {:?}",
        nano.state(),
        nano.triggerable_events().cloned().collect::<Vec<_>>()
    );
    println!();

    // Simulate a successful order:
    //    Pay with payload.
    nano.trigger_with(&OrderEvent::Pay, &2_500u32)
        .expect("Should transition to Paid");
    //    Ship with payload.
    nano.trigger_with(&OrderEvent::Ship, &"TRACK1234".to_string())
        .expect("Should transition to Shipped");
    //    Deliver without payload.
    nano.trigger(&OrderEvent::Deliver).expect("Should transition to Delivered");
    println!("\nFinal state: {:?}\n", nano.state());

    // Attempt an invalid transition (Pay after Delivered).
    match nano.trigger(&OrderEvent::Pay) {
        Ok(_) => println!("Unexpectedly succeeded!"),
        Err(e) => println!("Error trying to pay in {:?}: {}", nano.state(), e),
    }

    // Create a fresh order and cancel it early.
    let mut nano = Machine::new(OrderState::Created);
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );
    // Re-attach only the Cancel callback.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("Order #2 cancelled reason: {}", reason);
    });
    // Cancel with a payload.
    nano.trigger_with(
        &OrderEvent::Cancel,
        &"Customer changed mind".to_string(),
    )
    .unwrap();

    println!("Order #2 final: {:?}", nano.state());
}

pub fn on_enter<F>(&mut self, state: S, callback: F)

where F: Fn(E) + 'static,

Register a callback that only cares about the event (no payload).

Examples found in repository

examples/callbacks.rs (line 13)

fn main() {
    let mut nano = Machine::new("locked");

    // Define valid transitions.
    nano.when("insert coin", "locked", "unlocked");
    nano.when("turn knob", "unlocked", "locked");

    // State-specific callbacks without payload.
    nano.on_enter("unlocked", |e| println!("Unlocked via {:?}", e));
    nano.on_enter("locked", |e| println!("Locked via {:?}", e));

    // State-specific callback with a u32 payload.
    nano.on_enter_with("unlocked", |e, amount: &u32| {
        println!("Received {} cents via {:?}", amount, e);
    });

    // Global callbacks.
    nano.on_transition(|e| println!("Global - event {:?}", e));
    nano.on_transition_with(|e, amount: &u32| {
        println!("Global - saw {} cents via {:?}", amount, e);
    });
    nano.on_transition_with(|e, msg: &String| {
        println!("Global - saw \"{}\" via {:?}", msg, e);
    });

    // Prints:
    //   Unlocked via "insert coin"
    //   Global - event "insert coin"
    nano.trigger(&"insert coin").unwrap();

    // Prints:
    //   Locked via "turn knob"
    //   Global - event "turn knob"
    //   Global - saw "voucher" via "turn knob"
    nano.trigger_with(&"turn knob", &"voucher".to_string()).unwrap();

    // Prints:
    //   Unlocked via "insert coin"
    //   Received 50 cents via "insert coin"
    //   Global - event "insert coin"
    //   Global - saw 50 cents via "insert coin"
    nano.trigger_with(&"insert coin", &50u32).unwrap();

    // Final state: "unlocked"
    println!("Final state: {:?}", nano.state());
}

pub fn on_enter_with<P, F>(&mut self, state: S, callback: F)

where P: 'static, F: Fn(E, &P) + 'static,

Register a callback that expects a payload of type P.

The callback takes the triggering event and a payload of type P. It will only be invoked if the payload downcasts to P successfully.

Examples found in repository

examples/callbacks.rs (lines 17-19)

fn main() {
    let mut nano = Machine::new("locked");

    // Define valid transitions.
    nano.when("insert coin", "locked", "unlocked");
    nano.when("turn knob", "unlocked", "locked");

    // State-specific callbacks without payload.
    nano.on_enter("unlocked", |e| println!("Unlocked via {:?}", e));
    nano.on_enter("locked", |e| println!("Locked via {:?}", e));

    // State-specific callback with a u32 payload.
    nano.on_enter_with("unlocked", |e, amount: &u32| {
        println!("Received {} cents via {:?}", amount, e);
    });

    // Global callbacks.
    nano.on_transition(|e| println!("Global - event {:?}", e));
    nano.on_transition_with(|e, amount: &u32| {
        println!("Global - saw {} cents via {:?}", amount, e);
    });
    nano.on_transition_with(|e, msg: &String| {
        println!("Global - saw \"{}\" via {:?}", msg, e);
    });

    // Prints:
    //   Unlocked via "insert coin"
    //   Global - event "insert coin"
    nano.trigger(&"insert coin").unwrap();

    // Prints:
    //   Locked via "turn knob"
    //   Global - event "turn knob"
    //   Global - saw "voucher" via "turn knob"
    nano.trigger_with(&"turn knob", &"voucher".to_string()).unwrap();

    // Prints:
    //   Unlocked via "insert coin"
    //   Received 50 cents via "insert coin"
    //   Global - event "insert coin"
    //   Global - saw 50 cents via "insert coin"
    nano.trigger_with(&"insert coin", &50u32).unwrap();

    // Final state: "unlocked"
    println!("Final state: {:?}", nano.state());
}

examples/order.rs (lines 44-46)

fn main() {
    // Create the machine in the Created state.
    let mut nano = Machine::new(OrderState::Created);

    // Define transitions one-by-one.
    nano.when(OrderEvent::Pay, OrderState::Created, OrderState::Paid);
    nano.when(OrderEvent::Ship, OrderState::Paid, OrderState::Shipped);
    nano.when(OrderEvent::Deliver, OrderState::Shipped, OrderState::Delivered);

    // Define Cancel for both Created and Paid using when_iter.
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );

    // ─── State-specific hooks ───────────────────────────────────────────────
    // On Paid: log payment amount.
    nano.on_enter_with(OrderState::Paid, |evt, amount: &u32| {
        println!("✔ Payment {:?}: {}¢ received", evt, amount);
    });

    // On Shipped: log tracking code.
    nano.on_enter_with(OrderState::Shipped, |_evt, tracking: &String| {
        println!("🚚 Order shipped! Tracking code: {}", tracking);
    });

    // On Delivered: confirmation.
    nano.on_enter_with(OrderState::Delivered, |_evt, _: &()| {
        println!("📦 Order delivered. Thank you!");
    });

    // On Cancelled: show cancellation reason.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("❌ Order cancelled: {}", reason);
    });

    // ─── Global hooks ───────────────────────────────────────────────────────
    // Fires on *every* transition (no payload).
    nano.on_transition(|evt| {
        println!("🔄 Transition via event: {:?}", evt);
    });

    // Fires on *every* transition *with* a u32 payload (e.g. payments).
    nano.on_transition_with(|evt, amount: &u32| {
        println!("🌐 Global saw {}¢ payment via {:?}", amount, evt);
    });

    // Fires on *every* transition *with* a String payload
    // (e.g. tracking codes or cancellation reasons).
    nano.on_transition_with(|evt, text: &String| {
        println!("🌐 Global saw string payload {:?}: {}", evt, text);
    });
    // Inspect machine metadata:
    println!("All states: {:?}", nano.states().cloned().collect::<Vec<_>>());
    println!("All events: {:?}", nano.events().cloned().collect::<Vec<_>>());
    println!(
        "Triggerable now ({:?}): {:?}",
        nano.state(),
        nano.triggerable_events().cloned().collect::<Vec<_>>()
    );
    println!();

    // Simulate a successful order:
    //    Pay with payload.
    nano.trigger_with(&OrderEvent::Pay, &2_500u32)
        .expect("Should transition to Paid");
    //    Ship with payload.
    nano.trigger_with(&OrderEvent::Ship, &"TRACK1234".to_string())
        .expect("Should transition to Shipped");
    //    Deliver without payload.
    nano.trigger(&OrderEvent::Deliver).expect("Should transition to Delivered");
    println!("\nFinal state: {:?}\n", nano.state());

    // Attempt an invalid transition (Pay after Delivered).
    match nano.trigger(&OrderEvent::Pay) {
        Ok(_) => println!("Unexpectedly succeeded!"),
        Err(e) => println!("Error trying to pay in {:?}: {}", nano.state(), e),
    }

    // Create a fresh order and cancel it early.
    let mut nano = Machine::new(OrderState::Created);
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );
    // Re-attach only the Cancel callback.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("Order #2 cancelled reason: {}", reason);
    });
    // Cancel with a payload.
    nano.trigger_with(
        &OrderEvent::Cancel,
        &"Customer changed mind".to_string(),
    )
    .unwrap();

    println!("Order #2 final: {:?}", nano.state());
}

pub fn on_transition<F>(&mut self, callback: F)

where F: Fn(E) + 'static + Clone,

Register a callback to fire on any state transition.

Works similarly to on_enter, but the callback runs regardless of the specific state entered.

Examples found in repository

examples/callbacks.rs (line 22)

fn main() {
    let mut nano = Machine::new("locked");

    // Define valid transitions.
    nano.when("insert coin", "locked", "unlocked");
    nano.when("turn knob", "unlocked", "locked");

    // State-specific callbacks without payload.
    nano.on_enter("unlocked", |e| println!("Unlocked via {:?}", e));
    nano.on_enter("locked", |e| println!("Locked via {:?}", e));

    // State-specific callback with a u32 payload.
    nano.on_enter_with("unlocked", |e, amount: &u32| {
        println!("Received {} cents via {:?}", amount, e);
    });

    // Global callbacks.
    nano.on_transition(|e| println!("Global - event {:?}", e));
    nano.on_transition_with(|e, amount: &u32| {
        println!("Global - saw {} cents via {:?}", amount, e);
    });
    nano.on_transition_with(|e, msg: &String| {
        println!("Global - saw \"{}\" via {:?}", msg, e);
    });

    // Prints:
    //   Unlocked via "insert coin"
    //   Global - event "insert coin"
    nano.trigger(&"insert coin").unwrap();

    // Prints:
    //   Locked via "turn knob"
    //   Global - event "turn knob"
    //   Global - saw "voucher" via "turn knob"
    nano.trigger_with(&"turn knob", &"voucher".to_string()).unwrap();

    // Prints:
    //   Unlocked via "insert coin"
    //   Received 50 cents via "insert coin"
    //   Global - event "insert coin"
    //   Global - saw 50 cents via "insert coin"
    nano.trigger_with(&"insert coin", &50u32).unwrap();

    // Final state: "unlocked"
    println!("Final state: {:?}", nano.state());
}

examples/order.rs (lines 65-67)

fn main() {
    // Create the machine in the Created state.
    let mut nano = Machine::new(OrderState::Created);

    // Define transitions one-by-one.
    nano.when(OrderEvent::Pay, OrderState::Created, OrderState::Paid);
    nano.when(OrderEvent::Ship, OrderState::Paid, OrderState::Shipped);
    nano.when(OrderEvent::Deliver, OrderState::Shipped, OrderState::Delivered);

    // Define Cancel for both Created and Paid using when_iter.
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );

    // ─── State-specific hooks ───────────────────────────────────────────────
    // On Paid: log payment amount.
    nano.on_enter_with(OrderState::Paid, |evt, amount: &u32| {
        println!("✔ Payment {:?}: {}¢ received", evt, amount);
    });

    // On Shipped: log tracking code.
    nano.on_enter_with(OrderState::Shipped, |_evt, tracking: &String| {
        println!("🚚 Order shipped! Tracking code: {}", tracking);
    });

    // On Delivered: confirmation.
    nano.on_enter_with(OrderState::Delivered, |_evt, _: &()| {
        println!("📦 Order delivered. Thank you!");
    });

    // On Cancelled: show cancellation reason.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("❌ Order cancelled: {}", reason);
    });

    // ─── Global hooks ───────────────────────────────────────────────────────
    // Fires on *every* transition (no payload).
    nano.on_transition(|evt| {
        println!("🔄 Transition via event: {:?}", evt);
    });

    // Fires on *every* transition *with* a u32 payload (e.g. payments).
    nano.on_transition_with(|evt, amount: &u32| {
        println!("🌐 Global saw {}¢ payment via {:?}", amount, evt);
    });

    // Fires on *every* transition *with* a String payload
    // (e.g. tracking codes or cancellation reasons).
    nano.on_transition_with(|evt, text: &String| {
        println!("🌐 Global saw string payload {:?}: {}", evt, text);
    });
    // Inspect machine metadata:
    println!("All states: {:?}", nano.states().cloned().collect::<Vec<_>>());
    println!("All events: {:?}", nano.events().cloned().collect::<Vec<_>>());
    println!(
        "Triggerable now ({:?}): {:?}",
        nano.state(),
        nano.triggerable_events().cloned().collect::<Vec<_>>()
    );
    println!();

    // Simulate a successful order:
    //    Pay with payload.
    nano.trigger_with(&OrderEvent::Pay, &2_500u32)
        .expect("Should transition to Paid");
    //    Ship with payload.
    nano.trigger_with(&OrderEvent::Ship, &"TRACK1234".to_string())
        .expect("Should transition to Shipped");
    //    Deliver without payload.
    nano.trigger(&OrderEvent::Deliver).expect("Should transition to Delivered");
    println!("\nFinal state: {:?}\n", nano.state());

    // Attempt an invalid transition (Pay after Delivered).
    match nano.trigger(&OrderEvent::Pay) {
        Ok(_) => println!("Unexpectedly succeeded!"),
        Err(e) => println!("Error trying to pay in {:?}: {}", nano.state(), e),
    }

    // Create a fresh order and cancel it early.
    let mut nano = Machine::new(OrderState::Created);
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );
    // Re-attach only the Cancel callback.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("Order #2 cancelled reason: {}", reason);
    });
    // Cancel with a payload.
    nano.trigger_with(
        &OrderEvent::Cancel,
        &"Customer changed mind".to_string(),
    )
    .unwrap();

    println!("Order #2 final: {:?}", nano.state());
}

pub fn on_transition_with<P, F>(&mut self, callback: F)

where P: 'static, F: Fn(E, &P) + 'static + Clone,

Register a callback to fire on any state transition with a payload of type P.

Works similarly to on_enter_with, but the callback runs regardless of the specific state, and only if the payload downcasts to P successfully.

Examples found in repository

examples/callbacks.rs (lines 23-25)

fn main() {
    let mut nano = Machine::new("locked");

    // Define valid transitions.
    nano.when("insert coin", "locked", "unlocked");
    nano.when("turn knob", "unlocked", "locked");

    // State-specific callbacks without payload.
    nano.on_enter("unlocked", |e| println!("Unlocked via {:?}", e));
    nano.on_enter("locked", |e| println!("Locked via {:?}", e));

    // State-specific callback with a u32 payload.
    nano.on_enter_with("unlocked", |e, amount: &u32| {
        println!("Received {} cents via {:?}", amount, e);
    });

    // Global callbacks.
    nano.on_transition(|e| println!("Global - event {:?}", e));
    nano.on_transition_with(|e, amount: &u32| {
        println!("Global - saw {} cents via {:?}", amount, e);
    });
    nano.on_transition_with(|e, msg: &String| {
        println!("Global - saw \"{}\" via {:?}", msg, e);
    });

    // Prints:
    //   Unlocked via "insert coin"
    //   Global - event "insert coin"
    nano.trigger(&"insert coin").unwrap();

    // Prints:
    //   Locked via "turn knob"
    //   Global - event "turn knob"
    //   Global - saw "voucher" via "turn knob"
    nano.trigger_with(&"turn knob", &"voucher".to_string()).unwrap();

    // Prints:
    //   Unlocked via "insert coin"
    //   Received 50 cents via "insert coin"
    //   Global - event "insert coin"
    //   Global - saw 50 cents via "insert coin"
    nano.trigger_with(&"insert coin", &50u32).unwrap();

    // Final state: "unlocked"
    println!("Final state: {:?}", nano.state());
}

examples/order.rs (lines 70-72)

fn main() {
    // Create the machine in the Created state.
    let mut nano = Machine::new(OrderState::Created);

    // Define transitions one-by-one.
    nano.when(OrderEvent::Pay, OrderState::Created, OrderState::Paid);
    nano.when(OrderEvent::Ship, OrderState::Paid, OrderState::Shipped);
    nano.when(OrderEvent::Deliver, OrderState::Shipped, OrderState::Delivered);

    // Define Cancel for both Created and Paid using when_iter.
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );

    // ─── State-specific hooks ───────────────────────────────────────────────
    // On Paid: log payment amount.
    nano.on_enter_with(OrderState::Paid, |evt, amount: &u32| {
        println!("✔ Payment {:?}: {}¢ received", evt, amount);
    });

    // On Shipped: log tracking code.
    nano.on_enter_with(OrderState::Shipped, |_evt, tracking: &String| {
        println!("🚚 Order shipped! Tracking code: {}", tracking);
    });

    // On Delivered: confirmation.
    nano.on_enter_with(OrderState::Delivered, |_evt, _: &()| {
        println!("📦 Order delivered. Thank you!");
    });

    // On Cancelled: show cancellation reason.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("❌ Order cancelled: {}", reason);
    });

    // ─── Global hooks ───────────────────────────────────────────────────────
    // Fires on *every* transition (no payload).
    nano.on_transition(|evt| {
        println!("🔄 Transition via event: {:?}", evt);
    });

    // Fires on *every* transition *with* a u32 payload (e.g. payments).
    nano.on_transition_with(|evt, amount: &u32| {
        println!("🌐 Global saw {}¢ payment via {:?}", amount, evt);
    });

    // Fires on *every* transition *with* a String payload
    // (e.g. tracking codes or cancellation reasons).
    nano.on_transition_with(|evt, text: &String| {
        println!("🌐 Global saw string payload {:?}: {}", evt, text);
    });
    // Inspect machine metadata:
    println!("All states: {:?}", nano.states().cloned().collect::<Vec<_>>());
    println!("All events: {:?}", nano.events().cloned().collect::<Vec<_>>());
    println!(
        "Triggerable now ({:?}): {:?}",
        nano.state(),
        nano.triggerable_events().cloned().collect::<Vec<_>>()
    );
    println!();

    // Simulate a successful order:
    //    Pay with payload.
    nano.trigger_with(&OrderEvent::Pay, &2_500u32)
        .expect("Should transition to Paid");
    //    Ship with payload.
    nano.trigger_with(&OrderEvent::Ship, &"TRACK1234".to_string())
        .expect("Should transition to Shipped");
    //    Deliver without payload.
    nano.trigger(&OrderEvent::Deliver).expect("Should transition to Delivered");
    println!("\nFinal state: {:?}\n", nano.state());

    // Attempt an invalid transition (Pay after Delivered).
    match nano.trigger(&OrderEvent::Pay) {
        Ok(_) => println!("Unexpectedly succeeded!"),
        Err(e) => println!("Error trying to pay in {:?}: {}", nano.state(), e),
    }

    // Create a fresh order and cancel it early.
    let mut nano = Machine::new(OrderState::Created);
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );
    // Re-attach only the Cancel callback.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("Order #2 cancelled reason: {}", reason);
    });
    // Cancel with a payload.
    nano.trigger_with(
        &OrderEvent::Cancel,
        &"Customer changed mind".to_string(),
    )
    .unwrap();

    println!("Order #2 final: {:?}", nano.state());
}

pub fn trigger(&mut self, event: &E) -> Result<(), MachineError>

Trigger the given event on the machine without any payload.

If the event is defined for the current state, the machine will transition to the corresponding new state and invoke any registered callbacks.

Errors

• Returns MachineError::EventInvalid if the event is not defined in this state machine.
• Returns MachineError::StateInvalid if the event has no transition defined for the machine’s current state.

Examples found in repository

examples/callbacks.rs (line 33)

fn main() {
    let mut nano = Machine::new("locked");

    // Define valid transitions.
    nano.when("insert coin", "locked", "unlocked");
    nano.when("turn knob", "unlocked", "locked");

    // State-specific callbacks without payload.
    nano.on_enter("unlocked", |e| println!("Unlocked via {:?}", e));
    nano.on_enter("locked", |e| println!("Locked via {:?}", e));

    // State-specific callback with a u32 payload.
    nano.on_enter_with("unlocked", |e, amount: &u32| {
        println!("Received {} cents via {:?}", amount, e);
    });

    // Global callbacks.
    nano.on_transition(|e| println!("Global - event {:?}", e));
    nano.on_transition_with(|e, amount: &u32| {
        println!("Global - saw {} cents via {:?}", amount, e);
    });
    nano.on_transition_with(|e, msg: &String| {
        println!("Global - saw \"{}\" via {:?}", msg, e);
    });

    // Prints:
    //   Unlocked via "insert coin"
    //   Global - event "insert coin"
    nano.trigger(&"insert coin").unwrap();

    // Prints:
    //   Locked via "turn knob"
    //   Global - event "turn knob"
    //   Global - saw "voucher" via "turn knob"
    nano.trigger_with(&"turn knob", &"voucher".to_string()).unwrap();

    // Prints:
    //   Unlocked via "insert coin"
    //   Received 50 cents via "insert coin"
    //   Global - event "insert coin"
    //   Global - saw 50 cents via "insert coin"
    nano.trigger_with(&"insert coin", &50u32).unwrap();

    // Final state: "unlocked"
    println!("Final state: {:?}", nano.state());
}

examples/order.rs (line 97)

fn main() {
    // Create the machine in the Created state.
    let mut nano = Machine::new(OrderState::Created);

    // Define transitions one-by-one.
    nano.when(OrderEvent::Pay, OrderState::Created, OrderState::Paid);
    nano.when(OrderEvent::Ship, OrderState::Paid, OrderState::Shipped);
    nano.when(OrderEvent::Deliver, OrderState::Shipped, OrderState::Delivered);

    // Define Cancel for both Created and Paid using when_iter.
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );

    // ─── State-specific hooks ───────────────────────────────────────────────
    // On Paid: log payment amount.
    nano.on_enter_with(OrderState::Paid, |evt, amount: &u32| {
        println!("✔ Payment {:?}: {}¢ received", evt, amount);
    });

    // On Shipped: log tracking code.
    nano.on_enter_with(OrderState::Shipped, |_evt, tracking: &String| {
        println!("🚚 Order shipped! Tracking code: {}", tracking);
    });

    // On Delivered: confirmation.
    nano.on_enter_with(OrderState::Delivered, |_evt, _: &()| {
        println!("📦 Order delivered. Thank you!");
    });

    // On Cancelled: show cancellation reason.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("❌ Order cancelled: {}", reason);
    });

    // ─── Global hooks ───────────────────────────────────────────────────────
    // Fires on *every* transition (no payload).
    nano.on_transition(|evt| {
        println!("🔄 Transition via event: {:?}", evt);
    });

    // Fires on *every* transition *with* a u32 payload (e.g. payments).
    nano.on_transition_with(|evt, amount: &u32| {
        println!("🌐 Global saw {}¢ payment via {:?}", amount, evt);
    });

    // Fires on *every* transition *with* a String payload
    // (e.g. tracking codes or cancellation reasons).
    nano.on_transition_with(|evt, text: &String| {
        println!("🌐 Global saw string payload {:?}: {}", evt, text);
    });
    // Inspect machine metadata:
    println!("All states: {:?}", nano.states().cloned().collect::<Vec<_>>());
    println!("All events: {:?}", nano.events().cloned().collect::<Vec<_>>());
    println!(
        "Triggerable now ({:?}): {:?}",
        nano.state(),
        nano.triggerable_events().cloned().collect::<Vec<_>>()
    );
    println!();

    // Simulate a successful order:
    //    Pay with payload.
    nano.trigger_with(&OrderEvent::Pay, &2_500u32)
        .expect("Should transition to Paid");
    //    Ship with payload.
    nano.trigger_with(&OrderEvent::Ship, &"TRACK1234".to_string())
        .expect("Should transition to Shipped");
    //    Deliver without payload.
    nano.trigger(&OrderEvent::Deliver).expect("Should transition to Delivered");
    println!("\nFinal state: {:?}\n", nano.state());

    // Attempt an invalid transition (Pay after Delivered).
    match nano.trigger(&OrderEvent::Pay) {
        Ok(_) => println!("Unexpectedly succeeded!"),
        Err(e) => println!("Error trying to pay in {:?}: {}", nano.state(), e),
    }

    // Create a fresh order and cancel it early.
    let mut nano = Machine::new(OrderState::Created);
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );
    // Re-attach only the Cancel callback.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("Order #2 cancelled reason: {}", reason);
    });
    // Cancel with a payload.
    nano.trigger_with(
        &OrderEvent::Cancel,
        &"Customer changed mind".to_string(),
    )
    .unwrap();

    println!("Order #2 final: {:?}", nano.state());
}

pub fn trigger_with<P>( &mut self, event: &E, payload: &P, ) -> Result<(), MachineError>

where P: 'static,

Trigger the given event on the machine with an associated payload.

The payload will be provided to callbacks that accept the payload type P. If the event is defined for the current state, the machine will perform the transition and invoke any matching callbacks.

Errors

• Returns MachineError::EventInvalid if the event is not defined in this state machine.
• Returns MachineError::StateInvalid if no transition is defined for the machine’s current state with the given event.

Examples found in repository

examples/callbacks.rs (line 39)

fn main() {
    let mut nano = Machine::new("locked");

    // Define valid transitions.
    nano.when("insert coin", "locked", "unlocked");
    nano.when("turn knob", "unlocked", "locked");

    // State-specific callbacks without payload.
    nano.on_enter("unlocked", |e| println!("Unlocked via {:?}", e));
    nano.on_enter("locked", |e| println!("Locked via {:?}", e));

    // State-specific callback with a u32 payload.
    nano.on_enter_with("unlocked", |e, amount: &u32| {
        println!("Received {} cents via {:?}", amount, e);
    });

    // Global callbacks.
    nano.on_transition(|e| println!("Global - event {:?}", e));
    nano.on_transition_with(|e, amount: &u32| {
        println!("Global - saw {} cents via {:?}", amount, e);
    });
    nano.on_transition_with(|e, msg: &String| {
        println!("Global - saw \"{}\" via {:?}", msg, e);
    });

    // Prints:
    //   Unlocked via "insert coin"
    //   Global - event "insert coin"
    nano.trigger(&"insert coin").unwrap();

    // Prints:
    //   Locked via "turn knob"
    //   Global - event "turn knob"
    //   Global - saw "voucher" via "turn knob"
    nano.trigger_with(&"turn knob", &"voucher".to_string()).unwrap();

    // Prints:
    //   Unlocked via "insert coin"
    //   Received 50 cents via "insert coin"
    //   Global - event "insert coin"
    //   Global - saw 50 cents via "insert coin"
    nano.trigger_with(&"insert coin", &50u32).unwrap();

    // Final state: "unlocked"
    println!("Final state: {:?}", nano.state());
}

examples/order.rs (line 91)

fn main() {
    // Create the machine in the Created state.
    let mut nano = Machine::new(OrderState::Created);

    // Define transitions one-by-one.
    nano.when(OrderEvent::Pay, OrderState::Created, OrderState::Paid);
    nano.when(OrderEvent::Ship, OrderState::Paid, OrderState::Shipped);
    nano.when(OrderEvent::Deliver, OrderState::Shipped, OrderState::Delivered);

    // Define Cancel for both Created and Paid using when_iter.
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );

    // ─── State-specific hooks ───────────────────────────────────────────────
    // On Paid: log payment amount.
    nano.on_enter_with(OrderState::Paid, |evt, amount: &u32| {
        println!("✔ Payment {:?}: {}¢ received", evt, amount);
    });

    // On Shipped: log tracking code.
    nano.on_enter_with(OrderState::Shipped, |_evt, tracking: &String| {
        println!("🚚 Order shipped! Tracking code: {}", tracking);
    });

    // On Delivered: confirmation.
    nano.on_enter_with(OrderState::Delivered, |_evt, _: &()| {
        println!("📦 Order delivered. Thank you!");
    });

    // On Cancelled: show cancellation reason.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("❌ Order cancelled: {}", reason);
    });

    // ─── Global hooks ───────────────────────────────────────────────────────
    // Fires on *every* transition (no payload).
    nano.on_transition(|evt| {
        println!("🔄 Transition via event: {:?}", evt);
    });

    // Fires on *every* transition *with* a u32 payload (e.g. payments).
    nano.on_transition_with(|evt, amount: &u32| {
        println!("🌐 Global saw {}¢ payment via {:?}", amount, evt);
    });

    // Fires on *every* transition *with* a String payload
    // (e.g. tracking codes or cancellation reasons).
    nano.on_transition_with(|evt, text: &String| {
        println!("🌐 Global saw string payload {:?}: {}", evt, text);
    });
    // Inspect machine metadata:
    println!("All states: {:?}", nano.states().cloned().collect::<Vec<_>>());
    println!("All events: {:?}", nano.events().cloned().collect::<Vec<_>>());
    println!(
        "Triggerable now ({:?}): {:?}",
        nano.state(),
        nano.triggerable_events().cloned().collect::<Vec<_>>()
    );
    println!();

    // Simulate a successful order:
    //    Pay with payload.
    nano.trigger_with(&OrderEvent::Pay, &2_500u32)
        .expect("Should transition to Paid");
    //    Ship with payload.
    nano.trigger_with(&OrderEvent::Ship, &"TRACK1234".to_string())
        .expect("Should transition to Shipped");
    //    Deliver without payload.
    nano.trigger(&OrderEvent::Deliver).expect("Should transition to Delivered");
    println!("\nFinal state: {:?}\n", nano.state());

    // Attempt an invalid transition (Pay after Delivered).
    match nano.trigger(&OrderEvent::Pay) {
        Ok(_) => println!("Unexpectedly succeeded!"),
        Err(e) => println!("Error trying to pay in {:?}: {}", nano.state(), e),
    }

    // Create a fresh order and cancel it early.
    let mut nano = Machine::new(OrderState::Created);
    nano.when_iter(
        OrderEvent::Cancel,
        [
            (OrderState::Created, OrderState::Cancelled),
            (OrderState::Paid, OrderState::Cancelled),
        ],
    );
    // Re-attach only the Cancel callback.
    nano.on_enter_with(OrderState::Cancelled, |_evt, reason: &String| {
        println!("Order #2 cancelled reason: {}", reason);
    });
    // Cancel with a payload.
    nano.trigger_with(
        &OrderEvent::Cancel,
        &"Customer changed mind".to_string(),
    )
    .unwrap();

    println!("Order #2 final: {:?}", nano.state());
}

Trait Implementations

impl<S: Clone, E: Clone> Clone for Machine<S, E>

fn clone(&self) -> Machine<S, E>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S: Debug + Eq + Hash + Clone, E: Debug + Eq + Hash + Clone> Debug for Machine<S, E>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<S, E> Default for Machine<S, E>

where S: Default,

fn default() -> Self

Create a default machine, using S::default() as the initial state.