A script which turns a text based sequence description into a sequence diagram similar to PlantUML or Mermaid.js, but the resulting file is an editable draw.io diagram instead of an image file.
src/main.py -o [output_file] [input_file]
Where the input file is a text file describing the sequence using the syntax explained below and the output file is the resulting draw.io diagram.
The input file contains one statement per line. The indentation of lines does not matter.
Lines where the content begins with // are ignored.
Comments at the end of statements are not supported.
title: My Diagram Title
If a title statement is present, the resulting diagram will be framed by a title frame. The title statement is optional.
title width 200 height 60: My Super Long Diagram<br/>Title With Multiple Lines
The size of the UML box containing the title can be customized.
participant Alice
participant J: John Jumper
participant ML: Multiple<br/>Lines
participant P: With "Special" Chars()
Participants must be declared explicitly at the beginning.
The name after the keyword participant is its identifier and must be unique.
It is used for referencing the participant in other statements.
Optionally a text other than the participant identifier may be specified.
This is useful if the text is very long or contains special characters.
The participants occur in the same order as specified.
participant Alice width 200
participant J width 200 spacing 150: John
The width of a participant and the spacing between the current and the previous participant can be customized.
vertical offset 30
vertical offset -50
When processing the sequence description a counter for the current vertical position is maintained. The vertical position is incremented before/after statements by a reasonable amount for typical use cases. In some cases it may be desirable to move content further up or down. This can be done using the vertical spacing statement. This statement may occur in any location and modifies the vertical position at this specific point.
activate Alice
deactivate Alice
Participants can be activated and deactivated explicitly or via messages (see below). A participant can be activated multiple times which results in stacked activation lines. At the end of the sequence description all participants must be inactive.
activate John Alice
deactivate John Alice
Multiple participants can be activated or deactivated at once to have the activation lines start, respectively end on the same position.
Alice ->+ John: A long message<br/>on multiple lines
John -->>- Alice
The generalized form looks like this:
<Sender> <Line><Arrow><Activation> <Receiver>[: <Message>]
The message text may be omitted (together with the colon).
The following line types are defined:
-Solid Line--Dashed Line
The following arrow types are defined:
>Block Arrow>>Open Arrow
The following activation types are defined:
+Receiver is activated by the message-Sender is deactivated by the message|Receiver is activated and deactivated by the message- Omitted: No activation
Alice -> Alice: I'm thinking
Alice -->>| Alice: I'm still thinking
Alice ->+ Alice: Doing other things while thinking
Self calls are like regular messages, but the sender equals the receiver.
Supported activation types are: none, +, |
Alice: I'm thinking
This is a short form for a self call using activation type |.
The message text for this syntax is required.
found left -> Alice: some event happened
John -> lost left: sending to someone
Using the keywords "found/lost left/right", found respectively lost messages can be created. These kind of messages are typically used if the sender/receiver is out of scope of the diagram. As with regular messages, the arrow type can be customized and the message text is optional.
found right ->+ Alice
John ->- lost right
Found messages may activate the receiver (+). Lost messages may deactivate the sender (-).
Other activation types are not valid.
John -> lost left 120
found right 140 -> Alice
The width of the message can be customized by adding a number.
opt something happened
...
end
Creates a frame for an optional part of the sequence.
alt x == 1
...
else str == "abc"
...
else
...
end
Creates a frame for different branches of the sequence. An arbitrary amount of branches can be defined. If the branch label is omitted, it defaults to "else".
loop until tired
...
end
Creates a frame for a looped part of the sequence.
break on error
...
end
Creates a frame to indicate the abortion of a sequence.
critical
...
end
Creates a frame to indicate an uninterruptible sequence.
par
...
and
...
end
Creates a frame to indicate multiple processes running in parallel.
group "custom"
...
end
group "custom" with text
...
section and more text
...
section and even more
...
end
Creates a frame with a custom title and optionally custom labels and multiple sections.
The vertical dimensions of a frame is determined by the current vertical position on the beginning and end of the frame as described above. The horizontal dimensions of a frame is determined by the participants mentioned in the statements within the frame. Therefore, a frame cannot be empty. Sometimes a frame must be enlarged, for example because of long texts. This can be done with the following statement:
extend frame 100
extend frame -60
The statement horizontally extends the current frame by the specified value. Positive values extend the frame to the right. Negative values extend the frame to the left. The size of the frame at the point where the statement occurs is extended.
note on Alice dx 10: short note
note on Alice width 150 height 80 dx 100 dy 50: a larger note with<br/>multiple lines
Notes are placed at the current vertical position at the lifeline of the specified participant. Using the attributes shown in the example, the size and position of the note can be modified. Notes do not modify the current vertical position or frame width.