finder 0.2.1 → 0.3.0

data/.ruby

@@ -29,16 +29,23 @@ repositories:
   scm: git
   name: upstream
 resources:
-  home: http://rubyworks.github.com/finder
-  code: http://github.com/rubyworks/finder
-  mail: http://groups.google.com/rubyworks-mailinglist
+- uri: http://rubyworks.github.com/finder
+  label: Website
+  type: home
+- uri: http://github.com/rubyworks/finder
+  label: Source Code
+  type: code
+- uri: http://groups.google.com/rubyworks-mailinglist
+  label: Mailing List
+  type: mail
+categories: []
 extra: {}
 load_path:
 - lib
 revision: 0
 name: finder
 title: Finder
-version: 0.2.1
+version: 0.3.0
 summary: Robust library file locator
 created: '2009-11-24'
 description: Finder is a general purpose file finder for Ruby. Finder can search RubyGems,
@@ -46,4 +53,4 @@ description: Finder is a general purpose file finder for Ruby. Finder can search
   active or the most current library files. It is especially useful for implementing
   library-based plugin systems.
 organization: rubyworks
-date: '2012-03-14'
+date: '2012-05-22'

data/HISTORY.md

@@ -1,9 +1,25 @@
 # RELEASE HISTORY
 
+## 0.3.0 / 2012-05-22
+
+This is a significant release in that the behavior of `Find.load_path` has
+changed to return absolute paths by default. To get relative paths set
+the `:relative` options to `true`. However, if you are doing that you
+likely want to use the new `Find.feature` method which specifically searches
+for requirable files and returns relative paths by default.
+
+Changes:
+
+* Find.load_path now returns absolute paths by default.
+* Adds option `:relative=>true` to get relative paths.
+* Adds new `Find.feature` for finding requirable files.
+* New Base module provides shared methods to all systems.
+
+
 ## 0.2.1 / 2012-03-15
 
 Fix Gem finder so that is places spec in Array, and catches
-error is gem is not found.
+error if gem is not found.
 
 Changes:
 

data/LICENSE.txt

@@ -0,0 +1,31 @@
+Finder
+
+Copyright (c) 2012 Rubyworks. All rights reserved.
+
+License (spdx) BSD-2-Clause
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+
+   2. 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.
+
+THIS SOFTWARE IS PROVIDED ``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 HOLDERS 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.
+
+-----
+* http://rubyworks.github.com/finder
+* http://spdx.com/licenses/BSD-2_clause
+

data/README.md

@@ -19,21 +19,27 @@ $LOAD_PATH manually.
 
 ## INSTRUCTION
 
-To find finders, simply provide a glob to the appropriate Finder function,
-and it will return all matches found within current and/or most recent versions
-of a library.
+To find paths, simply provide a glob to the appropriate Finder function,
+and it will return all matches found within current or most recent
+versions of a library.
 
-For example, a common use case is for a plugin-in enabled application is to require all
-the finders found in library load paths:
+For example, a common use case for plug-in enabled application is to
+require all the files found in library load paths:
 
     require 'finder'
 
-    Find.load_path('myapp/*.rb').each do |file|
+    Find.feature('myapp/*').each do |file|
       require(file)
     end
 
-Alternately you might load finders only as needed. For instance, if a command-line
-option calls for it.
+This is basically equivalent to:
+
+    Find.load_path('myapp/*.rb', :relative=>true).each do |file|
+      require(file)
+    end
+
+Alternately you might load files only as needed. For instance, if a
+command-line option calls for it.
 
 
 ## COPYRIGHTS

data/demo/00_intro.md

@@ -0,0 +1,6 @@
+# Finder
+
+To use the Finder library first we need to require it.
+
+    require 'finder'
+

data/demo/{load_path.md → 01_load_path.md}

@@ -1,13 +1,9 @@
-# Plugin Demonstrandum
+# Load Path Lookup
 
-To use the Finder library first we need to require it.
-
-    require 'finder'
-
-Now use +Find.load+path+ to seach for a file pattern of our
+Use +Find.load_path+ to search for a file pattern of our
 choosing within library load paths.
 
-    files = Find.load_path('example.rb')
+    files = Find.load_path('example.rb', :relative=>true)
     file  = files.first
 
 The +find+ method returns path name relative to the load path.

data/demo/02_feature.md

