fe_cursor.rb in ruote-2.1.11

- old
+ new

@@ -64,22 +64,24 @@
   #     reviewer
   #     rewind :if => '${f:not_ok}'
   #     publisher
   #   end
   #
-  # === break
+  # === stop, over & break
   #
   # Exits the cursor.
   #
   #   cursor do
   #     author
   #     reviewer
   #     rewind :if => '${f:review} == fix'
-  #     _break :if => '${f:review} == abort'
+  #     stop :if => '${f:review} == abort'
   #     publisher
   #   end
   #
+  # '_break' or 'over' can be used instead of 'stop'.
+  #
   # === skip & back
   #
   # Those two commands jump forth and back respectively. By default, they
   # skip 1 child, but they accept a numeric parameter holding the number
   # of children to skip.
@@ -157,10 +159,48 @@
   #
   # this example features two nested cursors. There is a "_break" in the inner
   # cursor, but it will break the main 'cursor' (and thus break the whole
   # review process).
   #
+  # == cursor command in the workitem
+  #
+  # The command expressions are merely setting the workitem field '__command__'
+  # with an array value [ {command}, {arg} ].
+  #
+  # For example,
+  #
+  #   jump :to => 'author'
+  #     # is equivalent to
+  #   set 'field:__command__' => 'author'
+  #
+  # It is entirely OK to have a participant implementation that sets __command__
+  # by itself.
+  #
+  #   class Reviewer
+  #     include Ruote::LocalParticipant
+  #
+  #     def consume (workitem)
+  #       # somehow review the book
+  #       if review == 'bad'
+  #         #workitem.fields['__command__'] = [ 'rewind' ] # old style
+  #         workitem.command = 'rewind' # new style
+  #       else
+  #         # let it go
+  #       end
+  #       reply_to_engine(workitem)
+  #     end
+  #
+  #     def cancel (fei, flavour)
+  #       # cancel if review is still going on...
+  #     end
+  #   end
+  #
+  # This example uses the Ruote::Workitem#command= method which can be fed
+  # strings like 'rewind', 'skip 2', 'jump to author' or the equivalent arrays
+  # [ 'rewind' ], [ 'skip', 2 ], [ 'jump', 'author' ].
+  #
+  #
   # == :break_if / :rewind_if
   #
   # As an attribute of the cursor/repeat expression, you can set a :break_if.
   # It tells the cursor (loop) if it has to break.
   #
@@ -206,10 +246,12 @@
       move_on
     end
 
     protected
 
+    # Determines which child expression of the cursor is to be applied next.
+    #
     def move_on (workitem=h.applied_workitem)
 
       position = workitem['fei'] == h.fei ?
         -1 : Ruote::FlowExpressionId.child_id(workitem['fei'])
 
@@ -232,10 +274,12 @@
       else
         reply_to_parent(workitem)
       end
     end
 
+    # Will return true if this instance is about a 'loop' or a 'repeat'.
+    #
     def is_loop?
 
       name == 'loop' || name == 'repeat'
     end
 
@@ -252,11 +296,11 @@
 
         exp_name = c[0]
         ref = c[1]['ref']
         tag = c[1]['tag']
 
-        ref = Ruote.dosub(ref, self, workitem) if ref
-        tag = Ruote.dosub(tag, self, workitem) if tag
+        ref = @context.dollar_sub.s(ref, self, workitem) if ref
+        tag = @context.dollar_sub.s(tag, self, workitem) if tag
 
         next if exp_name != arg && ref != arg && tag != arg
 
         pos = i
         break