alias_callable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4334c1231c35835f8201a245e9311facbf5955d7586eff0b4f50787640f418c2
+  data.tar.gz: fe35d58d1cf341250766a2aa564ac05045d18c4360852cb50d86b26c92416b94
+SHA512:
+  metadata.gz: 823997bf9df2033c1a3d3e9159d3e9ede6e0dfc3b2b0d855bac9f2647803f5edcb087d53307b715e51c6ed2b99772a227615857bea07099d269264268278c50e
+  data.tar.gz: 226205bb435b18b36c3f6113170d71f67b2493e80b1dd0734fcdb51f333d1ab3fa8fbea368421be1f576abda7eb924820d43223ea23765008221446e98fefe42

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vladimir Gorodulin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,3 @@
+# alias_callable Ruby gem
+
+> **Keywords:** #alias #method #function #callable #ruby #gem #p20240728a #dependency #inclusion

data/lib/alias_callable/build_alias_method.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module AliasCallable
+
+  class BuildAliasMethod
+    def self.call(**kwargs)
+      new(**kwargs).call
+    end
+
+    def initialize(alias_name:, callable:, auto_fill: [])
+      @alias_name = alias_name
+      @callable = callable
+      @auto_fill = auto_fill
+    end
+
+    def call
+      ensure_auto_fill_validity! # Ensure that the auto_fill arguments are valid
+      signature = generate_method_signature # Generate method signature with proper parameters
+      kwargs_logic = generate_kwargs_logic # Generate code to handle keyword arguments with auto-fetching
+      call_expression = generate_call_expression # Generate the final method call with all arguments
+
+      <<-RUBY
+        def #{alias_name}(#{signature})
+          kwargs = {}
+          #{kwargs_logic}
+          #{call_expression}
+        end
+      RUBY
+    end
+
+    private
+
+    attr_reader :alias_name, :callable, :auto_fill
+
+    def params
+      @params ||= ::AliasCallable::ExtractCallableParameters.new(callable).call
+    end
+
+    def ensure_auto_fill_validity!
+      unsupported = auto_fill - params.keywords
+      if unsupported.any? # rubocop:disable Style/GuardClause
+        raise ArgumentError, "Unsupported auto_fill arguments: #{unsupported.join(', ')}"
+      end
+    end
+
+    def generate_method_signature
+      parts = []
+
+      # Add positional parameters if any
+      if params.positionals.any? || params.rest?
+        parts << "*args"
+      end
+
+      if auto_fill.any?
+        parts << auto_fill.map do |kw|
+          "#{kw}: ::AliasCallable::UNDEFINED"
+        end.join(", ")
+      end
+
+      # Always add keyrest capture to support methods with **kwargs
+      # Even if the callable doesn't have keyrest, this allows for more flexible method calls
+      parts << "**extra_kwargs"
+
+      # Always include block parameter to support both explicit &block and block_given?
+      parts << "&block"
+
+      parts.join(", ")
+    end
+
+    def generate_kwargs_logic
+      logic = []
+
+      auto_fill.each do |kw|
+        logic << <<-RUBY
+          if #{kw} != ::AliasCallable::UNDEFINED
+            kwargs[:#{kw}] = #{kw}
+          elsif respond_to?(:#{kw}, true)
+            kwargs[:#{kw}] = send(:#{kw})
+          elsif instance_variable_defined?("@#{kw}")
+            kwargs[:#{kw}] = instance_variable_get("@#{kw}")
+          end
+        RUBY
+      end
+
+      # Handle extra_kwargs (always include them in kwargs)
+      # Merge any additional keyword arguments
+      logic << <<-RUBY
+        kwargs.merge!(extra_kwargs) unless extra_kwargs.empty?
+      RUBY
+
+      logic.join("\n")
+    end
+
+    def generate_call_expression
+      parts = []
+
+      # Add positional args if needed
+      if params.positionals.any? || params.rest?
+        parts << "*args"
+      end
+
+      # Add keyword args
+      parts << "**kwargs"
+
+      # Always pass the block, regardless of whether the callable has an explicit block parameter
+      # This ensures support for callables that use block_given? internally
+      parts << "&block"
+
+      "_callable__#{alias_name}.call(#{parts.join(', ')})"
+    end
+  end
+
+end

data/lib/alias_callable/class_methods.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module AliasCallable
+
+  module ClassMethods
+    def alias_callable(alias_name, callable, auto_fill: [])
+      method_code = ::AliasCallable::BuildAliasMethod
+        .call(alias_name: alias_name, callable: callable, auto_fill: auto_fill)
+      # Define the delegator method with smart argument forwarding
+      class_eval(method_code)
+      # Define the "raw" delegator method and make it private
+      # This is the method that will be called by the delegator (alias) method
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def _callable__#{alias_name}       # def _callable__do_something
+          #{callable}                      #   ::DoSomething
+        end                                # end
+        private :_callable__#{alias_name}  # private :_callable__do_something
+      RUBY
+      alias_name
+    end
+
+    def aliased_callable(alias_name)
+      get_attached_object = lambda do |sc|
+        if sc.respond_to?(:attached_object)
+          sc.attached_object
+        else # Ruby 3.2 and earlier support. Slow, but better than nothing :(
+          ::ObjectSpace.each_object(Object).find { |o| o.is_a?(Module) && o.singleton_class == sc }
+        end
+      end
+      target = self.singleton_class? ? get_attached_object.call(self) : self.allocate # rubocop:disable Style/RedundantSelf
+      helper_name = :"_callable__#{alias_name}"
+      unless target.private_methods.include?(helper_name)
+        raise ::AliasCallable::UnknownCallableError, "No callable registered as `#{alias_name}` in #{self}."
+      end
+      target.send(helper_name)
+    end
+  end
+
+end

data/lib/alias_callable/extract_callable_parameters.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module AliasCallable
+
+  # Extracts parameters from a callable object (class/module)
+  class ExtractCallableParameters
+    def initialize(callable)
+      @callable = callable
+    end
+
+    # Main method to extract parameter information from the callable
+    def call
+      info = ParameterInfo.new
+
+      target_method_parameters.each do |param_type, param_name|
+        case param_type
+        when :key, :keyreq
+          info.keywords << param_name
+        when :req, :opt
+          info.positionals << param_name
+        when :rest
+          info.rest = true
+        when :keyrest
+          info.keyrest = true
+        end
+      end
+
+      info
+    end
+
+    private
+
+    # Determine which method's parameters we should extract
+    def target_method_parameters
+      if callable_responds_to_call? && !call_forwards_all_arguments?
+        class_callable_parameters # Parameters of callable.call method
+      elsif instance_initialize_parameters.any?
+        instance_initialize_parameters # Parameters of callable.new method
+      else
+        instance_callable_parameters # Parameters of callable.new.call method
+      end
+    end
+
+    def callable_responds_to_call?
+      @callable.respond_to?(:call)
+    end
+
+    def call_forwards_all_arguments?
+      return false if @callable.is_a?(Module) # not instantiable, so nowhere to forward
+      return false unless @callable.instance_methods.include?(:call)
+
+      full_argument_forwarding_pattern?(class_callable_parameters)
+    end
+
+    def full_argument_forwarding_pattern?(parameters)
+      # See NOTES.md on full forwarding parameter patterns.
+      # Handles:
+      # - explicit *args, **kwargs, &block style regardless of parameter names
+      # - *args, &block with ruby2_keywords (which lacks visible :keyrest in Ruby 2.7-3.0)
+      # - the ... syntax in both
+      #   - Ruby 3.0 (which showed [[:rest, :*], [:block, :&]]) and
+      #   - Ruby 3.1+ (which shows [[:rest, :*], [:keyrest, :**], [:block, :&]])
+
+      # Skip methods with specific required, optional or keyword parameters
+      return false if parameters.any? do |param|
+        [:req, :opt, :key, :keyreq].include?(param[0])
+      end
+
+      # Extract the parameter types (ignoring names)
+      param_types = parameters.map { |param| param[0] }
+
+      # Check for the required pattern components
+      has_rest = param_types.include?(:rest)
+      has_block = param_types.include?(:block)
+
+      # Consider keyrest optional because:
+      # 1. Ruby 3.0's `...` syntax initially didn't show keyrest in parameters inspection
+      # 2. Explicit `*args, &block` (without keyrest) can still forward all arguments
+      # in certain Ruby versions with ruby2_keywords applied
+
+      # Must have at minimum rest + block
+      if has_rest && has_block
+        # No other parameter types should exist beyond rest, keyrest, and block
+        extra_params = param_types - [:rest, :keyrest, :block]
+        return extra_params.empty?
+      end
+
+      false
+    end
+
+    def class_callable_parameters
+      @callable.method(:call).parameters # TODO: memoize
+    end
+
+    def instance_initialize_parameters
+      @callable.instance_method(:initialize).parameters # TODO: memoize
+    rescue NameError
+      []
+    end
+
+    def instance_callable_parameters
+      instance = @callable.allocate rescue nil # rubocop:disable Style/RescueModifier
+      instance&.method(:call)&.parameters || []
+    end
+  end
+
+end

data/lib/alias_callable/parameter_info.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module AliasCallable
+
+  ParameterInfo = Struct.new(:keywords, :positionals, :rest, :keyrest) do
+
+    def initialize
+      super([], [], false, false)
+    end
+
+    alias_method :rest?, :rest
+    alias_method :keyrest?, :keyrest
+
+  end
+
+end

data/lib/alias_callable/undefined.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module AliasCallable
+
+  UNDEFINED = Class.new do
+
+    def inspect
+      "UNDEFINED"
+    end
+
+    alias_method :to_s, :inspect
+
+  end.new
+
+end

data/lib/alias_callable/unknown_callable_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module AliasCallable
+
+  UnknownCallableError = Class.new(StandardError)
+
+end

data/lib/alias_callable/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module AliasCallable
+
+  VERSION = "0.1.0"
+
+end

data/lib/alias_callable.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module AliasCallable
+
+  autoload :BuildAliasMethod,             "alias_callable/build_alias_method"
+  autoload :ClassMethods,                 "alias_callable/class_methods"
+  autoload :ExtractCallableParameters,    "alias_callable/extract_callable_parameters"
+  autoload :ParameterInfo,                "alias_callable/parameter_info"
+  autoload :UNDEFINED,                    "alias_callable/undefined"
+  autoload :UnknownCallableError,         "alias_callable/unknown_callable_error"
+  autoload :VERSION,                      "alias_callable/version"
+
+  @backtrace_filtering_enabled = false
+
+  def self.enable_globally
+    ::Module.include(::AliasCallable::ClassMethods) unless enabled_globally?
+  end
+
+  def self.enabled_globally?
+    ::Module.included_modules.include?(::AliasCallable::ClassMethods)
+  end
+
+  def self.enable_backtrace_filtering
+    return if backtrace_filtering_enabled?
+
+    ::Exception.class_eval do
+      alias_method :original_backtrace, :backtrace
+
+      def backtrace
+        bt = original_backtrace
+        bt&.grep_v(%r{/alias_callable/})
+      end
+    end
+
+    @backtrace_filtering_enabled = true
+  end
+
+  def self.backtrace_filtering_enabled?
+    @backtrace_filtering_enabled
+  end
+
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: alias_callable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Vladimir Gorodulin
+bindir: bin
+cert_chain: []
+date: 2025-04-11 00:00:00.000000000 Z
+dependencies: []
+description: Bring callable classes to your code as methods.
+email:
+- ru.hostmaster@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/alias_callable.rb
+- lib/alias_callable/build_alias_method.rb
+- lib/alias_callable/class_methods.rb
+- lib/alias_callable/extract_callable_parameters.rb
+- lib/alias_callable/parameter_info.rb
+- lib/alias_callable/undefined.rb
+- lib/alias_callable/unknown_callable_error.rb
+- lib/alias_callable/version.rb
+homepage: https://github.com/gorodulin/alias_callable
+licenses:
+- MIT
+metadata:
+  changelog_uri: https://github.com/gorodulin/alias_callable/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/gorodulin/alias_callable
+  source_code_uri: https://github.com/gorodulin/alias_callable/tree/main
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Call Service Objects with ease. Include them to your classes as methods!
+test_files: []