ruote 2.1.11 → 2.2.0

data/lib/ruote/exp/fe_add_branches.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
@@ -101,7 +101,7 @@ module Ruote::Exp
       reply_to_parent(h.applied_workitem)
     end
 
-    def reply (workitem)
+    def reply(workitem)
 
       # never called
     end

data/lib/ruote/exp/fe_apply.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

data/lib/ruote/exp/fe_cancel_process.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
@@ -51,14 +51,14 @@ module Ruote::Exp
   #
   class CancelProcessExpression < FlowExpression
 
-    names :cancel_process
+    names :cancel_process, :terminate
 
     def apply
 
       @context.storage.put_msg('cancel_process', 'wfid' => h.fei['wfid'])
     end
 
-    def reply (workitem)
+    def reply(workitem)
 
       # never called
     end

data/lib/ruote/exp/fe_command.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
@@ -87,7 +87,7 @@ module Ruote::Exp
 
     include CommandMixin
 
-    names :skip, :back, :jump, :rewind, :continue, :break, :stop
+    names :skip, :back, :jump, :rewind, :continue, :break, :stop, :over
 
     def apply
 
@@ -143,7 +143,7 @@ module Ruote::Exp
     # (CommandExpression includes CommandMixin, but since it doesn't have
     # children, no need to 'evince' it)
     #
-    def fetch_command_target (exp=parent)
+    def fetch_command_target(exp=parent)
 
       case exp
         when nil then nil

data/lib/ruote/exp/fe_concurrence.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
@@ -182,7 +182,7 @@ module Ruote::Exp
       apply_children
     end
 
-    def reply (workitem)
+    def reply(workitem)
 
       if h.cmerge == 'first' || h.cmerge == 'last'
         h.workitems << workitem
@@ -230,7 +230,7 @@ module Ruote::Exp
       msgs.each { |m| @context.storage.put_msg('apply', m) }
     end
 
-    def over? (workitem)
+    def over?(workitem)
 
       over_if = attribute(:over_if, workitem)
       over_unless = attribute(:over_unless, workitem)
@@ -253,7 +253,7 @@ module Ruote::Exp
       h.ccount ? [ h.ccount, tree_children.size ].min : tree_children.size
     end
 
-    def reply_to_parent (_workitem)
+    def reply_to_parent(_workitem)
 
       workitem = merge_all_workitems
 

data/lib/ruote/exp/fe_concurrent_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
@@ -112,23 +112,34 @@ module Ruote::Exp
   #
   # Read more at the 'add_branches' expression description.
   #
+  #
+  # == 'citerator'
+  #
+  # 'citerator' is an alias for 'concurrent_iterator'.
+  #
+  #   pdef = Ruote.process_definition :name => 'test' do
+  #     citerator :on_val => 'alice, bob, charly', :to_var => 'v' do
+  #       participant '${v:v}'
+  #     end
+  #   end
+  #
   class ConcurrentIteratorExpression < ConcurrenceExpression
 
     include IteratorMixin
 
-    names :concurrent_iterator
+    names :concurrent_iterator, :citerator
 
     ADD_BRANCHES_FIELD = '__add_branches__'
 
     # Overrides FlowExpression#register_child to make sure that persist is
     # not called.
     #
-    def register_child (fei)
+    def register_child(fei)
 
       h.children << fei
     end
 
-    def add_branches (list)
+    def add_branches(list)
 
       if h.times_iterator && list.size == 1
 
@@ -142,6 +153,7 @@ module Ruote::Exp
         h.list_size += 1
 
         workitem = Ruote.fulldup(h.applied_workitem)
+        #workitem = Rufus::Json.dup(h.applied_workitem)
 
         variables = { 'ii' => h.list_size - 1 }
 
@@ -159,7 +171,7 @@ module Ruote::Exp
       end
     end
 
-    def reply (workitem)
+    def reply(workitem)
 
       if ab = workitem['fields'].delete(ADD_BRANCHES_FIELD)
 

data/lib/ruote/exp/fe_cron.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
@@ -99,7 +99,7 @@ module Ruote::Exp
       reschedule
     end
 
