flor 0.14.0 → 0.15.0

data/lib/flor/pcore/map.rb

@@ -1,53 +1,84 @@
 
-class Flor::Pro::Map < Flor::Procedure
-
-  names %w[ map for-each ]
-
-  def pre_execute
-
-    @node['vars'] ||= {}
-
-    @node['col'] = nil
-    @node['idx'] = -1
-    @node['fun'] = nil
-
-    @node['res'] = @node['heat0'] == 'map' ? [] : nil
-
-    unatt_unkeyed_children
+class Flor::Pro::Map < Flor::Pro::Iterator
+  #
+  # This is the classical "map" procedure. It accepts a collection
+  # and a function and yields a new collection.
+  #
+  # ```
+  # map [ 1, 2, 3 ]
+  #   def x
+  #     + x 3
+  # # f.ret yields [ 4, 5, 6 ]
+  # ```
+  #
+  # The collection if not given is taken from `f.ret`:
+  # ```
+  # [ 1, 2, 3 ]
+  # map
+  #   def x
+  #     + x 2
+  # # f.ret yields [ 3, 4, 5 ]
+  # ```
+  #
+  # The function may be given by reference:
+  # ```
+  # define add3 x
+  #   + x 3
+  # map [ 0, 1 ] add3
+  # ```
+  #
+  # There is an implicit `idx` var:
+  # ```
+  # map [ 'a', 'b' ]
+  #   def x \ [ idx, x ]
+  # # f.ret yields [ [ 0, 'a' ], [ 1, 'b' ] ]
+  # ```
+  # but that index can be included in the function signature:
+  # ```
+  # map [ 'a', 'b' ]
+  #   def x i \ [ x, i ]
+  # # f.ret yields [ [ 'a', 0 ], [ 'b', 1 ] ]
+  # ```
+  #
+  # ## with objects (hashes)
+  #
+  # ```
+  # map { a: 'A', b: 'B', c: 'C' }
+  #   def k v \ [ k v ]
+  # # f.ret --> [ [ 'a', 'A' ], [ 'b', 'B' ], [ 'c', 'C' ] ]
+  #
+  # map { a: 'A', b: 'B', c: 'C' }
+  #   def k v i \ [ i k v ]
+  # # f.ret --> [ [ 0, 'a', 'A' ], [ 1, 'b', 'B' ], [ 2, 'c', 'C' ] ]
+  # ```
+  #
+  # ## iterating and functions
+  #
+  # Iterating functions accept 0 to 3 arguments when iterating over an
+  # array and 0 to 4 arguments when iterating over an object.
+  #
+  # Those arguments are `[ value, index, length ]` for arrays.
+  # They are `[ key, value, index, length ]` for objects.
+  #
+  # The corresponding `key`, `val`, `idx` and `len` variables are also
+  # set in the closure for the function call.
+  #
+  # ## see also
+  #
+  # Collect.
+
+  name 'map'
+
+  protected
+
+  def receive_iteration
+
+    @node['res'] << payload['ret']
   end
 
-  def receive_non_att
-
-    @node['col'] ||=
-      Flor.to_coll(
-        if Flor.is_func_tree?(payload['ret'])
-          node_payload_ret
-        else
-          payload['ret']
-        end)
-
-    return execute_child(@ncid) \
-      if @node['fun'] == nil && children[@ncid] != nil
-
-    if @node['idx'] < 0
-      @node['fun'] = payload['ret']
-    elsif res = @node['res']
-      res << payload['ret']
-    end
-
-    @node['idx'] += 1
-    @node['mtime'] = Flor.tstamp
-
-    if @node['idx'] == @node['col'].size
-      if res = @node['res']
-        payload['ret'] = @node['res']
-      end
-      return wrap_reply
-    end
-
-    @node['vars']['idx'] = @node['idx']
+  def iterator_result
 
-    apply(@node['fun'], @node['col'][@node['idx'], 1], tree[2])
+    @node['res']
   end
 end
 

data/lib/flor/pcore/match.rb

@@ -184,6 +184,10 @@ class Flor::Pro::Match < Flor::Pro::Case
   # (guard {name})
   # (guard {name} {pattern|conditional}*)
   # ```
+  #
+  # ## see also
+  #
+  # Case.
 
   name 'match'
 
@@ -192,7 +196,7 @@ class Flor::Pro::Match < Flor::Pro::Case
     unatt_unkeyed_children
 
     conditional = true
-    @node['val'] = payload['ret'] if non_att_children.size.even?
+    @node['val'] = payload['ret'] if non_att_count.even?
     found_val = @node.has_key?('val')
     t = tree
     changed = false
@@ -216,7 +220,7 @@ class Flor::Pro::Match < Flor::Pro::Case
     t = tree[1][index]
 
     payload['_pat_val'] = @node['val'] \
