pluggability 0.4.3 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 74b416f4c7869bb0e92694c2cf9204934eb1c34e
-  data.tar.gz: afc7030991affa25440542dbcc8b2034d5b30a03
+SHA256:
+  metadata.gz: 4484023e3e262179c2c404956a61d7b2f45e39a4f35ec3a467ebb58487248a8c
+  data.tar.gz: 18c4dc97074347467326b56caaee97d198224179b5a2b927653999f3ef65cca6
 SHA512:
-  metadata.gz: baa2b85007768cdcb9737f652b0bff158dfe8126b110894a0f534950ce4d8b0b428794d9567593f261856db5d3f7b64430f01429f03fd06fde016bbc9053c2d5
-  data.tar.gz: 3073b7764f21c6c25bbf272e5802dcdcf20ea6dcf2af4a14f8e42531c8e50d1d77e520afeee87c2319f40d94d678347654e4ab1c1e506ce89e0790640295443e
+  metadata.gz: c91ad9882dbe4106aeb597d48400a5e2ca9e83fb89ac3961f6cacbd20bd2fdeb437e4b3e1e16bcefe4822c468865c91b82ba12dbdb311f6add6728de95dd46b4
+  data.tar.gz: 74b488aee0aae9ff89b74631f1a412b27356a51f3e62653d61715226871bd685ae9051880d5f26c573049b9944fbc50b239b86becae8b185d19e7e373180d2d7

data/History.md

@@ -0,0 +1,87 @@
+# Release History for pluggability
+
+---
+## v0.8.0 [2022-12-01] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Change default Ruby to 3.1
+- Fix support for classes with number in their name
+
+
+## v0.7.0 [2020-02-05] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Updated for Ruby 2.7
+
+
+## v0.6.0 [2018-03-12] Michael Granger <ged@FaerieMUD.org>
+
+Bugfix:
+
+- Switch back to require for loading derivatives
+
+
+## v0.5.0 [2018-01-19] Michael Granger <ged@FaerieMUD.org>
+
+Enhancements:
+
+- Update the mechanism used to search for derivatives for more-modern Rubygems,
+  Bundler, etc.
+
+
+## v0.4.3 [2015-03-04] Michael Granger <ged@FaerieMUD.org>
+
+Bugfix:
+
+- Add a workaround for older Rubygems to avoid Bundler problems.
+
+
+## v0.4.2 [2015-03-04] Michael Granger <ged@FaerieMUD.org>
+
+Bugfixes:
+
+- Set the minimum Rubygems version for #find_latest_files support [#1].
+
+
+## v0.4.1 [2015-03-03] Mahlon E. Smith <mahlon@martini.nu>
+
+Bugfix:
+
+- Only consider the latest versions of each installed gem
+  when finding files to load for .load_all.
+
+
+## v0.4.0 [2014-01-08] Michael Granger <ged@FaerieMUD.org>
+
+- Add a name attribute to plugins for introspection.
+
+
+## v0.3.0 [2013-09-25] Michael Granger <ged@FaerieMUD.org>
+
+- Add plugin exclusion patterns
+
+
+## v0.2.0 [2013-03-28] Michael Granger <ged@FaerieMUD.org>
+
+- Fix loading of grandchildren of plugins
+- Rename Pluggability::FactoryError to 
+  Pluggability::PluginError (with backward-compatibility aliases)
+
+
+## v0.1.0 [2013-03-27] Michael Granger <ged@FaerieMUD.org>
+
+- Add loading via underbarred name variants (CommaDelimitedThing ->
+  comma_delimited)
+- Rename some stuff for consistency.
+
+## v0.0.2 [2012-08-13] Michael Granger <ged@FaerieMUD.org>
+
+Simplify Pluggability#derivatives.
+
+
+## v0.0.1 [2012-08-03] Michael Granger <ged@FaerieMUD.org>
+
+First release after renaming from PluginFactory.
+

data/{README.rdoc → README.md}

@@ -1,22 +1,35 @@
-= pluggability
+# pluggability
 
-project:: https://bitbucket.org/ged/pluggability
-docs   :: http://deveiate.org/code/pluggability
-github :: http://github.com/ged/pluggability
+home
+: https://hg.sr.ht/~ged/Pluggability
 
+docs
+: https://deveiate.org/code/pluggability
 
-== Description
+code
+: https://hg.sr.ht/~ged/Pluggability/browse
 
-Pluggability 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.
+github
+: https://github.com/ged/pluggability
 
-An example of where this might be useful is in a program which generates
-output with a 'driver' object, which provides a unified interface but
-generates different kinds of output.
+
+## Description
+
+Pluggability is a toolkit for creating plugins.
+
+It provides a mixin that extends your class with methods to load and instantiate its subclasses by name. So instead of:
+
+    require 'acme/adapter/png'
+    png_adapter = Acme::Adapter::PNG.new( 'file.png' )
+  
+you can do:
+
+    require 'acme/adapter'
+    png_adapter = Acme::Adapter.create( :png, 'file.png' )
+
+A full example of where this might be useful is in a program which generates
+output with a 'driver' object, which provides a unified interface but generates
+different kinds of output.
 
 First the abstract base class, which is extended with Pluggability:
 
@@ -26,7 +39,7 @@ First the abstract base class, which is extended with Pluggability:
     
     class MyGem::Driver
         extend Pluggability
-        plugin_prefixes "drivers", "drivers/compat"
+        plugin_prefixes "mygem/drivers"
     end
 
 We can have one driver that outputs PDF documents:
@@ -60,14 +73,13 @@ it by its short name:
     ascii_driver = MyGem::Driver.create( :ascii, :columns => 80 )
 
 
-=== How Plugins Are Loaded
+### How Plugins Are Loaded
 
-The +create+ class method added to your class by Pluggability 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 +LogReader+ base
-class, and then use plugins to define readers for different log
-formats:
+The `create` class method added to your class by Pluggability 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 `LogReader` base class, and then use plugins to define
+readers for different log formats:
 
     require 'pluggability'
     
@@ -88,11 +100,10 @@ Pluggability searches for modules with the following names:
     apache_log_reader
     apache
  
