ruote 2.2.0 → 2.3.0

data/lib/ruote/exp/fe_cancel_process.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2011, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2005-2012, John Mettraux, jmettraux@gmail.com
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -49,13 +49,27 @@ module Ruote::Exp
   # If the goal is to cancel only a segment of a process instance, the
   # expression 'undo' (Ruote::Exp::UndoExpression) is better suited.
   #
+  # == 'terminate'
+  #
+  # Sometimes 'terminate' reads better than 'cancel_process'
+  #
+  #   Ruote.process_definition do
+  #     alice :task => 'do this'
+  #     terminate :if => '${no_need_for_bob}'
+  #     bob :task => 'do that'
+  #     charly :task => 'just do it'
+  #   end
+  #
   class CancelProcessExpression < FlowExpression
 
-    names :cancel_process, :terminate
+    names :cancel_process, :terminate, :kill_process
 
     def apply
 
-      @context.storage.put_msg('cancel_process', 'wfid' => h.fei['wfid'])
+      @context.storage.put_msg(
+        'cancel_process',
+        'wfid' => h.fei['wfid'],
+        'flavour' => name == 'kill_process' ? 'kill' : nil)
     end
 
     def reply(workitem)

data/lib/ruote/exp/fe_command.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2011, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2005-2012, John Mettraux, jmettraux@gmail.com
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -29,8 +29,8 @@ require 'ruote/exp/command'
 module Ruote::Exp
 
   #
-  # This class gathers the 'skip', 'back', 'jump', 'rewind', 'continue' and
-  # 'break' expressions which are used inside of the 'cursor' and 'repeat'
+  # This class gathers the 'skip', 'back', 'jump', 'rewind', 'continue', 'reset'
+  # and 'break' expressions which are used inside of the 'cursor' and 'repeat'
   # (loop) expressions.
   #
   # Look at the 'cursor' expression Ruote::Exp::Cursor for a discussion of
@@ -87,7 +87,11 @@ module Ruote::Exp
 
     include CommandMixin
 
-    names :skip, :back, :jump, :rewind, :continue, :break, :stop, :over
+    names :skip, :back, :jump, :rewind, :continue, :break, :stop, :over, :reset
+
+    # Used by FlowExpression when dealing with :on_error or :on_timeout
+    #
+    REGEXP = Regexp.new("^(#{expression_names.join('|')})( .+)?$")
 
     def apply
 

data/lib/ruote/exp/fe_concurrence.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2011, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2005-2012, John Mettraux, jmettraux@gmail.com
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -52,6 +52,48 @@ module Ruote::Exp
   # in that example, the concurrence will terminate as soon as 1 (count) of
   # the branches replies. The other branch will get cancelled.
   #
+  # :count and :wait_for may point to a negative integer, meaning "all but
+  # x".
+  #
+  #   concurrence :count => -2 do # all the branches replied but 2
+  #     # ...
+  #   end
+  #
+  # :count can be shortened to :c.
+  #
+  # === :wait_for
+  #
+  # This attribute accepts either an integer, either a list of tags.
+  #
+  # When used with the integer, it's equivalent to the :count attribute:
+  #
+  #   concurrence :wait_for => 1 do
+  #     # ...
+  #   end
+  #
+  # It waits for 1 branch to respond and then moves on (concurrence over).
+  #
+  # When used with a string (or an array), it extracts a list of tags and waits
+  # for the branches with those tags. Once all the tags have replied,
+  # the concurrence is over.
+  #
+  #   concurrence :wait_for => 'alpha, bravo' do
+  #     sequence :tag => 'alpha' do
+  #       # ...
+  #     end
+  #     sequence :tag => 'bravo' do
+  #       # ...
+  #     end
+  #     sequence :tag => 'charly' do
+  #       # ...
+  #     end
+  #   end
+  #
+  # This concurrence will be over when the branches alpha and bravo have
+  # replied. The charly branch may have replied or not, it doesn't matter.
+  #
+  # :wait_for can be shortened to :wf.
+  #
   # === :remaining
   #
   # As said for :count, the remaining branches get cancelled. By setting
@@ -63,6 +105,15 @@ module Ruote::Exp
   #     bravo
   #   end
   #
+  # :remaining can be shortened to :rem or :r.
+  #
+  # The default is 'cancel', where all the remaining branches are cancelled
+  # while the hand is given back to the main flow.
+  #
+  # There is a third setting, 'wait'. It behaves like 'cancel', but the
+  # concurrence waits for the cancelled children to reply. The workitems
+  # from cancelled branches are merged in as well.
+  #
   # === :merge
   #
   # By default, the workitems override each others. By default, the first
