test: add scenario for testing value expansion

1 files changed, 61 insertions, 0 deletions

diff --git a/subplot.md b/subplot.md
index eccda67..eeb55f6 100644
--- a/subplot.md
+++ b/subplot.md
@@ -1221,6 +1221,67 @@ given I am Tomjon
 ~~~
 
 
+## Recall values for use in later steps
+
+It's sometimes useful to use a value remembered in a previous step.
+For example, if one step creates a resource with a random number as
+its name, a later step should be able to use it. This happens in
+enough projects that Subplot's Python template has support for it.
+
+The Python template has a `Context` class, with methods
+`remember_value`, `recall_value`, and `expand_values`. These values
+are distinct from the other values that can be stored in a context.
+Only explicitly remembered values may be recalled or expanded so that
+expansions don't accidentally refer to values meant for another
+purpose.
+
+~~~scenario
+given file values.md
+and file values.yaml
+and file values.py
+and an installed subplot
+when I run sp-codegen values.md -o test.py
+when I run python3 test.py
+then command is successful
+~~~
+
+~~~~~~{#values.md .file .markdown .numberLines}
+---
+title: Values
+bindings: values.yaml
+functions: values.py
+template: python
+...
+
+
+# Values
+
+~~~scenario
+when I remember foo as bar
+then expanded "${foo}" is bar
+~~~
+
+~~~~~~
+
+~~~{#values.yaml .file .yaml .numberLines}
+- when: I remember {name} as {value}
+  function: remember
+  
+- then: expanded "{actual}" is {expected}
+  function: check
+~~~
+
+~~~{#values.py .file .python .numberLines}
+def remember(ctx, name=None, value=None):
+	ctx.remember_value(name, value)
+
+def check(ctx, expected=None, actual=None):
+    assert_eq(ctx.expand_values(actual), expected)
+~~~
+
+
+
+
 ## Set environment variables in generated test programs
 
 The generated test programs run each scenario with a fixed, almost