eco-helpers 3.0.27 → 3.0.29

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

@@ -0,0 +1,162 @@
+# rubocop:disable Naming/MethodParameterName
+
+module Eco::Language::Delegation
+  # Installs a middleware for each delegated entity
+  # @note It adds an implicit delegate missing to the target,
+  #   unless it has already been defined.
+  module DelegatingBlank
+    class << self
+      def included(base)
+        super
+
+        base.include DelegatingMissing
+        base.extend ClassMethods
+        base.inheritable_class_vars :_delegating_blank
+      end
+    end
+
+    module ClassMethods
+      include Eco::Language::Strings::Underscore
+
+      def delegating_blank(*these, to:, safe: false)
+        msg = "Delegating to: should be String or Symbol. Given: #{to.class}"
+        raise ArgumentError, msg unless sym_or_string?(to)
+
+        these.map do |this|
+          msg = "Expecting String or Symbol. Given: #{this}."
+          raise ArgumentError, msg unless sym_or_string?(this)
+
+          this.to_sym
+        end.each do |this|
+          delegating_missing(this, to: to) unless delegating_missing?(this)
+          install_blank_delegator(at: this, safe: safe)
+
+          _delegating_blank[this]      = to
+          _safe_blank_delegation[this] = safe
+        end
+
+        self
+      end
+
+      def delegating_blank?(sym)
+        return false unless sym_or_string?(sym)
+        return true  if _delegating_blank.key?(sym.to_sym)
+
+        false
+      end
+
+      def safe_blank_delegation?(sym)
+        return false unless sym_or_string?(sym)
+        return false unless _safe_blank_delegation.key?(sym.to_sym)
+
+        _safe_blank_delegation[sym.to_sym]
+      end
+
+      def delegating_blank_target(instance, at: nil)
+        return unless delegating_blank?(at)
+        return unless (subject_ref = _delegating_blank[at])
+
+        instance_has_method =
+          instance.methods.include?(subject_ref) ||
+          instance.private_methods.include?(subject_ref)
+
+        return instance.method(subject_ref).call if instance_has_method
+        return                                   unless at.to_s.start_with?('@')
+        return                                   unless instance.instance_variable_defined?(at)
+
+        instance.instance_variable_get(at)
+      end
+
+      private
+
+      def method_added(method_name)
+        return super if (@installing ||= false)
+
+        method_name = method_name.to_sym
+        return super unless delegating_blank?(method_name)
+
+        @installing = true
+        install_blank_delegator(at: method_name)
+        @installing = false
+        super
+      end
+
+      def _delegating_blank
+        @_delegating_blank ||= {}
+      end
+
+      def _safe_blank_delegation
+        @_safe_blank_delegation ||= {}
+      end
+
+      # If `base` does NOT have the method, don't install the middleware.
+      def install_blank_delegator(base = self, at:, safe: safe_blank_delegation?(at))
+        method_name  = underscore(at).gsub('@', '').to_sym
+        install_safe = safe
+
+        return unless instance_method?(base, name: method_name, include_private: true)
+
+        method_was_inherited = inherited_method?(base, name: method_name)
+        original_method      = :"delegated_blank_original_#{method_name}"
+
+        return if instance_method?(base, name: original_method, include_private: true, inherited: false)
+
+        base.alias_method(original_method, method_name) unless method_was_inherited
+
+        method_def = proc do |*args, **kargs, &block|
+          if method_was_inherited
+            super(*args, **kargs, &block)
+          else
+            send(original_method, *args, **kargs, &block)
+          end.then do |value|
+            next value unless blank?(value)
+
+            target = self.class.delegating_blank_target(self, at: at)
+
+            if at.to_s.start_with?('@')
+              target.instance_variable_get(at)
+            elsif !install_safe || target.respond_to?(method_name, true)
+              target.send(method_name, *args, **kargs, &block)
+            end
+          end
+        end
+
+        base.define_method(method_name, &method_def)
+      end
+
+      def instance_method?(base = self, name:, include_private: false, inherited: true)
+        return true  if base.method_defined?(name, inherited)
+        return false unless include_private
+
+        base.private_instance_methods(inherited).include?(name.to_sym)
+      end
+
+      def inherited_method?(base = self, name:)
+        return false if base.public_instance_methods(false).include?(name.to_sym)
+        return false if base.private_instance_methods(false).include?(name.to_sym)
+
+        true
+      end
+
+      def sym_or_string?(value)
+        return false unless value.is_a?(Symbol) || value.is_a?(String)
+        return false if value.to_s.strip.empty?
+
+        true
+      end
+    end
+
+    # INSTANCE Methods
+
+    def blank?(value)
+      return super if defined?(super)
+      return true  if value.nil?
+      return true  if value.to_s.strip.empty?
+      return true  if value.respond_to?(:empty?) && value.empty?
+
+      false
+    end
+  end
+end
+
+# rubocop:enable Naming/MethodParameterName

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