-Obviously the last one might load something other than what is intended,
-so you can also tell Pluggability that plugins should be loaded from a
-subdirectory by declaring one or more +plugin_prefixes+ in the base
-class. Each prefix will be tried (in the order they're declared) when
-searching for a subclass:
+Obviously the last one might load something other than what is intended, so you
+can also tell Pluggability that plugins should be loaded from a subdirectory by
+declaring one or more `plugin_prefixes` in the base class. Each prefix will be
+tried (in the order they're declared) when searching for a subclass:
 
     class LogReader
         extend Pluggability
@@ -134,16 +145,16 @@ will change the search to include:
     'logreader/apache'
     'logreader/Apache'
 
-If the plugin is not found, a Pluggability::PluginError is raised, and
-the message will list all the permutations that were tried.
+If the plugin is not found, a Pluggability::PluginError is raised, and the
+message will list all the permutations that were tried.
 
 
-=== Preloaded Plugins
+### Preloaded Plugins
 
-Sometimes you don't want to wait for plugins to be loaded on demand. For
-that case, Pluggability provides the load_all[rdoc-ref:Pluggability#load_all]
-method. This will find all possible matches for plugin files and load
-them, returning an Array of all the loaded classes:
+Sometimes you don't want to wait for plugins to be loaded on demand. For that
+case, Pluggability provides the Pluggability#load_all method. This will find
+all possible matches for plugin files and load them, returning an Array of all
+the loaded classes:
 
     class Template::Tag
         extend Pluggability
@@ -153,11 +164,10 @@ them, returning an Array of all the loaded classes:
     tag_classes = Template::Tag.load_all
 
 
-=== Excluding Some Files
+### Excluding Some Files
 
-You can also prevent some files from being automatically loaded by
-either create[rdoc-ref:Pluggability#create] or 
-load_all[rdoc-ref:Pluggability#load_all] by setting one or more exclusion
+You can also prevent some files from being automatically loaded by either
+Pluggability#create or Pluggability#load_all by setting one or more exclusion
 patterns:
 
     LogReader.plugin_exclusions 'spec/*', %r{/test/}
@@ -165,11 +175,11 @@ patterns:
 The patterns can either be Regexps or glob Strings.
 
 
-=== Logging
+### Logging
 
-If you need a little more insight into what's going on, Pluggability
-uses the Loggability[https://rubygems.org/gems/loggability] library.
-Just set the log level to 'debug' and it'll explain what's going on:
+If you need a little more insight into what's going on, Pluggability uses the
+[Loggability](https://rubygems.org/gems/loggability) library. Just set the log
+level to 'debug' and it'll explain what's going on:
 
     require 'pluggability'
     require 'loggability'
@@ -213,16 +223,16 @@ this might generate a log that looks (something) like:
       "ringbufferlogreader", "ringbufferLogReader", "ringbuffer"]
 
 
-== Installation
+## Installation
 
     gem install pluggability
 
 
-== Contributing
+## Contributing
 
 You can check out the current development source with Mercurial via its
-{Mercurial repo}[https://bitbucket.org/ged/pluggability]. Or if you
-prefer Git, via {its Github mirror}[https://github.com/ged/pluggability].
+[Mercurial repo](https://bitbucket.org/ged/pluggability). Or if you prefer Git,
+via [its Github mirror](https://github.com/ged/pluggability).
 
 After checking out the source, run:
 
@@ -232,9 +242,15 @@ This task will install any missing dependencies, run the tests/specs,
 and generate the API documentation.
 
 
-== License
+## Authors
+
+- Michael Granger <ged@faeriemud.org>
+- Martin Chase <outofculture@gmail.com>
+
+
+## License
 
-Copyright (c) 2008-2013, Michael Granger and Martin Chase
+Copyright (c) 2008-2020, Michael Granger and Martin Chase
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

data/lib/pluggability.rb

@@ -12,7 +12,7 @@ module Pluggability
 
 
 	# Library version
-	VERSION = '0.4.3'
+	VERSION = '0.8.0'
 
 
 	# An exception class for Pluggability specific errors.
@@ -170,7 +170,7 @@ module Pluggability
 
 		simple_name = subclass.name.sub( /^.*::/i, '' ).sub( /\W+$/, '' )
 		keys << simple_name << simple_name.downcase
-		keys << simple_name.gsub( /([a-z])([A-Z])/, "\\1_\\2" ).downcase
+		keys << simple_name.gsub( /([a-z0-9])([A-Z])/, "\\1_\\2" ).downcase
 
 		# Handle class names like 'FooBar' for 'Bar' factories.
 		Pluggability.log.debug "Inherited %p for %p-type plugins" % [ subclass, self.plugin_type ]
@@ -273,12 +273,13 @@ module Pluggability
 				else
 					Gem.find_files( glob )
 				end
+
 			Pluggability.log.debug "  found %d matching files" % [ candidates.length ]
 			next if candidates.empty?
 
 			candidates.each do |path|
 				next if self.is_excluded_path?( path )
-				require( path )
+				Kernel.require( path )
 			end
 		end
 
@@ -286,15 +287,13 @@ module Pluggability
 	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.
+	### Calculates an appropriate filename for the derived class using the name of
+	### the base class and tries to load it via <tt>load</tt>. If the including
+	### class responds to a method named <tt>plugin_prefixes</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 load modules. Eg., if
+	### <tt>class.plugin_prefixes</tt> returns <tt>['foo','bar']</tt> the require
+	### line is tried with both <tt>'foo/'</tt> and <tt>'bar/'</tt> prepended to it.
 	def load_derivative( class_name )
 		Pluggability.log.debug "Loading derivative #{class_name}"
 
@@ -334,58 +333,48 @@ module Pluggability
 
 
 	### Search for the module with the specified <tt>mod_name</tt>, using any
-	### #plugin_prefixes that have been set.
+	### #plugin_prefixes that have been set. Return the path that was required.
 	def require_derivative( mod_name )
-
-		subdirs = self.plugin_prefixes
-		subdirs << '' if subdirs.empty?
-		Pluggability.log.debug "Subdirs are: %p" % [subdirs]
-		fatals = []
-		tries  = []
-
-		# Iterate over the subdirs until we successfully require a
-		# module.
-		subdirs.map( &:strip ).each do |subdir|
-			self.make_require_path( mod_name, subdir ).each do |path|
-				next if self.is_excluded_path?( path )
-
-				Pluggability.logger.debug "Trying #{path}..."
-				tries << path
-
-				# Try to require the module, saving errors and jumping
-				# out of the catch block on success.
-				begin
-					require( path.untaint )
-				rescue LoadError => err
-					Pluggability.log.debug "No module at '%s', trying the next alternative: '%s'" %
-						[ path, err.message ]
-				rescue Exception => err
-					fatals << err
-					Pluggability.log.error "Found '#{path}', but encountered an error: %s\n\t%s" %
-						[ err.message, err.backtrace.join("\n\t") ]
-				else
-					Pluggability.log.info "Loaded '#{path}' without error."
-					return path
-				end
-			end
-		end
-
-		Pluggability.logger.debug "fatals = %p" % [ fatals ]
-
-		# Re-raise is there was a file found, but it didn't load for
-		# some reason.
-		if fatals.empty?
+		plugin_path = self.find_plugin_path( mod_name )
+		unless plugin_path
 			errmsg = "Couldn't find a %s named '%s': tried %p" % [
 				self.plugin_type,
 				mod_name,
-				tries
-			  ]
+				self.plugin_path_candidates( mod_name )
+			]
 			Pluggability.log.error( errmsg )
-			raise PluginError, errmsg
-		else
-			Pluggability.log.debug "Re-raising first fatal error"
-			Kernel.raise( fatals.first )
+			raise Pluggability::PluginError, errmsg
 		end
+
+		Kernel.require( plugin_path )
+
+		return plugin_path
+	end
+
+
+	### Search for the file that corresponds to +mod_name+ using the plugin prefixes
+	### and current Gem load path and return the path to the first candidate that
+	### exists.
+	def find_plugin_path( mod_name )
+		candidates = self.plugin_path_candidates( mod_name )
+		Pluggability.log.debug "Candidates for %p are: %p" % [ mod_name, candidates ]
+
+		candidate_paths = candidates.
+			flat_map {|path| Gem.find_latest_files( path ) }.
+			reject {|path| self.is_excluded_path?( path ) || ! File.file?(path) }
+		Pluggability.log.debug "Valid candidates in the current gemset: %p" % [ candidate_paths ]
+
+		return candidate_paths.first
+	end
+
+
+	### Return an Array of all the filenames a plugin of the given +mod_name+ might
+	### map to given the current plugin_prefixes.
+	def plugin_path_candidates( mod_name )
+		prefixes = self.plugin_prefixes
+		prefixes << '' if prefixes.empty?
+
+		return prefixes.flat_map {|pre| self.make_require_path(mod_name, pre) }
 	end
 
 

data/spec/helpers.rb

@@ -11,6 +11,7 @@ RSpec.configure do |config|
 	config.run_all_when_everything_filtered = true
 	config.filter_run :focus
 	config.order = 'random'
+    config.warnings = true
 	config.mock_with( :rspec ) do |mock_config|
 		mock_config.syntax = :expect
 	end