flor 0.14.0 → 0.15.0

data/lib/flor/pcore/for_each.rb

@@ -0,0 +1,65 @@
+
+require 'flor/pcore/iterator'
+
+
+class Flor::Pro::ForEach < Flor::Pro::Iterator
+  #
+  # Calls a function for each element in the argument collection.
+  #
+  # When the "for-each" ends, `f.ret` is pointing back to the argument
+  # collection.
+  #
+  # ```
+  # set l []
+  # for-each [ 0 1 2 3 4 5 6 7 ]
+  #   def x
+  #     pushr l (2 * x) if x % 2 == 0
+  # ```
+  # the var `l` will yield `[ 0, 4, 8, 12 ]` after the `for-each`
+  # the field `ret` will yield `[ 0, 1, 2, 3, 4, 5, 6, 7 ]`.
+  #
+  # ```
+  # set r []
+  # for-each { a: 'A', b: 'B', c: 'C' }
+  #   def k v i l  # key, val, idx, len
+  #     pushr r (+ k v (+ i 1) '/' l)
+  # ```
+  # the var `r` will yield `[ 'aA1/3', 'bB2/3', 'cC3/3' ]` after the `for-each`
+  # the field `ret` will yield `{ 'a': 'A', 'b': 'B', '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
+  #
+  # each.
+
+  name 'for-each'
+
+  protected
+
+  def pre_iterator
+
+    # nothing to do
+  end
+
+  def receive_iteration
+
+    # nothing to do
+  end
+
+  def iterator_result
+
+    @node['ocol']
+      # back to the original collection
+  end
+end
+

data/lib/flor/pcore/includes.rb

@@ -0,0 +1,32 @@
+
+class Flor::Pro::Includes < Flor::Procedure
+
+  name 'includes?'
+
+  def pre_execute
+
+    @node['rets'] = []
+
+    unatt_unkeyed_children
+  end
+
+  def receive_last
+
+    col = nil
+    elt = :nil
+
+    @node['rets'].each do |ret|
+      if col == nil && (ret.is_a?(Array) || ret.is_a?(Hash))
+        col = ret
+      elsif elt == :nil
+        elt = ret
+      end
+    end
+
+    fail Flor::FlorError.new('missing collection', self) if col == nil
+    fail Flor::FlorError.new('missing element', self) if elt == :nil
+
+    wrap_reply('ret' => col.include?(elt))
+  end
+end
+

data/lib/flor/pcore/inject.rb

@@ -0,0 +1,55 @@
+
+require 'flor/pcore/iterator'
+
+
+class Flor::Pro::Inject < Flor::Macro::Iterator
+  #
+  # Inject is a simplified version of [reduce](reduce.md).
+  #
+  # Inject takes a collection and a block. It reduces the collection
+  # to a single result thanks to the block.
+  #
+  # The block is run for each element in the collection, it's passed
+  # `res` and `elt`. `res` is the result, the accumulator, `elt`
+  # is the current element in the collection.
+  #
+  # The block must return the result for the next iteration.
+  #
+  # ```
+  # inject [ '0', 1, 'b', 3 ]
+  #   res + elt
+  # # --> "01b3"
+  # ```
+  #
+  # An initial value is accepted (generally after the collection)
+  #
+  # ```
+  # inject [ 0, 1, 2, 3, 4 ] 10
+  #   res + elt
+  # # --> 20
+  # ```
+  #
+  # ## 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
+  #
+  # Reduce.
+
+  name 'inject'
+
+  def rewrite_tree
+
+    rewrite_iterator_tree('reduce')
+  end
+end
+

data/lib/flor/pcore/iterator.rb

