flor 0.15.0 → 0.16.0

data/lib/flor/pcore/sort_by.rb

@@ -0,0 +1,67 @@
+
+class Flor::Pro::SortBy < Flor::Pro::Iterator
+  #
+  # Takes a collection and a function and returns the collection
+  # sorted by the value returned by the function.
+  #
+  # ```
+  # sort_by [ { n: 1 } { n: 0 } { n: 4 } { n: 7 } ] (def e \ e.n)
+  #   # OR
+  # sort_by (def e \ e.n) [ { n: 1 } { n: 0 } { n: 4 } { n: 7 } ]
+  #   #
+  #   # => [ { 'n' => 0 }, { 'n' => 1 }, { 'n' => 4 }, { 'n' => 7 } ]
+  # ```
+  #
+  # ## function parameters
+  #
+  # If the collection is an array, the function signature may look like:
+  # ```
+  # def f(elt, idx, len)
+  #   # elt: the element
+  #   # idx: the index of the element (an integer starting at 0)
+  #   # len: the length of the array being sorted
+  # ```
+  # If the collection is an object:
+  # ```
+  # def f(key, val, idx, len)
+  #   # key: the key for the entry
+  #   # val: the value for the entry
+  #   # idx: the index of the entry (an integer starting at 0)
+  #   # len: the number of keys/entries in the object
+  # ```
+  #
+  # Once the function has returning what value to rank/sort by, the
+  # sorting is done behind the scene by a (Ruby) sort. If the
+  # values returned are heterogeneous, the values are turned into
+  # their JSON representation before the sorting happens.
+  #
+  # ## see also
+  #
+  # sort, reverse, and shuffle
+
+  name 'sort_by'
+
+  protected
+
+  def receive_iteration
+
+    @node['res'] << payload['ret']
+  end
+
+  def iterator_result
+
+    res = @node['res']
+
+    classes = res.collect(&:class).uniq
+
+    res = res.collect { |e| e.is_a?(String) ? e : JSON.dump(e) } \
+      if classes.count > 1 || [ Hash ].include?(classes[0])
+
+    r = res.zip(@node['ocol'])
+      .sort_by(&:first)
+      .collect(&:last)
+
+    @node['ocol'].is_a?(Hash) ? Hash[r] : r
+  end
+end
+

data/lib/flor/pcore/split.rb

@@ -0,0 +1,39 @@
+
+class Flor::Pro::Split < Flor::Procedure
+
+  names %w[ split ]
+
+  def pre_execute
+
+    @node['rets'] = []
+
+    unatt_unkeyed_children
+  end
+
+  def receive_last
+
+    str = nil
+    rex = nil
+      #
+    (@node['rets'] + [ node_payload_ret ])
+      .each { |r|
+        break if str && rex
+        if r.is_a?(String)
+          if str == nil
+            str = r
+          else
+            rex ||= r
+          end
+        elsif Flor.is_regex_tree?(r)
+          rex = Flor.to_regex(r)
+        end }
+      #
+    rex ||= /\s+/
+
+    fail Flor::FlorError.new("found no string to split", self) \
+      if str == nil
+
+    wrap('ret' => str.split(rex))
+  end
+end
+

data/lib/flor/pcore/stall.rb

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

data/lib/flor/pcore/strings.rb

