Statecharts visualization

Sismic is not bundle with any graphical tool that can be used to edit or even view a statechart. Module sismic.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 sismic.io contains a function 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 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.

@startuml
title Elevator
state "active" as active {
  state "floorListener" as floorListener {
    [*] -right-> floorSelecting
    state "floorSelecting" as floorSelecting {
      floorSelecting --> floorSelecting : floorSelected / destination = event.floor
    }
  }
  --
  state "movingElevator" as movingElevator {
    [*] -right-> doorsOpen
    state "moving" as moving {
      moving --> doorsOpen : [destination == current] / doors_open = True
      state "movingDown" as movingDown {
        movingDown : **entry** / current = current - 1
        movingDown --> movingDown : [destination < current]
      }
      state "movingUp" as movingUp {
        movingUp : **entry** / current = current + 1
        movingUp --> movingUp : [destination > current]
      }
    }
    state "doorsClosed" as doorsClosed {
      doorsClosed --> movingUp : [destination > current]
      doorsClosed --> movingDown : [destination < current and destination >= 0]
    }
    state "doorsOpen" as doorsOpen {
      doorsOpen -right-> doorsClosed : [destination != current] / doors_open = False
      doorsOpen -right-> doorsClosed : [after(10) and current > 0] / destination = 0; doors_open = False
    }
  }
}
@enduml

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

_images/elevator.png

See also

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 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(statechart, filepath=None, *, based_on=None, based_on_filepath=None, statechart_name=True, statechart_description=False, statechart_preamble=False, state_contracts=False, state_action=True, transition_contracts=False, transition_action=True)

Export given statechart to plantUML (see http://plantuml/plantuml). If a filepath is provided, also save the output to this file.

Due to the way statecharts are representing, and due to the presence of features that are specific to Sismic, the resulting statechart representation does not include all the informations. For example, final states and history states won’t have name, actions and contracts.

If a previously exported representation for the statechart is provided, either as text (based_on parameter) or as a filepath (based_on_filepath parameter), it will attempt to reuse the modifications made to the transitions (their direction and length).

Parameters
  • statechart (Statechart) – statechart to export

  • filepath (Optional[str]) – save output to given filepath, if provided

  • based_on (Optional[str]) – existing representation of the statechart in PlantUML

  • based_on_filepath (Optional[str]) – filepath to an existing representation of the statechart in PlantUML

  • statechart_name (bool) – include the name of the statechart

  • statechart_description (bool) – include the description of the statechart

  • statechart_preamble (bool) – include the preamble of the statechart

  • state_contracts (bool) – include state contracts

  • state_action (bool) – include state actions (on entry, on exit and internal transitions)

  • transition_contracts (bool) – include transition contracts

  • transition_action (bool) – include actions on transition

Return type

str

Returns

textual representation using plantuml