plugin 1.0 → 1.1

data/HISTORY

@@ -1,8 +1,33 @@
 = RELEASE HISTORY
 
-== 0.1 / 2009-11-19
+== 1.1 / 2010-02-07
 
-This is the initial release of Plug.
+This release includes two significant adjustments.
+
+First, the conventional plugin directory has been renamed to 'plugins/',
+instead of 'plugin/'. I frequently shy away from plural names
+(as in the tendency in Ruby), but in this case I believe it helps
+differentiate it from regular library directories. It also frees 'plugin/'
+should any separate scripts be required for this project in the future.
+
+Second, should one need to search outside of the conventional 'plugins/'
+location, the #find method will accept a :directory option. This usage
+is discouraged, but is made available for the rare cases in which it
+might prove necessary.
+
+Changes:
+
+* Standard Plugin directory is 'plugins/' instead of 'plugin/'.
+* Can specify an alternate plugin directory by passing an option to #find.
+* $LOAD_PATHS are expanded, so all paths are returned as full path names.
+
+
+== 1.0 / 2009-11-24
+
+This is the first official public release of Plugin.
+Plugin provides a very easy way to locate plugins, and
+this making it super easy for your project to support
+pluggable components.
 
 Changes:
 

data/{README → README.rdoc}

@@ -16,12 +16,12 @@ 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.
 
+
 == USAGE
 
-Place all plugins for you projectt in <tt>lib/plugin/<name>/</tt>.
+Place all plugins for your project in <tt>lib/plugins/<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.
+place them in the alternate location, <tt><alternate-loadpath>/plugins/<name>/</tt>.[1]
 
 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
@@ -39,6 +39,8 @@ the plugins found:
 Alternately you might load plugins only as needed. For instance, if a command-line
 option calls for it.
 
+[1] Alterating the conventional load path shoud be avoided whenever possible.
+
 
 == COPYRIGHTS
 

data/lib/plugin.rb

@@ -2,11 +2,17 @@
 #
 # 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.
+# All plugins are expected to be within a library's designated
+# loadpath(s) under a toplevel <tt>plugins/</tt> subdirectory.
+# By using this assigned space plugins are kept isolated from
+# normal library scripts, which helps prevent inadvertent
+# name clashes.
+#
+# For example, lets say we want to create a pluggable template
+# system for our "luckyweb" project. Our <tt>lib/</tt>
+# directory would have the usual <tt>luckyweb</tt> directory,
+# but also now a <tt>plugins/luckyweb/</tt> path in which the
+# plugin templates would be stored.
 #
 # == How To Use
 #
@@ -19,6 +25,16 @@
 #
 #     Plugin['syckle/*']
 #
+# == Alternate Plugin Location
+#
+# By default <tt>plugins/</tt> is hardcoded into the system
+# as a reliable convention. This is intentional. However,
+# if you have specific need for serching for files outside
+# that directory you can do so by supplying a <tt>:directory</tt>
+# option to the <tt>#find</tt> command. Eg.
+#
+#     Plugin.find('discover.rb', :directory=>'rdoc')
+#
 # == A Note on RubyGems
 #
 # A way has not yet been devised to isolate the actived version
@@ -38,7 +54,7 @@ module Plugin
 
   extend self
 
-  DIRECTORY = 'plugin'
+  DIRECTORY = 'plugins'
 
   # Find plugins, searching through standard $LOAD_PATH,
   # Roll Libraries and RubyGems.
@@ -47,11 +63,11 @@ module Plugin
   #
   #   Plugins.find('syckle/*')
   #
-  def find(match)
+  def find(match, options={})
     plugins = []
-    plugins.concat find_roll(match)
-    plugins.concat find_loadpath(match)
-    plugins.concat find_gems(match)
+    plugins.concat find_roll(match, options)
+    plugins.concat find_loadpath(match, options)
+    plugins.concat find_gems(match, options)
     plugins.uniq
   end
 
@@ -64,13 +80,14 @@ module Plugin
 
   # Search roll for current or latest libraries.
 
-  def find_roll(match)
+  def find_roll(match, options={})
     plugins = []
+    directory = options[:directory] || DIRECTORY
     if defined?(::Roll)
       ::Roll::Library.ledger.each do |name, lib|
         lib = lib.sort.first if Array===lib
         lib.loadpath.each do |path|
-          find = File.join(lib.location, path, DIRECTORY, match)
+          find = File.join(lib.location, path, directory, match)
           list = Dir.glob(find)
           list = list.map{ |d| d.chomp('/') }
           plugins.concat(list)
