puma--puma/projects/gem_plugin

= GemPlugin:  Gem Based Plugin System

GemPlugin is a system that lets your users install gems and lets you load
them as additional features to use in your software.  It originated from the
Mongrel (http://mongrel.rubyforge.org) project but proved useful enough to
break out into a separate project.

GemPlugin works by listing the gems installed, and doing a require_gem on 
any that have the right dependencies.  For example, if a gem depends on
"gem_plugin" and "mongrel" then it'll load as a Mongrel plugin.  This
makes it so that users of the plugins only need to gem install (and maybe
config a bit), and plugin authors only need to make gems.


== Implementers

To use GemPlugin in your system you only have to require 'gem_plugin' and 
then use the GemPlugin::Manager.create, GemPlugin::Manager.load, and 
GemPlugin::Manager.available methods to work with them.

* GemPlugin::Manager.load -- Takes a "depend include/exclude map" and loads plugins based on it.
* GemPlugin::Manager.create -- Takes a URI style name and some options then creates one for you.
* GemPlugin::Manager.available -- Lets you inspect and mess with the internal plugin registry.

=== Loading Plugins

As an example from Mongrel it's necessary to load plugins that depend on rails after 
the Rails system is configured, but load other plugins right when Mongrel is ready.
To do this we very first do:

 GemPlugin::Manager.instance.load "mongrel" => GemPlugin::INCLUDE, "rails" => GemPlugin::EXCLUDE

Later, when it's ready to load Rails plugins as well we do this:

 GemPlugin::Manager.instance.load "mongrel" => GemPlugin::INCLUDE

This simply loads any plugins that remain and are ready for use in Rails.

=== Creating Plugins

Creating a plugin is cake:

 plug = GemPlugin::Manager.instance.create("/commands/snazzy", "something" => "yeah")

In this case we're making the snazzy command and passing a couple fake options.

=== Finding Available Plugins

Finding plugins is also very easy, you just call GemPlugin::Manager.instance.available
and you get a Hash that maps categories to name => class.  For example, if I had
the "/commands/snazzy" plugin registered above, then I'd get the following:

 puts GemPlugin::Manager.instance.available["/commands"].inspect
 -> { "/snazzy" => Snazzy}


=== Plugins Inside Modules

Plugins that are placed in modules are also lowercased when registered but
still retain their module.  So, if Snazzy was actually MyModule::Snazzy, then
it'd be registered as "/commands/mymodule::snazzy".


== Plugin Authors

People who wish to write gem plugins have a faily easy time of it, but need
to know the particular rules for the target system.  To keep this example
concrete we'll assume you want to write a Mongrel command plugin.

First thing is create your project like normal and setup Rake to make
your gem.  Your plugin then needs to be created like so:

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

And place this code in a file you will have RubyGems autorequire (I use lib/init.rb).

Next you need to add the following to whatever Rakefile code you use to create
your gem:

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

This does three things:

* Tells GemPlugins::Manager.load that this is a GemPlugin.
* Tells Mongrel that this is a Mongrel specific GemPlugin.
* Tells RubyGems to run init.rb when the gem is required, just hooking up your plugin.

Now, all the users of your plugin have to do is gem install it and then
they get the plugin automagically.

People writing GemPlugins for other systems would have to check the 
documentation from that project to get an idea of what extra 
requirements might be needed.  For example, you'd probably have to
depend on another project other that *mongrel* and most likely have
a few more things to configure in your init.rb.

== Plugin Users

Plugin users have it the easiest of all.  They simply do:

 gem install mongrel_command_snazzy

And that's it.  When they run mongrel_rails (given the above example)
this snazzy command get loaded automatically without any intervention.

The only thing missing in this release is a way for end users to configure
such a plugin.  I really think this is the job of the implementers to define.

== Contact

E-mail zedshaw at zedshaw.com and I'll help.  Comments about the API are welcome.