I made a tool to automatically generate a state transition diagram that can be used for both web development and application development

Overview

The other day this article introduced how to create a state transition diagram using graphviz, but it is still complicated and has a lot of description. So I thought it was hard to get along with, so I created a command line application that automatically generates the source code of this graphviz and outputs the image.

This application is called Pyagram, and as you might guess from its name, it was developed using Python. The development period was one day.

By using this Pyagram, it becomes possible to create a complicated state transition diagram relatively easily, so I would like to introduce it below.

For how to draw the state transition diagram, refer to this article.

The finished figure looks like the one below.

There are several objects in the figure.

--Figure title (top) --View (double circle) --Server-side processing (single circle on gray background) --Screen transition (dashed arrow) --Processing flow (straight arrow)

The above figure is a diagram of a web application, but I think that you can draw a highly complicated flow that links the smartphone application and the server side depending on your ingenuity.

How to write source code

First of all, use "@" to set the title of the figure.

@[title]
Screen transition diagram example

Then use "#" and "->" to define the screen and its transitions.

In this example, there are 3 screens, list, new creation, and error, and the list and new creation screen are connected to each other.

In addition, multiple screen transitions can be defined on one screen, and the screen path can also be defined under the screen name.

It will be a guideline when adding server-side processing later, so it is recommended to first define the screen-only transition in this way.

#[List screen]
/index

-->New creation screen

#[New creation screen]
/add

-->List screen

-->New creation screen

#[Server error screen]

Next, use "==>" to connect screen and server-side processing.

You can write multiple branches in one process, as in the example below.

You can also define a string for the label that appears next to the arrow. I mainly write the result of processing here.

$[GET /index]
==>List screen

$[GET /add]
==>New creation screen

$[POST /add]
==>Validation

$[Validation]
If the input value is valid
==>Save

If the input value is invalid
==>New creation screen

$[Save]
success
==>List screen

Database error
==>Server error screen

Finally, connect the actions from the screen with "==>".

#[List screen]
/index

-->New creation screen

Click the new button
==> GET /add


#[New creation screen]
/add

-->List screen

-->New creation screen

Click the back button
==> GET /index

Click the register button
==> POST /add

There are other samples on Github, so please refer to them.

Installation method

If you install it with the pip3 command, dependent libraries such as pyparsing will be installed at the same time.

After installation, the pyagram command will be saved in the appropriate bin directory, like / usr / local / bin / pyagram.

It seems that graphviz itself is for various OS, but since I only have a Mac at hand, I am only supporting Mac OS for the time being. Reports that it worked on other operating systems are welcome.

pip3 install pyagram

Execution method

The pyagram command takes two arguments.

The first is the t option, which sets the image format. You can use three types of image formats: gif, png, and svg.

The second is the i option, which sets the input file. The extension is optional and does not need to be.

The third is the o option, which specifies the output path. If not specified, it will be output to the same location as the input file.

The fourth is the font name. If not specified, the default font will be used. If the font name contains spaces, enclose it in "" (double quotation marks).

pyagram -t {image type} -i {source file}　-o {output path}　-f {font name} -d std

About implementation

It is divided into four processes: lexical analysis, parsing, intermediate file generation, and image file generation.

For lexical analysis, we used a parser combinator called pyparsing so that we could handle it without using complicated regular expressions.

In parsing, the abstract syntax tree is generated using the data generated by lexical analysis. I'm thinking that parsing could be simplified by making a more proper BNF, but I'd like to leave this as an issue later.

After outputting the graphviz source code in the intermediate file generation. Output the image file using the graphviz command. Intermediate files are deleted after use.

About the future

The number of drawings I draw in my work has gradually increased, but the tools I use differ depending on the diagram, which makes it bothersome, so I would like to be able to create all the diagrams I personally use with Pyagram. I will.

Also, if you have any request, I will add it even when I have time.

Supplement

I am surprised to hear a big response unexpectedly.

To add a little bit, the motivation for making this was that I wanted to convey the specifications a little more clearly, but I didn't want to spend too much time (can't) create the diagram. Especially when having a tester perform an integration test, there was a situation that it was difficult to do the test without at least the screen transition diagram. Also, from a management standpoint, most of my work is communication with customers and developers, project progress, design, etc., but I also want to get into the implementation to some extent (otherwise maintenance is done occasionally). Due to the circumstances (sometimes difficult things may be completed), we are trying to describe the contents with a certain degree of fineness.

The emphasis is on not spending too much time, so the appearance is secondary. The layout changes every time I generate a diagram in Graphviz, but if you're curious about this, try running the command a few times. If you do it several times, you will get a layout that is somewhat convincing. By the way, some of the source code I had had the same layout no matter how many times I executed the command. The algorithm around here depends on Graphviz, so I can't say for sure, but I felt that the layout tended to be fixed as the number of objects increased.

We have also introduced a new syntax for drawing diagrams of Web API integration with smartphone apps.

%[Client-side processing name]

If you write like this, a single circle without a background color will be displayed. It is supposed to be used for writing client-side processing such as smartphone apps and SPA frameworks such as AngularJS.

Since it has already been uploaded to PyPI, the latest version will be installed with the pip3 command described above.

If you already have it installed, you can upgrade it with the following command.

pip3 install pyagram --upgrade

For your reference, I will attach a diagram assuming a system that links a hybrid application using AngularJS and Cordova and a Web API.

Please refer to the link below for how to write the source code.

https://github.com/hideshi/pyagram/blob/master/example/mobile_app.txt

Supplement 2016/07/28

KAMEDA Akihiro made Windows support. In addition, we have added a command line option that allows you to specify the font type. Thank you very much.

The usage is as follows.

pyagram -t {Image type} -o {Output path} -i {Input file} -f {Font name}

If the font name contains spaces, it will work if you enclose it in double quotes as shown below.

pyagram -t {Image type} -o {Output path} -i {Input file} -f "Hiragino Kakugo Pro"

You can get the latest version with the pip3 command, so please try it.

Supplement 2016/07/30

YOSHIDA Katsuhiko made some improvements. Thank you very much.

--The extension of the input file is now arbitrary. It is OK without the extension. -&% @ $ # <>? Can now be included in characters.

Supplement 2016/07/31

New function to generate ER diagram has been added.

Supplement 2016/08/14

Due to a request, we have released Web service that can create state transition diagrams using Pyagram. You can get the image of the state transition diagram just by inputting the source code and pressing the image generation button. However, due to the characteristics of the system, the generated image is temporarily saved on the server. Also, since SSL is not installed so far, the source code sent will be sent in clear text. Therefore, please use it only when it is okay to send it, and use Pyagram in other cases. In addition, affiliates are displayed so that we can continue to provide services. Thank you for your understanding.