ruote 2.2.0 → 2.3.0

data/lib/ruote/exp/fe_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
@@ -48,7 +48,8 @@ module Ruote::Exp
   # it should iterate.
   #
   # The 'to' attribute takes two forms, :to_v, :to_var, :to_variable or
-  # :to_f, :to_fld, :to_field.
+  # :to_f, :to_fld, :to_field. Finally, you can write :to => 'field_name',
+  # :to => 'f:field_name' or :to => 'v:variable_name'.
   #
   # The 'to' attribute instructs the iterator into which variable or field
   # it should place the current value (the value being iterated over).
@@ -62,7 +63,7 @@ module Ruote::Exp
   # The 'on' attribute can be replaced by a :time or a :branches attribute.
   #
   #   pdef = Ruote.process_definition :name => 'test' do
-  #     iterator :times => '3'
+  #     iterator :times => '3' do
   #       participant 'accounting'
   #     end
   #   end
@@ -77,10 +78,24 @@ module Ruote::Exp
   #     end
   #   end
   #
+  # === variables and scope
+  #
+  # Starting with ruote 2.3.0, the iterator doesn't create a new scope for
+  # its variables, it uses the current scope.
+  #
+  # The old behaviour can be obtained by setting :scope => true, as in:
+  #
+  #     iterator :on => [ 1, 2, 3 ], :to_v => 'x', :scope => true do
+  #       # ...
+  #     end
+  #
+  # A corollary: by default, the variables set by the iterator or within it
+  # stick in the current scope...
+  #
   #
   # == the classical case
   #
-  # Iterating over a workitem field :
+  # Iterating over a workitem field:
   #
   #   pdef = Ruote.process_definition :name => 'test' do
   #     iterator :on_field => 'customers', :to_f => 'customer'
@@ -88,6 +103,17 @@ module Ruote::Exp
   #     end
   #   end
   #
+  # It's equivalent to:
+  #
+  #   pdef = Ruote.process_definition :name => 'test' do
+  #     iterator :on => '$f:customers', :to_f => 'customer'
+  #       participant '${f:customer}'
+  #     end
+  #   end
+  #
+  # "$f:customers" yields the actual array, whereas "${f:customers}"
+  # yields the string representation of the array.
+  #
   #
   # == break/rewind/continue/skip/jump
   #
@@ -190,7 +216,7 @@ module Ruote::Exp
       h.to_v, h.to_f = determine_tos
       h.position = -1
 
-      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
 
       move_on
     end
@@ -199,34 +225,43 @@ module Ruote::Exp
 
     def move_on(workitem=h.applied_workitem)
 
-      h.position += 1
+      current_position = h.position
+      h.position = 0 if h.position == -1
 
-      com, arg = get_command(workitem)
+      child_id = workitem['fei'] == h.fei ?
+        0 : Ruote::FlowExpressionId.new(workitem['fei']).child_id + 1
 
-      return reply_to_parent(workitem) if com == 'break'
+      com, arg = get_command(workitem)
 
       case com
+
+        when 'break' then return reply_to_parent(workitem)
+
         when 'rewind', 'continue' then h.position = 0
-        when 'skip' then h.position += arg
+        when 'skip' then h.position += (arg + 1)
         when 'jump' then h.position = arg
+
+        else
+          h.position = h.position + 1 if child_id >= tree_children.size
       end
 
       h.position = h.list.length + h.position if h.position < 0
 
+      return apply_child(child_id, workitem) if h.position == current_position
+
       val = h.list[h.position]
 
       return reply_to_parent(workitem) if val == nil
 
-      (h.variables ||= {})['ii'] = h.position
+      set_variable('ii', h.position)
 
       if h.to_v
-        h.variables[h.to_v] = val
+        set_variable(h.to_v, val)
       else #if h.to_f
         workitem['fields'][h.to_f] = val
       end
 
       apply_child(0, workitem)
-        # persist is done in there
     end
   end
 end

data/lib/ruote/exp/fe_listen.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
@@ -88,6 +88,11 @@ module Ruote::Exp
   # and this copy is delivered to the expressions that are client to the
   # 'listen'.
   #
+  # :merge can be set to 'override' where the event's workitem fields are
+  # used or some value which isn't true or 'true', in which case the
+  # workitem fields of the 'listen' expression is used as is (as it was
+  # when the flow reached the 'listen' expression).
+  #
   # == :upon
   #
   # There are two kinds of main events in ruote, apply and reply. Thus,