@@ -0,0 +1,104 @@
+# rubocop:disable Naming/MethodParameterName
+
+module Eco::Language::Delegation
+  module DelegatingMissing
+    class << self
+      def included(base)
+        super
+
+        base.extend Eco::Language::Klass::HelpersBuilt
+        base.extend ClassMethods
+        base.inheritable_class_vars :_delegating_missing, :delegating_missing_to
+      end
+    end
+
+    module ClassMethods
+      def delegating_missing(*these, to:)
+        msg = "Delegating to: should be String or Symbol. Given: #{to.class}"
+        raise ArgumentError, msg unless sym_or_string?(to)
+
+        these.map do |this|
+          msg = "Expecting String or Symbol. Given: #{this}."
+          raise ArgumentError, msg unless sym_or_string?(this)
+
+          this.to_sym
+        end.each do |this|
+          _delegating_missing[this] = to
+        end
+
+        self
+      end
+
+      def delegating_missing_to(to = nil)
+        return @delegating_missing_to if to.nil?
+
+        msg = "Expecting String or Symbol. Given: #{to}."
+        raise ArgumentError, msg unless sym_or_string?(to)
+
+
+        @delegating_missing_to = to.to_sym
+      end
+
+      def delegating_missing?(sym)
+        return true  if sym.nil? && delegating_missing_to
+        return false unless sym_or_string?(sym)
+        return true  if _delegating_missing.key?(sym.to_sym)
+        return true  if delegating_missing_to
+
+        false
+      end
+
+      def delegating_missing_target(instance, at: nil)
+        return unless delegating_missing?(at)
+        return unless (subject_ref = _delegating_missing[at] || delegating_missing_to)
+
+        instance_has_method =
+          instance.methods.include?(subject_ref) ||
+          instance.private_methods.include?(subject_ref)
+
+        return instance.method(subject_ref).call if instance_has_method
+        return                                   unless at.to_s.start_with?('@')
+        return                                   unless instance.instance_variable_defined?(at)
+
+        instance.instance_variable_get(at)
+      end
+
+      private
+
+      def _delegating_missing
+        @_delegating_missing ||= {}
+      end
+
+      def sym_or_string?(value)
+        return false unless value.is_a?(Symbol) || value.is_a?(String)
+        return false if value.to_s.strip.empty?
+
+        true
+      end
+    end
+
+    # INSTANCE Methods
+
+    def respond_to_missing?(method_name, include_private = false)
+      super
+    end
+
+    private
+
+    # @note if missing, redirect all parameters to `receiver`,
+    #   as long as responds_to `method_name`
+    def method_missing(method_name, *args, **kargs, &block)
+      return super unless self.class.delegating_missing?(method_name)
+
+      target = self.class.delegating_missing_target(self, at: method_name)
+
+      if method_name.to_s.start_with?('@')
+        target.instance_variable_get(method_name)
+      else
+        target.send(method_name, *args, **kargs, &block)
+      end
+    end
+  end
+end
+
+# rubocop:enable Naming/MethodParameterName

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

@@ -0,0 +1,53 @@
+module Eco::Language::Delegation
+  # Class to lookup constants through `delegated_class`.
+  # @note it uses `DelegatingMissing`.
+  # @note it tries to lookup on the `class` of the `delegating_missing_to`
+  #   object. Which requires an instance of the delegator to exist, with
+  #   the aim of scoping its class (so it can chain constant lookup), unless
+  #   `delegated_class` is explicitly stated.
+  # @note that not setting `delegated_class` explicitly could fail
+  #   to chain the looup.
+  module DelegatingMissingConst
+    class << self
+      def included(base)
+        super
+
+        base.send :include, DelegatingMissing
+        base.send :include, ForDelegator::ConstDelegator
+        base.extend ClassMethods
+
+        # because we inject `#initialize`
+        base.send :prepend, InstanceMethods
+      end
+    end
+
+    module ClassMethods
+      # Set always `delegated_class` when fetching the
+      # `delegating_missing_to` object.
+      def delegating_missing_target(instance, at: nil)
+        super.tap do |target|
+          next unless target
+          next unless at.nil?
+
+          delegated_class target.class
+        end
+      end
+    end
+
+    module InstanceMethods
+      # Set the `delegated_class` to chain **constant lookup**
+      # via `delegating_missing_to.class`.
+      # @note this requires that the target can be fetched without passing
+      #   parameters (as it is typically the case with `delegating_missing_to`).
+      def initialize(...)
+        super if defined?(super)
+
+        delegated_class.tap do |klass|
+          next unless (target = self.class.delegating_missing_target(self))
+
+          self.class.delegated_class target.class
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+module Eco::Language::Delegation
+  module DelegatingMissingOnClass
+    class << self
+      def included(base)
+        super
+
+        base.extend Eco::Language::Klass::HelpersBuilt
+        base.extend ClassMethods
+        base.inheritable_class_vars :delegating_missing_on_class_to
+      end
+    end
+
+    module ClassMethods
+      def delegating_missing_on_class_to(to = nil)
+        return @delegating_missing_on_class_to if to.nil?
+
+        msg = "Expecting String or Symbol. Given: #{to}."
+        raise ArgumentError, msg unless sym_or_string?(to)
+
+        @delegating_missing_on_class_to = to
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        super
+      end
+
+      private
+
+      # @note if missing, redirect all parameters to `target`,
+      #   as long as responds_to `method_name`
+      def method_missing(method_name, *args, **kargs, &block)
+        return super unless (target = delegating_missing_on_class_target)
+
+        target.send(method_name, *args, **kargs, &block)
+      end
+
+      # retrieves the delegating_missing_on_class_to object
+      def delegating_missing_on_class_target
+        return unless @delegating_missing_on_class_to
+
+        # fetch the object behind the method
+        method(@delegating_missing_on_class_to).call
+      end
+
+      def sym_or_string?(value)
+        return false unless value.is_a?(Symbol) || value.is_a?(String)
+        return false if value.to_s.strip.empty?
+
+        true
+      end
+    end
+  end
+end

