tiny_hooks 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c9ab59bc23d29d510f328d7b6c0f19bfc9b561b37b6865174cccb1470e76513
-  data.tar.gz: 58f946a1c561d3a52d4f3cb5b1943a0af75cd20e7c6fb1db3386406b55266f3c
+  metadata.gz: c5d6e7ef3a23f548af13f1f6497d5ac5eedcf833d8090380b085a9c85bddf37a
+  data.tar.gz: 6992a9ce9f85531803f35f009817b0b7c0b140088e64b9f38c67f4b0225e7d0d
 SHA512:
-  metadata.gz: 2faa91f190024c927083e05a50861c4a367aa7f1a16dd2d88e2925081b96b91ea5e235eff0e7e7ec9d85a778dd5bfbcbc20a93e77050fa0aa8d4562dc3ebc13f
-  data.tar.gz: db4bc764b7e46918680cd552cf7fdde2b968fe728c30e5e67a0da896a4b6a0a24d72e62b5b4e9100ce65f7cca28c31effe460aff82d2f949c6f9fcf18c929543
+  metadata.gz: 9dfd1ec6b94c48b2309bf4f713dccdd7d8ae572b6ea42615ebb891238306c84224b15657f9fe77d1f3f6ae8a7f45b26c6ac347183d7bde7750e0a6d6a0879a38
+  data.tar.gz: 109d45de44c9309ad233b8a819550306016e6dacb33a7f2a8980de4fddda7562839e6f7463c9c2b0a730544322941d21acfba1b77ea50bb6e7dbc18cdf62dffb

data/.rubocop.yml

@@ -30,13 +30,18 @@ Layout/MultilineAssignmentLayout:
 Lint/ConstantResolution:
   Enabled: false
 
-Metrics/MethodLength:
-  Max: 15
+# I couldn't come up with code clean enough
+# For now I gave up following Metrics cops
+Metrics:
+  Enabled: false
 
 Security/Eval:
   Exclude:
     - 'test/**/*.rb'
 
+Style/ClassVars:
+  Enabled: false
+
 Style/ConstantVisibility:
   Exclude:
     - 'lib/tiny_hooks/version.rb'

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [1.0.0] - 2021-05-09
+
+- Support halting
+- [BREAKING CHANGE] Inferface changed from `extend` to `include`
+- Support public only mode enabled by `public_only!`
+- Support targeting with `target!`
+- Support `if` option of `define_hook`
+
 ## [0.3.0] - 2021-04-10
 
 - Implement restoration of original method

data/Gemfile

@@ -14,3 +14,7 @@ gem 'rubocop-minitest', '~> 0.11.0', require: false # For lint
 gem 'rubocop-performance', '~> 1.10.1', require: false # For lint
 gem 'rubocop-rake', '>= 0.5.1', require: false # For lint
 gem 'rubocop-sensible', '~> 0.3.0', require: false # For lint
+
+# Benchmark
+gem 'activesupport'
+gem 'benchmark_driver'

data/README.md

@@ -20,11 +20,11 @@ Or install it yourself as:
 
 ## Usage
 
