
p(edit-on-github). "Edit on GitHub":https://github.com/Yakindu/statecharts/edit/master/plugins/org.yakindu.sct.doc.user/src/user-guide/statechart_language.textile

h1(#the-statechart-language). The statechart language

This chapter describes the language used to describe statecharts. It consists of graphical and textual elements.

h2(#the-statechart-language-basics). State machine basics

h3(#the-statechart-language-basics-wording). Words and Definitions

To prevent any confusion, some definitions:

* A *"finite state machine":https://en.wikipedia.org/wiki/Finite-state_machine* (FSM) is an abstract machine that consists of a finite set of states and its behavior.
* A *"state diagram":https://en.wikipedia.org/wiki/State_diagram* is one of many possible representations of an FSM. A "state transition table":https://en.wikipedia.org/wiki/State_transition_table would be different way to describe an FSM.
* A *"statechart":https://en.wikipedia.org/wiki/State_diagram#Harel_statechart* is an extended form of the classic state diagram. However, the basic principles are the same. In this documentation, the term "statechart" usually means the graphical representation of a state machine, while the term "state machine" usually pertains to its dynamic aspects.

h3(#the-statechart-language-basics-theory). Automata theory

YAKINDU SCT was designed to create statecharts according to "David Harel's":https://en.wikipedia.org/wiki/David_Harel statechart theory. Harel statecharts have become part of the "Unified Modeling Language":https://en.wikipedia.org/wiki/Unified_Modeling_Language (UML). Harel introduced a couple of extensions to convetional state diagrams, making them more concise and more readable.

h4(#classic_state_diagrams). Classic state diagrams

Classic state diagrams describe finite state machines (FSM) and consist of the following things only:

* A (finite) set of possible states
* A start state
* An accepting or final state
* A set of transitions connecting states
* A set of input symbols
* A set of output symbols
* An output function, mapping pairs of input symbols and states to output symbols

These parameters describe a finite state machine completely.

h4(#moore_and_mealy_machines). Moore and Mealy machines

In classic automata theory, two distinct types of finite state machines exist:

* The *"Moore machine":https://en.wikipedia.org/wiki/Moore_machine*, where the output of the machine depends on its current state only
* The *"Mealy machine":https://en.wikipedia.org/wiki/Mealy_machine*, where the output of the machine depends on its current state and its input.

It is possible to transform these types of machine into each other, however, states, transitions and the output function need to be changed to achieve this.

h4(#harel_statecharts). Harel statecharts

Harel statecharts extend the classic state diagrams by a couple of additional aspects, resulting in representations that need much less states and transitions, making them much more compact, expressive, manageable and comprehensible – though not as mathematically concise as Moore or Mealy machines.

Harel added the following notations, dealing with _hierarchy_, _concurrency_, and _communication_:

* _Composite states_ and _regions_, containing nested states or regions.
* _History states_, allowing to re-enter a composite state or region at the point where they had been left.
* _Orthogonal states_, allowing to run state machines concurrently.
* _Events_, allowing for communication between orthogonal states.
* _Variables_, allowing to memorize values and reducing the necessary number of states drastically.
* _Actions_ (output) can not only occur along transitions, but additionally inside of states, especially as entry actions or exit actions.
* _Activities_ (operations), bridging the gap between a state machine and real-world behavior.

Since Harel statecharts are a superset of Mealy and Moore machines, it is possible to model the latter in YAKINDU Statechart Tools as well.

###. FIXME: The subsequent section a) doesn't cover all the differences between the YAKINDU statechart language and the UML and b) contains implementation-specific aspects that are unrelated to the language. For now, let's omit that section and refine it later.

###. h4(#yakindu_statecharts_and_statecharts). YAKINDU statecharts and UML statecharts

###. To define the behavior in the statechart, YAKINDU Statechart Tools uses its own statechart language, explained in this chapter.

###. YAKINDU statecharts are very similar to UML statecharts. For readers who are familiar with the latter, some words about differences between the two:

###. * YAKINDU statecharts are self-contained with interfaces defining events and variables.
###. * Core execution semantics are run cycle-driven, not event-driven.
###. ** This allows to process concurrent events.
###. ** Event-driven behavior can be defined on top.
###. * Time is an abstract concept for statecharts.
###. * Time control is delegated to the environment.

###. The model interpreter and different flavors of generated code are following these same core semantics.

###. Please refer to the Wikipedia article "UML state machine":https://en.wikipedia.org/wiki/UML_state_machine for more details.



###. FIXME: I (Rainer) didn't get the purpose of the following section.

###. h2(#why-statechart-language). Why another language?

###. Before you get too intrigued by learning yet another language, even one you can't use anywhere outside of YAKINDU SCT, you should know _why_ YAKINDU SCT uses its own domain specific language.

###. There are other tools out there that allow you to draw state diagrams, add behavior to them and even generate code out of them. Some of these tools are even offering a much wider palette of languages you can generate to. What they do not have is their own language. The text you type in is directly copied to the generated code instead. One might argue that this is pretty good, because you can then use any possible language construct of your target language, which is true. If you ever want to switch to another language, because maybe you need the exact same construct in two parts of a multi-language project, those constructs don not work anymore. Even worse, the tool cannot inform you that your input is invalid, because all it does is pass raw text through to the generated code.

###. With the use of its own language, YAKINDU SCT is able to:

###. * Verify the input (syntax and semantic)
###. * Offer refactorings
###. * Offer special triggers for reactions, for example timed ones
###. * Correctly transform all language statements into the target language
###. * Simulate the statechart, so the correct behavior can be verified before any line of code is written or generated

###. Also, YAKINDU SCT's language is not complicated at all. If something is not clear, this chapter should be able to help you.



h2(#statechart_model). Statechart model

A _statechart_ or _statechart model_ consists of several components.

The most important part is the _diagram_, comprising "states":#state and "transitions":#transition. They are organized into zero or more "regions":#region. For hints how to use the statechart editor to modify a statechart, see section "Editing statecharts".

The _definition section_ is a textual statechart model component. It contains definitions of "namespaces":#namespace, "interfaces":#interface-scope, "variables":#variables, events, operations, etc.

Most objects defined in the definition section have a _type_. For example, a variable could be of the _integer_ type. Another example is the return type of an operation (if any). Events can be typed as well. For details, see "the section about types":#types.

A type system or _domain_ specifies which types are available. YAKINDU Statechart Tools has a built-in type system.

==<div class="pro-feature">==
YAKINDU Statechart Tools Professional Edition allows for additional domains to be installed and includes and domain for the C programming language.
==</div>==



h2(#graphical-elements). Statechart elements

h3(#region). Region

YAKINDU statecharts are organized in regions. Hence it is possible to organize multiple state machines in different regions and to run them virtually concurrently.

!(standard-image)images/docu_parallelRegions.jpg(Parallel regions)!

p=. Parallel regions

Regions can contain "states":#state. Regions can be contained in states as well, turning them into "composite states":#composite-state.


h3(#state). State

States are the central elements of a state machine. A state has to be placed inside a "region":#region and must have a name that is unique inside this region. During state machine execution, a state can be active or passive.

A state can have _behavior_. The behavior specifies which "actions":#reactions are executed. Such actions can be triggered by entering the state, leaving the state, occurrence of events, conditions becoming true, or time passing. The behavior specification is a text inside the state's box and consists of a sequence of so-called "_local reactions_":#reactions. 

The state *Countdown* in the following example has three local reactions:

p(#fig_state-example). 
!(standard-image)images/docu_state_010_example_01.png(State example)!

p=. State example: A simple state machine to launch a rocket.

When the *Countdown* state is entered, it sets the counting variable _t_ to 10. As long as that variable's value is greater than 0, each second it gets counted down by 1. The operation _speak_ provides audible information on how many seconds to go until rocket launch. If _t_ has been counted down to 0 – checked by a transition's _guard condition_ –, the *Countdown* state will become inactive and launches the rocket upon exiting. The countdown can be aborted anytime before launch by a _cancel_ event. (See figure "&quot;Transition example&quot;":#fig_transition-example for a different state machine which solves the same task but puts more emphasis on transitions.)

_Can you find the mistake in the state behavior?_


h3(#transition). Transition

A transition is the transfer of one "state":#state to another. A transition is diagrammed as an arrow leading from a _source state_ to a _target state_.

A transition should have a _transition "reaction":#reactions_. The transition reaction specifies what the conditions are for this transition to be taken and which actions, if any, are to be executed. The occurrence of an event, a condition becoming true, or time passing can trigger a transition. The transition's reaction is attached to the transition's arrow as a text. Its syntax can be found in the section on "reactions":#reactions.

*Please note:* Transitions without any reaction are possible, but useless. They will never be taken.

Here's an example:

p(#fig_transition-example). 
!(standard-image)images/docu_transition_030_example_01.png(Transition example)!

p=. Transition example: A simple state machine to launch a rocket.

The initial transition's _effect_ sets the counting variable _t_ to 10. As long as that variable's value is greater than 0, each second it gets counted down by 1. The operation _speak_ – executed as one of a transition's _actions_ – cares for audible information on how many seconds to go until rocket launch. If _t_ has been counted down to 0 – checked by a transition's _guard condition_ –, the rocket is launched. The countdown can be aborted anytime before launch by a _cancel_ event which _triggers_ the appropriate transition to fire. (See figure "&quot;State example&quot;":#fig_state-example for a different state machine which solves the same task but puts more emphasis on states.)

Figure "&quot;Transition syntax overview&quot;":#fig_transition-syntax-overview shows how the syntax of a transition reaction is defined.

p(#fig_transition-syntax-overview). 
!(standard-image)images/docu_grammar_030_transition-overview.png(Transition syntax overview)!

p=. Transition syntax overview

h4(#entry-and-exit-points). Entry and exit points

Unlike "UML":https://en.wikipedia.org/wiki/Unified_Modeling_Language transitions, transitions in YAKINDU statecharts can denote specific entry or exit points when leaving or entering composite states. This is denoted by the _TransitionProperties_ non-terminal symbol in figure "&quot;Transition syntax overview&quot;":#fig_transition-syntax-overview.

The syntax to connect a transition to a "named entry":#entry is as follows:

<code># ><em>entry-name</em></code>

A "named exit":#exit can be used as follows:

<code># <em>exit-point-1</em>> [ <em>exit-point-2</em>> ]…</code>

It is also possible to have both in one transition specification. The order of exit and entry points is irrelevant. Instead, the position of the @>@ character is decisive:

* If the @>@ character is to the _right_ of a name, like in @exit_name>@, that name denotes an _exit_.
* If the @>@ character is to the _left_ of a name, like in @>entry_name@, that name denotes an _entry_.

The sample statechart in figure "&quot;Entries and exits&quot;":#fig_state_entry_exit contains two composite states:

* The composite state _Process_ models a process with two passes (states) A and B. If both passes succeed, the composite state is left via the _no&#95;problem_ exit node. However, if an error occurs in either A or B the execution flow proceeds to the _problem_ exit point and leaves the composite state there.
* The composite state _Handle result_ is intended to handle the processing result, be it success or failure. It has two entry points _success_ and _failure_.

The question is how to connect the exit points of _Process_ to the corresponding entry points of _Handle result_. This is done by two transitions leading from _Process_ to _Handle result_ and appropriate specifications.

The transition shown on the left specifies @# no_problem> >success@. This means: If the source composite state is left via the _no&#95;problem_ exit point, then enter the target composite state at the _success_ entry point. The specification of the transition on the right is analogous: If the source state is left via the _problem_ exit point, then enter the target state at the _failure_ entry point.

Alternatively, _Process_ could have been modeled with two different error exit states, say _error&#95;1_ and _error&#95;2_. This would allow to respond differently to different error conditions, while still enabling to catch them both with a single flow. A transition with @# >error_1 >error_2 problem>@ would do so.

p(#fig_state_entry_exit). 
!(standard-image)images/docu_state_entry_exit.png(Entries and exits)!

p=. Entries and exits

h4(#transition-priorities). Transition priorities

If a state has several outgoing transitions, based on the events that occured and on guard conditions, several of these transitions could fire at the same time. Here's simple example:

p(#fig_transition-priorities-1). 
!(standard-image)images/docu_transition_020_priorities_01.png(Transition priorities [1])!

p=. Transition priorities &#91;1]

Which transition will fire when the state machine is in state *A* and event _e1_ occurs? Fortunately YAKINDU state machines behave deterministically, so this question can be answered unambiguously. Outgoing transitions of a state have a definite order and are _prioritized_ by that order. The state machine checks the transitions one by one in their order and executes the first transition that fulfills all prerequisites for firing.

As you can see in figure "&quot;Transition priorities &#91;1]&quot;":#fig_transition-priorities-1, little numbers indicate the transition priorities. These numbering is shown only if the option _Show transition priority_ in _Window → Preferences → YAKINDU SCT → Diagram Appearance_ is activated. By default, this option is _not_ activated.

The order of transitions is a property of their source state. In the example above, the transition priorities of state *A* appear like this in the _Properties_ view:

p(#fig_transition-priorities-2). 
!(standard-image)images/docu_transition_020_priorities_02.png(Transition priorities [2])!

p=. Transition priorities &#91;2]

To change priorities, select a transition in the _Properties_ view and click on the _up_ or _down_ button as appropriate.


h3(#entry). Entry

When a state machine starts or when the control flow enters a "region":#region, an _entry_ defines which "state":#state is to be activated first. The flow passes through the state machine's or the region's entry and transitions to the target state the entry's transition is pointing to. This state becomes active.

An entry has a single outgoing transition and no incoming ones. Its outgoing transition has neither a trigger nor a guard condition. It is always taken immediately.

An entry is depicted as a filled circle, see figure "&quot;Entry, exit, and final state&quot;":#fig_state_entry_exit_final_explained.

p(#fig_state_entry_exit_final_explained). 
!(standard-image)images/docu_state_entry_exit_final_explained.png(Entry, exit, and final state)!

p=. Entry, exit, and final state

h4(#default-entry-and-initial-state). Default entry and initial state

An entry without a name is called the _default entry_. It is similar to the UML's _initial state_. However, while the transition from the initial state to an ordinary state may specify a guard, the transition sourced at an entry cannot.

A region may have at most one default entry.

h4(#named-entries). Named entries

The "default entry":#default-entry-and-initial-state specifies a single entry point into a region. A region can provide a multitude of additional or alternative entry points, thus implementing different kinds of behavior, depending on which entry point has been taken. If a region comprises multiple entries, these entries must be _named_. An entry's name must be unique within its region.

The default entry implicitly has the name @default@. Alternatively, it is possible to explicitly give the name @default@ to the default entry. Semantically both variants are equivalent. Whether an entry has no name or it has the name @default@: in both cases the entry is called _default entry_.

An incoming transition to a composite state can specify a named entry it shall lead to. For details, see "Entry and Exit points":#entry-and-exit-points.

Named entries have no equivalent in the UML.

The sample statechart in figure "&quot;Entry state&quot;":#fig_state_entry has a composite state named _Handle result_. This composite state has a default entry as well as an entry called _failure_. If state *A* is active and the _error_ trigger fires, control is transitioned to the _Handle result_ composite state. The notation @error # >failure@ specifies that the _failure_ entry is to be used; see "Entry and exit points":#entry-and-exit-points.

p(#fig_state_entry). 
!(standard-image)images/docu_state_entry.png(Entry state)!

p=. Entry state


h3(#exit). Exit

An _exit_ is a pseudo state that is used to leave and deactivate a composite state. Exits are counterpart to "entries":#entry. They are also known as exit points, exit states, or exit nodes. See section "&quot;Final state&quot;":#final-state for a different way to terminate a region or state machine.

An exit may have multiple incoming transitions and has no outgoing one.

An exit state is depicted as an unfilled circle with an X-shaped cross, see figure "&quot;Entry, exit, and final state&quot;":#fig_state_entry_exit_final_explained.

Within a region, multiple exits are allowed. Each exit must either have a name that is unique within its region or be the _default exit_. The default exit is either unnamed or has the name @default@, which is semantically equivalent. A region may have at most one default exit. For details on how to connect named exits to transitions, see subsection "&quot;Entry and exit points&quot;":#entry-and-exit-points in the section on transitions.

When a composite state reaches an exit in any of its regions, all states in other regions of that composite state, if any, are deactivated immediately. The composite state will be left and be deactivated. It maintains no status information that could be probed from the outside. In other words, reaching an exit in one of a composite state's regions has severe consequences for all the other regions since they are exited and disposed immediately. After that, the containing composite state is also exited. There must be an unguarded transition that catches the exit and leads to another state outside of the composite state. The semantics of exit is different from that of final state; please see section "&quot;Final state&quot;":#final-state for details.

Exits have no equivalent in the UML.


h3(#final-state). Final state

A _final state_ denotes the end of the execution flow of a state machine or region. See section "&quot;Exit&quot;":#exit for a different way to terminate a composite state.

A final state is depicted as an unfilled circle with a smaller filled black circle inside, see figure "&quot;Entry, exit, and final state&quot;":#fig_state_entry_exit_final_explained.

A final state can have multiple incoming transitions and has no outgoing ones.

Within a region, only a single final state is allowed, but each region may have its own final state.

When a region reaches its final state, control stops there and waits until all other orthogonal regions, if any, have reached their respective final states, too. The semantics of final states is different from that of exits; please see section "&quot;Exit&quot;":#exit for details.

bq.. *Note*

Final states are proper states. This is different from the UML, where a final state is a pseudo state, i.e. in the UML a final state cannot have any properties normal states can have, except for a name.


h3(#choice). Choice

A choice is a pseudo state. It can be used to model a conditional path. A choice node divides a transition into multiple parts.

Usually the first transition points towards the choice node. One of the choice's outgoing transitions can carry a condition.

###. FIXME: An example and more explanation is needed here.


h3(#synchronization). Synchronization

Synchronization is a means to either split a flow into several parallel regions of a substate or to join several parallel flows from orthogonal regions into a single flow. The synchronization state corresponds to the UML's concepts of fork and join.

Whether a synchronization state behaves as a fork or as a join depends on its usage.

* A synchronization with a single incoming transition and several outgoing ones _forks_ the flow into several regions of the same substate. These regions are executed in parallel, see section "&quot;Orthogonal states&quot;":#orthogonal-states.
* A synchronization with several incoming transitions from parallel regions of the same substate and a single outgoing transition _joins_ the incoming flows into a single flow of execution.

A synchronization state is shown as a thick horizontal or vertical line, as can be seen in figure "&quot;Synchronization state&quot;":#fig_state_synchronization.

p(#fig_state_synchronization). 

!(standard-image)images/docu_state_synchronization.png(Synchronization state)!

p=. Synchronization state

For a synchronization to actually join the incoming transitions and execute the outgoing one, all of the following conditions must be met:

* All source states must be active.
* All guard conditions that are specified must be fulfilled.
* If one or more triggers are defined, at least one trigger must fire at a point in time while the conditions above are met.

Figure "&quot;Synchronization state&quot;":#fig_state_synchronization shows a sample statechart containing a forking and a joining synchronization. After having left the *Initialize* state, the synchronization state forks the execution flow into two regions _r1_ and _r2_. Both are part of the *Process* composite state and both are executed virtually concurrently. That is, when activating *Process*, the substates *Line A 1* and *Line B 1* also become active. When the flows continues and both *Line A 2* and *Line B 2* have been reached, the synchronization state on the right-hand side joins the flows and transitions to substates *Cleanup*, making it the active state. However, as long as only one of *Line A 2* and *Line B 2* is active, the synchronization will wait for the other one to also become active, before proceeding to *Process*.

The example also demonstrates different lengths and orientations of the synchronization symbol. In the statechart editor, first select the synchronization symbol, then use a handle in one of the symbol's corners to change length or orientation. The handles in the middle of the symbol have no effect.


h3(#composite-state). Composite state

A composite state is a "state":#state containing a "region":#region. All usual characteristics of regions apply - they can have entry states, exit states, and so on. "Transitions":#transition can connect inner states of composite states to states that are at the same hierarchical level as the composite state, or they can directly be sourced at the composite states. This is useful for constructs like "cancel", where the operation of a composite state should be able to be aborted every time, no matter the active substate.

See "entry state":#entry, "exit state":#exit, "final state":#final-state and "connecting entries and exits to transitions":#entry-and-exit-points for further information.


h3(#orthogonal-states). Orthogonal states

Orthogonal states are basically "composite states":#composite-state with more than one region. These regions are executed virtually concurrently. *Please note* the word _virtually_! YAKINDU SCT does _not_ guarantee in any way that orthogonal regions are really executed concurrently. At the time being, no code generator utilizes threads to achieve this. Orthogonal states should rather be understood as a manner to have two or more sub-statecharts working together, however, they are executed _one after the other other_ in every cycle, in a defined order: top to bottom, left to right. The same applies to multiple regions in the statechart itself. Consult section "raising and processing events":#raising-and-processing-an-event for further information on region priorities and their meanings for the statechart execution.

###. CHECK Are there still no code generators taking advantage of threads and executing regions in parallel?

The presumably most famous example for orthogonal states is the keyboard example:

!(standard-image)images/docu_orthogonalState_example.jpg(Orthogonal states)!

p=. Orthogonal states


h3(#shallow-history). Shallow history

The shallow history state is a pseudo state that is placed inside regions of composite states. It is used to remember the last active state inside a composite state. This makes it possible to jump back to the remembered state instead of starting at the inner initial state again. History states save the current state exactly when their containing region is left.

The following example, showing the answering of a questionaire, explains this:

!(standard-image)images/docu_shallowHistory01.jpg(Shallow history [1])!

p=. Shallow history &#91;1]

Particularly interesting in this statechart are the _checkProgress_ and _goon_ events. The _checkProgress_ event jumps back to the *init* state while assigning the current progress count to the variable _temp_. The event _goon_ jumps to the shallow history state that was placed inside the composite state.

!(standard-image)images/docu_shallowHistory02.jpg(Shallow history [2])!

p=. Shallow history &#91;2]

!(standard-image)images/docu_shallowHistory03.jpg(Shallow history [3])!

p=. Shallow history &#91;3]

When the _goon_ event is triggered, the most recent active state inside of the composite state *answeringQuestions* is activated again.


h3(#deep-history). Deep history

Deep history is similar to shallow history, but more complex. With a deep history the latest state of multiple nested states is remembered.



h2(#definition-section). Definition section

###. FIXME: This is very "dry" stuff! Examples are needed!

###. FIXME: Relation between definition section and the concept of code generation should be explained, since the statechart model is intrinsically independend of code generation. We should discuss whether to mention code generation at all here.

The _definition section_ is a text area. Per default, it is located to the left of the drawing area. You can move or resize it like other elements in the drawing area.

In the definition section you have to define entities you want to use in your statechart. This includes "variables":#variables, "events":#events, and "operations":#operations. Variables and events have to be defined in the scope of a named "interface":#interface-scope or an "internal interface":#internal-scope. Especially useful for larger parts of a statechart model is the possibility to use "namespaces":#namespace. All these elements are properly reflected in generated source code as much as the respective target language supports it.


h3(#scopes). Scopes

==<!-- Start stext_keyword_namespace -->==

h4(#namespace). Namespace

The statechart language allows to define unique namespaces. They can be used to qualify references to statechart elements.

bc. namespace trafficlights

==<!-- End stext_keyword_namespace -->==

==<!-- Start stext_keyword_interface -->==

h4(#interface-scope). Interface scope

Declarations in the interface scope are externally visible. They can be shared within the environment.

bc. 
interface NamedInterface:
  in event event1
  out event event3 : integer
  var variable1 : integer
  
Note: All elements defined in a named interface _must_ be referenced using that interface's name, such as @NamedInterface.event1@, @NamedInterface.event3@, or @NamedInterface.variable1@.

It is also possible to have a single unnamed interface, which is externally visible as well:

bc. 
interface:
  in event event1

It behaves exactly the same as a named interface.

==<!-- End stext_keyword_interface -->==

==<!-- Start stext_keyword_internal -->==

h4(#internal-scope). Internal scope

Definitions made in the internal scope are visible to the statechart only. It is not possible to access them from client code.

bc. internal:
  var localVariable1: integer
  event localEvent: integer
  operation localOperation (int1 : integer, int2 : integer): integer
  localEvent2 / raise NamedInterface.event3 :
  localOperation(valueof(localEvent) , NamedInterface.variable1)

==<!-- End stext_keyword_internal -->==


h3(#variables). Variables

Variables have to be defined in an "internal":#internal-scope or "external":#interface-scope interface. Variables in the internal scope are not visible to any client code outside of generated state machine code.

bc. var variable1: real

Variables that are defined in a named interface have to be referenced using the interface name, see section "&quot;Interfaces&quot;":#interface-scope.

Variables are always typed, see section "&quot;Types&quot;":#types.

Variables can be _readonly_ (constants):

bc. var readonly pi: real = 3.1415

Variables can be referenced by the environment.

bc. var external variable3: integer = 34

==<!-- End stext_keyword_var -->==


==<!-- Start stext_keyword_const -->==

h3(#constants). Constants

Variables can be immutable. For this special variable the keyword @const@ is used:

bc. const variable1: real

==<!-- End stext_keyword_const -->==


==<!-- Start stext_keyword_event -->==

h3(#events). Events

An _event_ is something of importance that happens at a certain point in time in the context of a state machine, for example a user pushes a button, a temperature sensor delivers a value, a period of time has passed, etc. An event can be of three basic types:

* Internal events are meant to be raised and processed by the state machine internally only.
* External events are defined in an "interface scope":#interface-scope and can be _incoming_ or _outgoing_. An external event is either raised by the environment and processed by the state machine or it is raised within the state machine and can be processed outside.

Events that are defined in a named interface need to be referenced using the interface's name, see section "&quot;Interfaces&quot;":#interface-scope.

Events can be processed in triggers, see section "&quot;Trigger specification&quot;":#event-specifications. In order to raise an event in the state machine, see section "&quot;Raising an event&quot;":#raising-an-event. For details on the processing of events see section "&quot;Raising and processing an event&quot;":#raising-and-processing-an-event.

h4(#incoming-and-outgoing-events). Incoming and outgoing events

An event in an interface scope has a _direction_. It is either incoming or outgoing.

bc. 
interface NamedInterface:
  in event event1
  out event event2
  
Events in the internal scope do not have a direction, because they do not leave the state machine.

bc. 
internal:
  event ev1


h4(#events-with-variables). Events with variables

An event can be typed and can carry a value:

bc. 
internal:
  event event1 : integer


An event can have a value assignment:

bc. 
internal:
  event event1: integer = 25


Read access to the value of an event is possible in the statechart using the @valueof()@ built-in method, see section "&quot;Built-in methods&quot;":#built-in-functions for details. Please note that reading an event's value is possible only when the event actually occurs, for example in a guard:

bc. event1 [valueof(event1) == 6]


An event parameter can be specified when raising an event, as in the following example:

bc. raise event1 : 3+3

Regarding the syntax of event raising, see section "&quot;Raising an event&quot;":#raising-an-event. Regarding the more complicated details of processing an event, see section "&quot;Raising and processing an event&quot;":#raising-and-processing-an-event.

==<!-- End stext_keyword_event -->==


==<!-- Start stext_keyword_operation -->==

h3(#operations). Operations

Operations can have none, one or multiple parameters. A parameter is declared with a name and a type. An operation may have a single return type similar to usual programming languages. Again, see section "&quot;Types&quot;":#types for details.

bc. operation myOperation (xValue: integer, yValue: integer): integer

==<!-- End stext_keyword_operation -->==



h2(#reactions). Reactions

Reactions are one of the most important features of YAKINDU SCT's statechart language. Basically everything that happens in a statechart happens in a reaction.

Reactions can be attached to states as well as transitions. While states can have as many reactions as you wish, transitions can only have one.

The syntax follows the standards of automata theory, where the output is put into relation to the input of the automaton using the following notation (especially Mealy automata):  @input / output@

YAKINDU SCT uses the following syntax for all reactions:

bc. Trigger [Guard] / Effect

The possible values for the trigger depend on the context, either a state or a transition.

All three components are grammatically optional, though a reaction with neither a trigger nor a guard will never happen. Reactions with no effect are useful for transitions, the slash @/@ can be omitted as well then.

h3(#event-specifications). Trigger specifications

Reactions can define a _trigger_ that needs to happen to activate the reaction. "Events":#events are possible triggers, as well as certain keywords defined in the statechart language.

Triggers can be combined with "_guards_":#guard-condition to further define the execution conditions of the reaction. In that case, the reaction is only executed when both the trigger fires and the guard is true.

You can define multiple triggers for the reaction: @trigger1, trigger2@. When at least one of them occurs, the reaction's trigger fires.

The special triggers defined by the statechart language are the following:
* "@after@: execute after given time":#reaction-trigger-after 
* "@every@: execute periodically after given time":#reaction-trigger-every
* "@always@: execute always":#reaction-trigger-always
* "@oncycle@: same as @always@":#reaction-trigger-oncycle
* "@else@: useful for choice states":#reaction-trigger-else
* "@default@: same as @else@":#reaction-trigger-default
* "@entry@: execute on state entry":#reaction-trigger-entry
* "@exit@: execute on state exit":#reaction-trigger-exit

Examples:

* A reaction shall occur when an event named @ev1@ happens: @ev1 / effect@
* A reaction shall occur when @ev1@ or @ev2@ happen: @ev1, ev2 / effect@
* A reaction shall occur when @ev1@ happened or three seconds passed: @ev1, after 3s / effect@

p. 

Figure "&quot;Event specifications syntax overview&quot;":#fig_transition-syntax-overview shows where to put event specifications in a reaction trigger and how their syntax is defined.

p(#fig_event-specifications-syntax-overview). 
!(standard-image)images/docu_grammar_030_event-specification-overview.png(Event specifications syntax overview)!

p=. Event specifications syntax overview

==<!-- Start stext_keyword_after -->==

h4(#reaction-trigger-after). Reaction trigger "after"

The _after_ trigger specifies a one-shot time event.

After the specified time the reaction is triggered. An _after_ trigger can be used in transitions of states as well as in local reactions of states and statecharts. The specified time starts when the state or statechart is entered.

bc. after 20 s

Synopsis: @after@ _time_ _unit_


The _time_ value is a integer literal or an expression with an integer value.

The time _unit_ is one of:

* ==<!-- Start stext_keyword_s -->== @s@: seconds ==<!-- End stext_keyword_s -->==
* ==<!-- Start stext_keyword_ms -->==@ms@: milliseconds ==<!-- End stext_keyword_ms -->==
* ==<!-- Start stext_keyword_us -->==@us@: microseconds ==<!-- End stext_keyword_us -->==
* ==<!-- Start stext_keyword_ns -->==@ns@: nanoseconds ==<!-- End stext_keyword_ns -->==

==<!-- End stext_keyword_after -->==
==<!-- Start stext_keyword_every -->==

h4(#reaction-trigger-every). Reaction trigger "every"

The _every_ trigger specifies periodic time events.

The reaction is triggered recurrently after each passing of the specified period of time. An _every_ trigger can be used in transitions as well as in local reactions of states and statecharts. The specified period of time starts when the state or statechart is entered and repeats periodically.

bc. every 200 ms


Synopsis: @every@ _time_ _unit_

The _time_ value is a integer literal or an expression with an integer value.

The time _unit_ is one of:

* @s@: seconds
* @ms@: milliseconds
* @us@: microseconds
* @ns@: nanoseconds

==<!-- End stext_keyword_every -->==
==<!-- Start stext_keyword_always -->==

h4(#reaction-trigger-always). Reaction trigger "always"

This trigger is always true and enables a reaction to be executed in every run-to-completion step (RTC). The _always_ trigger is equivalent to the _oncycle_ trigger.

==<!-- End stext_keyword_always -->==
==<!-- Start stext_keyword_oncycle -->==

h4(#reaction-trigger-oncycle). Reaction trigger "oncycle"

This trigger is always true and enables a reaction to be executed in every run-to-completion step (RTC). The _always_ trigger is equivalent to the _oncycle_ trigger.

==<!-- End stext_keyword_oncycle -->==
==<!-- Start stext_keyword_else -->==

h4(#reaction-trigger-else). Reaction trigger "else"

This trigger is intended to be used for the outgoing transitions of _choice_ pseudo states to make sure that there is always an outgoing transition that can be taken. It can only be be used in transitions and implies the lowest evaluation priority for that transition. The _default_ trigger is equivalent to the _else_ trigger.

==<!-- End stext_keyword_else -->==
==<!-- Start stext_keyword_default -->==

h4(#reaction-trigger-default). Reaction trigger "default"

This trigger is intended to be used for the outgoing transitions of _choice_ pseudo states to make sure that there is always an outgoing transition that can be taken. It can only be be used in transitions and implies the lowest evaluation priority for that transition. The _default_ trigger is equivalent to the _else_ trigger.

==<!-- End stext_keyword_default -->==
==<!-- Start stext_keyword_entry -->==

h4(#reaction-trigger-entry). Reaction trigger "entry"

An _entry_ trigger marks actions that are carried out when entering a state or state machine, immediately _before_ making it active.

bq. *Please note:* A self-transition, leading from a state back to itself, actually first leaves and then re-enters the state. That means that its @exit@ effects as well as its @entry@ effects are executed. This is in contrast to a local reaction, which is executed without leaving the active state. Thus @exit@ and @entry@ effects are _not_ executed in the latter case.

==<!-- End stext_keyword_entry -->==
==<!-- Start stext_keyword_exit -->==

h4(#reaction-trigger-exit). Reaction trigger "exit"

An _exit_ trigger marks actions that are carried out when exiting a state or state machine, immediately _after_ making it inactive.

bq. *Please note:* A self-transition, leading from a state back to itself, actually first leaves and then re-enters the state. That means that its @exit@ effects as well as its @entry@ effects are executed. This is in contrast to a local reaction, which is executed without leaving the active state. Thus @exit@ and @entry@ effects are _not_ executed in the latter case.

==<!-- End stext_keyword_exit -->==

h3(#guard-condition). Guard condition

A _guard_ is another option to specify when a reaction should be executed. They can be used on their own or in conjunction with a specified "_trigger_":#event-specifications. In the latter case, the trigger needs to be fired _and_ the guard needs to be true for the reaction to fire its effect.

As a reminder, the complete reaction syntax is as follows:

bc. 
Trigger [Guard] / Effect

In the square brackets you can use any "expression":#expressions that evaluates to a boolean - boolean variables, all kinds of comparisons and operations that return a boolean fall into this category. Please note: YAKINDU SCT does not support the concept of "truthy and falsey" seen in C, Javascript or Python. 
@[x]@ is not a valid guard condition unless the type of x is boolean.

Please consult figure "&quot;Guard condition syntax overview&quot;":#fig_guard-condition-syntax-overview to find out how a guard condition syntactically fits into a reaction.

p(#fig_guard-condition-syntax-overview). 
!(standard-image)images/docu_grammar_030_guard-condition-overview.png(Guard condition syntax overview)!

p=. Guard condition syntax overview

h3(#reaction-effect). Reaction effect

A transition specification may contain zero, one or more _actions_ that are executed when the transition fires, like assigning a value to a variable, calling an operation, or raising an event. All actions taken together are called the transition's _reaction effect_. The complete syntax for reactions is as follows:

bc. 
Trigger [Guard] / Effect

This means that the effect will only be executed when the trigger fires or does not exist _and_ the guard condition evaluates to true or does not exist _and_ at least a trigger or a guard exist. See the sections about "triggers":#event-specifications and "guard conditions":#guard-condition.

Normally, actions are "statements":#statements. Note that you can also use the "conditional expression":#conditional-expression to make some constructs more elegant.

If an effect shall consist of multiple actions, they need to be _separated_ by a semicolon @;@. That means the last action is _not_ followed by a semicolon: @Trigger [Guard] / action1; action2; action3@

A reaction in a state always has a _reaction effect_ with at least one action.

Figure "&quot;Reaction effect syntax&quot;":#fig_reaction-effect-syntax shows the syntax definition.

p(#fig_reaction-effect-syntax). 
!(standard-image)images/docu_grammar_030_reaction-effect.png(Reaction effect syntax)!

p=. Reaction effect syntax

Example: When a transition or local reaction specified as @ev1 [x > 3] / x += 1; notify(x); raise ev2@ is executed, it increments variable _x_ by 1, calls the _notify_ operation with _x_ as parameter, and raises event _ev2_.

h4(#raising-and-processing-an-event). Raising and processing an event

For the syntax of event raising, see "Raising an event":#raising-an-event.
For the syntax of event declaration, see "Events":#events.

When a reaction raises an event, please consider two important points:
* The event exists in the current run-to-completion step (RTC) only and thus can be dealt with during the rest of that particular RTC only.
* Orthogonal regions are executed sequentially and in a deterministic order.

This has remarkable consequences on where an event is "visible" and where it is not. Let's say we have a state machine at a certain point in time where _n_ orthogonal regions are active. The regions _r<sub>i</sub>_ have a defined execution order: _r<sub>1</sub>_ → _r<sub>2</sub>_ → … → _r<sub>n-1</sub>_ → _r<sub>n</sub>_.

If an event _e_ is raised in region _r<sub>m</sub>_, then _e_ is available only in those regions that have not been processed yet, i.&nbsp;e. in _r<sub>i</sub>_ where _i_ > _m_ and _i_ ≤ _n_.

 The following example illustrates this. When the state machine is started, the situation is as shown in figure "&quot;Raising an event &#91;1]&quot;":#fig_raising-an-event_1: *A* and *X* in the parallel regions _r1_ and _r2_ are active states. Important: Region _r1_ is executed *before* _r2_.

p(#fig_raising-an-event_1). 
!(standard-image)images/docu_transition_010_raise_event_01.png(Raising an event [1])!

p=. Raising an event &#91;1]

Now event _e1_ occurs. It triggers transition *A → B* in _r1_. This transition's effect @raise e2@ causes event _e2_ to be raised. This event triggers transition *X → Y* in _r2_ to fire _within the same RTC_.

After that the situation is now as can be seen in figure "&quot;Raising an event &#91;2]&quot;":#fig_raising-an-event_2: substates *B* and *Y* are now active states. However, the transition *B → C* will not be taken, because that would have to happen in another RTC. But by then the particular _e2_ instance raised by *A → B* will be long gone, since it was restricted to the RTC it has been raised in.

p(#fig_raising-an-event_2). 
!(standard-image)images/docu_transition_010_raise_event_02.png(Raising an event [2])!

p=. Raising an event &#91;2]

Orthogonal regions within a state are always executed from left to right or from top to bottom, respectively. On the top level, where orthogonal regions can be graphically arranged at will, the execution order is defined by the statechart model's property _region priority_. To inspect or change it, open the _Properties_ view and select the statechart's definition section.

The region priorities of the example above are shown in figure "&quot;Region priorities&quot;":#fig_region-priorities. Change the execution order and the example will behave differently than described.

p(#fig_region-priorities). 
!(standard-image)images/docu_regions_010_priorities_01.png(Region priorities)!

p=. Region priorities

Not being able to raise an event and process it in "earlier" regions is a restriction you can overcome using variables. The idea is to set a "communication variable" to a certain value in a region that is processed "later". During the next RTC the earlier region could act on the variables value.

h2(#types). Types

The language has a small integrated type system consisting of the following simple types:

* integer
* real
* boolean
* string
* void

h2(#statements). Statements

A statement is one of three kinds:

* assignment
* event raising
* operation call

h3(#assignments). Assignments

The language has the following assignment operators:

<table><tbody><tr class="odd"><td align="left">simple assignment</td><td align="left">@=@</td></tr><tr class="even"><td align="left">multiply and assign</td><td align="left">@*=@</td></tr><tr class="odd"><td align="left">divide and assign</td><td align="left">@/=@</td></tr><tr class="even"><td align="left">calculate modulo and assign</td><td align="left">@%=@</td></tr><tr class="odd"><td align="left">add and assign</td><td align="left">@+=@</td></tr><tr class="even"><td align="left">subtract and assign</td><td align="left">@-=@</td></tr><tr class="odd"><td align="left">bitshift left and assign</td><td align="left">@<<=@</td></tr><tr class="even"><td align="left">bitshift right and assign</td><td align="left">@>>=@</td></tr><tr class="odd"><td align="left">bitwise AND and assign</td><td align="left">@&=@</td></tr><tr class="even"><td align="left">bitwise XOR and assign</td><td align="left">@^=@</td></tr><tr class="odd"><td align="left">bitwise OR and assign</td><td align="left">@|=@</td></tr></tbody></table>

h3(#raising-an-event). Raising an event

An event is raised by using the keyword @raise@, followed by the event name, e. g. @raise Incoming_call@. If the event is an interface event, the name of the interface must also be prepended as usual.

Example:

bc. 
interface intrfc:
  out event ev
  
Usage in the statechart:

bc. 
always / raise intrfc.ev

See also "Declaring events":#events and "Processing events":#raising-and-processing-an-event.

h3(#calling-an-operation). Calling an operation

An operation is called similar to other programming languages with the operation name and passing concrete parameters. The parameters can be expressions. The parenthesis can be omitted when no parameters are needed.

###. FIXME: Add an example!

h2(#expressions). Expressions

Expressions in YAKINDU Statechart Tools are similar to expressions in other programming languages. The language provides operators for logical expressions, number arithmetic, bitwise arithmetic, and bit shifting.

The type of a logical expression is *boolean*.

h3(#Logical-and). Logical AND

bc. expr1 && expr2


h3(#Logical-or). Logical OR

bc. expr1 ||  expr2


h3(#Logical-not). Logical NOT

bc. !expr1


h3(#conditional-expression). Conditional expression

bc. expr1 ? expr2 : expr3

When @expr1@ evaluates to true, this returns @expr2@, else @exp3@. This can be used to assign values to variables: 

bc. 
y = x > 5 ? 1 : 2

This does the same as the following snippet of C code:

bc. 
if(x > 5) {
  y = 1;
} else {
  y = 2;
}


h3(#bitwise-xor). Bitwise XOR

bc. expr1 ^ expr2


h3(#bitwise-or). Bitwise OR

bc. expr1 | expr2


h3(#bitwise-and). Bitwise AND

bc. expr1 & expr2


h3(#logical-relations-and-shift-operators). Logical Relations and Shift Operators

|<. less than|<. @<@|
|<. equal or less than|<. @<=@|
|<. greater than|<. @>@|
|<. equal or greater than|<. @>=@|
|<. equal|<. @==@|
|<. not equal|<. @!=@|
|<. shift left|<. @<<@|
|<. shift right|<. @>>@|

h3(#binary-arithmetic-operators). Binary arithmetic operators

|<. plus|<. @+@|
|<. minus|<. @-@|
|<. multiply|<. @*@|
|<. divide|<. @/@|
|<. modulo|<. @%@|

h3(#unary-arithmetic-operators). Unary arithmetic operators

|<. positive|<. @+@|
|<. negative|<. @-@|
|<. complement|<. @~@|


h2(#built-in-functions). Built-in functions

==<!-- Start stext_keyword_valueof -->==

h3(#value-of-event). valueof(event)

An event can have a value. This function returns the value of the specified event.

###. FIXME: Specify what happens if the event does not have a value.

bc. myVar = valueof(myEvent)

==<!-- End stext_keyword_valueof -->==
==<!-- Start stext_keyword_as -->==

h3(#as). as

Casts a variable. The following example casts a literal from integer to real.

bc. myReal = 12 as real

==<!-- End stext_keyword_as -->==
==<!-- Start stext_keyword_active -->==

h3(#active-state). active(state)

Returns _true_ if the specified state is active and _false_ otherwise.

bc. myBool = active(StateA)

==<!-- End stext_keyword_ -->==


h2(#complete-statechart-language-grammar). Complete statechart language grammar

This section presents the complete grammar of the statechart language. If you are in doubt how to write down a transition specification, a variable declaration, or any other syntactical construct of the statechart language, this is your definite reference that clarifies all syntactical questions.

The grammar is visualized using "railroad diagrams":https://en.wikipedia.org/wiki/Syntax_diagram. Railroad diagrams are easy to read and comprise all syntactically valid language constructs. Figure "&quot;Railroad diagrams explained&quot;":#fig-railroad-diagrams-explained shows an example:

p(#fig-railroad-diagrams-explained). 

!(standard-image)images/docu_grammar_020_simpleelementreferenceexpression.png(Railroad diagrams explained)!

p=. Railroad diagrams explained

On the left-hand side you'll find the so-called "_non-terminal symbol_":https://en.wikipedia.org/wiki/Terminal_and_nonterminal_symbols (or _non-terminal_ for short) that is being defined by this particular diagram. Here the non-terminal is _SimpleElementReferenceExpression_. To find out what a _SimpleElementReferenceExpression_ is allowed to look like, follow the "railroad track" just like a train would do. At each junction, the train either keeps its direction or changes it by 45 degrees, but it cannot make sharp turns of 90 degrees or more.

On its way, the train passes several "stations". Each station represents a language element that is valid at this point. In our example, the first station is a rectangle with a grey background. The grey background denotes a non-terminal, and the word inside the rectangle is the non-terminal's name, here: _ID_. You will have to look up this particular non-terminal's railroad diagram to learn more about it. However, for simplicity and because their meanings are more or less obvious a few non-terminals are not refined further. Examples are _STRING_, _INT_, _BOOL_, or _ID_.

In a _SimpleElementReferenceExpression_, a valid ID – a name – is always the first element, e.&nbsp;g. @init42@. If the train turns right at the junction, it moves directly to the railroad diagram's exit. That means just an _ID_ like @init42@ is a valid _SimpleElementReferenceExpression_. Please note that when the train reaches the junction right before the exit, it cannot turn left, because trains don't move that way. That is, the train is unable to travel to the @(@ station from this direction.

The train can reach the @)@ from the opposite direction only. After having left the initial _ID_ station, the train can move to the left at the junction and then run a stretch touching only the @(@ and @)@ stations, in that order. These rectangles have a white background color, denoting a "_terminal symbol_":https://en.wikipedia.org/wiki/Terminal_and_nonterminal_symbols or _terminal_ for short. A terminal stands for itself; write it down as it is.

Following that rule, @init42()@ is a valid _SimpleElementReferenceExpression_. One or more _Expressions_ inside the paranthesis, separated by the @,@ terminal, are also valid. Example: @init42(foo, bar + 27)@.

bq.. *Please note:*

The railroad diagrams themselves are generated from a textual grammar representation established and maintained with "Xtext":https://eclipse.org/Xtext/. If you suspect the diagrams shown here are lagging behind the actual implementation, look for files with the @.xtext@ extension in the YAKINDU Statechart Tools source code distribution!

bq.. *Please also note:*

Not each and every construction that is syntactically allowed does make sense semantically. The statechart editor will flag such constructions as errors.

h3(#statechart-grammar). Statechart grammar

Figure "&quot;Statechart grammar&quot;":#fig-statechart-grammar shows the statechart grammar. It makes use of the "expressions grammar":#expressions-grammar.

p(#fig-statechart-grammar). 

!(standard-image)images/docu_grammar_010_stext.png(Statechart grammar)!

p=. Statechart grammar

h3(#expressions-grammar). Expressions grammar

Figure "&quot;Expressions grammar&quot;":#fig-expressions-grammar shows the expressions grammar. It is used by the "statechart grammar":#statechart-grammar.

p(#fig-expressions-grammar). 

!(standard-image)images/docu_grammar_010_expressions.png(Expressions grammar)!

p=. Expressions grammar