@@ -97,6 +148,8 @@ module Ruote::Exp
   #
   # makes sure that alpha's version of the workitem wins.
   #
+  # :merge can be shortened to :m.
+  #
   # === :merge_type
   #
   # ==== :override
@@ -141,8 +194,60 @@ module Ruote::Exp
   # This could prove useful for participant having to deal with multiple merge
   # strategy results.
   #
+  # ==== :union
+  #
+  # (Available from ruote 2.3.0)
+  #
+  # Will override atomic fields, concat arrays and merge hashes...
+  #
+  # The union of those two workitems
+  #
+  #   { 'a' => 0, 'b' => [ 'x', 'y' ], 'c' => { 'aa' => 'bb' }
+  #   { 'a' => 1, 'b' => [ 'y', 'z' ], 'c' => { 'cc' => 'dd' }
+  #
+  # will be
+  #
+  #   { 'a' => 1,
+  #     'b' => [ 'x', 'y', 'z' ],
+  #     'c' => { 'aa' => 'bb', 'cc' => 'dd' } }
+  #
+  # Warning: duplicates in arrays present _before_ the merge will be removed
+  # as well.
+  #
+  # ==== :concat
+  #
+  # (Available from ruote 2.3.0)
+  #
+  # Much like :union, but duplicates are not removed. Thus
+  #
+  #   { 'a' => 0, 'b' => [ 'x', 'y' ], 'c' => { 'aa' => 'bb' }
+  #   { 'a' => 1, 'b' => [ 'y', 'z' ], 'c' => { 'cc' => 'dd' }
+  #
+  # will be
+  #
+  #   { 'a' => 1,
+  #     'b' => [ 'x', 'y', 'y', 'z' ],
+  #     'c' => { 'aa' => 'bb', 'cc' => 'dd' } }
+  #
+  # ==== :deep
+  #
+  # (Available from ruote 2.3.0)
+  #
+  # Identical to :concat but hashes are merged with deep_merge (ActiveSupport
+  # flavour).
+  #
+  # ==== :ignore
   #
-  # === :over_if (and :over_unless)
+  # (Available from ruote 2.3.0)
+  #
+  # A very simple merge type, the workitems given back by the branches are
+  # simply discarded and the workitem as passed to the concurrence expression
+  # is used to reply to the parent expression (of the concurrence expression).
+  #
+  # :merge_type can be shortened to :mt.
+  #
+  #
+  # === :over_if (and :over_unless) attribute
   #
   # Like the :count attribute controls how many branches have to reply before
   # a concurrence ends, the :over attribute is used to specify a condition
@@ -166,30 +271,70 @@ module Ruote::Exp
 
     names :concurrence
 
+    COUNT_R = /^-?\d+$/
+
     def apply
 
-      h.ccount = attribute(:count).to_i rescue 0
-      h.ccount = nil if h.ccount < 1
+      return do_reply_to_parent(h.applied_workitem) if tree_children.empty?
+
+      #
+      # count and wait_for
+
+      count = (attribute(:count) || attribute(:c)).to_s
+      count = nil unless COUNT_R.match(count)
+
+      wf = count || attribute(:wait_for) || attribute(:wf)
+
+      if COUNT_R.match(wf.to_s)
+        h.ccount = wf.to_i
+      elsif wf
+        h.wait_for = Ruote.comma_split(wf)
+      end
 
-      h.cmerge = att(:merge, %w[ first last highest lowest ])
-      h.cmerge_type = att(:merge_type, %w[ override mix isolate stack ])
-      h.remaining = att(:remaining, %w[ cancel forget ])
+      #
+      # other attributes
+
+      h.cmerge = att(
+        [ :merge, :m ],
+        %w[ first last highest lowest ])
+      h.cmerge_type = att(
+        [ :merge_type, :mt ],
+        %w[ override mix isolate stack union ignore concat deep ])
+      h.remaining = att(
+        [ :remaining, :rem, :r ],
+        %w[ cancel forget wait ])
 
       h.workitems = (h.cmerge == 'first' || h.cmerge == 'last') ? [] : {}
 
       h.over = false
 
       apply_children
+
+      @context.storage.put_msg(
+        'reply', 'fei' => h.fei, 'workitem' => h.applied_workitem
+      ) if h.ccount == 0
+        #
+        # force an immediate reply
     end
 
     def reply(workitem)
 