@@ -0,0 +1,21 @@
+# Feature Lookup
+
+We can use +Find.feature+ to seach for requireable files from within
+library load paths. The `feature` method returns relatvie paths
+by default and automatically handles extensions --just like `require`.
+
+    files = Find.feature('example')
+    file  = files.first
+
+The +find+ method returns path name relative to the load path.
+
+    file.assert == 'example.rb'
+
+We can use the `realtive` or `aboslute` options to get the full path.
+
+    files = Find.feature('example', :absolute=>true)
+    file  = files.first
+
+    File.expand_path(file).assert == file
+    file.assert.end_with?('example.rb')
+

data/demo/applique/helper.rb

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

data/lib/finder.rb

@@ -3,26 +3,36 @@ require 'finder/find'
 module Finder
 
   # Current version.
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 
   # Clean module that can be included elsewhere, to proved #path, #load_path
   # and #data_path methods without including the Gem, Roll, and Site constants.
+  #
   module Findable
     def path(match, options={})
       Find.path(match, options)
     end
 
+    def data_path(match, options={})
+      Find.data_path(match, options)
+    end
+
     def load_path(match, options={})
       Find.load_path(match, options)
     end
 
-    def data_path(match, options={})
-      Find.data_path(match, options)
+    def require_path(match, options={})
+      Find.require_path(match, options)
+    end
+
+    def feature(match, options={})
+      Find.feature(match, options)
     end
   end
 
 end
 
-# Convenience shortcut.
-Find = Finder::Find
+module Find
+  extend Finder::Find
+end
 

data/lib/finder/base.rb

@@ -0,0 +1,69 @@
+module Finder
+  module Find
+
+    # Base module provides helper methods to other
+    # finders.
+    #
+    module Base
+
+      #
+      # When included into a module, that module is atuomatically
+      # self extended.
+      #
+      def self.included(mod)
+        mod.extend(mod)
+      end
+
+      ##
+      ## Like #load_path but searches only for requirable files.
+      ##
+      ## NOTE: This may be somewhat limited at the moment until we
+      ## figure out how best to determine all possible extensions.
+      ##
+      #def require_path(match, options={})
+      #  match = append_extensions(match, options)
+      #  load_path(match, options)
+      #end
+
+      #
+      # Like #load_path but searches only for requirable feature files
+      # and returns relative paths by default.
+      #
+      def feature(match, options={})
+        options[:relative] = true unless options.key?(:relative) or options.key?(:absolute)
+        match = append_extensions(match, options)
+        load_path(match, options)
+      end
+
+    private
+
+      #
+      # Validate and normalize load options.
+      #
+      # @param [Hash] options
+      #
+      def valid_load_options(options)
+        if options.key?(:relative) && options.key?(:absolute)
+          raise ArgumentError, "must be either relative or absolute" unless options[:relative] ^ options[:absolute]
+        end
+
+        options[:relative] = false if options[:absolute]
+
+        options
+      end
+
+      #
+      # Append requirable extensions to match glob.
+      #
+      #
+      def append_extensions(match, options={})
+        unless Find::EXTENSIONS.include?(File.extname(match))
+          match = match + '{' + Find::EXTENSIONS.join(',') + '}'
+        end
+        match
+      end
+
+    end
+
+  end
+end

data/lib/finder/find.rb

@@ -1,3 +1,5 @@
+require 'rbconfig'
+require 'finder/base'
 require 'finder/roll'
 require 'finder/gem'
 require 'finder/site'
@@ -9,6 +11,9 @@ module Finder
   module Find
     extend self
 
+    # TODO: expand on extensions
+    EXTENSIONS = %w{.rb .rbx .so}
+
     # Find matching paths, searching through Rolled libraries, Gem-installed libraries
     # and site locations in `$LOAD_PATH` and `RbConfig::CONFIG['datadir']`.
     #
@@ -28,12 +33,27 @@ module Finder
 
     # Shortcut for #path.
     #
-    #   Plugin['syckle/*']
+    #   Find['lib/foo/*']
     #
     alias_method :[], :path
 
-    # Searching through Rolls, RubyGems and Site locations for matching
-    # load paths.
+    # Searching through all systems for matching data paths.
+    #
+    # @param [String] match
+    #   File glob to match against.
+    #
+    # @example
+    #   Find.data_path('bar/*')
+    #
+    def data_path(match, options={})
+      found = []
+      systems.each do |system|
+        found.concat system.data_path(match, options)
+      end
+      found.uniq
+    end
+
+    # Searching through all systems for matching load paths.
     #
     # @param [String] match
     #   File glob to match against.
@@ -49,19 +69,34 @@ module Finder
       found.uniq
     end
 
