eco-helpers 2.5.10 → 2.6.1

data/lib/eco/data/locations/convert.rb

@@ -8,7 +8,7 @@ module Eco::Data::Locations
     # @return [Eco::CSV::Table]
     def csv_from(filename, encoding: 'utf-8')
       raise ArgumentError, "Expecting String filename. Given: #{filename.class}" unless filename.is_a?(String)
-      raise "Missing #{filename}" unless File.exists?(filename)
+      raise "Missing #{filename}" unless File.exist?(filename)
       Eco::CSV.read(filename, encoding: encoding)
     rescue CSV::MalformedCSVError => e
       if match = e.message.match(/line (?<line>\d+)/i)
@@ -21,11 +21,14 @@ module Eco::Data::Locations
     # @note The steps of usage would be:
     #   1. First **treeify** your input (i.e. `Eco::API::Organization::TagTree#as_json`,
     #     or `treeify(nodes)`
+    # @yield [str_node, node] block for custom output node name
+    # @yiledreturn [String] the node name
     # @param hash_nodes [Array<Hash>] a hierarchical tree of Hash nodes, nested via `nodes`
     # @return [CSV::Table] ready to be made a hierarchical csv tree (i.e. out.to_csv)
-    def hash_tree_to_tree_csv(hash_nodes, out: [], done_ids: [], repeated_ids: [], level: 0)
+    def hash_tree_to_tree_csv(hash_nodes, out: [], done_ids: [], repeated_ids: [], level: 0, attrs: [:id])
       lev  = level + 1
       base = empty_array(level)
+      sattrs = attrs.map(&:to_s)
 
       hash_nodes.each_with_object(out) do |node, out|
         if done_ids.include?(id = node["id"])
@@ -33,8 +36,9 @@ module Eco::Data::Locations
         else
           has_offspring = (children = node["nodes"]) && !children.empty?
           done_ids << id
-          out      << (base.dup << node["id"])
-          hash_tree_to_tree_csv(node["nodes"], out: out, done_ids: done_ids, repeated_ids: repeated_ids, level: lev)
+          str_node = node.values_at(*sattrs).join(" ## ")
+          out      << (base.dup << str_node)
+          hash_tree_to_tree_csv(node["nodes"], out: out, done_ids: done_ids, repeated_ids: repeated_ids, level: lev, attrs: attrs)
         end
       end.tap do |out|
         if level == 0

data/lib/eco/data/locations/node_base/csv_convert.rb

@@ -23,7 +23,7 @@ module Eco::Data::Locations::NodeBase
     #   ready to be parsed as an organization tagtree
     def hash_tree(value, &block)
       return hash_tree_from_csv(value, &block) if value.is_a?(::CSV::Table)
-      return value.as_json                     if value.is_a?(tree_class)
+      return value.as_json(&block)             if value.is_a?(tree_class)
       raise ArgumentError, "Expecting Eco::API::Organization::TagTree or CSV::Table. Given: #{value.class}"
     end
 
@@ -40,8 +40,8 @@ module Eco::Data::Locations::NodeBase
     # @yield [Node] optional custom serializer
     # @yieldreturn [Hash] the serialized Node
     # @return [CSV::Table] a table with L1 to Ln columns ready for dump to csv
-    def csv_tree(value, encoding: 'utf-8', &block)
-      Eco::CSV::Table.new(hash_tree_to_tree_csv(hash_tree(value, &block)))
+    def csv_tree(value, encoding: 'utf-8', attrs: [:id], &block)
+      Eco::CSV::Table.new(hash_tree_to_tree_csv(hash_tree(value, &block), attrs: attrs))
     end
 
     # @note it just converts to an organizational tagtree and uses a helper method.
@@ -51,7 +51,7 @@ module Eco::Data::Locations::NodeBase
     # @return [CSV::Table] a table with a list of nodes and their parents
     def csv_list(value, &block)
       value = org_tree(value, &block) unless value.is_a?(tree_class)
-      Eco::CSV.Table.new(hash_list(value))
+      Eco::CSV::Table.new(hash_list(value))
     end
   end
 end

