finder 0.1.0

data/.ruby

@@ -0,0 +1,50 @@
+---
+source:
+- ruby.yml
+authors:
+- name: Trans
+  email: transfire@gmail.com
+copyrights:
+- holder: Rubyworks
+  year: '2009'
+  license: BSD-2-Clause
+replacements: []
+alternatives: []
+requirements:
+- name: detroit
+  groups:
+  - build
+  development: true
+- name: qed
+  groups:
+  - test
+  development: true
+- name: ae
+  groups:
+  - test
+  development: true
+dependencies: []
+conflicts: []
+repositories:
+- uri: git://github.com/rubyworks/plugin.git
+  scm: git
+  name: upstream
+resources:
+  home: http://rubyworks.github.com/finder
+  code: http://github.com/rubyworks/finder
+  mail: http://groups.google.com/rubyworks-mailinglist
+extra: {}
+load_path:
+- lib
+revision: 0
+name: finder
+title: Finder
+version: 0.1.0
+summary: Robust library file locator
+created: '2009-11-24'
+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
+  library-based plugin systems.
+organization: rubyworks
+date: '2012-02-11'

data/.yardopts

@@ -0,0 +1,7 @@
+--title Finder
+--output-dir doc
+--private
+--protected
+lib/
+-
+[A-Z]*.*

data/COPYING.rdoc

@@ -0,0 +1,38 @@
+= COPYRIGHT
+
+== NOTICES
+
+=== Finder
+
+Copyright:: (c) 2012 RubyWorks
+License::   (r) BSD-2-Clause
+Website::   http://rubyworks.github.com/finder
+
+== LICENSES
+
+=== BSD-2-Clause License
+
+    Assay
+
+    Copyright (c) 2012 Rubyworks. All rights reserved.
+
+    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.

data/HISTORY.md

@@ -0,0 +1,12 @@
+# RELEASE HISTORY
+
+## 0.1.0 / 2012-02-11
+
+Finder is a new library built from the ashes of the old Plugin gem.
+Along with a new more fitting name, it has more robust and expanded
+capabilites!
+
+Changes:
+
+* Happy Rebirthday!
+

data/README.md

