flor 0.14.0 → 0.15.0

data/lib/flor/pcore/on_error.rb

@@ -0,0 +1,68 @@
+
+class Flor::Pro::OnError < Flor::Procedure
+  #
+  # Counterpart to the on_error: attribute.
+  #
+  # Takes a function definition (or a variable pointing to one of them)
+  # and makes sure the function is called when an error occurs at the
+  # current level or below.
+  #
+  # ```
+  # sequence
+  #   set f.l []
+  #   on_error (def err \ push f.l err.error.msg)
+  #   push f.l 0
+  #   push f.l x # <-- will fail because `x` is unknown
+  #   push f.l 1
+  # ```
+  # Where the field `l` ends up containing
+  # `[ 0, "don't know how to apply \"x\"" ]`.
+  #
+  # ```
+  # set f.l []
+  #
+  # define error_handler err
+  #   push f.l err.error.msg
+  #
+  # sequence
+  #   on_error error_handler
+  #   # ...
+  # ```
+  #
+  # ## on and on_error
+  #
+  # "on_error" is made to allow for `on error`, so that:
+  # ```
+  # sequence
+  #   on error
+  #     push f.l err.msg # a block with an `err` variable
+  #   # ...
+  # ```
+  # gets turned into:
+  # ```
+  # sequence
+  #   on_error
+  #     def err # a anonymous function definition with an `err` argument
+  #       push f.l err.msg
+  #   # ...
+  # ```
+  #
+  # ## see also
+  #
+  # On, on_cancel.
+
+  name 'on_error'
+
+  def pre_execute
+
+    unatt_unkeyed_children
+  end
+
+  def receive_non_att
+
+    store_on(:error)
+
+    super
+  end
+end
+

data/lib/flor/pcore/rand.rb

@@ -30,8 +30,8 @@ class Flor::Pro::Rand < Flor::Procedure
 
     a, b = determine_bounds
 