-    def reply (workitem)
+    def reply(workitem)
 
       launch_sub(
         "#{h.fei['expid']}_0",
@@ -110,7 +110,7 @@ module Ruote::Exp
       reschedule
     end
 
-    def cancel (flavour)
+    def cancel(flavour)
 
       @context.storage.delete_schedule(h.job_id)
       reply_to_parent(h.applied_workitem)

data/lib/ruote/exp/fe_cursor.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
@@ -178,7 +178,7 @@ module Ruote::Exp
   #   class Reviewer
   #     include Ruote::LocalParticipant
   #
-  #     def consume (workitem)
+  #     def consume(workitem)
   #       # somehow review the book
   #       if review == 'bad'
   #         #workitem.fields['__command__'] = [ 'rewind' ] # old style
@@ -189,7 +189,7 @@ module Ruote::Exp
   #       reply_to_engine(workitem)
   #     end
   #
-  #     def cancel (fei, flavour)
+  #     def cancel(fei, flavour)
   #       # cancel if review is still going on...
   #     end
   #   end
@@ -250,7 +250,7 @@ module Ruote::Exp
 
     # Determines which child expression of the cursor is to be applied next.
     #
-    def move_on (workitem=h.applied_workitem)
+    def move_on(workitem=h.applied_workitem)
 
       position = workitem['fei'] == h.fei ?
         -1 : Ruote::FlowExpressionId.child_id(workitem['fei'])
@@ -286,7 +286,7 @@ module Ruote::Exp
     # Jumps to an integer position, or the name of an expression
     # or a tag name of a ref name.
     #
-    def jump_to (workitem, position, arg)
+    def jump_to(workitem, position, arg)
 
       pos = Integer(arg) rescue nil
 

data/lib/ruote/exp/fe_define.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
@@ -92,7 +92,7 @@ module Ruote::Exp
     # Returns true if the tree's root expression is a definition
     # (define, process_definition, ...)
     #
-    def self.is_definition? (tree)
+    def self.is_definition?(tree)
 
       self.expression_names.include?(tree.first)
     end
@@ -100,7 +100,7 @@ module Ruote::Exp
     # Used by instances of this class and also the expression pool,
     # when launching a new process instance.
     #
-    def self.reorganize (tree)
+    def self.reorganize(tree)
 
       definitions, bodies = tree[2].partition { |b| is_definition?(b) }
       name = tree[1]['name'] || tree[1].keys.find { |k| tree[1][k] == nil }

data/lib/ruote/exp/fe_echo.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
@@ -40,7 +40,7 @@ module Ruote::Exp
 
     def apply
 
-      text = "#{attribute_text}\n"
+      text = "#{attribute(:text) || attribute_text}\n"
 
       if t = @context['s_tracer']
         t << text
@@ -51,7 +51,7 @@ module Ruote::Exp
       reply_to_parent(h.applied_workitem)
     end
 
-    def reply (workitem)
+    def reply(workitem)
 
       # never called
     end

data/lib/ruote/exp/fe_equals.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
@@ -96,7 +96,7 @@ module Ruote::Exp
       keys.collect { |k| grab_value(k) }
     end
 
-    def grab_value (k)
+    def grab_value(k)
 
       attval = attribute(k)
 

data/lib/ruote/exp/fe_error.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
@@ -64,7 +64,7 @@ module Ruote::Exp
         'workitem' => h.applied_workitem)
     end
 
-    def reply (workitem)
+    def reply(workitem)
 
       return reply_to_parent(workitem) if h.triggered
 

data/lib/ruote/exp/fe_filter.rb

