pluginfactory 1.0.2 → 1.0.3

data/ChangeLog

@@ -1,102 +1,325 @@
-2004-03-09 22:32  Michael Granger <ged@FaerieMUD.org>
+-- Wed, 13 Aug 2008 21:58:41 -0000 by deveiant (r52) -----
+   Changed: lib/pluginfactory.rb
+            Rakefile
+            utils.rb
+            spec/pluginfactory_spec.rb
 
-	* makedist.rb (1.1), utils.rb (1.1), docs/.cvsignore (1.1),
-	docs/CATALOG (1.1), docs/makedocs.rb (1.1):
+   Updating tags on new files.
 
-	Initial checkin.
-	
-2004-03-08 00:07  Michael Granger <ged@FaerieMUD.org>
 
-	* tests/: othersub.rb (1.2), dir/deepsubofmybase.rb (1.2):
+-- Wed, 13 Aug 2008 21:57:47 -0000 by deveiant (r51) -----
+   Deleted: rake
 
-	- Fixed class/file agreement.
-	
-2004-03-08 00:06  Michael Granger <ged@FaerieMUD.org>
+   Removing old rake tasklib dir
 
-	* tests/mybase.rb (1.2):
 
-	- Fixed derivativeDirs method.
-	
-2004-03-08 00:05  Michael Granger <ged@FaerieMUD.org>
+-- Wed, 13 Aug 2008 21:57:18 -0000 by deveiant (r50) -----
+   Added:   project.yml (new)
+   Changed: README
+            /trunk
+            LICENSE
+            Rakefile
 
-	* lib/pluginfactory.rb (1.4):
+   Converting to the new build system
 
-	- Documentation additions
-	
-	- Refactored path-search code
-	
-2004-03-07 21:30  Michael Granger <ged@FaerieMUD.org>
 
-	* test.rb (1.3):
+-- Wed, 26 Mar 2008 16:01:36 -0000 by deveiant (r48) -----
+   Changed: Rakefile
+            rake/publishing.rb
+            rake/svn.rb
 
-	- Added a hook into -d that turns on logging.
-	
-2004-03-07 19:13  Martin Chase <stillflame@FaerieMUD.org>
+    * More packaging/publishing fixes.
 
-	* README (1.4):
 
-	no, this is not using the default install.rb installation process
-	
-2004-03-07 19:07  Martin Chase <stillflame@FaerieMUD.org>
+-- Tue, 25 Mar 2008 21:17:07 -0000 by deveiant (r46) -----
+   Changed: /trunk
+            Rakefile
+            rake/publishing.rb
 
-	* lib/pluginfactory.rb (1.3):
+    * Fixed announcement-sending task to use SMTP+SSL via a monkeypatch to net/smtp. (Maybe package it
+    up and upstream later?)
 
-	FactoryError now inherits from RuntimeError
-	
-2004-03-07 19:06  Martin Chase <stillflame@FaerieMUD.org>
 
-	* test.rb (1.2):
+-- Tue, 25 Mar 2008 19:36:11 -0000 by deveiant (r45) -----
+   Added:   experiments (new)
+            experiments/logger_output.rb (new)
+            rake/publishing.rb (new)
+   Changed: README
+            lib/pluginfactory.rb
+            /trunk
+            MANIFEST
+            LICENSE
+            Rakefile (and 4 other/s)
+   Deleted: .gemspec
+            makedist.rb
+            install.rb
+            .cvsignore
+            docs
 
-	filling in
-	
-2004-03-07 19:05  Martin Chase <stillflame@FaerieMUD.org>
+    * Packaging and publication tasks updated.
+    * Updated documentation.
 
-	* tests/: mybase.rb (1.1), othersub.rb (1.1), subofmybase.rb (1.1),
-	dir/deepsubofmybase.rb (1.1):
 
-	initial import
-	
-2004-03-07 15:42  Martin Chase <stillflame@FaerieMUD.org>
+-- Fri, 27 Jul 2007 06:53:27 -0000 by deveiant (r43) -----
+   Deleted: test.rb
 
-	* README (1.3):
+   Removed test runner script
 
-	reformatted
-	
-2004-03-07 15:41  Martin Chase <stillflame@FaerieMUD.org>
 
