ruote-maestrodev 2.2.1

data/lib/ruote/exp/fe_restore.rb

@@ -0,0 +1,102 @@
+#--
+# 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/merge'
+
+
+module Ruote::Exp
+
+  #
+  # Restores the fields of the current workitem. That means usually copying
+  # them from a saved version in a variable or in a separate field.
+  #
+  #   restore :from_var => 'v'
+  #
+  # or
+  #
+  #   restore :from_f => 'customer.address.street', :to_f => 'delivery.street'
+  #
+  # (yes, this sets the field 'street' inside of the field 'delivery')
+  #
+  # == set_fields
+  #
+  # This expressions has a 'set_fields' alias. It can be handy (and readable)
+  # to set a bunch of workitem fields in one sweep somewhere in a process :
+  #
+  #   Ruote.process_definition :name => 'working hard' do
+  #     sequence do
+  #       set_fields :val => { 'customer' => { 'name' => 'Fred', 'age' => 40 } }
+  #       participant :ref => 'delivery'
+  #       participant :ref => 'invoincing'
+  #     end
+  #   end
+  #
+  class RestoreExpression < FlowExpression
+
+    include MergeMixin
+      # still have to implement something about merge...
+
+    names :restore, :set_fields
+
+    def apply
+
+      from =
+        has_attribute(*%w[ v var variable ].map { |k| "from_#{k}" }) ||
+        has_attribute(*%w[ f fld field ].map { |k| "from_#{k}" }) ||
+        has_attribute(*%w[ val value ])
+
+      _, to_f = determine_tos
+        # note : to_v is discarded (the underscore)
+
+      from = 'from_var' if from == 'from_v'
+
+      afrom = attribute(from)
+
+      fields = if from.match(/var/)
+        lookup_variable(afrom)
+      elsif from.match(/f/)
+        Ruote.lookup(h.applied_workitem['fields'], afrom)
+      else # val
+        afrom
+      end
+
+      if to_f
+        Ruote.set(h.applied_workitem['fields'], to_f, fields)
+      else
+        h.applied_workitem['fields'] = fields
+      end
+
+      # TODO : merge strategies
+
+      reply_to_parent(h.applied_workitem)
+    end
+
+    def reply(workitem)
+
+      # empty, never called
+    end
+  end
+end
+

data/lib/ruote/exp/fe_save.rb

@@ -0,0 +1,72 @@
+#--
+# 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
+
+  #
+  # 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
+  #
+  # See also the 'restore' expression (Ruote::Exp::RestoreExpression).
+  #
+  class SaveExpression < FlowExpression
+
+    names :save
+
+    def apply
+
+      to_v, to_f = determine_tos
+
+      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)
+    end
+
+    def reply(workitem)
+
+      # empty, never called
+    end
+  end
+end
+

data/lib/ruote/exp/fe_sequence.rb

@@ -0,0 +1,59 @@
+#--
+# 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
+
+  #
+  # The plain 'sequence' expression.
+  #
+  #   sequence do
+  #     participant 'alpha'
+  #     participant 'bravo'
+  #     participant 'charly'
+  #   end
+  #
+  class SequenceExpression < FlowExpression
+
+    names :sequence
+
+    def apply
+
+      reply(h.applied_workitem)
+    end
+
+    def reply(workitem)
+
+      position = workitem['fei'] == h.fei ?
+        0 : Ruote::FlowExpressionId.new(workitem['fei']).child_id + 1
+
+      if position < tree_children.size
+        apply_child(position, workitem)
+      else
+        reply_to_parent(workitem)
+      end
+    end
+  end
+end
+

