around_the_world 0.5.0 → 0.6.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 102af00bd8cee2883f110fbdc21569c3d28d5a6f3ddf991f9d0ff61e6e495ce9
-  data.tar.gz: 65e03179f83fb8e7fce01dc8d5656c6270de7a4cea41b0abfd21fa440f984803
+  metadata.gz: 27a886d37bde56a1c6edb2c15b966cda10a449c0212d5133e7678109ffe25d10
+  data.tar.gz: 35bf0553fdf79e411fce5dc412075f3daff8d2e61eae3361525110f43f9e6b5a
 SHA512:
-  metadata.gz: 463f3e58ebc0cf77787711929a010cc1f1e9750cf39a8a3d88da9f29c19df982dfb72efa6b09ce852097a731afa906ad557f8b35170fc0a4895966337d52ab6c
-  data.tar.gz: 5597d4aa0d6f958429546e8ccd6e8607565ea59b09d8d63255ae60e139da1018d5a2f47b46cb78e5056876c19e0117c3c8960bf5a916f708632728f75b09aeb3
+  metadata.gz: 0673b719dc14327044758b00bc15419d2913b76b81393ebe4840bd9d22ba60f63d74842013b0c4aefdae0a23b232cb19b2b5fef84c5930e9e0bda3f36c72d56d
+  data.tar.gz: 57612955ef4da508567167eea0c6398060b7a40992baf8a99cb84033e8981c62b43beda02e95d2b3070ebe89f632e8b9d67e8c4d69c930463f91c5c8c9b187f8

data/lib/around_the_world/method_wrapper/proxy_creation.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module AroundTheWorld
+  class MethodWrapper
+    module ProxyCreation
+      private
+
+      # @return [Boolean] Returns true if the method has beeen wrapped for the given purpose,
+      #                   whether or not that wrapper applies to subclassed methods.
+      def already_wrapped?(method_name, target, purpose)
+        existing_proxy_modules(target).any? { |mod| mod.for?(purpose) && mod.defines_proxy_method?(method_name) }
+      end
+
+      # @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 given purpose.
+      def proxy_module_with_purpose(method_name, target, purpose, wrap_subclasses)
+        existing_proxy_module_with_purpose(method_name, target, purpose, wrap_subclasses) ||
+          ProxyModule.new(purpose: purpose, wrap_subclasses: wrap_subclasses?)
+      end
+
+      def existing_proxy_module_with_purpose(method_name, target, purpose, wrap_subclasses)
+        existing_proxy_modules(target).reverse_each.find do |ancestor|
+          ancestor.for?(purpose) &&
+            !ancestor.defines_proxy_method?(method_name) &&
+            ancestor.wraps_subclasses? == wrap_subclasses
+        end
+      end
+
+      # @return [Array<AroundTheWorld::ProxyModule>] All ProxyModules +prepended+ to the target module.
+      def existing_proxy_modules(target)
+        target_ancestry_index = base_ancestry_index(target)
+
+        @existing_proxy_modules ||= {}
+        @existing_proxy_modules[target] ||= target.ancestors.select.with_index do |ancestor, index|
+          next if index >= target_ancestry_index
+
+          ancestor.is_a? ProxyModule
+        end
+      end
+
+      # @return [Integer] The index of the target module in its ancestry array
+      def base_ancestry_index(target)
+        target.ancestors.index(target)
+      end
+    end
+  end
+end

data/lib/around_the_world/method_wrapper.rb

@@ -1,28 +1,41 @@
 # frozen_string_literal: true
 
+require_relative "method_wrapper/proxy_creation"
+
 module AroundTheWorld
   class MethodWrapper
+    include ProxyCreation
+
+    private_class_method :new
+
     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
+      # Passes arguments directly to {#new} - see {#initialize} for full docs
+      def wrap(**args, &block)
+        new(**args, &block).wrap
       end
     end
 
-    attr_reader :method_name, :target, :prevent_double_wrapping_for, :block
+    attr_reader :method_name, :target
 
-    # @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]
+    # @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.
+    # @param :wrap_subclasses [Boolean]
+    #   If true, the given method will still be wrapped by the given block in subclasses that override the given method.
+    #   If false, subclasses that override the method will also override the wrapping block.
+    #   Default: false
     # @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)
+    def initialize(method_name:, target:, prevent_double_wrapping_for: nil, wrap_subclasses: false, &block)
+      raise TypeError, "target must be a module or a class" unless target.is_a?(Module)
+
       @method_name = method_name.to_sym
       @target = target
-      @prevent_double_wrapping_for = prevent_double_wrapping_for
+      @prevent_double_wrapping_for = prevent_double_wrapping_for || nil
+      @wrap_subclasses = wrap_subclasses
       @block = block
     end
 
@@ -37,6 +50,16 @@ module AroundTheWorld
 
     private
 
