much-plugin 0.1.0 → 0.2.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fdbddb73262158cb2261ed12d723e7fe54267fa06918211664cfb61f39a838d0
+  data.tar.gz: '085b09a6f64eced79f590df6bfacc5baa3595b3c2429f4ff453b824c33e366ce'
+SHA512:
+  metadata.gz: f213b81efdfabae338b351d95cbf9a4ee3bbd16d90343ba9bff6fc300f382b870d441ef2a1bd253dfcad8716872567bd0a45379dbd9c1e68e0badf5086aa0f6f
+  data.tar.gz: a882e8279f35d99aa3f8cda31bca0d7452ba27e620a4f705c715859904c45f0e62afcb5d018d434f06345e1fbbd24561737b764d571efb2beb2a9844a28ebec2

data/Gemfile

@@ -1,6 +1,12 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
+ruby "~> 2.5"
+
 gemspec
 
-gem 'rake', "~> 10.4.0"
-gem 'pry',  "~> 0.9.0"
+gem "pry"
+
+# to release, uncomment this and run `bundle exec ggem r -f`
+gem "ggem"

data/README.md

@@ -5,20 +5,17 @@ An API to ensure mixin included logic (the "plugin") only runs once.
 ## Usage
 
 ```ruby
-requre 'much-plugin'
+requre "much-plugin"
 
 module MyPluginMixin
   include MuchPlugin
 
   plugin_included do
-
-    # ... do some stuff ...
+    # do some stuff ...
     # - will be class eval'd in the scope of the receiver of `MyPluginMixin`
     # - will only be executed once per receiver, no matter how many times
     #   `MyPluginMixin` is included in that receiver
-
   end
-
 end
 ```
 
@@ -26,11 +23,96 @@ Mix `MuchPlugin` in on other mixins that act as "plugins" to other components.
 
 This allows you to define multiple hooks separately and ensures each hook will only be executed once - even if your plugin is mixed in multiple times on the same receiver.
 
