feat: expose references to Inner

Problem: Mutable access to `Inner` is required for ergonomic unit
testing.

Solution: Add `inner` and `inner_mut` to:
- `awaitable::state_machine{UninitializedStateMachine,
  InitializedStateMachine}`
- `blocking::state_machine{UninitializedStateMachine,
  InitializedStateMachine}`
Mark the methods as `unsafe` for the case of an
`InitializedStateMachine` to force users to think critically about
mutating in thise case.

Testing: `cargo test`

Issue: mdeloof#34

statig/src/awaitable/state_machine.rs

@@ -124,11 +124,6 @@ where
     {
         self.handle_with_context(&(), context).await;
     }
-
-    /// Get the current state.
-    pub fn state(&self) -> &M::State {
-        &self.inner.state
-    }
 }
 
 impl<M> Clone for StateMachine<M>
@@ -286,6 +281,66 @@ where
     pub fn state(&self) -> &M::State {
         &self.inner.state
     }
+
+    /// Get a reference to the [Inner] storage.
+    ///
+    /// ```
+    /// # use statig::prelude::*;
+    /// # #[derive(Default)]
+    /// # pub struct Blinky {
+    /// #     led: bool,
+    /// # }
+    /// #
+    /// # pub struct Event;
+    /// #
+    /// # #[state_machine(
+    /// #     initial = "State::on()",
+    /// #     state(derive(Debug, PartialEq, Eq))
+    /// # )]
+    /// # impl Blinky {
+    /// #     #[state]
+    /// #     fn on(event: &Event) -> Response<State> { Handled }
+    /// # }
+    /// #
+    /// # let uninitialized_state_machine = Blinky::default().uninitialized_state_machine();
+    /// let initialized_state_machine = uninitialized_state_machine.init();
+    /// assert_eq!(initialized_state_machine.inner().shared_storage.led, false);
+    /// assert_eq!(initialized_state_machine.inner().state, State::on());
+    /// ```
+    pub fn inner(&self) -> &Inner<M> {
+        &self.inner
+    }
+
+    /// Get a mutable reference to the [Inner] storage.
+    /// # Safety
+    ///
+    /// The users is responsible for validating that mutating an
+    /// [InitializedStateMachine] does not break any invariants.
+    ///
+    /// ```
+    /// # use statig::prelude::*;
+    /// # #[derive(Default)]
+    /// # pub struct Blinky {
+    /// #     led: bool,
+    /// # }
+    /// #
+    /// # pub struct Event;
+    /// #
+    /// # #[state_machine(initial = "State::on()")]
+    /// # impl Blinky {
+    /// #     #[state]
+    /// #     fn on(event: &Event) -> Response<State> { Handled }
+    /// # }
+    /// #
+    /// # let mut uninitialized_state_machine = Blinky::default().uninitialized_state_machine();
+    /// let mut initialized_state_machine = uninitialized_state_machine.init();
+    /// unsafe {
+    ///     initialized_state_machine.inner_mut().shared_storage.led = true;
+    /// }
+    /// ```
+    pub unsafe fn inner_mut(&mut self) -> &mut Inner<M> {
+        &mut self.inner
+    }
 }
 
 impl<M> Clone for InitializedStateMachine<M>
@@ -458,6 +513,60 @@ where
         state_machine.inner.async_init_with_context(context).await;
         state_machine
     }
+    /// Get a reference to the [Inner] storage.
+    ///
+    /// ```
+    /// # use statig::prelude::*;
+    /// # #[derive(Default)]
+    /// # pub struct Blinky {
+    /// #     led: bool,
+    /// # }
+    /// #
+    /// # pub struct Event;
+    /// #
+    /// # #[state_machine(
+    /// #     initial = "State::on()",
+    /// #     state(derive(Debug, PartialEq, Eq))
+    /// # )]
+    /// # impl Blinky {
+    /// #     #[state]
+    /// #     fn on(event: &Event) -> Response<State> { Handled }
+    /// # }
+    /// #
+    /// let mut uninitialized_state_machine = Blinky::default().uninitialized_state_machine();
+    ///
+    /// assert_eq!(uninitialized_state_machine.inner().shared_storage.led, false);
+    /// assert_eq!(uninitialized_state_machine.inner().state, State::on());
+    /// ```
+    pub fn inner(&mut self) -> &Inner<M> {
+        &self.inner
+    }
+
+    /// Get a mutable reference to the [Inner] storage.
+    ///
+    /// ```
+    /// # use statig::prelude::*;
+    /// # #[derive(Default)]
+    /// # pub struct Blinky {
+    /// #     led: bool,
+    /// # }
+    /// #
+    /// # pub struct Event;
+    /// #
+    /// # #[state_machine(initial = "State::on()")]
+    /// # impl Blinky {
+    /// #     #[state]
+    /// #     fn on(event: &Event) -> Response<State> { Handled }
+    /// # }
+    /// #
+    /// let mut uninitialized_state_machine = Blinky::default().uninitialized_state_machine();
+    ///
+    /// uninitialized_state_machine.inner_mut().shared_storage.led = true;
+    /// uninitialized_state_machine.inner_mut().state = State::on();
+    /// ```
+    pub fn inner_mut(&mut self) -> &mut Inner<M> {
+        &mut self.inner
+    }
 }
 
 impl<M> Clone for UninitializedStateMachine<M>

statig/src/blocking/state_machine.rs

@@ -265,6 +265,66 @@ where
     pub fn state(&self) -> &M::State {
         &self.inner.state
     }