-    # Searching through Rolls, RubyGems and Site locations for matching
-    # data paths.
+    ## Searching through all systems for matching load paths.
+    ##
+    ## @param [String] match
+    ##   File glob to match against.
+    ##
+    ## @example
+    ##   Find.require_path('bar/*')
+    ##
+    #def require_path(match, options={})
+    #  found = []
+    #  systems.each do |system|
+    #    found.concat system.require_path(match, options)
+    #  end
+    #  found.uniq
+    #end
+
+    # Searching through all systems for matching requirable feature files.
     #
     # @param [String] match
     #   File glob to match against.
     #
     # @example
-    #   Find.data_path('bar/*')
+    #   Find.feature('ostruct')
     #
-    def data_path(match, options={})
+    def feature(match, options={})
       found = []
       systems.each do |system|
-        found.concat system.data_path(match, options)
+        found.concat system.feature(match, options)
       end
       found.uniq
     end

data/lib/finder/gem.rb

@@ -4,7 +4,7 @@ module Finder
     # RubyGems finder methods.
     #
     module Gem
-      extend self
+      include Base
 
       #
       # Search gems.
@@ -57,6 +57,8 @@ module Finder
       # @return [Array<String>] List of paths.
       #
       def load_path(match, options={})
+        options = valid_load_options(options)
+
         specs = specifications(options)
 
         matches = []
@@ -67,7 +69,7 @@ module Finder
             list = Dir[glob] #.map{ |f| f.untaint }
             list = list.map{ |d| d.chomp('/') }
             # return relative paths unless absolute flag
-            if not options[:absolute]
+            if options[:relative] #not options[:absolute]
               # the extra '' in File.join adds a '/' to the end of the path
               list = list.map{ |f| f.sub(File.join(spec.full_gem_path, path, ''), '') }
             end
@@ -108,17 +110,20 @@ module Finder
 
     private
 
+      #
       def specifications(options)
         name = options[:from] || options[:gem]
         if name
+          criteria = [options[:version]].compact
           begin
-            specs = [::Gem::Specification.find_by_name(name.to_s)]
+            specs = [::Gem::Specification.find_by_name(name.to_s, *criteria)]
           rescue ::Gem::LoadError
-            return []
+            specs = []
           end
         else
-          ::Gem::Specification.current_specs
+          specs = ::Gem::Specification.current_specs
         end
+        return specs
       end
 
     end

data/lib/finder/roll.rb

@@ -1,10 +1,10 @@
 module Finder
   module Find
 
-    # Library finder methods.
+    # Finder methods for `Library` system.
     #
     module Roll
-      extend self
+      include Base
 
       #
       # Search for current or latest files within a library.
@@ -26,10 +26,18 @@ module Finder
           ledger = ::Library.ledger
         end
 
-        matches = []
+        criteria = [options[:version]].compact
+        matches  = []
 
         ledger.each do |name, lib|
-          lib  = lib.sort.first if Array===lib
+          if Array === lib
+            lib = lib.select do |l|
+              criteria.all?{ |c| l.version.satisfy?(c) }
+            end
+            lib = lib.sort.first
+          else
+            next unless criteria.all?{ |c| l.version.satisfy?(c) }
+          end
           find = File.join(lib.location, match)
           list = Dir.glob(find)
           list = list.map{ |d| d.chomp('/') }
@@ -62,24 +70,43 @@ module Finder
       #
       def load_path(match, options={})
         return [] unless defined?(::Library)
+        options = valid_load_options(options)
 
         if from = options[:from]
-          ledger = {from.to_s => ::Library.ledger[from.to_s]}
+          libs = ::Library.ledger[from.to_s]
+          if libs
+            case libs
+            when ::Array
+              ledger = libs.empty? ? {} : {from.to_s => libs}
+            else
+              ledger = {from.to_s => libs}
+            end
+          else
+            ledger = {}
+          end
         else
           ledger = ::Library.ledger
         end
 
+        criteria = [options[:version]].compact
         matches = []
 
         ledger.each do |name, lib|
           list = []
-          lib  = lib.sort.first if Array===lib
+          if Array===lib
+            lib = lib.select do |l|
+              criteria.all?{ |c| l.version.satisfy?(c) }
+            end
+            lib = lib.sort.first
+          else
+            next unless criteria.all?{ |c| lib.version.satisfy?(c) }
+          end
           lib.loadpath.each do |path|
             find = File.join(lib.location, path, match)
             list = Dir.glob(find)
             list = list.map{ |d| d.chomp('/') }