+      workitem = Ruote.fulldup(workitem)
+        #
+        # since workitem field merging might happen, better to work on
+        # a copy of the workitem (so that history, coming afterwards,
+        # doesn't see a modified version of the workitem)
+
       if h.cmerge == 'first' || h.cmerge == 'last'
         h.workitems << workitem
       else
         h.workitems[workitem['fei']['expid']] = workitem
       end
 
+      if h.wait_for && tag = workitem['fields']['__left_tag__']
+        h.wait_for.delete(tag)
+      end
+
       over = h.over
       h.over = over || over?(workitem)
 
@@ -198,6 +343,10 @@ module Ruote::Exp
 
         reply_to_parent(nil)
 
+      elsif h.over && h.remaining == 'wait'
+
+        reply_to_parent(nil)
+
       elsif h.children.empty?
 
         do_unpersist || return
@@ -236,9 +385,13 @@ module Ruote::Exp
       over_unless = attribute(:over_unless, workitem)
 
       if over_if && Condition.true?(over_if)
+        workitem['winner'] = true
         true
       elsif over_unless && (not Condition.true?(over_unless))
+        workitem['winner'] = true
         true
+      elsif h.wait_for
+        h.wait_for.empty?
       else
         (h.workitems.size >= expected_count)
       end
@@ -246,30 +399,70 @@ module Ruote::Exp
 
     # How many branch replies are expected before the concurrence is over ?
     #
+    def expected_count
+
+      if h.ccount.nil?
+        count_list_size
+      elsif h.ccount >= 0
+        [ h.ccount, count_list_size ].min
+      else # all but 1, 2, ...
+        i = count_list_size + h.ccount
+        i < 1 ? 1 : i
+      end
+    end
+
     # (note : concurrent_iterator overrides it)
     #
-    def expected_count
+    def count_list_size
 
-      h.ccount ? [ h.ccount, tree_children.size ].min : tree_children.size
+      tree_children.size
     end
 
     def reply_to_parent(_workitem)
 
+      #
+      # remaining 'wait' case first
+
+      if h.remaining == 'wait'
+
+        if h.workitems.size >= count_list_size
+          #
+          # all children have replied
+
+          workitem = merge_all_workitems
+
+          do_unpersist && super(workitem, false)
+
+        elsif h.children_cancelled == nil
+          #
+          # the concurrence is over, let's cancel all children and then
+          # wait for them
+
+          h.children_cancelled = true
+          do_persist
+
+          h.children.each { |i| @context.storage.put_msg('cancel', 'fei' => i) }
+        end
+
+        return
+      end
+
+      #
+      # remaining 'forget' and 'cancel' cases
+
       workitem = merge_all_workitems
 
-      if h.ccount == nil || h.children.empty?
+      if h.children.empty?
 
         do_unpersist && super(workitem, false)
 
       elsif h.remaining == 'cancel'
 
-        if r = do_unpersist
+        if do_unpersist
 
           super(workitem, false)
 
-          h.children.each do |i|
-            @context.storage.put_msg('cancel', 'fei' => i) #unless replied?(i)
-          end
+          h.children.each { |i| @context.storage.put_msg('cancel', 'fei' => i) }
         end
 
       else # h.remaining == 'forget'
@@ -281,9 +474,13 @@ module Ruote::Exp
       end
     end
 
+    # Called by #reply_to_parent, returns the unique, merged, workitem that
+    # will be fed back to the parent expression.
+    #
     def merge_all_workitems
 
       return h.applied_workitem if h.workitems.size < 1
+      return h.applied_workitem if h.cmerge_type == 'ignore'
 
       wis = case h.cmerge
         when 'first'
@@ -294,11 +491,14 @@ module Ruote::Exp
           is = h.workitems.keys.sort.collect { |k| h.workitems[k] }
           h.cmerge == 'highest' ? is.reverse : is
       end
-      rwis = wis.reverse
 
-      wis.inject(nil) { |t, wi|
-        merge_workitems(rwis.index(wi), t, wi, h.cmerge_type)
-      }
+      as, bs = wis.partition { |wi| wi.delete('winner') }
+      wis = bs + as
+        #
+        # the 'winner' is the workitem that triggered successfully the
+        # :over_if or :over_unless, let's take him precedence in the merge...
+
+      merge_workitems(wis, h.cmerge_type)
     end
   end
 end

data/lib/ruote/exp/fe_concurrent_iterator.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2011, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2005-2012, John Mettraux, jmettraux@gmail.com
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -64,6 +64,43 @@ module Ruote::Exp
   # rewind/break/jump/... like 'iterator' does, since it fires all its
   # branches when applied.
   #
