Update to version 0.2.4.

- Experimental: the runner now maintains a stack of nodes visited and
  can climb the stack upon request to return to a previously visited node
- Tests for this new functionality have been added
- The package now exports `YarnProgram` and `YarnInstruction` protobufs

Author: weaversam8

examples/yarn2/return-metadata.csv

@@ -0,0 +1 @@
+id,node,lineNumber,tags

examples/yarn2/return.csv

@@ -0,0 +1,4 @@
+id,text,file,node,lineNumber
+line:/Users/sweaver/Git/YarnRunner-Python/examples/yarn2/return.yarn-Start-0,Here's an example of returning inline from a node.,/Users/sweaver/Git/YarnRunner-Python/examples/yarn2/return.yarn,Start,3
+line:/Users/sweaver/Git/YarnRunner-Python/examples/yarn2/return.yarn-Start-1,Here's the last line.,/Users/sweaver/Git/YarnRunner-Python/examples/yarn2/return.yarn,Start,7
+line:/Users/sweaver/Git/YarnRunner-Python/examples/yarn2/return.yarn-node2-2,Here's the inline node.,/Users/sweaver/Git/YarnRunner-Python/examples/yarn2/return.yarn,node2,12

examples/yarn2/return.yarn

@@ -0,0 +1,17 @@
+title: Start
+---
+Here's an example of returning inline from a node.
+
+<<jump node2>>
+
+Here's the last line.
+===
+title: node2
+---
+
+Here's the inline node.
+
+// This command isn't implemented in the runner, but only in this specific test.
+<<return>>
+
+===

examples/yarn2/return.yarnc

@@ -2,7 +2,7 @@
 
 [metadata]
 name = yarnrunner-python
-version = 0.2.3
+version = 0.2.4
 author = Sam Weaver
 author_email = sweaver@relaypro.com
 description = An unofficial Python interpreter for compiled Yarn Spinner programs.

setup.cfg

@@ -0,0 +1,27 @@
+import os
+from .context import YarnRunner
+
+compiled_yarn_f = open(os.path.join(os.path.dirname(
+    __file__), '../examples/yarn2/return.yarnc'), 'rb')
+names_csv_f = open(os.path.join(os.path.dirname(
+    __file__), '../examples/yarn2/return.csv'), 'r')
+
+runner = YarnRunner(compiled_yarn_f, names_csv_f, autostart=False)
+
+
+def return_command():
+    runner.climb_node_stack()
+
+
+runner.add_command_handler("return", return_command)
+
+
+def test_return():
+    runner.resume()
+    assert "Here's an example of returning inline from a node." == runner.get_line()
+    assert runner.has_line()
+    assert "Here's the inline node." == runner.get_line()
+    assert runner.has_line()
+    assert "Here's the last line." == runner.get_line()
+    assert not runner.has_line()
+    assert runner.finished

tests/test_return.py

@@ -1 +1,2 @@
 from .runner import YarnRunner
+from .yarn_spinner_pb2 import Program as YarnProgram, Instruction as YarnInstruction

yarnrunner_python/__init__.py

@@ -18,6 +18,7 @@ def __init__(self, compiled_yarn_f, names_csv_f, autostart=True, enable_tracing=
         self.visits = {key: 0 for key in self._compiled_yarn.nodes.keys()}
         self.variables = {}
         self.current_node = None
+        self._node_stack = []
         self._command_handlers = {}
         self._line_buffer = []
         self._option_buffer = []
@@ -146,6 +147,18 @@ def choose(self, index):
     def add_command_handler(self, command, fn):
         self._command_handlers[command] = fn
 
+    def climb_node_stack(self):
+        if len(self._node_stack) < 1:
+            raise Exception(
+                "climb_node_stack() was called with an empty node stack.")
+
+        previous_node, previous_pc = self._node_stack.pop()
+        self.current_node = previous_node
+        self._vm_instruction_stack = self._compiled_yarn.nodes[previous_node].instructions
+        self._program_counter = previous_pc
+        if not self.paused:
+            self.__process_instruction()
+
     ##### OpCode Implementations below here #####
 
     def __jump_to(self, instruction):
@@ -170,6 +183,7 @@ def __go_to_node(self, node_key):
             raise Exception(
                 f"{node_key} is not a valid node in this Yarn story.")
 
+        self._node_stack.append((self.current_node, self._program_counter))
         self.current_node = node_key
         self.visits[node_key] += 1
         self.__debug_log(