around_the_world 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf3d2cd621e18996b29ef47dc0fd22a933cf6fa4add557b04a1cecbafbd6ae49
-  data.tar.gz: 2584124852e8f1d30b240bdd59da3ddebe92f1e553b72cf187be45030400f7e0
+  metadata.gz: 102af00bd8cee2883f110fbdc21569c3d28d5a6f3ddf991f9d0ff61e6e495ce9
+  data.tar.gz: 65e03179f83fb8e7fce01dc8d5656c6270de7a4cea41b0abfd21fa440f984803
 SHA512:
-  metadata.gz: 97f1643c1942aef0020fc6c3d82deb5e75bf871f927d9571ddb898aa34816b6ee2b0c756089855e323b35ce89176a1ad8f54bc5fb70ca912f867e2037cd1c28b
-  data.tar.gz: be6f2f090b1c17a1e1dd094f030393400eddccdac6ac39d159427c9111fdc5ec1afd9475073ac380ca16243734d78194da1e256a3442dc1a2967c0f4cb41e0f6
+  metadata.gz: 463f3e58ebc0cf77787711929a010cc1f1e9750cf39a8a3d88da9f29c19df982dfb72efa6b09ce852097a731afa906ad557f8b35170fc0a4895966337d52ab6c
+  data.tar.gz: 5597d4aa0d6f958429546e8ccd6e8607565ea59b09d8d63255ae60e139da1018d5a2f47b46cb78e5056876c19e0117c3c8960bf5a916f708632728f75b09aeb3

data/lib/around_the_world.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
-require_relative "around_the_world/version"
 require_relative "around_the_world/errors"
+require_relative "around_the_world/method_wrapper"
+require_relative "around_the_world/proxy_module"
+require_relative "around_the_world/version"
 require "active_support/concern"
 
 module AroundTheWorld
@@ -14,7 +16,7 @@ module AroundTheWorld
     #
     # @example
     #   class SomeClass
-    #     around_method :dont_look_in_here, "DoesAThing" do
+    #     around_method :dont_look_in_here do
     #       things_happened = super
     #
     #       if things_happened
@@ -32,36 +34,46 @@ module AroundTheWorld
     #   SomeClass.new.dont_look_in_here
     #   => "Something happened!"
     #
+    # @example
+    #   around_method :dont_look_in_here, prevent_double_wrapping_for: :memoization do
+    #     @memoized ||= super
+    #   end
+    #
+    #   around_method :dont_look_in_here, prevent_double_wrapping_for: :memoization do
+    #     @memoized ||= super
+    #   end
+    #   # => AroundTheWorld::DoubleWrapError:
+    #          "Module AroundTheWorld:ProxyModule:memoization already defines the method :dont_look_in_here"
+    #
+    #   around_method :dont_look_in_here do
+    #     do_something_else
+    #     super
+    #   end
+    #   # => no error raised
+    #
     # @param method_name [Symbol]
-    # @param proxy_module_name [String] The camelized name of a custom module to place the wrapper method in.
-    #                                   This is necessary to enable wrapping a single method more than once
-    #                                   since a module cannot super to itself.
-    #                                   It's recommended to name the module after what the method wrapper will do,
-    #                                   for example LogsAnEvent for a wrapper method that logs something.
-    #                                   Because of the potential for overriding previously wrapped methods, this
-    #                                   parameter is required.
-    def around_method(method_name, proxy_module_name, &block)
-      proxy_module = around_method_proxy_module(proxy_module_name)
-      ensure_around_method_uniqueness!(method_name, proxy_module)
-
-      proxy_module.define_method(method_name, &block)
-      prepend proxy_module unless ancestors.include?(proxy_module)
-    end
-
-    private
-
-    def around_method_proxy_module(proxy_module_name)
-      namespaced_proxy_module_name = "#{self}::#{proxy_module_name}"
-
-      const_set(proxy_module_name, Module.new) unless const_defined?(namespaced_proxy_module_name)
-
-      const_get(namespaced_proxy_module_name)
-    end
+    # @param proxy_module_name [String]
+    #   DEPRECATED: this argument is deprecated and will be removed in a future release.
+    #     Use the :prevent_double_wrapping_for option instead.
+    #   The camelized name of a custom module to place the wrapper method in. This is necessary
+    #   to enable wrapping a single method more than once since a module cannot super to itself.
+    #   It's recommended to name the module after what the method wrapper will do, for example
+    #   LogsAnEvent for a wrapper method that logs something. Because of the potential for
+    #   overriding previously wrapped methods, this parameter is required.
+    #
+    # @param :prevent_double_wrapping_for [Object]
+    #   If defined, this prevents wrapping the method twice for a given purpose. Accepts any argument.
+    def around_method(method_name, proxy_module_name = nil, prevent_double_wrapping_for: nil, &block)
+      if proxy_module_name
+        prevent_double_wrapping_for ||= proxy_module_name
 
-    def ensure_around_method_uniqueness!(method_name, proxy_module)
-      return unless proxy_module.instance_methods.include?(method_name.to_sym)
+        puts <<~DEPRECATION
+          DEPRECATION WARNING: the proxy_module_name argument is deprecated and will be removed
+            in version 1.0. Please use the :prevent_double_wrapping_for option instead.
+        DEPRECATION
+      end
 
-      raise DoubleWrapError, "Module #{proxy_module} already defines the method :#{method_name}"
+      MethodWrapper.wrap(method_name, self, prevent_double_wrapping_for, &block)
     end
   end
 end

data/lib/around_the_world/errors.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module AroundTheWorld
+  class MethodNotDefinedError < NoMethodError; end
   class DoubleWrapError < StandardError; end
 end

