moku 0.4.0

#![warn(missing_docs)]
#![doc = include_str!("../README.md")]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![cfg_attr(not(feature = "std"), no_std)]

/// Designates a module for state machine generation.
///
/// Moku expects the following items directly inside of the attributed module:
/// - an empty module attributed with [`machine_module`]
/// - exactly one implementation of [`TopState`]
/// - any number of implementations of [`Substate`]
///
/// An optional name can be provided as an argument to set the default name of the
/// [`StateMachine`] for use in logging. If not provided, the name defaults to the
/// module name in `UpperCamel` case. This is useful for `no_std` environments
/// where [`StateMachine::set_name`] is not available.
///
/// ## Examples
/// ```
/// #[moku::state_machine]
/// mod blinky {
///     #[moku::machine_module]
///     mod machine {}
///
///     use machine::State;
///
///     struct Top;
///     impl moku::TopState for Top {}
///
///     struct Led;
///     impl moku::Substate<Top> for Led {}
/// }
/// ```
///
/// With a custom name:
/// ```
/// #[moku::state_machine(Kikai)]
/// mod my_machine {
///     #[moku::machine_module]
///     pub mod machine {}
///
///     pub struct Top;
///     impl moku::TopState for Top {}
/// }
///
/// # use moku::*;
/// let machine = my_machine::machine::Builder::new(my_machine::Top).build();
/// assert_eq!(machine.name(), "Kikai");
/// ```
pub use moku_macros::state_machine;

/// Designates a module to be populated with the autogenerated code of a state machine.
///
/// The module must be empty and reside directly inside a module attributed with [`state_machine`].
///
/// ## Example
/// ```
/// #[moku::state_machine]
/// mod blinky {
///     #[moku::machine_module]
///     mod machine {}
///
///     use machine::State;
///
///     struct Top;
///     impl moku::TopState for Top {}
/// }
/// ```
pub use moku_macros::machine_module;

/// Represents either no action or some type of transition to new state.
///
/// Return type of multiple [`Substate`] methods.
pub enum Next<T: StateEnum> {
    /// No transition should be taken, stay in the current active state.
    None,

    /// A transition should be taken to the target state.
    /// See [`StateMachine::transition`] for transition semantics.
    Target(T),

    /// A transition should be taken to exactly the target state.
    /// See [`StateMachine::exact_transition`] for exact transition semantics.
    ExactTarget(T),
}

impl<T: StateEnum> From<T> for Next<T> {
    fn from(value: T) -> Self {
        Next::Target(value)
    }
}

impl<T: StateEnum> From<Option<T>> for Next<T> {
    fn from(value: Option<T>) -> Self {
        match value {
            None => Next::None,
            Some(target) => Next::Target(target),
        }
    }
}

impl<T: StateEnum> From<()> for Next<T> {
    fn from(_: ()) -> Self {
        Next::None
    }
}

/// A state machine event.
///
/// Optionally implement this trait for a single type in a [`state_machine`] module
/// to mark it as the event type to be used by the state machine and its states.
pub trait StateMachineEvent {}

impl StateMachineEvent for () {}

/// The result of a single state handling an event.
///
/// Implements [`From`] for implementors of `StateEnum` and `Option<StateEnum>`
pub enum Response<T: StateEnum> {
    /// The transition triggered by the event.
    /// A value of Next::None defers the handling of the event to the superstate.
    Next(Next<T>),

    /// Drop the event and stop handling it immediately.
    Drop,
}

impl<T: StateEnum> From<T> for Response<T> {
    fn from(value: T) -> Self {
        Response::Next(value.into())
    }
}

impl<T: StateEnum> From<Option<T>> for Response<T> {
    fn from(value: Option<T>) -> Self {
        Response::Next(value.into())
    }
}

impl<T: StateEnum> From<()> for Response<T> {
    fn from(_: ()) -> Self {
        Response::Next(Next::None)
    }
}

impl<T: StateEnum> From<Next<T>> for Response<T> {
    fn from(value: Next<T>) -> Self {
        Response::Next(value)
    }
}

/// A flat list of all states in a state machine.
///
/// Autogenerated by moku in the [`machine_module`] as `State`.
///
/// # Example
/// For some machine:
/// ```text
/// Top
/// ├─ Foo
/// │  └─ Bar
/// └─ Fizz
///    └─ Buzz
/// ```
/// The [`StateEnum`] would be:
/// ```
/// #[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// pub enum State {
///     Top,
///     Foo,
///     Bar,
///     Fizz,
///     Buzz,
/// }
/// ```
pub trait StateEnum: core::fmt::Debug + Clone + Copy + PartialEq + Eq {}

/// A state machine.
pub trait StateMachine<T, U, V>
where
    T: StateEnum,
    U: StateMachineEvent,
    V: TopState,
{
    /// Update the state machine.
    ///
    /// Starting with the deepest state, calls [`Substate::update`] (or [`TopState::update`]).
    ///
    /// If any state returns `Some(state)` from its update method, that transition will be
    /// completed and the state machine will continue updating states starting from the nearest
    /// common ancestor of the previous state and the new state after transition.
    ///
    /// # Example
    /// For some machine:
    /// ```text
    /// Top
    /// ├─ Foo
    /// │  └─ Bar
    /// └─ Fizz
    ///    └─ Buzz
    /// ```
    /// If the [`Substate::update`] method of the `Bar` state returns `State::Buzz.into()`,
    /// then:
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub struct Top;
    /// #    impl TopState for Top {}
    /// #
    /// #    struct Foo;
    /// #    impl Substate<Top> for Foo {}
    /// #
    /// #    struct Bar;
    /// #    impl Substate<Foo> for Bar {}
    /// #
    /// #    struct Fizz;
    /// #    impl Substate<Top> for Fizz {}
    /// #
    /// #    struct Buzz;
    /// #    impl Substate<Fizz> for Buzz {}
    /// # }
    /// # use moku::*;
    /// # use example::machine::{Builder, State};
    /// # let mut machine = Builder::new(example::Top).build();
    /// # machine.transition(State::Bar);
    /// assert!(matches!(machine.state(), State::Bar));
    /// machine.update();
    /// ```
    /// Will have the log output of:
    /// ```text
    /// Example: Updating
    /// │Updating Bar
    /// │Transitioning from Bar to Buzz
    /// ││Exiting Bar
    /// ││Exiting Foo
    /// ││Entering Fizz
    /// ││Entering Buzz
    /// │└Transition complete
    /// │Updating Top
    /// └Update complete
    /// ```
    /// `Top` being the nearest common ancestor of the starting state, `Bar`, and the new state,
    /// `Buzz`, so the update continues from `Top`.
    fn update(&mut self);

    /// Top-down update the state machine.
    ///
    /// Starting with the [`TopState`], calls [`Substate::top_down_update`] (or [`TopState::top_down_update`]).
    ///
    /// Useful for propagating changes to state fields before calling [`StateMachine::update`], or for
    /// simply inverting the precedence of transitions (superstates may trigger transitions before
    /// their substates).
    ///
    /// If any state returns `Some(state)` from its update method, that transition will be
    /// completed and the state machine will continue updating states starting from the first
    /// active descendent of the nearest common ancestor of the previous state and the new state
    /// after transition.
    ///
    /// # Example
    /// For some machine:
    /// ```text
    /// Top
    /// ├─ Foo
    /// │  └─ Bar
    /// └─ Fizz
    ///    └─ Buzz
    /// ```
    /// If the [`Substate::top_down_update`] method of the `Foo` state returns `State::Buzz.into()`,
    /// then:
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub struct Top;
    /// #    impl TopState for Top {}
    /// #
    /// #    struct Foo;
    /// #    impl Substate<Top> for Foo {}
    /// #
    /// #    struct Bar;
    /// #    impl Substate<Foo> for Bar {}
    /// #
    /// #    struct Fizz;
    /// #    impl Substate<Top> for Fizz {}
    /// #
    /// #    struct Buzz;
    /// #    impl Substate<Fizz> for Buzz {}
    /// # }
    /// # use moku::*;
    /// # use example::machine::{Builder, State};
    /// # let mut machine = Builder::new(example::Top).build();
    /// # machine.transition(State::Foo);
    /// assert!(matches!(machine.state(), State::Foo));
    /// machine.top_down_update();
    /// ```
    /// Will have the log output of:
    /// ```text
    /// Example: Top-down updating
    /// │Top-down updating Top
    /// │Top-down updating Foo
    /// │Transitioning from Foo to Fizz
    /// ││Exiting Foo
    /// ││Entering Fizz
    /// ││Entering Buzz
    /// │└Transition complete
    /// │Top-down updating Fizz
    /// │Top-down updating Buzz
    /// └Top-down update complete
    /// ```
    /// `Top` being the nearest common ancestor of the starting state, `Foo`, and the new state,
    /// `Fizz`, so the top-down update continues from the first active descendent of `Top`: `Fizz`.
    fn top_down_update(&mut self);

    /// Attempt to transition the [`StateMachine`] to the target state.
    ///
    /// If the target state is already in the currently active state hierarchy, no
    /// transition is made. To force re-entry of an active state, use
    /// [`StateMachine::exact_transition`].
    ///
    /// Subject to interruption by short circuit transitions (from [`Substate::enter`] or [`Substate::exit`])
    /// and initial transitions (from [`Substate::init`] or [`TopState::init`]).
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub struct Top;
    /// #    impl TopState for Top {}
    /// #
    /// #    struct Foo;
    /// #    impl Substate<Top> for Foo {}
    /// #
    /// #    struct Bar;
    /// #    impl Substate<Foo> for Bar {}
    /// # }
    /// # use moku::*;
    /// # use example::machine::{Builder, State};
    /// # let mut machine = Builder::new(example::Top).build();
    /// // where Bar is a substate of Top:
    /// machine.transition(State::Bar);
    /// assert!(matches!(machine.state(), State::Bar));
    ///
    /// machine.transition(State::Top);
    /// assert!(matches!(machine.state(), State::Bar));
    /// ```
    fn transition(&mut self, target: T);

    /// Attempt to transition the [`StateMachine`] to the target state regardless of currently
    /// active states.
    ///
    /// Makes the transition even if the target state is in the current active state hierarchy.
    /// The state will be re-initialized; [`Substate::enter`] and [`Substate::init`] will be called.
    ///
    /// Subject to interruption by short circuit transitions (from [`Substate::enter`] or [`Substate::exit`])
    /// and initial transitions (from [`Substate::init`] or [`TopState::init`]).
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub struct Top;
    /// #    impl TopState for Top {}
    /// #
    /// #    struct Foo;
    /// #    impl Substate<Top> for Foo {}
    /// #
    /// #    struct Bar;
    /// #    impl Substate<Foo> for Bar {}
    /// # }
    /// # use moku::*;
    /// # use example::machine::{Builder, State};
    /// # let mut machine = Builder::new(example::Top).build();
    /// // where Bar is a substate of Top:
    /// machine.transition(State::Bar);
    /// assert!(matches!(machine.state(), State::Bar));
    ///
    /// machine.transition(State::Top);
    /// assert!(matches!(machine.state(), State::Bar));
    ///
    /// machine.exact_transition(State::Top);
    /// assert!(matches!(machine.state(), State::Top));
    /// ```
    fn exact_transition(&mut self, target: T);

    /// Get the current state of the [`StateMachine`].
    ///
    /// Returns the deepest active state.
    ///
    /// # Example
    /// For some machine:
    /// ```text
    /// Top
    /// └─ Foo
    ///    └─ Bar
    /// ```
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub struct Top;
    /// #    impl TopState for Top {}
    /// #
    /// #    struct Foo;
    /// #    impl Substate<Top> for Foo {}
    /// #
    /// #    struct Bar;
    /// #    impl Substate<Foo> for Bar {}
    /// # }
    /// # use moku::*;
    /// # use example::machine::{Builder, State};
    /// # let mut machine = Builder::new(example::Top).build();
    /// machine.transition(State::Bar);
    /// assert!(matches!(machine.state(), State::Bar));
    /// ```
    fn state(&self) -> T;

    /// Check if a given state matches the current state of this [`StateMachine`] or any active
    /// superstate.
    ///
    /// # Example
    /// For some machine:
    /// ```text
    /// Top
    /// ├─ Foo
    /// │  └─ Bar
    /// └─ Fizz
    /// ```
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub struct Top;
    /// #    impl TopState for Top {}
    /// #
    /// #    struct Foo;
    /// #    impl Substate<Top> for Foo {}
    /// #
    /// #    struct Bar;
    /// #    impl Substate<Foo> for Bar {}
    /// #
    /// #    struct Fizz;
    /// #    impl Substate<Top> for Fizz {}
    /// # }
    /// # use moku::{StateMachine, StateMachineBuilder};
    /// # use example::machine::{Builder, State};
    /// # let mut machine = Builder::new(example::Top).build();
    /// machine.transition(State::Bar);
    /// assert!(machine.state_matches(State::Top));
    /// assert!(machine.state_matches(State::Foo));
    /// assert!(machine.state_matches(State::Bar));
    /// assert!(!machine.state_matches(State::Fizz));
    /// ```
    fn state_matches(&self, state: T) -> bool;

    /// Get a reference to the top state.
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// // ...
    ///     pub struct Top {
    ///        pub foo: u8,
    ///     }
    ///
    ///     impl TopState for Top {}
    /// // ...
    /// # }
    /// # use moku::*;
    /// # use example::machine::Builder;
    /// # let machine = Builder::new(example::Top { foo: 8 }).build();
    ///
    /// dbg!(machine.top_ref().foo);
    /// ```
    fn top_ref(&self) -> &V;

    /// Get a mutable reference to the top state.
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// // ...
    ///     pub struct Top {
    ///        pub foo: u8,
    ///     }
    ///
    ///     impl TopState for Top {}
    /// // ...
    /// # }
    /// # use moku::*;
    /// # use example::machine::Builder;
    /// # let mut machine = Builder::new(example::Top { foo: 8 }).build();
    ///
    /// machine.top_mut().foo = 8;
    /// ```
    fn top_mut(&mut self) -> &mut V;

    /// Get the name of this state machine.
    ///
    /// This name is used in moku log messages.
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub struct Top;
    /// #
    /// #    impl TopState for Top {}
    /// # }
    /// # use moku::*;
    /// # use example::machine::Builder;
    /// # let machine = Builder::new(example::Top).build();
    /// assert_eq!(machine.name(), "Example");
    /// ```
    fn name(&self) -> &str;

    /// Set the name of this state machine.
    ///
    /// This name is used in moku log messages.
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub struct Top;
    /// #
    /// #    impl TopState for Top {}
    /// # }
    /// # use moku::*;
    /// # use example::machine::Builder;
    /// # let mut machine = Builder::new(example::Top).build();
    /// machine.set_name("Kikai".to_owned());
    /// assert_eq!(machine.name(), "Kikai");
    /// ```
    #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
    #[cfg(feature = "std")]
    fn set_name(&mut self, name: String);

    /// Handle an event.
    ///
    /// Starting with the deepest state, calls [`Substate::handle_event`] (or [`TopState::handle_event`])
    /// for each active state.
    ///
    /// If a state returns [`Response::Next`] with [`Next::None`], event handling will continue with its superstate.
    ///
    /// If any state returns [`Response::Next`] with something other than [`Next::None`],
    /// the given transition will be completed and no further `handle_event` functions are called.
    ///
    /// If any state returns [`Response::Drop`], event handling stops immediately and no further
    /// `handle_event` functions are called.
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// // ...
    ///     pub enum Event { A }
    ///     impl StateMachineEvent for Event {}
    ///
    ///     pub struct Top;
    ///     impl TopState for Top {}
    /// // ...
    /// # }
    /// # use moku::*;
    /// # use example::machine::Builder;
    /// # let mut machine = Builder::new(example::Top).build();
    /// machine.handle_event(&example::Event::A);
    /// ```
    fn handle_event(&mut self, event: &U);

    /// Get a list of currently active states, starting from the [TopState].
    ///
    /// # Example
    /// For some machine:
    /// ```text
    /// Top
    /// ├─ Foo
    /// │  └─ Bar
    /// └─ Fizz
    ///    └─ Buzz
    /// ```
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub struct Top;
    /// #    impl TopState for Top {}
    /// #
    /// #    struct Foo;
    /// #    impl Substate<Top> for Foo {}
    /// #
    /// #    struct Bar;
    /// #    impl Substate<Foo> for Bar {}
    /// #
    /// #    struct Fizz;
    /// #    impl Substate<Top> for Fizz {}
    /// #
    /// #    struct Buzz;
    /// #    impl Substate<Fizz> for Buzz {}
    /// # }
    /// # use moku::*;
    /// # use example::machine::{Builder, State};
    /// # let mut machine = Builder::new(example::Top).build();
    /// # machine.transition(State::Bar);
    /// assert!(matches!(machine.state(), State::Bar));
    /// assert_eq!(
    ///     machine.state_list(),
    ///     vec![State::Top, State::Foo, State::Bar]
    /// );
    /// ```
    #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
    #[cfg(feature = "std")]
    fn state_list(&self) -> Vec<T>;
}

