doc: block with a slot wrapper

1 files changed, 36 insertions, 1 deletions

diff --git a/doc/primitives-with-arguments.md b/doc/primitives-with-arguments.md
index a65af0b..2237898 100644
--- a/doc/primitives-with-arguments.md
+++ b/doc/primitives-with-arguments.md
@@ -58,7 +58,42 @@ attached value to the required type,  it shows the user an error
 message during execution.
 
 
-# TODO slot wrappers
+Example 2: Block with a Slot Wrapper
+------------------------------------
+
+In Turtle Art,  moving the turtle backward by x  is the same  as
+moving it forward  by negative x (or -x).   In fact,  the 'back'
+block uses the same method  (`Turtle.forward`)  as the 'forward'
+block.   But the 'back' block  needs to switch  the sign  of its
+argument before passing it to `Turtle.forward`. I.e. it needs to
+execute the following statement:
+
+    Turtle.forward(minus(...))
+
+where `...` again  stands for the output of the block  connected
+to the right hand dock of the 'back' block.   This is where slot
+wrappers come in helpful.  A slot wrapper is a Primitive that is
+'wrapped around'  an argument  of its 'parent' Primitive.   Slot
+wrappers can only be attached to `ArgSlot` objects,  that is, to
+arguments that come from other blocks. In the case of the 'back'
+block, this looks as follows:
+
+    Primitive(Turtle.forward,
+        arg_descs=[ArgSlot(TYPE_NUMBER,
+            wrapper=Primitive(
+                Primitive.minus, return_type=TYPE_NUMBER,
+                    arg_descs=[ArgSlot(TYPE_NUMBER)]))],
+        call_afterwards=self.after_move))
+
+When the 'back' block is called,  it passes the argument that it
+gets from its right hand dock to the `ArgSlot` object.  That, in
+turn, passes it to its wrapper, and then matches the type of the
+return value of the wrapper against its type requirement. If the
+types match,  the wrapper's return value  is passed back  to the
+function of the main Primitive, `Turtle.forward`.
+
+Note  that  slot wrappers  and  Primitive objects  can be nested
+inside each other infinitely deeply.
 
 
 Example 3: Block with a Group of Primitives