eco-helpers 3.0.37 → 3.1.2

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

@@ -0,0 +1,129 @@
+module Eco::Language::Klass
+  # Helpers for dynamic object loading based on class declaration
+  # @note
+  #   - this helpers aim to boost the usage of the ruby language
+  #     in complex integration configurations.
+  module AutoLoader
+    include Resolver
+    include Hierarchy
+
+    # It loads/creates a new instance of children classes pending to be loaded.
+    # @note This method **should be explicitly called**.
+    # @return [Boolean] `true` if there were children loaded, `false` otherwise.
+    def autoload_children!(object)
+      return false if @loading_children
+      return false unless autoloaded_class
+
+      pending_children = unloaded_children
+      return false if pending_children.empty?
+
+      @loading_children = true
+
+      pending_children.each do |klass|
+        @child = klass.new(object)
+      rescue TypeError => _e
+        # Can't create from this class (must be the singleton class)
+        # Just ignore
+      ensure
+        autoloaded_children.push(klass)
+      end
+
+      true
+    ensure
+      @loading_children = false
+    end
+
+    # To enable the class autoloader, you should use this  method
+    def autoloads_children_of(klass)
+      class_resolver :autoloader_class, klass
+      @autoloaded_class = klass
+    end
+
+    # Resolves the class `autoloader_class` if it has been defined via `autoloads_children_of`
+    def autoloaded_class
+      return unless @autoloaded_class
+
+      autoloader_class
+    end
+
+    # To which restricted namespaces this class autoloads from
+    def autoloaded_namespaces(type = :include)
+      @autoloaded_namespaces       ||= {}
+      @autoloaded_namespaces[type] ||= []
+    end
+
+    # To restrict which namespaces it is allowed to load from
+    def autoload_namespace(*namespaces)
+      _autoload_namespace(:include, *namespaces)
+    end
+
+    # To ignore certain namespaces this class should not autoload from
+    def autoload_namespace_ignore(*namespaces)
+      _autoload_namespace(:ignore, *namespaces)
+    end
+
+    def _autoload_namespace(type, *namespaces)
+      autoloaded_namespaces(type).concat(namespaces) unless namespaces.empty?
+    end
+
+    # @param constant [Class, String] a class or namespace we want to check auto-load entitlement thereof.
+    # @return [Boolean] determines if a given namespace is entitled for autoloading
+    def autoload_class?(constant)
+      constants = constant.to_s.split("::").compact
+      autoload  = true
+
+      unless autoloaded_namespaces(:include).empty?
+        autoload = autoloaded_namespaces(:include).any? do |ns|
+          ns.to_s.split("::").compact.zip(constants).all? {|(r, c)| r == c}
+        end
+      end
+
+      unless autoloaded_namespaces(:ignore).empty?
+        autoload &&= autoloaded_namespaces(:ignore).none? do |ns|
+          ns.to_s.split("::").compact.zip(constants).all? {|(r, c)| r == c}
+        end
+      end
+
+      autoload
+    end
+
+    # As children are loaded as they are declared, we should not load twice same children.
+    def autoloaded_children
+      @auto_loaded_children ||= [] # rubocop:disable Naming/MemoizedInstanceVariableName
+    end
+
+    # Children classes of `autoloader_class` that have not been created an instance of.
+    def unloaded_children
+      return [] unless autoloaded_class
+
+      new_detected = new_classes
+      known_class!(*new_detected)
+
+      descendants(
+        parent_class: autoloaded_class,
+        scope:        new_detected
+      ).select do |child_class|
+        next false if autoloaded_children.include?(child_class)
+        next false unless autoload_class?(child_class)
+
+        true
+      end.sort
+    end
+
+    # Known namespaces serves the purpose to discover recently added namespaces
+    #   provided that the namespace discovery is optimized
+    def known_classes
+      @known_classes ||= []
+    end
+
+    # Add to known namespaces
+    def known_class!(*classes)
+      known_classes.concat(classes)
+    end
+
+    # List all new namespaces
+    def new_classes
+      ObjectSpace.each_object(::Class).to_a - known_classes
+    end
+  end
+end

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