@@ -0,0 +1,123 @@
+
+class Flor::Pro::Strings < Flor::Procedure
+  #
+  # "downcase", "upcase", "capitalize", etc.
+  #
+  # "downcase", "lowercase", "lowcase",
+  # "upcase", "uppercase",
+  # "capitalize",
+  # "snakecase", "snake_case",
+  # "trim", "strip"
+  #
+  # ```
+  # downcase 'HELLO'           # => 'hello'
+  # 'HELLO'; downcase _        # => 'hello'
+  # 'HELLO'; downcase 'WORLD'  # => 'world'
+  # # ...
+  # downcase 'WORLD'            # => 'world'
+  # downcase 'WORLD' cap: true  # => 'World'
+  # # ...
+  # capitalize 'hello world'  # => 'Hello World'
+  # ```
+  #
+  # The `cap:` attribute, when set to something trueish, will make sure the
+  # resulting string(s) first char is capitalized. Not that "capitalize" itself
+  # will capitalize all the words (unlike Ruby's `String#capitalize`).
+  #
+  # ## objects and arrays
+  #
+  # Please note:
+  #
+  # ```
+  # [ "A" "BC" "D" ]; downcase _    # => [ 'a' 'bc' 'd' ]
+  # { a: "A" b: "BC" }; downcase _  # => { a: 'a', b: 'bc' }
+  # ```
+  #
+  # ## see also
+  #
+  # length, reverse
+
+  names %w[
+    downcase lowercase lowcase
+    upcase uppercase
+    capitalize
+    trim strip
+    snakecase snake_case
+    camelcase camelCase ]
+
+  def pre_execute
+
+    @node['ret'] = nil
+    @node['atts'] = []
+
+    unatt_unkeyed_children
+  end
+
+  def receive_payload_ret; payload['ret']; end # don't duplicate the ret
+
+  def receive_last
+
+    met =
+      case heap
+      when 'downcase', 'lowercase', 'lowcase' then :downcase
+      when 'upcase', 'uppercase' then :upcase
+      when 'capitalize' then :capitalize
+      when 'strip', 'trim' then :strip
+      when 'snakecase', 'snake_case' then :snakecase
+      when 'camelcase', 'camelCase' then :camelcase
+      else fail NotImplementedError.new("#{heap.inspect} not implemented")
+      end
+    ret =
+      process(
+        met,
+        @node['ret'] || node_payload_ret,
+        att('cap', 'capitalize'))
+
+    wrap('ret' => ret)
+  end
+
+  protected
+
+  def process(met, o, cap)
+
+    r =
+      case o
+      when String then StringWrapper.new(o).send(met)
+      when Array then o.collect { |e| process(met, e, cap) }
+      when Hash then o.inject({}) { |h, (k, v)| h[k] = process(met, v, cap); h }
+      else o
+      end
+
+    cap ?
+      r.capitalize :
+      r
+  end
+
+  class StringWrapper
+    extend ::Forwardable
+
+    def_delegators :@s, :downcase, :upcase, :strip
+
+    def initialize(s); @s = s; end
+
+    def camelcase
+
+      @s
+        .gsub(/_(.)/) { |_| $1.upcase }
+    end
+
+    def capitalize
+
+      @s
+        .gsub(/\b[a-z]/) { |c| c.upcase }
+    end
+
+    def snakecase
+
+      @s
+        .gsub(/([a-z])([A-Z])/) { |_| $1 + '_' + $2.downcase }
+        .gsub(/([A-Z])/) { |c| c.downcase }
+    end
+  end
+end
+

data/lib/flor/pcore/timestamp.rb

@@ -0,0 +1,34 @@
+
+class Flor::Pro::TimeStamp < Flor::Procedure
+  #
+  # Places a string timestamp in f.ret.
+  #
+  # ## timestamp
+  #
+  # Places the current UTC timestamp into `f.ret`.
+  #
+  # ```
+  # set f.timestamp  # set the field "timestamp" to
+  #   timestamp _    # something like "2018-08-13T08:04:06Z"
+  # ```
+  #
+  # ## ltimestamp
+  #
+  # ```
+  # set f.timestamp  # set the field "timestamp" to
+  #   ltimestamp _    # something like "2018-08-13T10:04:06"
+  # ```
+
+  names %w[ timestamp ltimestamp ]
+
+  def receive_last
+
+    payload['ret'] =
+      heap[0, 1] == 'l' ?
+      Time.now.strftime('%Y-%m-%dT%H:%M:%S') :
+      Flor.ststamp
+
+    wrap
+  end
+end
+

data/lib/flor/pcore/to_array.rb

@@ -1,8 +1,7 @@
 
 class Flor::Pro::ToArray < Flor::Procedure
   #
-  # "to-array", turns an argument into an array, "to-object" turns it into
-  # an object.
+  # Turns the argument into an array or an object.
   #
   # ```
   # to-array [ 0 1 2 ]
