Add a Story.tell_by_step method

CHANGELOG.rst

@@ -12,7 +12,8 @@ The YAML format of a statechart also changed, look carefully at the changelog an
   ``transitions_with``, ``remove_transition`` and ``rotate_transition``.
 - (Added) Statechart: new methods to manipulate states: ``remove_state``, ``rename_state``, ``move_state``,
   ``state_for``, ``parent_for``, ``children_for``.
-- (Added) Steps: add ``__eq__`` on ``MacroStep`` and ``MicroStep``.
+- (Added) Steps: ``__eq__`` for ``MacroStep`` and ``MicroStep``.
+- (Added) Stories: ``tell_by_step`` method for a ``Story``.
 - (Added) Module: a new exceptions hierarchy (see ``exceptions`` module).
   The new exceptions are used in place of the old ones (``Warning``, ``AssertionError`` and ``ValueError``).
 - (Changed) YAML: uppermost *states:* should be replaced by *initial state:* and can contain at most one state.

docs/stories.rst

@@ -57,15 +57,33 @@ a scenario.
     assert isinstance(interpreter, Interpreter)
 
     story.tell(interpreter)
-    print(interpreter.time)
-    print(interpreter.context.get('current'))
+    print(interpreter.time, interpreter.context.get('current'))
 
 After having *told* the story to the interpreter, we observe that 15 seconds have passed, and the elevator has moved to the ground floor.
 
 .. testoutput::
 
-    15
-    0
+    15 0
+
+
+While telling a whole story at once can be convenient, it is sometimes interesting to tell the story step by step.
+The :py:meth:`~sismic.stories.Story.tell_by_step` returns a generator that yields the object (either a pause or an event)
+that was told to the interpreter, and the result of calling :py:meth:`~sismic.interpreter.Interpreter.execute`.
+
+.. testcode::
+
+    # Recreate the interpreter
+    interpreter = Interpreter(statechart)
+
+    for told, macrosteps in story.tell_by_step(interpreter):
+        print(interpreter.time, told, interpreter.context.get('current'))
+
+.. testoutput::
+
+    0 Event(floorSelected, floor=4) 4
+    5 Pause(5) 4
+    5 Event(floorSelected, floor=2) 2
+    15 Pause(10) 0
 
 
 Storywriters

sismic/stories.py

@@ -49,6 +49,24 @@ def tell(self, interpreter, *args, **kwargs):
             interpreter.execute(*args, **kwargs)
         return interpreter
 
+    def tell_by_step(self, interpreter, *args, **kwargs):
+        """
+        Tells the story to the interpreter, step by step.
+        This method returns a generator which yields the event or the pause that was told to the interpreter and
+        the result of *interpreter.execute*.
+
+        :param interpreter: an interpreter instance
+        :param args: additional positional arguments that are passed to *interpreter.execute*.
+        :param kwargs: additional keywords arguments that are passed to *interpreter.execute*.
+        :return: a generator that yields (told event or pause, result of *interpreter.execute*).
+        """
+        for item in self:
+            if isinstance(item, Event):
+                interpreter.queue(item)
+            elif isinstance(item, Pause):
+                interpreter.time += item.duration
+            yield item, interpreter.execute(*args, **kwargs)
+
     def __repr__(self):
         return 'Story({})'.format(super().__repr__())