visualization.rst

Statecharts visualization

Sismic is not bundle with any graphical tool that can be used to edit or even view a statechart. Module :pysismic.io contains routines that can be used to (import and) export statecharts to other formats, some of them being used by third-party tools that support visualising (or editing) statecharts.

Notably, module :pysismic.io contains a function :py~sismic.io.export_to_plantuml that exports a given statechart to PlantUML, a tool based on graphviz that can automatically render statecharts (to some extent). An online version of PlantUML can be found here.

Function :py~sismic.io.export_to_plantuml can be directly called from the command-line without having to run a Python interpreter, through the sismic-plantuml (or python -m sismic.io.plantuml) command-line interface.

usage: sismic-plantuml [-h] [--based-on based] [--show-description]
                    [--show-preamble] [--show-state-contracts]
                    [--show-transition-contracts] [--hide-state-action]
                    [--hide-name] [--hide-transition-action]
                    statechart

Command-line utility to export Sismic statecharts to plantUML. 
See sismic.io.export_to_plantuml for more informations.

positional arguments:
statechart                      A YAML file describing a statechart

optional arguments:
-h, --help                      show this help message and exit
--based-on based                A previously exported PlantUML representation 
                                    for this statechart
--show-description              Show statechart description
--show-preamble                 Show statechart preamble
--show-state-contracts          Show state contracts
--show-transition-contracts     Show transition contracts
--hide-state-action             Hide state action
--hide-name                     Hide statechart name
--hide-transition-action        Hide transition action

For example, the elevator statechart presented in the previous section can be exported to the following PlantUML excerpt.

/examples/elevator/elevator.plantuml

This PlantUML description can automatically be converted to the following statechart representation using the PlantUML tool (an online version can be found here).

PlantUML's rendering can be modified to some extent by adjusting the notation used for transitions. By default, --> transitions correspond to downward transitions of good length.

A transition can be shortened by using -> instead of -->, and the direction of a transition can be changed by using -up->, -right->, -down-> or -left->. Both changes can be applied at the same time using -u->, -r->, -d-> or -l->. See PlantUML documentation for more information.

If you already exported a statechart to PlantUML and made some changes to the direction or length of the transitions, it is likely that you want to keep these changes when exporting again the (possibly modified) statechart to PlantUML.

The :py~sismic.io.export_to_plantuml function accepts two optional (mutually exclusive) parameters based_on and based_on_filepath that can be used to provide an earlier version of a PlantUML text representation (or a path to such a version if based_on_filepath is used). This will then be used to incorporate as much as possible the changes made on transitions.

sismic.io.export_to_plantuml