-	* install.rb (1.2):
+-- Fri, 27 Jul 2007 06:50:56 -0000 by deveiant (r42) -----
+   Added:   LICENSE
+            -> renamed from /trunk/COPYRIGHT@r41
+            Rakefile (new)
+            rake (new)
+            rake/helpers.rb (new)
+            spec/spec.opts (new)
+            rake/svn.rb (new) (and 4 other/s)
+   Changed: lib/pluginfactory.rb
+            /trunk
+            test.rb
+   Deleted: tests
+            COPYRIGHT
 
-	filled in
-	
-2004-03-07 14:36  Martin Chase <stillflame@FaerieMUD.org>
+   Converted test::unit tests to RSpec
 
-	* COPYRIGHT (1.2), README (1.2):
 
-	filled in
-	
-2004-03-07 10:49  Martin Chase <stillflame@FaerieMUD.org>
+-- Tue, 13 Mar 2007 18:34:19 -0000 by deveiant (r40) -----
+   Changed: /trunk
+            makedist.rb
 
-	* lib/pluginfactory.rb (1.2):
+   Bumping project-version and fixing makedist problems.
 
-	cleaned out ties to other modules
-	
-2004-03-07 09:33  Martin Chase <stillflame@FaerieMUD.org>
 
-	* lib/: factory.rb (1.2), pluginfactory.rb (1.1):
+-- Tue, 13 Mar 2007 18:20:58 -0000 by deveiant (r38) -----
+   Changed: lib/pluginfactory.rb
 
-	renaming
-	
-2004-03-07 09:31  Martin Chase <stillflame@FaerieMUD.org>
+    * Log list of candidate subdirs
 
-	* COPYRIGHT (1.1), README (1.1), install.rb (1.1), test.rb (1.1),
-	lib/factory.rb (1.1):
 
