Finny 0.1.0 (#6)

Reworked the library for Rust 2018 with a function builder API. Missing features:
 * Submachines
 * "Any" events
 * Docs & visualization
 * Inspection
 * Deferred events, shallow history for states

Author: rudib

.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: Build
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Build
+      run: cargo build --verbose
+    - name: Run tests
+      run: cargo test --verbose
+    - name: Run no_std test
+      run: cd finny_nostd_tests && cargo build && cargo run

.travis.yml

@@ -1,14 +1,10 @@
-[package]
-name = "fsm"
-version = "0.1.0"
-authors = ["Rudi Benkovic <rudi.benkovic@gmail.com>"]
+[workspace]
+members = [
+    "finny/",
+    "finny_derive/",
+    "finny_tests/"
+]
 
-[dependencies]
-serde = { version = "1.0" }
-serde_derive = { version = "1.0", optional = true }
-
-[features]
-default = ["std", "info_serializable"]
-std = []
-core_collections = []
-info_serializable = ["serde_derive"]
+exclude = [
+    "finny_nostd_tests/"
+]

Cargo.toml

@@ -1,90 +1,64 @@
-# Hierarchical state machines for Rust
+# Finny - Finite State Machines for Rust
 
-Inspired by Boost MSM. Generates the transition tables using procedural macros. Requires at least Rust 1.16.
-
-Consider this a preview, undocumented, alpha-level release.
-
-[![Build Status](https://travis-ci.org/hashmismatch/fsm.rs.svg?branch=master)](https://travis-ci.org/hashmismatch/fsm.rs)
+![Build](https://github.com/hashmismatch/finny.rs/workflows/Build/badge.svg)
 
 ## Features
-
-- Static states
-- Submachines with optional state preserving events
-- Orthogonal regions
-- Interrupt states
-- State guards
-- Queued events
-- Enum generation for event and state types
-- Internal state transitions that don't trigger the entry and exit events
-- Helpers for multiple entry states	
-- Graphviz visualisation, the codegen generates a test that saves the graph file to the filesystem
-- Inspection trait for custom debugging	
+* Declarative, builder API with a procedural function macro that generate the dispatcher
+* Compile-time transition graph validation
+* No run-time allocations required, `no_std` support
+* Support for generics within the shared context
+* Transition guards and actions
+* FSM regions, also known as orthogonal states
+* Event queueing and run-to-completition execution
 
 ## Example
 
 ```rust
-extern crate fsm;
-#[macro_use]
-extern crate fsm_codegen;
-
-use fsm::*;
-
-#[derive(Clone, PartialEq, Default, Debug)]
-pub struct Event1 { v: usize }
-impl FsmEvent for Event1 {}
-
-#[derive(Clone, PartialEq, Default, Debug)]
-pub struct EventGo;
-impl FsmEvent for EventGo {}
-
-#[derive(Clone, PartialEq, Default, Debug)]
-pub struct EventRestart;
-impl FsmEvent for EventRestart {}
-
-#[derive(Clone, PartialEq, Default, Debug)]
-pub struct EventStart;
-impl FsmEvent for EventStart {}
-
-#[derive(Clone, PartialEq, Default, Debug)]
-pub struct EventStop;
-impl FsmEvent for EventStop {}
-
-#[derive(Clone, PartialEq, Default)]
-pub struct StateA { a: usize }
-impl FsmState<FsmMinTwo> for StateA { }
-
-#[derive(Clone, PartialEq, Default)]
-pub struct StateB { b: usize }
-impl FsmState<FsmMinTwo> for StateB { }
-
-#[derive(Clone, PartialEq, Default)]
-pub struct StateC { c: usize }
-impl FsmState<FsmMinTwo> for StateC { }
-
-#[derive(Fsm)]
-struct FsmMinTwoDefinition(
-	InitialState<FsmMinTwo, StateA>,
-
-    Transition         < FsmMinTwo,  StateA,        EventStart,        StateB,    NoAction >,
-    Transition         < FsmMinTwo,  StateB,        EventStop,         StateA,    NoAction >,
-    Transition         < FsmMinTwo,  StateB,        EventGo,           StateC,    NoAction >,
-
-    Transition         < FsmMinTwo, (StateA, StateB, StateC),
-                                                    EventRestart,      StateA,    NoAction >,
-
-    TransitionInternal < FsmMinTwo,  StateA,        Event1,                       NoAction >,
-
-    InterruptState     < FsmMinTwo,  StateB,        EventStop >
-);
-
-#[cfg(test)]
-#[test]
-fn test_fsm_min2() {
-    let mut fsm = FsmMinTwo::new(());
-    fsm.start();
-    assert_eq!(FsmMinTwoStates::StateA, fsm.get_current_state());
+extern crate finny;
+use finny::{finny_fsm, FsmFactory, FsmResult, decl::{BuiltFsm, FsmBuilder}};
+
+// The context is shared between all guards, actions and transitions. Generics are supported here!
+#[derive(Default)]
+pub struct MyContext { val: u32 }
+// The states are plain structs.
+#[derive(Default)]
+pub struct MyStateA { n: usize }
+#[derive(Default)]
+pub struct MyStateB;
+// The events are also plain structs. They can have fields.
+#[derive(Clone)]
+pub struct MyEvent;
+
+// The FSM is generated by a procedural macro
+#[finny_fsm]
+fn my_fsm(mut fsm: FsmBuilder<MyFsm, MyContext>) -> BuiltFsm {
+    // The FSM is described using a builder-style API
+    fsm.state::<MyStateA>()
+       .on_entry(|state, ctx| {
+           state.n += 1;
+           ctx.context.val += 1;
+        })
+       .on_event::<MyEvent>()
+       .transition_to::<MyStateB>()
+       .guard(|_ev, ctx| { ctx.context.val > 0 })
+       .action(|_ev, ctx, state_a, state_b| { ctx.context.val += 1; });
+    fsm.state::<MyStateB>();
+    fsm.initial_state::<MyStateA>();
+    fsm.build()
+}
 
-    fsm.process_event(FsmMinTwoEvents::EventStart(EventStart)).unwrap();
-    assert_eq!(FsmMinTwoStates::StateB, fsm.get_current_state());    
+// The FSM is built and tested.
+fn main() -> FsmResult<()> {
+    let mut fsm = MyFsm::new(MyContext::default())?;
+    assert_eq!(0, fsm.val);
+    fsm.start()?;
+    let state_a: &MyStateA = fsm.get_state();
+    assert_eq!(1, state_a.n);
+    assert_eq!(1, fsm.val);
+    fsm.dispatch(MyEvent)?;
+    assert_eq!(2, fsm.val);
+    Ok(())
 }
-```
+```
+
+License: MIT OR Apache-2.0

README.md

@@ -0,0 +1,19 @@
+[package]
+name = "finny"
+version = "0.1.0"
+authors = ["Rudi Benkovic <rudi.benkovic@gmail.com>"]
+edition = "2018"
+repository = "https://github.com/hashmismatch/finny.rs"
+description = "Finite State Machines with a procedural builder-style API and compile time transition checks."
+license = "MIT OR Apache-2.0"
+keywords = ["fsm", "state"]
+categories = ["Data structures", "Algorithms"]
+
+[dependencies]
+derive_more = "0.99.11"
+finny_derive = { path = "../finny_derive", version = "0.1.0" }
+arraydeque = { version = "0.4", default-features = false }
+
+[features]
+default = ["std"]
+std = ["arraydeque/std"]

finny/Cargo.toml

@@ -0,0 +1,72 @@
+use crate::lib::*;
+
+use crate::{FsmBackend, fsm::EventContext};
+use super::{FsmQueueMock, FsmStateBuilder};
+
+pub struct FsmEventBuilderState<'a, TFsm, TContext, TEvent, TState> {
+    pub (crate) _state_builder: &'a FsmStateBuilder<TFsm, TContext, TState>,
+    pub (crate) _event: PhantomData<TEvent>
+}
+
+impl<'a, TFsm, TContext, TEvent, TState> FsmEventBuilderState<'a, TFsm, TContext, TEvent, TState> {
+    /// An internal transition doesn't trigger the state's entry and exit actions, as opposed to self-transitions.
+    pub fn internal_transition<'b>(&'b self) -> FsmEventBuilderTransition<'b, TFsm, TContext, TEvent, TState> {
+        FsmEventBuilderTransition {
+            _state_event_builder: self
+        }
+    }
+
+    /// A self transition triggers this state's entry and exit actions, while an internal transition does not.
+    pub fn self_transition<'b>(&'b self) -> FsmEventBuilderTransition<'b, TFsm, TContext, TEvent, TState> {
+        FsmEventBuilderTransition {
+            _state_event_builder: self
+        }
+    }
+
+    /// Transition into this state. The transition can have a guard and an action.
+    pub fn transition_to<'b, TStateTo>(&'b self) -> FsmEventBuilderTransitionFull<'b, TFsm, TContext, TEvent, TState, TStateTo> {
+        FsmEventBuilderTransitionFull {
+            _transition_from: self,
+            _state_to: PhantomData::default()
+        }
+    }
+}
+
+
+pub struct FsmEventBuilderTransition<'a, TFsm, TContext, TEvent, TState> {
+    _state_event_builder: &'a FsmEventBuilderState<'a, TFsm, TContext, TEvent, TState>
+}
+
+impl<'a, TFsm, TContext, TEvent, TState> FsmEventBuilderTransition<'a, TFsm, TContext, TEvent, TState>
+    where TFsm: FsmBackend
+{
+    /// An action that happens when the currently active state receives this event. No transitions.
+    pub fn action<TAction: Fn(&TEvent, &mut EventContext<'a, TFsm, FsmQueueMock<TFsm>>, &mut TState)>(&mut self, _action: TAction) -> &mut Self {
+        self
+    }
+    
+    /// A guard for executing this action.
+    pub fn guard<TGuard: Fn(&TEvent, &EventContext<'a, TFsm, FsmQueueMock<TFsm>>) -> bool>(&mut self, _guard: TGuard) -> &mut Self {
+        self
+    }
+}
+
+
+pub struct FsmEventBuilderTransitionFull<'a, TFsm, TContext, TEvent, TStateFrom, TStateTo> {
+    _transition_from: &'a FsmEventBuilderState<'a, TFsm, TContext, TEvent, TStateFrom>,
+    _state_to: PhantomData<TStateTo>
+}
+
+impl<'a, TFsm, TContext, TEvent, TStateFrom, TStateTo> FsmEventBuilderTransitionFull<'a, TFsm, TContext, TEvent, TStateFrom, TStateTo> 
+    where TFsm: FsmBackend
+{
+    /// An action that happens between the transitions from the two states.
+    pub fn action<TAction: Fn(&TEvent, &mut EventContext<'a, TFsm, FsmQueueMock<TFsm>>, &mut TStateFrom, &mut TStateTo)>(&mut self, _action: TAction) -> &mut Self {
+        self
+    }
+
+    /// A guard for starting this transition from one state to another, including executing the action.
+    pub fn guard<TGuard: Fn(&TEvent, &EventContext<'a, TFsm, FsmQueueMock<TFsm>>) -> bool>(&mut self, _guard: TGuard) -> &mut Self {
+        self
+    }
+}

finny/src/decl/event.rs

@@ -0,0 +1,45 @@
+use crate::lib::*;
+
+use crate::FsmBackend;
+use super::FsmStateBuilder;
+
+/// The main builder-API for defining your Finny state machine.
+#[derive(Default)]
+pub struct FsmBuilder<TFsm, TContext> {
+    pub _fsm: PhantomData<TFsm>,
+    pub _context: PhantomData<TContext>
+}
+
+/// The consumed struct of the FSM, ensures that all of the builder's references are released.
+pub struct BuiltFsm;
+
+impl<TFsm, TContext> FsmBuilder<TFsm, TContext>
+	where TFsm: FsmBackend
+{
+	/// Sets the initial state of the state machine. Required!
+	pub fn initial_state<TSTate>(&mut self) {
+		
+	}
+
+	/// Defines multiple initial states for multiple regions of the FSM. The type has to be a tuple
+	/// of the initial states for each region.
+	///
+	/// Example : `fsm.initial_states<(StateA, StateX)>()`
+	pub fn initial_states<TStates>(&mut self) {
+
+	}
+
+	/// Adds some information about a state.
+	pub fn state<TState>(&mut self) -> FsmStateBuilder<TFsm, TContext, TState> {
+		FsmStateBuilder {
+			_state: PhantomData::default(),
+			_fsm: PhantomData::default(),
+			_context: PhantomData::default()
+		}
+	}
+
+	/// Builds the final machine. Has to be returned from the definition function.
+    pub fn build(self) -> BuiltFsm {
+        BuiltFsm
+    }
+}

finny/src/decl/fsm.rs

@@ -0,0 +1,16 @@
+//! The builder-style API structures for defining your Finny FSM. The procedural macro parses
+//! these method calls and generated the optimized implementation.
+
+mod fsm;
+mod state;
+mod event;
+
+pub use self::fsm::*;
+pub use self::state::*;
+pub use self::event::*;
+
+#[cfg(feature = "std")]
+pub type FsmQueueMock<F> = crate::FsmEventQueueVec<F>;
+
+#[cfg(not(feature = "std"))]
+pub type FsmQueueMock<F> = crate::FsmEventQueueNull<F>;