@@ -48,7 +47,7 @@ class Flor::Pro::ToArray < Flor::Procedure
     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)
+      unless Flor.is_collection?(r)
 
     fail Flor::FlorError.new('to-object expects array with even length', self) \
       if r.is_a?(Array) && r.length.odd?

data/lib/flor/pcore/twig.rb

@@ -6,7 +6,7 @@ class Flor::Pro::Twig < Flor::Procedure
   def pre_execute
 
     unatt_unkeyed_children
-    stringify_first_child
+    rep_first_child
   end
 
   def receive_first

data/lib/flor/pcore/type_of.rb

@@ -0,0 +1,37 @@
+
+class Flor::Pro::TypeOf < Flor::Procedure
+  #
+  # returns the type of argument or the incoming f.ret.
+  #
+  # ```
+  # type-of "hello"   # ==> 'string'
+  # type-of 1         # ==> 'number'
+  # type-of 1.1       # ==> 'number'
+  # type-of [ 'a' 1 ] # ==> 'array'
+  # type-of { a: 1 }  # ==> 'object'
+  #
+  # type {}    # ==> 'object'
+  # type true  # ==> 'boolean'
+  # ```
+  #
+  # ## see also
+  #
+  # array?, number?, ...
+
+  names %w[ type-of type ]
+
+  def pre_execute
+
+    @node['ret'] = receive_payload_ret
+
+    unatt_unkeyed_children
+  end
+
+  def receive_payload_ret; payload['ret']; end # don't duplicate the ret
+
+  def receive_last
+
+    wrap('ret' => Flor.type(@node['ret']).to_s)
+  end
+end
+

data/lib/flor/pcore/until.rb

@@ -1,8 +1,7 @@
 
 class Flor::Pro::Until < Flor::Procedure
   #
-  # `until` loops until a condition evaluates to true.
-  # `while` loops while a condition evaluates to true.
+  # Loops until or while a condiation evalutates to true.
   #
   # ```
   # set i 0
@@ -104,7 +103,8 @@ class Flor::Pro::Until < Flor::Procedure
 
   def cancel_when_closed
 
-    return [] unless @message['flavour'] == 'break'
+    return cancel if node_status_flavour == 'on-error'
+    return [] if @message['flavour'] != 'break'
 
     cancel
   end

data/lib/flor/punit/cancel.rb

@@ -43,8 +43,8 @@ class Flor::Pro::Cancel < Flor::Procedure
 
     targets =
       @node['atts']