data/lib/eco/language/delegation/{const_delegator.rb → for_delegator/const_delegator.rb}

@@ -1,7 +1,9 @@
-module Eco::Language::Delegation
+module Eco::Language::Delegation::ForDelegator
   # Module that is to be used with ruby `Delegator` or related helpers,
   # such as `SimpleDelegator` or `Forwardable`.
-  # @note it includes `DelegatedClass`
+  # @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
@@ -15,13 +17,13 @@ module Eco::Language::Delegation
       def included(base)
         super
 
-        base.send :include, Eco::Language::DelegatedClass
-        base.extend(ClassMethods)
+        base.send :include, DelegatedClass
+        base.extend ClassMethods
       end
     end
 
     module ClassMethods
-      def const_defined?(str, inherit = true, delegated: true)
+      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)
 
@@ -41,7 +43,7 @@ module Eco::Language::Delegation
         const_get(str)
       end
 
-      def constants(inherited = true, delegated: true)
+      def constants(inherited = true, delegated: true) # rubocop:disable Style/OptionalBooleanParameter
         super(inherited).dup.tap do |consts|
           next unless delegated && delegated_class
 

data/lib/eco/language/delegation/{const_lookup_hooks.rb → for_delegator/const_lookup_hooks.rb}

@@ -1,6 +1,8 @@
-module Eco::Language::Delegation
+module Eco::Language::Delegation::ForDelegator
   # This approach only makes sense to be used in `Delegator` and related helpers.
-  # @note it includes `ConstDelegator` (which includes `DelegatedClass`)
+  # @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.
@@ -11,22 +13,49 @@ module Eco::Language::Delegation
       def included(base)
         super
 
-        base.send :include, Eco::Language::Delegation::ConstDelegator
+        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.extend(ClassMethods)
+        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
@@ -45,6 +74,7 @@ module Eco::Language::Delegation
         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)
@@ -58,23 +88,11 @@ module Eco::Language::Delegation
         base.define_method(meth_name, &method_def)
       end
 
-      # @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
-
-      def instance_method?(base = self, name:, include_private: false)
-        return true  if base.method_defined?(name)
+      def instance_method?(base = self, name:, include_private: false, inherited: true)
+        return true  if base.method_defined?(name, inherited)
         return false unless include_private
 
-        base.private_instance_methods.include?(name.to_sym)
+        base.private_instance_methods(inherited).include?(name.to_sym)
       end
     end
   end

data/lib/eco/language/delegation/{delegated_class.rb → for_delegator/delegated_class.rb}

@@ -1,4 +1,4 @@
-module Eco::Language::Delegation
+module Eco::Language::Delegation::ForDelegator
   module DelegatedClass
     class << self
       private
@@ -6,7 +6,11 @@ module Eco::Language::Delegation
       def included(base)
         super
 
-        base.extend(ClassMethods)
+        base.extend Eco::Language::Klass::HelpersBuilt
+        base.extend ClassMethods
+
+        base.inheritable_class_vars :delegated_class
+
         base.send :patch_class_compare
       end
     end
@@ -20,12 +24,6 @@ module Eco::Language::Delegation
 
       private
 
-      def inherited(subclass)
-        super
-
-        subclass.instance_variable_set(:@delegated_class, @delegated_class)
-      end
-
       def patch_class_compare(base = self)
         %i[< <= ==].each do |op|
           base.singleton_class.define_method(op) do |other|
@@ -40,17 +38,6 @@ module Eco::Language::Delegation
 
     # Instance methods
 
-    # It allows to chain delegators, when the first parameter is an
-    # instance of `delegated_class`.
-    # @note it also allows to create an instance of `delegated_class`
-    #   on initialization.
-    def initialize(*args, **kargs, &block)
-      obj = args.first
-      obj = new(*args, **kargs, &block) unless of_kind?(obj)
-
-      super(obj)
-    end
-
     def delegated_class
       self.class.delegated_class
     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

@@ -3,6 +3,9 @@ module Eco::Language
   end
 end
 
-require_relative 'delegation/delegated_class'
-require_relative 'delegation/const_delegator'
-require_relative 'delegation/const_lookup_hooks'
+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'
+require_relative 'delegation/delegating_blank'

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