ruote 2.1.11 → 2.2.0

data/lib/ruote/exp/fe_forget.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2010, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2005-2011, 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
@@ -59,6 +59,13 @@ module Ruote::Exp
   #
   # This expression can be useful for fire-and-forget parallelism in processes.
   #
+  # == forget vs lose
+  #
+  # forget : replies to parent expression immediately, is not cancellable
+  # (not reachable).
+  #
+  # lose : never replies to parent expression, is cancellable.
+  #
   class ForgetExpression < FlowExpression
 
     names :forget
@@ -72,7 +79,7 @@ module Ruote::Exp
       reply_to_parent(h.applied_workitem)
     end
 
-    def reply (workitem)
+    def reply(workitem)
 
       # never gets called
     end

data/lib/ruote/exp/fe_given.rb

@@ -0,0 +1,154 @@
+#--
+# Copyright (c) 2005-2011, 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.
+#++
+
+require 'ruote/exp/fe_sequence'
+
+
+module Ruote::Exp
+
+  #
+  # This expressions corresponds to a "case" statement in Ruby or a "switch"
+  # in other languages.
+  #
+  # It accepts two variants "given that" and "given an x of".
+  #
+  # 'given' works in conjunction with the 'that' / 'of' expression.
+  #
+  #
+  # == "given that"
+  #
+  #   given do
+  #     that "${location} == paris" do
+  #       subprocess "notify_and_wait_for_pickup"
+  #     end
+  #     that "${state} == ready" do
+  #       subprocess "deliver"
+  #     end
+  #     # else...
+  #     subprocess "do_something_else"
+  #   end
+  #
+  #
+  # == "given an x of"
+  #
+  #   given "${status}" do
+  #     of "ordered" do
+  #       participant "alpha"
+  #     end
+  #     of "delivered" do
+  #       participant "alpha"
+  #     end
+  #     # else...
+  #     subprocess "do_something_else"
+  #   end
+  #
+  # This variant also accepts regular expressions :
+  #
+  #   given "${target}" do
+  #     of "/-manager$/" do
+  #       # ...
+  #     end
+  #     of /^user-/ do
+  #       # ...
+  #     end
+  #   end
+  #
+  # == mixing 'that' and 'of'
+  #
+  # It's OK to use a "that" inside a "given an x" :
+  #
+  #   given '${target}' do
+  #     that "${location} == paris" do
+  #       subprocess "notify_and_wait_for_pickup"
+  #     end
+  #     of "home" do
+  #       subprocess "return_procedure"
+  #     end
+  #   end
+  #
+  #
+  # == the else part
+  #
+  # Anything that comes after the serie of 'that' and 'of' is considered in
+  # the 'else' zone and is executed if none of the 'that' or 'of' triggered.
+  #
+  #   given '${target}' do
+  #     that "${location} == paris" do
+  #       subprocess "notify_and_wait_for_pickup"
+  #     end
+  #     of "home" do
+  #       subprocess "return_procedure"
+  #     end
+  #     subprocess "do_this"
+  #     subprocess "and_then_that"
+  #   end
+  #
+  # Yes, two 'else' subprocesses will get executed one after the other (the
+  # 'given' acting like a 'sequence' for them.
+  #
+  # Interestingly :
+  #
+  #   given '${target}' do
+  #     of "home" do
+  #       subprocess "return_procedure"
+  #     end
+  #     subprocess "do_this"
+  #     of "office" do
+  #       subprocess "go_to_work"
+  #     end
+  #     subprocess "and_then_that"
+  #   end
+  #
+  # If the workitem field 'target' is set to 'home' only the 'return_procedure'
+  # subprocess will get called.
+  #
+  # If the workitem field 'target' is set to 'office', the 'do_this'
+  # subprocess, then the 'go_to_work' one will get called.
+  #
+  class GivenExpression < SequenceExpression
+
+    names :given
+
+    def reply(workitem)
+
+      if given = attribute(:t) || attribute_text
+        workitem['fields']['__given__'] = given
+      end
+
+      # as soon as one child says true, reply to the parent expression
+
+      if workitem['fields']['__result__'].to_s == 'true'
+
+        workitem['fields'].delete('__given__')
+        workitem['fields'].delete('__result__')
+        reply_to_parent(workitem)
+
+      else
+
+        super
+      end
+    end
+  end
+end
+