@@ -84,10 +101,12 @@ module Plugin
   #
   # Activated gem versions are in here too.
 
-  def find_loadpath(match)
+  def find_loadpath(match, options={})
     plugins = []
+    directory = options[:directory] || DIRECTORY
     $LOAD_PATH.uniq.each do |path|
-      list = Dir.glob(File.join(path, DIRECTORY, match))
+      path = File.expand_path(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)
@@ -99,11 +118,12 @@ module Plugin
   #
   # TODO: Is there anyway to skip active gems?
 
-  def find_gems(match)
+  def find_gems(match, options={})
     plugins = []
+    directory = options[:directory] || DIRECTORY
     if defined?(::Gem)
       ::Gem.latest_load_paths do |path|
-        list = Dir.glob(File.join(path, DIRECTORY, match))
+        list = Dir.glob(File.join(path, directory, match))
         list = list.map{ |d| d.chomp('/') }
         plugins.concat(list)
       end

data/meta/released

@@ -1 +1 @@
-2009-11-20
+2010-02-07

data/meta/version

@@ -1 +1 @@
-1.0
+1.1

data/test/demos/helper.rb

@@ -0,0 +1,3 @@
+# add the fixtures directory to the $LOAD_PATH
+# $:.unshift(File.dirname(File.dirname(__FILE__)) + '/fixtures')
+

data/test/demos/plugins/example.rb

@@ -0,0 +1 @@
+$proof = "plugin loading worked"

data/test/demos/usage.rdoc

@@ -0,0 +1,26 @@
+= Plugin Demonstrandum
+
+To use the Plugin library first we need to require it.
+
+  require 'plugin'
+
+Now use +Plugin.find+ to seach for a file pattern of our
+choosing within the +plugins+ loadpath.
+
+  files = Plugin.find('example.rb')
+  file  = files.first
+
+The +find+ method returns full path names.
+
+  File.expand_path(file).assert == file
+  file.assert.ends_with?('plugins/example.rb')
+
+As with any Ruby script we can require it.
+
+  require file
+
+Our example.rb script defines the global variable $proof.
+We can see that it loaded just fine.
+
+  $proof.assert == "plugin loading worked"
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: plugin
 version: !ruby/object:Gem::Version 
-  version: "1.0"
+  version: "1.1"
 platform: ruby
 authors: 
 - Thomas Sawyer
@@ -9,24 +9,20 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-24 00:00:00 -05:00
+date: 2010-02-07 00:00:00 -05:00
 default_executable: 
 dependencies: []
 
 description: |-
   Plugins is a general purpose plugin handler for Ruby.
   (Note: This has nothing to do with Rails plugins.)
-email: proutils@librelist.com
+email: 
 executables: []
 
 extensions: []
 
-extra_rdoc_files: 
-- README
-- MANIFEST
-- HISTORY
-- Syckfile
-- COPYING
+extra_rdoc_files: []
+
 files: 
 - lib/plugin.rb
 - meta/authors
@@ -43,11 +39,12 @@ files:
 - meta/summary
 - meta/title
 - meta/version
-- README
+- test/demos/helper.rb
+- test/demos/plugins/example.rb
+- test/demos/usage.rdoc
+- README.rdoc
 - HISTORY
 - COPYING
-- MANIFEST
-- Syckfile
 has_rdoc: true
 homepage: http://rubyworks.github.com/plugin
 licenses: []
@@ -56,8 +53,6 @@ post_install_message:
 rdoc_options: 
 - --title
 - Plugin API
-- --main
-- README
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 

data/MANIFEST

@@ -1,19 +0,0 @@
-#!mast -x Syckfile bin lib meta test [A-Z]*
-lib/plugin.rb
-meta/authors
-meta/collection
-meta/contact
-meta/created
-meta/description
-meta/homepage
-meta/license
-meta/name
-meta/released
-meta/repository
-meta/ruby
-meta/summary
-meta/title
-meta/version
-README
-HISTORY
-COPYING

data/Syckfile

@@ -1,25 +0,0 @@
----
-automatic: true
-
-box:
-  types  : [ gem, gz ]
-  include: [ bin, doc, lib, meta, test, "[A-Z]*" ]
-  exclude: [ doc/rdoc, doc/ri ]
-  spec   : true
-
-dnote:
-  priority: -1
-  active  : true
-
-stats:
-  priority: -1
-  active  : true
-
-#ridoc:
-#  exclude: []
-#  active : true
-
-email:
-  mailto : transfire@gmail.com
-  active : true
-