eco-helpers 3.0.26 → 3.0.28

data/lib/eco/language/delegation/for_delegator/const_delegator.rb

@@ -0,0 +1,66 @@
+module Eco::Language::Delegation::ForDelegator
+  # Module that is to be used with ruby `Delegator` or related helpers,
+  # such as `SimpleDelegator` or `Forwardable`.
+  # @note
+  #   1. It includes `DelegatedClass`
+  #   2. This class only provides lookups integration.
+  # @note it looks up the constant via `delegated_class`. This is because
+  #   on `Delegator` approaches, the intance object (`self`) points to the
+  #   delegated object, which doesn't allow to refer to `self.class` to
+  #   implement a delegation of constants that other way.
+  #   For example, `self.class::CONSTANT` will not point to the delegator
+  #   class constant, but to the constant of the delegated object's class.
+  module ConstDelegator
+    class << self
+      private
+
+      def included(base)
+        super
+
+        base.send :include, DelegatedClass
+        base.extend ClassMethods
+      end
+    end
+
+    module ClassMethods
+      def const_defined?(str, inherit = true, delegated: true) # rubocop:disable Style/OptionalBooleanParameter
+        return super(str, inherit) if super(str, inherit) || !delegated
+        return true                if delegated_class&.const_defined?(str, inherit)
+
+        false
+      end
+
+      def const_get(str)
+        return super                          if const_defined?(str, delegated: false)
+        return delegated_class.const_get(str) if delegated_class&.const_defined?(str)
+
+        super
+      end
+
+      def const_missing(str)
+        return super unless const_defined?(str)
+
+        const_get(str)
+      end
+
+      def constants(inherited = true, delegated: true) # rubocop:disable Style/OptionalBooleanParameter
+        super(inherited).dup.tap do |consts|
+          next unless delegated && delegated_class
+
+          delegated_class.constants(inherited).each do |const|
+            consts.unshift(const)
+          end
+        end
+      end
+
+      private
+
+      def remove_const(str)
+        return super unless const_defined?(str)
+        return super if const_defined?(str, delegated: false)
+
+        raise NameError, "#{str} not defined (is delegated to #{delegated_class})"
+      end
+    end
+  end
+end

data/lib/eco/language/delegation/for_delegator/const_lookup_hooks.rb

@@ -0,0 +1,99 @@
+module Eco::Language::Delegation::ForDelegator
+  # This approach only makes sense to be used in `Delegator` and related helpers.
+  # @note
+  #   1. It includes `ConstDelegator` (which includes `DelegatedClass`).
+  #   2. This class installs new instance methods.
+  # @note for each not inherited constant that isn't part of the delegated object's
+  #   class, it will create a undercore/snake named instance method, to ease
+  #   constant lookup througout chained/wrapped delegators.
+  module ConstLookupHooks
+    class << self
+      private
+
+      def included(base)
+        super
+
+        msg  = 'Only to be included in Delegator subclasses (i.e. SimpleDelegator). '
+        msg << 'As this concern is just a work around to not being possible to fetch '
+        msg << 'the Decorator class, because self.class refers to the class of the '
+        msg << 'decorated object. Meaning that it is not necessary on other patterns.'
+        raise ArgumentError, msg unless base <= Delegator
+
+        base.send :include, ConstDelegator
+
+        base.extend ClassMethods
+        base.send :install_constant_lookup_hooks
+      end
+    end
+
+    module ClassMethods
+      include Eco::Language::Strings::Underscore
+
+      # @note
+      #   - We don't install const hook methods when `delegated_class` is (re)defined,
+      #     because these hooks aim only the delegator (not the delegated).
+      # @todo **However**It is still to be seen if we should include this concern
+      #   to the `delegated_class`, provided that const lookup methods are aligned
+      #   (as it is a requirement).
+      # When `delegated_class` is **defined**, install const hook methods too it.
+      # def delegated_class(klass = nil)
+      #   super.tap do
+      #     next if klass.nil?
+      #     next if klass < ConstLookupHooks
+
+      #     klass.send :include, ConstLookupHooks
+      #   end
+      # end
+
+      private
+
+      # When **inherited**, install const hook methods to the `subclass`.
+      def inherited(subclass)
+        super
+
+        subclass.send :install_constant_lookup_hooks
+      end
+
+      # When a constant is **added** install const hook methods to it.
+      # to the `subclass`.
+      def const_added(sym)
+        install_constant_lookup_hook(const: sym)
+      end
+
+      # Drawback is this will also create methods for modules and classes hanging
+      # from `base` namespace. Unfortunatelly, we need to go with them, because
+      # it might happen a constant points to one of them to implement some behaviour.
+      def install_constant_lookup_hooks(base = self)
+        # Only method-hook constants that are not inherited,
+        # nor delegated to the decorated class.
+        # This constraint ensure that we don't overpopulate with hook methods,
+        # and that the lookup respects the order in which the decorators are
+        # wrapped (i.e. Sugar.new(Milk.new(Coffe.new)) < Sugar(Milk(Coffee)) ).
+        base.constants(false, delegated: false).each do |const|
+          install_constant_lookup_hook(base, const: const)
+        end
+      end
+
+      # If `base` does NOT have the constant hook method, it defines it.
+      def install_constant_lookup_hook(base = self, const:)
+        meth_name = underscore(const).to_sym
+        return if instance_method?(base, name: meth_name, include_private: true)
+
+        method_def = proc do |*args, **kargs, &block|
+          return super(*args, **kargs, &block) if defined?(super)
+
+          base.const_get(const)
+        end
+
+        base.define_method(meth_name, &method_def)
+      end
+
+      def instance_method?(base = self, name:, include_private: false)
+        return true  if base.method_defined?(name)
+        return false unless include_private
+
+        base.private_instance_methods.include?(name.to_sym)
+      end
+    end
+  end
+end

