ruote 0.9.20 → 2.1.1

data/lib/ruote/exp/fe_if.rb

@@ -0,0 +1,124 @@
+#--
+# Copyright (c) 2005-2010, 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
+  #
+  # It's ok to shortcircuit the _if expression like this :
+  #
+  #   _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_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
+
+        apply_child_if_present(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_if_present(
+            workitem['fields']['__result__'] == true ? 1 : 2, workitem)
+        end
+      end
+    end
+
+    protected
+
+    def apply_child_if_present (index, workitem)
+
+      if tree_children[index]
+        apply_child(index, workitem)
+      else
+        reply_to_parent(workitem)
+      end
+    end
+  end
+end
+

data/lib/ruote/exp/fe_inc.rb

@@ -0,0 +1,205 @@
+#--
+# Copyright (c) 2005-2010, 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
+

data/lib/ruote/exp/fe_iterator.rb

@@ -0,0 +1,193 @@
+#--
+# Copyright (c) 2005-2010, 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/commanded'
+require 'ruote/exp/iterator'
+
+
+module Ruote::Exp
+
+  #
+  # Iterating on a list of values
+  #
+  #   pdef = Ruote.process_definition :name => 'test' do
+  #     iterator :on_val => 'alice, bob, charly', :to_var => 'v' do
+  #       participant '${v:v}'
+  #     end
+  #   end
+  #
+  # This expression expects at list an 'on' attribute, which can be :on,
+  # :on_val, :on_value for a value (usually a comma separated list), :on_v,
+  # :on_var, :on_variable for a list contained in the designated variable and
+  # :on_f, :on_fld, :on_field for a list contained in the designated workitem
+  # field.
+  #
+  # The 'on' attribute is used to instruct the expression on which list/array
+  # it should iterate.
+  #
+  # The 'to' attribute takes two forms, :to_v, :to_var, :to_variable or
+  # :to_f, :to_fld, :to_field.
+  #
+  # The 'to' attribute instructs the iterator into which variable or field
+  # it should place the current value (the value being iterated over).
+  #
+  # If there is no 'to' specified, the current value is placed in the variable
+  # named 'i'.
+  #
+  # The variables 'ii' contains the index (from 0 to ...) of the current value
+  # (think Ruby's #each_with_index).
+  #
+  # The 'on' attribute can be replaced by a :time or a :branches attribute.
+  #
+  #   pdef = Ruote.process_definition :name => 'test' do
+  #     iterator :times => '3'
+  #       participant 'accounting'
+  #     end
+  #   end
+  #
+  # will be equivalent to
+  #
+  #   pdef = Ruote.process_definition :name => 'test' do
+  #     sequence do
+  #       participant 'accounting'
+  #       participant 'accounting'
+  #       participant 'accounting'
+  #     end
+  #   end
+  #
+  #
+  # == break/rewind/continue/skip/jump
+  #
+  # The 'iterator' expression understands a certain the following commands :
+  #
+  # * break (_break) : exits the iteration
+  # * rewind : places the iteration back at the first iterated value
+  # * continue : same as 'rewind'
+  # * skip : skips a certain number of steps (relative)
+  # * jump : jump to certain step (absolute)
+  #
+  #   pdef = Ruote.process_definition :name => 'test' do
+  #     iterator :times => '3'
+  #       sequence do
+  #         participant 'accounting', :review => '${v:i}'
+  #         rewind :if => '${f:redo_everything} == true'
+  #       end
+  #     end
+  #   end
+  #
+  #
+  # == break/rewind/continue/skip/jump with :ref
+  #
+  # An iterator can be tagged (with the :tag attribute) and directly referenced
+  # from a break/rewind/continue/skip/jump command.
+  #
+  # It's very useful when iterators (and cursors/loops) are nested within each
+  # other or when one has to act on an iterator from outside of it.
+  #
+  #   concurrence do
+  #
+  #     iterator :on => 'alpha, bravo, charly', :tag => 'review' do
+  #       participant '${v:i}'
+  #     end
+  #
+  #     # meanwhile ...
+  #
+  #     sequence do
+  #       participant 'main control program'
+  #       _break :ref => 'review', :if => '${f:cancel_review} == yes'
+  #     end
+  #   end
+  #
+  # in this example, the participant 'main control program' may cancel the
+  # review.
+  #
+  #   iterator :on => 'c1, c2, c3', :to_f => 'client', :tag => 'main' do
+  #     cursor do
+  #       participant :ref => '${f:client}'
+  #       _break :ref => 'main', :if => '${f:cancel_everything}'
+  #       participant :ref => 'salesclerk'
+  #       participant :ref => 'salesclerk'
+  #     end
+  #   end
+  #
+  # in this weird process, if one customer says "cancel everything" (set the
+  # workitem field "cancel_everything" to true), then the whole iterator
+  # gets 'broken' out of.
+  #
+  class IteratorExpression < CommandedExpression
+
+    include IteratorMixin
+
+    names :iterator
+
+    def apply
+
+      return reply_to_parent(h.applied_workitem) if tree_children.size < 1
+
+      h.list = determine_list
+      h.to_v, h.to_f = determine_tos
+      h.position = -1
+
+      h.to_v = 'i' if h.to_v == nil && h.to_f == nil
+
+      move_on
+    end
+
+    protected
+
+    def move_on (workitem=h.applied_workitem)
+
+      h.position += 1
+
+      com, arg = get_command(workitem)
+
+      return reply_to_parent(workitem) if com == 'break'
+
+      case com
+        when 'rewind', 'continue' then h.position = 0
+        when 'skip' then h.position += arg
+        when 'jump' then h.position = arg
+      end
+
+      h.position = h.list.length + h.position if h.position < 0
+
+      val = h.list[h.position]
+
+      return reply_to_parent(workitem) if val == nil
+
+      (h.variables ||= {})['ii'] = h.position
+
+      if h.to_v
+        h.variables[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
+