+### `plugin_class_methods` / `plugin_instance_methods`
+
+MuchPlugin provides convenience methods for defining instance/class methods on plugin receivers:
+
+```ruby
+requre "much-plugin"
+
+module MyPluginMixin
+  include MuchPlugin
+
+  plugin_class_methods do
+    # define some methods ...
+    # - these methods will become class methods on the receiver
+  end
+
+  plugin_instance_methods do
+    # define some methods ...
+    # - these methods will become instance methods on the receiver
+  end
+end
+```
+
+### `after_plugin_included`
+
+These hooks work just like the `plugin_included` hooks, except they are evaluated _after_ any plugin class/instance methods have been evaluated. E.g. use this to call a class method that the plugin defines.
+
+```ruby
+requre "much-plugin"
+
+module MyPluginMixin
+  include MuchPlugin
+
+  after_plugin_included do
+    configure_the_plugin
+  end
+
+  plugin_class_methods do
+    def configure_the_plugin
+      # ...
+    end
+  end
+end
+```
+
+## Example
+
+```ruby
+requre "much-plugin"
+
+module AnotherMixin
+  def another
+    "another"
+  end
+end
+
+module MyPlugin
+  include MuchPlugin
+
+  plugin_included do
+    include AnotherMixin
+  end
+
+  plugin_class_methods do
+    def a_class_method
+      "a-class-method"
+    end
+  end
+
+  plugin_instance_methods do
+    def an_instance_method
+      "an-instance-method"
+    end
+  end
+end
+
+class MyClass
+  include MyPlugin
+end
+
+my_class = MyClass.new
+my_class.another            # => "another"
+my_class.an_instance_method # => "an-instance-method"
+MyClass.a_class_method      # => "a-class-method"
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'much-plugin'
+    gem "much-plugin"
 
 And then execute:
 

data/bench/script.rb

@@ -0,0 +1,27 @@
+require "much-plugin"
+require "benchmark"
+
+module Methods; end
+
+module MyMixin
+  def self.included(receiver)
+    receiver.class_eval{ include Methods }
+  end
+end
+
+module MyPlugin
+  include MuchPlugin
+
+  plugin_included do
+    include Methods
+  end
+end
+
+Benchmark.bmbm do |x|
+  x.report("MyMixin") do
+    10_000.times{ Class.new{ include MyMixin } }
+  end
+  x.report("MyPlugin") do
+    10_000.times{ Class.new{ include MyPlugin } }
+  end
+end

data/lib/much-plugin.rb

@@ -1,36 +1,92 @@
+# frozen_string_literal: true
+
 require "much-plugin/version"
 
 module MuchPlugin
-
   def self.included(receiver)
-    receiver.class_eval do
-      extend ClassMethods
+    receiver.class_eval{ extend ClassMethods }
+  end
+
+  module ClassMethods
+    # install an included block that first checks if this plugin's receiver mixin
+    # has already been included.  If it has not been, include the receiver mixin
+    # and run all of the `plugin_included` blocks
+    def included(plugin_receiver)
+      return if plugin_receiver.include?(self.much_plugin_included_detector)
+      plugin_receiver.send(:include, self.much_plugin_included_detector)
 
-      # install an included hook that first checks if this plugin has
-      # already been installed on the reciever.  If it has not been,
-      # class eval each callback on the receiver.
+      self.much_plugin_included_blocks.each do |block|
+        plugin_receiver.class_eval(&block)
+      end
 
-      def self.included(plugin_receiver)
-        return if self.much_plugin_receivers.include?(plugin_receiver)
+      self.much_plugin_class_method_blocks.each do |block|
+        self.much_plugin_class_methods_module.class_eval(&block)
+      end
+      plugin_receiver.send(:extend, self.much_plugin_class_methods_module)
 
-        self.much_plugin_receivers.push(plugin_receiver)
-        self.much_plugin_included_hooks.each do |hook|
-          plugin_receiver.class_eval(&hook)
-        end
+      self.much_plugin_instance_method_blocks.each do |block|
+        self.much_plugin_instance_methods_module.class_eval(&block)
       end
+      plugin_receiver.send(:include, self.much_plugin_instance_methods_module)
 
+      self.much_plugin_after_included_blocks.each do |block|
+        plugin_receiver.class_eval(&block)
+      end
     end
-  end
 
-  module ClassMethods
+    # the included detector is an empty module that is only used to detect if
+    # the plugin has been included or not, it doesn't add any behavior or
+    # methods to the object receiving the plugin; we use `const_set` to name the
+    # module so if its seen in the ancestors it doesn't look like some random
+    # module and it can be tracked back to much-plugin
+    def much_plugin_included_detector
+      @much_plugin_included_detector ||= Module.new.tap do |m|
+        self.const_set("MuchPluginIncludedDetector", m)
+      end
+    end
 
-    def much_plugin_receivers;      @much_plugin_receivers      ||= []; end
-    def much_plugin_included_hooks; @much_plugin_included_hooks ||= []; end
+    def much_plugin_class_methods_module
+      @much_plugin_class_methods_module ||= Module.new.tap do |m|
+        self.const_set("MuchPluginClassMethods", m)
+      end
+    end
 
-    def plugin_included(&hook)
-      self.much_plugin_included_hooks << hook
+    def much_plugin_instance_methods_module
+      @much_plugin_instance_methods_module ||= Module.new.tap do |m|
+        self.const_set("MuchPluginInstanceMethods", m)
+      end
     end
 
-  end
+    def much_plugin_included_blocks
+      @much_plugin_included_blocks ||= []
+    end
+
+    def much_plugin_after_included_blocks
+      @much_plugin_after_included_blocks ||= []
+    end
+
+    def much_plugin_class_method_blocks
+      @much_plugin_class_method_blocks ||= []
+    end
+
+    def much_plugin_instance_method_blocks
+      @much_plugin_instance_method_blocks ||= []
+    end
 
+    def plugin_included(&block)
+      self.much_plugin_included_blocks << block
+    end
+
+    def after_plugin_included(&block)
+      self.much_plugin_after_included_blocks << block
+    end
+
+    def plugin_class_methods(&block)
+      self.much_plugin_class_method_blocks << block
+    end
+
+    def plugin_instance_methods(&block)
+      self.much_plugin_instance_method_blocks << block
+    end
+  end
 end

data/lib/much-plugin/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module MuchPlugin
-  VERSION = "0.1.0"
+  VERSION = "0.2.3"
 end

data/much-plugin.gemspec

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 # -*- encoding: utf-8 -*-
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "much-plugin/version"
 
@@ -8,16 +10,17 @@ Gem::Specification.new do |gem|
   gem.version     = MuchPlugin::VERSION
   gem.authors     = ["Kelly Redding", "Collin Redding"]
   gem.email       = ["kelly@kellyredding.com", "collin.redding@me.com"]
-  gem.description = %q{An API to ensure mixin included logic (the "plugin") only runs once.}
   gem.summary     = %q{An API to ensure mixin included logic (the "plugin") only runs once.}
+  gem.description = %q{An API to ensure mixin included logic (the "plugin") only runs once.}
   gem.homepage    = "http://github.com/redding/much-plugin"
-  gem.license     = 'MIT'
+  gem.license     = "MIT"
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
-  gem.add_development_dependency("assert", ["~> 2.15"])
+  gem.required_ruby_version = "~> 2.5"
 
+  gem.add_development_dependency("assert", ["~> 2.19.0"])
 end

data/test/helper.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # this file is automatically required when you run `assert`
 # put any test helpers here
 
@@ -5,6 +7,6 @@
 $LOAD_PATH.unshift(File.expand_path("../..", __FILE__))
 
 # require pry for debugging (`binding.pry`)
-require 'pry'
+require "pry"
 
-require 'test/support/factory'
+require "test/support/factory"

data/test/support/factory.rb

@@ -1,6 +1,7 @@
-require 'assert/factory'
+# frozen_string_literal: true
+
+require "assert/factory"
 
 module Factory
   extend Assert::Factory
-
 end

data/test/system/much-plugin_tests.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "assert"
+require "much-plugin"
+
+module MuchPlugin
+  class SystemTests < Assert::Context
+    desc "MuchPlugin"
+    setup do
+      @my_class = MyClass.new
+    end
+    subject{ @my_class }
+
+    should "class eval the plugin included block on MyClass" do
+      assert_equal "another", subject.another
+    end
+
+    should "add the plugin class methods to MyClass" do
+      assert_equal "a-class-method", MyClass.a_class_method
+    end
+
+    should "add the plugin instance methods to MyClass" do
+      assert_equal "an-instance-method", subject.an_instance_method
+    end
+
+    module AnotherMixin
+      def another
+        "another"
+      end
+    end
+
+    module MyPlugin
+      include MuchPlugin
+
+      plugin_included do
+        include AnotherMixin
+      end
+
+      plugin_class_methods do
+        def a_class_method
+          "a-class-method"
+        end
+      end
+
+      plugin_instance_methods do
+        def an_instance_method
+          "an-instance-method"
+        end
+      end
+    end
+
+    class MyClass
+      include MyPlugin
+    end
+  end
+end

data/test/unit/much-plugin_tests.rb

@@ -1,73 +1,84 @@
-require 'assert'
-require 'much-plugin'
+# frozen_string_literal: true
 
-module MuchPlugin
+require "assert"
+require "much-plugin"
 
+module MuchPlugin
   class UnitTests < Assert::Context
     desc "MuchPlugin"
     setup do
-      @hook1 = proc{ 1 }
-      @hook2 = proc{ 2 }
+      @block1 = proc{ 1 }
+      @block2 = proc{ 2 }
 
       @plugin = Module.new{ include MuchPlugin }
     end
     subject{ @plugin }
 
-    should have_imeths :much_plugin_included_hooks, :much_plugin_receivers
-    should have_imeths :plugin_included
+    should have_imeths :much_plugin_included_detector, :much_plugin_included_blocks
+    should have_imeths :plugin_included, :after_plugin_included
 
-    should "have no plugin included hooks by default" do
-      assert_empty subject.much_plugin_included_hooks
+    should "know its included detector" do
+      mixin = subject.much_plugin_included_detector
+      assert_instance_of Module, mixin
+      assert_same mixin, subject.much_plugin_included_detector
+      exp = subject::MuchPluginIncludedDetector
+      assert_same exp, subject.much_plugin_included_detector
     end
 
-    should "have no plugin receivers by default" do
-      assert_empty subject.much_plugin_receivers
+    should "have no plugin included blocks by default" do
+      assert_empty subject.much_plugin_included_blocks
+      assert_empty subject.much_plugin_after_included_blocks
     end
 
-    should "append hooks" do
-      subject.plugin_included(&@hook1)
-      subject.plugin_included(&@hook2)
+    should "append blocks" do
+      subject.plugin_included(&@block1)
+      subject.plugin_included(&@block2)
 
-      assert_equal @hook1, subject.much_plugin_included_hooks.first
-      assert_equal @hook2, subject.much_plugin_included_hooks.last
+      assert_equal @block1, subject.much_plugin_included_blocks.first
+      assert_equal @block2, subject.much_plugin_included_blocks.last
     end
-
   end
 
   class MixedInTests < UnitTests
     desc "when mixed in"
     setup do
       @receiver = Class.new do
-        def self.inc_hook1;   @hook1_count ||= 0; @hook1_count += 1; end
-        def self.hook1_count; @hook1_count ||= 0; end
-        def self.inc_hook2;   @hook2_count ||= 0; @hook2_count += 1; end
-        def self.hook2_count; @hook2_count ||= 0; end
+        def self.inc_block1;   @block1_count ||= 0; @block1_count += 1; end
+        def self.block1_count; @block1_count ||= 0; end
+        def self.inc_block2;   @block2_count ||= 0; @block2_count += 1; end
+        def self.block2_count; @block2_count ||= 0; end
+
+        def self.do_something_count; @do_something_count ||= 0; end
       end
     end
 
-    should "call the plugin included hooks" do
-      assert_equal 0, @receiver.hook1_count
-      assert_equal 0, @receiver.hook2_count
+    should "call the plugin included blocks" do
+      assert_equal 0, @receiver.block1_count
+      assert_equal 0, @receiver.block2_count
+      assert_equal 0, @receiver.do_something_count
 
       @receiver.send(:include, TestPlugin)
 
-      assert_equal 1, @receiver.hook1_count
-      assert_equal 1, @receiver.hook2_count
+      assert_equal 1, @receiver.block1_count
+      assert_equal 1, @receiver.block2_count
+      assert_equal 1, @receiver.do_something_count
     end
 
-    should "call hooks only once no matter even if previously mixed in" do
+    should "call blocks only once no matter even if previously mixed in" do
       @receiver.send(:include, TestPlugin)
 
-      assert_equal 1, @receiver.hook1_count
-      assert_equal 1, @receiver.hook2_count
+      assert_equal 1, @receiver.block1_count
+      assert_equal 1, @receiver.block2_count
+      assert_equal 1, @receiver.do_something_count
 
       @receiver.send(:include, TestPlugin)
 
-      assert_equal 1, @receiver.hook1_count
-      assert_equal 1, @receiver.hook2_count
+      assert_equal 1, @receiver.block1_count
+      assert_equal 1, @receiver.block2_count
+      assert_equal 1, @receiver.do_something_count
     end
 
-    should "call hooks only once even if mixed in by a 3rd party" do
+    should "call blocks only once even if mixed in by a 3rd party" do
       third_party = Module.new do
         def self.included(receiver)
           receiver.send(:include, TestPlugin)
@@ -75,27 +86,39 @@ module MuchPlugin
       end
       @receiver.send(:include, third_party)
 
-      assert_equal 1, @receiver.hook1_count
-      assert_equal 1, @receiver.hook2_count
+      assert_equal 1, @receiver.block1_count
+      assert_equal 1, @receiver.block2_count
+      assert_equal 1, @receiver.do_something_count
 
       @receiver.send(:include, TestPlugin)
 
-      assert_equal 1, @receiver.hook1_count
-      assert_equal 1, @receiver.hook2_count
+      assert_equal 1, @receiver.block1_count
+      assert_equal 1, @receiver.block2_count
+      assert_equal 1, @receiver.do_something_count
 
       @receiver.send(:include, third_party)
 
-      assert_equal 1, @receiver.hook1_count
-      assert_equal 1, @receiver.hook2_count
-    end
-
-    TestPlugin = Module.new do
-      include MuchPlugin
-
-      plugin_included{ inc_hook1 }
-      plugin_included{ inc_hook2 }
+      assert_equal 1, @receiver.block1_count
+      assert_equal 1, @receiver.block2_count
+      assert_equal 1, @receiver.do_something_count
     end
 
+    TestPlugin =
+      Module.new do
+        include MuchPlugin
+
+        plugin_included{ inc_block1 }
+        after_plugin_included{
+          inc_block2
+          do_something
+        }
+
+        plugin_class_methods do
+          def do_something
+            @do_something_count ||= 0
+            @do_something_count += 1
+          end
+        end
+      end
   end
-
 end

metadata

@@ -1,96 +1,77 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: much-plugin
-version: !ruby/object:Gem::Version 
-  hash: 27
-  prerelease: 
-  segments: 
-  - 0
-  - 1
-  - 0
-  version: 0.1.0
+version: !ruby/object:Gem::Version
+  version: 0.2.3
 platform: ruby
-authors: 
+authors:
 - Kelly Redding
 - Collin Redding
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2015-11-24 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 29
-        segments: 
-        - 2
-        - 15
-        version: "2.15"
-  type: :development
+date: 2021-01-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: assert
-  version_requirements: *id001
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.19.0
+  type: :development
   prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.19.0
 description: An API to ensure mixin included logic (the "plugin") only runs once.
-email: 
+email:
 - kelly@kellyredding.com
 - collin.redding@me.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
-- .gitignore
+files:
+- ".gitignore"
 - Gemfile
 - LICENSE
 - README.md
-- Rakefile
+- bench/script.rb
 - lib/much-plugin.rb
 - lib/much-plugin/version.rb
 - log/.gitkeep
 - much-plugin.gemspec
 - test/helper.rb
 - test/support/factory.rb
+- test/system/much-plugin_tests.rb
 - test/unit/much-plugin_tests.rb
 - tmp/.gitkeep
 homepage: http://github.com/redding/much-plugin
-licenses: 
+licenses:
 - MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  none: false
-  requirements: 
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
   - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
-rubyforge_project: 
-rubygems_version: 1.8.29
+rubygems_version: 3.1.2
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: An API to ensure mixin included logic (the "plugin") only runs once.
-test_files: 
+test_files:
 - test/helper.rb
 - test/support/factory.rb
+- test/system/much-plugin_tests.rb
 - test/unit/much-plugin_tests.rb

data/Rakefile

@@ -1 +0,0 @@
-require "bundler/gem_tasks"