plugman 0.1.1 → 0.2

data/README.md

@@ -1,6 +1,30 @@
 Plugman
 =======
 
+Plugman is a plugin manager that supports event driven communication
+with plugins. It handles the loading, initialization and all
+communications with the plugins.
+
+
+Installation
+------------
+
+The easiest way to get plugman is through rubygems
+
+    gem install plugman
+
+If you want to track the latest changes
+
+    git clone git://github.com/kjellm/plugman.git
+    gem build plugman.gemspec
+    gem install plugman-XXX.gem
+
+
+Usage
+-----
+
+See the API documentation at <http://rubydoc.info/gems/plugman/>.
+
 Alternatives
 ------------
 
@@ -11,3 +35,21 @@ FIX document differences
 - little-plugger
 - pluginfactory
 
+
+Bugs
+----
+
+Report bugs to <http://github.com/kjellm/plugman/issues>
+
+
+Author
+------
+
+Kjell-Magne Øierud &lt;kjellm AT acm DOT org&gt;
+
+
+License
+-------
+
+This computer program is distributed under the GPL. Please see the
+COPYING file part of this distribution.

data/lib/plugman.rb

@@ -5,14 +5,46 @@ require 'plugman/plugin_base'
 require 'logger'
 require 'stringio'
 
+#
+# Plugman is a plugin manager that supports event driven communication
+# with plugins. It handles the loading, initialization and all
+# communications with the plugins.
+#
+# To call a method on the registered plugins, call plugman with a
+# method name matching 
+# 
+#   /^signal_(before|after|at)/
+#
+# plugman will then call similar named (without signal_) methods on all
+# plugins which responds to the method.
+#
+# === Example
+#
+# Put some plugins in lib/your_app/plugin/. For documentation on
+# writing plugins, see link:Plugman/PluginBase.html
+#
+#   require 'plugman'
+#  
+#   class YourApp
+#
+#     def initialize
+#       @pm = Plugman.new('your_app')
+#       @pm.load_plugins
+#     end
+#
+#     def main
+#       @pm.signal_at_starup
+#
+#       # ...
+#    
+#       @pm.signal_before_bar
+#     end
+#
+
 class Plugman
 
   def initialize(finder_or_name)
-    if finder_or_name.is_a?(String)
-      @finder = Finder::Standard.new(finder_or_name)
-    else
-      @finder = finder
-    end
+    self.finder = finder_or_name
     @plugins = []
     @log = StringIO.new("")
     @logger = Logger.new(@log)
@@ -23,6 +55,8 @@ class Plugman
     @log.string
   end
 
+  # Looks for plugins, requires them, checks state, initializes, and
+  # registers the plugins
   def load_plugins
     @finder.plugin_files.each do |f|
       require_plugin(f)
@@ -35,13 +69,11 @@ class Plugman
     @plugins = @plugins.select {|p| p.state_ok? }
   end
 
-  def register_plugin(klass)
-    @plugins.push(klass.new)
-  end
-
+  # Calls the 
   def method_missing(name, *arguments, &block)
-    if name.to_s =~ /^send_(before|after|at|.*_hook$)/
-      method = name.to_s[5..-1]
+    if name.to_s =~ /^signal_(before|after|at)/
+      method = name.to_s[7..-1]
+      @logger.debug("Sending #{method} to plugins")
       @plugins.select {|p| p.respond_to?(method)}.each do |p|
         p.send(method, *arguments)
       end
@@ -50,10 +82,23 @@ class Plugman
     end
   end
 
+  def register_plugin(klass)
+    @plugins.push(klass.new)
+  end
+
   # FIX implement respond_to? to match method_missing?
 
   private
 
+  def finder=(finder_or_name)
+    if finder_or_name.is_a?(String)
+      @finder = Finder::Standard.new(finder_or_name)
+    elsif finder_or_name.respond_to?(:plugin_files)
+      @finder = finder_or_name
+    else
+      raise ArgumentError 'Require a string or an object repsonding to plugin_files()'
+    end
+  end
 
   def require_plugin(f)
     @logger.debug "Requiering #{f}"

data/lib/plugman/plugin_base.rb

@@ -1,5 +1,38 @@
 
 class Plugman
+
+  #
+  # Plugins need to inherit this class for plugman to be able register
+  # them.
+  #
+  # A typical plugin will look like something like this:
+  #
+  #    require 'plugman/plugin_base' 
+  #  
+  #    class YourApp
+  #      module Plugin
+  #        class CoolPlugin < Plugman::PluginBase
+  #
+  #           def at_startup
+  #             puts "Whoa, it worked!"
+  #           end
+  #
+  #           def before_bar
+  #             puts "foo"
+  #           end
+  #
+  #        end
+  #      end
+  #    end
+  #
+  # After a plugin is initialized, plugman will call state_ok?(). Only
+  # plugins who return true in this method will be registered by
+  # plugman.
+  #
+  # For documentation on method names, see the documentation for
+  # link:Plugman.html
+  #
+
   class PluginBase
 
     def self.manager=(obj)
@@ -10,6 +43,8 @@ class Plugman
       @@manager.register_plugin(klass)
     end
 
+    # Just returns true. Define this in your plugin class if you need
+    # to verify that your plugin state is ok after initialization.
     def state_ok?; true; end
 
   end

data/test/{foo.rb → test_plugman.rb}

@@ -2,14 +2,16 @@ require 'plugman'
 require 'plugman/finder'
 require 'test/unit' 
 
-class Foo < Test::Unit::TestCase
+class TestPlugman < Test::Unit::TestCase
 
   def test_it
     pm = Plugman.new(Plugman::Finder::Simple.new(File.dirname(__FILE__) + '/plugin'))
     pm.load_plugins
     
     str = ""
-    pm.send_before_big_bang(str)
+    pm.signal_before_big_bang(str)
+    print pm.log
+
     assert(str =~ /WHOOOP/)
     assert(str =~ /WHIIIIIIIIIIZZZZZZZZ/)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: plugman
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: '0.2'
   prerelease: 
 platform: ruby
 authors:
@@ -9,10 +9,12 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-06-01 00:00:00.000000000 +02:00
+date: 2011-06-14 00:00:00.000000000 +02:00
 default_executable: 
 dependencies: []
-description: FIX
+description: Plugman is a plugin manager that supports event driven communication
+  with plugins. It handles the loading, initialization and all communications with
+  the plugins.
 email: kjellm@acm.org
 executables: []
 extensions: []
@@ -23,7 +25,7 @@ files:
 - lib/plugman/finder/standard.rb
 - lib/plugman/finder/simple.rb
 - lib/plugman.rb
-- test/foo.rb
+- test/test_plugman.rb
 - test/plugin/bar.rb
 - test/plugin/baz.rb
 - Rakefile