mongrel 0.3 → 0.3.1

data/lib/pluginfactory.rb

@@ -0,0 +1,384 @@
+#!/usr/bin/env ruby -w
+#
+# This module contains the PluginFactory mixin. Including PluginFactory in your
+# class turns it 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.
+#
+# 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:
+#
+# == Creation Argument Variants
+#
+# The +create+ class method added to your class by PluginFactory searches for your module using 
+#
+# == Synopsis
+# 
+#---##### in driver.rb #####---
+# 
+#	require "PluginFactory"
+#
+#	class Driver
+#		include PluginFactory
+#		def self::derivativeDirs
+#		   ["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" )
+# 
+#---##########
+# 
+# == Rcsid
+# 
+# $Id: pluginfactory.rb 32 2005-03-05 00:21:05Z ged $
+# 
+# == Authors
+# 
+# * Martin Chase <stillflame@FaerieMUD.org>
+# * Michael Granger <ged@FaerieMUD.org>
+# 
+# modified temporarily by Zed A. Shaw until license attribution can be given.
+#---
+#
+# Please see the file docs/COPYRIGHT for licensing details.
+#
+
+
+### An exception class for PluginFactory specific errors.
+class FactoryError < RuntimeError
+	def initialize( *args )
+		if ! args.empty?
+			msg = args.collect {|a| a.to_s}.join
+			super( msg )
+		else
+			super( message )
+		end					
+	end
+end # class FactoryError
+
+
+### A mixin that adds PluginFactory class methods to a base class, so that
+### subclasses may be instantiated by name.
+module PluginFactory
+
+	### A callback for logging the various debug and information this module
+	### has to log.  Should take two arguments, the log level, possibly as a
+	### symbol, and the log message itself.
+	@logger_callback = nil
+	class << self
+		attr_accessor :logger_callback
+	end
+
+	### If the logger callback is set, use it to pass on a log entry.  First argument is 
+	def self::log(level, *msg)
+		@logger_callback.call(level, msg.join) if @logger_callback
+	end
+
+
+	### Inclusion callback -- extends the including class.
+	def self::included( klass )
+		klass.extend( self )
+	end
+
+
+	### Raise an exception if the object being extended is anything but a
+	### class.
+	def self::extend_object( obj )
+		unless obj.is_a?( Class )
+			raise TypeError, "Cannot extend a #{obj.class.name}", caller(1)
+		end
+		obj.instance_variable_set( :@derivatives, {} )
+		super
+	end
+
+
+	#############################################################
+	###	M I X I N   M E T H O D S
+	#############################################################
+
+	### Return the Hash of derivative classes, keyed by various versions of
+	### the class name.
+	def derivatives
+		ancestors.each {|klass|
+			if klass.instance_variables.include?( "@derivatives" )
+				break klass.instance_variable_get( :@derivatives )
+			end
+		}
+	end
+
+
+	### Returns the type name used when searching for a derivative.
+	def factoryType
+		base = nil
+		self.ancestors.each {|klass|
+			if klass.instance_variables.include?( "@derivatives" )
+				base = klass
+				break
+			end
+		}
+
+		raise FactoryError, "Couldn't find factory base for #{self.name}" if
+			base.nil?
+
+		if base.name =~ /^.*::(.*)/
+			return $1
+		else
+			return base.name
+		end
+	end
+
+	
+	### Inheritance callback -- Register subclasses in the derivatives hash
+	### so that ::create knows about them.
+	def inherited( subclass )
+		keys = [ subclass.name, subclass.name.downcase, subclass ]
+
+		# Handle class names like 'FooBar' for 'Bar' factories.
+		if subclass.name.match( /(?:.*::)?(\w+)(?:#{self.factoryType})/i )
+			keys << Regexp.last_match[1].downcase
+		else
+			keys << subclass.name.sub( /.*::/, '' ).downcase
+		end
+
+		keys.uniq.each {|key|
+			#PluginFactory::log :info, "Registering %s derivative of %s as %p" %
+			#	[ subclass.name, self.name, key ]
+			self.derivatives[ key ] = subclass
+		}
+		super
+	end
+
+
+	### Returns an Array of registered derivatives
+	def derivativeClasses
+		self.derivatives.values.uniq
+	end
+
+
+	### Given the <tt>className</tt> of the class to instantiate, and other
+	### arguments bound for the constructor of the new object, this method
+	### loads the derivative class if it is not loaded already (raising a
+	### LoadError if an appropriately-named file cannot be found), and
+	### instantiates it with the given <tt>args</tt>. The <tt>className</tt>
+	### may be the the fully qualified name of the class, the class object
+	### itself, or the unique part of the class name. The following examples
+	### would all try to load and instantiate a class called "FooListener"
+	### if Listener included Factory
+	###   obj = Listener::create( 'FooListener' )
+	###   obj = Listener::create( FooListener )
+	###   obj = Listener::create( 'Foo' )
+	def create( subType, *args, &block )
+		subclass = getSubclass( subType )
+
+		return subclass.new( *args, &block )
+	rescue => err
+		nicetrace = err.backtrace.reject {|frame| /#{__FILE__}/ =~ frame}
+		msg = "When creating '#{subType}': " + err.message
+		Kernel::raise( err.class, msg, nicetrace )
+	end
+
+
+	### Given a <tt>className</tt> like that of the first argument to
+	### #create, attempt to load the corresponding class if it is not
+	### already loaded and return the class object.
+	def getSubclass( className )
+		return self if ( self.name == className || className == '' )
+		return className if className.is_a?( Class ) && className >= self
+
+		unless self.derivatives.has_key?( className.downcase )
+			self.loadDerivative( className )
+
+			unless self.derivatives.has_key?( className.downcase )
+				raise FactoryError,
+					"loadDerivative(%s) didn't add a '%s' key to the "\
+					"registry for %s" %
+					[ className, className.downcase, self.name ]
+			end
+
+			subclass = self.derivatives[ className.downcase ]
+			unless subclass.is_a?( Class )
+				raise FactoryError,
+					"loadDerivative(%s) added something other than a class "\
+					"to the registry for %s: %p" %
+					[ className, self.name, subclass ]
+			end
+		end
+
+		return self.derivatives[ className.downcase ]
+	end
+
+
+	### Calculates an appropriate filename for the derived class using the
+	### name of the base class and tries to load it via <tt>require</tt>. If
+	### the including class responds to a method named
+	### <tt>derivativeDirs</tt>, its return value (either a String, or an
+	### array of Strings) is added to the list of prefix directories to try
+	### when attempting to require a modules. Eg., if
+	### <tt>class.derivativeDirs</tt> returns <tt>['foo','bar']</tt> the
+	### require line is tried with both <tt>'foo/'</tt> and <tt>'bar/'</tt>
+	### prepended to it.
+	def loadDerivative( className )
+		className = className.to_s
+
+		#PluginFactory::log :debug, "Loading derivative #{className}"
+
+		# Get the unique part of the derived class name and try to
+		# load it from one of the derivative subdirs, if there are
+		# any.
+		modName = self.getModuleName( className )
+		self.requireDerivative( modName )
+
+		# Check to see if the specified listener is now loaded. If it
+		# is not, raise an error to that effect.
+		unless self.derivatives[ className.downcase ]
+			raise FactoryError,
+				"Couldn't find a %s named '%s'. Loaded derivatives are: %p" % [
+				self.factoryType,
+				className.downcase,
+				self.derivatives.keys,
+			], caller(3)
+		end
+
+		return true
+	end
+
+
+	### Build and return the unique part of the given <tt>className</tt>
+	### either by stripping leading namespaces if the name already has the
+	### name of the factory type in it (eg., 'My::FooService' for Service,
+	### or by appending the factory type if it doesn't.
+	def getModuleName( className )
+		if className =~ /\w+#{self.factoryType}/
+			modName = className.sub( /(?:.*::)?(\w+)(?:#{self.factoryType})/, "\\1" )
+		else
+			modName = className
+		end
+
+		return modName
+	end
+
+
+	### If the factory responds to the #derivativeDirs method, call
+	### it and use the returned array as a list of directories to
+	### search for the module with the specified <tt>modName</tt>.
+	def requireDerivative( modName )
+
+		# See if we have a list of special subdirs that derivatives
+		# live in
+		if ( self.respond_to?(:derivativeDirs) )
+			subdirs = self.derivativeDirs
+			subdirs = [ subdirs ] unless subdirs.is_a?( Array )
+
+		# If not, just try requiring it from $LOAD_PATH
+		else
+			subdirs = ['']
+		end
+
+		fatals = []
+
+		# Iterate over the subdirs until we successfully require a
+		# module.
+		catch( :found ) {
+			subdirs.collect {|dir| dir.strip}.each do |subdir|
+				self.makeRequirePath( modName, subdir ).each {|path|
+					#PluginFactory::log :debug, "Trying #{path}..."
+
+					# Try to require the module, saving errors and jumping
+					# out of the catch block on success.
+					begin
+						require( path.untaint )
+					rescue LoadError => err
+						PluginFactory::log :debug,
+							"No module at '%s', trying the next alternative: '%s'" %
+							[ path, err.message ]
+					rescue ScriptError,StandardError => err
+						fatals << err
+						PluginFactory::log :error,
+							"Found '#{path}', but encountered an error: %s\n\t%s" %
+							[ err.message, err.backtrace.join("\n\t") ]
+					else
+						#PluginFactory::log :debug, 
+						#	"Found '#{path}'. Throwing :found"
+						throw :found
+					end
+				}
+			end
+
+			#PluginFactory::log :debug, "fatals = %p" % [ fatals ]
+
+			# Re-raise is there was a file found, but it didn't load for
+			# some reason.
+			if ! fatals.empty?
+				#PluginFactory::log :debug, "Re-raising first fatal error"
+				Kernel::raise( fatals.first )
+			end
+
+			nil
+		}
+	end
+
+
+	### Make a list of permutations of the given +modname+ for the given
+	### +subdir+. Called on a +DataDriver+ class with the arguments 'Socket' and
+	### 'drivers', returns:
+	###   ["drivers/socketdatadriver", "drivers/socketDataDriver",
+	###    "drivers/SocketDataDriver", "drivers/socket", "drivers/Socket"]
+	def makeRequirePath( modname, subdir )
+		path = []
+		myname = self.factoryType
+
+		# Make permutations of the two parts
+		path << modname
+		path << modname.downcase
+		path << modname			 + myname
+		path << modname.downcase + myname
+		path << modname.downcase + myname.downcase
+
+		# If a non-empty subdir was given, prepend it to all the items in the
+		# path
+		unless subdir.nil? or subdir.empty?
+			path.collect! {|m| File::join(subdir, m)}
+		end
+
+		return path.uniq.reverse
+	end
+
+end # module Factory

data/tools/rakehelp.rb

@@ -65,35 +65,39 @@ end
 
 
 def setup_gem(pkg_name, pkg_version, author, summary, executables, test_file)
-    pkg_version = pkg_version
-    pkg_name    = pkg_name
-    pkg_file_name = "#{pkg_name}-#{pkg_version}"
-
-    spec = Gem::Specification.new do |s|
-        s.name = pkg_name
-        s.version = pkg_version
-        s.platform = Gem::Platform::RUBY
-        s.author = author
-        s.summary = summary
-        s.test_file = test_file
-        s.has_rdoc = true
-        s.extra_rdoc_files = [ "README" ]
-
-        s.files = %w(COPYING LICENSE ext/http11/MANIFEST README Rakefile setup.rb) +
-        Dir.glob("{bin,doc,test,lib}/**/*") + 
-        Dir.glob("ext/**/*.{h,c,rb}") +
-        Dir.glob("examples/**/*.rb") +
-        Dir.glob("tools/*.rb")
+  pkg_version = pkg_version
+  pkg_name    = pkg_name
+  pkg_file_name = "#{pkg_name}-#{pkg_version}"
+  
+  spec = Gem::Specification.new do |s|
+    s.name = pkg_name
+    s.version = pkg_version
+    s.platform = Gem::Platform::RUBY
+    s.author = author
+    s.summary = summary
+    s.test_file = test_file
+    s.has_rdoc = true
+    s.extra_rdoc_files = [ "README" ]
     
-        s.require_path = "lib"
-        s.extensions = FileList["ext/**/extconf.rb"].to_a
-
-        s.executables = executables
-        s.bindir = "bin"
-    end
-
-    Rake::GemPackageTask.new(spec) do |p|
-        p.gem_spec = spec
-        p.need_tar = true
+    s.files = %w(COPYING LICENSE ext/http11/MANIFEST README Rakefile setup.rb) +
+      Dir.glob("{bin,doc/rdoc,test,lib}/**/*") + 
+      Dir.glob("ext/**/*.{h,c,rb}") +
+      Dir.glob("examples/**/*.rb") +
+      Dir.glob("tools/*.rb")
+    
+    s.require_path = "lib"
+    s.extensions = FileList["ext/**/extconf.rb"].to_a
+    
+    s.executables = executables
+    s.bindir = "bin"
+    
+    if block_given?
+      yield s
     end
+  end
+  
+  Rake::GemPackageTask.new(spec) do |p|
+    p.gem_spec = spec
+    p.need_tar = true
+  end
 end