data/lib/eco/language/delegation/for_delegator/delegated_class.rb

@@ -0,0 +1,71 @@
+module Eco::Language::Delegation::ForDelegator
+  module DelegatedClass
+    class << self
+      private
+
+      def included(base)
+        super
+
+        base.extend Eco::Language::Klass::HelpersBuilt
+        base.extend ClassMethods
+
+        base.inheritable_class_vars :delegated_class
+
+        base.send :patch_class_compare
+      end
+    end
+
+    module ClassMethods
+      def delegated_class(klass = nil)
+        return @delegated_class if klass.nil?
+
+        @delegated_class = klass
+      end
+
+      private
+
+      def patch_class_compare(base = self)
+        %i[< <= ==].each do |op|
+          base.singleton_class.define_method(op) do |other|
+            return super(other) unless delegated_class
+            return true         if super(other)
+
+            delegated_class.send(op, other)
+          end
+        end
+      end
+    end
+
+    # Instance methods
+
+    def delegated_class
+      self.class.delegated_class
+    end
+
+    def new(...)
+      delegated_class.new(...)
+    end
+
+    def of_kind?(obj)
+      return true  if obj.is_a?(delegated_class)
+      return false unless obj.is_a(Delegator)
+      return true  if obj.__get_obj__.is_a?(delegated_class)
+
+      false
+    end
+
+    def is_a?(base)
+      return true  if super
+      return false unless delegated_class
+      return true  if delegated_class <= base
+
+      false
+    end
+
+    def instance_of?(base)
+      return true if base == delegated_class
+
+      super
+    end
+  end
+end

data/lib/eco/language/delegation/for_delegator.rb

@@ -0,0 +1,11 @@
+require 'delegate'
+
+module Eco::Language::Delegation
+  # Helpers to be included on native `Delegator` subclasses.
+  module ForDelegator
+  end
+end
+
+require_relative 'for_delegator/delegated_class'
+require_relative 'for_delegator/const_delegator'
+require_relative 'for_delegator/const_lookup_hooks'

data/lib/eco/language/delegation.rb

@@ -0,0 +1,10 @@
+module Eco::Language
+  module Delegation
+  end
+end
+
+require_relative 'delegation/for_delegator'
+require_relative 'delegation/chainable_delegator'
+require_relative 'delegation/delegating_missing_on_class'
+require_relative 'delegation/delegating_missing'
+require_relative 'delegation/delegating_missing_const'

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

