Document "task"

Author: jmettraux

doc/procedures/readme.md

@@ -70,6 +70,7 @@
 * [schedule](schedule.md) - Schedules a function
 * [signal](signal.md) - Used in conjuction with "on".
 * [sleep](sleep.md) - Makes a branch of an execution sleep for a while.
+* [task](task.md) - Tasks a tasker with a task.
 * [trap](trap.md) - Watches the messages emitted in the execution and reacts when a message matches certain criteria.
 
 
@@ -152,7 +153,7 @@
   * [Flor::Pro::Slice](https://github.com/floraison/flor/blob/master/lib/flor/pcore/slice.rb) : [slice, index](slice.md)
   * [Flor::Pro::Stall](https://github.com/floraison/flor/blob/master/lib/flor/pcore/stall.rb) : [stall](stall.md)
   * [Flor::Pro::Strings](https://github.com/floraison/flor/blob/master/lib/flor/pcore/strings.rb) : downcase, lowercase, upcase, uppercase, capitalize
-  * [Flor::Pro::Task](https://github.com/floraison/flor/blob/master/lib/flor/punit/task.rb) : task
+  * [Flor::Pro::Task](https://github.com/floraison/flor/blob/master/lib/flor/punit/task.rb) : [task](task.md)
   * [Flor::Pro::TimeStamp](https://github.com/floraison/flor/blob/master/lib/flor/pcore/timestamp.rb) : [timestamp, ltimestamp](timestamp.md)
   * [Flor::Pro::ToArray](https://github.com/floraison/flor/blob/master/lib/flor/pcore/to_array.rb) : [to-array, to-object](to_array.md)
   * [Flor::Pro::Trace](https://github.com/floraison/flor/blob/master/lib/flor/punit/trace.rb) : trace

doc/procedures/task.md

@@ -0,0 +1,41 @@
+
+# task
+
+Tasks a tasker with a task.
+
+```
+task 'clean up' by: 'alan'
+task 'clean up' for: 'alan'
+task 'clean up' assign: 'alan'
+task 'alan' with: 'clean up'
+alan task: 'clean up'  # {tasker} task: {taskname}
+task 'alan'
+# ...
+```
+
+Note that the quotes are the tasker name can be omitted:
+```
+task 'clean up' by: alan
+task 'clean up' for: alan
+task 'clean up' assign: alan
+task alan with: 'clean up'
+alan task: 'clean up'  # {tasker} task: {taskname}
+task alan
+# ...
+```
+
+Tasking hands a task (a message hash serializable to JSON) to a tasker.
+See [tasks](../tasks.md) for more information.
+
+Since routing tasks among taskers is flor essential "task", this "task"
+procedure is very important.
+
+Note that "task" can be implicit, as in:
+```
+alan task: 'clean up'
+```
+
+
+* [source](https://github.com/floraison/flor/tree/master/lib/flor/punit/task.rb)
+* [task spec](https://github.com/floraison/flor/tree/master/spec/punit/task_spec.rb)
+

lib/flor/punit/task.rb

@@ -1,13 +1,37 @@
 
 class Flor::Pro::Task < Flor::Procedure
   #
-  # Tasks a tasker with a task. Argh.
+  # Tasks a tasker with a task.
   #
   # ```
   # task 'clean up' by: 'alan'
   # task 'clean up' for: 'alan'
   # task 'clean up' assign: 'alan'
   # task 'alan' with: 'clean up'
+  # alan task: 'clean up'  # {tasker} task: {taskname}
+  # task 'alan'
+  # # ...
+  # ```
+  #
+  # Note that the quotes are the tasker name can be omitted:
+  # ```
+  # task 'clean up' by: alan
+  # task 'clean up' for: alan
+  # task 'clean up' assign: alan
+  # task alan with: 'clean up'
+  # alan task: 'clean up'  # {tasker} task: {taskname}
+  # task alan
+  # # ...
+  # ```
+  #
+  # Tasking hands a task (a message hash serializable to JSON) to a tasker.
+  # See [tasks](../tasks.md) for more information.
+  #
+  # Since routing tasks among taskers is flor essential "task", this "task"
+  # procedure is very important.
+  #
+  # Note that "task" can be implicit, as in:
+  # ```
   # alan task: 'clean up'
   # ```
 

spec/punit/task_spec.rb

@@ -244,6 +244,7 @@
             task 'three' assign: 'alpha'
             task 'alpha' with: 'four'
             alpha task: 'five'
+            task 'alpha'
           },
           wait: true)
 
@@ -257,6 +258,7 @@
           [ 'alpha', 'three' ],
           [ 'alpha', 'four' ],
           [ 'alpha', 'five' ],
+          [ 'alpha', nil ],
         ])
       end
 
@@ -269,6 +271,7 @@
             task 'three' assign: alpha
             task alpha with: 'four'
             alpha task: 'five'
+            task alpha
           },
           wait: true)
 
@@ -282,6 +285,7 @@
           [ 'alpha', 'three' ],
           [ 'alpha', 'four' ],
           [ 'alpha', 'five' ],
+          [ 'alpha', nil ],
         ])
       end
     end