data/lib/around_the_world/method_wrapper.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module AroundTheWorld
+  class MethodWrapper
+    class << self
+      # Passes arguments directly to {#new} - see docs
+      def wrap(method_name, target, prevent_double_wrapping_for = false, &block)
+        new(method_name, target, prevent_double_wrapping_for, &block).wrap
+      end
+    end
+
+    attr_reader :method_name, :target, :prevent_double_wrapping_for, :block
+
+    # @param method_name [String, Symbol] The name of the method to be wrapped.
+    # @param target [Module] The class or module containing the method to be wrapped.
+    # @param prevent_double_wrapping_for [String, Symbol]
+    #   An identifier to define the proxy module's purpose in the ancestor tree.
+    #   A method can only be wrapped once for a given purpose, though it can be wrapped
+    #   again for other purposes, or for no given purpose.
+    # @block The block that will be executed when the method is invoked.
+    #        Should always call super, at least conditionally.
+    def initialize(method_name, target, prevent_double_wrapping_for = false, &block)
+      @method_name = method_name.to_sym
+      @target = target
+      @prevent_double_wrapping_for = prevent_double_wrapping_for
+      @block = block
+    end
+
+    # Defines the wrapped method inside a proxy module and prepends the proxy module to the target module if necessary.
+    def wrap
+      ensure_method_defined!
+      prevent_double_wrapping! if prevent_double_wrapping?
+
+      define_proxy_method
+      target.prepend proxy_module unless target.ancestors.include?(proxy_module)
+    end
+
+    private
+
+    def ensure_method_defined!
+      return if target.instance_methods(true).include?(method_name) || target.private_method_defined?(method_name)
+
+      raise MethodNotDefinedError, "#{target} does not define :#{method_name}"
+    end
+
+    def prevent_double_wrapping!
+      return unless proxy_module_for(prevent_double_wrapping_for)&.instance_methods&.include?(method_name)
+
+      raise DoubleWrapError, "Module #{proxy_module} already defines the method :#{method_name}"
+    end
+
+    def define_proxy_method
+      proxy_module.define_method(method_name, &block)
+
+      proxy_module.instance_exec(method_name, method_privacy) do |method_name, method_privacy|
+        case method_privacy
+        when :protected
+          protected method_name
+        when :private
+          private method_name
+        end
+      end
+    end
+
+    def method_privacy
+      if target.protected_method_defined?(method_name)
+        :protected
+      elsif target.private_method_defined?(method_name)
+        :private
+      end
+    end
+
+    def prevent_double_wrapping?
+      !prevent_double_wrapping_for.blank?
+    end
+
+    # @return [AroundTheWorld::ProxyModule] The proxy module upon which the method wrapper will be defined
+    def proxy_module
+      return @proxy_module ||= proxy_module_for(prevent_double_wrapping_for) if prevent_double_wrapping?
+
+      @proxy_module ||= first_available_proxy_module || ProxyModule.new
+    end
+
+    # @param purpose [String, Symbol] An identifier to define the proxy module's purpose in the ancestor tree.
+    # @return [AroundTheWorld::ProxyModule] Either an already-defined proxy module for the given purpose,
+    #                                       or a new proxy module if one does not exist for the gibven purpose.
+    def proxy_module_for(purpose)
+      raise ArgumentError if purpose.blank?
+
+      existing_proxy_modules.find { |proxy_module| proxy_module.for?(purpose) } ||
+        ProxyModule.new(purpose: prevent_double_wrapping_for)
+    end
+
+    # @return [AroundTheWorld::ProxyModule] The first defined ProxyModule that does not define the method to be wrapped.
+    # @return [NilClass] If all prepended ProxyModules already define the method,
+    #                    or no ProxyModules have been prepended yet.
+    def first_available_proxy_module
+      existing_proxy_modules.reverse_each.find { |ancestor| !ancestor.instance_methods.include?(method_name) }
+    end
+
+    # @return [Array<AroundTheWorld::ProxyModule>] All ProxyModules +prepended+ to the target module.
+    def existing_proxy_modules
+      @existing_proxy_modules ||= target.ancestors.select.with_index do |ancestor, index|
+        next if index >= base_ancestry_index
+
+        ancestor.is_a? ProxyModule
+      end
+    end
+
+    # @return [Integer] The index of the target module in its ancestry array
+    def base_ancestry_index
+      @base_ancestry_index = target.ancestors.index(target)
+    end
+  end
+end

data/lib/around_the_world/proxy_module.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module AroundTheWorld
+  class ProxyModule < Module
+    attr_reader :purpose
+
+    def initialize(purpose: nil)
+      @purpose = purpose unless purpose.blank?
+    end
+
+    def for?(purpose)
+      return false if self.purpose.blank?
+
+      self.purpose == purpose
+    end
+
+    def inspect
+      "#<#{self.class.name}#{":#{purpose}" if purpose}>"
+    end
+  end
+end

data/lib/around_the_world/version.rb

@@ -2,5 +2,5 @@
 
 module AroundTheWorld
   # This constant is managed by spicerack
-  VERSION = "0.4.3"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: around_the_world
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.5.0
 platform: ruby
 authors:
 - Allen Rettberg
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-10-10 00:00:00.000000000 Z
+date: 2018-12-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -35,6 +35,8 @@ files:
 - README.md
 - lib/around_the_world.rb
 - lib/around_the_world/errors.rb
+- lib/around_the_world/method_wrapper.rb
+- lib/around_the_world/proxy_module.rb
 - lib/around_the_world/version.rb
 homepage: https://www.freshly.com
 licenses: