eco-helpers 3.0.27 → 3.0.28

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,18 +88,6 @@ 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)
         return false unless include_private

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,8 @@ 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'

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,18 +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?
+      subclass.instance_exec(&when_inherited)
+    end
+
+    def when_inherited(&block)
+      return @when_inherited unless block_given?
 
-          @when_inherited = block
-        end
-      end
+      @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/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

data/lib/eco/language/strings.rb

@@ -0,0 +1,8 @@
+module Eco
+  module Language
+    module Strings
+    end
+  end
+end
+
+require_relative 'strings/underscore'

data/lib/eco/language.rb

@@ -3,6 +3,7 @@ module Eco
   end
 end
 
+require_relative 'language/strings'
 require_relative 'language/klass'
 require_relative 'language/methods'
 require_relative 'language/models'

data/lib/eco/version.rb

@@ -1,3 +1,3 @@
 module Eco
-  VERSION = '3.0.27'.freeze
+  VERSION = '3.0.28'.freeze
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: eco-helpers
 version: !ruby/object:Gem::Version
-  version: 3.0.27
+  version: 3.0.28
 platform: ruby
 authors:
 - Oscar Segura
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-28 00:00:00.000000000 Z
+date: 2025-03-31 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -987,18 +1001,28 @@ files:
 - lib/eco/language/basic_logger.rb
 - lib/eco/language/curry.rb
 - lib/eco/language/delegation.rb
-- lib/eco/language/delegation/const_delegator.rb
-- lib/eco/language/delegation/const_lookup_hooks.rb
-- lib/eco/language/delegation/delegated_class.rb
+- lib/eco/language/delegation/chainable_delegator.rb
+- lib/eco/language/delegation/delegating_missing.rb
+- lib/eco/language/delegation/delegating_missing_const.rb
+- lib/eco/language/delegation/delegating_missing_on_class.rb
+- lib/eco/language/delegation/for_delegator.rb
+- lib/eco/language/delegation/for_delegator/const_delegator.rb
+- lib/eco/language/delegation/for_delegator/const_lookup_hooks.rb
+- lib/eco/language/delegation/for_delegator/delegated_class.rb
 - lib/eco/language/hash_transform.rb
 - lib/eco/language/hash_transform_modifier.rb
 - lib/eco/language/klass.rb
+- lib/eco/language/klass/builder.rb
+- lib/eco/language/klass/helpers_built.rb
+- lib/eco/language/klass/hierarchy.rb
+- lib/eco/language/klass/inheritable_class_vars.rb
+- lib/eco/language/klass/naming.rb
+- lib/eco/language/klass/resolver.rb
 - lib/eco/language/klass/when_inherited.rb
 - lib/eco/language/match.rb
 - lib/eco/language/match_modifier.rb
 - lib/eco/language/methods.rb
 - lib/eco/language/methods/call_detector.rb
-- lib/eco/language/methods/delegate_missing.rb
 - lib/eco/language/methods/dsl_able.rb
 - lib/eco/language/models.rb
 - lib/eco/language/models/class_helpers.rb
@@ -1006,6 +1030,8 @@ files:
 - lib/eco/language/models/modifier.rb
 - lib/eco/language/models/parser_serializer.rb
 - lib/eco/language/models/wrap.rb
+- lib/eco/language/strings.rb
+- lib/eco/language/strings/underscore.rb
 - lib/eco/language/values_at.rb
 - lib/eco/version.rb
 homepage: https://www.ecoportal.com