module GemPlugin

Implements a dynamic plugin loading, configuration, and discovery system based on RubyGems and a simple additional name space that looks like a URI.

A plugin is created and put into a category with the following code:

class MyThing < GemPlugin::Plugin "/things"
  ...
end

What this does is sets up your MyThing in the plugin registry via GemPlugin::Manager. You can then later get this plugin with GemPlugin::Manager#create(“/things/mything”) and can also pass in options as a second parameter.

This isn't such a big deal, but the power is really from the GemPlugin::Manager#load method. This method will go through the installed gems and require_gem any that depend on the gem_plugin RubyGem. You can arbitrarily include or exclude gems based on what they also depend on, thus letting you load these gems when appropriate.

Since this system was written originally for the Mongrel project that'll be the best example of using it.

Imagine you have a neat plugin for Mongrel called snazzy_command that gives the mongrel_rails a new command snazzy (like: mongrel_rails snazzy). You'd like people to be able to grab this plugin if they want and use it, because it's snazzy.

First thing you do is create a gem of your project and make sure that it depends on “mongrel” AND “gem_plugin”. This signals to the GemPlugin system that this is a plugin for mongrel.

Next you put this code into a file like lib/init.rb (can be anything really):

class Snazzy < GemPlugin::Plugin "/commands"
  ...
end

Then when you create your gem you have the following bits in your Rakefile:

spec.add_dependency('mongrel', '>= 0.3.9')
spec.add_dependency('gem_plugin', '>= 0.1')
spec.autorequire = 'init.rb'

Finally, you just have to now publish this gem for people to install and Mongrel will “magically” be able to install it.

The “magic” part though is pretty simple and done via the GemPlugin::Manager#load method. Read that to see how it is really done.