gem_plugin 0.1

data/LICENSE

@@ -0,0 +1,58 @@
+Ruby is copyrighted free software by Zed A. Shaw <zedshaw at zedshaw dot com>
+You can redistribute it and/or modify it under either the terms of the GPL
+or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict
+	  with standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+       a) distribute the executables and library files of the software,
+	  together with instructions (in the manual page or equivalent)
+	  on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under this terms.
+
+     They are gc.c(partly), utils.c(partly), regex.[ch], st.[ch] and some
+     files under the ./missing directory.  See each file for the copying
+     condition.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.
+

data/README

@@ -0,0 +1,115 @@
+= 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.

data/Rakefile

@@ -0,0 +1,35 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/clean'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'tools/rakehelp'
+require 'fileutils'
+include FileUtils
+
+setup_tests
+setup_clean ["pkg", "lib/*.bundle", "*.gem", ".config"]
+
+setup_rdoc ['README', 'LICENSE', 'COPYING', 'lib/**/*.rb', 'doc/**/*.rdoc']
+
+desc "Does a full compile, test run"
+task :default => [:test, :package]
+
+version="0.1"
+summary = "A plugin system based only on rubygems"
+test_file = "test/test_plugins.rb"
+author="Zed A. Shaw"
+name="gem_plugin"
+scripts=[]
+
+setup_gem(name, version,  author, summary, scripts, test_file) do |spec|
+  spec.autorequire = "gem_plugin"
+end
+
+task :gem_test => [:package] do
+  sh %{sudo gem install pkg/gem_plugin-#{version}}
+end
+
+task :site => [:rerdoc] do
+  sh %{ scp -r doc/rdoc/* #{ENV['SSH_USER']}@rubyforge.org:/var/www/gforge-projects/mongrel/gem_plugin_rdoc/ }
+end

data/doc/rdoc/classes/GemPlugin.html

@@ -0,0 +1,247 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html 
+     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>Module: GemPlugin</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+  <meta http-equiv="Content-Script-Type" content="text/javascript" />
+  <link rel="stylesheet" href=".././rdoc-style.css" type="text/css" media="screen" />
+  <script type="text/javascript">
+  // <![CDATA[
+
+  function popupCode( url ) {
+    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
+  }
+
+  function toggleCode( id ) {
+    if ( document.getElementById )
+      elem = document.getElementById( id );
+    else if ( document.all )
+      elem = eval( "document.all." + id );
+    else
+      return false;
+
+    elemStyle = elem.style;
+    
+    if ( elemStyle.display != "block" ) {
+      elemStyle.display = "block"
+    } else {
+      elemStyle.display = "none"
+    }
+
+    return true;
+  }
+  
+  // Make codeblocks hidden by default
+  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
+  
+  // ]]>
+  </script>
+
+</head>
+<body>
+
+
+
+    <div id="classHeader">
+        <table class="header-table">
+        <tr class="top-aligned-row">
+          <td><strong>Module</strong></td>
+          <td class="class-name-in-header">GemPlugin</td>
+        </tr>
+        <tr class="top-aligned-row">
+            <td><strong>In:</strong></td>
+            <td>
+                <a href="../files/lib/gem_plugin_rb.html">
+                lib/gem_plugin.rb
+                </a>
+        <br />
+            </td>
+        </tr>
+
+        </table>
+    </div>
+  <!-- banner header -->
+
+  <div id="bodyContent">
+
+
+
+  <div id="contextContent">
+
+    <div id="description">
+      <p>
+Implements a dynamic plugin loading, configuration, and discovery system
+based on RubyGems and a simple additional name space that looks like a URI.
+</p>
+<p>
+A plugin is created and put into a category with the following code:
+</p>
+<pre>
+ class MyThing &lt; GemPlugin::Plugin &quot;/things&quot;
+   ...
+ end
+</pre>
+<p>
+What this does is sets up your MyThing in the plugin registry via <a
+href="GemPlugin/Manager.html">GemPlugin::Manager</a>. You can then later
+get this plugin with <a
+href="GemPlugin/Manager.html#M000008">GemPlugin::Manager.create</a>(&quot;/things/mything&quot;)
+and can also pass in options as a second parameter.
+</p>
+<p>
+This isn&#8217;t such a big deal, but the power is really from the <a
+href="GemPlugin/Manager.html#M000006">GemPlugin::Manager.load</a> 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.
+</p>
+<p>
+Since this system was written originally for the Mongrel project
+that&#8217;ll be the best examle of using it.
+</p>
+<p>
+Imagine you have a neat plugin for Mongrel called snazzy_command that give
+the mongrel_rails a new command snazzy (like: mongrel_rails snazzy).
+You&#8216;d like people to be able to grab this plugin if they want and use
+it, because it&#8217;s snazzy.
+</p>
+<p>
+First thing you do is create a gem of your project and make sure that it
+depends on &quot;mongrel&quot; AND &quot;gem_plugin&quot;. This signals to
+the <a href="GemPlugin.html">GemPlugin</a> system that this is a plugin for
+mongrel.
+</p>
+<p>
+Next you put this code into a file like lib/init.rb (can be anything
+really):
+</p>
+<pre>
+ class Snazzy &lt; GemPlugin::Plugin &quot;/commands&quot;
+   ...
+ end
+</pre>
+<p>
+Then when you create your gem you have the following bits in your Rakefile:
+</p>
+<pre>
+ spec.add_dependency('mongrel', '&gt;= 0.3.9')
+ spec.add_dependency('gem_plugin', '&gt;= 0.1')
+ spec.autorequire = 'init.rb'
+</pre>
+<p>
+Finally, you just have to now publish this gem for people to install and
+Mongrel will &quot;magically&quot; be able to install it.
+</p>
+<p>
+The &quot;magic&quot; part though is pretty simple and done via the <a
+href="GemPlugin/Manager.html#M000006">GemPlugin::Manager.load</a> method.
+Read that to see how it is really done.
+</p>
+
+    </div>
+
+
+   </div>
+
+    <div id="method-list">
+      <h3 class="section-bar">Methods</h3>
+
+      <div class="name-list">
+      <a href="#M000001">Plugin</a>&nbsp;&nbsp;
+      </div>
+    </div>
+
+  </div>
+
+
+    <!-- if includes -->
+
+    <div id="section">
+
+    <div id="class-list">
+      <h3 class="section-bar">Classes and Modules</h3>
+
+      Class <a href="GemPlugin/Base.html" class="link">GemPlugin::Base</a><br />
+Class <a href="GemPlugin/Manager.html" class="link">GemPlugin::Manager</a><br />
+
+    </div>
+
+    <div id="constants-list">
+      <h3 class="section-bar">Constants</h3>
+
+      <div class="name-list">
+        <table summary="Constants">
+        <tr class="top-aligned-row context-row">
+          <td class="context-item-name">EXCLUDE</td>
+          <td>=</td>
+          <td class="context-item-value">true</td>
+        </tr>
+        <tr class="top-aligned-row context-row">
+          <td class="context-item-name">INCLUDE</td>
+          <td>=</td>
+          <td class="context-item-value">false</td>
+        </tr>
+        </table>
+      </div>
+    </div>
+
+
+
+      
+
+
+    <!-- if method_list -->
+    <div id="methods">
+      <h3 class="section-bar">Public Class methods</h3>
+
+      <div id="method-M000001" class="method-detail">
+        <a name="M000001"></a>
+
+        <div class="method-heading">
+          <a href="GemPlugin.src/M000001.html" target="Code" class="method-signature"
+            onclick="popupCode('GemPlugin.src/M000001.html');return false;">
+          <span class="method-name">Plugin</span><span class="method-args">(c)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+This nifty function works with the <a
+href="GemPlugin/Base.html">GemPlugin::Base</a> to give you the syntax:
+</p>
+<pre>
+ class MyThing &lt; GemPlugin::Plugin &quot;/things&quot;
+   ...
+ end
+</pre>
+<p>
+What it does is temporarily sets the GemPlugin::Base.category, and then
+returns <a href="GemPlugin/Base.html">GemPlugin::Base</a>. Since the next
+immediate thing Ruby does is use this returned class to create the new
+class, <a href="GemPlugin/Base.html#M000002">GemPlugin::Base.inherited</a>
+gets called. <a
+href="GemPlugin/Base.html#M000002">GemPlugin::Base.inherited</a> then uses
+the set category, class name, and class to register the plugin in the right
+way.
+</p>
+        </div>
+      </div>
+
+
+    </div>
+
+
+  </div>
+
+
+<div id="validator-badges">
+  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
+</div>
+
+</body>
+</html>