-    fail ArgumentError.new(
-      "'rand' expects an integer or a float"
+    fail Flor::FlorError.new(
+      "'#{tree[0]}' expects an integer or a float", self
     ) unless is_number?(a) && is_number?(b)
 
     payload['ret'] = Random.rand(a...b)

data/lib/flor/pcore/range.rb

@@ -49,7 +49,8 @@ class Flor::Pro::Range < Flor::Procedure
     edn = aedn if aedn
     ste = aste if aste
 
-    fail ArgumentError.new("#{@node['heat0']} step is 0") if ste == 0
+    fail Flor::FlorError.new("#{@node['heat0']} step is 0", self) \
+      if ste == 0
 
     #payload['ret'] = (sta..edn - 1).step(ste).to_a
       # doesn't accept negative steps

data/lib/flor/pcore/reduce.rb

@@ -0,0 +1,124 @@
+
+class Flor::Pro::Reduce < Flor::Pro::Iterator
+  #
+  # Reduce takes a collection and a function. It reduces the collection
+  # to a single result thanks to the function.
+  #
+  # ```
+  # reduce [ '0', 1, 'b', 3 ]
+  #   def result element
+  #     result + element
+  # # --> "01b3"
+  # ```
+  #
+  # An initial value is accepted (generally after the collection)
+  #
+  # ```
+  # reduce [ 0, 1, 2, 3, 4 ] 10
+  #   def result i \ result + i
+  # # --> 20
+  # ```
+  #
+  # Passing a proc is OK too, but, in the case of a mathematical expression
+  # prefixing it with `v.` prevents premature rewriting...
+  #
+  # ```
+  # reduce [ 0, 1, 2, 3, 4 ] 10 v.+
+  # # --> 20
+  # ```
+  #
+  # ## 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 `[ result, value, index, length ]` for arrays.
+  # They are `[ result, key, value, index, length ]` for objects.
+  #
+  # The corresponding `res`, `key`, `val`, `idx` and `len` variables are also
+  # set in the closure for the function call.
+  #
+  # ## see also
+  #
+  # Inject.
+
+  name 'reduce'
+
+  protected
+
+  def prepare_iterations
+
+    @node['args']
+      .each { |a|
+        if Flor.is_func_tree?(a)
+          @node['fun'] ||= a
+        elsif Flor.is_proc_tree?(a)
+          @node['fun'] ||= proc_to_fun(a)
+        elsif a.is_a?(Array) || a.is_a?(Hash)
+          @node['ocol'] ||= a
+        else
+          @node['res'] ||= a
+        end }
+
+    @node['ocol'] ||= node_payload_ret
+    ocol = @node['ocol']
+
+    fail Flor::FlorError.new(
+      "function not given to #{heap.inspect}", self
+    ) unless @node['fun']
+    fail Flor::FlorError.new(
+      "collection not given to #{heap.inspect}", self
+    ) unless ocol.is_a?(Array) || ocol.is_a?(Hash)
+
+    @node['col'] = Flor.to_coll(@node['ocol'])
+
+    @node['res'] ||= @node['col'].shift
+
+    @node['args'] = nil
+  end
+
+  def determine_iteration_vars
+
+    res = @node['res']
+    idx = @node['idx']
+    elt = @node['col'][idx]
+    len = @node['col'].length
+
+    if @node['ocol'].is_a?(Array)
+      { 'res' => res, 'elt' => elt,
+        'idx' => idx, 'len' => len }
+    else
+      { 'res' => res, 'key' => elt[0], 'val' => elt[1],
+        'idx' => idx, 'len' => len }
+    end
+  end
+
+  def receive_iteration
+
+    @node['res'] = payload['ret']
+  end
+
+  def iterator_result
+
+    @node['res']
+  end
+
+  def proc_to_fun(prc)
+
+    h = prc[1]['proc']
+    l = tree[2]
+
+    [ '_func',
+      { 'nid' => "#{nid}_0_1",
+        'tree' =>
+          [ 'def', [
+            [  '_att', [ [ 'r', [], l ] ], l ],
+            [  '_att', [ [ 'x', [], l ] ], l ],
+            [  h, [ [ 'r', [], l ], [ 'x', [], l ] ], l ]
+          ], l ],
+        'cnid' => '0',  #
+        'fun' => 0 },   # TODO really?
+      l ]
+  end
+end
+

data/lib/flor/pcore/reverse.rb

@@ -0,0 +1,46 @@
+
+class Flor::Pro::Reverse < Flor::Procedure
+  #
+  # Reverses an array or a string.
+  #
+  # ```
+  # reverse [ 0, 2, 4 ]
+  #   # --> sets f.ret to [ 4, 2, 0 ]
+  # reverse "melimelo"
+  #   # --> sets f.ret to "olemilem"
+  # ```
+  #
+  # Reverses f.ret if there are no arguments
+  # ```
+  # [ 5, 6, 4 ]   # sets f.ret to [ 5, 6, 4 ]
+  # reverse _     # sets f.ret to [ 4, 6, 5 ]
+  # ```
+  #
+  # Will fail if it finds nothing reversable.
+
+  name 'reverse'
+
+  def pre_execute
+
+    @node['ret'] = receive_payload_ret
+
+    unatt_unkeyed_children
+  end
+
+  def receive_payload_ret
+
+    r = payload['ret']
+    r.respond_to?(:reverse) ? r.reverse : false
+  end
+
+  def receive_last
+
+    r =
+      @node['ret'] ||
+      fail(
+        Flor::FlorError.new('found no argument that could be reversed', self))
+
+    wrap_reply('ret' => r)
+  end
+end
+

data/lib/flor/pcore/select.rb

@@ -0,0 +1,72 @@
+
+require 'flor/pcore/iterator'
+
+
+class Flor::Pro::Select < Flor::Macro::Iterator
+  #
+  # Filters a collection
+  #
+  # "select" and "reject" are the 'block-oriented' children of
+  # "filter" and "filter-out" respectively.
+  #
+  # ```
+  # select [ 1, 2, 3, 4, 5 ]
+  #   = (elt % 2) 1
+  #
+  # # f.ret --> [ 1, 3, 5 ]
+  # ```
+  #
+  # Note that the equivalent "filter" is:
+  # ```
+  # filter [ 1, 2, 3, 4, 5 ]
+  #   def x
+  #     = (x % 2) 1
+  # ```
+  #
+  # The blocks understand `elt` (the current element), `idx` (the current
+  # zero-based index), and `key` (the current key for an object/hash).
+  #
+  # ## with objects (hashes)
+  #
+  # ```
+  # select { a: 'A', b: 'B', c: 'C', d: 'D' }
+  #   key == 'a' or val == 'C' or idx == 3
+  #
+  # # f.ret --> { 'a' => 'A', 'c' => 'C', 'd' => 'D' }
+  # ```
+  #
+  # ## reject
+  #
+  # "reject" is the negative of "select".
+  #
+  # ```
+  # reject [ 1, 2, 3, 4, 5 ]
+  #   (elt % 2) == 0
+  #
+  # # f.ret --> [ 1, 3, 5 ]
+  # ```
+  #
+  # ## iterating blocks
+  #
+  # Iterating blocks are given 3 to 4 local variables.
+  #
+  # A block iterating over an array will receive `elt` (the current element
+  # of the iteration), `idx` (the zero-based index of the current element),
+  # and `len` (the length of the array).
+  #
+  # A block iterating over an object will receive `key` (the current string
+  # key), `val` (the current value), `idx` (the zero-based index of the
+  # current key/val), and `len` (the length of the object).
+  #
+  # ## see also
+  #
+  # filter, map, reject, and collect.
+
+  names %w[ select reject ]
+
+  def rewrite_tree
+
+    rewrite_iterator_tree(heap == 'select' ? 'filter' : 'filter-out')
+  end
+end
+

data/lib/flor/pcore/set.rb

@@ -77,6 +77,14 @@ class Flor::Pro::Set < Flor::Procedure
     @node['refs'] = []
   end
 
+  def execute_child(index=0, sub=nil, h=nil)
+
+    payload['ret'] = node_payload_ret \
+      if children[index]
+
+    super(index, sub, h)
+  end
+
   def receive_non_att
 
     ret = payload['ret']

data/lib/flor/pcore/stall.rb

@@ -1,5 +1,15 @@
 
 class Flor::Pro::Stall < Flor::Procedure
+  #
+  # "stall" is mostly used in flor tests. It simply dead ends.
+  #
+  # It receives its execution message, executes all its attributes but
+  # does not answer to its parent procedure, effectively stalling
+  # its branch of the execution.
+  #
+  # ## see also
+  #
+  # _skip
 
   name 'stall'
 

data/lib/flor/pcore/to_array.rb

@@ -0,0 +1,61 @@
+
+class Flor::Pro::ToArray < Flor::Procedure
+  #
+  # "to-array", turns an argument into an array, "to-object" turns it into
+  # an object.
+  #
+  # ```
+  # to-array [ 0 1 2 ]
+  #   # --> [ 0 1 2 ]  # (left intact)
+  #
+  # to-array 123
+  #   # --> [ 123 ]
+  #
+  # to-array { a: 'A', b: 'B' }
+  #   # --> [ [ 'a', 'A' ], [ 'b', 'B' ] ]
+  # ```
+  #
+  # and
+  #
+  # ```
+  # to-object [ 'a' 'A' 'b' 'B' 'c' 'C' ]
+  #   # --> { 'a': 'A', b: 'B', c: 'C' }
+  # ```
+
+  names %w[ to-array to-object ]
+
+  def pre_execute
+
+    @node['ret'] = receive_payload_ret
+
+    unatt_unkeyed_children
+  end
+
+  def receive_last
+
+    wrap_reply('ret' => (heap == 'to-object') ? to_object : to_array)
+  end
+
+  protected
+
+  def to_array
+
+    Flor.to_coll(@node['ret'])
+  end
+
+  def to_object
+
+    r = @node['ret']
+
+    fail Flor::FlorError.new('to-object wants an array (or an object)', self) \
+      unless r.is_a?(Array) || r.is_a?(Hash)
+
+    fail Flor::FlorError.new('to-object expects array with even length', self) \
+      if r.is_a?(Array) && r.length.odd?
+
+    r = r.each_slice(2).to_a if r.find { |e| ! e.is_a?(Array) }
+
+    Hash[r]
+  end
+end
+

data/lib/flor/pcore/until.rb

@@ -1,5 +1,39 @@
 
 class Flor::Pro::Until < Flor::Procedure
+  #
+  # `until` loops until a condition evaluates to true.
+  # `while` loops while a condition evaluates to true.
+  #
+  # ```
+  # set i 0
+  # until i == 7
+  #   task 'bob' "verify counter ($(i))"
+  #   set i (i + 1)
+  # ```
+  #
+  # ```
+  # set i 0
+  # while i < 7
+  #   task 'bob' "verify counter ($(i))"
+  #   set i (i + 1)
+  # ```
+  #
+  # `until` and `while` understand `break` and `continue`, like `cursor` and
+  # `loop` do.
+  #
+  # ```
+  # until
+  #   false
+  #   push f.l 0
+  #   set outer-break break # alias local break to "outer-break"
+  #   until false
+  #     push f.l 'a'
+  #     outer-break 'x'
+  # ```
+  #
+  # ## see also
+  #
+  # Break, continue, cursor, loop.
 
   names 'until', 'while'