@@ -0,0 +1,29 @@
+module Eco::Language::Klass
+  module Builder
+    include Resolver
+    include Naming
+
+    # If the class for `name` exists, it returns it. Otherwise it generates it.
+    # @param name [String, Symbol] the name of the new class
+    # @param inherits [Class] the parent class to _inherit_ from
+    # @param parent_space [String] parent namespace of the generated class, if not given: `self`
+    # @yield [child_class] configure the new class
+    # @yieldparam child_class [Class] the new class
+    # @return [Class] the new generated class
+    def new_class(name, inherits:, parent_space: nil)
+      name            = name.to_sym.freeze
+      class_name      = to_constant(name)
+      parent_space    = parent_space ? resolve_class(parent_space) : self
+      full_class_name = "#{parent_space}::#{class_name}"
+
+      unless (target_class = resolve_class(full_class_name, exception: false))
+        target_class = Class.new(inherits)
+        parent_space.const_set class_name, target_class
+      end
+
+      target_class.tap do |klass|
+        yield(klass) if block_given?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+module Eco::Language::Klass
+  module HelpersBuilt
+    include Resolver
+    include Naming
+    include Builder
+    include Hierarchy
+    include InheritableClassVars
+  end
+end

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

@@ -0,0 +1,34 @@
+module Eco::Language::Klass
+  module Hierarchy
+    # Finds all child classes of the current class.
+    # @param parent_class [Class] the parent class we want to find children of.
+    # @param direct [Boolean] it will only include direct child classes.
+    # @param scope [nil, Array] to only look for descendants among the ones in `scope`.
+    # @return [Arrary<Class>] the child classes in hierarchy order.
+    def descendants(parent_class: self, direct: false, scope: nil)
+      scope ||= ObjectSpace.each_object(::Class)
+      return [] if scope.empty?
+
+      scope.select do |klass|
+        klass < parent_class
+      end.sort do |k_1, k_2|
+        next -1 if k_2 < k_1
+        next  1 if k_1 < k_2
+        0
+      end.tap do |siblings|
+        next unless direct
+
+        siblings.reject! do |si|
+          siblings.any? {|s| si < s}
+        end
+      end
+    end
+
+    # @param parent_class [Class] the parent class we want to find children of.
+    # @param direct [Boolean] it will only include direct child classes.
+    # @return [Boolean] `true` if the current class has child classes, and `false` otherwise.
+    def descendants?(parent_class: self, direct: false)
+      descendants(parent_class: parent_class, direct: direct).length.positive?
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+module Eco::Language::Klass
+  module InheritableClassVars
+    include Naming
+
+    # Keeps track on class instance variables that should be inherited by child classes.
+    # @note
+    #   - subclasses will inherit the value as is at that moment
+    #   - any change afterwards will be only on the specific class (in line with class instance variables)
+    #   - adapted from https://stackoverflow.com/a/10729812/4352306
+    # TODO: this separates the logic of the method to the instance var.
+    #   Think if would be possible to join them somehow.
+    def inheritable_class_vars(*vars)
+      @inheritable_class_vars ||= [:inheritable_class_vars]
+      @inheritable_class_vars += vars
+    end
+
+    # Builds the attr_reader and attr_writer of `attrs` and registers
+    # the associated instance variable as inheritable.
+    def inheritable_attrs(*attrs)
+      attrs.each do |attr|
+        class_eval %(
+          class << self; attr_accessor :#{attr} end
+        ), __FILE__, __LINE__ - 2
+      end
+
+      inheritable_class_vars(*attrs)
+    end
+
+    # This callback method is called whenever a subclass of the current class is created.
+    # @note
+    #   - values of the instance variables are copied as they are (no dups or clones)
+    #   - the above means: avoid methods that change the state of the mutable object on it
+    #   - mutating methods would reflect the changes on other classes as well
+    #   - therefore, `freeze` will be called on the values that are inherited.
+    def inherited(subclass)
+      super
+
+      inheritable_class_vars.each do |var|
+        instance_var = instance_variable_name(var)
+        value        = instance_variable_get(instance_var)
+        subclass.instance_variable_set(instance_var, value.freeze)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+module Eco::Language::Klass
+  module Naming
+    # Helper to normalize `key` into a correct `ruby` **constant name**
+    # @param key [String, Symbol] to be normalized
+    # @return [String] a correct constant name
+    def to_constant(key)
+      key.to_s.strip.split(/[\-\_ ]/i).compact.map do |str|
+        str.slice(0).upcase + str.slice(1..-1).downcase
+      end.join
+    end
+
+    # Helper to create an instance variable `name`
+    # @param [String, Symbol] the name of the variable
+    # @reutrn [String] the name of the created instance variable
+    def instance_variable_name(name)
+      str = name.to_s
+      str = "@#{str}" unless str.start_with?("@")
+      str
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+module Eco::Language::Klass
+  module Resolver
+    # Creates a class and instance object methods with name `name` to resolve `klass` name
+    def class_resolver(name, klass)
+      define_singleton_method(name) { resolve_class(klass) }
+      define_method(name) { self.class.resolve_class(klass) }
+    end
+
+    # With given a `klass` name it resolves to an actual `Class`
+    # @return [Class] the class that was being searched by name `klass`.
+    def resolve_class(klass, exception: true)
+      @resolved ||= {}
+      @resolved[klass] ||=
+        case klass
+        when Class
+          klass
+        when String
+          begin
+            Kernel.const_get(klass)
+          rescue NameError
+            raise if exception
+          end
+        when Symbol
+          resolve_class(send(klass))
+        else
+          raise "Unknown class: #{klass}" if exception
+        end
+    end
+  end
+end

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

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