@@ -118,6 +123,24 @@ module Ruote::Exp
   # * 'entering' 'phase_two'
   # * 'leaving' 'phase_two'
   #
+  # When listening to tags, absolute paths can be given.
+  #
+  #   concurrence do
+  #     sequence :tag => 'a' do
+  #       alpha
+  #       sequence :tag => 'b' do
+  #         bravo
+  #       end
+  #     end
+  #     sequence do
+  #       listen :to => 'a/b', :upon => 'entering'
+  #       charly
+  #     end
+  #    end
+  #   end
+  #
+  # Charly will be next when the flow is about to reach bravo.
+  #
   #
   # == :to and :on
   #
@@ -165,6 +188,35 @@ module Ruote::Exp
   # The documentation about the dollar notation and the one about common
   # attributes :if and :unless applies for the :where attribute.
   #
+  #
+  # == listen :to => :errors
+  #
+  # The listen expression can be made to listen to errors.
+  #
+  #   listen :to => errors do
+  #     participant 'supervisor_sms', :task => 'verify system'
+  #   end
+  #
+  # Whenever an error happens in the process with this listen stance,
+  # the listen will trigger.
+  #
+  # "listen :to => :errors" only works with errors in the same process instance
+  # (same wfid).
+  #
+  # "listen :to => :errors" doesn't trigger when the error is caught (via
+  # :on_error).
+  #
+  # === listen :to => :errors, :class => 'ArgumentError'
+  #
+  # One can restrict the listen to certain classes of errors.
+  # Passing a list of error classes separated by a comma is OK.
+  #
+  # === listen :to => :errors, :message => /x/
+  #
+  # One can restrict the error listening to errors matching a certain regex
+  # or equal to a certain string. The attribute is :message or :msg. The
+  # value is a String (strict equality) or a Regex (matching).
+  #
   class ListenExpression < FlowExpression
 
     names :listen, :receive, :intercept
@@ -176,9 +228,12 @@ module Ruote::Exp
 
     def apply
 
+      # gathering info
+
       h.to = attribute(:to) || attribute(:on)
 
       h.upon = UPONS[attribute(:upon) || 'apply']
+      h.upon = 'error_intercepted' if h.to == 'errors'
 
       h.lmerge = attribute(:merge).to_s
       h.lmerge = 'true' if h.lmerge == ''
@@ -186,19 +241,18 @@ module Ruote::Exp
       h.lwfid = attribute(:wfid).to_s
       h.lwfid = %w[ same current true ].include?(h.lwfid)
 
+      h.lwfid = true if h.to == 'errors'
+        # can only listen to errors in the same process instance
+
       persist_or_raise
 
