subplot.md: Document the type map a little

Signed-off-by: Daniel Silverstone <dsilvers@digital-scurf.org>

1 files changed, 23 insertions, 2 deletions

diff --git a/subplot.md b/subplot.md
index 7c0054a..8f90a88 100644
--- a/subplot.md
+++ b/subplot.md
@@ -408,6 +408,8 @@ expresssions ([PCRE][]).
   function: create_standard_setup
 - when: "{thing} happens"
   function: make_thing_happen
+  types:
+    thing: word
 - when: "I say (?P<sentence>.+) with a smile"
   regex: true
   function: speak
@@ -438,7 +440,9 @@ consisting of printable characters. This can be varied by adding a
 suffix, such as `{name:text}` which matches any text. The following
 kinds of simple patterns are supported:
 
-* `{name}` or `{name:word}` &ndash; a single word
+* `{name}` or `{name:word}` &ndash; a single word. As a special case, the
+  form `{name:file}` is also supported.  It is also a single word, but has the
+  added constraint that it must match an embedded file's name.
 * `{name:text}` &ndash; any text
 * `{name:int}` &ndash; any whole number, including negative
 * `{name:uint}` &ndash; any unsigned whole number
@@ -463,6 +467,23 @@ as arguments, when it's called.
 [PCRE]: https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions
 [regex]: https://crates.io/crates/regex
 
+## The type map
+
+Patterns may also contain a type map.  This is a dictionary called `types`
+and contains a key-value mapping from capture name to the type of the capture.
+Valid types are listed above in the simple patterns section.  In addition to
+simple patterns, the type map can be used for regular expression bindings as
+well.
+
+When using simple patterns, if the capture is given a type in the type map, and
+also in the pattern, then the types must match, otherwise subplot will refuse to
+load the binding.
+
+Typically the type map is used by the code generators to, for example, distinguish
+between `"12"` and `12` (i.e. between a string and what should be a number). This
+permits the generated test suites to use native language types directly.  The
+`file` type, if used, must refer to an embedded file in the document; sp-docgen
+will emit a warning if the file is not found, and sp-codegen will emit an error.
 
 ## Functions file
 
@@ -1084,7 +1105,7 @@ def tmpdir_is_set(ctx):
 
 A scenario step binding can capture parts of a scenario step, to be
 passed to the function implementing the step as an argument. Captures
-can be done using regular expressions.
+can be done using regular expressions or "simple patterns".
 
 ### Capture using simple patterns