@@ -2,23 +2,23 @@ module Eco::Language::Klass
   module Builder
     include Resolver
     include Naming
+    include Uid
 
     # 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`
+    # @param namespace [Class, String] an existing `constant` (class or module) the new class will be namespaced on
     # @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
+    def new_class(name = "Child#{uid}", inherits: self, namespace: inherits)
+      name            = name.to_s.to_sym.freeze
       class_name      = to_constant(name)
-      parent_space    = parent_space ? resolve_class(parent_space) : self
-      full_class_name = "#{parent_space}::#{class_name}"
+      full_class_name = "#{namespace}::#{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
+        Kernel.const_get(namespace.to_s).const_set class_name, target_class
       end
 
       target_class.tap do |klass|

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

@@ -0,0 +1,19 @@
+module Eco::Language::Klass
+  module Const
+    def redef_without_warning(sym, value)
+      self.class.send(:remove_const, sym) if self.class.const_defined?(sym)
+      self.class.const_set(sym, value)
+    end
+
+    def if_const(sym, at: self) # rubocop:disable Naming/MethodParameterName
+      value = nil
+      value = at.const_get(sym) if at.const_defined?(sym)
+
+      value.tap do
+        next if value.nil?
+
+        yield(value)
+      end
+    end
+  end
+end

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

@@ -1,7 +1,9 @@
 module Eco::Language::Klass
   module HelpersBuilt
-    include Resolver
+    include Uid
+    include Const
     include Naming
+    include Resolver
     include Builder
     include Hierarchy
     include InheritableClassVars

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

@@ -1,6 +1,7 @@
 module Eco::Language::Klass
   module Hierarchy
     # Finds all child classes of the current class.
+    # @note in native `ruby`, you might want `#subclasses` method.
     # @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`.
@@ -28,7 +29,10 @@ module Eco::Language::Klass
     # @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?
+      descendants(
+        parent_class: parent_class,
+        direct:       direct
+      ).length.positive?
     end
   end
 end

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

@@ -1,11 +1,14 @@
 module Eco::Language::Klass
   module Naming
     # Helper to normalize `key` into a correct `ruby` **constant name**
+    # @note it removes namespace syntax `::`
     # @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
+      key.to_s.strip.split('::').compact.map do |str|
+        str.slice(0).upcase + str[1..]&.downcase
+      end.join.split(/[\-\_ :]+/i).compact.map do |str|
+        str.slice(0).upcase + str[1..]&.downcase
       end.join
     end
 

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

@@ -1,15 +1,23 @@
 module Eco::Language::Klass
   module Resolver
-    # Creates a class and instance object methods with name `name` to resolve `klass` name
+    # Creates a class and instance object methods with name `name`
+    # to resolve `klass` name
+    # @note the method is defined at instance and class level.
     def class_resolver(name, klass)
       define_singleton_method(name) { resolve_class(klass) }
-      define_method(name) { self.class.resolve_class(klass) }
+      define_method(name)           { self.class.resolve_class(klass) }
     end
 
+    # Class resolver
     # 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 ||= {}
+    # @note it caches the resolved `klass`es
+    # @raise [Exception] when could not resolve if `exception` is `true`
+    # @param klass [Class, String, Symbol] the class to resolve
+    # @param source_class [Class] when the reference to `klass` belongs to a different inheritance chain.
+    # @param exception [Boolean] if it should raise exception when could not resolve
+    # @return [Class] he class that was being searched by name `klass`.
+    def resolve_class(klass, source_class: self, exception: true)
+      @resolved        ||= {}
       @resolved[klass] ||=
         case klass
         when Class
@@ -21,7 +29,14 @@ module Eco::Language::Klass
             raise if exception
           end
         when Symbol
-          resolve_class(send(klass))
+          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

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