-	Initial revision
-	
-2004-03-07 09:31  Martin Chase <stillflame@FaerieMUD.org>
+-- Thu, 22 Feb 2007 23:03:05 -0000 by deveiant (r37) -----
+   Changed: lib/pluginfactory.rb
+
+
+    * Support #derivative_dirs method as well as the camelCased variant.
+
+
+-- Sat, 01 Jul 2006 18:50:52 -0000 by ged (r36) -----
+   Changed: lib/pluginfactory.rb
+            docs/makedocs.rb
+            test.rb
+
+
+    * Converted camelCased methods to under_barred ones.
+
+    * Fixed tests.
+
+
+-- Sat, 05 Mar 2005 00:32:10 -0000 by ged (r35) -----
+   Changed: /trunk
+
+   Incremented project version attribute
+
+
+-- Sat, 05 Mar 2005 00:25:54 -0000 by ged (r33) -----
+   Changed: makedist.rb
+
+   Merged changes from project-utils version
+
+
+-- Sat, 05 Mar 2005 00:21:05 -0000 by ged (r32) -----
+   Changed: lib/pluginfactory.rb
+
+   - Made load failures raise FactoryErrors as intended instead of RuntimeErrors.
+
+
+-- Sun, 21 Nov 2004 17:14:13 -0000 by ged (r31) -----
+   Changed: utils.rb
+            install.rb
+
+   -- Updated project-utils files
+
+
+-- Sun, 21 Nov 2004 17:02:59 -0000 by ged (r30) -----
+   Added:   .gemspec (new)
+   Changed: /trunk
+            MANIFEST
+
+   -- Gemified
+   -- Fixed missing utils.rb in MANIFEST
+   -- Added project-spec properties to the root dir.
+
+
+-- Wed, 08 Sep 2004 04:51:57 -0000 by ged (r28) -----
+   Added:   docs/makedocs.rb (new)
+            utils.rb (new)
+            makedist.rb (new)
+            install.rb (new)
+
+   - Hmmm... that didn't work. Copying over new versions of the util scripts until
+   I figure out how the hell to do what I want.
+
+
+-- Wed, 08 Sep 2004 04:27:06 -0000 by ged (r27) -----
+   Deleted: docs/makedocs.rb
+            utils.rb
+            makedist.rb
+            install.rb
+
+   - Replacing with versions from project-utils (experimental -- may just have to
+   re-check them in)
+
+
+-- Tue, 24 Aug 2004 01:38:10 -0000 by ged (r26) -----
+   Changed: lib/pluginfactory.rb
+
+   - Added a very important property
+
+
+-- Tue, 24 Aug 2004 01:36:11 -0000 by ged (r25) -----
+   Changed: lib/pluginfactory.rb
+
+   - Added keywords property to lib/pluginfactory.rb
+
+
+-- Tue, 24 Aug 2004 01:35:26 -0000 by ged (r24) -----
+   Changed: install.rb
+
+   - Fixed String =~ String warning
+
+
+-- Tue, 24 Aug 2004 01:34:13 -0000 by ged (r23) -----
+   Changed: install.rb
+
+   - Added bangheader
+
+
+-- Tue, 24 Aug 2004 01:33:14 -0000 by ged (r22) -----
+   Changed: test.rb
+
+   - Easyified bangheader
+
+
+-- Wed, 10 Mar 2004 06:36:15 -0000 by deveiant (r20) -----
+   Changed: ChangeLog
+
+   Updated for tag release_0_01
+
+
+-- Wed, 10 Mar 2004 06:34:00 -0000 by deveiant (r19) -----
+   Added:   .cvsignore (new)
+            .irbrc (new)
+            docs/makedocs.rb (new)
+            docs/CATALOG (new)
+            utils.rb (new)
+            makedist.rb (new) (and 5 other/s)
+   Changed: /trunk
+
+   Initial checkin.
+
+
+-- Mon, 08 Mar 2004 08:07:38 -0000 by deveiant (r18) -----
+   Changed: tests/dir/deepsubofmybase.rb
+            tests/othersub.rb
+
+   - Fixed class/file agreement.
+
+
+-- Mon, 08 Mar 2004 08:06:24 -0000 by deveiant (r17) -----
+   Changed: tests/mybase.rb
+
+   - Fixed derivativeDirs method.
+
+
+-- Mon, 08 Mar 2004 08:05:38 -0000 by deveiant (r16) -----
+   Changed: lib/pluginfactory.rb
+
+   - Documentation additions
+   - Refactored path-search code
+
+
+-- Mon, 08 Mar 2004 05:30:01 -0000 by deveiant (r15) -----
+   Changed: test.rb
+
+   - Added a hook into -d that turns on logging.
+
+
+-- Mon, 08 Mar 2004 03:13:38 -0000 by stillflame (r14) -----
+   Changed: README
+
+   no, this is not using the default install.rb installation process
+
+
+-- Mon, 08 Mar 2004 03:07:27 -0000 by stillflame (r13) -----
+   Changed: lib/pluginfactory.rb
+
+   FactoryError now inherits from RuntimeError
+
+
+-- Mon, 08 Mar 2004 03:06:05 -0000 by stillflame (r12) -----
+   Changed: test.rb
+
+   filling in
+
+
+-- Mon, 08 Mar 2004 03:05:36 -0000 by stillflame (r11) -----
+   Added:   tests/dir/deepsubofmybase.rb (new)
+            tests/othersub.rb (new)
+            tests/dir (new)
+            tests (new)
+            tests/subofmybase.rb (new)
+            tests/mybase.rb (new) (and 1 other/s)
+
+   initial import
+
+
+-- Sun, 07 Mar 2004 23:42:11 -0000 by stillflame (r10) -----
+   Changed: README
+
+   reformatted
+
+
+-- Sun, 07 Mar 2004 23:41:51 -0000 by stillflame (r9) -----
+   Changed: install.rb
+
+   filled in
+
+
+-- Sun, 07 Mar 2004 22:36:44 -0000 by stillflame (r8) -----
+   Changed: README
+            COPYRIGHT
+
+   filled in
+
+
+-- Sun, 07 Mar 2004 18:49:23 -0000 by stillflame (r7) -----
+   Changed: lib/pluginfactory.rb
+
+   cleaned out ties to other modules
+
+
+-- Sun, 07 Mar 2004 17:33:10 -0000 by stillflame (r6) -----
+   Added:   lib/pluginfactory.rb (new)
+   Deleted: lib/factory.rb
+
+   renaming
+
+
+-- Sun, 07 Mar 2004 17:31:18 -0000 by stillflame (r2) -----
+   Added:   README (new)
+            lib/factory.rb (new)
+            test.rb (new)
+            lib (new)
+            COPYRIGHT (new)
+            install.rb (new) (and 1 other/s)
+
+   Initial revision
+
+
+-- Sun, 07 Mar 2004 17:31:18 -0000 by unknown (r1) -----
+   Added:   /trunk (new)
+            /branches (new)
+            /tags (new)
+
+   New repository initialized by cvs2svn.
 
