Visualise your FSM

It can be extremely useful to visualise you FSM and with that in mind FSM2 is able to export your FSM to the smcat format and then convert that to an svg file (image).

https://github.com/sverweij/state-machine-cat

Start by exporting your fsm2 file to an smcat file.

final machine = StateMachine.create((g) => g
    ..initialState(Solid())
    ..state<Solid>((b) => b
      ..on<OnMelted>((s, e) => b.transitionTo(
            Liquid(),
            sideEffect: (e) => print('Melted'),
          )))
   ));
await machine.export('/path/to/file.smcat');

Install

Next we need to install the visualisation tools.

pub global activate fsm2
fsm2 --install

Generate

Now you can generate svg files to show your fsm.

fsm2 /path/to/file.smcat

fms2 will now generate an svg file which you can view using any suitable svg viewer.

Display

You now have two options to view the generated svg files.

Firefox

If you have firefox installed the fsm2 can automatically display the svg using firefox:

fsm2 --show /path/to/file.smcat

FSM2 Viewer

We have now created a flutter desktop application call fsm2_viewer.

GitHub - bsutton/fsm2_viewer: Desktop application viewer for the fsm2 library.GitHub

Desktop application for viewing all the svg pages of your FSM.

Page Breaks

When you FSM gets large it can be had to analyse the entire statemachine one page.

FSM2 allows you to put page breaks into rendered image.

You can add a page break at any state of coregion.

final machine = StateMachine.create((g) => g
    ..initialState<S>()
    ..state<Alive>((b) => b
      ..initialState<Young>()
      ..onEnter((s, e) async => watcher.onEnter(s, e))
      ..onExit((s, e) async => watcher.onExit(s, e))
      ..on<OnBirthday, Young>(
          condition: (e) => human.age < 18, sideEffect: (e) async => human.age++)
      ..on<OnBirthday, MiddleAged>(
          condition: (e) => human.age < 50, sideEffect: (e) async => human.age++)
      ..on<OnBirthday, Old>(
          condition: (e) => human.age < 80, sideEffect: (e) async => human.age++)
      ..on<OnDeath, Purgatory>()
      ..state<Young>((b) => b..onExit((s, e) async => watcher.onExit(s, e)))
      ..state<MiddleAged>(
          (b) => b..onEnter((s, e) async => watcher.onEnter(s, e)))
      ..state<Old>((b) => b))
    ..state<Dead>((b) => b
      ..pageBreak
      ..onEnter((s, e) async => watcher.onEnter(s, e))

      /// ..initialState<InHeaven>()
      ..state<Purgatory>((b) => b
        ..onEnter((s, e) async => watcher.onEnter(s, e))
        ..on<OnJudged, Buddhist>(
            condition: (e) => e.judgement == Judgement.good,
            conditionLabel: 'good')
        ..on<OnJudged, Catholic>(
            condition: (e) => e.judgement == Judgement.bad,
            conditionLabel: 'bad')
        ..on<OnJudged, SalvationArmy>(
            condition: (e) => e.judgement == Judgement.ugly,
            conditionLabel: 'ugly'))
      ..state<InHeaven>((b) => b..state<Buddhist>((b) => b))
      ..state<InHell>((b) => b
        ..state<Christian>(
            (b) => b..state<SalvationArmy>((b) {})..state<Catholic>((b) => b))))
    ..onTransition((from, event, to) => watcher.log('${event.runtimeType}')));

In the above example the 'Dead' will appear on two pages. It will appear on page 1 as a simple state and it will appear on page 1 as the parent state of any nested children. The blue border indicates a parent state whose contents is displayed on the next page.

Page 1

Page 2

Watch and refresh

Whilst working on you fsm it can be handy to see the latest version of the FSM.

You can use the fsm2 watch option to regenerate and display the latest svg file:

fsm2 -s -w /path/to/file.smcat

Now each time you regenerate the smcat file fsm2 will launch firefox with the latest version.

Script it

You can use dcli to re-generate and display your smcat file on demand.

Dcli is a library and tooling for creating cli apps using dart.

pub global activate dcli
cd /your/projectroot/tool
dcli create gen_smcat.dart

Dcli will create a sample script and a pubspec.yaml in the tool directory. Edit the pubspec.yaml in the tool directory to include your own project:

name: gen_smcat
version: 0.0.1
description: A script generated by dcli.
environment: 
  sdk: '>=2.9.0 <3.0.0'
dependencies: 
  args: ^1.0.0
  dcli: ^0.32.0
  path: ^1.0.0
  fsm2: ^0.10.0
  <your project name>:
    path: ..

dev_dependencies: 
  pedantic: ^1.0.0

Replace the contents of gen_smcat.dart with:

#! /usr/bin/env dcli

import 'dart:io';
import 'package:dcli/dcli.dart';
/// path to script that generates fsm 
import '../cleaning_air_fsm.dart';
 
void main(List<String> args) {

  // replace 'createMachine' with a call to your method
  // that creates your fsm.
  
  var machine = createMachine();
  machine.export('cleaning_air.smcat');

}

To generate and visualise your FSM.

Open two terminal windows

Use the first terminal window to regenerate the smcat file each time you change your fsm.

tool/gen_smcat.dart

Use the second terminal to have fsm2 watch for changes and automatically display them.

fsm2 --show tool/cleaning_air.smcat