data/lib/ruote/exp/fe_if.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2010, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2005-2011, 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
@@ -61,7 +61,14 @@ module Ruote::Exp
   #
   # == shorter
   #
-  # It's ok to shortcircuit the _if expression like this :
+  # The :test can be shortened to a :t :
+  #
+  #   _if :t => '${f:customer.name} == Fred' do
+  #     subprocess 'premium_course'
+  #     subprocess 'regular_course'
+  #   end
+  #
+  # When using Ruby to generate the process definition tree, you can simply do :
   #
   #   _if '${f:customer.name} == Fred' do
   #     subprocess 'premium_course'
@@ -79,21 +86,18 @@ module Ruote::Exp
 
     # called by 'else', 'then' or perhaps 'equals'
     #
-    def reply (workitem)
+    def reply(workitem)
 
       if workitem['fei'] == h.fei # apply --> reply
 
         h.test = attribute(:test)
+        h.test = attribute(:t) if h.test.nil?
         h.test = attribute_text if h.test.nil?
         h.test = nil if h.test == ''
 
-        offset = if h.test != nil
-          Condition.true?(h.test) ? 0 : 1
-        else
-          0
-        end
+        offset = (h.test.nil? || Condition.true?(h.test)) ? 0 : 1
 
-        apply_child_if_present(offset, workitem)
+        apply_child(offset, workitem)
 
       else # reply from a child
 
@@ -103,18 +107,17 @@ module Ruote::Exp
 
         else
 
-          apply_child_if_present(
-            workitem['fields']['__result__'] == true ? 1 : 2, workitem)
+          apply_child(workitem['fields']['__result__'] == true ? 1 : 2, workitem)
         end
       end
     end
 
     protected
 
-    def apply_child_if_present (index, workitem)
+    def apply_child(index, workitem)
 
       if tree_children[index]
-        apply_child(index, workitem)
+        super
       else
         reply_to_parent(workitem)
       end

data/lib/ruote/exp/fe_inc.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2010, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2005-2011, 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
@@ -151,14 +151,14 @@ module Ruote::Exp
       reply_to_parent(h.applied_workitem)
     end
 
-    def reply (workitem)
+    def reply(workitem)
 
       # never called
     end
 
     protected
 
-    def new_value (type, key)
+    def new_value(type, key)
 
       dec = name.match(/^dec/)
 

data/lib/ruote/exp/fe_iterator.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2010, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2005-2011, 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
@@ -126,11 +126,11 @@ module Ruote::Exp
   #
   #   class Adjust
   #     include Ruote::LocalParticipant
-  #     def consume (workitem)
+  #     def consume(workitem)
   #       workitem.command = 'break' if workitem.fields['amount'] > 10_000
   #       reply_to_engine(workitem)
   #     end
-  #     def cancel (fei, flavour)
+  #     def cancel(fei, flavour)
   #     end
   #   end
   #
@@ -197,7 +197,7 @@ module Ruote::Exp
 
     protected
 
-    def move_on (workitem=h.applied_workitem)
+    def move_on(workitem=h.applied_workitem)
 
       h.position += 1
 

data/lib/ruote/exp/fe_let.rb

@@ -0,0 +1,75 @@
+#--
+# Copyright (c) 2005-2011, 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.
+#++
+
+require 'ruote/exp/fe_sequence'
+
+
+module Ruote::Exp
+
+  #
+  # Behaves like a sequence, but the children have their own variable
+  # scope.
+  #
+  #   pdef = Ruote.process_definition do
+  #     set 'v:var' => 'val'
+  #     echo "out:${v:var}"
+  #     let do
+  #       set 'v:var' => 'val1'
+  #       echo "in:${v:var}"
+  #     end
+  #     echo "out:${v:var}"
+  #   end
+  #
+  # # => out:val, in:val1, out:val
+  #
+  #
+  # == as a 'case' statement
+  #
+  #   let do
+  #     define 'published' do
+  #       do_this
+  #     end
+  #     define 'reviewed' do
+  #       do_that
+  #     end
+  #     subprocess '${case}'
+  #   end
+  #
+  # Subprocesses 'published' and 'reviewed' are bound in a local scope,
+  # that gets discarded when the let exits.
+  #
+  class LetExpression < SequenceExpression
+
+    names :let
+
+    def apply
+
+      h.variables = {}
+        # the blank local scope
+
+      reply(h.applied_workitem)
+    end
+  end
+end
+