data/lib/eco/language/klass.rb

@@ -5,4 +5,10 @@ module Eco
   end
 end
 
+require_relative 'klass/resolver'
+require_relative 'klass/naming'
+require_relative 'klass/builder'
+require_relative 'klass/hierarchy'
 require_relative 'klass/when_inherited'
+require_relative 'klass/inheritable_class_vars'
+require_relative 'klass/helpers_built'

data/lib/eco/language/methods.rb

@@ -6,5 +6,4 @@ module Eco
 end
 
 require_relative 'methods/call_detector'
-require_relative 'methods/delegate_missing'
 require_relative 'methods/dsl_able'

data/lib/eco/language/models/class_helpers.rb

@@ -2,7 +2,7 @@ module Eco
   module Language
     module Models
       module ClassHelpers
-        NOT_USED = "no_used!"
+        NOT_USED = 'no_used!'.freeze
 
         def redef_without_warning(const, value)
           self.class.send(:remove_const, const) if self.class.const_defined?(const)
@@ -22,24 +22,24 @@ module Eco
         # @param exception [Boolean] if it should raise exception when could not resolve
         # @return [Class] the `Class` constant
         def resolve_class(klass, source_class: self, exception: true)
-          @resolved ||= {}
+          @resolved        ||= {}
           @resolved[klass] ||=
             case klass
-              when Class
-                klass
-              when String
-                begin
-                  Kernel.const_get(klass)
-                rescue NameError => e
-                  raise if exception
-                end
-              when Symbol
-                source_class.resolve_class(source_class.send(klass))
-              when Hash
-                referrer, referred = klass.first
-                resolve_class(referred, source_class: referrer, exception: exception)
-              else
-                raise "Unknown class: #{klass}" if exception
+            when Class
+              klass
+            when String
+              begin
+                Kernel.const_get(klass)
+              rescue NameError
+                raise if exception
+              end
+            when Symbol
+              source_class.resolve_class(source_class.send(klass))
+            when Hash
+              referrer, referred = klass.first
+              resolve_class(referred, source_class: referrer, exception: exception)
+            else
+              raise "Unknown class: #{klass}" if exception
             end
         end
 
@@ -48,11 +48,11 @@ module Eco
         # @param key [String, Symbol] to be normalized
         # @return [String] a correct constant name
         def to_constant(key)
-          str_name = key.to_s.strip.split(/::/).compact.map do |str|
+          key.to_s.strip.split('::').compact.map do |str|
             str.slice(0).upcase + str.slice(1..-1)
-          end.join("").split(/[\-\_ :]+/i).compact.map do |str|
+          end.join.split(/[\-\_ :]+/i).compact.map do |str|
             str.slice(0).upcase + str.slice(1..-1)
-          end.join("")
+          end.join
         end
 
         # Helper to create an instance variable `name`
@@ -75,7 +75,7 @@ module Eco
           name            = name.to_s.to_sym.freeze
           class_name      = to_constant(name)
 
