put documentation into the doc/ folder: how to define Primitives with args

1 files changed, 59 insertions, 0 deletions

diff --git a/doc/primitives-with-arguments.md b/doc/primitives-with-arguments.md
new file mode 100644
index 0000000..1a2552b
--- /dev/null
+++ b/doc/primitives-with-arguments.md
@@ -0,0 +1,59 @@
+How to define Primitive objects for blocks with arguments
+=========================================================
+
+The tutorials in this document assume that the reader is able to
+add simple blocks without arguments to Turtle Art.  Please refer
+to the module documentation  of  ../TurtleArt/tabasics.py  for a
+tutorial on that.
+
+Example 1: Block with one Argument
+----------------------------------
+
+In this example,   we define the `Primitive` object  for a block
+that increases the pen color  by a numeric argument   that comes
+from another block. In Turtle Art, the block looks like this:
+
+     ,---.___,---------.
+    /                   |
+    | increment color |=
+    \                   |
+     `---.___,---------´
+
+When the block  is executed,   we want it to do the same  as the
+following statement:
+
+    Turtle.set_pen_color(plus(Turtle.get_pen_color(), ...))
+
+where `...` stands for the output of the block  connected to the
+right hand  dock  of  our block.   For arguments  not  known  in
+advance,   we need  to insert  a placeholder  in the form  of an
+`ArgSlot` object.  An `ArgSlot` object describes some properties
+of  the  argument  it  receives.   It  defines  the type  of the
+argument,  it knows whether the argument needs to be called  (if
+it is callable),  and it knows which callable  (if any)  it must
+wrap around the argument before consuming it.  (For more on slot
+wrappers,  please refer to the other examples below.)   For this
+example,  we can use the default values for the second and third
+property  (`True` and `None`,  respectively).   We only need  to
+state the first one, the argument type, explicitly:
+
+    prim_inc_color = Primitive(Turtle.set_pen_color,
+        arg_descs=[ConstantArg(Primitive(
+            Primitive.plus, return_type=TYPE_NUMBER,
+                arg_descs=[ConstantArg(Primitive(
+                    Turtle.get_pen_color, return_type=TYPE_NUMBER)),
+                    ArgSlot(TYPE_NUMBER)]))],
+        call_afterwards=self.after_uturn)
+
+    self.tw.lc.def_prim('inc_color', 0, prim_inc_color)
+
+Turtle Art  uses the same type system for argument types  as for
+the return types of Primitive objects. If a value block (such as
+the number block)   is attached  to  the right hand dock  of the
+'increment color' block,   then Turtle Art  matches the value of
+that block against the type requirement of the argument slot. If
+the attached block  has a Primitive object  (such as  the 'plus'
+block),   then that Primitive's return value  is matched against
+the required type. If Turtle Art doesn't know how to convert the
+attached value to the required type,  it shows the user an error
+message during execution.