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

Missing Features

• enter/exit actions
• exit state
• guards
• 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 Freezing
  state Mild

  [*] --> Freezing
  Freezing -> Mild: TemperatureRises
  Mild -> Freezing: TemperatureDrops
}

state Spring {
  state Chilly
  state Warm
  [*] --> Chilly
  Chilly -> Warm: TemperatureRises
  Warm -> Chilly: TemperatureDrops
}

[*] --> Winter
Winter --> Spring : TimeAdvances
Spring --> Summer : TimeAdvances / StartBlooming
Summer --> Autumn : TimeAdvances / RipenFruit
Autumn --> Winter : TimeAdvances / DropPetals

@enduml

2. Generate the state machine

use phyto_fsm::generate_fsm;

// Generate FSM from PlantUML file
generate_fsm!(
    file_path = "path/to/your/diagram.puml",
    log_level = "debug"  // Optional: enables transition logging
);

3. Implement your actions

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

struct PlantActions;

impl IPlantFsmEventParams for PlantActions {
    type TimeAdvancesParams = std::time::SystemTime;
    type TemperatureRisesParams = NoEventData;
    type TemperatureDropsParams = NoEventData;
}

impl IPlantFsmActions for PlantActions {
    fn start_blooming(&mut self, time: Self::TimeAdvancesParams) {
        println!("Started blooming at {:?}", time);
    }

    fn ripen_fruit(&mut self, _: Self::TimeAdvancesParams) {
        println!("Fruit is ripening");
    }

    fn drop_petals(&mut self, _: Self::TimeAdvancesParams) {
        println!("Dropping petals");
    }
}

4. Use your state machine

use plant_fsm::PlantFsm;

fn main() {
    let actions = PlantActions;
    let mut fsm = PlantFsm::new(actions);

    // Transition within Winter: Freezing -> Mild
    fsm.temperature_rises(());

    // Transition to next season: Winter -> Spring (enters Spring::Chilly)
    fsm.time_advances(std::time::SystemTime::now());
}