/// Trait for getting references to active states.
///
/// Will be implemented by a [`StateMachine`] for every one of its states.
pub trait StateRef<T, U, V>
where
    T: StateEnum,
    U: StateMachineEvent,
{
    /// Get a reference to the state, if currently active.
    ///
    /// Returns `None` if the state machine is not currently in the state.
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub struct Top;
    /// #
    /// #    impl TopState for Top {}
    /// #
    /// // ...
    ///     pub struct Foo;
    ///
    ///     impl Substate<Top> for Foo {}
    /// // ...
    /// # }
    /// # use moku::*;
    /// # use example::machine::Builder;
    /// # let machine = Builder::new(example::Top).build();
    ///
    /// let foo: Option<&example::Foo> = machine.state_ref();
    /// ```
    fn state_ref(&self) -> Option<&V>;

    /// Get a mutable reference to the state.
    ///
    /// Returns `None` if the state machine is not currently in the state.
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub struct Top;
    /// #
    /// #    impl TopState for Top {}
    /// #
    /// // ...
    ///     pub struct Foo;
    ///
    ///     impl Substate<Top> for Foo {}
    /// // ...
    /// # }
    /// # use moku::*;
    /// # use example::machine::Builder;
    /// # let mut machine = Builder::new(example::Top).build();
    ///
    /// let foo: Option<&mut example::Foo> = machine.state_mut();
    /// ```
    fn state_mut(&mut self) -> Option<&mut V>;
}

/// Builder for a [`StateMachine`].
pub trait StateMachineBuilder<T, U, V, W>
where
    T: StateEnum,
    U: StateMachineEvent,
    V: TopState,
    W: StateMachine<T, U, V>,
{
    /// Make a new [`StateMachineBuilder`] from a [`TopState`].
    ///
    /// # Example
    /// ```
    /// #[moku::state_machine]
    /// mod example {
    ///     #[moku::machine_module]
    ///     pub mod machine {}
    ///
    ///     use machine::State;
    ///
    ///     pub struct Top;
    ///
    ///     impl moku::TopState for Top {}
    /// }
    ///
    /// use moku::StateMachineBuilder;
    /// use example::machine::Builder;
    ///
    /// let builder = Builder::new(example::Top);
    /// let machine = builder.build();
    /// ```
    fn new(top_state: V) -> Self;

    /// Set the name of the [`StateMachine`].
    ///
    /// If not set, defaults to the [`state_machine`] module's name in `UpperCamel` case.
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub struct Top;
    /// #
    /// #    impl TopState for Top {}
    /// # }
    /// #
    /// # use moku::*;
    /// # use example::machine::Builder;
    /// let machine = Builder::new(example::Top).name("Kikai".to_owned()).build();
    /// assert_eq!(machine.name(), "Kikai");
    /// ```
    #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
    #[cfg(feature = "std")]
    fn name(self, name: String) -> Self;

    /// Build the [`StateMachine`].
    ///
    /// # Example
    /// ```
    /// #[moku::state_machine]
    /// mod example {
    ///     #[moku::machine_module]
    ///     pub mod machine {}
    ///
    ///     use machine::State;
    ///
    ///     pub struct Top;
    ///
    ///     impl moku::TopState for Top {}
    /// }
    ///
    /// use moku::StateMachineBuilder;
    /// use example::machine::Builder;
    ///
    /// let builder = Builder::new(example::Top);
    /// let machine = builder.build();
    /// ```
    fn build(self) -> W;
}

/// Return type of [`Substate::enter`].
///
/// Represents either a successful state entry or a short circuit transition.
pub enum Entry<T: StateEnum, U> {
    /// State entry was successful, here is the newly constructed state.
    State(U),

    /// A transition should be taken to the target state.
    /// See [`StateMachine::transition`] for transition semantics.
    Target(T),

    /// A transition should be taken to exactly the target state.
    /// See [`StateMachine::exact_transition`] for exact transition semantics.
    ExactTarget(T),
}

impl<T: StateEnum, U> From<U> for Entry<T, U> {
    fn from(value: U) -> Self {
        Entry::State(value)
    }
}

/// A substate of a [`StateMachine`].
///
/// Implement this trait for each non-top state in a [`state_machine`] module.
/// The generic parameter specifies the superstate (parent state).
///
/// ## Example
/// ```
/// #[moku::state_machine]
/// mod example {
///     #[moku::machine_module]
///     mod machine {}
///
///     use machine::State;
///
///     struct Top;
///     impl moku::TopState for Top {}
///
///     struct Foo;
///     impl moku::Substate<Top> for Foo {}
///
///     struct Bar;
///     impl moku::Substate<Foo> for Bar {}
/// }
/// ```
pub trait Substate<Parent>: Sized {
    /// The state enum type. Auto-filled by the [`state_machine`] macro.
    type State: StateEnum;

    /// The event type. Auto-filled by the [`state_machine`] macro.
    type Event: StateMachineEvent;

    /// Context providing mutable access to all active superstates.
    /// Auto-filled by the [`state_machine`] macro.
    type Context<'a>;