@@ -0,0 +1,519 @@
+#--
+# 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/util/filter'
+
+
+module Ruote::Exp
+
+  #
+  # Filter is a one-way filter expression. It filters workitem fields.
+  # Validations and Transformations are possible.
+  #
+  # Validations will raise errors (that'll block the process segment
+  # unless an :on_error attribute somehow deals with the problem).
+  #
+  # Transformations will copy values around fields.
+  #
+  # There are two ways to use it. With a single rule or with an array of
+  # rules.
+  #
+  #   filter 'x', :type => 'string'
+  #     # will raise an error if the field 'x' doesn't contain a String
+  #
+  # or
+  #
+  #   filter :in => [
+  #     { :field => 'x', :type => 'string' },
+  #     { :field => 'y', :type => 'number' }
+  #   ]
+  #
+  # For the remainder of this piece of documentation, the one rule filter
+  # will be used.
+  #
+  # == filtering targets (field names)
+  #
+  # Top level field names are OK :
+  #
+  #   filter 'customer_id', :type => 'string'
+  #   filter 'invoice_id', :type => 'number'
+  #
+  # Pointing to fields lying deeper is OK :
+  #
+  #   filter 'customer.id', :type => 'number'
+  #   filter 'customer.name', :type => 'string'
+  #   filter 'invoice', :type => 'array'
+  #   filter 'invoice.0.id', :type => 'number'
+  #
+  # (Note the dollar notation is also OK with such dotted identifiers)
+  #
+  # It's possible to target multiple fields by passing a list of field names
+  # or a regular expression.
+  #
+  #   filter 'city, region, country', :type => 'string'
+  #     # will make sure that those 3 fields hold a string value
+  #
+  #   filter '/^address\.x_/', :type => number
+  #   filter '/^address!x_/', :type => number
+  #     # fields whosename start with x_ in the address hash should be numbers
+  #
+  # Note the "!" used as a shortcut for "\." in the second line.
+  #
+  #
+  # == validations
+  #
+  # === 'type'
+  #
+  # Ruote is a Ruby library, it adopts Ruby "laissez-faire" for workitem
+  # fields, but sometimes, some type oriented validation is necessary.
+  # Ruote limits itself to the types found in the JSON specification with
+  # one or two additions.
+  #
+  #   filter 'x', :type => 'string'
+  #   filter 'x', :type => 'number'
+  #   filter 'x', :type => 'bool'
+  #   filter 'x', :type => 'boolean'
+  #   filter 'x', :type => 'null'
+  #
+  #   filter 'x', :type => 'array'
+  #
+  #   filter 'x', :type => 'object'
+  #   filter 'x', :type => 'hash'
+  #     # 'object' and 'hash' are equivalent
+  #
+  # It's OK to pass multiple types for a field
+  #
+  #   filter 'x', :type => 'bool,number'
+  #   filter 'x', :type => [ 'string', 'array' ]
+  #
+  #   filter 'x', :type => 'string,null'
+  #     # a string or null or not set
+  #
+  # The array and the object/hash types accept a subtype for their values
+  # (a hash/object must have string keys anyway).
+  #
+  #   filter 'x', :type => 'array<number>'
+  #   filter 'x', :type => 'array<string>'
+  #   filter 'x', :type => 'array<array<string>>'
+  #
+  #   filter 'x', :type => 'array<string,number>'
+  #     # an array of strings or numbers (both)
+  #   filter 'x', :type => 'array<string>,array<number>'
+  #     # an array of strings or an array of numbers
+  #
+  # === 'match' and 'smatch'
+  #
+  # 'match' will check if a field, when turned into a string, matches
+  # a given regular expression.
+  #
+  #   filter 'x', :match => '1'
+  #     # will match "11", 1, 1.0, "212"
+  #
+  # 'smatch' works the same but only accepts fields that are strings.
+  #
+  #   filter 'x', :smatch => '^user_'
+  #     # valid only if x's value is a string that starts with "user_"
+  #
+  # === 'size' and 'empty'
+  #
+  # 'size' is valid for values that respond to the #size method (strings
+  # hashes and arrays).
+  #
+  #   filter 'x', :size => 4
+  #     # will be valid of values like [ 1, 2, 3, 4 ], "toto" or
+  #     # { 'a' => 1, 'b' => 2, 'c' => 3, 'd' => 4 }
+  #
+  #   filter 'x', :size => [ 4, 5 ]
+  #   filter 'x', :size => '4,5'
+  #     # four to five elements
+  #
+  #   filter 'x', :size => [ 4 ]
+  #   filter 'x', :size => [ 4, nil ]
+  #   filter 'x', :size => '4,'
+  #     # four or more elements
+  #
+  #   filter 'x', :size => [ nil, 4 ]
+  #   filter 'x', :size => ',4'
+  #     # four elements or less
+  #
+  # Similarly, the 'empty' check will evaluate to true (ie not raise an
+  # exception) if the value responds to #empty? and is, well, not empty.
+  #
+  #   filter 'x', :empty => true
+  #
+  # === 'in'
+  #
+  # Checks if a value is in a given set of values.
+  #
+  #   filter 'x', :in => [ 1, 2, 3 ]
+  #   filter 'x', :in => "john, jeff, jim"
+  #
+  # === 'has'
+  #
+  # Checks if an array contains certain values
+  #
+  #   filter 'x', :has => 1
+  #   filter 'x', :has => "x"
+  #   filter 'x', :has => [ 1, 7, 12 ]
+  #   filter 'x', :has => "abraham, bob, charly"
+  #
+  # Also checks if a hash has certain keys (strings only of course)
+  #
+  #   filter 'x', :has => "x"
+  #   filter 'x', :has => "abraham, bob, charly"
+  #
+  # === 'valid'
+  #
+  # Sometimes, it's better to immediately say 'true' or 'false'.
+  #
+  #   filter 'x', :valid => 'true'
+  #   filter 'x', :valid => 'false'
+  #
+  # Not very useful...
+  #
+  # In fact, it's meant to be used with the dollar notation
+  #
+  #   filter 'x', :valid => '${other.field}'
+  #     # will be valid if ${other.field} evaluates to 'true'...
+  #
+  # === cumulating validations
+  #
+  # As seen before, type validations can be cumulated.
+  #
+  #   filter 'x', :type => 'bool,number'
+  #
+  # Validations can be cumulated as well
+  #
+  #   filter 'x', :type => 'array<number>', :has => [ 1, 2 ]
+  #     # will be valid if the field 'x' holds an array of numbers
+  #     # and that array has 1 and 2 among its elements
+  #
+  # === validation errors
+  #
+  # By defaults a validation error will result in a process error (ie the
+  # process instance will have to be manually fixed and resumed, or there
+  # is a :on_error somewhere dealing automatically with errors).
+  #
+  # It's possible to prevent raising an error and simply record the validation
+  # errors.
+  #
+  #   filter 'x', :type => 'bool,number', :record => true
+  #
+  # will enumerate validation errors in the '__validation_errors__' workitem
+  # field.
+  #
+  #   filter 'y', :type => 'bool,number', :record => 'verrors'
+  #
+  # will enumerate validation errors in teh 'verrors' workitem field.
+  #
+  # To flush the recording field, use :flush => true
+  #
+  #   sequence do
+  #     filter 'x', :type => 'string', :record => true
+  #     filter 'y', :type => 'number', :record => true, :flush => true
+  #     participant 'after'
+  #   end
+  #
+  # the participant 'after' will only see the result of the second filter.
+  #
+  # For complex filters, if the first rule has :record => true, the
+  # 'recording' will happen for the whole filter.
+  #
+  #   sequence do
+  #     filter :in => [
+  #       { :field => 'x', :type => 'string', :record => true },
+  #       { :field => 'y', :type => 'number' } ]
+  #     participant 'after'
+  #   end
+  #
+  #
+  # == transformations
+  #
+  # So far, only the validation aspect of filter was shown. They can also be
+  # used to transform the workitem.
+  #
+  #   filter 'x', :type => 'string', :or => 'missing'
+  #     # will replace the value of x by 'missing' if it's not a string
+  #
+  #   filter 'z', :remove => true
+  #     # will remove the workitem field z
+  #
+  #   filter 'a,b,c', 'set' => '---'
+  #     # sets the field a, b and c to '---'
+  #
+  # === 'remove'
+  #
+  # Removes a field (or a subfield).
+  #
+  #   filter 'z', :remove => true
+  #
+  # === 'default'
+  #
+  # If there is no value for a field, sets it
+  #
+  #   filter 'x', 'default' => 0
+  #     # will set x to 0, if it's not set or its value is nil
+  #
+  #   filter '/^user-.+/', 'default' => 'nemo'
+  #     # will set any 'user-...' field to 'nemo' if its value is nil
+  #
+  # === 'or'
+  #
+  # 'or' combines with a condition. The 'or' value is set if the condition
+  # evaluates to false.
+  #
+  # Using 'or' without a condition makes it equivalent to a 'default'.
+  #
+  #   filter 'x', 'or' => 0
+  #     # will set x to 0, if it's not set or its value is nil
+  #
+  #   filter 'x', 'type' => 'number', 'or' => 0
+  #     # if x is not set or is not a number, will set it to 0
+  #
+  # Multiple conditions are OK
+  #
+  #   filter 'x', 't' => 'array', 'has' => 'cat', 'or' => []
+  #     # if x is an array and has the 'cat' element, nothing will happen.
+  #     # Else x will be set to [].
+  #
+  # === 'and'
+  #
+  # 'and' is much like 'or', but it triggers if the condition evaluates to true.
+  #
+  #   filter 'x', 'type' => number, 'and' => '*removed*'
+  #     # if x is a number, it will replace it with '*removed*'
+  #
+  # === 'set'
+  #
+  # Like 'remove' removes unconditionally, 'set' sets a field unconditionally.
+  #
+  #   filter 'x', 'set' => 'blue'
+  #     # sets the field x to 'blue'
+  #
+  # === copy, merge, migrate / to, from
+  #
+  #   # in :   { 'x' => 'y' }
+  #   filter 'x', 'copy_to' => 'z'
+  #   # out :  { 'x' => 'y', 'z' => 'y' }
+  #
+  #   # in :   { 'x' => 'y' }
+  #   filter 'z', 'copy_from' => 'x'
+  #   # out :  { 'x' => 'y', 'z' => 'y' }
+  #
+  #   # in :   { 'x' => 'y' }
+  #   filter 'z', 'copy_from' => 'x'
+  #   # out :  { 'x' => 'y', 'z' => 'y' }
+  #
+  #   # in :   { 'a' => %w[ x y ]})
+  #   filter '/a\.(.+)/', 'copy_to' => 'b\1'
+  #   # out :  { 'a' => %w[ x y ], 'b0' => 'x', 'b1' => 'y' },
+  #
+  #   # in :   { 'a' => %w[ x y ]})
+  #   filter '/a!(.+)/', 'copy_to' => 'b\1'
+  #   # out :  { 'a' => %w[ x y ], 'b0' => 'x', 'b1' => 'y' },
+  #     #
+  #     # '!' is used as a replacement for '\.' in regexes
+  #
+  #   # in :   { 'a' => 'b', 'c' => 'd', 'source' => [ 7 ] })
+  #   filter '/^.$/', 'copy_from' => 'source.0'
+  #   # out :  { 'a' => 7, 'c' => 7, 'source' => [ 7 ] },
+  #
+  # ...
+  #
+  # 'copy_to' and 'copy_from' copy whole fields. 'move_to' and 'move_from'
+  # move fields.
+  #
+  # 'merge_to' and 'merge_from' merge hashes (or add values to
+  # arrays), 'push_to' and 'push_from' are aliases for 'merge_to' and
+  # 'merge_from' respectively.
+  #
+  # 'migrate_to' and 'migrate_from' act like 'merge_to' and 'merge_from' but
+  # delete the merge source afterwards (like 'move').
+  #
+  # All those hash/array filter operations understand the '.' field, meaning
+  # the hash being filtered itself.
+  #
+  #   # in :   { 'x' => { 'a' => 1, 'b' => 2 } })
+  #   filter 'x', 'merge_to' => '.'
+  #   # out :  { 'x' => { 'a' => 1, 'b' => 2 }, 'a' => 1, 'b' => 2 },
+  #
+  # === access to 'previous versions' with ~ and ~~
+  #
+  # Before a filter is applied, a copy of the hash to filter is placed under
+  # the '~' key in the hash itself.
+  #
+  # this filter will at first set the field x to 0, and then reset it to its
+  # original value :
+  #
+  #   filter :in => [
+  #     { :field => 'x', :set => 0 },
+  #     { :field => 'x', :copy_from => '~.x' }
+  #   ]
+  #
+  # For the 'filter' expression, '~~' contains the same thing as '~', but
+  # for the :filter attribute, it contains the hash (workitem fields) as
+  # it was when the expression with the :filter attribute got reached (applied).
+  #
+  # === 'restore' and 'restore_from'
+  #
+  # Since these two filter operations leverage '~~', they're not very useful
+  # for the 'filter' expression. But they make lots of sense for the :filter
+  # attribute.
+  #
+  #   # in :   { 'x' => 'a', 'y' => 'a' },
+  #   filter :in => [
+  #     { 'field' => 'x', 'set' => 'X' },
+  #     { 'field' => 'y', 'set' => 'Y' },
+  #     { 'field' => '/^.$/', 'restore' => true } ]
+  #   # out :   { 'x' => 'a', 'y' => 'a' },
+  #
+  #   # in :   { 'x' => 'a', 'y' => 'a' },
+  #   filter :in => [
+  #     { 'field' => 'A', 'set' => {} },
+  #     { 'field' => '.', 'merge_to' => 'A' },
+  #     { 'field' => 'x', 'set' => 'X' },
+  #     { 'field' => 'y', 'set' => 'Y' },
+  #     { 'field' => '/^[a-z]$/', 'restore_from' => 'A' },
+  #     { 'field' => 'A', 'delete' => true } ]
+  #   # out :  { 'x' => 'a', 'y' => 'a' })
+  #
+  #
+  # == short forms
+  #
+  # Could help make filters a bit more compact.
+  #
+  # * 'size', 'sz'
+  # * 'empty', 'e'
+  # * 'in', 'i'
+  # * 'has', 'h'
+  # * 'type', 't'
+  # * 'match', 'm'
+  # * 'smatch', 'sm'
+  # * 'valid', 'v'
+  #
+  # * 'remove', 'rm', 'delete', 'del'
+  # * 'set', 's'
+  # * 'copy_to', 'cp_to'
+  # * 'move_to', 'mv_to'
+  # * 'merge_to', 'mg_to'
+  # * 'migrate_to', 'mi_to'
+  # * 'restore', 'restore_from', 'rs'
+  #
+  #
+  # == compared to the :filter attribute
+  #
+  # The :filter attribute accepts participant names, but for this filter
+  # expression, it makes no sense accepting partipants... Simply invoke
+  # the participant as usual.
+  #
+  # The 'restore' operation makes lots of sense for the :filter attribute
+  # though.
+  #
+  class FilterExpression < FlowExpression
+
+    names :filter
+
+    def apply
+
+      filter = referenced_filter || complete_filter || one_line_filter
+
+      record = filter.first.delete('record') rescue nil
+      flush = filter.first.delete('flush') rescue nil
+
+      record = '__validation_errors__' if record == true
+
+      opts = {
+        :double_tilde => parent_id ?
+          (parent.h.applied_workitem['fields'] rescue nil) : nil,
+        :no_raise => record
+      }
+        #
+        # parent_fields are placed in the ^^ available to the filter
+
+      fields = Ruote.filter(filter, h.applied_workitem['fields'], opts)
+
+      if record and fields.is_a?(Array)
+        #
+        # validation failed, :record requested, list deviations in
+        # the given field name
+
+        (flush ?
+          h.applied_workitem['fields'][record] = [] :
+          h.applied_workitem['fields'][record] ||= []
+        ).concat(fields)
+
+        reply_to_parent(h.applied_workitem)
+
+      else
+        #
+        # filtering successful
+
+        reply_to_parent(h.applied_workitem.merge('fields' => fields))
+      end
+    end
+
+    def reply(workitem)
+
+      # never called
+    end
+
+    protected
+
+    def referenced_filter
+
+      prefix, key = attribute_text.split(':')
+
+      return nil unless %w[ v var variable f field ].include?(prefix)
+
+      filter = prefix.match(/^v/) ?
+        lookup_variable(key) : Ruote.lookup(h.applied_workitem['fields'], key)
+
+      if filter.is_a?(Hash) and i = filter['in']
+        return i
+      end
+
+      filter
+    end
+
+    def complete_filter
+
+      return nil if attribute_text != ''
+
+      attribute(:in)
+    end
+
+    def one_line_filter
+
+      [ attributes.inject({}) { |h, (k, v)|
+        if v.nil?
+          h['field'] = k
+        else
+          h[k] = v
+        end
+        h
+      } ]
+    end
+  end
+end
+