use std::collections::hash_map::Entry;
use std::collections::HashMap;
use std::error::Error;
use std::fmt::{self, Debug};
use std::hash::Hash;
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum FsmError<S, E>
where
S: Debug + Clone,
E: Debug + Clone,
{
NoTransition { state: S, event: E },
}
impl<S, E> fmt::Display for FsmError<S, E>
where
S: Debug + Clone,
E: Debug + Clone,
{
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::NoTransition { state, event } => {
write!(f, "FSM NoTransition: state={state:?} event={event:?}")
}
}
}
}
impl<S, E> Error for FsmError<S, E>
where
S: Debug + Clone,
E: Debug + Clone,
{
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum BuildError<S, E>
where
S: Debug + Clone,
E: Debug + Clone,
{
MissingInitialState,
DuplicateTransition { state: S, event: E },
}
impl<S, E> fmt::Display for BuildError<S, E>
where
S: Debug + Clone,
E: Debug + Clone,
{
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::MissingInitialState => write!(f, "FSM initial state is required"),
Self::DuplicateTransition { state, event } => {
write!(
f,
"FSM duplicate transition: state={state:?} event={event:?}"
)
}
}
}
}
impl<S, E> Error for BuildError<S, E>
where
S: Debug + Clone,
E: Debug + Clone,
{
}
#[derive(Debug, Clone, PartialEq, Eq)]
struct Transition<S, M> {
next_state: S,
motion: M,
}
type TransitionKey<S, E> = (S, E);
#[derive(Debug, Clone)]
pub struct Fsm<S, E, M>
where
S: Hash + Eq + Clone + Debug,
E: Hash + Eq + Clone + Debug,
M: Clone + Debug,
{
transitions: HashMap<TransitionKey<S, E>, Transition<S, M>>,
state: S,
initial_state: S,
}
impl<S, E, M> Fsm<S, E, M>
where
S: Hash + Eq + Clone + Debug,
E: Hash + Eq + Clone + Debug,
M: Clone + Debug,
{
pub fn builder() -> FsmBuilder<S, E, M> {
FsmBuilder::new()
}
pub fn step(&mut self, event: &E) -> Result<(&S, &M), FsmError<S, E>> {
let key = (self.state.clone(), event.clone());
let transition = self
.transitions
.get(&key)
.ok_or_else(|| FsmError::NoTransition {
state: self.state.clone(),
event: event.clone(),
})?;
self.state = transition.next_state.clone();
Ok((&self.state, &transition.motion))
}
pub fn step_state(&mut self, event: &E) -> Result<&S, FsmError<S, E>> {
self.step(event).map(|(s, _)| s)
}
pub fn current_state(&self) -> &S {
&self.state
}
pub fn initial_state(&self) -> &S {
&self.initial_state
}
pub fn reset(&mut self) {
self.state = self.initial_state.clone();
}
pub fn transition_count(&self) -> usize {
self.transitions.len()
}
pub fn has_transition(&self, state: &S, event: &E) -> bool {
self.transitions
.contains_key(&(state.clone(), event.clone()))
}
pub fn transitions(&self) -> Vec<(&S, &E, &S, &M)> {
self.transitions
.iter()
.map(|((cs, evt), t)| (cs, evt, &t.next_state, &t.motion))
.collect()
}
}
#[derive(Debug, Clone)]
pub struct FsmBuilder<S, E, M>
where
S: Hash + Eq + Clone + Debug,
E: Hash + Eq + Clone + Debug,
M: Clone + Debug,
{
transitions: HashMap<TransitionKey<S, E>, Transition<S, M>>,
initial_state: Option<S>,
error: Option<BuildError<S, E>>,
}
impl<S, E, M> FsmBuilder<S, E, M>
where
S: Hash + Eq + Clone + Debug,
E: Hash + Eq + Clone + Debug,
M: Clone + Debug,
{
pub fn new() -> Self {
Self {
transitions: HashMap::new(),
initial_state: None,
error: None,
}
}
pub fn initial_state(mut self, state: S) -> Self {
self.initial_state = Some(state);
self
}
pub fn on(mut self, cs: S, evt: E, ns: S, motion: M) -> Self {
match self.transitions.entry((cs, evt)) {
Entry::Vacant(entry) => {
entry.insert(Transition {
next_state: ns,
motion,
});
}
Entry::Occupied(entry) => {
if self.error.is_none() {
let (state, event) = entry.key();
self.error = Some(BuildError::DuplicateTransition {
state: state.clone(),
event: event.clone(),
});
}
}
}
self
}
pub fn on_many<I>(mut self, transitions: I) -> Self
where
I: IntoIterator<Item = (S, E, S, M)>,
{
for (cs, evt, ns, motion) in transitions {
self = self.on(cs, evt, ns, motion);
}
self
}
pub fn build(self) -> Result<Fsm<S, E, M>, BuildError<S, E>> {
let initial_state = self.initial_state.ok_or(BuildError::MissingInitialState)?;
if let Some(error) = self.error {
return Err(error);
}
Ok(Fsm {
transitions: self.transitions,
state: initial_state.clone(),
initial_state,
})
}
}
impl<S, E, M> Default for FsmBuilder<S, E, M>
where
S: Hash + Eq + Clone + Debug,
E: Hash + Eq + Clone + Debug,
M: Clone + Debug,
{
fn default() -> Self {
Self::new()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
enum State {
Idle,
Running,
Stopped,
}
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
enum Event {
Start,
Stop,
Reset,
}
#[derive(Debug, Clone, PartialEq)]
enum Motion {
Log(String),
Alert,
None,
}
fn build_test_fsm() -> Fsm<State, Event, Motion> {
Fsm::builder()
.initial_state(State::Idle)
.on(
State::Idle,
Event::Start,
State::Running,
Motion::Log("started".into()),
)
.on(State::Running, Event::Stop, State::Stopped, Motion::Alert)
.on(State::Stopped, Event::Reset, State::Idle, Motion::None)
.build()
.unwrap()
}
#[test]
fn test_basic_transition() {
let mut fsm = build_test_fsm();
assert_eq!(*fsm.current_state(), State::Idle);
let (ns, motion) = fsm.step(&Event::Start).unwrap();
assert_eq!(*ns, State::Running);
assert_eq!(*motion, Motion::Log("started".into()));
}
#[test]
fn test_no_transition_error() {
let mut fsm = build_test_fsm();
let error = fsm.step(&Event::Stop).unwrap_err();
assert_eq!(
error,
FsmError::NoTransition {
state: State::Idle,
event: Event::Stop,
}
);
assert_eq!(*fsm.current_state(), State::Idle);
}
#[test]
fn test_reset() {
let mut fsm = build_test_fsm();
fsm.step(&Event::Start).unwrap();
fsm.step(&Event::Stop).unwrap();
assert_eq!(*fsm.current_state(), State::Stopped);
fsm.reset();
assert_eq!(*fsm.current_state(), State::Idle);
}
#[test]
fn test_full_cycle() {
let mut fsm = build_test_fsm();
fsm.step(&Event::Start).unwrap();
fsm.step(&Event::Stop).unwrap();
fsm.step(&Event::Reset).unwrap();
assert_eq!(*fsm.current_state(), State::Idle);
}
#[test]
fn test_builder_requires_initial_state() {
let error = Fsm::<State, Event, Motion>::builder().build().unwrap_err();
assert_eq!(error, BuildError::MissingInitialState);
}
#[test]
fn test_duplicate_transition_is_a_build_error() {
let error = Fsm::builder()
.initial_state(State::Idle)
.on(State::Idle, Event::Start, State::Running, Motion::Alert)
.on(State::Idle, Event::Start, State::Stopped, Motion::None)
.build()
.unwrap_err();
assert_eq!(
error,
BuildError::DuplicateTransition {
state: State::Idle,
event: Event::Start,
}
);
}
#[test]
fn test_first_duplicate_transition_is_reported() {
let error = Fsm::builder()
.initial_state(State::Idle)
.on(State::Idle, Event::Start, State::Running, Motion::Alert)
.on(State::Idle, Event::Start, State::Stopped, Motion::None)
.on(State::Running, Event::Stop, State::Idle, Motion::Alert)
.on(State::Running, Event::Stop, State::Stopped, Motion::None)
.build()
.unwrap_err();
assert_eq!(
error,
BuildError::DuplicateTransition {
state: State::Idle,
event: Event::Start,
}
);
}
#[test]
fn test_missing_initial_state_takes_precedence() {
let error = Fsm::builder()
.on(State::Idle, Event::Start, State::Running, Motion::Alert)
.on(State::Idle, Event::Start, State::Stopped, Motion::None)
.build()
.unwrap_err();
assert_eq!(error, BuildError::MissingInitialState);
}
#[test]
fn test_on_many_accepts_into_iterator() {
let transitions = [
(State::Idle, Event::Start, State::Running, Motion::Alert),
(State::Running, Event::Stop, State::Stopped, Motion::None),
];
let fsm = Fsm::builder()
.initial_state(State::Idle)
.on_many(transitions)
.on_many(std::iter::once((
State::Stopped,
Event::Reset,
State::Idle,
Motion::Alert,
)))
.build()
.unwrap();
assert_eq!(fsm.transition_count(), 3);
}
#[test]
fn test_error_types_implement_std_error() {
fn assert_error<T: std::error::Error>() {}
assert_error::<FsmError<State, Event>>();
assert_error::<BuildError<State, Event>>();
}
#[test]
fn test_transition_count() {
let fsm = build_test_fsm();
assert_eq!(fsm.transition_count(), 3);
}
}