+  # == :on and arrays
+  #
+  # Given a workitem field named 'x' containing the array value
+  # [ 'a', 'b', 'c' ] and a workitem field 'y' containing the string 'a, b, c',
+  # this:
+  #
+  #   concurrent_iterator :on_field => 'x', :to_f => 'xx' do
+  #     # ...
+  #   end
+  #
+  # is equivalent to
+  #
+  #   concurrent_iterator :on => '$f:x', :to_f => 'xx' do
+  #     # ...
+  #   end
+  #
+  # is equivalent to
+  #
+  #   concurrent_iterator :on => '${f:y}', :to_f => 'xx' do
+  #     # ...
+  #   end
+  #
+  # == :to_field and :to_f, :to_var and :to_v, :to
+  #
+  # Those 4 lines are equivalent:
+  #
+  #     concurrent_iterator :on => [ 'ceo', 'cto' ], :to_field => 'a' do ...
+  #     concurrent_iterator :on => [ 'ceo', 'cto' ], :to_f => 'a' do ...
+  #     concurrent_iterator :on => [ 'ceo', 'cto' ], :to => 'f:a' do ...
+  #     concurrent_iterator :on => [ 'ceo', 'cto' ], :to => 'a' do ...
+  #
+  # Those 3 lines are equivalent:
+  #
+  #     concurrent_iterator :on => [ 'ceo', 'cto' ], :to_var => 'a' do ...
+  #     concurrent_iterator :on => [ 'ceo', 'cto' ], :to_v => 'a' do ...
+  #     concurrent_iterator :on => [ 'ceo', 'cto' ], :to => 'v:a' do ...
+  #
   # == :times and :branches
   #
   # Similarly to the iterator expression, the :times or the :branches attribute
@@ -86,6 +123,28 @@ module Ruote::Exp
   #   end
   #
   #
+  # == ruote 2.3.0 and the citerator children
+  #
+  # Prior to ruote 2.3.0, the concurrent-iterator only considered one child
+  # expression:
+  #
+  #   concurrent_iterator :times => 3 do
+  #     participant 'al'
+  #     participant 'bob' # 'bob' would never be reached
+  #   end
+  #
+  # So one had to write:
+  #
+  #   concurrent_iterator :times => 3 do
+  #     sequence do
+  #       participant 'al'
+  #       participant 'bob' # 'bob' would never be reached
+  #     end
+  #   end
+  #
+  # Ruote 2.3.0 lifts that restriction.
+  #
+  #
   # == options
   #
   # the concurrent_iterator accepts the same options for merging as its bigger
@@ -145,7 +204,7 @@ module Ruote::Exp
 
         count = (list.first.to_i rescue nil)
 
-        list = (h.list_size + 1..h.list_size + count) if count
+        list = (h.list_size + 0...h.list_size + count) if count
       end
 
       list.each do |val|
@@ -153,7 +212,6 @@ module Ruote::Exp
         h.list_size += 1
 
         workitem = Ruote.fulldup(h.applied_workitem)
-        #workitem = Rufus::Json.dup(h.applied_workitem)
 
         variables = { 'ii' => h.list_size - 1 }
 
@@ -163,11 +221,14 @@ module Ruote::Exp
           workitem['fields'][h.to_f] = val
         end
 
+        expid, subtree = if tree_children.size > 1
+          [ h.fei['expid'], [ 'sequence', {}, tree_children ] ]
+        else
+          [ "#{h.fei['expid']}_0", tree_children[0] ]
+        end
+
         launch_sub(
-          "#{h.fei['expid']}_0",
-          tree_children[0],
-          :workitem => workitem,
-          :variables => variables)
+          expid, subtree, :workitem => workitem, :variables => variables)
       end
     end
 
@@ -199,7 +260,7 @@ module Ruote::Exp
       return reply_to_parent(h.applied_workitem) if list.empty?
 
       h.to_v, h.to_f = determine_tos
-      h.to_v = 'i' if h.to_v.nil? && h.to_f.nil?
+      h.to_v = 'i' unless h.to_v or h.to_f
 
       h.list_size = 0
 
@@ -210,9 +271,9 @@ module Ruote::Exp
 
     # Overrides the implementation found in ConcurrenceExpression
     #
-    def expected_count
+    def count_list_size
 
-      h.ccount ? [ h.ccount, h.list_size ].min : h.list_size
+      h.list_size
     end
   end
 end