ruote-maestrodev 2.2.1

data/lib/ruote/exp/fe_forget.rb

@@ -0,0 +1,88 @@
+#--
+# 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.
+#++
+
+
+module Ruote::Exp
+
+  #
+  # Forgets all of its children.
+  #
+  # This expression is somehow deprecated in favour of the :forget attribute
+  # that any expression understands.
+  #
+  #   sequence do
+  #     participant 'alpha'
+  #     forget do
+  #       sequence do
+  #         participant 'bravo'
+  #         participant 'charly'
+  #       end
+  #     end
+  #     participant 'delta'
+  #   end
+  #
+  # In this example above, the flow goes from alpha to bravo and delta. The
+  # bravo-charly segment is independent of the main process flow. Charly's
+  # reply will be forgotten.
+  #
+  # Now the equivalent process definition, but using the :forget attribute :
+  #
+  #   sequence do
+  #     participant 'alpha'
+  #     sequence :forget => true do
+  #       participant 'bravo'
+  #       participant 'charly'
+  #     end
+  #     participant 'delta'
+  #   end
+  #
+  # 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
+
+    def apply
+
+      tree_children.each_with_index do |t, index|
+        apply_child(index, Ruote.fulldup(h.applied_workitem), true)
+      end
+
+      reply_to_parent(h.applied_workitem)
+    end
+
+    def reply(workitem)
+
+      # never gets called
+    end
+  end
+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

@@ -0,0 +1,127 @@
+#--
+# 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.
+#++
+
+
+module Ruote::Exp
+
+  #
+  # Here are examples of the 'if' expression in use :
+  #
+  #   _if do
+  #     equals :field_value => 'customer', :other_value => 'British Petroleum'
+  #     participant :ref => 'Allister'
+  #   end
+  #
+  # and :
+  #
+  #   _if :test => '${f:customer} == British Petroleum' do
+  #     participant :ref => 'Allister'
+  #   end
+  #
+  # An else clause is accepted :
+  #
+  #   _if do
+  #     equals :field_value => 'customer', :other_value => 'British Petroleum'
+  #     participant :ref => 'Allister'
+  #     participant :ref => 'Bernardo'
+  #   end
+  #
+  # or :
+  #
+  #   _if :test => '${f:customer} == British Petroleum' do
+  #     participant :ref => 'Allister'
+  #     participant :ref => 'Bernardo'
+  #   end
+  #
+  # Note that any expression accepts an :if attribute :
+  #
+  #   participant :ref => 'Al', :if => '${f:customer} == British Petroleum'
+  #
+  #
+  # == shorter
+  #
+  # 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'
+  #     subprocess 'regular_course'
+  #   end
+  #
+  class IfExpression < FlowExpression
+
+    names :if
+
+    def apply
+
+      reply(h.applied_workitem)
+    end
+
+    # called by 'else', 'then' or perhaps 'equals'
+    #
+    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 = (h.test.nil? || Condition.true?(h.test)) ? 0 : 1
+
+        apply_child(offset, workitem)
+
+      else # reply from a child
+
+        if h.test != nil || Ruote::FlowExpressionId.child_id(workitem['fei']) != 0
+
+          reply_to_parent(workitem)
+
+        else
+
+          apply_child(workitem['fields']['__result__'] == true ? 1 : 2, workitem)
+        end
+      end
+    end
+
+    protected
+
+    def apply_child(index, workitem)
+
+      if tree_children[index]
+        super
+      else
+        reply_to_parent(workitem)
+      end
+    end
+  end
+end
+

data/lib/ruote/exp/fe_inc.rb

