ruote 2.2.0 → 2.3.0

data/lib/ruote/exp/command.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
@@ -30,8 +30,13 @@ module Ruote::Exp
   #
   module CommandMixin
 
+    # Field name '__command__', where one can place a command.
+    #
     F_COMMAND = '__command__'
-    ATT_COMMANDS = %w[ break rewind over stop ]
+
+    # break_if, break_unless, rewind_if, rewind_unless, ...
+    #
+    ATT_COMMANDS = %w[ break rewind reset over stop ]
 
     protected
 

data/lib/ruote/exp/commanded.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
@@ -58,7 +58,7 @@ module Ruote::Exp
       h.command_workitem = workitem
       h.command_workitem['fei'] = h.children.first
 
-      do_persist || return
+      do_persist or return
 
       @context.storage.put_msg('cancel', 'fei' => h.children.first)
 

data/lib/ruote/exp/condition.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
@@ -52,8 +52,8 @@ module Ruote::Exp
 
     def self.apply?(sif, sunless)
 
-      return (true?(sif)) if sif
-      return ( ! true?(sunless)) if sunless
+      return (true?(sif)) if sif != nil
+      return ( ! true?(sunless)) if sunless != nil
 
       true
     end
@@ -65,9 +65,8 @@ module Ruote::Exp
       conditional = unescape(conditional.to_s)
 
       REGEXES.each do |method, regex|
-        if m = regex.match(conditional)
-          return self.send(method, m)
-        end
+        m = regex.match(conditional)
+        return self.send(method, m) if m
       end
 
       evl(conditional) ? true : false
@@ -77,6 +76,13 @@ module Ruote::Exp
       raise ConditionError.new(conditional)
     end
 
+    # Returns true if the given conditional string evaluates to false.
+    #
+    def self.false?(conditional)
+
+      ( ! true?(conditional))
+    end
+
     # Evaluates the given [conditional] code string and returns the
     # result.
     #
@@ -95,13 +101,11 @@ module Ruote::Exp
 
     def self.parse(conditional)
 
-      Rufus::TreeChecker.parse(conditional)
+      Ruote.parse_ruby(conditional)
 
-    rescue NoMethodError => nme
+    rescue SyntaxError => se
 
-      raise NoMethodError.new(
-        "/!\\ please upgrade your rufus-treechecker gem /!\\"
-      )
+      [ :str, conditional ]
 
     rescue => e
 
@@ -147,9 +151,16 @@ module Ruote::Exp
         return evl(tree[1]).send(tree[2], evl(tree.last.last))
       end
 
-      return flatten(tree) if tree[0] == :call
+      if (c = flatten_and_compare(tree)) != nil
+        return c
+      end
+
+      if tree[0] == :call
+        return flatten(tree)
+      end
 
       raise ArgumentError
+        # TODO : consider returning false
 
       #require 'ruby2ruby'
       #Ruby2Ruby.new.process(Sexp.from_array(tree))
@@ -157,7 +168,21 @@ module Ruote::Exp
         # it's nice but "Loan/Grant" becomes "(Loan / Grant)"
     end
 
-    KEYWORDS = %w[ call const arglist ].collect { |w| w.to_sym }
+    def self.flatten_and_compare(tree)
+
+      ftree = tree.flatten
+      comparator = (ftree & COMPARATORS).first
+
+      return nil unless comparator
+
+      icomparator = ftree.index(comparator)
+      left = ftree[0..icomparator - 1]
+      right = ftree[icomparator + 1..-1]
+
+      evl("#{flatten(left).inspect} #{comparator} #{flatten(right).inspect}")
+    end
+
+    KEYWORDS = %w[ call const arglist str ].collect { |w| w.to_sym }
 
     def self.flatten(tree)
 

data/lib/ruote/exp/fe_add_branches.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_apply.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_await.rb

