Secretary of State

Convert csv state machine descriptions into mermaid markdown code.

Installation

Installation requires python 3 and pip.

1. Clone the repositoryy
2. Pip install the current directory to add it to PATH

git clone https://github.com/aidnem/secretary-of-state
cd secretary-of-state
pip install -e .

This will add the secretary command to path

Usage

To use secretary, simply pass in a path to a csv file:

secretary file.csv

This will spit the output into stdout. To capture it into a file, use something like the following:

secretary file.csv > file.md

If your state machine is very large/complex, it might be beneficial to combine compound conditions (expressions with '&&' or '||') into single conditions to simplify the diagram. Do this with the -c or --combine switch. Make sure to always pass the file as the first argument, followed by the flag.

secretary file.csv -c > file.md

CSV Format

Secretary accepts a state machine table in the following format:

• Row 1 - A list of the states, beginning with a blank cell. This row serves as the labels for the columns below it.

• Rows 2 until end of file - Rows, beginning with the current state, where each cell contains the condition for the transition to the next state, which is the state written in the first row directly above the cell. To make a cell not include a transition, make its content one of the following:

  • default
  • Not allowed
  • TBD

  Conditions may use && or || for conditionals that use and/or statements. These will be parsed and rendered as separate conditions with correct control flow by secretary. If the -c or --combine switch is specified, these 'compound conditions' will remain un-parsed and combined into one condition, just as they appear in the table. This is useful for large or complex state machines.

Example:

	IDLE	ACTIVE
IDLE	default	action == ACTIVATE && enabled
ACTIVE	timeout >= 500ms || action == DEACTIVATE	default

In this example, IDLE can transition to ACTIVE if action == ACTIVATE and enabled is true. ACTIVE can transition to IDLE if timeout >= 500ms or if action == DEACTIVATE.

The csv for this table is shown below:

,IDLE,ACTIVE
IDLE,default,action == ACTIVATE && enabled
ACTIVE,timeout >= 500ms || action == DEACTIVATE,default

The mermaid diagram generated by secretary from this output is the following:

flowchart LR

classDef state font-size:40px,padding:10px

node0:::state
node0([IDLE])
node1:::state
node1([ACTIVE])
node0 --> node2
node2{"action == ACTIVATE"}
node2 -.->|true| node3
node2 -.->|false| node0
node3{"enabled"}
node3 -.->|true| node1
node3 -.->|false| node0
node1 --> node4
node4{"timeout >= 500ms"}
node4 -.->|true| node0
node4 -.->|false| node5
node5{"action == DEACTIVATE"}
node5 -.->|true| node0
node5 -.->|false| node1

Loading

These example files can be found in example.csv and example.md.