ruote 2.2.0 → 2.3.0

data/lib/ruote/exp/fe_registerp.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
@@ -25,8 +25,6 @@
 
 module Ruote::Exp
 
-  #
-  # (Since ruote 2.1.12)
   #
   # This expressions lets one register participants directly from a process
   # definition.

data/lib/ruote/exp/fe_reserve.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_restore.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
@@ -56,6 +56,7 @@ module Ruote::Exp
   class RestoreExpression < FlowExpression
 
     include MergeMixin
+      # still have to implement something about merge...
 
     names :restore, :set_fields
 
@@ -66,9 +67,8 @@ module Ruote::Exp
         has_attribute(*%w[ f fld field ].map { |k| "from_#{k}" }) ||
         has_attribute(*%w[ val value ])
 
-      to =
-        has_attribute(*%w[ f fld field ].map { |k| "to_#{k}" }) ||
-        has_attribute('to')
+      _, to_f = determine_tos
+        # note : to_v is discarded (the underscore)
 
       from = 'from_var' if from == 'from_v'
 
@@ -82,8 +82,8 @@ module Ruote::Exp
         afrom
       end
 
-      if to
-        Ruote.set(h.applied_workitem['fields'], attribute(to), fields)
+      if to_f
+        Ruote.set(h.applied_workitem['fields'], to_f, fields)
       else
         h.applied_workitem['fields'] = fields
       end

data/lib/ruote/exp/fe_save.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,18 +23,21 @@
 #++
 
 
-
 module Ruote::Exp
 
   #
   # Saves the current workitem fields into a variable or into a field.
   #
   #   save :to_field => 'old_workitem'
+  #     # or
+  #   save :to => 'f:old_workitem'
   #     #
   #     # saves a copy of the fields of the current workitem into itself,
   #     # in the field named 'old_workitem'
   #
   #   save :to_variable => '/wix'
+  #     # or
+  #   save :to => 'v:/wix'
   #     #
   #     # saves a copy of the current workitem in the varialbe 'wix' at
   #     # the root of the process
@@ -47,24 +50,14 @@ module Ruote::Exp
 
     def apply
 
-      tk =
-        has_attribute(*%w[ v var variable ].map { |k| "to_#{k}" }) ||
-        has_attribute(*%w[ f fld field ].map { |k| "to_#{k}" })
-
-      return reply_to_parent(h.applied_workitem) unless tk
-
-      key = attribute(tk)
-
-      if tk.match(/^to_v/)
-
-        set_variable(key, h.applied_workitem['fields'])
-
-      elsif tk.match(/^to_f/)
+      to_v, to_f = determine_tos
 
-        Ruote.set(
-          h.applied_workitem['fields'],
-          key,
-          Ruote.fulldup(h.applied_workitem['fields']))
+      if to_v
+        set_variable(to_v, h.applied_workitem['fields'])
+      elsif to_f
+        set_f(to_f, Ruote.fulldup(h.applied_workitem['fields']))
+      #else
+        # do nothing
       end
 
       reply_to_parent(h.applied_workitem)

data/lib/ruote/exp/fe_sequence.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
@@ -34,12 +34,48 @@ module Ruote::Exp
   #     participant 'charly'
   #   end
   #
+  #
+  # == using 'let'
+  #
+  # 'let' 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 SequenceExpression < FlowExpression
 
-    names :sequence
+    names :sequence, :let
 
     def apply
 
+      h.variables ||= {} if name == 'let'
+
       reply(h.applied_workitem)
     end
 

data/lib/ruote/exp/fe_set.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
@@ -22,6 +22,8 @@
 # Made in Japan.
 #++
 
+require 'ruote/exp/fe_sequence'
+
 
 module Ruote::Exp
 
@@ -58,6 +60,33 @@ module Ruote::Exp
   #
   #   set :f => 'my_field', :value => 'oh and ${whatever}', :escape => true
   #
+  # == :override / :over
+  #
+  # (attribute introduced in ruote 2.3.0)
+  #
+  # When setting a variable with no slash prefix, the target will always be the
+  # most local scope. When one wants to purposely override/overwrite an already
+  # set variable, the attribute :override can be set to true.
+  #
+  # In this example, although the second 'set' happens in its own scope, the
+  # variable v0, will be set to 'b' in the initial (top) scope:
+  #
+  #   pdef = Ruote.define do
+  #     set 'v:v0' => 'a'
+  #     sequence :scope => true do
+  #       set 'v:v0' => 'b', :over => true
+  #     end
+  #   end
+  #
+  # :over(ride) tells the 'set' expression to locate where the var is set
+  # and change the value there.
+  #
+  # :over is ignored for process (/) and engine (//) variables. It has no
+  # meaning for workitem fields.
+  #
+  # When :over is set to 'sub' (or :sub), the :over => true behaviour is
+  # followed, but it doesn't cross into the parent subprocess.
+  #
   # == ruote 2.0's shorter form
   #
   # Ruote 2.0 introduces a shorter form for the 'set' expression :
@@ -85,6 +114,29 @@ module Ruote::Exp
   #     set 'f_${v:v}' => 'val2'
   #   end
   #
+  # === shorter form and non-string values
+  #
+  # Dollar substitutions like '${a}' will always squash the field or the
+  # variable into a string. It's useful, especially when one is doing
+  # 'user-${name}', but when the field (or variable) is an array or an hash
+  #
+  #   set 'f' => '${array}'
+  #
+  # will put the string representation of array into the field 'f', not
+  # a copy of the array itself.
+  #
+  # This will copy the array into the field 'f':
+  #
+  #   set 'f' => '$f:array'
+  #
+  # Note the mandatory 'f:'. There is a thing to be aware of: if the field
+  # array is missing, it will resolve into "$f:array" (no substitution at all).
+  #
+  # There is always the old-style fallback:
+  #
+  #   set :field => 'f', :field_value => 'array'
+  #
+  #
   # == set and rset
   #
   # Some gems (Sinatra) for example may provide a set method that hides calls
