Phyto FSM

A Rust procedural macro for generating state machines from PlantUML diagrams.

Overview

Many state machine frameworks provide the possibility to create a visualization from your FSM defined by the source code, which then can be e.g. added to your documentation. phyto-fsm does it the opposite way:

• you create a visual representation of an FSM using a PlantUML state diagram
• phyto-fsm
  • parses the diagram during compile time
  • generates a type-safe FSM representation as well as a trait to handle actions such as on transitions
• using the generated trait you define the actions to take on transitions

This way the design of the FSM is easy to grasp first hand and documentation and source code are always inline.

State Machine Features

• Events with custom data
• Customizable actions

Missing:

• composite states
• enter/exit actions
• exit state
• guards
• transition logging
• event deferring
• sub state machines
• history states

Generated Code Naming Conventions

When you use generate_fsm!("path/to/diagram.puml"), the macro generates various traits, enums, and structs based on your PlantUML diagram name and elements. Here's how they are named:

Core Generated Types

For a PlantUML diagram whose name is given by:

@startuml DiagramName
...
@enduml

The following is generated:

Event and Action Elements

The actions and events associated with a transition must be defined as such with PlantUML:

StateA --> StateB : EventName / ActionName

• EventName becomes the event that triggers the transition
• ActionName (optional) becomes the method called during the transition
• Use / to separate the event from the action

Example

1. Create a PlantUML state diagram

@startuml PlantFsm 

state Winter 
state Spring
state Summer
state Autumn

[*] --> Winter
Winter --> Spring : TemperatureRises
Spring --> Summer : DaylightIncreases / StartBlooming
Summer --> Autumn : DaylightDecreases / RipenFruit
Autumn --> Winter : TemperatureDrops / DropPetals 

@enduml

2. Generate the state machine

use phyto_fsm::generate_fsm;

// Generate FSM from PlantUML file
generate_fsm!("path/to/your/diagram.puml");

3. Implement your actions

use plant_fsm::{IPlantFsmActions, IPlantFsmEventParams, NoEventData};

struct PlantActions;

impl IPlantFsmEventParams for PlantActions {
    type TemperatureRisesParams = NoEventData;
    type DaylightIncreasesParams = i32;  // Lumens
    type DaylightDecreasesParams = NoEventData;
    type TemperatureDropsParams = NoEventData;
}

impl IPlantFsmActions for PlantActions {
    fn start_blooming(&mut self, lumens: Self::DaylightIncreasesParams) {
        println!("🌸 Blooming with {} lumens!", lumens);
    }
    
    fn ripen_fruit(&mut self, _: Self::DaylightDecreasesParams) {
        println!("🍎 Fruit is ripening");
    }
    
    fn drop_petals(&mut self, _: Self::TemperatureDropsParams) {
        println!("🍂 Dropping petals");
    }
}

4. Use your state machine

use plant_fsm::{PlantFsm, PlantFsmEvent};

fn main() {
    let actions = PlantActions;
    let mut fsm = PlantFsm::new(actions);
    
    fsm.trigger_event(PlantFsmEvent::TemperatureRises(()));
    fsm.trigger_event(PlantFsmEvent::DaylightIncreases(1000)); 
    fsm.trigger_event(PlantFsmEvent::DaylightDecreases(()));
    fsm.trigger_event(PlantFsmEvent::TemperatureDrops(()));
}