plugin 0.9 → 1.0

data/README

@@ -1,32 +1,34 @@
 = Plugin
 
 * home: http://rubyworks.github.com/plugin
+* source: http://github.com/rubyworks/plugin
 
 
 == DESCRIPTION
 
-Plugin is a straighforward plugin manager for Ruby.
-It can handle RubyGems, Rolls and Ruby's standard
-site locals.
-
-
-== USAGE
+Plugin is a straighforward plugin manager for Ruby. It can handle
+RubyGems, Rolls and Ruby's standard site locals. It is both more
+flexible and more robust the using Gem.find_files or searching the
+$LOAD_PATH manually.
 
 The Plugin library does two signifficant things. First it designates
 a location in the ruby $LOAD_PATH for plugins. Second it provides
 an easy to use function for finding plugin scripts stored in the
 designated location.
 
-Place all plugin code in your project's <tt>lib/plugin/<name>/</tt>,
-or if you have altered the load path for your project, you can
-place it in the alternae location under <tt>plugin/<name></tt>.
+== USAGE
+
+Place all plugins for you projectt in <tt>lib/plugin/<name>/</tt>.
+Or if you have altered the load path for your project, you can
+place it in the alternate location under <tt>plugin/<name></tt>.
+However, this is not a recommended practice.
 
-To find plugins, simply provide a path or file glob to the
-<tt>Plugin.find</tt> function, and it will return all matches
-found within current and most recent versions of libraries.
+To find plugins, simply provide a glob to the <tt>Plugin.find</tt> function,
+and it will return all matches found within current and/or most recent versions
+of libraries.
 
-For example, it wil be common for pluggable applications to require all
-the plugins they find:
+For example, a common use case for a pluggable application is to require all
+the plugins found:
 
   require 'plugin'
 
@@ -34,8 +36,8 @@ the plugins they find:
     require(file)
   end
 
-Alternately you might load plugins only as needs. Say, it a command-line
-call required it.
+Alternately you might load plugins only as needed. For instance, if a command-line
+option calls for it.
 
 
 == COPYRIGHTS

data/lib/plugin.rb

@@ -2,6 +2,38 @@
 #
 # Find plugins across various library managers.
 #
+# All plugins are expected to be within a libraries designated
+# loadpath(s) under a <tt>plugin/</tt> subdirectory. By using
+# this assigned space, ie. <tt>plugin/<tt>, plugins are kept
+# isolated from normal libary scripts. This helps prevent 
+# inadvertent name clashes.
+#
+# == How To Use
+#
+# Usage is very simple. Just supply a glob to the +Plugin.find+
+# function.
+#
+#     Plugin.find('syckle/*')
+#
+# A shortcut is provided with <tt>[]</tt>.
+#
+#     Plugin['syckle/*']
+#
+# == A Note on RubyGems
+#
+# A way has not yet been devised to isolate the actived version
+# of a gem from the latest inactive version. Therefore some
+# overlap can occur if an older version of a plugin-containing
+# gem has been activated prior to calling Plugin.find(). Such an
+# occurance will be rare (considering the use cases of plugins),
+# so it is nothing to be overly concerned about. Moreover, it is
+# a long-way from the offical Gems plugin policy which is to find
+# all matching files from *all* versions using Gem.find_files().
+# I quote Eric Hodel, "It's an encouragement to make your plugin
+# files as light as possible, such as requiring an additional file
+# or calling some very stable API." While an understandable
+# encouragment, ultimately it is not a robust solution.
+
 module Plugin
 
   extend self
@@ -17,20 +49,27 @@ module Plugin
   #
   def find(match)
     plugins = []
+    plugins.concat find_roll(match)
+    plugins.concat find_loadpath(match)
+    plugins.concat find_gems(match)
+    plugins.uniq
+  end
 
-    # Standard $LOAD_PATH
-    $LOAD_PATH.uniq.each do |path|
-      list = Dir.glob(File.join(path, DIRECTORY, match))
-      #dirs = dirs.select{ |d| File.directory?(d) }
-      list = list.map{ |d| d.chomp('/') }
-      plugins.concat(list)
-    end
+  # Shortcut for #find.
+  #
+  #   Plugin['syckle/*']
+  #
+  alias_method :[], :find
+
+
+  # Search roll for current or latest libraries.
 
-    # ROLL (load latest or current versions only)
+  def find_roll(match)
+    plugins = []
     if defined?(::Roll)
       ::Roll::Library.ledger.each do |name, lib|
         lib = lib.sort.first if Array===lib
-        lib.load_path.each do |path|
+        lib.loadpath.each do |path|
           find = File.join(lib.location, path, DIRECTORY, match)
           list = Dir.glob(find)
           list = list.map{ |d| d.chomp('/') }
@@ -38,25 +77,39 @@ module Plugin
         end
       end
     end
+    plugins
+  end
+
+  # Search standard $LOAD_PATH.
+  #
+  # Activated gem versions are in here too.
+
+  def find_loadpath(match)
+    plugins = []
+    $LOAD_PATH.uniq.each do |path|
+      list = Dir.glob(File.join(path, DIRECTORY, match))
+      #dirs = dirs.select{ |d| File.directory?(d) }
+      list = list.map{ |d| d.chomp('/') }
+      plugins.concat(list)
+    end
+    plugins
+  end
+
+  # Search latest gem versions.
+  #
+  # TODO: Is there anyway to skip active gems?
 
-    # RubyGems (load latest versions only)
-    # TODO: need current versions
+  def find_gems(match)
+    plugins = []
     if defined?(::Gem)
-      Gem.latest_load_paths do |path|
+      ::Gem.latest_load_paths do |path|
         list = Dir.glob(File.join(path, DIRECTORY, match))
         list = list.map{ |d| d.chomp('/') }
         plugins.concat(list)
       end
     end
-
     plugins
   end
 
-  # Shortcut for #find.
-  #
-  #   Plugins['syckle/*']
-  #
-  alias_method :[], :find
-
 end
 

data/meta/version

@@ -1 +1 @@
-0.9
+1.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: plugin
 version: !ruby/object:Gem::Version 
-  version: "0.9"
+  version: "1.0"
 platform: ruby
 authors: 
 - Thomas Sawyer
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-20 00:00:00 -05:00
+date: 2009-11-24 00:00:00 -05:00
 default_executable: 
 dependencies: []