ruote 2.2.0 → 2.3.0

data/lib/ruote/exp/fe_cron.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
@@ -94,7 +94,6 @@ module Ruote::Exp
     def apply
 
       h.schedule = attribute(:tab) || attribute(:interval) || attribute_text
-      h.job_id = nil
 
       reschedule
     end
@@ -110,17 +109,11 @@ module Ruote::Exp
       reschedule
     end
 
-    def cancel(flavour)
-
-      @context.storage.delete_schedule(h.job_id)
-      reply_to_parent(h.applied_workitem)
-    end
-
     # Note : this method has to be public.
     #
     def reschedule
 
-      h.job_id = @context.storage.put_schedule(
+      h.schedule_id = @context.storage.put_schedule(
         'cron',
         h.fei,
         h.schedule,
@@ -128,7 +121,7 @@ module Ruote::Exp
         'fei' => h.fei,
         'workitem' => h.applied_workitem)
 
-      @context.storage.delete_schedule(h.job_id) if try_persist
+      @context.storage.delete_schedule(h.schedule_id) if try_persist
         #
         # if the persist failed, immediately unschedule
         # the just scheduled job

data/lib/ruote/exp/fe_cursor.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
@@ -66,6 +66,12 @@ module Ruote::Exp
   #     publisher
   #   end
   #
+  # === reset
+  #
+  # Whereas 'rewind' places the cursor back to the initial step with the current
+  # workitem, 'reset' will rewind it and start again but with the workitem
+  # as it was when it reached the cursor/repeat.
+  #
   # === stop, over & break
   #
   # Exits the cursor.
@@ -262,7 +268,7 @@ module Ruote::Exp
       return reply_to_parent(workitem) if com == 'break'
 
       case com
-        when 'rewind', 'continue' then position = 0
+        when 'rewind', 'continue', 'reset' then position = 0
         when 'skip' then position += arg
         when 'jump' then position = jump_to(workitem, position, arg)
       end
@@ -270,8 +276,12 @@ module Ruote::Exp
       position = 0 if position >= tree_children.size && is_loop?
 
       if position < tree_children.size
+
+        workitem = h.applied_workitem if com == 'reset'
         apply_child(position, workitem)
+
       else
+
         reply_to_parent(workitem)
       end
     end
@@ -298,8 +308,8 @@ module Ruote::Exp
         ref = c[1]['ref']
         tag = c[1]['tag']
 
-        ref = @context.dollar_sub.s(ref, self, workitem) if ref
-        tag = @context.dollar_sub.s(tag, self, workitem) if tag
+        ref = dsub(ref, workitem) if ref
+        tag = dsub(tag, workitem) if tag
 
         next if exp_name != arg && ref != arg && tag != arg
 

data/lib/ruote/exp/fe_define.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
@@ -105,6 +105,8 @@ module Ruote::Exp
       definitions, bodies = tree[2].partition { |b| is_definition?(b) }
       name = tree[1]['name'] || tree[1].keys.find { |k| tree[1][k] == nil }
 
+      definitions = definitions.collect { |d| reorganize(d)[1] }
+
       [ name, [ 'define', tree[1], definitions + bodies ] ]
     end
   end

data/lib/ruote/exp/fe_echo.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_equals.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_error.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_filter.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
@@ -80,6 +80,12 @@ module Ruote::Exp
   #
   # Note the "!" used as a shortcut for "\." in the second line.
   #
+  # Passing a | separated list of field also works :
+  #
+  #   filter 'city|region|country', :type => 'string'
+  #     # will make sure that at least of one those field is present
+  #     # any of the three that is present must hold a string
+  #
   #
   # == validations
   #
@@ -162,6 +168,13 @@ module Ruote::Exp
   #
   #   filter 'x', :empty => true
   #
+  # === 'is'
+  #
+  # Checks if a field holds the given value.
+  #
+  #   filter 'x', :is => true
+  #   filter 'x', :is => [ 'a', 2, 3 ]
+  #
   # === 'in'
   #
   # Checks if a value is in a given set of values.
@@ -183,6 +196,15 @@ module Ruote::Exp
   #   filter 'x', :has => "x"
   #   filter 'x', :has => "abraham, bob, charly"
   #
+  # === 'includes'
+  #
+  # Checks if an array includes a given value. Works with Hash values as well.
+  #
+  #   filter 'x', :includes => 1
+  #
+  # Whereas 'has' accepts multiple values, 'includes' only accepts one (like
+  # Ruby's Array#include?).
+  #
   # === 'valid'
   #
   # Sometimes, it's better to immediately say 'true' or 'false'.
@@ -398,6 +420,34 @@ module Ruote::Exp
   #     { 'field' => 'A', 'delete' => true } ]
   #   # out :  { 'x' => 'a', 'y' => 'a' })
   #
+  # === 'take' and 'discard'
+  #
+  # (doesn't work well with the filter expression, it works better with
+  # filter as an attribute)
+  #
+  # Those two only make sense in out filters. One should use one or the other in
+  # a filter, but not both. It's probably better to use them at the bottom of
+  # the filters (last positions), because they switch the applied workitem
+  # (apply time) with the current workitem (reply time).
+  #
+  # 'take' means "the fields to consider are the one in the applied workitem
+  # plus the ones from the new workitem listed here".
+  #
+  # 'discard' means "the fields to consider are the the ones of the applied
+  # workitem plus all the ones from the new workitem except those listed here".
+  #
+  #   subprocess 'list_products', :filter => { :out => [
+  #     { 'field' => 'products', 'take' => true },
+  #     { 'field' => 'point_of_contact', 'take' => true }
+  #   ] }
+  #     # whatever the fields set by 'list_products', only 'products' and
+  #     # 'point_of_contact' make it through
+  #
+  # Saying :discard => true means "completely ignore any workitem field set
+  # by this expression".
+  #
+  #   subprocess 'review_document', :discard => true
+  #
   #
   # == short forms
   #
@@ -421,6 +471,23 @@ module Ruote::Exp
   # * 'restore', 'restore_from', 'rs'
   #
   #
+  # == top-level 'or'
+  #
+  # Filters may be used to transform hashes or to validate them. In both cases
+  # the filters seen until now were like chained by a big AND.
+  #
+  # It's OK to write
+  #
+  #   filter :in => [
+  #     { 'field' => 'server_href', 'smatch' => '^https?:\/\/' },
+  #     'or',
+  #     { 'field' => 'nickname', 'type' => 'string' } ]
+  #
+  # Granted, this is mostly for validation purposes, but it also works
+  # with transformations (as soon as an 'or' child succeeds it's returned
+  # and the other children are not evaluated).
+  #
+  #
   # == compared to the :filter attribute
   #
   # The :filter attribute accepts participant names, but for this filter
@@ -430,13 +497,42 @@ module Ruote::Exp
   # The 'restore' operation makes lots of sense for the :filter attribute
   # though.
   #
+  #
+  # == filtering with rules in a block
+  #
+  # This filter
+  #
+  #   filter :in => [
+  #     { :field => 'x', :type => 'string' },
+  #     { :field => 'y', :type => 'number' }
+  #   ]
+  #
+  # can be rewritten as
+  #
+  #   filter do
+  #     field 'x', :type => 'string'
+  #     field 'y', :type => 'number'
+  #   end
+  #
+  # The field names can be passed directly as head of each rule :
+  #
+  #   filter do
+  #     x :type => 'string'
+  #     y :type => 'number'
+  #   end
+  #
   class FilterExpression < FlowExpression
 
     names :filter
 
     def apply
 
-      filter = referenced_filter || complete_filter || one_line_filter
+      h.applied_workitem['fields'].delete('__result__')
+        #
+        # get rid of __result__
+
+      filter =
+        referenced_filter || complete_filter || one_line_filter || block_filter
 
       record = filter.first.delete('record') rescue nil
       flush = filter.first.delete('flush') rescue nil
@@ -480,6 +576,50 @@ module Ruote::Exp
 
     protected
 
+    # Filter is passed in a block (which is not evaluted as a ruote branch
+    # but immediately translated into a filter.
+    #
+    #   pdef = Ruote.process_definition do
+    #     filter do
+    #       field 'x', :type => 'string'
+    #       field 'y', :type => 'number'
+    #     end
+    #   end
+    #
+    # Note : 'or' is OK
+    #
+    #   pdef = Ruote.process_definition do
+    #     filter do
+    #       field 'x', :type => 'string'
+    #       _or
+    #       field 'y', :type => 'number'
+    #     end
+    #   end
+    #
+    def block_filter
+
+      return nil if tree.last.empty?
+
+      tree.last.collect { |line|
+
+        next 'or' if line.first == 'or'
+
+        rule = line[1].remap { |(k, v), h|
+          if v == nil
+            h['field'] = k
+          else
+            h[k] = v
+          end
+        }
+
+        rule['field'] ||= line.first
+
+        rule
+      }
+    end
+
+    # Filter is somewhere else (process variable or workitem field)
+    #
     def referenced_filter
 
       prefix, key = attribute_text.split(':')
@@ -496,6 +636,15 @@ module Ruote::Exp
       filter
     end
 
+    # Filter is passed with an :in attribute.
+    #
+    #   Ruote.process_definition do
+    #     filter :in => [
+    #       { :field => 'x', :type => 'string' },
+    #       { :field => 'y', :type => 'number' }
+    #     ]
+    #   end
+    #
     def complete_filter
 
       return nil if attribute_text != ''
@@ -503,15 +652,25 @@ module Ruote::Exp
       attribute(:in)
     end
 
+    # Filter thanks to the attributes of the expression.
+    #
+    #   pdef = Ruote.process_definition do
+    #     filter 'x', :type => 'string', :record => true
+    #     filter 'y', :type => 'number', :record => true
+    #   end
+    #
     def one_line_filter
 
-      [ attributes.inject({}) { |h, (k, v)|
+      if (attributes.keys - COMMON_ATT_KEYS - %w[ ref original_ref ]).empty?
+        return nil
+      end
+
+      [ attributes.remap { |(k, v), h|
         if v.nil?
           h['field'] = k
         else
           h[k] = v
         end
-        h
       } ]
     end
   end

data/lib/ruote/exp/fe_forget.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
@@ -57,14 +57,31 @@ module Ruote::Exp
   #     participant 'delta'
   #   end
   #
-  # This expression can be useful for fire-and-forget parallelism in processes.
+  # This expression can be useful for fire-and-forget 'parallelism'
+  # in processes.
   #
-  # == forget vs lose
+  #
+  # == multi forget
+  #
+  # Forget multiple children at once.
+  #
+  #   forget do
+  #     alice :task => 'take out garbage'
+  #     bob :task => 'clean living room'
+  #   end
+  #
+  # The forget expression will reply immediately to its parent expression, it
+  # will thus not be cancellable (neither the children will be cancellable).
+  #
+  #
+  # == 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 ForgetExpression < FlowExpression
 

data/lib/ruote/exp/fe_given.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_if.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_inc.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
@@ -23,9 +23,6 @@
 #++
 
 
-require 'ruote/exp/fe_set'
-
-
 module Ruote::Exp
 
   #
@@ -75,8 +72,8 @@ module Ruote::Exp
   #     set 'v:x' => %w[ a b c d ]
   #     repeat do
   #       dec 'v:x', :pos => 'head'
-  #       _break :unless => '${v:d}'
-  #       participant '${v:d}'
+  #       _break :unless => '${__result__}'
+  #       participant '${__result__}'
   #     end
   #   end
   #
@@ -108,7 +105,7 @@ module Ruote::Exp
   #   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
+  # 'dec' places the removed value in workitem field '__result__'. This trick
   # was used in the above iterator example.
   #
   # A specific variable or field can be specified via the :to_var / :to_field
@@ -117,65 +114,137 @@ module Ruote::Exp
   #   dec 'v:x', :to_v => 'a'
   #   participant :ref => '${v:a}'
   #
-  class IncExpression < SetExpression
+  #
+  # == nested value
+  #
+  # (Since ruote 2.3.0)
+  #
+  # If nested expressions are provided the __result__ workitem field is
+  # used for inc.
+  #
+  #   inc 'v:x' do
+  #     set '__result__' => 3
+  #   end
+  #
+  # will increase the value of the variable x by 3.
+  #
+  #
+  # == push and pop
+  #
+  # push and pop are aliases for inc and dec respectively. There is a major
+  # difference though: they'll force the target value into an array.
+  #
+  #   sequence do
+  #     set 'v:x' => 2
+  #     push 'v:x' => 3
+  #   end
+  #
+  # will result in a variable x holding [ 2, 3 ] as value.
+  #
+  # Likewise,
+  #
+  #   pop 'v:x'
+  #
+  # will force a value of [] into the variable x if it wasn't previously set
+  # or its value was not an array with more than one element.
+  #
+  class IncExpression < SequenceExpression
 
-    names :inc, :dec, :increment, :decrement
+    names :inc, :dec, :increment, :decrement, :push, :pop
 
     def apply
 
-      if var_key = has_attribute(:v, :var, :variable)
+      h.variables ||= {} # ensures a local scope
+
+      reply(h.applied_workitem)
+    end
+
+    def reply_to_parent(workitem)
+
+      h.applied_workitem['fields'] = workitem['fields']
+
+      key, value = if var_key = has_attribute(:v, :var, :variable)
 
         var = attribute(var_key)
-        set_v(var, new_value(:var, var))
+
+        [ "v:#{var}", new_value(:var, var, nil) ]
 
       elsif field_key = has_attribute(:f, :fld, :field)
 
         field = attribute(field_key)
-        set_f(field, new_value(:field, field))
 
-      else
+        [ field, new_value(:field, field, nil) ]
+
+      elsif k = att_text
+
+        [ k, new_value(nil, k, nil) ]
 
-        k = attribute_text
+      elsif kv = find_kv
 
-        raise(
-          ArgumentError.new('no variable or field to increment/decrement')
-        ) if k.length < 1
+        k, v = kv
 
-        set_vf(k, new_value(nil, k))
+        [ k, new_value(nil, k, v) ]
 
-      #else
-      #  raise ArgumentError.new(
-      #    "missing a variable or field target in #{tree.inspect}")
+      else
+
+        raise(ArgumentError.new('no variable or field to increment/decrement'))
       end
 
-      reply_to_parent(h.applied_workitem)
-    end
+      h.variables = nil
+        # the local scope is over,
+        # variables set here will be set in the parent scope
+
+      if dec? && value.is_a?(Array)
+        k, car, value = value
+        set_vf(k || '__result__', car)
+      end
 
-    def reply(workitem)
+      set_vf(key, value)
 
-      # never called
+      super(h.applied_workitem)
     end
 
     protected
 
-    def new_value(type, key)
+    def find_kv
 
-      dec = name.match(/^dec/)
+      compile_atts.reject { |k, v|
+        COMMON_ATT_KEYS.include?(k) ||
+        k.match(/^to_/)
+      }.first
+    end
+
+    def dec?
+
+      @dec ||= !!(name.match(/^dec/) or name == 'pop')
+    end
+
+    def new_value(type, key, increment)
 
       if type == nil && m = PREFIX_REGEX.match(key)
         type = (m[1][0, 1] == 'f' ? :field : :var)
         key = m[2]
       end
 
-      delta = lookup_val
+      delta = increment.nil? ? lookup_val : increment
+
+      if delta.nil? && @msg && @msg['action'] == 'reply'
+        delta = h.applied_workitem['fields']['__result__']
+      end
 
       ndelta = Ruote.narrow_to_number(delta || 1)
-      ndelta = -ndelta if dec && ndelta
+      ndelta = -ndelta if dec? && ndelta
 
       value = type == :var ?
         lookup_variable(key) :
         Ruote.lookup(h.applied_workitem['fields'], key)
 
+      value = case value
+        when NilClass then []
+        when Array then value
+        else [ value ]
+      end if (name == 'push' || name == 'pop')
+
       pos = attribute(:position) || attribute(:pos)
 
       return ((value || 0) + ndelta) if ndelta && (not value.is_a?(Array))
@@ -183,10 +252,7 @@ module Ruote::Exp
       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?
+      return (pos == 'tail' ? value + [ delta ] : [ delta ] + value) unless dec?
 
       car, cdr = if delta != nil
         (value.delete(delta) != nil ) ? [ delta, value ] : [ nil, value ]
@@ -196,9 +262,10 @@ module Ruote::Exp
         [ value[0], value[1..-1] ]
       end
 
-      to_v ? set_v(to_v, car) : set_f(to_f, car)
+      to_v, to_f = determine_tos
+      key = to_v ? "v:#{to_v}" : to_f
 
-      cdr
+      [ key, car, cdr ]
     end
   end
 end