@@ -0,0 +1,357 @@
+#--
+# 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
+# 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/condition'
+
+
+module Ruote::Exp
+
+  #
+  # The 'await' expression is the successor of the 'listen' expression
+  # (Ruote::Exp::ListenExpression). It's been introduced in ruote 2.3.0.
+  #
+  # Hopefully it has a simpler syntax than 'listen'. The major difference
+  # between listen and await is that await, by default, listens only
+  # to events in the same process instance.
+  #
+  # This expression blocks until an event occurs somewhere else in the same
+  # process instance.
+  #
+  #   concurrence do
+  #     sequence do
+  #       participant 'alice'
+  #       await :left_tag => 'a'
+  #       participant 'bob'
+  #     end
+  #     sequence :tag => 'a' do
+  #       participant 'charly'
+  #       participant 'doug'
+  #     end
+  #     sequence do
+  #       participant 'eric'
+  #     end
+  #   end
+  #
+  # In this example, the flow between alice and bob, will block until 'doug'
+  # has replied (Yes, this example could have been written using
+  # :left_participant => 'doug').
+  #
+  # == modes
+  #
+  # 'await', like 'listen' works in two mode, "once" and "multiple times".
+  #
+  # In the 'once' mode, the await expression blocks the flow until the workitem
+  # (somewhere else in the process instance) leaves the alice participant:
+  #
+  #   sequence do
+  #     await :left_participant => 'alice'
+  #     participant 'eric'
+  #   end
+  #
+  # In the 'multiple times' mode, the await expression triggers its children
+  # expressions each time a matching event occurs. It never replies to its
+  # parent expression. Here, the participant 'post_alice' will receive a
+  # workitem each time, somewhere else in the process
+  #
+  #   await :left_participant => 'alice' do
+  #     participant 'post_alice'
+  #   end
+  #
+  # Note, that, unlike "listen" in previous versions of ruote, it's OK
+  # to consider the children of "await" as part of an implicit sequence:
+  #
+  #   await :left_participant => 'alice' do
+  #     participant 'bob'
+  #     participant 'charly'
+  #   end
+  #
+  # Bob and charly will be applied in sequence.
+  #
+  # == tag, participant or error events
+  #
+  # Await listens to 3 types of events: tag, participant and error events.
+  #
+  # Here is a assortment of examples:
+  #
+  #   await :in_participant => 'alice'
+  #   await :reached_participant => 'alice'
+  #   await :out_participant => 'alice'
+  #   await :left_participant => 'alice'
+  #
+  #   await :participant => 'alice'
+  #   await :participants => 'alice' # looks better with an array
+  #
+  #   # implicit OR with arrays:
+  #   #
+  #   await :in_participant => /^al/
+  #   await :in_participant => %w[ alice alfred ]
+  #   await :in_participant => [ /^al/, /fred$/ ]
+  #
+  #   await :in_tag => 'phase2'
+  #   await :reached_tag => 'phase2'
+  #   await :out_tag => 'phase2'
+  #   await :left_tag => 'phase2'
+  #
+  #   await :tags => 'phase2'
+  #
+  #   await :error
+  #   await :error => 'ArgumentError'
+  #   await :error => 'RuntimeError, ArgumentError'
+  #   await :error => %w[ RuntimeError ArgumentError ]
+  #
+  # Basically, the attribute is composed of a left part and a right part.
+  # The right part is one of "in", "reached" or "out", "left". "in" and
+  # "reached" are equivalent, as are "out" and "left".
+  #
+  # The right part is "tag" or "participant".
+  #
+  # "error" can be used alone.
+  #
+  # When "tags" and "participant(s)" are used alone, they are synonymous with
+  # "reached_tag" and "reached_participant" respectively.
+  #
+  # === absolute tags
+  #
+  # It's OK to specify absolute tags, like in:
+  #
+  #   pdef = Ruote.define do
+  #     concurrence do
+  #       sequence do
+  #         await :tag => 'a/b'
+  #         echo 'a/b'
+  #       end
+  #       sequence :tag => 'a' do
+  #         noop
+  #         sequence :tag => 'b' do
+  #           echo 'b'
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  # == :where condition
+  #
+  # The "await" expression accepts an optional attribute which adds another
+  # guard which is checked to determine if the trigger should occur or not.
+  #
+  #   pdef = Ruote.process_definition do
+  #     concurrence :wait_for => 1 do
+  #       await :left_participant => 'a', :where => "${task} == 'sing'" do
+  #         echo 'sing-a'
+  #       end
+  #       await :left_participant => 'a' do
+  #         echo 'any-a'
+  #       end
+  #       concurrence do
+  #         participant 'a', :task => 'talk'
+  #         participant 'a', :task => 'sing'
+  #       end
+  #     end
+  #   end
+  #
+  # In this example, the message 'sing-a' will be echoed only once (twice for
+  # 'any-a').
+  #
+  #
+  # == :global => false by default
+  #
+  # Unlike the 'listen' expression, 'await', by default, only triggers for
+  # events in the same process instance. To react on events whatever the
+  # process instance, :global => true (or "true") can be used.
+  #
+  #   await :left_tag => 'phase1', :global => true do
+  #     participant 'supervisor', :msg => 'phase1 over'
+  #   end
+  #
+  #
+  # == :merge => nil/ignore
+  #
+  # In the listen expression, the default is for the event's workitem to
+  # get merged into the waiting workitem. With 'await', the default is
+  # the event's workitem completely overriding the awaiting workitem.
+  #
+  # Using the :merge attribute, other behaviours are possible.
+  #
+  #   await :left_tag => 'phase3', :merge => 'ignore'
+  #   await :left_tag => 'phase3', :merge => 'drop'
+  #     # the event's workitem is ignored, the awaiting workitem is used
+  #
+  #   await :left_tag => 'phase3', :merge => 'override'
+  #     # the event's workitem is used, this is the default
+  #
+  #   await :left_tag => 'phase3', :merge => 'incoming'
+  #     # a hash merge happens, the incoming (event) workitem wins
+  #     # workitem = awaiting.merge(incoming)
+  #
+  #   await :left_tag => 'phase3', :merge => 'awaiting'
+  #     # a hash merge happens, the awaiting workitem wins
+  #     # workitem = incoming.merge(awaiting)
+  #
+  # Note: the :where guard is always about the event's workitem (not the
+  # workitem as it reached the 'await' expression).
+  #
+  class AwaitExpression < FlowExpression
+
+    names :await
+
+    INS = %w[ in entered reached]
+    OUTS = %w[ out left ]
+
+    SPLIT_R = /^(#{(INS + OUTS).join('|')})_(tag|participant)s?$/
+    SINGLE_R = /^(tag)s|(participant|error)s?$/ # not 'tag' alone
+
+    def apply
+
+      #
+      # gathering info
+
+      direction, type, value = attributes.collect { |k, v|
+        if m = SPLIT_R.match(k)
+          [ m[1], m[2], v ]
+        elsif m = SINGLE_R.match(k)
+          [ 'in', m[1] || m[2], v ]
+        else
+          nil
+        end
+      }.compact.first
+
+      raise ArgumentError.new(
+        "couldn't determine which event to listen to from: " +
+        attributes.inspect
+      ) unless direction
+
+      global = (attribute(:global).to_s == 'true')
+      global = false if type == 'error'
+
+      h.amerge = attribute(:merge).to_s
+
+      action = if type == 'tag'
+        INS.include?(direction) ? 'entered_tag' : 'left_tag'
+      elsif type == 'participant'
+        INS.include?(direction) ? 'dispatch' : 'receive'
+      else # error
+        'error_intercepted'
+      end
+
+      persist_or_raise
+
+      #
+      # adding a new tracker
+
+      @context.tracker.add_tracker(
+        global ? nil : h.fei['wfid'],
+        action,
+        Ruote.to_storage_id(h.fei),
+        determine_condition(type, value),
+        { 'action' => 'reply',
+          'fei' => h.fei,
+          'workitem' => 'replace',
+          'flavour' => 'await' })
+    end
+
+    def reply(workitem)
+
+      #
+      # :where guard
+
+      where = attribute(:where, workitem)
+      return if where && Condition.false?(where)
+
+      #
+      # merge
+
+      wi = h.applied_workitem.dup
+
+      wi['fields'] = case h.amerge
+        when 'ignore', 'drop' then wi['fields']
+        when 'incoming' then wi['fields'].merge(workitem['fields'])
+        when 'awaiting' then workitem['fields'].merge(wi['fields'])
+        else workitem['fields'] # 'override'
+      end
+
+      #
+      # actual trigger
+
+      if tree_children.any?
+
+        i, t = if tree_children.size == 1
+          [ "#{h.fei['expid']}_0", tree_children[0] ]
+        else
+          [ h.fei['expid'], [ 'sequence', {}, tree_children ] ]
+        end
+
+        launch_sub(i, t, :forget => true, :workitem => wi)
+
+      else
+
+        reply_to_parent(wi)
+      end
+    end
+
+    protected
+
+    # Overriding the parent's #reply_to_parent to make sure the tracker is
+    # removed before (expression terminating, no need for it to track anything
+    # anymore).
+    #
+    def reply_to_parent(workitem)
+
+      @context.tracker.remove_tracker(h.fei)
+
+      super(workitem)
+    end
+
+    # Matches Ruby class names, like "Ruote::ForcedError" or "::ArgumentError"
+    #
+    KLASS_R = /^(::)?([A-Z][a-z]+)+(::([A-Z][a-z]+)+)*$/
+
+    # Builds the condition used by the tracker service to filter msgs.
+    #
+    def determine_condition(type, value)
+
+      value = Ruote.comma_split(value)
+
+      if type == 'participant'
+
+        { 'participant_name' => value }
+
+      elsif type == 'error'
+
+        # array or comma string or string ?
+
+        h = { 'class' => [], 'message' => [] }
+
+        value.each { |e| (KLASS_R.match(e) ? h['class'] : h['message']) << e }
+
+        h.delete_if { |k, v| v == nil or v == [] }
+
+      else # 'tag'
+
+        { (value.first.to_s.match(/\//) ? 'full_tag' : 'tag') => value }
+      end
+    end
+  end
+end
+