@@ -0,0 +1,151 @@
+
+class Flor::Pro::Iterator < Flor::Procedure
+
+  def pre_execute
+
+    @node['vars'] ||= {}
+
+    @node['args'] = [] # before iterating, arguments are collected
+
+    @node['ocol'] = nil # original collection
+    @node['fun'] = nil # function
+
+    @node['col'] = nil # collection
+    @node['idx'] = -1
+
+    unatt_unkeyed_children
+  end
+
+  def receive_non_att
+
+    if @node['args']
+      receive_argument
+    else
+      receive_iteration
+      iterate
+    end
+  end
+
+  protected
+
+  def receive_argument
+
+    @node['args'] << payload['ret']
+
+    if children[@ncid]
+      execute_child(@ncid)
+    else
+      iterate
+    end
+  end
+
+  def iterate
+
+    prepare_iterations unless @node['ocol']
+
+    return no_iterate unless @node['fun']
+
+    @node['idx'] += 1
+    @node['mtime'] = Flor.tstamp
+
+    return end_iterator if iterator_over?
+
+    apply_iteration
+  end
+
+  def function_mandatory?
+
+    true
+  end
+
+  def prepare_iterations
+
+    prepare_iterator
+
+    @node['args']
+      .each { |a|
+        if Flor.is_func_tree?(a)
+          @node['fun'] ||= a
+        elsif a.is_a?(Array) || a.is_a?(Hash)
+          @node['ocol'] ||= a
+        end }
+
+    @node['ocol'] ||= node_payload_ret
+    ocol = @node['ocol']
+
+    fail Flor::FlorError.new(
+      "function not given to #{heap.inspect}", self
+    ) if function_mandatory? && ( ! @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']) if @node['fun']
+    @node['args'] = nil
+  end
+
+  def prepare_iterator
+
+    @node['res'] = []
+  end
+
+  def apply_iteration
+
+    vars = determine_iteration_vars
+
+    args = vars.values
+    vars.each { |k, v| @node['vars'][k] = v }
+
+    apply(@node['fun'], args, tree[2])
+  end
+
+  def determine_iteration_vars
+
+    idx = @node['idx']
+    elt = @node['col'][idx]
+    len = @node['col'].length
+
+    if @node['ocol'].is_a?(Array)
+      { 'elt' => elt, 'idx' => idx, 'len' => len }
+    else
+      { 'key' => elt[0], 'val' => elt[1], 'idx' => idx, 'len' => len }
+    end
+  end
+
+  def iterator_over?
+
+    @node['idx'] == @node['col'].size
+  end
+
+  def end_iterator
+
+    wrap_reply('ret' => iterator_result)
+  end
+end
+
+
+class Flor::Macro::Iterator < Flor::Macro
+
+  def rewrite_iterator_tree(procedure_name)
+
+    atts = att_children
+
+    l = tree[2]
+
+    th = [ procedure_name, [], l, *tree[3] ]
+    atts.each { |ac| th[1] << Flor.dup(ac) }
+
+    if non_att_children.any?
+
+      td = [ 'def', [], l ]
+      td[1] << [ '_att', [ [ 'res', [], l ] ], l ] if procedure_name == 'reduce'
+      td[1] << [ '_att', [ [ 'elt', [], l ] ], l ]
+      non_att_children.each { |nac| td[1] << Flor.dup(nac) }
+
+      th[1] << td
+    end
+
+    th
+  end
+end
+

data/lib/flor/pcore/keys.rb

@@ -0,0 +1,60 @@
+
+class Flor::Pro::Keys < Flor::Procedure
+  #
+  # Returns the "keys" or the "values" of an object.
+  #
+  # ```
+  # keys { a: 'A', b: 'B' }
+  #   # f.ret --> [ 'a', 'b' ]
+  # values { a: 'A', b: 'B' }
+  #   # f.ret --> [ 'A', 'B' ]
+  # ```
+  #
+  # When used against an array, the indexes will be the numerical indexes
+  # 0 to array length - 1.
+  #
+  # ```
+  # keys [ 1, 'to', true ]
+  #   # f.ret -> [ 0, 1, 2 ]
+  # values [ 1, 'to', true ]
+  #   # f.ret -> [ 1, 'to', true ]
+  # ```
+  #
+  # When used against something that is neither an object nor an array
+  # it will fail.
+  #
+  # ## see also
+  #
+  # length
+
+  names %w{ keys values }
+
+  def pre_execute
+
+    @node['ret'] = receive_payload_ret
+
+    unatt_unkeyed_children
+  end
+
+  def receive_last
+
+    ret = @node['ret']
+
+    fail Flor::FlorError.new(
+      "no argument given", self
+    ) if ret.nil?
+    fail Flor::FlorError.new(
+      "received argument of class #{ret.class}, no #{heap}", self
+    ) unless ret.is_a?(Array) || ret.is_a?(Hash)
+
+    r =
+      if ret.is_a?(Hash)
+        heap == 'keys' ? ret.keys : ret.values
+      else
+        heap == 'keys' ? (0..ret.length - 1).to_a : ret
+      end
+
+    wrap_reply('ret' => r)
+  end
+end
+

data/lib/flor/pcore/length.rb

@@ -1,18 +1,45 @@
 
 class Flor::Pro::Length < Flor::Procedure
+  #
+  # Returns the length of its last collection argument or
+  # the length of the incoming f.ret
+  #
+  # ```
+  # length [ 0 1 2 3 ]
+  #   # f.ret ==> 4
+  #
+  # { a: 'A', b: 'B', c: 'C' }
+  # length _
+  #   # f.ret ==> 3
+  # ```
+  #
+  # It will fail unless "length" receives a (non-attribute) argument
+  # that has a length.
+  #
+  # Has the "size" alias.
 
-  name 'length'
+  names %w[ length size ]
 
-  def receive_last
+  def pre_execute
+
+    @node['ret'] = receive_payload_ret
+
+    unatt_unkeyed_children
+  end
+
+  def receive_payload_ret
 
     r = payload['ret']
+    r.respond_to?(:length) ? r.length : false
+  end
+
+  def receive_last
 
-    payload['ret'] =
-      if r.respond_to?(:length) then r.length
-      else -1
-      end
+    r =
+      @node['ret'] ||
+      fail(Flor::FlorError.new('found no argument that has a length', self))
 
-    super
+    wrap_reply('ret' => r)
   end
 end
 

data/lib/flor/pcore/logo.rb

@@ -1,5 +1,23 @@
 
 class Flor::Pro::Logo < Flor::Procedure
+  #
+  # When `and` evaluates the children and returns false as soon
+  # as one of returns a falsy value. Returns true else.
+  # When `or` evaluates the children and returns true as soon
+  # as one of them returns a trueish value. Returns false else.
+  #
+  # ```
+  # and
+  #   false
+  #   true
+  #     # => evalutes to false
+  # ```
+  #
+  # ```
+  # and (check_this _) (check_that _)
+  # ```
+  #
+  # Gives priority to `and` over `or`.
 
   names %w[ and or ]
 

data/lib/flor/pcore/loop.rb

@@ -13,6 +13,10 @@ class Flor::Pro::Loop < Flor::Pro::Cursor
   # ```
   #
   # Accepts `break` and `continue` like `cursor` does.
+  #
+  # ## see also
+  #
+  # Cursor, break, continue.
 
   name 'loop'