+    attr_reader :prevent_double_wrapping_for, :wrap_subclasses, :block
+
+    def prevent_double_wrapping?
+      prevent_double_wrapping_for.present?
+    end
+
+    def wrap_subclasses?
+      wrap_subclasses.present?
+    end
+
     def ensure_method_defined!
       return if target.instance_methods(true).include?(method_name) || target.private_method_defined?(method_name)
 
@@ -44,7 +67,7 @@ module AroundTheWorld
     end
 
     def prevent_double_wrapping!
-      return unless proxy_module_for(prevent_double_wrapping_for)&.instance_methods&.include?(method_name)
+      return unless already_wrapped?(method_name, target, prevent_double_wrapping_for)
 
       raise DoubleWrapError, "Module #{proxy_module} already defines the method :#{method_name}"
     end
@@ -70,46 +93,9 @@ module AroundTheWorld
       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)
+      @proxy_module ||= proxy_module_with_purpose(method_name, target, prevent_double_wrapping_for, wrap_subclasses?)
     end
   end
 end

data/lib/around_the_world/proxy_module.rb

@@ -4,18 +4,29 @@ module AroundTheWorld
   class ProxyModule < Module
     attr_reader :purpose
 
-    def initialize(purpose: nil)
+    def initialize(purpose: nil, wrap_subclasses: false)
       @purpose = purpose unless purpose.blank?
+      @wrap_subclasses = wrap_subclasses
     end
 
     def for?(purpose)
-      return false if self.purpose.blank?
-
       self.purpose == purpose
     end
 
+    def wraps_subclasses?
+      wrap_subclasses.present?
+    end
+
     def inspect
       "#<#{self.class.name}#{":#{purpose}" if purpose}>"
     end
+
+    def defines_proxy_method?(method_name)
+      instance_methods(true).include?(method_name.to_sym) || private_method_defined?(method_name.to_sym)
+    end
+
+    private
+
+    attr_reader :wrap_subclasses
   end
 end

data/lib/around_the_world/rewrapper.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/array"
+require_relative "method_wrapper/proxy_creation"
+
+module AroundTheWorld
+  class Rewrapper
+    include MethodWrapper::ProxyCreation
+
+    private_class_method :new
+
+    class << self
+      def rewrap(target, proxy_modules)
+        new(target, proxy_modules).rewrap
+      end
+    end
+
+    attr_reader :target, :proxy_modules
+
+    def initialize(target, proxy_modules)
+      @target = target
+      @proxy_modules = Array.wrap(proxy_modules)
+    end
+
+    def rewrap
+      proxy_modules.each do |mod|
+        next if existing_proxy_modules(target).include?(mod)
+
+        target.prepend mod
+      end
+    end
+  end
+end

data/lib/around_the_world/version.rb

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

data/lib/around_the_world.rb

@@ -2,13 +2,19 @@
 
 require_relative "around_the_world/errors"
 require_relative "around_the_world/method_wrapper"
+require_relative "around_the_world/rewrapper"
 require_relative "around_the_world/proxy_module"
 require_relative "around_the_world/version"
 require "active_support/concern"
+require "active_support/descendants_tracker"
 
 module AroundTheWorld
   extend ActiveSupport::Concern
 
+  included do
+    extend ActiveSupport::DescendantsTracker
+  end
+
   class_methods do
     protected
 
@@ -52,28 +58,34 @@ module AroundTheWorld
     #   # => no error raised
     #
     # @param method_name [Symbol]
-    # @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
+    # @param :wrap_subclasses [Boolean]
+    #   If true, the given method will still be wrapped by the given block in subclasses that override the given method.
+    #   If false, subclasses that override the method will also override the wrapping block.
+    #   Default: false
+    def around_method(method_name, prevent_double_wrapping_for: nil, wrap_subclasses: false, &block)
+      MethodWrapper.wrap(
+        method_name: method_name,
+        target: self,
+        prevent_double_wrapping_for: prevent_double_wrapping_for,
+        wrap_subclasses: wrap_subclasses,
+        &block
+      )
+
+      descendants.each { |child| Rewrapper.rewrap(child, proxy_modules_for_subwrapping) }
+    end
+
+    def inherited(child)
+      super
+
+      Rewrapper.rewrap(child, proxy_modules_for_subwrapping)
+    end
 
-        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
+    private
 
-      MethodWrapper.wrap(method_name, self, prevent_double_wrapping_for, &block)
+    def proxy_modules_for_subwrapping
+      ancestors.select { |mod| mod.is_a?(ProxyModule) && self < mod && mod.wraps_subclasses? }
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: around_the_world
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0.pre
 platform: ruby
 authors:
 - Allen Rettberg
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-12-04 00:00:00.000000000 Z
+date: 2019-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -36,7 +36,9 @@ files:
 - lib/around_the_world.rb
 - lib/around_the_world/errors.rb
 - lib/around_the_world/method_wrapper.rb
+- lib/around_the_world/method_wrapper/proxy_creation.rb
 - lib/around_the_world/proxy_module.rb
+- lib/around_the_world/rewrapper.rb
 - lib/around_the_world/version.rb
 homepage: https://www.freshly.com
 licenses:
@@ -53,9 +55,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.7.6