+
+    /// Get a reference to the [Inner] storage.
+    ///
+    /// ```
+    /// # use statig::prelude::*;
+    /// # #[derive(Default)]
+    /// # pub struct Blinky {
+    /// #     led: bool,
+    /// # }
+    /// #
+    /// # pub struct Event;
+    /// #
+    /// # #[state_machine(
+    /// #     initial = "State::on()",
+    /// #     state(derive(Debug, PartialEq, Eq))
+    /// # )]
+    /// # impl Blinky {
+    /// #     #[state]
+    /// #     fn on(event: &Event) -> Response<State> { Handled }
+    /// # }
+    /// #
+    /// # let uninitialized_state_machine = Blinky::default().uninitialized_state_machine();
+    /// let initialized_state_machine = uninitialized_state_machine.init();
+    /// assert_eq!(initialized_state_machine.inner().shared_storage.led, false);
+    /// assert_eq!(initialized_state_machine.inner().state, State::on());
+    /// ```
+    pub fn inner(&self) -> &Inner<M> {
+        &self.inner
+    }
+
+    /// Get a mutable reference to the [Inner] storage.
+    /// # Safety
+    ///
+    /// The users is responsible for validating that mutating an
+    /// [InitializedStateMachine] does not break any invariants.
+    ///
+    /// ```
+    /// # use statig::prelude::*;
+    /// # #[derive(Default)]
+    /// # pub struct Blinky {
+    /// #     led: bool,
+    /// # }
+    /// #
+    /// # pub struct Event;
+    /// #
+    /// # #[state_machine(initial = "State::on()")]
+    /// # impl Blinky {
+    /// #     #[state]
+    /// #     fn on(event: &Event) -> Response<State> { Handled }
+    /// # }
+    /// #
+    /// # let uninitialized_state_machine = Blinky::default().uninitialized_state_machine();
+    /// let mut initialized_state_machine = uninitialized_state_machine.init();
+    /// unsafe {
+    ///     initialized_state_machine.inner_mut().shared_storage.led = true;
+    /// }
+    /// ```
+    pub unsafe fn inner_mut(&mut self) -> &mut Inner<M> {
+        &mut self.inner
+    }
 }
 
 impl<M> Clone for InitializedStateMachine<M>
@@ -434,6 +494,61 @@ where
         state_machine.inner.init_with_context(context);
         state_machine
     }
+
+    /// Get a reference to the [Inner] storage.
+    ///
+    /// ```
+    /// # use statig::prelude::*;
+    /// # #[derive(Default)]
+    /// # pub struct Blinky {
+    /// #     led: bool,
+    /// # }
+    /// #
+    /// # pub struct Event;
+    /// #
+    /// # #[state_machine(
+    /// #     initial = "State::on()",
+    /// #     state(derive(Debug, PartialEq, Eq))
+    /// # )]
+    /// # impl Blinky {
+    /// #     #[state]
+    /// #     fn on(event: &Event) -> Response<State> { Handled }
+    /// # }
+    /// #
+    /// let mut uninitialized_state_machine = Blinky::default().uninitialized_state_machine();
+    ///
+    /// assert_eq!(uninitialized_state_machine.inner().shared_storage.led, false);
+    /// assert_eq!(uninitialized_state_machine.inner().state, State::on());
+    /// ```
+    pub fn inner(&mut self) -> &Inner<M> {
+        &self.inner
+    }
+
+    /// Get a mutable reference to the [Inner] storage.
+    ///
+    /// ```
+    /// # use statig::prelude::*;
+    /// # #[derive(Default)]
+    /// # pub struct Blinky {
+    /// #     led: bool,
+    /// # }
+    /// #
+    /// # pub struct Event;
+    /// #
+    /// # #[state_machine(initial = "State::on()")]
+    /// # impl Blinky {
+    /// #     #[state]
+    /// #     fn on(event: &Event) -> Response<State> { Handled }
+    /// # }
+    /// #
+    /// let mut uninitialized_state_machine = Blinky::default().uninitialized_state_machine();
+    ///
+    /// uninitialized_state_machine.inner_mut().shared_storage.led = true;
+    /// uninitialized_state_machine.inner_mut().state = State::on();
+    /// ```
+    pub fn inner_mut(&mut self) -> &mut Inner<M> {
+        &mut self.inner
+    }
 }
 
 impl<M> Clone for UninitializedStateMachine<M>

statig/src/inner.rs

@@ -4,7 +4,7 @@ use crate::blocking::{self, StateExt as _};
 use crate::{IntoStateMachine, Response};
 
 /// Private internal representation of a state machine that is used for the public types.
-pub(crate) struct Inner<M>
+pub struct Inner<M>
 where
     M: IntoStateMachine,
 {

statig/src/lib.rs

@@ -671,7 +671,7 @@
 //! I highly recommend it if you want to learn how to use state machines to design
 //! complex systems.
 
-#![cfg_attr(not(feature = "std"), no_std)]
+#![cfg_attr(all(not(feature = "std"), not(doc)), no_std)]
 #![allow(incomplete_features)]
 
 mod inner;
@@ -815,7 +815,7 @@ pub use statig_macro::action;
 
 /// Prelude containing the necessary imports for use with macro.
 pub mod prelude {
-    #[cfg(feature = "async")]
+    #[cfg(any(feature = "async", doc))]
     pub use crate::awaitable::{IntoStateMachineExt as _, StateExt as _, *};
     pub use crate::blocking::{IntoStateMachineExt as _, StateExt as _, *};
     pub use crate::Response::{self, *};
@@ -826,7 +826,7 @@ pub mod prelude {
 
 pub mod blocking;
 
-#[cfg(feature = "async")]
+#[cfg(any(feature = "async", doc))]
 pub mod awaitable;
 
 pub(crate) use inner::*;