@@ -0,0 +1,46 @@
+# Finder
+
+[Homepage](http://rubyworks.github.com/finder) /
+[Report Issue](http://github.com/rubyworks/finder/issues) /
+[Development](http://github.com/rubyworks/finder) /
+[Mailing List](http://groups.google.com/groups/rubyworks-mailinglist) /
+[IRC Channel](irc://chat.us.freenode.net/rubyworks)
+
+[![Build Status](https://secure.travis-ci.org/rubyworks/finder.png)](http://travis-ci.org/rubyworks/finder)
+
+
+## DESCRIPTION
+
+Finder is a straight-forward file finder for searching Ruby library paths.
+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.
+
+
+## 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.
+
+For example, a common use case is for a pluggable application is to require all
+the finders found in library load paths:
+
+  require 'finder'
+
+  Find.load_path('myapp/*.rb').each do |file|
+    require(file)
+  end
+
+Alternately you might load finders only as needed. For instance, if a command-line
+option calls for it.
+
+
+## COPYRIGHTS
+
+Copyright (c) 2009 Thomas Sawyer
+
+Finder is release under the terms of the **BSD-2-Clause** license.
+
+See COPYING for details.
+

data/demo/applique/ae.rb

@@ -0,0 +1 @@
+require 'ae'

data/demo/applique/helper.rb

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

data/demo/fixtures/example.rb

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

data/demo/load_path.md

@@ -0,0 +1,34 @@
+# Plugin Demonstrandum
+
+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
+choosing within library load paths.
+
+    files = Find.load_path('example.rb')
+    file  = files.first
+
+The +find+ method returns path name relative to the load path.
+
+    file.assert == 'example.rb'
+
+We can use the `aboslute` option to get the full path.
+
+    files = Find.load_path('example.rb', :absolute=>true)
+    file  = files.first
+
+    File.expand_path(file).assert == file
+    file.assert.end_with?('example.rb')
+
+As with any Ruby script we can require it.
+
+    file = Find.load_path('example.rb').first
+    require file
+
+Our example.rb script defines the global variable $proof.
+We can see that it loaded just fine.
+
+    $proof.assert == "plugin loading worked"
+

data/lib/finder.rb

@@ -0,0 +1,28 @@
+require 'finder/find'
+
+module Finder
+
+  # Current version.
+  VERSION = '0.1.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 load_path(match, options={})
+      Find.load_path(match, options)
+    end
+
+    def data_path(match, options={})
+      Find.data_path(match, options)
+    end
+  end
+
+end
+
+# Convenience shortcut.
+Find = Finder::Find
+

data/lib/finder/find.rb

@@ -0,0 +1,84 @@
+require 'finder/roll'
+require 'finder/gem'
+require 'finder/site'
+
+module Finder
+
+  # Find module is the main interface for Finder library.
+  #
+  module Find
+    extend self
+
+    # Find matching paths, searching through Rolled libraries, Gem-installed libraries
+    # and site locations in `$LOAD_PATH` and `RbConfig::CONFIG['datadir']`.
+    #
+    # @param [String] match
+    #   File glob to match against.
+    #
+    # @example
+    #   Find.path('lib/foo/*')
+    #
+    def path(glob, options={})
+      found = []
+      systems.each do |system|
+        found.concat system.path(match, options)
+      end
+      found.uniq
+    end
+
+    # Shortcut for #path.
+    #
+    #   Plugin['syckle/*']
+    #
+    alias_method :[], :path
+
+    # Searching through Rolls, RubyGems and Site locations for matching
+    # load paths.
+    #
+    # @param [String] match
+    #   File glob to match against.
+    #
+    # @example
+    #   Find.load_path('bar/*')
+    #
+    def load_path(match, options={})
+      found = []
+      systems.each do |system|
+        found.concat system.load_path(match, options)
+      end
+      found.uniq
+    end
+
+    # Searching through Rolls, RubyGems and Site locations for matching
+    # data paths.
+    #
+    # @param [String] match
+    #   File glob to match against.
+    #
+    # @example
+    #   Find.data_path('bar/*')
+    #
+    def data_path(glob)
+      found = []
+      systems.each do |system|
+        found.concat system.data_path(match, options)
+      end
+      found.uniq
+    end
+
+    #
+    # List of supported library management systems.
+    #
+    def systems
+      @systems ||= (
+        systems = []
+        systems << Roll if defined?(::Library)
+        systems << Gem  if defined?(::Gem)
+        systems << Site
+        systems
+      )
+    end
+
+  end
+
+end

data/lib/finder/gem.rb

@@ -0,0 +1,126 @@
+module Finder
+  module Find
+
+    # RubyGems finder methods.
+    #
+    module Gem
+      extend self
+
+      #
+      # Search gems.
+      #
+      # @param [String] match
+      #   The file glob to match.
+      #
+      # @param [Hash] options
+      #   Search options.
+      #
+      # @return [Array<String>] List of absolute paths.
+      #
+      def path(match, options={})
+        matches = []
+        ::Gem::Specification.current_specs.each do |spec|
+          list = []
+          glob = File.join(spec.full_gem_path, match)
+          list = Dir[glob] #.map{ |f| f.untaint }
+          list = list.map{ |d| d.chomp('/') }
+          matches.concat(list)
+          # activate the library if activate flag
+          lib.activate if options[:activate] && !list.empty?
+        end
+        matches
+      end
+
+      #
+      # Search gem load paths.
+      #
+      # @param [String] match
+      #   The file glob to match.
+      #
+      # @param [Hash] options
+      #   Search options.
+      #
+      # @option options [true,false] :absolute
+      #   Return absolute paths instead of relative to load path.
+      #
+      # @option options [true,false] :activate
+      #   Activate the gems if it has matching files.
+      #
+      # @return [Array<String>] List of paths.
+      #
+      def load_path(match, options={})
+        matches = []
+        ::Gem::Specification.current_specs.each do |spec|
+          list = []
+          spec.require_paths.each do |path|
+            glob = File.join(spec.full_gem_path, path, match)
+            list = Dir[glob] #.map{ |f| f.untaint }
+            list = list.map{ |d| d.chomp('/') }
+            # return relative paths unless absolute flag
+            if 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
+            matches.concat(list)
+          end
+          # activate the library if activate flag
+          lib.activate if options[:activate] && !list.empty?
+        end
+        matches
+      end
+
+      #
+      # Search gem data paths.
+      #
+      # @param [String] match
+      #   The file glob to match.
+      #
+      # @param [Hash] options
+      #   Search options.
+      #
+      # @return [Array<String>] List of absolute paths.
+      #
+      def data_path(match, options={})
+        matches = []
+        ::Gem::Specification.current_specs.each do |spec|
+          list = []
+          glob = File.join(spec.full_gem_path, 'data', match)
+          list = Dir[glob] #.map{ |f| f.untaint }
+          list = list.map{ |d| d.chomp('/') }
+          matches.concat(list)
+          # activate the library if activate flag
+          lib.activate if options[:activate] && !list.empty?
+        end
+        matches
+      end
+
+    end
+
+  end
+end
+
+
+module Gem
+
+  # Gem::Specification is extended to support `current_specs` method.
+  class Specification
+
+    # Return a list of active specs or latest version of spec if not active.
+    def self.current_specs
+      named = Hash.new{|h,k| h[k] = [] }
+      each{ |spec| named[spec.name] << spec }
+      list = []
+      named.each do |name, vers|
+        if spec = vers.find{ |s| s.activated? }
+          list << spec
+        else
+          spec = vers.max{ |a,b| a.version <=> b.version }
+          list << spec
+        end
+      end
+      return list
+    end
+
+  end
+
+end

data/lib/finder/roll.rb

@@ -0,0 +1,87 @@
+module Finder
+  module Find
+
+    # Library finder methods.
+    #
+    module Roll
+      extend self
+
+      #
+      # Search for current or latest files within a library.
+      #
+      # @param [String] match
+      #   The file glob to match.
+      #
+      # @param [Hash] options
+      #   Search options.
+      #
+      # @return [Array<String>] List of paths.
+      #
+      def path(match, options={})
+        return [] unless defined?(::Library)
+        matches = []
+        ::Library.ledger.each do |name, lib|
+          lib  = lib.sort.first if Array===lib
+          find = File.join(lib.location, match)
+          list = Dir.glob(find)
+          list = list.map{ |d| d.chomp('/') }
+          matches.concat(list)
+        end
+        matches
+      end
+
+      #
+      # Search Roll system for current or latest library files. This is useful
+      # for plugin loading.
+      #
+      # This only searches activated libraries or the most recent version
+      # of any given library.
+      #
+      # @param [String] match
+      #   The file glob to match.
+      #
+      # @param [Hash] options
+      #   Search options.
+      #
+      # @option options [true,false] :absolute
+      #   Return absolute paths instead of relative to load path.
+      #
+      # @option options [true,false] :activate
+      #   Activate the library if it has matching files.
+      #
+      # @return [Array<String>] List of paths.
+      #
+      def load_path(match, options={})
+        matches = []
+        ::Library.ledger.each do |name, lib|
+          list = []
+          lib  = lib.sort.first if Array===lib
+          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]
+              # 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
+            matches.concat(list)
+          end
+          # activate the library if activate flag
+          lib.activate if options[:activate] && !list.empty?
+        end
+        matches
+      end
+
+      ## Search rolls for current or latest libraries.
+      ##
+      ##def load_path(match, options={})
+      #  return [] unless defined?(::Library)
+      #  #::Library.search_latest(match)
+      #  ::Library.find_files(match)
+      #end
+
+    end
+
+  end
+end

data/lib/finder/site.rb

@@ -0,0 +1,72 @@
+require 'rbconfig'
+
+module Finder
+  module Find
+
+    # System location finder methods.
+    #
+    module Site
+      extend self
+
+      DATA_PATH = RbConfig::CONFIG['datadir']
+
+      #
+      # Search load path for matching patterns.
+      #
+      # @param [String] match
+      #   The file glob to match.
+      #
+      # @param [Hash] options
+      #   Search options.
+      #
+      # @return [Array<String>] List of paths.
+      #    
+      def path(match, options={})
+        found = []
+        $LOAD_PATH.uniq.map do |path|
+          list = Dir.glob(File.join(File.expand_path(path), match))
+          list = list.map{ |d| d.chomp('/') }
+          found.concat(list)
+        end
+        found.concat(data_path(match, options))
+        found
+      end
+
+      # Search load path for matching patterns.
+      #
+      # @param [String] match
+      #   The file glob to match.
+      #
+      # @param [Hash] options
+      #   Search options.
+      #   
+      # @option options [true,false] :absolute
+      #   Return absolute paths instead of relative to load path.
+      #
+      # @return [Array<String>] List of paths.
+      #
+      def load_path(match, options={})
+        found = []
+        $LOAD_PATH.uniq.map 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]
+            # the extra '' in File.join adds a '/' to the end of the path
+            list = list.map{ |f| f.sub(File.join(path, ''), '') }
+          end
+          found.concat(list)
+        end
+        found
+      end
+
+      # Search data path.
+      #
+      def data_path(match, options={})
+        Dir.glob(File.join(DATA_PATH, match)).uniq
+      end
+
+    end
+
+  end
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: finder
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Trans
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-02-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: detroit
+  requirement: &20870760 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *20870760
+- !ruby/object:Gem::Dependency
+  name: qed
+  requirement: &20870140 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *20870140
+- !ruby/object:Gem::Dependency
+  name: ae
+  requirement: &20869620 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *20869620
+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
+  library-based plugin systems.
+email:
+- transfire@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- COPYING.rdoc
+- HISTORY.md
+- README.md
+files:
+- .ruby
+- .yardopts
+- demo/applique/ae.rb
+- demo/applique/helper.rb
+- demo/fixtures/example.rb
+- demo/load_path.md
+- lib/finder/find.rb
+- lib/finder/gem.rb
+- lib/finder/roll.rb
+- lib/finder/site.rb
+- lib/finder.rb
+- HISTORY.md
+- README.md
+- COPYING.rdoc
+homepage: http://rubyworks.github.com/finder
+licenses:
+- BSD-2-Clause
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: Robust library file locator
+test_files: []