-      condition = if h.upon == 'dispatch' || h.upon == 'receive'
-        { 'participant_name' => h.to }
-      else
-        { 'tag' => h.to }
-      end
+      # adding a new tracker
 
       @context.tracker.add_tracker(
         h.lwfid ? h.fei['wfid'] : nil,
         h.upon,
         Ruote.to_storage_id(h.fei),
-        condition,
+        determine_condition,
         { 'action' => 'reply',
           'fei' => h.fei,
           'workitem' => 'replace',
@@ -211,7 +265,7 @@ module Ruote::Exp
       # :where guard
 
       where = attribute(:where, workitem)
-      return if where && ( ! Condition.true?(where))
+      return if where && Condition.false?(where)
 
       #
       # green for trigger
@@ -225,10 +279,16 @@ module Ruote::Exp
       #else don't touch
       end
 
-      if tree_children.size > 0
+      if tree_children.any?
+
+        i, t = if tree_children.size == 1
+          [ "#{h.fei['expid']}_0", tree_children[0] ]
+        else
+          [ h.fei['expid'], [ 'sequence', {}, tree_children ] ]
+        end
+
+        launch_sub(i, t, :forget => true, :workitem => wi)
 
-        launch_sub(
-          "#{h.fei['expid']}_0", tree[2][0], :forget => true, :workitem => wi)
       else
 
         reply_to_parent(wi)
@@ -237,12 +297,37 @@ module Ruote::Exp
 
     protected
 
+    # Overriding the parent's #reply_to_parent to make sure the tracker is
+    # removed before (expression terminating, no need for it to track anything
+    # anymore).
+    #
     def reply_to_parent(workitem)
 
       @context.tracker.remove_tracker(h.fei)
 
       super(workitem)
     end
+
+    def determine_condition
+
+      if h.upon == 'dispatch' || h.upon == 'receive'
+
+        { 'participant_name' => h.to }
+
+      elsif h.upon == 'error_intercepted'
+
+        {
+          'class' => Ruote.comma_split(attribute(:class) || ''),
+          'message' => attribute(:message) || attribute(:msg)
+        }.delete_if { |k, v|
+          v == nil or v == []
+        }
+
+      else
+
+        { (h.to.match(/\//) ? 'full_tag' : 'tag') => h.to }
+      end
+    end
   end
 end
 

data/lib/ruote/exp/fe_lose.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
@@ -85,12 +85,29 @@ module Ruote::Exp
   # Probably produces definitions more compact than when using the 'lose'
   # expression.
   #
-  # == forget vs lose
+  #
+  # == multi lose
+  #
+  # Losing multiple children:
+  #
+  #   lose do
+  #     alice :task => 'take out garbage'
+  #     bob :task => 'clean living room'
+  #   end
+  #
+  # will trigger alice's and bob's tasks together. The lose expression will
+  # never reply, unless cancelled (in which case alice and bob task get
+  # cancelled as well).
+  #
+  #
+  # == forget vs lose vs flank
   #
   # forget : replies to parent expression immediately, is not cancellable
   # (not reachable).
   #
-  # lose : never replies to parent expression, is cancellable.
+  # lose : never replies to the parent expression, is cancellable.
+  #
+  # flank : immediately replies to the parent expression, is cancellable.
   #
   class LoseExpression < FlowExpression
 
@@ -98,7 +115,17 @@ module Ruote::Exp
 
     def apply
 
-      apply_child(0, h.applied_workitem)
+      tree_children.each_with_index do |t, index|
+
+        msg = pre_apply_child(index, Ruote.fulldup(h.applied_workitem), false)
+          # forget ? false
+
+        @context.storage.put_msg('apply', msg)
+      end
+
+      persist_or_raise
+
+      # no reply to the parent expression
     end
 
     def reply(workitem)

data/lib/ruote/exp/fe_noop.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

data/lib/ruote/exp/fe_on_error.rb

@@ -0,0 +1,109 @@
+#--
+# 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
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# Made in Japan.
+#++
+
+
+module Ruote::Exp
+
+  #
+  # Up until ruote 2.3.0, 'on_error' was only an attribute
+  #
+  #   sequence :on_error => 'error_handler' do
+  #     # ...
+  #   end
+  #
+  # This 'on_error' expression makes such definitions possible
+  #
+  #   sequence do
+  #     on_error /unknown participant/ => 'missing_participant'
+  #     on_error 'decommission'
+  #     # ...
+  #   end
+  #
+  # where errors containing 'unknown participant' in their messages are handled
+  # by the participant or subprocess named 'missing participant', while
+  # the rest of the errors is handled by the participant or the subprocess
+  # named 'decommission'.
+  #
+  # Speaking of subprocesses, this is also possible
+  #
+  #   sequence do
+  #
+  #     on_error /unknown participant/ do
+  #       admin :msg => 'there was an unknown participant'
+  #     end
+  #     on_error do
+  #       # decommissioning...
+  #     end
+  #
+  #     # ...
+  #   end
+  #
+  class OnErrorExpression < FlowExpression
+
+    names :on_error
+
+    def apply
+
+      regex = nil
+      handler = attribute_text
+
+      if handler == ''
+        regex = (attributes.keys - COMMON_ATT_KEYS).first
+        handler = attribute(regex)
+      end
+
+      if tree.last.size > 0
+        regex = handler
+        handler = [ 'sequence', {}, Ruote.fulldup(tree.last) ]
+      end
+
+      return reply_to_parent(h.applied_workitem) if regex.nil? && handler.nil?
+        # nothing to register, let's move on
+
+      par = parent
+      oe = par.h.on_error
+
+      if oe.is_a?(String) or Ruote.is_tree?(oe)
+        oe = [ nil, oe ]
+      end
+
+      oe = Array(par.h.on_error).compact
+      oe << [ regex, handler, fei.child_id ]
+
+      par.h.on_error = oe
+
+      if par.do_persist
+        reply_to_parent(h.applied_workitem) # success
+      else
+        apply # try again
+      end
+    end
+
+    def reply(workitem)
+
+      # never called
+    end
+  end
+end
+