@@ -0,0 +1,205 @@
+#--
+# 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_set'
+
+
+module Ruote::Exp
+
+  #
+  # Increments or decrements the value found in a process variable or
+  # a workitem field.
+  #
+  # One points to a var or a field in these various ways :
+  #
+  #   sequence do
+  #     inc :var => 'counter'
+  #     inc :field => 'counter'
+  #     inc 'v:counter'
+  #     inc 'f:counter'
+  #   end
+  #
+  # 'inc' and 'dec' work with two types of values : numbers (the default) and
+  # arrays.
+  #
+  #
+  # == numbers
+  #
+  # The vanilla case of inc/dec is increasing/decreasing a value by 1.
+  #
+  #   dec :var => 'x'
+  #
+  # will decrease the value in variable 'x' by 1.
+  #
+  # inc/dec works with two kind of numbers, integers and floats.
+  #
+  # If the target var or field is not set, it will be assumed to be at zero.
+  #
+  # The default increment is 1 (or 1.0 for floats). It can be changed by
+  # passing a value to the inc/dec expression.
+  #
+  #   inc 'v:x', :val => 3
+  #   inc 'v:y', :val => 2.4
+  #
+  #
+  # == arrays
+  #
+  # inc/dec can be used to push/pop elements in arrays held in process variables
+  # or workitem fields.
+  #
+  # This fragment of process definition
+  #
+  #   sequence do
+  #     set 'v:x' => %w[ a b c d ]
+  #     repeat do
+  #       dec 'v:x', :pos => 'head'
+  #       _break :unless => '${v:d}'
+  #       participant '${v:d}'
+  #     end
+  #   end
+  #
+  # is equivalent to
+  #
+  #   iterator :on => 'a, b, c, d', :to_var => 'x' do
+  #     participant '${v:x}'
+  #   end
+  #
+  # More details : the inc expression expects a value and it will place it
+  # at the end of the current array. The :pos or :position attribute can
+  # be set to 'head' to let the inc expression place the value at the head
+  # of the array.
+  #
+  #   set 'v:x' => [ 'alfred', 'bryan' ]
+  #   set 'v:customer_name' => 'charles'
+  #
+  #   inc 'v:x', :val => '${v:customer_name}'
+  #     # the variable 'x' now holds [ 'alfred', 'bryan', 'charles' ]
+  #   inc 'v:y', :val => '${v:customer_name}', :pos => 'head'
+  #     # the variable 'x' now holds [ 'charles', 'alfred', 'bryan', 'charles' ]
+  #
+  # The 'dec' / 'decrement' variant of the expression will remove the tail
+  # value (by default) of the array, or the head value if :pos is set to 'head'.
+  #
+  # It's also possible to remove a specific value by passing it to 'dec' :
+  #
+  #   set 'v:x' => [ 'alfred', 'bryan', 'carl' ]
+  #   dec 'v:x', :val => 'bryan'
+  #     # the variable 'x' now holds [ 'alfred', 'carl' ]
+  #
+  # 'dec' places the removed value in the local variable named 'd'. This trick
+  # was used in the above iterator example.
+  #
+  # A specific variable or field can be specified via the :to_var / :to_field
+  # attributes :
+  #
+  #   dec 'v:x', :to_v => 'a'
+  #   participant :ref => '${v:a}'
+  #
+  class IncExpression < SetExpression
+
+    names :inc, :dec, :increment, :decrement
+
+    def apply
+
+      if var_key = has_attribute(:v, :var, :variable)
+
+        var = attribute(var_key)
+        set_v(var, new_value(:var, var))
+
+      elsif field_key = has_attribute(:f, :fld, :field)
+
+        field = attribute(field_key)
+        set_f(field, new_value(:field, field))
+
+      else
+
+        k = attribute_text
+
+        raise(
+          ArgumentError.new('no variable or field to increment/decrement')
+        ) if k.length < 1
+
+        set_vf(k, new_value(nil, k))
+
+      #else
+      #  raise ArgumentError.new(
+      #    "missing a variable or field target in #{tree.inspect}")
+      end
+
+      reply_to_parent(h.applied_workitem)
+    end
+
+    def reply(workitem)
+
+      # never called
+    end
+
+    protected
+
+    def new_value(type, key)
+
+      dec = name.match(/^dec/)
+
+      if type == nil && m = PREFIX_REGEX.match(key)
+        type = (m[1][0, 1] == 'f' ? :field : :var)
+        key = m[2]
+      end
+
+      delta = lookup_val
+
+      ndelta = Ruote.narrow_to_number(delta || 1)
+      ndelta = -ndelta if dec && ndelta
+
+      value = type == :var ?
+        lookup_variable(key) :
+        Ruote.lookup(h.applied_workitem['fields'], key)
+
+      pos = attribute(:position) || attribute(:pos)
+
+      return ((value || 0) + ndelta) if ndelta && (not value.is_a?(Array))
+
+      pos ||= 'tail'
+      value ||= []
+
+      return (pos == 'tail' ? value + [ delta ] : [ delta ] + value) unless dec
+
+      to_v, to_f = determine_tos
+      to_v = 'd' if to_v.nil? && to_f.nil?
+
+      car, cdr = if delta != nil
+        (value.delete(delta) != nil ) ? [ delta, value ] : [ nil, value ]
+      elsif pos == 'tail'
+        [ value[-1], value[0..-2] ]
+      else
+        [ value[0], value[1..-1] ]
+      end
+
+      to_v ? set_v(to_v, car) : set_f(to_f, car)
+
+      cdr
+    end
+  end
+end
+