data/lib/ruote/exp/fe_set.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.
+#++
+
+
+module Ruote::Exp
+
+  #
+  # Setting a workitem field or a process variable.
+  #
+  #   sequence do
+  #     set :field => 'subject', :value => 'food and beverage'
+  #     set :field => 'date', :val => 'tomorrow'
+  #     participant :ref => 'attendees'
+  #   end
+  #
+  # :field can be abbreviated to :f or :fld. :variable can be abbreviated to
+  # :v or :var. Likewise, :val and :value are interchangeable.
+  #
+  # == field_value, variable_value
+  #
+  # Usually, grabbing a value from a field or a value will look like
+  #
+  #   set :f => 'my_field', :value => '${v:my_variable}'
+  #
+  # But doing those ${} substitutions always result in a string result. What
+  # if the variable or the field holds a non-string value ?
+  #
+  #   set :f => 'my_field', :var_value => 'my_variable'
+  #
+  # Is the way to go then. 'set' understands v_value, var_value, variable_value
+  # and f_value, fld_value and field_value.
+  #
+  # == :escape
+  #
+  # If the value to insert contains ${} stuff but this has to be preserved,
+  # setting the attribute :escape to true will do the trick.
+  #
+  #   set :f => 'my_field', :value => 'oh and ${whatever}', :escape => true
+  #
+  # == ruote 2.0's shorter form
+  #
+  # Ruote 2.0 introduces a shorter form for the 'set' expression :
+  #
+  #   sequence do
+  #     set :field => 'f', :value => 'val0'
+  #     set :variable => 'v', :value => 'val1'
+  #     set :field => 'f_${v:v}', :value => 'val2'
+  #   end
+  #
+  # can be rewritten as
+  #
+  #   sequence do
+  #     set 'f:f' => 'val0'
+  #     set 'v:v' => 'val1'
+  #     set 'f:f_${v:v}' => 'val2'
+  #   end
+  #
+  # since 'f:' is the default for the 'dollar notation', the shortest form
+  # becomes
+  #
+  #   sequence do
+  #     set 'f' => 'val0'
+  #     set 'v:v' => 'val1'
+  #     set 'f_${v:v}' => 'val2'
+  #   end
+  #
+  # == set and rset
+  #
+  # Some gems (Sinatra) for example may provide a set method that hides calls
+  # to set when building process definitions (see http://groups.google.com/group/openwferu-users/browse_thread/thread/9ac606e30ada686e)
+  #
+  # A workaround is to write 'rset' instead of 'set'.
+  #
+  #   rset 'customer' => 'Jeff'
+  #
+  #
+  # == 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'
+  #
+  class SetExpression < FlowExpression
+
+    names :rset, :set, :unset
+
+    def apply
+
+      opts = { :escape => attribute(:escape) }
+
+      value = lookup_val(opts)
+        # a nil value is totally OK
+
+      if var_key = has_attribute(:v, :var, :variable)
+
+        set_v(attribute(var_key), value, name == 'unset')
+
+      elsif field_key = has_attribute(:f, :fld, :field)
+
+        set_f(attribute(field_key), value, name == 'unset')
+
+      elsif value == nil && kv = expand_atts(opts).find { |k, v| k != 'escape' }
+
+        kv << (name == 'unset')
+
+        set_vf(*kv)
+
+      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
+  end
+end
+

data/lib/ruote/exp/fe_subprocess.rb