-            # return relative load path unless absolte flag
-            if not options[:absolute]
+            # return relative load path unless absolute flag
+            if options[:relative]
               # the extra '' in File.join adds a '/' to the end of the path
               list = list.map{ |f| f.sub(File.join(lib.location, path, ''), '') }
             end
@@ -100,6 +127,9 @@ module Finder
       #  ::Library.find_files(match)
       #end
 
+      #
+      # Search project's data paths.
+      #
       def data_path(match, options={})
         return [] unless defined?(::Library)
 
@@ -109,11 +139,19 @@ module Finder
           ledger = ::Library.ledger
         end
 
+        criteria = [options[:version]].compact
         matches = []
 
         ledger.each do |name, lib|
           list = []
-          lib  = lib.sort.first if Array===lib
+          if Array === lib
+            lib = lib.select do |l|
+              criteria.all?{ |c| l.version.satisfy?(c) }
+            end
+            lib = lib.sort.first
+          else
+            next unless criteria.all?{ |c| l.version.satisfy?(c) }
+          end
           find = File.join(lib.location, 'data', match)
           list = Dir.glob(find)
           list = list.map{ |d| d.chomp('/') }

data/lib/finder/site.rb

@@ -1,13 +1,14 @@
-require 'rbconfig'
-
 module Finder
   module Find
 
     # System location finder methods.
     #
     module Site
-      extend self
+      include Base
 
+      #
+      # System's data path.
+      #
       DATA_PATH = RbConfig::CONFIG['datadir']
 
       # TODO: Might this support `:from` option via
@@ -23,7 +24,7 @@ module Finder
       #   Search options.
       #
       # @return [Array<String>] List of paths.
-      #    
+      #
       def path(match, options={})
         return [] if options[:from]
 
@@ -37,6 +38,7 @@ module Finder
         found
       end
 
+      #
       # Search load path for matching patterns.
       #
       # @param [String] match
@@ -44,7 +46,7 @@ module Finder
       #
       # @param [Hash] options
       #   Search options.
-      #   
+      #
       # @option options [true,false] :absolute
       #   Return absolute paths instead of relative to load path.
       #
@@ -53,12 +55,14 @@ module Finder
       def load_path(match, options={})
         return [] if options[:from]
 
+        options = valid_load_options(options)
+
         found = []
-        $LOAD_PATH.uniq.map do |path|
+        $LOAD_PATH.uniq.each do |path|
           list = Dir.glob(File.join(File.expand_path(path), match))
           list = list.map{ |d| d.chomp('/') }
-          # return relative load path unless absolute flag
-          if not options[:absolute]
+          # return absolute path unless relative flag
+          if options[:relative]
             # the extra '' in File.join adds a '/' to the end of the path
             list = list.map{ |f| f.sub(File.join(path, ''), '') }
           end
@@ -67,6 +71,7 @@ module Finder
         found
       end
 
+      #
       # Search data path.
       #
       def data_path(match, options={})

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: finder
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-15 00:00:00.000000000 Z
+date: 2012-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: detroit
-  requirement: &30903600 !ruby/object:Gem::Requirement
+  requirement: &28070020 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *30903600
+  version_requirements: *28070020
 - !ruby/object:Gem::Dependency
   name: qed
-  requirement: &30903060 !ruby/object:Gem::Requirement
+  requirement: &28069460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *30903060
+  version_requirements: *28069460
 - !ruby/object:Gem::Dependency
   name: ae
-  requirement: &30918840 !ruby/object:Gem::Requirement
+  requirement: &28068940 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *30918840
+  version_requirements: *28068940
 description: Finder is a general purpose file finder for Ruby. Finder can search RubyGems,
   Roll libraries and Ruby's standard $LOAD_PATH and system data directory for the
   active or the most current library files. It is especially useful for implementing
@@ -53,20 +53,25 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files:
+- LICENSE.txt
 - HISTORY.md
 - README.md
 files:
 - .ruby
 - .yardopts
+- demo/00_intro.md
+- demo/01_load_path.md
+- demo/02_feature.md
 - demo/applique/ae.rb
 - demo/applique/helper.rb
 - demo/fixtures/example.rb
-- demo/load_path.md
+- lib/finder/base.rb
 - lib/finder/find.rb
 - lib/finder/gem.rb
 - lib/finder/roll.rb
 - lib/finder/site.rb
 - lib/finder.rb
+- LICENSE.txt
 - HISTORY.md
 - README.md
 homepage: http://rubyworks.github.com/finder