-          unless target_class = resolve_class("#{namespace}::#{class_name}", exception: false)
+          unless (target_class = resolve_class("#{namespace}::#{class_name}", exception: false))
             target_class = Class.new(inherits)
             Kernel.const_get(namespace.to_s).const_set class_name, target_class
           end
@@ -108,9 +108,9 @@ module Eco
         # Builds the attr_reader and attr_writer of `attrs` and registers the associated instance variable as inheritable.
         def inheritable_attrs(*attrs)
           attrs.each do |attr|
-            class_eval %(
+            class_eval %( # rubocop:disable Style/DocumentDynamicEvalDefinition
               class << self; attr_accessor :#{attr} end
-            )
+            ), __FILE__, __LINE__ - 2
           end
           inheritable_class_vars(*attrs)
         end
@@ -122,6 +122,8 @@ module Eco
         #   - mutating methods would reflect the changes on other classes as well
         #   - therefore, `freeze` will be called on the values that are inherited.
         def inherited(subclass)
+          super
+
           inheritable_class_vars.each do |var|
             instance_var = instance_variable_name(var)
             value        = instance_variable_get(instance_var)

data/lib/eco/language/models/collection.rb

@@ -22,11 +22,13 @@ module Eco
           def attrs_create_method(attrs, method)
             attrs.each do |attr|
               attr = attr.to_s
+
               if method.include?("attr")
                 attr_method = method.sub("attr", attr)
               else
                 attr_method = "#{attr}_#{method}"
               end
+
               define_method attr_method do |*args|
                 send(method, attr, *args)
               end
@@ -36,6 +38,7 @@ module Eco
 
         def initialize(data = [], klass:, factory: nil, handy: Eco::Assets::Language.new)
           raise "Raise klass required, given: #{klass}" unless klass
+
           @klass   = klass
           @factory = factory
           @handy   = handy
@@ -70,6 +73,7 @@ module Eco
 
         def each(&block)
           return to_enum(:each) unless block
+
           @items.each(&block)
         end
 
@@ -104,6 +108,7 @@ module Eco
 
         def attr(attr, value = true, modifier = default_modifier)
           return present(attr, value) if boolean?(value)
+
           select do |object|
             match?(attr_value(object, attr), value, modifier)
           end.then do |matching|
@@ -113,6 +118,7 @@ module Eco
 
         def attr?(attr, value = true, modifier = default_modifier)
           return present(attr, value).length == length if boolean?(value)
+
           match?(attrs(attr), value, modifier.new.reverse)
         end
 
@@ -130,6 +136,7 @@ module Eco
 
         def group_by(attr = nil, &block)
           return to_h(attr) if attr
+
           to_a.group_by(&block) if block
         end
 
@@ -138,6 +145,7 @@ module Eco
         def to_h(attr, &block)
           return to_a.group_by(&block) if block
           raise "And attr or a block are required. Given attr: #{attr}" unless attr
+
           to_a.group_by { |object| object.method(attr).call }
         end
         # @!endgroup
@@ -175,16 +183,18 @@ module Eco
         private
 
         def attr_value(obj, attr)
-          return nil unless obj && attr
+          return unless obj && attr
+
           if obj.is_a?(Hash)
             obj[attr]
-          elsif obj.respond_to?(attr.to_sym)
+          elsif obj.respond_to?(attr.to_sym, true)
             obj.send(attr)
           end
         end
 
         def attr_value_present?(obj, attr)
           return false unless (value = attr_value(obj, attr))
+
           if value.is_a?(Enumerable)
             value.count > 1
           elsif value.is_a?(String)

data/lib/eco/language/strings/underscore.rb

@@ -0,0 +1,17 @@
+module Eco::Language::Strings
+  module Underscore
+    private
+
+    # @see https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-underscore
+    def underscore(sym)
+      return super if defined?(super)
+      return sym.to_s.dup unless /[A-Z-]|::/.match?(sym)
+
+      word = sym.to_s.gsub('::', '/')
+      word.gsub!(/(?<=[A-Z])(?=[A-Z][a-z])|(?<=[a-z\d])(?=[A-Z])/, '_')
+      word.tr!('-', '_')
+      word.downcase!
+      word
+    end
+  end
+end