data/lib/ruote/exp/fe_listen.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005-2010, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2005-2011, 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
@@ -43,7 +43,7 @@ module Ruote::Exp
   #
   # It can be used in two ways : 'blocking' or 'triggering'. In both cases
   # the listen expression 'reacts' upon activity (incoming or outgoing workitem)
-  # happening on a channel (a participant name).
+  # happening on a channel (a participant name or a tag name).
   #
   # == blocking
   #
@@ -99,14 +99,42 @@ module Ruote::Exp
   # Can be set to 'reply', to react on workitems being handed back to the
   # engine by the participant.
   #
+  # Setting :upon to 'entering' or 'leaving' tells the listen to focus on
+  # tag events.
+  #
+  #   sequence do
+  #     sequence :tag => 'phase_one' do
+  #       alpha
+  #     end
+  #     sequence :tag => 'phase_two' do
+  #       bravo
+  #     end
+  #   end
+  #
+  # In this dummy process definition, there are four tag events :
+  #
+  # * 'entering' 'phase_one'
+  # * 'leaving' 'phase_one'
+  # * 'entering' 'phase_two'
+  # * 'leaving' 'phase_two'
+  #
+  #
   # == :to and :on
   #
   # The :to attribute has already been seen, it can be replaced by the :on one.
   #
-  # Those two attributes are expected to hold regular expressions, so it's OK to
-  # write things like :
+  #   listen :to => 'alpha'
+  #
+  # is equivalent to
+  #
+  #   listen :on => 'alpha'
+  #
+  #
+  # == :to (:on) and regular expressions
   #
-  #   listen :to => "^user\_.+"
+  # It's OK to write things like :
+  #
+  #   listen :to => "/^user\_.+/"
   #
   # or
   #
@@ -115,6 +143,7 @@ module Ruote::Exp
   # To listen for workitems for all the participant whose name start with
   # "user_".
   #
+  #
   # == :wfid
   #
   # By default, a listen expression listens for any workitem/participant event
@@ -122,16 +151,34 @@ module Ruote::Exp
   # will make the listen expression only care for events belonging to the
   # same process instance (same wfid).
   #
+  #
+  # == :where
+  #
+  # The :wfid can be considered a 'guard'. Another tool for guarding listen
+  # is to use the :where attribute.
+  #
+  #   listen :to => 'alpha', :where => '${customer.state} == CA'
+  #
+  # The listen will trigger only if the workitem has a customer field with
+  # a subfield state containing the value "CA".
+  #
+  # The documentation about the dollar notation and the one about common
+  # attributes :if and :unless applies for the :where attribute.
+  #
   class ListenExpression < FlowExpression
 
     names :listen, :receive, :intercept
 
+    UPONS = {
+      'apply' => 'dispatch', 'reply' => 'receive',
+      'entering' => 'entered_tag', 'leaving' => 'left_tag'
+    }
+
     def apply
 
       h.to = attribute(:to) || attribute(:on)
 
-      upon = attribute(:upon) || 'apply'
-      h.upon = (upon == 'reply') ? 'receive' : 'dispatch'
+      h.upon = UPONS[attribute(:upon) || 'apply']
 
       h.lmerge = attribute(:merge).to_s
       h.lmerge = 'true' if h.lmerge == ''
@@ -141,15 +188,24 @@ module Ruote::Exp
 
       persist_or_raise
 
+      condition = if h.upon == 'dispatch' || h.upon == 'receive'
+        { 'participant_name' => h.to }
+      else
+        { 'tag' => h.to }
+      end
+
       @context.tracker.add_tracker(
         h.lwfid ? h.fei['wfid'] : nil,
         h.upon,
-        h.fei,
-        { 'participant_name' => h.to },
-        { 'action' => 'reply', 'fei' => h.fei, 'flavour' => 'listen' })
+        Ruote.to_storage_id(h.fei),
+        condition,
+        { 'action' => 'reply',
+          'fei' => h.fei,
+          'workitem' => 'replace',
+          'flavour' => 'listen' })
     end
 
-    def reply (workitem)
+    def reply(workitem)
 
       #
       # :where guard
@@ -181,7 +237,7 @@ module Ruote::Exp
 
     protected
 
-    def reply_to_parent (workitem)
+    def reply_to_parent(workitem)
 
       @context.tracker.remove_tracker(h.fei)