@@ -94,75 +146,126 @@ module Ruote::Exp
   #
   #   rset 'customer' => 'Jeff'
   #
-  class SetExpression < FlowExpression
+  #
+  # == unset
+  #
+  # 'unset' is the counterpart to 'set', it removes a field (or a variable)
+  #
+  #   unset :field => 'customer_name'
+  #   unset :f => 'customer_name'
+  #   unset :variable => 'vx'
+  #   unset :var => 'vx'
+  #   unset :v => 'vx'
+  #
+  # or simply
+  #
+  #   unset 'f:customer_name'
+  #   unset 'customer_name' # yes, it's field by default
+  #   unset 'v:vx'
+  #
+  #
+  # == using set with a block
+  #
+  # (not a very common usage, introduced by ruote 2.3.0)
+  #
+  # 'set' can be used with a block. It then behaves like a 'sequence' and
+  # picks its value in the workitem field named '__result__'.
+  #
+  #   set 'customer_name' do
+  #     participant 'alice'
+  #     participant 'bob'
+  #   end
+  #
+  # Here, alice or bob may set the field '__result__' to some value,
+  # that will get picked as the value of the field 'customer_name'.
+  #
+  # Note that inside the set, a blank variable scope will be used (like in
+  # a 'let).
+  #
+  #
+  # == __result__
+  #
+  # 'set' and 'unset' place the [un]set value in the field named __result__.
+  #
+  #   sequence do
+  #     set 'f0' => 2
+  #     participant 'x${__result__}''
+  #   end
+  #
+  # will route a workitem to the participant named 'x2'.
+  #
+  class SetExpression < SequenceExpression
 
     names :rset, :set, :unset
 
     def apply
 
-      opts = { :escape => attribute(:escape) }
+      h.variables ||= {} # ensures a local scope
 
-      value = lookup_val(opts)
-        # a nil value is totally OK
+      reply(h.applied_workitem)
+    end
 
-      if var_key = has_attribute(:v, :var, :variable)
+    def reply_to_parent(workitem)
 
-        set_v(attribute(var_key), value)
+      h.applied_workitem['fields'] = workitem['fields']
+        # since set_vf and co work on h.applied_workitem...
 
-      elsif field_key = has_attribute(:f, :fld, :field)
+      opts = { :escape => attribute(:escape) }
+      compiled_atts = compile_atts(opts)
 
-        set_f(attribute(field_key), value)
+      kv = find_kv(compiled_atts)
 
-      elsif value == nil && kv = expand_atts(opts).find { |k, v| k != 'escape' }
+      over = attribute(:override) || attribute(:over)
+      unset = name == 'unset'
 
-        set_vf(*kv)
+      h.variables = nil
+        # the local scope is over,
+        # variables set here will be set in the parent scope
 
+      value = if tree_children.empty?
+        lookup_val(opts)
       else
-
-        raise ArgumentError.new(
-          "missing a variable or field target in #{tree.inspect}")
+        h.applied_workitem['fields']['__result__']
       end
+        #
+        # a nil value is totally OK
 
-      reply_to_parent(h.applied_workitem)
-    end
+      result = if var_key = has_attribute(:v, :var, :variable)
 
-    def reply(workitem)
+        set_v(attribute(var_key), value, :unset => unset, :override => over)
 
-      # never called
-    end
+      elsif field_key = has_attribute(:f, :fld, :field)
 
-    protected
+        set_f(attribute(field_key), value, :unset => unset)
 
-    def set_v(key, value)
+      elsif value == nil && kv
 
-      if name == 'unset'
-        unset_variable(key)
-      else
-        set_variable(key, value)
-      end
-    end
+        kv << { :unset => unset, :override => over }
+
+        set_vf(*kv)
+
+      elsif kv
 
-    def set_f(key, value)
+        set_vf(kv.first, value, :unset => unset, :override => over)
 
-      if name == 'unset'
-        h.applied_workitem['fields'].delete(key)
       else
-        Ruote.set(h.applied_workitem['fields'], key, value)
+
+        raise ArgumentError.new(
+          "missing a variable or field target in #{tree.inspect}")
       end
-    end
 
-    PREFIX_REGEX = /^([^:]+):(.+)$/ #unless defined?(PREFIX_REGEX)
+      h.applied_workitem['fields']['__result__'] = result
 
-    def set_vf(key, value)
+      super(h.applied_workitem)
+    end
+
+    protected
 
-      field = true
+    def find_kv(atts)
 
-      if m = PREFIX_REGEX.match(key)
-        field = m[1][0, 1] == 'f'
-        key = m[2]
-      end
+      forbidden = COMMON_ATT_KEYS + %w[ escape over override ]
 
-      field ? set_f(key, value) : set_v(key, value)
+      atts.find { |k, v| ! forbidden.include?(k) }
     end
   end
 end

data/lib/ruote/exp/{fe_let.rb → fe_stall.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
@@ -22,53 +22,22 @@
 # 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
-  #
+  # Stalls the [current branch of the] process. Does it by simply getting
+  # applied and not replying.
   #
-  # == as a 'case' statement
+  # Mostly used for tests.
   #
-  #   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
+  class StallExpression < FlowExpression
 
-    names :let
+    names :stall
 
     def apply
 
-      h.variables = {}
-        # the blank local scope
-
-      reply(h.applied_workitem)
+      # do nothing, stall the [current branch of the] process.
     end
   end
 end