-`extend TinyHooks` in your class/module and you're all set to use `define_hook`!
+`include TinyHooks` in your class/module and you're all set to use `define_hook`!
 
 ```ruby
 class MyClass
-  extend TinyHooks
+  include TinyHooks
 
   def my_method
     puts 'my method'
@@ -41,15 +41,170 @@ MyClass.new.my_method
 
 TinyHooks shines when the class/module is the base class/module of your library and your users will inherit/include it. In these cases, end users can define hooks to the methods you provide. The only thing you have to do is to provide the list of methods.
 
-## Difference between TinyHooks and ActiveSupport::Callbacks
+### Halting
+
+You can halt hook and method body execution by `throw`ing `:abort`.
+
+```ruby
+class MyClass
+  include TinyHooks
+
+  def my_method
+    puts 'my method'
+  end
+
+  define_hook :before, :my_method do
+    throw :abort
+    puts 'my before hook'
+  end
+end
+
+MyClass.new.my_method
+# => ""
+```
+
+You can change how to halt from two options: throwing `:abort` and returning `false`. This can be done via `terminator` option.
+
+```ruby
+class MyClass
+  include TinyHooks
+
+  def my_method
+    puts 'my method'
+  end
+
+  define_hook :before, :my_method, terminator: :return_false do
+    false
+  end
+end
+
+MyClass.new.my_method
+# => ""
+```
+
+### Targeting for hooks
+
+You can limit the targets for hooks in two ways. You can enable hooks for public methods only by using `public_only!` method and include/exclude targets with Regexp pattern by using `targets!` method.
+
+```ruby
+class MyClass
+  include TinyHooks
+
+  def my_method
+    puts 'my method'
+  end
+
+  private
+
+  def my_private_method
+    puts 'my private method'
+  end
+end
+
+class MyClassWithPublicOnly < MyClass
+  public_only!
+
+  define_hook :before, :my_private_method do
+    puts 'my_private_method'
+  end
+  # => This causes PrivateError
+end
+
+class MyClassWithExclude < MyClass
+  target! exclude_pattern: /my_method/
+
+  define_hook :before, :my_method do
+    puts 'my_method'
+  end
+  # => This causes TargetError
+end
+```
+
+You can call `include_private!` method to disable the effect of `public_only!`.
+
+### Conditional hooks
+
+You can add `if` option to `define_hook` call. `if` option must be a Proc and is evaluated in context of an instance.
+
+```ruby
+class MyClass
+  include TinyHooks
+
+  def initialize(hook_enabled = true)
+    @hook_enabled = hook_enabled
+  end
+
+  def my_method
+    puts 'my method'
+  end
+
+  def hook_enabled?
+    @hook_enabled
+  end
+
+  define_hook :before, :my_method, if: -> { hook_enabled? } do
+    puts 'my before hook'
+  end
+end
+
+MyClass.new(true).my_method
+# => "my before hook\nmy method\n"
+
+MyClass.new(false).my_method
+# => "my method\n"
+```
+
+## Differences between TinyHooks and ActiveSupport::Callbacks
 
 While `TinyHooks` and `ActiveSupport::Callbacks` share the same purpose, there are a few major differences.
 
-* `TinyHooks` doesn’t support halting, but will support in the future.
+### Differences in usage
+
 * While `ActiveSupport::Callbacks` has a set of methods for callbacks to work, `TinyHooks` has only one method.
 * You can apply callbacks/hooks into any existing methods without any changes with `TinyHooks`, while you need to change methods to call `run_callbacks` method within them to apply callbacks with `ActiveSupport::Callbacks`.
 
-In short, `TinyHooks` is simpler while `ActiveSupport::Callbacks` allows more control over callbacks.
+### Differences in performance
+
+According to the [benchmark](https://github.com/okuramasafumi/tiny_hooks/blob/main/benchmark/compare_to_as_callbacks.rb), `TinyHooks` is 1.6 times as fast as `ActiveSupport::Callbacks` when before and after callbacks are applied, and twice as fast when no callbacks are applied.
+
+The result on my machine:
+
+```
+Warming up --------------------------------------
+       ActiveSupport   246.181k i/s -    256.956k times in 1.043769s (4.06μs/i)
+           TinyHooks   282.834k i/s -    293.502k times in 1.037719s (3.54μs/i)
+Calculating -------------------------------------
+       ActiveSupport   230.196k i/s -    738.542k times in 3.208320s (4.34μs/i)
+           TinyHooks   373.057k i/s -    848.501k times in 2.274453s (2.68μs/i)
+
+Comparison:
+           TinyHooks:    373057.2 i/s
+       ActiveSupport:    230195.9 i/s - 1.62x  slower
+
+Warming up --------------------------------------
+ActiveSupport no callback set     1.992M i/s -      2.096M times in 1.052258s (501.99ns/i)
+    TinyHooks no callback set     3.754M i/s -      3.791M times in 1.009753s (266.39ns/i)
+                        Plain     3.852M i/s -      3.955M times in 1.026654s (259.57ns/i)
+Calculating -------------------------------------
+ActiveSupport no callback set     2.005M i/s -      5.976M times in 2.980861s (498.79ns/i)
+    TinyHooks no callback set     4.025M i/s -     11.262M times in 2.798054s (248.46ns/i)
+                        Plain     3.765M i/s -     11.557M times in 3.069944s (265.63ns/i)
+
+Comparison:
+    TinyHooks no callback set:   4024854.4 i/s
+                        Plain:   3764695.4 i/s - 1.07x  slower
+ActiveSupport no callback set:   2004848.9 i/s - 2.01x  slower
+```
+
+### Differences in functionality
+
+There are few things TinyHooks doesn't cover. For example, TinyHooks doesn't support `unless` option in `define_hook` method or Symbol as a callback body since they are just syntax sugar.
+
+One of the features TinyHooks doesn't have is `reset_callbacks` which resets all callbacks with given condition. In order to do this, you must call `restore_original` method in iteration.
+
+### Conclusion
+
+In short, in most cases, TinyHooks is simpler, easier and faster solution.
 
 ## Development
 

data/benchmark/compare_to_as_callbacks.rb

@@ -0,0 +1,101 @@
+require 'benchmark_driver'
+
+Benchmark.driver do |x|
+  x.prelude <<~RUBY
+    require 'active_support/callbacks'
+    require 'active_support/core_ext/object/blank'
+    class Record
+      include ActiveSupport::Callbacks
+      define_callbacks :save
+
+      def save
+        run_callbacks :save do
+          puts "- save"
+        end
+      end
+    end
+
+    class PersonRecord < Record
+      set_callback :save, :before, :saving_message
+      def saving_message
+        puts "saving..."
+      end
+
+      set_callback :save, :after do |object|
+        puts "saved"
+      end
+    end
+
+    require 'tiny_hooks'
+
+    class TinyRecord
+      include TinyHooks
+
+      def save
+        puts '- save'
+      end
+    end
+
+    class TinyPersonRecord < TinyRecord
+      def saving_message
+        puts 'saving...'
+      end
+
+      define_hook :before, :save do
+        saving_message
+      end
+
+      define_hook :after, :save do
+        puts 'saved'
+      end
+    end
+
+    person = PersonRecord.new
+    tiny_person = TinyPersonRecord.new
+  RUBY
+
+  x.report 'ActiveSupport', %( person.save )
+  x.report 'TinyHooks', %( tiny_person.save )
+end
+
+Benchmark.driver do |x|
+  x.prelude <<~RUBY
+    require 'active_support/callbacks'
+    require 'active_support/core_ext/object/blank'
+
+    class ASNoCallbackSet
+      include ActiveSupport::Callbacks
+      define_callbacks :save
+
+      def save
+        run_callbacks :save do
+          puts "- save"
+        end
+      end
+    end
+
+    require 'tiny_hooks'
+
+    class TinyNoCallbackSet
+      include TinyHooks
+
+      def save
+        puts '- save'
+      end
+    end
+
+    class Plain
+      def save
+        puts '- save'
+      end
+    end
+
+    as_no_callback_set = ASNoCallbackSet.new
+    tiny_no_callback_set = TinyNoCallbackSet.new
+    plain = Plain.new
+  RUBY
+
+  x.report 'ActiveSupport no callback set', %( as_no_callback_set.save )
+  x.report 'TinyHooks no callback set', %( tiny_no_callback_set.save )
+  x.report 'Plain', %( plain.save )
+end

data/lib/tiny_hooks.rb

@@ -8,92 +8,181 @@ require_relative 'tiny_hooks/version'
 module TinyHooks
   class Error < StandardError; end
 
+  class PrivateError < Error; end
+
+  class TargetError < Error; end
+
+  HALTING = Object.new.freeze
+  private_constant :HALTING
+  UNDEFINED_TARGETS = [].freeze
+  private_constant :UNDEFINED_TARGETS
+
   # @api private
-  def self.extended(mod)
-    mod.class_eval { @@_originals ||= {} }
-    # mod.instance_variable_set(:@_originals, {}) unless mod.instance_variable_defined?(:@_originals)
-    # mod.define_singleton_method(:_originals) do
-    #   mod.instance_variable_get(:@_originals)
-    # end
+  def self.included(base)
+    base.class_eval do
+      @_originals = {}
+      @_targets = UNDEFINED_TARGETS
+      @_public_only = false
+    end
+    base.extend ClassMethods
   end
 
-  # Define hook with kind and target method
-  #
-  # @param [Symbol, String] kind the kind of the hook, possible values are: :before, :after and :around
-  # @param [Symbol, String] target the name of the targeted method
-  def define_hook(kind, target, &block)
-    raise ArgumentError, 'You must provide a block' unless block
-
-    original_method = instance_method(target)
-    @@_originals[target.to_sym] = original_method unless @@_originals[target.to_sym]
-
-    body = case kind.to_sym
-           when :before
-             _before(original_method, &block)
-           when :after
-             _after(original_method, &block)
-           when :around
-             _around(original_method, &block)
-           else
-             raise Error, "#{kind} is not supported."
-           end
-    undef_method(target)
-    define_method(target, &body)
-  end
+  # @api private
+  def self.with_halting(terminator, *args, **kwargs, &block)
+    hook_result = nil
+    abort_result = catch :abort do
+      hook_result = instance_exec(*args, **kwargs, &block)
+      true
+    end
+    return HALTING if abort_result.nil? && terminator == :abort
+    return HALTING if hook_result == false && terminator == :return_false
 
-  module_function :define_hook
+    hook_result
+  end
 
-  # Restore original method
-  #
-  # @param [Symbol, String] target
-  def restore_original(target)
-    original_method = @@_originals[target.to_sym] || instance_method(target)
+  # Class methods
+  module ClassMethods
+    # Define hook with kind and target method
+    #
+    # @param [Symbol, String] kind the kind of the hook, possible values are: :before, :after and :around
+    # @param [Symbol, String] target the name of the targeted method
+    # @param [Symbol] terminator choice for terminating execution, default is throwing abort symbol
+    # @param [Symbol] if condition to determine if it should define callback. Block is evaluated in context of self
+    def define_hook(kind, target, terminator: :abort, if: nil, &block) # rubocop:disable Naming/MethodParameterName
+      raise ArgumentError, 'You must provide a block' unless block
+      raise ArgumentError, 'terminator must be one of the following: :abort or :return_false' unless %i[abort return_false].include? terminator.to_sym
+      raise TinyHooks::TargetError, "Hook for #{target} is not allowed" if @_targets != UNDEFINED_TARGETS && !@_targets.include?(target)
 
-    undef_method(target)
-    define_method(target, original_method)
-  end
+      is_private = private_instance_methods.include?(target.to_sym)
 
-  private
+      begin
+        original_method = @_public_only ? public_instance_method(target) : instance_method(target)
+      rescue NameError => e
+        raise unless e.message.include?('private')
 
-  def _before(original_method, &block)
-    if RUBY_VERSION >= '2.7'
-      proc do |*args, **kwargs, &blk|
-        instance_exec(*args, **kwargs, &block)
-        original_method.bind_call(self, *args, **kwargs, &blk)
-      end
-    else
-      proc do |*args, &blk|
-        instance_exec(*args, &block)
-        original_method.bind(self).call(*args, &blk)
+        raise TinyHooks::PrivateError, "Public only mode is on and hooks for private methods (#{target} for this time) are not available."
       end
+      @_originals[target.to_sym] = original_method unless @_originals[target.to_sym]
+
+      undef_method(target)
+      define_method(target, &method_body(kind, original_method, terminator, binding.local_variable_get(:if), &block))
+      private target if is_private
     end
-  end
 
-  def _after(original_method, &block)
-    if RUBY_VERSION >= '2.7'
-      proc do |*args, **kwargs, &blk|
-        original_method.bind_call(self, *args, **kwargs, &blk)
-        instance_exec(*args, **kwargs, &block)
+    # Restore original method
+    #
+    # @param [Symbol, String] target
+    def restore_original(target)
+      original_method = @_originals[target.to_sym] || instance_method(target)
+
+      undef_method(target)
+      define_method(target, original_method)
+    end
+
+    # Defines target for hooks
+    # @param include_pattern [Regexp]
+    # @param exclude_pattern [Regexp]
+    def target!(include_pattern: nil, exclude_pattern: nil)
+      raise ArgumentError if include_pattern.nil? && exclude_pattern.nil?
+
+      candidates = @_public_only ? instance_methods : instance_methods + private_instance_methods
+      @_targets = if include_pattern && exclude_pattern
+                    targets = candidates.grep(include_pattern)
+                    targets.grep_v(exclude_pattern)
+                  elsif include_pattern
+                    candidates.grep(include_pattern)
+                  else
+                    candidates.grep_v(exclude_pattern)
+                  end
+    end
+
+    # Enable public only mode
+    def public_only!
+      @_public_only = true
+    end
+
+    # Disable public only mode
+    def include_private!
+      @_public_only = false
+    end
+
+    private
+
+    def method_body(kind, original_method, terminator, if_proc, &block)
+      case kind.to_sym
+      when :before then _before(original_method, terminator: terminator, if_proc: if_proc, &block)
+      when :after  then _after(original_method, if_proc: if_proc, &block)
+      when :around then _around(original_method, if_proc: if_proc, &block)
+      else
+        raise Error, "#{kind} is not supported."
       end
-    else
-      proc do |*args, &blk|
-        original_method.bind(self).call(*args, &blk)
-        instance_exec(*args, &block)
+    end
+
+    def _before(original_method, terminator:, if_proc:, &block)
+      if RUBY_VERSION >= '2.7'
+        proc do |*args, **kwargs, &blk|
+          if if_proc.nil? || instance_exec(&if_proc) != false
+            hook_result = nil
+            abort_result = catch :abort do
+              hook_result = instance_exec(*args, **kwargs, &block)
+              true
+            end
+            return if abort_result.nil? && terminator == :abort
+            return if hook_result == false && terminator == :return_false
+          end
+
+          original_method.bind_call(self, *args, **kwargs, &blk)
+        end
+      else
+        proc do |*args, &blk|
+          if if_proc.nil? || instance_exec(&if_proc) != false
+            hook_result = nil
+            abort_result = catch :abort do
+              hook_result = instance_exec(*args, &block)
+              true
+            end
+            return if abort_result.nil? && terminator == :abort
+            return if hook_result == false && terminator == :return_false
+          end
+
+          original_method.bind(self).call(*args, &blk)
+        end
       end
     end
-  end
 
-  def _around(original_method, &block)
-    if RUBY_VERSION >= '2.7'
-      proc do |*args, **kwargs, &blk|
-        wrapper = -> { original_method.bind_call(self, *args, **kwargs, &blk) }
-        instance_exec(wrapper, *args, **kwargs, &block)
+    def _after(original_method, if_proc:, &block)
+      if RUBY_VERSION >= '2.7'
+        proc do |*args, **kwargs, &blk|
+          original_method.bind_call(self, *args, **kwargs, &blk)
+          instance_exec(*args, **kwargs, &block) if if_proc.nil? || instance_exec(&if_proc) != false
+        end
+      else
+        proc do |*args, &blk|
+          original_method.bind(self).call(*args, &blk)
+          instance_exec(*args, &block) if if_proc.nil? || instance_exec(&if_proc) != false
+        end
       end
-    else
-      proc do |*args, &blk|
-        wrapper = -> { original_method.bind(self).call(*args, &blk) }
-        instance_exec(wrapper, *args, &block)
+    end
+
+    def _around(original_method, if_proc:, &block)
+      if RUBY_VERSION >= '2.7'
+        proc do |*args, **kwargs, &blk|
+          wrapper = -> { original_method.bind_call(self, *args, **kwargs, &blk) }
+          instance_exec(wrapper, *args, **kwargs, &block) if if_proc.nil? || instance_exec(&if_proc) != false
+        end
+      else
+        proc do |*args, &blk|
+          wrapper = -> { original_method.bind(self).call(*args, &blk) }
+          instance_exec(wrapper, *args, &block) if if_proc.nil? || instance_exec(&if_proc) != false
+        end
       end
     end
+
+    def inherited(subclass)
+      super
+      subclass.instance_variable_set(:@_originals, instance_variable_get(:@_originals).clone)
+      subclass.instance_variable_set(:@_targets, instance_variable_get(:@_targets).clone)
+      subclass.instance_variable_set(:@_public_only, instance_variable_get(:@_public_only).clone)
+    end
   end
 end

data/lib/tiny_hooks/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TinyHooks
-  VERSION = '0.3.0'
+  VERSION = '1.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tiny_hooks
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 1.0.0
 platform: ruby
 authors:
 - OKURA Masafumi
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-04-25 00:00:00.000000000 Z
+date: 2021-05-09 00:00:00.000000000 Z
 dependencies: []
 description: Simple, tiny and general hooks control.
 email:
@@ -26,6 +26,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- benchmark/compare_to_as_callbacks.rb
 - bin/console
 - bin/setup
 - lib/tiny_hooks.rb