@@ -0,0 +1,12 @@
+require 'securerandom'
+
+module Eco::Language::Klass
+  module Uid
+    # Generates random ids in hexadecimal to use in class name generation.
+    # @param len [Integeter] length of the `uid`
+    # @return [String] a random unique id of length `len`
+    def uid(len = 8)
+      SecureRandom.hex(len/2)
+    end
+  end
+end

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

@@ -1,15 +1,39 @@
 module Eco::Language::Klass
   module WhenInherited
-    def inherited(subclass)
-      super
+    class << self
+      def included(base)
+        super
 
-      subclass.instance_exec(&when_inherited)
+        base.extend InheritableClassVars
+        base.extend ClassMethods
+
+        base.inheritable_class_vars :when_inherited
+      end
     end
 
-    def when_inherited(&block)
-      return @when_inherited unless block_given?
+    module ClassMethods
+      def inherited(subclass)
+        super
+
+        when_inherited.each_value do |block|
+          block.call(subclass)
+        end
+      end
+
+      def when_inherited(section = nil, *keys, &block)
+        key               = [section || :general, *keys]
+        @when_inherited ||= {}
+
+        return @when_inherited unless block_given?
+
+        if @when_inherited.key?(key)
+          msg = "Warn: redefining inheritance on #{key} (#{self})"
+          puts msg
+        end
 
-      @when_inherited = block
+        @when_inherited[key] = block
+        @when_inherited
+      end
     end
   end
 end

data/lib/eco/language/klass.rb

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

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

@@ -0,0 +1,23 @@
+module Eco::Language::Methods
+  # Helpers to scope change from private to public, etc.
+  module AccessModifier
+    class << self
+      def included(base)
+        super
+
+        base.extend ClassMethods
+      end
+    end
+
+    module ClassMethods
+      def make_public(*args, base: self)
+        base.public(*args)
+      end
+
+      # Makes **public** in `base` all those **private** methods of `from`.
+      def make_public_all(base = self, from: base, inherited: false)
+        base.send(:public, *from.private_instance_methods(inherited: inherited))
+      end
+    end
+  end
+end

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

@@ -12,7 +12,12 @@ module Eco::Language::Methods
     module ClassMethods
       private
 
-      def unless_instance_method(base = self, name:, include_private: true, inherited: true)
+      def unless_instance_method(
+        base = self,
+        name:,
+        include_private: true,
+        inherited:       true
+      )
         return false if instance_method?(base, name: name, include_private: include_private, inherited: inherited)
 
         yield if block_given?

data/lib/eco/language/methods.rb

@@ -6,5 +6,6 @@ module Eco
 end
 
 require_relative 'methods/instance_method_helpers'
+require_relative 'methods/access_modifier'
 require_relative 'methods/call_detector'
 require_relative 'methods/dsl_able'

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

@@ -0,0 +1,41 @@
+module Eco::Language::Models
+  # Helpers for dynammic generation of classes based on a hierarchical model
+  # @note you might want to use it in combination
+  #   with `Eco::Language::Klass::HelpersBuilt`
+  # @attr_reader model [Hash, nil] the `model` of the current `class`
+  module Hierarchy
+    attr_reader :model
+
+    # @param value [Hash, Enumerable, String, Symbol, nil] unparsed model to be assigned to the `class`
+    def model=(value)
+      @model = parse_model(value)
+    end
+
+    # @return [Array<String>] the `keys` of the current class' `model`
+    def model_attrs
+      model&.keys || []
+    end
+
+    # Thanks to this step the format on the declaration of the model is flexible
+    # @param model [Hash, Enumerable, String, Symbol, nil]
+    # @return [Hash, nil] where keys are `Symbol` s
+    def parse_model(model)
+      case model
+      when String
+        parse_model(model.to_sym)
+      when Symbol
+        {model => nil}
+      when Hash
+        model.transform_keys(&:to_sym)
+      when Enumerable
+        model.each_with_object({}) do |sub, hash|
+          hash.merge!(parse_model(sub))
+        end
+      when NilClass
+        nil
+      else
+        raise "Incorrect model declaration, allowed String, Symbol, Hash and Enumerable. Given: #{model.class}"
+      end
+    end
+  end
+end