wizardwerdna-pluggable 0.1.1 → 0.2.0

data/README.rdoc

@@ -1,6 +1,11 @@
 = pluggable
 
-Pluggable is a mixin for classes requiring plugins.  A pluggable class, +Klass+, has a public function, +plugins+, returning an array-like object that holds all subclasses of <tt>Klass::Plugin</tt>.
+Pluggable is a mixin for classes requiring plugins.  Including *Pluggable* adds several methods:
+
+[*install_plugins*] Should generally be called when initializing an instance of the Pluggable class.
+[*plugins*] After initialization, returns a list of plugin instances
+
+For example:
 
 	require 'rubygems'
 	require 'pluggable'
@@ -20,8 +25,7 @@ Pluggable is a mixin for classes requiring plugins.  A pluggable class, +Klass+,
 	
 	Test.new.process # => ["foo", "bar"]	
 
-It may be convenient to have public methods of plugins delegated to from the +plugins+ object, which may in turn be delgated to by the +Pluggable+ class in various ways.  For example:
-
+It may be convenient to have public methods of plugins delegated to from the +plugins+ object, which may in turn be delgated to by the +Pluggable+ class in various ways.  This is accomplished with the class method *delegate_plugin_public_methods_except*, which should be called after loading all of the plugins. For example:
 
 	require 'rubygems'
 	require 'pluggable'
@@ -42,11 +46,45 @@ It may be convenient to have public methods of plugins delegated to from the +pl
 	end
 
 	Test.delegate_plugin_public_methods_except :process
-
 	
 	Test.new.process # => ["foo", "bar"]
-	Test.new.plugins.foo = "foo"
-	Test.new.plugins.bar = "bar"
+	Test.new.plugins.foo # => "foo"
+	Test.new.plugins.bar # => "bar"
+	
+Finally, it may be useful to establish an API for plugins in the form of a traditional Ruby module.  The module may be included into the plugins using the class method *plugin_install_methods, which may be called in the Pluggable class definition.  For example:
+
+	require 'rubygems'
+	require 'pluggable'
+	module PluginAPI
+	  def first; "first"; end
+	  def second; private_second; end
+	  module ClassMethods
+	    def class_first; "class_first"; end
+	  end
+	  private
+	  def private_second; "second"; end
+	  def self.included(klass)
+	    klass.extend ClassMethods
+	  end
+	end
+
+	class Test
+		include Pluggable
+		def initialize; install_plugins; end
+		def process; plugins.map {|plugin| plugin.process}; end
+		private
+		def method_missing symbol, *args
+		  plugins.send(symbol, *args)
+		end
+	end
+	
+	require 'plugin_definitions'
+
+	Test.new.plugins.first.first # => "first"
+	Test.new.plugins.first.second # => "second"
+	Test.new.plugins.first.class.class_first # => "class_first"
+	
+And of course, the plugins may override the API definitions.
 
 == Note on Patches/Pull Requests
  

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/lib/pluggable.rb

@@ -65,5 +65,8 @@ module Pluggable
     def delegate_plugin_public_methods_except *excluded_methods
       PluginFactory.instance.delegate_plugin_public_methods_to_plugins_class_except *excluded_methods
     end
+    def plugin_include_module mod
+      Plugin.class_eval "include #{mod.to_s}"
+    end
   end
 end

data/pluggable.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{pluggable}
-  s.version = "0.1.1"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Andrew C. Greenberg"]

data/spec/pluggable_spec.rb

@@ -1,8 +1,22 @@
 require 'forwardable'
 require File.dirname(__FILE__) + '/spec_helper.rb'
 
+module PluginAPI
+  def first; "first"; end
+  def second; private_second; end
+  module ClassMethods
+    def class_first; "class_first"; end
+  end
+  private
+  def private_second; "second"; end
+  def self.included(klass)
+    klass.extend ClassMethods
+  end
+end
+
 class Test
   include Pluggable
+  plugin_include_module PluginAPI
   def process
     plugins.map{|each| each.process}
   end
@@ -49,7 +63,15 @@ describe Pluggable, "when included in a class" do
     Test.plugin_factory.should have(3).items
     Test.plugin_factory.should include(Plugin1, Plugin2, Plugin3)
   end
+    
+  it "should install a class method #delegate_plugin_public_methods_except" do
+    Test.should respond_to(:delegate_plugin_public_methods_except)
+  end
   
+  it "should install a class method #plugin_include_module" do
+    Test.should respond_to(:plugin_include_module)
+  end
+
   it "should add a method #plugins that should be nil upon creation" do
     @test_instance.should respond_to(:plugins)
     @test_instance.plugins.should be_nil
@@ -58,10 +80,6 @@ describe Pluggable, "when included in a class" do
   it "should add a method #install_plugins" do
     Test.new.should respond_to(:install_plugins)
   end
-  
-  it "should install a class method #delegate_plugin_public_methods_except" do
-    Test.should respond_to(:delegate_plugin_public_methods_except)
-  end
 end
 
 describe Pluggable, "after installing plugins" do
@@ -113,6 +131,16 @@ describe Pluggable, "after Test has delegated all but excepted plugin public met
   end
 end
 
+describe Test::Plugin, "after Test has included a module" do
+  it "should have the instance methods of the module" do
+    Test::Plugin.instance_methods.should include(*PluginAPI.instance_methods)
+  end
+  
+  it "should have the class methods of the module" do
+    Test::Plugin.methods.should include(*PluginAPI::ClassMethods.instance_methods)
+  end
+end
+
 describe Test::PluginFactory, "instances" do
   before(:each) do
     @instance = Test::PluginFactory.instance
@@ -132,7 +160,6 @@ describe Test::PluginFactory, "instances" do
 end
 
 describe Test, "when using message_missing to simulate delegation from the parent" do
-  
   before(:each) do
     @test_instance = Test.new
     @test_instance.install_plugins
@@ -147,4 +174,10 @@ describe Test, "when using message_missing to simulate delegation from the paren
     @test_instance.bar.should == "bar"
     @test_instance.baz.should == "baz"
   end
+  
+  it "should work with included module procedures" do
+    @test_instance.plugins.first.first.should == "first"
+    @test_instance.plugins.first.second.should == "second"
+    @test_instance.plugins.first.class.class_first.should == "class_first"
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: wizardwerdna-pluggable
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors: 
 - Andrew C. Greenberg