-	* COPYRIGHT (1.1.1.1), README (1.1.1.1), install.rb (1.1.1.1),
-	test.rb (1.1.1.1), lib/factory.rb (1.1.1.1) (utags: release):
 
-	initial stripping out of Arrow/MUES
-	

data/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2008, Michael Granger
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+  * Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+  * Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+  * Neither the name of the author/s, nor the names of the project's
+    contributors may be used to endorse or promote products derived from this
+    software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README

@@ -1,39 +1,204 @@
-= The PluginFactory mixin
 
-A mixin implementing a factory pattern, modified to load in subclasses on
-request.
+= PluginFactory
 
-== Install
+PluginFactory is a mixin module that turns an including class into a factory for
+its derivatives, capable of searching for and loading them by name. This is
+useful when you have an abstract base class which defines an interface and basic
+functionality for a part of a larger system, and a collection of subclasses
+which implement the interface for different underlying functionality.
 
-$ sudo ./install.rb
+An example of where this might be useful is in a program which talks to a
+database. To avoid coupling it to a specific database, you use a Driver class
+which encapsulates your program's interaction with the database behind a useful
+interface. Now you can create a concrete implementation of the Driver class for
+each kind of database you wish to talk to. If you make the base Driver class a
+PluginFactory, too, you can add new drivers simply by dropping them in a
+directory and using the Driver's <tt>create</tt> method to instantiate them:
 
-== Tests
+== Synopsis
 
-$ ./test.rb
+in driver.rb:
 
-== Authors
+  require "PluginFactory"
+
+  class Driver
+  	include PluginFactory
+  	def self::derivative_dirs
+  	   ["drivers"]
+  	end
+  end
+
+in drivers/mysql.rb:
+
+  require 'driver'
+
+  class MysqlDriver < Driver
+  	...implementation...
+  end
+
+in /usr/lib/ruby/1.8/PostgresDriver.rb:
+
+  require 'driver'
+
+  class PostgresDriver < Driver
+  	...implementation...
+  end
+
+elsewhere
+
+  require 'driver'
+
+  config[:driver_type] #=> "mysql"
+  driver = Driver.create( config[:driver_type] )
+  driver.class #=> MysqlDriver
+  pgdriver = Driver.create( "PostGresDriver" )
+
+== How Plugins Are Loaded
+
+The +create+ class method added to your class by PluginFactory searches for your
+module using several different strategies. It tries various permutations of the
+base class's name in combination with the derivative requested. For example,
+assume we want to make a +DataDriver+ base class, and then use plugins to define
+drivers for different kinds of data sources:
+
+  require 'pluginfactory'
+
+  class DataDriver
+	include PluginFactory
+  end
+
+When you attempt to load the 'socket' data-driver class like so:
+
+  DataDriver.create( 'socket' )
+
+PluginFactory searches for modules with the following names:
 
-Michael Granger <ged@FaerieMUD.org>
+  'socketdatadriver'
+  'socket_datadriver'
+  'socketDataDriver'
+  'socket_DataDriver'
+  'SocketDataDriver'
+  'Socket_DataDriver'
+  'socket'
+  'Socket'
 
-== Contributors
+Obviously the last one will load something other than what is intended, so you
+can also tell PluginFactory that plugins should be loaded from a subdirectory by
+declaring a class method called `derivative_dirs` in the base class. It should
+return an Array that contains a list of subdirectories to try:
 
-Martin Chase <stillflame@FaerieMUD.org>
+  class DataDriver
+	include PluginFactory
+	
+	def self::derivative_dirs
+	  ['drivers']
+	end
+  end
 