-      if t && t[0].match(/\A_pat_(arr|obj|or|guard)\z/)
+      if t && t[0].match(/\A_pat_(arr|obj|or|guard|regex)\z/)
 
     super
   end
@@ -225,6 +229,8 @@ class Flor::Pro::Match < Flor::Pro::Case
 
   def patternize(t)
 
+    return [ '_pat_regex', *t[1..-1] ] if t[0] == '_rxs'
+
     return t unless t[1].is_a?(Array)
 
     bang = t[1]

data/lib/flor/pcore/matchr.rb

@@ -73,18 +73,17 @@ class Flor::Pro::Matchr < Flor::Procedure
     rets = @node['rets'].dup
     rets.unshift(node_payload_ret) if rets.size < 2
 
-    fail ArgumentError.new(
-      "'#{tree[0]}' needs 1 or 2 arguments"
+    fail Flor::FlorError.new(
+      "'#{tree[0]}' needs 1 or 2 arguments", self
     ) if rets.size < 2
 
     rex =
-      rets.find { |r| r.is_a?(Array) && r[0] == '_rxs' } ||
+      rets.find { |r| Flor.is_regex_tree?(r) } ||
       rets.last
 
     str = (rets - [ rex ]).first
 
-    rex = rex.is_a?(String) ? rex : rex[1].to_s
-    rex = rex.match(/\A\/[^\/]*\/[a-z]*\z/) ? Kernel.eval(rex) : Regexp.new(rex)
+    rex = Flor.to_regex(rex)
 
     [ rex, str ]
   end

data/lib/flor/pcore/move.rb

@@ -1,13 +1,13 @@
 
 class Flor::Pro::Move < Flor::Procedure
   #
-  # Moves a cursor to a given position
+  # Moves a cursor to a given position, a kind of local goto.
   #
   # ```
   # cursor
-  #   do-this
+  #   do-this _
   #   move to: 'do-that-other-thing'
-  #   do-that _ # got skipped
+  #   do-that _ # gets skipped
   #   do-that-other-thing _
   # ```
 

data/lib/flor/pcore/noeval.rb

@@ -11,6 +11,19 @@ class Flor::Pro::NoEval < Flor::Procedure
   #     [ 1, 2, 3 ]
   #   # f.ret is still 1 here, not [ 1, 2, 3 ]
   # ```
+  #
+  # Could be useful when determining on the fly what the "parent"
+  # procedure should be.
+  # ```
+  # set head
+  #   case (size f.customers)
+  #     0;          noeval
+  #     [ 1, 10 ];  concurrence
+  #     else;       sequence
+  # head
+  #   task 'a'
+  #   task 'b'
+  # ```
 
   name 'noeval'
 

data/lib/flor/pcore/not.rb

@@ -1,5 +1,21 @@
 
 class Flor::Pro::Not < Flor::Procedure
+  #
+  # `not` negates its last child (or its last unkeyed attribute)
+  #
+  # ```
+  # not _      # --> true
+  # not true   # --> false
+  # not false  # --> true
+  # not 0      # --> false
+  # not 1      # --> false
+  # ```
+  #
+  # ```
+  # not
+  #   true
+  #   false  # --> true
+  # ```
 
   name 'not'
 

data/lib/flor/pcore/on.rb

@@ -0,0 +1,172 @@
+
+class Flor::Pro::On < Flor::Macro
+  #
+  # Catches signals or errors.
+  #
+  # ## signals
+  #
+  # Turns
+  # ```
+  # on 'approve'
+  #   task 'bob' mission: 'gather signatures'
+  # ```
+  # into
+  # ```
+  # trap point: 'signal', name: 'approve'
+  #   def msg
+  #     task 'bob' mission: 'gather signatures'
+  # ```
+  #
+  # It's OK trapping multiple signal names:
+  # ```
+  # on [ /^bl/ 'red' 'white' ]
+  #   task 'bob' mission: "order can of $(sig) paint"
+  # ```
+  #
+  # ## error
+  #
+  # "on" understands `on error` with a block. It in facts turns:
+  # ```
+  # sequence
+  #   on error
+  #     push f.l err.msg # a block with an `err` variable
+  #   # ...
+  # ```
+  # into:
+  # ```
+  # sequence
+  #   on_error
+  #     def err # a anonymous function definition with an `err` argument
+  #       push f.l err.msg
+  #   # ...
+  # ```
+  #
+  # Please note that "error" in `on error` is not quoted, nor double quoted.
+  # If it were, it would trap the signal named "error".
+  #
+  #
+  # ## cancel
+  #
+  # "on" understands `on cancel` with a block. It in facts turns:
+  # ```
+  # sequence
+  #   on cancel
+  #     push f.l msg # a block with a `msg` variable
+  #   # ...
+  # ```
+  # into:
+  # ```
+  # sequence
+  #   on_cancel
+  #     def msg # a anonymous function definition with a `msg` argument
+  #       push f.l msg
+  #   # ...
+  # ```
+  #
+  # Please note that "cancel" in `on cancel` is not quoted, nor double quoted.
+  # If it were, it would trap the signal named "cancel".
+  #
+  #
+  # ## timeout
+  #
+  # `on timeout` turns:
+  # ```
+  # sequence timeout: '1w'
+  #   on timeout
+  #     push f.l msg # a block with a `msg` variable
+  #   # ...
+  # ```
+  # into:
+  # ```
+  # sequence timeout: '1w'
+  #   on_timeout
+  #     def msg # a anonymous function definition with a `msg` argument
+  #       push f.l msg
+  #   # ...
+  # ```
+  #
+  # Please note that "timeout" in `on timeout` is not quoted, nor double quoted.
+  # If it were, it would trap the signal named "timeout".
+  #
+  #
+  # ## see also
+  #
+  # Trap and signal.
+
+  name 'on'
+
+  def rewrite_tree
+
+    if att = find_catch # 22
+      rewrite_as_catch_tree(att)
+    else
+      rewrite_as_trap_tree
+    end
+  end
+
+  protected
+
+  CATCHES = %w[ error cancel timeout ]
+
+  def find_catch
+
+    att_children
+      .each_with_index { |t, i|
+        tt = t[1].is_a?(Array) && t[1].length == 1 && t[1].first
+        return [ tt[0], i ] if tt && tt[1] == [] && CATCHES.include?(tt[0]) }
+
+    nil
+  end
+
+  def rewrite_as_catch_tree(att)
+
+    flavour, index = att
+
+    atts = att_children
+    atts.delete_at(index)
+
+    l = tree[2]
+
+    th = [ "on_#{flavour}", [], l, *tree[3] ]
+    atts.each { |ac| th[1] << Flor.dup(ac) }
+
+    td = [ 'def', [], l ]
+    td[1] << [ '_att', [ [ 'msg', [], l ] ], l ]
+    td[1] << [ '_att', [ [ 'err', [], l ] ], l ] if flavour == 'error'
+    non_att_children.each { |nac| td[1] << Flor.dup(nac) }
+
+    th[1] << td
+
+    th
+  end
+
+  def rewrite_as_trap_tree
+
+    atts = att_children
+    signame_i = atts.index { |at| at[1].size == 1 }
+
+    fail Flor::FlorError.new("signal name not found in #{tree.inspect}", self) \
+      unless signame_i
+
+    tname = atts[signame_i]
+    tname = Flor.dup(tname[1][0])
+    atts.delete_at(signame_i)
+
+    l = tree[2]
+
+    th = [ 'trap', [], l, *tree[3] ]
+    th[1] << [ '_att', [ [ 'point', [], l ], [ '_sqs', 'signal', l ] ], l ]
+    th[1] << [ '_att', [ [ 'name', [], l ], tname ], l ]
+    th[1] << [ '_att', [ [ 'payload', [], l ], [ '_sqs', 'event', l ] ], l ]
+    atts.each { |ac| th[1] << Flor.dup(ac) }
+
+    td = [ 'def', [], l ]
+    td[1] << [ '_att', [ [ 'msg', [], l ] ], l ]
+    non_att_children.each { |nac| td[1] << Flor.dup(nac) }
+
+    th[1] << td
+
+    th
+  end
+end
+

data/lib/flor/pcore/on_cancel.rb

@@ -0,0 +1,54 @@
+
+class Flor::Pro::OnCancel < Flor::Procedure
+  #
+  # Counterpart to the on_cancel: attribute.
+  #
+  # ```
+  # set f.l []
+  # sequence
+  #   on_cancel (def msg \ push f.l "$(msg.point):$(msg.nid)")
+  #   push f.l 0
+  #   cancel '0_1' # cancels the containing sequence
+  #   push f.l 1
+  # push f.l 2
+  # ```
+  # Ends up with `[ 0, 'cancel:0_1', 2 ]` in the field `l`.
+  #
+  # ## on and on_cancel
+  #
+  # "on_cancel" is made to allow for `on cancel`, so that:
+  # ```
+  # sequence
+  #   on cancel
+  #     push f.l msg # a block with a `msg` variable
+  #   # ...
+  # ```
+  # gets turned into:
+  # ```
+  # sequence
+  #   on_cancel
+  #     def msg # a anonymous function definition with a `msg` argument
+  #       push f.l msg
+  #   # ...
+  # ```
+  #
+  #
+  # ## see also
+  #
+  # On, on_error.
+
+  name 'on_cancel'
+
+  def pre_execute
+
+    unatt_unkeyed_children
+  end
+
+  def receive_non_att
+
+    store_on(:cancel)
+
+    super
+  end
+end
+