-        .select { |k, v| k == nil }
-        .inject([]) { |a, (k, v)|
+        .select { |k, _| k == nil }
+        .inject([]) { |a, (_, v)|
           v = Array(v)
           a.concat(v) if v.all? { |e| e.is_a?(String) }
           a } +
@@ -55,7 +55,7 @@ class Flor::Pro::Cancel < Flor::Procedure
     nids += tags_to_nids(tags)
     nids = nids.uniq
 
-    fla = @node['heap']
+    fla = heap
 
     messages = nids
       .collect { |nid| wrap_cancel('nid' => nid, 'flavour' => fla)[0] }

data/lib/flor/punit/ccollect.rb

@@ -1,5 +1,34 @@
 
 class Flor::Pro::Ccollect < Flor::Macro::Iterator
+  #
+  # A concurrent version of [collect](collect.md).
+  #
+  # Whereas "collect" executes its children one by one and then yields
+  # an array with the result of each child, "ccollect" executes the children
+  # concurrently.
+  #
+  # In the example below, Alice, Bob, and Charly are concurrently tasked
+  # with some analysis work. The field `ret` coming out of the "ccollect"
+  # will be an array composed of the `f.ret` of each "task" call.
+  # ```
+  # sequence
+  #   ccollect [ 'alice' 'bob' 'charly' ]
+  #     notify elt 'you received a task'
+  #     task elt "initiate analysis for project $(project.id) as #$(idx + 1)"
+  # ```
+  #
+  # Like "collect", the block iterating over an array will receive the `elt`,
+  # `idx` and `len` variables (current element, current element index (starting
+  # at zero), and length of the collection).
+  #
+  # When iterating over an object (a hash), the variables will be `key`, `val`,
+  # `idx`, and `len`.
+  #
+  # "ccollect" is actually a macro rewriting itself to a [cmap](cmap.md).
+  #
+  # ## see also
+  #
+  # Collect, map, cmap.
 
   name 'ccollect'
 

data/lib/flor/punit/cmap.rb

@@ -1,56 +1,112 @@
 
 class Flor::Pro::Cmap < Flor::Procedure
+  #
+  # Concurrent version of "map". Spins a concurrent child for each
+  # element of the incoming/argument collection.
+  #
+  # ```
+  # cmap [ 1 2 3 ]
+  #   def x \ * x 2
+  # # yields: [ 2, 4, 6 ]
+  #
+  # [ 1 2 3 ]
+  # cmap (def x \ * x 2)
+  # # yields: [ 2, 4, 6 ]
+  #
+  # define double x \ * x 2
+  # cmap double [ 1 2 3 ]
+  # # yields: [ 2, 4, 6 ]
+  # ```
+  #
+  # "cmap" is over when all the children have answered. For more complex
+  # concurrent behaviours, look at [concurrence](concurrence.md).
+  #
+  # ## see also
+  #
+  # Map, concurrence.
 
   name 'cmap'
 
   def pre_execute
 
-    @node['atts'] = []
+    @node['args'] = []
+    @node['result'] = nil
 
-    @node['fun'] = nil
-    @node['col'] = []
+    unatt_unkeyed_children
   end
 
   def receive_non_att
 
-    if @node['fun']
-      receive_elt
+    if @node['result']
+      receive_ret
     else
-      receive_fun
+      @node['args'] << payload['ret']
+      super
+    end
+  end
+
+  def receive_last
+
+    if @node['result']
+      super
+    else
+      receive_last_argument
     end
   end
 
   protected
 
-  def receive_fun
+  def receive_last_argument
 
-    fun = payload['ret']
+    col = nil
+    fun = nil
+    @node['args'].each do |a|
+      if Flor.is_func_tree?(a)
+        fun = a
+      elsif Flor.is_collection?(a)
+        col = a
+      end
+    end
+    col ||= node_payload_ret
 
-    fail Flor::FlorError.new("'#{tree[0]}' expects a function", self) \
+    fail Flor::FlorError.new("collection not given to #{heap.inspect}", self) \
+      unless Flor.is_collection?(col)
+    return wrap('ret' => col) \
       unless Flor.is_func_tree?(fun)
 
-    @node['fun'] = fun
+    @node['cnt'] = col.size
+    @node['result'] = []
 
-    att(nil)
+    col
       .collect
       .with_index { |e, i|
-        apply(fun, [ e, i ], tree[2], vars: { 'idx' => i }) }
+        apply(fun, determine_iteration_args(col, i), tree[2]) }
       .flatten(1)
   end
 
-  def receive_elt
+  def determine_iteration_args(col, idx)
 
-    idx =
-      (message['rvars'] && message['rvars']['idx']) ||
-      Flor.sub_nid(message['from']) - 1 # fall back :-(
+    args =
+      if col.is_a?(Array)
+        [ [ 'elt', col[idx] ] ]
+      else
+        e = col.to_a[idx]
+        [ [ 'key', e[0] ], [ 'val', e[1] ] ]
+      end
+    args << [ 'idx', idx ]
+    args << [ 'len', col.length ]
+
+    args
+  end
 
-    @node['col'][idx] = payload['ret']
+  def receive_ret
 
-    return [] if cnodes_any?
+    @node['result'] << [ from_sub_nid, payload['ret'] ]
+    @node['cnt'] = @node['cnt'] - 1
 
-    payload['ret'] = @node['col']
+    return [] if @node['cnt'] > 0 # still waiting for answers
 
-    wrap
+    wrap('ret' => @node['result'].sort_by(&:first).collect(&:last)) # over
   end
 end