data/lib/eco/data/locations/node_base/tag_validations.rb

@@ -1,33 +1,43 @@
 module Eco::Data::Locations::NodeBase
   module TagValidations
+    include Eco::Language::AuxiliarLogger
+
     ALLOWED_CHARACTERS = "A-Za-z0-9 &_'\/.-"
     VALID_TAG_REGEX    = /^[#{ALLOWED_CHARACTERS}]+$/
     INVALID_TAG_REGEX  = /[^#{ALLOWED_CHARACTERS}]+/
     VALID_TAG_CHARS    = /[#{ALLOWED_CHARACTERS}]+/
     DOUBLE_BLANKS      = /\s\s+/
 
-    def clean_id(str, notify: true)
+    def clean_id(str, notify: true, ref: '')
       blanks_x2 = has_double_blanks?(str)
       partial   = replace_not_allowed(str)
       remove_double_blanks(partial).tap do |result|
         next unless notify
-        next if invalid_warned?
+        next if invalid_warned?(str)
         if partial != str
           invalid_chars = identify_invalid_characters(str)
-          puts "• (Row: #{self.row_num}) Invalid characters _#{invalid_chars}_ (removed): '#{str}' (converted to '#{result}')"
+          log(:warn) {
+            "• #{ref}Invalid characters _#{invalid_chars}_ <<_removed_: '#{str}' :_converted_>> '#{result}'"
+          }
         elsif blanks_x2
-          puts "• (Row: #{self.row_num}) Double blanks (removed): '#{str}' (converted to '#{result}')"
+          log(:warn) {
+            "• #{ref}Double blanks removed: '#{str}' :_converted_>> '#{result}'"
+          }
         end
-        invalid_warned!
+        invalid_warned!(str)
       end
     end
 
-    def invalid_warned?
-      @invalid_warned ||= false
+    def invalid_warned?(str)
+      invalid_warned[str] ||= false
+    end
+
+    def invalid_warned!(str)
+      invalid_warned[str] = true
     end
 
-    def invalid_warned!
-      @invalid_warned = true
+    def invalid_warned
+      @invalid_warned ||= {}
     end
 
     def has_double_blanks?(str)

data/lib/eco/data/locations/node_base/treeify.rb

@@ -12,14 +12,31 @@ module Eco::Data::Locations::NodeBase
     # @yieldreturn [Hash] custom hash model when treeifying (allows to set more keys/properties).
     # @nodes [Array<NodeBase>] list of nodes
     # @return [Array<Hash>] a hierarchical tree of nested Hashes via `nodes` key.
-    def treeify(nodes, &block)
+    def treeify(nodes, skipped: [], unlinked_trees: [], &block)
       return [] if nodes.empty?
       block ||= nodes.first.class.serializer
-      get_children(nil, parents_hash(nodes), &block)
+      done_ids = {}
+      warns    = []
+      parents  = parents_hash(nodes)
+      get_children(nil, parents, done_ids: done_ids, skipped: skipped, warns: warns, &block).tap do |tree|
+        check_results(
+          tree,
+          nodes,
+          parents,
+          done_ids: done_ids,
+          skipped: skipped,
+          unlinked_trees: unlinked_trees,
+          warns: warns,
+          &block
+        )
+        log(:warn) { warns.join("\n") } unless warns.empty?
+      end
     end
 
     private
 
+    # @return [Hash] where `key`s are all the `parentId` of the nodes
+    #   and `value` and `Array` of those nodes that have that `parentId`
     def parents_hash(nodes)
       nodes.each_with_object({}) do |node, parents|
         (parents[node.parentId] ||= []).push(node)
@@ -32,12 +49,21 @@ module Eco::Data::Locations::NodeBase
     #   3. The above can translate into some
     # @yield [node]
     # @yieldreturn [Hash] custom hash model when treeifying
-    def get_children(node_id, parents, parent: nil, done_ids: {}, level: 0, &block)
+    def get_children(node_id, parents, parent: nil, level: 0, done_ids: {}, skipped: [], warns: [], &block)
       level_ids = []
       (parents[node_id] ||= []).each_with_object([]) do |child, results|
         # Skipping done id. Add proper warnings...
         # => rely on `done_ids` to identify if an `id` has already been done
-        next report_skipped_node(child, parent, done_ids, level, level_ids, parents) if done_ids[child.id]
+        next report_skipped_node(
+          child,
+          parent,
+          done_ids,
+          level,
+          level_ids,
+          parents,
+          skipped: skipped,
+          warns:   warns
+        ) if done_ids[child.id]
 
         # Fill in tracking data
         child.parent        = parent
@@ -52,8 +78,26 @@ module Eco::Data::Locations::NodeBase
         node_hash.merge(yield(child)) if block_given?
         # we must register the `id` before recursing down
         done_ids[child.id] = child
+
+        children = get_children(
+          child.id,
+          parents,
+          parent:   child,
+          done_ids: done_ids,
+          level:    level + 1,
+          skipped:  skipped,
+          warns:    warns,
+          &block
+        ).tap do |desc|
+          if (nil_count = desc.count(nil)) > 0
+            log(:debug) {
+              "get_children gave #{nil_count} nil values for nodes of #{child.id}"
+            }
+          end
+        end
+
         results << node_hash.merge({
-          "nodes" => get_children(child.id, parents, parent: child, done_ids: done_ids, level: level + 1, &block).compact
+          "nodes" => children.compact
         })
       end
     end
@@ -70,8 +114,138 @@ module Eco::Data::Locations::NodeBase
       "#{" " * level}"
     end
 
-    # Gives different warnings, depending the case
-    def report_skipped_node(node, parent, done_ids, level, level_ids, parents)
+    # Method to ensure the results are consistent
+    # @param skipped [Array<NodePlain>] those skipped because repeated
+    #   1. It will add children of them that were skipped. This won't clash with unlinked nodes
+    #     because otherwise would be part of `done_ids` anyway.
+    # @param unlinked_trees [Array<Hash>] by excluding those done and skipped,
+    #   it will treeify the unlinked nodes (the exclusion applies to `parants_hash`)
+    def check_results(tree, nodes, parents, done_ids: {}, skipped: [], unlinked_trees: [], warns: [], &block)
+      update_skipped(skipped, parents, done_ids: done_ids) unless skipped.empty?
+
+      if done_ids.count != nodes.count
+        tracked_nodes       = done_ids.values
+        untracked_nodes     = nodes - tracked_nodes - skipped
+        # skipped keys is inherent, as they were excluded because of id clash with done_ids
+        unlinked_parent_ids = (parents.keys - done_ids.keys).compact
+
+        msg = []
+
+        # The reason of missing nodes in the output tree is unknown!
+        if skipped.empty? && unlinked_parent_ids.empty?
+          msg << "BUG in this library (open issue with maintainers)."
+          msg << "There were no skipped nodes nor missin referred parents, and yet:"
+          msg << "  • the tree nodes count: #{done_ids.count} ..."
+          msg << "  • doesn't match the original nodes count: #{nodes.count}"
+          raise msg.join("\n")
+        end
+
+        unless unlinked_parent_ids.empty?
+          msg << "There are #{unlinked_parent_ids.count} referred parent_id's NOT linked to the root:"
+          msg << "  • total_nodes: #{nodes.count}"
+          msg << "  • tracked_nodes: #{tracked_nodes.count}"
+          msg << "  • untracked_nodes: #{untracked_nodes.count}"
+          msg << "  • unlinked_parents: #{unlinked_parent_ids.count}"
+          msg << "  • skipped (repeated) nodes: #{skipped.count}" unless skipped.empty?
+
+          unlinked_nodes   = nodes - skipped
+          unlinked_parents = parents.slice(*unlinked_parent_ids) # doesn'thave skipped ones
+
+          residual_skipped = []
+          unlinked_trees.concat \
+            get_unlinked_trees(
+              unlinked_nodes,
+              unlinked_parents,
+              done_ids: done_ids,
+              skipped:  residual_skipped,
+              warns:    warns,
+              &block
+            )
+
+          update_skipped(skipped, parents, with: residual_skipped, done_ids: done_ids) unless residual_skipped.empty?
+
+          tracked_nodes       = done_ids.values
+          untracked_nodes     = nodes - tracked_nodes - skipped
+          unlinked_parent_ids = (parents.keys - done_ids.keys).compact
+
+          msg << "After treeifying via the unlinked_parents:"
+          msg << "  • total_nodes: #{nodes.count}"
+          msg << "  • tracked_nodes: #{tracked_nodes.count}"
+          msg << "  • untracked_nodes: #{untracked_nodes.count}"
+          msg << "  • unlinked_parents: #{unlinked_parent_ids.count}"
+          msg << "  • skipped in this step: #{residual_skipped.count}"
+        end
+
+        msg << "  • total skipped (repeated) nodes: #{skipped.count} !!" unless skipped.empty?
+        warns << msg.join("\n")
+        nil
+      end
+    end
+
+    # Treeifies the unlinked nodes by scoping existing parent ids.
+    def get_unlinked_trees(nodes, parents, done_ids: {}, skipped: [], warns: [], &block)
+      node_ids           = nodes.map(&:id)
+      parent_ids         = parents.keys & node_ids
+      missing_parent_ids = parents.keys - parent_ids
+      missing_parents    = parents.slice(*missing_parent_ids)
+      warns << "  • missing_parents: #{missing_parents.count}"
+      nil_parent_nodes   = missing_parents.each_with_object([]) do |(id, nodes), mem|
+        nodes.each {|node| node.parent_id = nil}
+        mem.concat(nodes)
+      end
+      rest_parents = parents.slice(*parent_ids).merge({
+        nil => nil_parent_nodes
+      })
+      get_children(nil, rest_parents, done_ids: done_ids, skipped: skipped, warns: warns, &block)
+    end
+
+    # Same as `get_children` but not performing checks and with
+    # option to retrieve the source nodes (rather than parsing to `Hash`).
+    # @note serves the purpose to identify what linked children got inherently
+    #   skipped, because their parent was skipped.
+    def get_tree_nodes_raw(node_id, parents, src_plain: true, &block)
+      (parents[node_id] ||= []).each_with_object([]) do |child, results|
+        unless src_plain
+          node_hash = {
+            "id"        => child.id,
+            "name"      => child.name,
+            "parent_id" => node_id
+          }
+          node_hash.merge(yield(child)) if block_given?
+        end
+
+        descendants = get_tree_nodes_raw(child.id, parents, src_plain: src_plain, &block).tap do |desc|
+          if (nil_count = desc.count(nil)) > 0
+            puts "get_tree_nodes_raw gave #{nil_count} nil values for nodes of #{child.id}"
+          end
+        end
+
+        if src_plain
+          results.concat(descendants)
+        else
+          results << node_hash.merge({
+            "nodes" => descendants.compact
+          })
+        end
+      end
+    end
+
+    # It goes through the `with` skipped nodes, and adds them to the `skipped` ones
+    #   by including their not tracked/done/included children.
+    def update_skipped(skipped, parents, with: skipped, done_ids: {})
+      raw_skipped_children = with.each_with_object([]) do |node, mem|
+        mem << node
+        mem.concat get_tree_nodes_raw(node.id, parents)
+      end.uniq
+      skipped_children = raw_skipped_children - done_ids.values
+      skipped.concat(skipped_children).uniq!
+      skipped
+    end
+
+    # With given a skipped `node` (repeated `id`), it gives different warnings,
+    # provided that the context in which the double-up `id` happened is identified.
+    def report_skipped_node(node, parent, done_ids, level, level_ids, parents, skipped: [], warns: [])
+      skipped << node
       lev          = level + 1
       done_node    = done_ids[node.id]
       prev_parent  = node.parent
@@ -84,6 +258,9 @@ module Eco::Data::Locations::NodeBase
       row_str      = row_num ? "(Row: #{row_num}) " : ''
       node_str     = "#{row_str}Node '#{node.id}' #{level_msg(lev)} (#{parent_msg(parent)})"
 
+      msg  = []
+      msg << "#{indent(level)}Skipping #{node_str}."
+
       # Implementation integrity guard
       # => as we don't register in `done_ids` those that are skipped,
       #   when a `node` has already a tracked `parent` or `level`,
@@ -114,18 +291,15 @@ module Eco::Data::Locations::NodeBase
       cyclic    = multi_parent && done_node == node
       double_up = node_dup || lev_dup
 
-      msg  = []
-      msg << "#{indent(level)}WARNING: Skipping #{node_str}."
-
       if cyclic
-        str  = "#{indent(level)+1}Cyclic definition. By skipping the node, "
+        str  = "#{indent(level + 1)}Cyclic definition. By skipping the node, "
         str << "it will remain as #{parent_msg(done_node.parent)} (#{level_msg(prev_level)})."
         msg << str
       end
 
       if double_up
-        str  = "#{indent(level)+1}The node ID has been tracked as #{level_msg(done_node.tracked_level)}, "
-        str << "as #{parent_msg(node_dup.parent)} "
+        str  = "#{indent(level + 1)}Node ID was already tracked as #{level_msg(done_node.tracked_level)}, "
+        str << "as #{parent_msg(done_node.parent)} "
         str << "(same parent)."      if lev_dup
         str << "(different parent)." if multi_parent
         msg << str
@@ -133,18 +307,19 @@ module Eco::Data::Locations::NodeBase
 
       unless cyclic || double_up
         str  = "Integrity issue in Treeify. "
-        str  = "Skipping is only applicable to double_ups or cyclic nodes."
+        str << "Skipping is only applicable to double_ups or cyclic nodes."
         str << "\n • #{node_str}."
         raise str
       end
 
-      if children = parents[node.id]
-        str  = "#{indent(level)+1}Immediate children of skipped node (will probably be missing): "
-        str << children.map {|gc| "'#{gc.id}'"}.join(", ")
+      unless (children = parents[node.id] || []).empty?
+        str  = "#{indent(level + 1)}Immediate children of skipped node (will probably be missing): "
+        str << children.map {|ch| "'#{ch.id}'"}.join(", ")
         msg << str
       end
 
-      log(:warn) { msg.join('\n') }
+      warns << msg.join("\n")
+      nil
     end
   end
 end

data/lib/eco/data/locations/node_level.rb

@@ -28,7 +28,7 @@ module Eco::Data::Locations
     end
 
     def tag
-      clean_id(raw_tag)
+      clean_id(raw_tag, ref: "(Row: #{self.row_num}) ")
     end
 
     def raw_tag

data/lib/eco/data/locations/node_plain/parsing.rb

@@ -20,7 +20,7 @@ class Eco::Data::Locations::NodePlain
     end
 
     # It builds each NodePlain from the input csv.
-    # @param `csv` [CSV::Table]
+    # @param `csv` [CSV::Table] with specific headers
     # @return [Array<NodePlain>]
     def nodes_from_csv(csv)
       raise ArgumentError, "Expecting CSV::Table. Given: #{csv.class}" unless csv.is_a?(::CSV::Table)

data/lib/eco/data/locations/node_plain/serial.rb

@@ -6,7 +6,7 @@ class Eco::Data::Locations::NodePlain
     def serializer
       @serializer ||= proc do |node|
         raise "Expecting NodePlain. Given: #{node.class}" unless node.is_a?(Eco::Data::Locations::NodePlain)
-        keys = Eco::Data::Locations::NodePlain::NODE_PLAIN_ATTRS
+        keys = Eco::Data::Locations::NodePlain::ALL_ATTRS
         node.to_h(*keys)
       end
     end

data/lib/eco/data/locations/node_plain.rb

@@ -15,7 +15,7 @@ module Eco::Data::Locations
     PROP_ATTRS         = ALL_ATTRS - ADDITIONAL_ATTRS
 
     def id
-      clean_id(super)
+      clean_id(super, ref: "(Row: #{self.row_num}) ")
     end
     # backwards compatibility
     alias_method :tag, :id
@@ -24,8 +24,9 @@ module Eco::Data::Locations
       super || self.id
     end
 
-    def parentId
-      self.parent_id
+    def parent_id
+      clean_id(super, notify: false, ref: "(Row: #{self.row_num} - parent_id) ")
     end
+    alias_method :parentId, :parent_id
   end
 end

data/lib/eco/data/mapper.rb

@@ -62,6 +62,12 @@ module Eco
         internal?(value) || external?(value)
       end
 
+      # Whether `value` maps to itself
+      def self_mapped?(value)
+        return false unless include?(value)
+        value == to_internal(value)
+      end
+
       def to_internal(value)
         return value if !@source
         @by_external[value]
@@ -71,7 +77,6 @@ module Eco
         return value if !@source
         @by_internal[value]
       end
-
     end
   end
 end

data/lib/eco/language/klass/when_inherited.rb

@@ -0,0 +1,17 @@
+module Eco
+  module Language
+    module Klass
+      module WhenInherited
+        def inherited(subclass)
+          super
+          subclass.instance_exec(&when_inherited)
+        end
+
+        def when_inherited(&block)
+          return @when_inherited unless block_given?
+          @when_inherited = block
+        end
+      end
+    end
+  end
+end

data/lib/eco/language/klass.rb

@@ -0,0 +1,8 @@
+module Eco
+  module Language
+    module Klass
+    end
+  end
+end
+
+require_relative 'klass/when_inherited'

data/lib/eco/language/methods/delegate_missing.rb

@@ -0,0 +1,28 @@
+module Eco
+  module Language
+    module Methods
+      module DelegateMissing
+        def delegate_missing_to(meth)
+          @delegate_missing_to = meth
+        end
+
+        def method_missing(method_name, *args, **kargs, &block)
+          super unless receiver = object_missing_delegated_to
+          receiver.send(method_name, *args, **kargs, &block)
+        end
+
+        def respond_to_missing?(method_name, include_private = false)
+          super
+        end
+
+        private
+
+        # retrieve the delegate_missing_to object
+        def object_missing_delegated_to
+          return nil unless @delegate_missing_to
+          self.method(@delegate_missing_to).call
+        end
+      end
+    end
+  end
+end

data/lib/eco/language/methods/dsl_able.rb

@@ -0,0 +1,25 @@
+module Eco
+  module Language
+    module Methods
+      module DslAble
+        # It runs the `block` within this object context
+        # @note if the object misses any method, redirects the method to the
+        #   original evaluate caller.
+        def evaluate(*args, **kargs, &block)
+          return unless block_given?
+          @self_before_evaluate = eval "self", block.binding
+          instance_exec(*args, **kargs, &block).tap do
+            @self_before_evaluate = nil
+          end
+        end
+
+        # When it's the case, redirect to the original `evaluate` caller
+        # @see https://www.dan-manges.com/blog/ruby-dsls-instance-eval-with-delegation
+        def method_missing(method, *args, **kargs, &block)
+          super unless @self_before_evaluate
+          @self_before_evaluate.send(method, *args, **kargs, &block)
+        end
+      end
+    end
+  end
+end

data/lib/eco/language/methods.rb

@@ -0,0 +1,9 @@
+module Eco
+  module Language
+    module Methods
+    end
+  end
+end
+
+require_relative 'methods/dsl_able'
+require_relative 'methods/delegate_missing'

data/lib/eco/language.rb

@@ -3,6 +3,8 @@ module Eco
   end
 end
 
+require_relative 'language/klass'
+require_relative 'language/methods'
 require_relative 'language/models'
 require_relative 'language/auxiliar_logger'
 require_relative 'language/basic_logger'

data/lib/eco/version.rb

@@ -1,3 +1,3 @@
 module Eco
-  VERSION = "2.5.10"
+  VERSION = "2.6.1"
 end