A statechart can specify code that needs to be executed under some circumstances. For example, the preamble of a statechart, the guard or action of a transition or the on entry and on exit of a state may all contain code.
In Sismic, these pieces of code can be evaluated and executed by :py~sismic.code.Evaluator instances. By default, when an interpreter is created, a :py~sismic.code.PythonEvaluator is created and allows the interpreter to evaluate and execute Python code contained in a statechart.
Alternatively, a :py~sismic.code.DummyEvaluator that always evaluates conditions to True and silently ignores actions can be used, but is clearly of less interest.
In the following, we will implicitly assume that the code evaluator is an instance of :py~sismic.code.PythonEvaluator.
When a code evaluator is created or provided to an interpreter, all the variables that are defined or used by the statechart are stored in an execution context. This context is exposed through the context attribute of the interpreter and can be seen as a mapping between variable names and their values. When a piece of code contained in a statechart has to be evaluated or executed, the context of the evaluator is used to populate the local and global variables that are available for this piece of code.
As an example, consider the following partial statechart definition.
statechart:
# ...
preamble: |
x = 1
y = 0
root state:
name: s1
on entry: x += 1When an interpreter is created for this statechart, its preamble is executed and the context of the code evaluator is populated with {'x': 1, 'y': 0}. When the statechart is further executed (initialized), and its root state s1 is entered, the code x += 1 contained in the on entry field of s1 is then executed in this context. After execution, the context is {'x': 2, 'y': 0}.
The default code evaluator uses a global context, meaning that all variables that are defined in the statechart are exposed by the evaluator when a piece of code has to be evaluated or executed. The main limitation of this approach is that you cannot have distinct variables with a same name in different states or, in other words, there is only one scope for all your variables.
The preamble of a statechart can be used to provide default values for some variables. However, the preamble is part of the statechart and as such, cannot be used to parametrize the statechart. To circumvent this, an initial context can be specified when a :py~sismic.code.PythonEvaluator is created. For convenience, this initial context can also be passed to the constructor of an :py~sismic.interpreter.Interpreter.
Considered the following toy example:
initial_context
from sismic.io import import_from_yaml from sismic.interpreter import Interpreter
- yaml = """statechart:
name: example preamble: x = DEFAULT_X root state: name: s
"""
statechart = import_from_yaml(yaml)
Notice that variable DEFAULT_X is used in the preamble but not defined. The statechart expects this variable to be provided in the initial context, as illustrated next:
initial_context
interpreter = Interpreter(statechart, initial_context={'DEFAULT_X': 1})
We can check that the value of x is 1 by accessing the context attribute of the interpreter:
initial_context
assert interpreter.context['x'] == 1
Omitting to provide the DEFAULT_X variable in the initial context leads to an error, as an unknown variable is accessed by the preamble:
initial_context
- try:
Interpreter(statechart)
- except Exception as e:
print(e)
initial_context
"name 'DEFAULT_X' is not defined" occurred while executing "x = DEFAULT_X"
It could be tempting to define a default value for x in the preamble and overriding this value by providing an initial context where x is defined. However, the initial context of an interpreter is set before executing the preamble of a statechart. As a consequence, if a variable is defined both in the initial context and the preamble, its value will be overridden by the preamble.
Consider the following example where x is both defined in the initial context and the preamble:
initial_context
- yaml = """statechart:
name: example preamble: x = 1 root state: name: s
"""
statechart = import_from_yaml(yaml) interpreter = Interpreter(statechart, initial_context={'x': 2})
assert interpreter.context['x'] == 1
The value of x is eventually set to 1.
While the initial context provided to the interpreter defined the value of x to 2, the code contained in the preamble overrode its value. If you want to make use of the initial context to somehow parametrize the execution of the statechart while still providing default values for these parameters, you should either check the existence of the variables before setting their values or rely on the setdefault function that is exposed by the Python code evaluator when a piece of code is executed (not only in the preamble).
This function can be used to define (and return) a variable, very similarly to the setdefault method of a dictionary. Using this function, we can easily rewrite the preamble of our statechart to deal with the optional default values of x (and y and z in this example):
initial_context
- yaml = """statechart:
name: example preamble: | x = setdefault('x', 1) setdefault('y', 1) # Value is affected to y implicitly setdefault('z', 1) # Value is affected to z implicitly root state: name: s on entry: print(x, y, z)
"""
statechart = import_from_yaml(yaml) interpreter = Interpreter(statechart, initial_context={'x': 2, 'z': 3}) interpreter.execute()
initial_context
2 1 3
Warning
Under the hood, a Python evaluator makes use of eval() and exec() with global and local contexts. This can lead to some weird issues with variable scope (as in list comprehensions or lambda's). See this question on Stackoverflow for more information.
When a piece of code is evaluated or executed, the default Python code evaluator enriches its local context with several predefined variables and functions. These predefined objects depend on the situation triggering a code evaluation or a code execution (entry or exit actions, guard evaluation, transition action, ...).
These entries are covered in the docstring of a :py~sismic.code.PythonEvaluator:
sismic.code.PythonEvaluator
Note
This section explains which are the methods that are called during the execution or evaluation of a piece of code, and is mainly useful if you plan to write your own statechart code interpreter.
An :py~sismic.code.Evaluator subclass must at lest implement the following methods and attributes:
sismic.code.Evaluator._evaluate_code
sismic.code.Evaluator._execute_code
sismic.code.Evaluator.context
Note
None of those two methods are actually called by the interpreter during the execution of a statechart. These methods are fallback methods that are used by other methods that are implicitly called depending on what is currently being processed in the statechart. The documentation of :py~sismic.code.Evaluator covers this:
sismic.code.Evaluator