.. role:: fsmlang(code)
	:language: fsmlang

===============
Event Sequences
===============

A finite state machine should be designed not only with a clear identification of the events the machine must handle,
but also with an understanding of the order in which these events will occur.  To facilitate this, FSMLang provides for
the declaration of these event sequences at the end of the machine.

Recalling the :ref:`the-simple-communicator`, we can list at least two event sequences which the machine must handle:

.. code-block:: fsmlang

	sequence seq1 SEND_MESSAGE, ACK;
	sequence seq2 SEND_MESSAGE, SEND_MESSAGE, ACK, SEND_MESSAGE, ACK;

The first sequence represents requesting to send a message and receiving the acknowledgement before another message is
sent, whereas the second sequence represents requesting to send two messages before the first acknowledgement is
received.

Executing `fsm -tp --add-plantuml-title simpleCommunicator.fsm` yields the following PlantUML diagrams, in addition
to the basic machine diagram:

.. uml::

	/'
		seq1.plantuml
	
		This file generated by FSMLang
	
	
	'/
	
	@startuml
	title seq1
	state IDLE
	state AWAITING_ACK
	[*] --> IDLE
	IDLE --> AWAITING_ACK: **Event 1:** SEND_MESSAGE\n **Action:** sendMessage
	AWAITING_ACK --> IDLE: **Event 2:** ACK\n **Action:** checkQueue
	
	@enduml
	
.. uml::

	/'
		seq2.plantuml
	
		This file generated by FSMLang
	
	
	'/
	
	@startuml
	title seq2
	state IDLE
	state AWAITING_ACK
	[*] --> IDLE
	IDLE --> AWAITING_ACK: **Event 1:** SEND_MESSAGE\n **Action:** sendMessage
	AWAITING_ACK --> AWAITING_ACK: **Event 2:** SEND_MESSAGE\n **Action:** queueMessage
	AWAITING_ACK --> IDLE: **Event 3:** ACK\n **Action:** checkQueue
	IDLE --> AWAITING_ACK: **Event 4:** SEND_MESSAGE\n **Action:** sendMessage
	AWAITING_ACK --> IDLE: **Event 5:** ACK\n **Action:** checkQueue
	
	@enduml


-----------
Transitions
-----------

When transitions are given by a function rather than a state, the sequence should indicate which option to choose.

.. code-block:: fsmlang

	sequence seq1 e1 transition s1, e2, e5;

Should the possible return values for the transition function be given in the machine specification, the transition
indicated in the sequence will be checked against that list.  A note will be placed in the PlantUML output with the
audit results.

When the sequence does not choose a transition, a note to that effect is also placed in the PlantUML output; the first
listed transition function return value will be chosen.  If no return values are listed, no transition will be made.

In the case that a sequence specifies a transition when no transition function is involved, the choice given in the
sequence is audited against the machine specification.  Again, the results of that audit are displayed as notes in
the PlantUML output.

--------------------
Start and End States
--------------------

Transition functions are a *choice* ; the event sequence will behave differently depending on which choice is taken.  To
fully document this in an event sequence, it is possible to declare a sequence as starting from any state.  Thus,
*sequence1* can progress through a transition choice taking the first path; then *sequence2* can be written to take up
from that same choice, but starting with a different option.  In this way, it is not necessary to repeat the initial part
of the sequence.

A start state is declared before the events themselves:

.. code-block:: fsmlang

	sequence seq1 start s1 e1, e2 transition s3, e4, e5;
	sequence seq2 start s2 e4, e5;

Here, the other possible transition after e2 is s2; the second sequence picks up there with the same events as the
first sequence thereafter.

End states are different; they exist only to provide an audit point.  If the sequence does not finish in the designated
end state, something is wrong.  A note to that effect is added to the PlantUML output.

End states are given after the event list:

.. code-block:: fsmlang

	sequence seq3 start s1 e1, e2, e3, e4 end s3;

-----------
HTML Output
-----------

The HTML output adds a table of all of the sequences in text (below), or as a list of the UML diagrams when `--include-svg-img`
is used and the images were previously produced.  The table is placed just before the table of sub-machines.

.. raw:: html

	<table class="elements">
	<thead><tr>
	<th colspan=5 align=left>Event Sequences</th>
	</tr>
	<tr><th>Name</th><th>Comment</th><th>Initial State</th><th>Sequence</th><th>Final State</th></tr>
	</thead>
	<tbody>
	<tr>
	<td class="label">seq1</td>
	<td>
	</td>
	<td>
	IDLE</td>
	<td>
	<ul class="event_sequence">
	<li>SEND_MESSAGE: IDLE &rarr; AWAITING_ACK (sendMessage)</li>
	<li>ACK: AWAITING_ACK &rarr; IDLE (checkQueue)</li>
	</ul>
	</td>
	<td>
	<p>Traced: IDLE.</p></td>
	</tr>
	<tr>
	<td class="label">seq2</td>
	<td>
	</td>
	<td>
	IDLE</td>
	<td>
	<ul class="event_sequence">
	<li>SEND_MESSAGE: IDLE &rarr; AWAITING_ACK (sendMessage)</li>
	<li>SEND_MESSAGE: AWAITING_ACK &rarr; AWAITING_ACK (queueMessage)</li>
	<li>ACK: AWAITING_ACK &rarr; IDLE (checkQueue)</li>
	<li>SEND_MESSAGE: IDLE &rarr; AWAITING_ACK (sendMessage)</li>
	<li>ACK: AWAITING_ACK &rarr; IDLE (checkQueue)</li>
	</ul>
	</td>
	<td>
	<p>Traced: IDLE.</p></td>
	</tr>
	</tbody>
	</table>

------------------------
ReSTructured Text Output
------------------------

The RST output adds a table of all of the sequences in text, or as a list of the UML diagrams when `--include-svg-img`
is used and the images were previously produced.  The table is placed just before the table of sub-machines.

See the Event Sequence section of :doc:`RST/simpleCommunicator`