-== License/Legal
+This will change the list that is required to:
+
+  'drivers/socketdatadriver'
+  'drivers/socket_datadriver'
+  'drivers/socketDataDriver'
+  'drivers/socket_DataDriver'
+  'drivers/SocketDataDriver'
+  'drivers/Socket_DataDriver'
+  'drivers/socket'
+  'drivers/Socket'
+
+If you return more than one subdirectory, each of them will be tried in turn:
+
+  class DataDriver
+	include PluginFactory
+	
+	def self::derivative_dirs
+	  ['drivers', 'datadriver']
+	end
+  end
+
+will change the search to include:
+
+  'drivers/socketdatadriver'
+  'drivers/socket_datadriver'
+  'drivers/socketDataDriver'
+  'drivers/socket_DataDriver'
+  'drivers/SocketDataDriver'
+  'drivers/Socket_DataDriver'
+  'drivers/socket'
+  'drivers/Socket'
+  'datadriver/socketdatadriver'
+  'datadriver/socket_datadriver'
+  'datadriver/socketDataDriver'
+  'datadriver/socket_DataDriver'
+  'datadriver/SocketDataDriver'
+  'datadriver/Socket_DataDriver'
+  'datadriver/socket'
+  'datadriver/Socket'
+
+If the plugin is not found, a FactoryError is raised, and the message will list
+all the permutations that were tried.
+
+== Logging
+
+If you need a little more insight into what's going on, PluginFactory exposes a
+logging callback which will be called at various points in the process, and will
+include details on what's being attempted.
+
+You can activate logging by setting PluginFactory.logger_callback to something
+that responds to the #call message. It will be called with two arguments, a
+severity level and a message:
+
+  callback.call( :info, "Something happened" )
+
+This is intended to make it easy to hook up to Logger or anything with a similar
+interface:
+
+  require 'pluginfactory'
+  require 'logger'
+  
+  class DataDriver
+    include PluginFactory
+    
+    @logger = Logger.new( $stderr )
+    @logger.level = Logger::DEBUG
+    PluginFactory.logger_callback = lambda do |severity, msg|
+      @logger.send(severity, msg)
+    end
+  end
+  
+  DataDriver.create( 'ringbuffer' )
+
+this might generate a log that looks like:
+
+  D, [...] DEBUG -- : Loading derivative ringbuffer
+  D, [...] DEBUG -- : Subdirs are: [""]
+  D, [...] DEBUG -- : Path is: ["ringbufferdatadriver", "ringbufferDataDriver", 
+        "ringbuffer"]...
+  D, [...] DEBUG -- : Trying ringbufferdatadriver...
+  D, [...] DEBUG -- : No module at 'ringbufferdatadriver', trying the next 
+        alternative: 'no such file to load -- ringbufferdatadriver'
+  D, [...] DEBUG -- : Trying ringbufferDataDriver...
+  D, [...] DEBUG -- : No module at 'ringbufferDataDriver', trying the next 
+        alternative: 'no such file to load -- ringbufferDataDriver'
+  D, [...] DEBUG -- : Trying ringbuffer...
+  D, [...] DEBUG -- : No module at 'ringbuffer', trying the next alternative: 
+        'no such file to load -- ringbuffer'
+  D, [...] DEBUG -- : fatals = []
+  E, [...] ERROR -- : Couldn't find a DataDriver named 'ringbuffer': 
+        tried ["ringbufferdatadriver", "ringbufferDataDriver", "ringbuffer"]
+
+== Subversion ID
+
+$Id: README 50 2008-08-13 21:57:18Z deveiant $
+
+== Authors
 
-All assets of the project are copyright (c) 2003-2004, The FaerieMUD
-Consortium. All rights reserved.
+* Martin Chase <stillflame@FaerieMUD.org>
+* Michael Granger <ged@FaerieMUD.org>
 
-You may use, modify, and/or redistribute this software under the terms of the
-Perl Artistic License, a copy of which should have been included in this
-distribution (See the file COPYRIGHT). If it was not, a copy of it may be
-obtained from http://language.perl.com/misc/Artistic.html or
-http://www.faeriemud.org/artistic.html).
+:include: LICENSE
 
-THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
-INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND
-FITNESS FOR A PARTICULAR PURPOSE.
+--
 
-== Rcsid
+Please see the file LICENSE for licensing details.
 
-   $Id: README 14 2004-03-08 03:13:38Z stillflame $