    /// Called when a [`StateMachine`] enters this state.
    ///
    /// Serves as a constructor for the state. If the state type is defined within the
    /// [`state_machine`] module and has no fields, this method will be autogenerated.
    ///
    /// This method is only called when the state becomes active, and is not called upon re-entrant
    /// transitions (if this state is already active).
    ///
    /// Returning a value of `Entry::Target(T)` will result in a "short circuit"
    /// transition that will be completed by the [`StateMachine`].
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub struct Top;
    /// #
    /// #    impl TopState for Top {}
    /// #
    /// // ...
    ///     pub struct Foo {
    ///         bar: u8,
    ///     }
    ///
    ///     impl Substate<Top> for Foo {
    ///         fn enter(
    ///             ctx: &mut Self::Context<'_>,
    ///         ) -> impl Into<Entry<Self::State, Self>> {
    ///             Self { bar: 8 }
    ///         }
    ///     }
    /// // ...
    /// # }
    fn enter(_ctx: &mut Self::Context<'_>) -> impl Into<Entry<Self::State, Self>>;

    /// Called when a [`StateMachine`] transitions directly to this state.
    ///
    /// This method can return a target state representing the initial transition to take upon
    /// entry of this state. It is called only when the state machine transitions directly to this
    /// state, meaning that it will not be called when transitioning with a target state that is a
    /// substate of this state.
    ///
    /// This method is called upon re-entrant transitions (if this state is already active).
    ///
    /// Returning a value of `Next::None` results in the [`StateMachine`] remaining in this state after
    /// transition.
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub struct Top;
    /// #
    /// #    impl TopState for Top {}
    /// #
    /// #    pub struct Foo;
    /// // ...
    ///     impl Substate<Top> for Foo {
    ///         fn init(
    ///             &mut self,
    ///             ctx: &mut Self::Context<'_>,
    ///         ) -> impl Into<Next<Self::State>> {
    ///             State::Bar
    ///         }
    ///     }
    /// // ...
    /// #    pub struct Bar;
    /// #    impl Substate<Foo> for Bar {}
    /// # }
    fn init(&mut self, _ctx: &mut Self::Context<'_>) -> impl Into<Next<Self::State>> {}

    /// Called when [`StateMachine::update`] is called.
    ///
    /// This method may return a target state to transition to as a result of updating.
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub struct Top;
    /// #
    /// #    impl TopState for Top {}
    /// #
    /// #    pub struct Foo;
    /// // ...
    ///     impl Substate<Top> for Foo {
    ///         fn update(
    ///             &mut self,
    ///             ctx: &mut Self::Context<'_>,
    ///         ) -> impl Into<Next<Self::State>> {
    ///             State::Bar
    ///         }
    ///     }
    /// // ...
    /// #    pub struct Bar;
    /// #    impl Substate<Foo> for Bar {}
    /// # }
    fn update(&mut self, _ctx: &mut Self::Context<'_>) -> impl Into<Next<Self::State>> {}

    /// Called when [`StateMachine::top_down_update`] is called.
    ///
    /// This method may return a target state to transition to as a result of updating.
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub struct Top;
    /// #
    /// #    impl TopState for Top {}
    /// #
    /// #    pub struct Foo;
    /// // ...
    ///     impl Substate<Top> for Foo {
    ///         fn top_down_update(
    ///             &mut self,
    ///             ctx: &mut Self::Context<'_>,
    ///         ) -> impl Into<Next<Self::State>> {
    ///             State::Bar
    ///         }
    ///     }
    /// // ...
    /// #    pub struct Bar;
    /// #    impl Substate<Foo> for Bar {}
    /// # }
    fn top_down_update(&mut self, _ctx: &mut Self::Context<'_>) -> impl Into<Next<Self::State>> {}

    /// Called when a [`StateMachine`] exits this state.
    ///
    /// The state is consumed by this call.
    ///
    /// This method may return a target state to "short circuit" transition to as a result of
    /// exiting this state.
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub struct Top;
    /// #
    /// #    impl TopState for Top {}
    /// #
    /// #    pub struct Foo;
    /// // ...
    ///     impl Substate<Top> for Foo {
    ///         fn exit(
    ///             self,
    ///             ctx: &mut Self::Context<'_>,
    ///         ) -> impl Into<Next<Self::State>> {
    ///             State::Bar
    ///         }
    ///     }
    /// // ...
    /// #    pub struct Bar;
    /// #    impl Substate<Foo> for Bar {}
    /// # }
    fn exit(self, _ctx: &mut Self::Context<'_>) -> impl Into<Next<Self::State>> {}

    /// Called when [`StateMachine::handle_event`] is called.
    ///
    /// Return [`Response::Next`] with [`Next::None`] to continue event handling with the superstate.
    ///
    /// Return [`Response::Next`] with something other than [`Next::None`]
    /// to transition to the given state, after which event handling is stopped.
    ///
    /// Return [`Response::Drop`] to immediately stop event handling.
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub enum Event { A, B, C }
    /// #    impl StateMachineEvent for Event {}
    /// #
    /// #    pub struct Top;
    /// #    impl TopState for Top {}
    /// #
    /// #    pub struct Bar;
    /// #    impl Substate<Top> for Bar {}
    /// #
    /// // ...
    ///     pub struct Foo;
    ///
    ///     impl Substate<Top> for Foo {
    ///         fn handle_event(
    ///             &mut self,
    ///             _ctx: &mut Self::Context<'_>,
    ///             event: &Self::Event,
    ///         ) -> impl Into<Response<Self::State>> {
    ///             match event {
    ///                 Event::A => Response::Next(Next::None),
    ///                 Event::B => Response::Drop,
    ///                 Event::C => Response::Next(Next::Target(State::Bar)),
    ///             }
    ///         }
    ///     }
    /// // ...
    /// # }
    /// ```
    #[allow(unused_variables)]
    fn handle_event(
        &mut self,
        _ctx: &mut Self::Context<'_>,
        event: &Self::Event,
    ) -> impl Into<Response<Self::State>> {
    }
}

/// The topmost state of a [`StateMachine`].
///
/// Implement this trait for exactly one state in a [`state_machine`] module.
///
/// ## Example
/// ```
/// #[moku::state_machine]
/// mod example {
///     #[moku::machine_module]
///     mod machine {}
///
///     use machine::State;
///
///     struct Top {
///         counter: u32,
///     }
///
///     impl moku::TopState for Top {
///         fn init(&mut self) -> impl Into<moku::Next<Self::State>> {
///             State::Foo
///         }
///     }
///
///     struct Foo;
///     impl moku::Substate<Top> for Foo {}
/// }
/// ```
pub trait TopState: Sized {
    /// The state enum type. Auto-filled by the [`state_machine`] macro.
    type State: StateEnum;

    /// The event type. Auto-filled by the [`state_machine`] macro.
    type Event: StateMachineEvent;

    /// Called when a [`StateMachine`] initializes (upon calling [`StateMachineBuilder::build`]) and
    /// upon transitions directly to this state.
    ///
    /// This method can return a target state representing the initial transition to take upon
    /// entry of this state.
    ///
    /// Returning a value of `Next::None` results in the [`StateMachine`] remaining in this state after
    /// transition.
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// // ...
    ///     pub struct Top;
    ///
    ///     impl TopState for Top {
    ///         fn init(&mut self) -> impl Into<Next<Self::State>> {
    ///             State::Foo
    ///         }
    ///     }
    /// // ...
    /// #
    /// #    pub struct Foo;
    /// #    impl Substate<Top> for Foo {}
    /// # }
    fn init(&mut self) -> impl Into<Next<Self::State>> {}

    /// Called when [`StateMachine::update`] is called.
    ///
    /// This method may return a target state to transition to as a result of updating.
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// // ...
    ///     pub struct Top;
    ///
    ///     impl TopState for Top {
    ///         fn update(&mut self) -> impl Into<Next<Self::State>> {
    ///             State::Foo
    ///         }
    ///     }
    /// // ...
    /// #
    /// #    pub struct Foo;
    /// #    impl Substate<Top> for Foo {}
    /// # }
    fn update(&mut self) -> impl Into<Next<Self::State>> {}

    /// Called when [`StateMachine::top_down_update`] is called.
    ///
    /// This method may return a target state to transition to as a result of updating.
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// // ...
    ///     pub struct Top;
    ///
    ///     impl TopState for Top {
    ///         fn top_down_update(&mut self) -> impl Into<Next<Self::State>> {
    ///             State::Foo
    ///         }
    ///     }
    /// // ...
    /// #
    /// #    pub struct Foo;
    /// #    impl Substate<Top> for Foo {}
    /// # }
    fn top_down_update(&mut self) -> impl Into<Next<Self::State>> {}

    /// Called when [`StateMachine::handle_event`] is called.
    ///
    /// This is the final state called during event handling.
    ///
    /// Return [`Next::None`] to make no transition.
    ///
    /// # Example
    /// ```
    /// # #[moku::state_machine]
    /// # mod example {
    /// #    use moku::*;
    /// #
    /// #    #[machine_module]
    /// #    pub mod machine {}
    /// #    use machine::State;
    /// #
    /// #    pub enum Event { A, B, C }
    /// #    impl StateMachineEvent for Event {}
    /// #
    /// // ...
    ///     pub struct Top;
    ///     impl TopState for Top {
    ///         fn handle_event(&mut self, event: &Self::Event) -> impl Into<Next<Self::State>> {
    ///             match event {
    ///                 Event::A => Next::Target(State::Foo),
    ///                 _ => Next::None,
    ///             }
    ///         }
    ///     }
    /// // ...
    /// #
    /// #    pub struct Foo;
    /// #    impl Substate<Top> for Foo {}
    /// # }
    /// ```
    #[allow(unused_variables)]
    fn handle_event(&mut self, event: &Self::Event) -> impl Into<Next<Self::State>> {}
}

/// Types and traits for autogenerated state machine code.
///
/// The contents of this module are intended to be used only by the code that is generated by moku.
pub mod internal {
    use core::marker::PhantomData;

    use log::info;

    use super::*;

    /// Internal state trait used by the generated code.
    ///
    /// This trait unifies [`TopState`] and [`Substate`] for use with [`Node`].
    /// Users should implement [`TopState`] or [`Substate`] instead.
    pub trait StateLike<T, U = ()>: Sized
    where
        T: StateEnum,
        U: StateMachineEvent,
    {
        /// Type containing parent context.
        type Context<'a>;

        /// Called when entering this state.
        fn enter(ctx: &mut Self::Context<'_>) -> Entry<T, Self>;

        /// Called after entering or on direct transition.
        fn init(&mut self, ctx: &mut Self::Context<'_>) -> impl Into<Next<T>>;

        /// Called during update.
        fn update(&mut self, ctx: &mut Self::Context<'_>) -> impl Into<Next<T>>;

        /// Called during top-down update.
        fn top_down_update(&mut self, ctx: &mut Self::Context<'_>) -> impl Into<Next<T>>;

        /// Called when exiting this state.
        fn exit(self, ctx: &mut Self::Context<'_>) -> impl Into<Next<T>>;

        /// Called to handle an event.
        fn handle_event(
            &mut self,
            ctx: &mut Self::Context<'_>,
            event: &U,
        ) -> impl Into<Response<T>>;
    }

    /// Type containing parent context of a [`TopState`], i.e. nothing.
    ///
    /// Not intended for use by users.
    pub struct TopContext<'a>(PhantomData<&'a ()>);

    /// Blanket implementation of StateLike for TopState.
    impl<T, U, V> StateLike<T, U> for V
    where
        T: StateEnum,
        U: StateMachineEvent,
        V: TopState<State = T, Event = U>,
    {
        type Context<'a> = TopContext<'a>;

        fn enter(_ctx: &mut Self::Context<'_>) -> Entry<T, Self> {
            unreachable!("TopState::enter should never be called")
        }

        fn init(&mut self, _ctx: &mut Self::Context<'_>) -> impl Into<Next<T>> {
            TopState::init(self)
        }

        fn update(&mut self, _ctx: &mut Self::Context<'_>) -> impl Into<Next<T>> {
            TopState::update(self)
        }

        fn top_down_update(&mut self, _ctx: &mut Self::Context<'_>) -> impl Into<Next<T>> {
            TopState::top_down_update(self)
        }

        fn exit(self, _ctx: &mut Self::Context<'_>) -> impl Into<Next<T>> {
            unreachable!("TopState::exit should never be called");

            #[allow(unreachable_code)]
            Next::None
        }

        fn handle_event(
            &mut self,
            _ctx: &mut Self::Context<'_>,
            event: &U,
        ) -> impl Into<Response<T>> {
            Response::Next(TopState::handle_event(self, event).into())
        }
    }

    /// The result of the attempted transition on a branch of the state tree.
    pub enum TransitionResult<T: StateEnum> {
        /// The target state does not exist in the branch and the machine must move up the tree
        /// towards the root to find it.
        MoveUp,

        /// Either the target state has been reached and the transition is done, or a short circuit
        /// transition occurred during the transition, and a new target should replace the previous
        /// target state. [`Next::None`] represents a completed transition.
        Next(Next<T>),
    }

    /// The substate of a state.
    ///
    /// Also aggregates some functionality that would be attributed to the state.
    pub trait SubstateEnum<T, U, V>
    where
        T: StateEnum,
        U: StateMachineEvent,
        V: StateLike<T, U>,
    {
        /// The variant that represents no substate, i.e. being in exactly this state.
        fn none_variant() -> Self;

        /// The [`StateEnum`] variant that this [`SubstateEnum`] represents.
        fn this_state() -> T;

        /// Does this state match exactly a given [`StateEnum`] variant?
        fn is_state(state: T) -> bool;

        /// The current leaf state of this branch.
        fn current_state(&self) -> T {
            Self::this_state()
        }

        /// Is this state an ancestor of the given state?
        #[allow(unused_variables)]
        fn is_ancestor(state: T) -> bool {
            false
        }

        /// Update this state and its active descendents.
        #[allow(unused_variables)]
        fn update(&mut self, state: &mut V, ctx: &mut V::Context<'_>) -> Next<T> {
            Next::None
        }

        /// Update this state and its active descendents if in need of update after a transition.
        #[allow(unused_variables)]
        fn update_in_need(&mut self, state: &mut V, ctx: &mut V::Context<'_>) -> Next<T> {
            Next::None
        }

        /// Top-down update this state and its active descendents.
        #[allow(unused_variables)]
        fn top_down_update(&mut self, state: &mut V, ctx: &mut V::Context<'_>) -> Next<T> {
            Next::None
        }

        /// Top-down update this state and its active descendents if in need of update after a
        /// transition.
        #[allow(unused_variables)]
        fn top_down_update_in_need(&mut self, state: &mut V, ctx: &mut V::Context<'_>) -> Next<T> {
            Next::None
        }

        /// Clear the top-down update flag from the nodes of this state's active descendents.
        fn clear_top_down_updated(&mut self) {}

        /// Exit this state and its active descendents.
        #[allow(unused_variables)]
        fn exit(&mut self, state: &mut V, ctx: &mut V::Context<'_>, indent: bool) -> Next<T> {
            Next::None
        }

        /// Transition this state and its active descendents.
        #[allow(unused_variables)]
        fn transition(
            &mut self,
            target: T,
            state: &mut V,
            ctx: &mut V::Context<'_>,
            indent: bool,
            exact: bool,
        ) -> TransitionResult<T> {
            TransitionResult::MoveUp
        }

        /// Enter the substate that moves towards a target state.
        ///
        /// Panics if called when the target state is not a descendent of this state.
        #[allow(unused_variables)]
        fn enter_substate_towards(
            &mut self,
            target: T,
            state: &mut V,
            ctx: &mut V::Context<'_>,
            indent: bool,
        ) -> Next<T> {
            unreachable!()
        }

        /// Does this state or any active descendents match a given state?
        fn state_matches(&self, state: T) -> bool {
            Self::is_state(state)
        }

        /// Handle an event.
        #[allow(unused_variables)]
        fn handle_event(
            &mut self,
            event: &U,
            state: &mut V,
            ctx: &mut V::Context<'_>,
        ) -> Response<T> {
            Response::Next(Next::None)
        }

        /// Build a list of the currently active states.
        #[cfg(feature = "std")]
        fn state_list(&self, list: Vec<T>) -> Vec<T>;
    }

    /// The result of trying to enter a [`Node`].
    pub enum NodeEntry<T, U, V, W>
    where
        T: StateEnum,
        U: StateMachineEvent,
        V: StateLike<T, U>,
        W: SubstateEnum<T, U, V>,
    {
        /// Entry was successful, here is the new [`Node`].
        Node(Node<T, U, V, W>),

        /// Entry resulted in a short circuit transition.
        Target(T),

        /// Entry resulted in a short circuit exact transition.
        ExactTarget(T),
    }

    impl<T, U, V, W> From<Entry<T, V>> for NodeEntry<T, U, V, W>
    where
        T: StateEnum,
        U: StateMachineEvent,
        V: StateLike<T, U>,
        W: SubstateEnum<T, U, V>,
    {
        fn from(entry: Entry<T, V>) -> Self {
            match entry {
                Entry::State(state) => NodeEntry::Node(Node::from_state(state)),
                Entry::Target(target) => NodeEntry::Target(target),
                Entry::ExactTarget(target) => NodeEntry::ExactTarget(target),
            }
        }
    }

    bitflags::bitflags! {
        #[derive(Debug, Clone, Copy, Default)]
        struct NodeFlags: u8 {
            const NEEDS_UPDATE = 1;
            const TOP_DOWN_UPDATED = 2;
        }
    }

    /// A node in the state tree.
    pub struct Node<T, U, V, W>
    where
        T: StateEnum,
        U: StateMachineEvent,
        V: StateLike<T, U>,
        W: SubstateEnum<T, U, V>,
    {
        phantom_t: PhantomData<T>,
        phantom_u: PhantomData<U>,

        #[allow(missing_docs)]
        pub state: V,

        #[allow(missing_docs)]
        pub substate: W,

        flags: NodeFlags,
    }

    impl<T, U, V, W> Node<T, U, V, W>
    where
        T: StateEnum,
        U: StateMachineEvent,
        V: StateLike<T, U>,
        W: SubstateEnum<T, U, V>,
    {
        /// Make a new [`Node`] from a state.
        pub fn from_state(state: V) -> Self {
            Self {
                phantom_t: PhantomData,
                phantom_u: PhantomData,
                state,
                substate: W::none_variant(),
                flags: NodeFlags::empty(),
            }
        }

        /// Check if this node needs an update.
        pub fn needs_update(&self) -> bool {
            self.flags.contains(NodeFlags::NEEDS_UPDATE)
        }

        /// Enter this node.
        pub fn enter(ctx: &mut V::Context<'_>, indent: bool) -> NodeEntry<T, U, V, W> {
            info!(
                "{}\u{02502}Entering {:?}",
                if indent { "\u{02502}" } else { "" },
                W::this_state()
            );
            match V::enter(ctx) {
                Entry::State(state) => NodeEntry::Node(Self {
                    phantom_t: PhantomData,
                    phantom_u: PhantomData,
                    state,
                    substate: W::none_variant(),
                    flags: NodeFlags::empty(),
                }),
                Entry::Target(target) => {
                    info!(
                        "{}\u{02502}Short circuit transition to {target:?}",
                        if indent { "\u{02502}" } else { "" },
                    );
                    NodeEntry::Target(target)
                }
                Entry::ExactTarget(target) => {
                    info!(
                        "{}\u{02502}Short circuit exact transition to {target:?}",
                        if indent { "\u{02502}" } else { "" },
                    );
                    NodeEntry::ExactTarget(target)
                }
            }
        }

        /// Update this node and its active descendents.
        pub fn update(&mut self, ctx: &mut V::Context<'_>) -> Next<T> {
            self.flags.insert(NodeFlags::NEEDS_UPDATE);
            match self.substate.update(&mut self.state, ctx) {
                Next::None => {
                    info!("\u{02502}Updating {:?}", W::this_state());
                    self.flags.remove(NodeFlags::NEEDS_UPDATE);
                    self.state.update(ctx).into()
                }
                target => target,
            }
        }

        /// Update this node and its active descendents if in need of update after a transition.
        pub fn update_in_need(&mut self, ctx: &mut V::Context<'_>) -> Next<T> {
            if self.flags.contains(NodeFlags::NEEDS_UPDATE) {
                match self.substate.update_in_need(&mut self.state, ctx) {
                    Next::None => {
                        info!("\u{02502}Updating {:?}", W::this_state());
                        self.flags.remove(NodeFlags::NEEDS_UPDATE);
                        self.state.update(ctx).into()
                    }
                    target => target,
                }
            } else {
                Next::None
            }
        }

        /// Top-down update this node and its active descendents.
        pub fn top_down_update(&mut self, ctx: &mut V::Context<'_>) -> Next<T> {
            info!("\u{02502}Top-down updating {:?}", W::this_state());
            self.flags.insert(NodeFlags::TOP_DOWN_UPDATED);
            match self.state.top_down_update(ctx).into() {
                Next::None => self.substate.top_down_update(&mut self.state, ctx),
                target => target,
            }
        }

        /// Top-down update this node and its active descendents if in need of update after a
        /// transition.
        pub fn top_down_update_in_need(&mut self, ctx: &mut V::Context<'_>) -> Next<T> {
            if !self.flags.contains(NodeFlags::TOP_DOWN_UPDATED) {
                info!("\u{02502}Top-down updating {:?}", W::this_state());
                self.flags.insert(NodeFlags::TOP_DOWN_UPDATED);
                match self.state.top_down_update(ctx).into() {
                    Next::None => (),
                    target => return target,
                }
            }

            self.substate.top_down_update_in_need(&mut self.state, ctx)
        }

        /// Clear the top-down update flag from this node and its active descendents.
        pub fn clear_top_down_updated(&mut self) {
            self.flags.remove(NodeFlags::TOP_DOWN_UPDATED);
            self.substate.clear_top_down_updated();
        }

        /// Exit this node and its active descendents.
        pub fn exit(self, ctx: &mut V::Context<'_>, indent: bool) -> Next<T> {
            info!(
                "{}\u{02502}Exiting {:?}",
                if indent { "\u{02502}" } else { "" },
                W::this_state()
            );

            let res = self.state.exit(ctx).into();

            match &res {
                Next::None => (),
                Next::Target(target) => info!(
                    "{}\u{02502}Short circuit transition to {target:?}",
                    if indent { "\u{02502}" } else { "" }
                ),
                Next::ExactTarget(target) => info!(
                    "{}\u{02502}Short circuit exact transition to {target:?}",
                    if indent { "\u{02502}" } else { "" }
                ),
            }

            res
        }

        /// Transition this node and its active descendents.
        pub fn transition(
            &mut self,
            target: T,
            ctx: &mut V::Context<'_>,
            indent: bool,
            exact: bool,
        ) -> TransitionResult<T> {
            // try to transition the current substate towards the target state
            match self
                .substate
                .transition(target, &mut self.state, ctx, indent, exact)
            {
                // substate is not the target state or an ancestor of it
                TransitionResult::MoveUp => {
                    // check if substate exit resulted in a short circuit transition
                    match self.substate.exit(&mut self.state, ctx, indent) {
                        Next::None => {
                            if W::is_ancestor(target) {
                                match self.substate.enter_substate_towards(
                                    target,
                                    &mut self.state,
                                    ctx,
                                    indent,
                                ) {
                                    // substate successfully moved towards target state,
                                    // continue transitioning downwards
                                    //
                                    // now that we're moving downwards, we don't need the exact flag;
                                    // setting it false will cause us to stop at the target state
                                    Next::None => self.substate.transition(
                                        target,
                                        &mut self.state,
                                        ctx,
                                        indent,
                                        false,
                                    ),
                                    // substate transition resulted in a short circuit transition
                                    res => TransitionResult::Next(res),
                                }
                            } else if W::is_state(target) {
                                // this state is the target
                                if exact {
                                    // we need to leave and come back
                                    TransitionResult::MoveUp
                                } else {
                                    let res = self.state.init(ctx).into();
                                    match &res {
                                        Next::Target(new_target) => {
                                            info!("\u{02502}Initial transition to {new_target:?}")
                                        }
                                        Next::ExactTarget(new_target) => {
                                            info!(
                                                "\u{02502}Initial exact transition to {new_target:?}"
                                            )
                                        }
                                        Next::None => (),
                                    }
                                    TransitionResult::Next(res)
                                }
                            } else {
                                // this state is not the target state or an ancestor of it
                                TransitionResult::MoveUp
                            }
                        }
                        next => TransitionResult::Next(next),
                    }
                }
                res => res,
            }
        }

        /// Get the current leaf state of this branch.
        pub fn current_state(&self) -> T {
            self.substate.current_state()
        }

        /// Does this node or any active descendents match a given state?
        pub fn state_matches(&self, state: T) -> bool {
            self.substate.state_matches(state)
        }

        /// Handle an event.
        pub fn handle_event(&mut self, ctx: &mut V::Context<'_>, event: &U) -> Response<T> {
            match self.substate.handle_event(event, &mut self.state, ctx) {
                Response::Next(Next::None) => {
                    let res = self.state.handle_event(ctx, event).into();
                    match &res {
                        Response::Drop => {
                            info!("\u{02502}{:?} dropping event", W::this_state())
                        }
                        Response::Next(next) => match next {
                            Next::None => {
                                info!("\u{02502}{:?} deferring event", W::this_state())
                            }
                            Next::Target(target) => info!(
                                "\u{02502}{:?} triggered transition to {:?}",
                                W::this_state(),
                                target
                            ),
                            Next::ExactTarget(target) => info!(
                                "\u{02502}{:?} triggered exact transition to {:?}",
                                W::this_state(),
                                target
                            ),
                        },
                    }
                    res
                }
                substate_res => substate_res,
            }
        }

        /// Build a list of the currently active states.
        #[allow(unused)]
        #[cfg(feature = "std")]
        pub fn state_list(&self, mut list: Vec<T>) -> Vec<T> {
            list.push(W::this_state());
            self.substate.state_list(list)
        }
    }

    /// The root node of a state tree.
    pub struct TopNode<T, U, V, W>
    where
        T: StateEnum,
        U: StateMachineEvent,
        V: TopState<State = T, Event = U>,
        W: SubstateEnum<T, U, V>,
    {
        #[allow(missing_docs)]
        pub node: Node<T, U, V, W>,

        #[cfg(feature = "std")]
        name: String,

        #[cfg(not(feature = "std"))]
        name: &'static str,
    }

    impl<T, U, V, W> TopNode<T, U, V, W>
    where
        T: StateEnum,
        U: StateMachineEvent,
        V: TopState<State = T, Event = U>,
        W: SubstateEnum<T, U, V>,
    {
        /// Make a new [`TopNode`] from a [`TopState`] and a machine name.
        #[cfg(feature = "std")]
        pub fn new(top_state: V, name: String) -> Self {
            Self {
                node: Node::from_state(top_state),
                name,
            }
        }

        /// Make a new [`TopNode`] from a [`TopState`] and a machine name.
        #[cfg(not(feature = "std"))]
        pub fn new(top_state: V, name: &'static str) -> Self {
            Self {
                node: Node::from_state(top_state),
                name,
            }
        }

        /// Perform the initial transition of this node.
        pub fn init(&mut self) {
            match TopState::init(&mut self.node.state).into() {
                Next::Target(target) => {
                    info!("{}: Initial transition to {target:?}", self.name());
                    self.transition_quiet(target, false, false);
                    info!("\u{02514}Transition complete");
                }
                Next::ExactTarget(target) => {
                    info!("{}: Initial exact transition to {target:?}", self.name());
                    self.transition_quiet(target, false, true);
                    info!("\u{02514}Transition complete");
                }
                Next::None => (),
            }
        }

        /// Update this node and its active descendents.
        pub fn update(&mut self) {
            info!("{}: Updating", self.name());

            match self.node.update(&mut TopContext(PhantomData)) {
                Next::None => (),
                next => {
                    match next {
                        Next::None => unreachable!(),
                        Next::Target(target) => self.transition(target, true, false),
                        Next::ExactTarget(target) => self.transition(target, true, true),
                    }

                    while self.node.needs_update() {
                        match self.node.update_in_need(&mut TopContext(PhantomData)) {
                            Next::None => (),
                            Next::Target(target) => self.transition(target, true, false),
                            Next::ExactTarget(target) => self.transition(target, true, true),
                        }
                    }
                }
            }
            info!("\u{02514}Update complete");
        }

        /// Top-down update this node and its active descendents.
        pub fn top_down_update(&mut self) {
            info!("{}: Top-down updating", self.name());

            match self.node.top_down_update(&mut TopContext(PhantomData)) {
                Next::None => (),
                next => {
                    match next {
                        Next::None => unreachable!(),
                        Next::Target(target) => self.transition(target, true, false),
                        Next::ExactTarget(target) => self.transition(target, true, true),
                    }

                    loop {
                        match self
                            .node
                            .top_down_update_in_need(&mut TopContext(PhantomData))
                        {
                            Next::None => break,
                            Next::Target(target) => self.transition(target, true, false),
                            Next::ExactTarget(target) => self.transition(target, true, true),
                        }
                    }
                }
            }
            self.node.clear_top_down_updated();
            info!("\u{02514}Top-down update complete");
        }

        /// Transition this node and its active descendents without logging the start and end of
        /// the transition.
        pub fn transition_quiet(&mut self, target: T, indent: bool, exact: bool) {
            if !exact && self.state_matches(target) {
                return;
            }

            match self
                .node
                .transition(target, &mut TopContext(PhantomData), indent, exact)
            {
                TransitionResult::MoveUp => {
                    assert!(exact);
                    if W::is_state(target) {
                        self.init();
                    } else {
                        self.transition_quiet(target, indent, false);
                    }
                }
                TransitionResult::Next(next) => match next {
                    Next::None => (),
                    Next::Target(new_target) => self.transition_quiet(new_target, indent, false),
                    Next::ExactTarget(new_target) => {
                        self.transition_quiet(new_target, indent, true)
                    }
                },
            }
        }

        /// Transition this node and its active descendents.
        pub fn transition(&mut self, target: T, indent: bool, exact: bool) {
            if indent {
                info!(
                    "\u{02502}Transitioning from {:?} to {target:?}",
                    self.state(),
                );
            } else {
                info!(
                    "{}: Transitioning from {:?} to {target:?}",
                    self.name(),
                    self.state(),
                );
            }

            if !exact && self.state_matches(target) {
                info!(
                    "{}\u{02502}Already in {target:?}",
                    if indent { "\u{02502}" } else { "" },
                );
            } else {
                self.transition_quiet(target, indent, exact);
            }

            info!(
                "{}\u{02514}Transition complete",
                if indent { "\u{02502}" } else { "" },
            );
        }

        /// Get the current leaf state of this state tree.
        pub fn state(&self) -> T {
            self.node.current_state()
        }

        /// Get the name of this machine.
        pub fn name(&self) -> &str {
            #[cfg(feature = "std")]
            return &self.name;

            #[cfg(not(feature = "std"))]
            return self.name;
        }

        /// Set the name of this machine.
        #[cfg(feature = "std")]
        pub fn set_name(&mut self, name: String) {
            self.name = name;
        }

        /// Does this node or any active descendents match a given state?
        pub fn state_matches(&self, state: T) -> bool {
            self.node.state_matches(state)
        }

        /// Handle an event.
        pub fn handle_event(&mut self, event: &U) {
            info!("{}: Handling event", self.name());
            match self.node.handle_event(&mut TopContext(PhantomData), event) {
                Response::Drop => (),
                Response::Next(next) => match next {
                    Next::None => (),
                    Next::Target(target) => self.transition(target, true, false),
                    Next::ExactTarget(target) => self.transition(target, true, true),
                },
            }
            info!("\u{02514}Event handled");
        }
    }
}