@@ -0,0 +1,211 @@
+#--
+# 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/subprocess'
+
+
+module Ruote::Exp
+
+  #
+  # An expression for invoking a subprocess.
+  #
+  #   pdef = Ruote.process_definition do
+  #     sequence do
+  #       subprocess :ref => 'delivering'
+  #       subprocess 'invoicing'
+  #       refill_stock :if => '${v:stock_size} < 10'
+  #     end
+  #     define 'delivering' do
+  #       # ...
+  #     end
+  #     define 'invoicing' do
+  #       # ...
+  #     end
+  #     define 'refill_stock' do
+  #       # ...
+  #     end
+  #   end
+  #
+  #
+  # == passing attributes as variables
+  #
+  # The attributes of the subprocess expression are passed as variables of
+  # the new subprocess instance.
+  #
+  #   Ruote.process_definition do
+  #     subprocess 'sub0', :a => 'A', :b => 'B'
+  #     define :sub0 do
+  #       echo '${v:a}:${v:b}'
+  #     end
+  #   end
+  #
+  # This example (and useless) process example will output "A:B" to STDOUT.
+  #
+  #
+  # == passing 'blocks' to subprocesses
+  #
+  # When the subprocess expression has children, the first of them is passed
+  # to the subprocess instance as the 'tree' variable, readily available for
+  # an 'apply' expression.
+  #
+  #   Ruote.process_definition :name => 'double review' do
+  #     sequence do
+  #       sub0 do
+  #         review_board
+  #       end
+  #       sub0 do
+  #         review_board
+  #       end
+  #     end
+  #     define 'sub0' do
+  #       concurrence do
+  #         apply :i => 0
+  #         apply :i => 1
+  #         apply :i => 2
+  #       end
+  #     end
+  #   end
+  #
+  # This example will send 2 x 3 concurrent workitems to the participant
+  # named 'review_board' (note that it could also be the name of another
+  # subprocess).
+  #
+  #
+  # == passing 'parameters' to subprocess
+  #
+  #   Ruote.process_definition :name => 'whatever' do
+  #
+  #     call :who => 'the cops', :when => 'if I\'m not back at 3'
+  #
+  #     process_definition 'call' do
+  #       participant :ref => '${v:who}', :msg => 'this is a call'
+  #     end
+  #   end
+  #
+  # This binds the variables 'who' and 'when' in the subprocess instance.
+  #
+  # Of course you can combine parameters and blocks passing.
+  #
+  #
+  # == pointing to subprocesses via their URI
+  #
+  # It's OK to invoke subprocesses via a URI
+  #
+  #   subprocess :ref => 'pdefs/definition1.rb'
+  #
+  # or
+  #
+  #   subprocess :ref => 'http://pdefs.example.org/account/def1.xml'
+  #
+  # Remember that the 'remote_definition_allowed' option of the engine has
+  # to be set to true for the latter to work, else the engine will refuse
+  # to load definitions over HTTP.
+  #
+  # Shorter :
+  #
+  #   subprocess 'http://pdefs.example.org/account/def1.xml'
+  #
+  #
+  # == subprocess URIs bound at engine level
+  #
+  # There is a class of variables accessible to process instances in read-only
+  # mode : engine level variables.
+  #
+  # They can be set via the engine's initialization code (or later) like in
+  # this example :
+  #
+  #   engine.variables['inventory_check'] = 'http://pdefs.example.com/ic0.rb'
+  #
+  # All the process instance in the engine may then trigger this process in
+  # these 3 ways :
+  #
+  #   subprocess :ref => 'inventory_check'
+  #   subprocess 'inventory_check'
+  #   inventory_check
+  #
+  # The latter may make process definitions quite readable (but blur the
+  # distinction between expressions, call to participants or to subprocesses).
+  #
+  #
+  # == subprocess trees bound at engine level
+  #
+  # It's OK to place a process tree directly in an engine variable :
+  #
+  #   engine.variables['inventory_check'] = Ruote.process_definition do
+  #     cursor do
+  #       manager :task => 'hire inventory team'
+  #       floor_manager :task => 'lead inventory'
+  #       manager :task => 'check results'
+  #       rewind :unless => '${inventory_successful}'
+  #     end
+  #   end
+  #
+  # Then, from the main process :
+  #
+  #   sequence do
+  #     # ...
+  #     inventory_check
+  #     # ...
+  #   end
+  #
+  class SubprocessExpression < FlowExpression
+
+    names :subprocess
+
+    def apply
+
+      return invoke_engine_participant if attribute(:engine)
+
+      ref = attribute(:ref) || attribute_text
+
+      raise "no subprocess referred in #{tree}" unless ref
+
+      pos, subtree = Ruote.lookup_subprocess(self, ref)
+
+      vars = compile_atts
+      vars.merge!('tree' => tree_children.first)
+        # NOTE : we're taking the first child here...
+
+      launch_sub(pos, subtree, :variables => vars)
+    end
+
+    protected
+
+    def invoke_engine_participant
+
+      atts = tree[1]
+
+      if ref = atts.find { |k, v| v.nil? }
+        ref = ref.first
+        atts.delete(ref)
+      end
+      atts['pdef'] = atts['ref'] || ref
+      atts['ref'] = atts.delete('engine')
+
+      @h['name'] = 'participant'
+      Ruote::Exp::ParticipantExpression.new(@context, @h).apply
+    end
+  end
+end
+