loadable 1.2.0

data/README.md

@@ -0,0 +1,192 @@
+# Loadable
+
+## 1 Overview
+
+| Project      | Loadable                                                 |
+|--------------|----------------------------------------------------------|
+| Author       | Thomas Sawyer                                            |
+| License      | BSD-2-Clause                                             |
+| Copyright    | (c) 2010 Thomas Sawyer                                   |
+| Website      | http://github.com/rubyworks/loadable                     |
+| Development  | http://github.com/rubyworks/loadable                     |
+| Mailing-List | http://groups.google.com/group/rubyworks-mailinglist     |
+
+
+## 2 Description
+
+The Loadable gem provides a more robust and convenient means of augmenting
+Ruby's load system, namely the `load` and `require` methods. Rather than
+alias and override these methods, Loadable keeps a list of *load wedges*
+that control the routing of require and load calls.
+
+In addition, the Loadable gem includes two pre-made load wedges that can be
+used to prevent name clashes between Ruby's standard library and gem packages
+(see INFRACTIONS.rdoc for more on this). There is also a load wedge for
+for developers to make it trivial to make vendored sub-projects loadable.
+
+
+## 3 Usage
+
+### 3.1 Installation
+
+Installing via RubyGems follows the usual pattern.
+
+    $ gem install loadable
+
+To automatically load both the Gem and Ruby wedges, and the entire Loadable
+system, add `loadable` to your RUBYOPT environment variable.
+
+    $ export RUBYOPT="-rloadable"
+
+Place this in your shell's configuration file, such as `~/.bashrc`.
+
+If you do not want the default setup you can `require 'loadable/system'` instead.
+This will load in Loadable system, but only add an `OriginalLoader` to the
+`$LOADERS` list, leaving off the Ruby and Gem loaders.
+
+### 3.2 Custom Loaders
+
+Loadable was written initially to provide the specific capability of loading
+Ruby standard libraries without potential interference from libraries
+installed via RubyGems (see INFRACTIONS.rdoc). The code ultimately evolved
+into a more generic tool, useful for writing any kind of plug-in load
+router. 
+
+The code for the Ruby wedge serves as a good example of writing a load wedge.
+(Note this is leaves out a few details of the real class for simplicity sake.)
+
+    require 'rbconfig'
+    require 'loadable/mixin'
+
+    class Loadable::RubyLoader
+      include Loadable
+
+      LOCATIONS = ::RbConfig::CONFIG.values_at(
+        'rubylibdir', 'archdir', 'sitelibdir', 'sitearchdir'
+      )
+
+      def call(fname, options={})
+        return unless options[:from].to_s == 'ruby'
+        LOCATIONS.each do |loadpath|
+          if path = lookup(loadpath, fname, options)
+            return super(path, options)
+          end
+        end
+        raise_load_error(fname)
+      end
+
+      def each(options={}, &block)
+        LOCATIONS.each do |loadpath|
+          traverse(loadpath, &block)
+        end
+      end
+    end
+
+To put this loader into action we simply need to register it with the Loadable 
+domain.
+
+    Loadable.register(Loadable::RubyLoader.new)
+
+Under the hood, this simply appends the instance to the `$LOADERS` global variable.
+
+Loaders, also called load wedges, are easy to write as their interface is very
+simple. Any object the responds to #call, taking parameters of 
+<code>(fname, options={})</code>, can be used as a load wedge. A load wedge
+should also support `#each(options={}, &block)` which is used to iterate over
+all requirable files a loader supports.
+
+The `Loadable` mixin is just a convenience module that makes writing loaders
+a bit easier. Load wedges can be written without it, however the mixin
+provides a few methods that are often useful to any load wedge. An example is
+the `lookup` method used in the above example, which will search a
+load path in accordance with the Ruby's built-in require and load lookup
+procedures, i.e. automatically trying defualt extensions like `.rb`.
+
+You might wonder how the single method, `#call`, handles both load and require
+operations. The secret is in the `options` hash. If <code>options[:load]</code>
+resolves to true, then it is a *load* operation, otherwise it is a *require*
+operation. The `$LOADERS` global variable is iterated over in order.
+When `#load` or `#require` is called each wedge is tried in turn. The return
+value of `#call` controls how this loop proceeds. If the return value is `true`
+then the load was successful, and the loop can break. If it is `false` it means
+the loading has already been handled and the loop can also break. But if the
+return value is `nil`, it means the wedge does not apply and the loop should
+continue. If all wedges have been tried and all have returned `nil` then it
+falls back to the original `#load` and `#require` calls, via an instance
+`OriginalLoader` which should always be the last loader in the `$LOADERS` list.
+
+
+## 4 Built-in Loaders
+
+The Loadable gem provides three special loaders out-of-the-box, the `RubyLoader`,
+the `GemLoader` and the `VendorLoader`. The first two are probably not exaclty
+what you think they are, going just by their names, so keep reading...
+
+### 4.1 RubyLoader
+
+The Ruby wedge makes it possible to load a Ruby standard library without
+interference from installed gems or other package systems. It does this by 
+checking for a `:from` option passed to the require or load methods.
+
+    require 'ostruct', :from=>'ruby'
+
+This will load the `ostruct.rb` script from the Ruby standard library regardless
+of whether someone else dropped an `ostruct.rb` file in their project's `lib/`
+directory without understanding the potential consequences.
+
+### 4.2 GemLoader
+
+The Gem wedge is similar to the Ruby wedge, in that it isolates the loading
+of a gem's files from other gems.
+
+    gem 'facets', '~>2.8'
+
+    require 'string/margin', :from=>'facets'
+
+With this we can be sure that 'facets/string/margin' was loaded from the Facets
+library regardless of whether some other gem has a 'facets/string/margin' file
+in its `lib/` directory. If no gem has this file, it will fallback to the 
+remaining loaders. However, if we use the `:gem` options instead, it will 
+raise a load error.
+
+    require 'string/does_not_exit', :gem=>'facets'
+
+The Gem wedge also supports version constraints, so you do not have to use 
+`gem()` method for one off requires from a given gem.
+
+    require 'string/margin', :from=>'facets', :version=>'~>2.8'
+
+### 4.3 VendorLoader
+
+The Vendor wedge is used to add vendored projects to the load system.
+This is especially useful for development. Vendored projects can be added
+in two ways, by registering an instance of VendorLoader, e.g.
+
+    Loadable.register Loadable::VendorLoader.new('vendor/*')
+
+Or using the dedicated `Loadable.vendor(*dir)` method that Loadable provides
+to make this more convenient.
+
+    Loadable.vendor('vendor/*')
+
+
+## 5 Development
+
+Source code for Loadbable is hosted by [GitHub](http://github.com/rubyworks/loadable).
+
+If you has come across and issues, we encourage you to fork the repository and 
+submit a pull request with the fix. When submitting a pull request, it is best
+if the changes are orgnanized into a new topic branch.
+
+If you don't have time to code up patches yourself, please do not hesitate to
+simply report the issue on the [issue tracker](http://github.com/rubyworks/loadable/issues).
+
+
+## 6 Copyrights
+
+Copyright (c) 2010 Thomas Sawyer, Rubyworks
+
+Load is distributed under the terms of the **FreeBSD** license.
+
+See COPYING.rdoc file for details.
+

data/lib/loadable/class_require.rb

@@ -0,0 +1,10 @@
+class Module
+  def module_require(child)
+    child = child.to_s.gsub('::','/').downcase
+    path  = name.to_s.gsub('::','/').downcase
+    path  = File.join(path, child)
+    require_relative(path)
+  end
+  alias_mehtod :class_require, :module_require
+end
+

data/lib/loadable/core_ext/rubygems.rb

@@ -0,0 +1,81 @@
+module Gem
+
+  # TODO: Below are two implementations of the same feature. Currently
+  # we are using `Gem.search` code which calls `Gem::Specification.current_specs`.
+  # Possibly this could be replaced by simply calling `GemPathSearcher.current_files`.
+  # Hoverver, it is unclear to me at this time which is the best course of action.
+
+  # Search RubyGems for matching paths in current gem versions.
+  def self.search(fname, options={})
+    return unless defined?(::Gem)
+    matches = []
+    Gem::Specification.current_specs.each do |spec|
+      glob = File.join(spec.lib_dirs_glob, match)
+      list = Dir[glob] #.map{ |f| f.untaint }
+      list = list.map{ |d| d.chomp('/') }
+      matches.concat(list)
+    end
+    matches
+  end
+
+  class Specification
+    # Return a list of actives specs, or latest version 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
+
+    # Return full path of requireable file path given relative path.
+    def find_requirable_file(file)
+      root = full_gem_path
+
+      require_paths.each do |lib|
+        base = "#{root}/#{lib}/#{file}"
+        Gem.suffixes.each do |suf|
+          path = "#{base}#{suf}"
+          return path if File.file? path
+        end
+      end
+
+      return nil
+    end
+  end
+
+=begin
+  class GemPathSearcher
+    # Return a list of matching files among active or latest gems.
+    def current_files(glob)
+      matches  = {}
+      gemspecs = init_gemspecs
+
+      # loaded specs
+      gemspecs.each do |spec|
+        next unless spec.loaded?
+        next if matches.key?(spec.name)
+        files = matching_files(spec, glob)
+        matches[spec.name] = files
+      end
+
+      # latest specs
+      gemspecs.each do |spec|
+        next if matches.key?(spec.name)
+        files = matching_files(spec, glob)
+        matches[spec.name] = files
+      end
+
+      matches.values.flatten.uniq
+    end
+  end
+=end
+
+end

data/lib/loadable/domain.rb

@@ -0,0 +1,64 @@
+module Loadable
+
+  # Stores active loaders.
+  $LOADERS = []
+
+  # Require/load script.
+  #
+  # @param [String] fname
+  #   The script to require/load.
+  #
+  def self.call(fname, options={})
+    success = nil
+    $LOADERS.each do |wedge| 
+      success = wedge.call(fname, options)
+      break unless success.nil?
+    end
+    return success
+  end
+
+  # Iterate over all requirable files.
+  #
+  #   LoadSystem.each{ |file| p file }
+  #
+  # Note that esoteric load wedges may return a symbolic path rather than
+  # an actual file path.
+  #
+  def self.each(options={}, &block)
+    $LOADERS.each do |wedge| 
+      wedge.each(options, &block)
+    end
+  end
+
+  # Search wedges for all matching paths.
+  #
+  #   LoadSystem.search('detroit-*.rb')
+  #
+  # Note that "esoteric" wedges might return a symbolic identifier rather
+  # than an actual file path.
+  #
+  # TODO: Handle default ruby extensions in search.
+  def self.search(glob, options={}, &criteria)
+    matches = []
+    $LOADERS.each do |wedge| 
+      wedge.each do |path|
+        next unless criteria.call(path) if criteria
+        matches << path if File.fnmatch?(glob, path.to_s)  # TODO: add `options[:flags].to_i` ?
+      end
+    end
+    matches
+  end
+
+  # Vendor location.
+  #
+  def self.vendor(*directory)
+    $LOADERS.unshift(VendorLoader.new(*directory))
+  end
+
+  # Add a loader to the $LOADERS global variable.
+  #
+  def self.register(loader)
+    $LOADERS.unshift(loader)
+  end
+
+end

data/lib/loadable/kernel.rb

@@ -0,0 +1,35 @@
+module Kernel
+
+  # Aliases for original load and require.
+  alias_method :load0,    :load
+  alias_method :require0, :require
+
+  # TODO: I am not certain `:load` is the best name for this option.
+  # Something like `:eval` is more meaningful. OTOH, we could flip
+  # it about and use `:feature` or `:cache` to mean the opposite.
+
+  #
+  def require(fname, options={})
+    options[:load] = false unless options.key?(:load)
+    Loadable.call(fname, options)
+    #success = LoadSystem.require(fname, options)
+    #if success.nil?
+    #  success = require_without_wedge(fname)
+    #end
+    #success
+  end
+
+  #
+  def load(fname, options={})
+    options = Hash===options ? options : {:wrap=>options}
+    options[:load] = true unless options.key?(:load)
+    Loadable.call(fname, options)
+    #success = LoadSystem.load(fname, options)
+    #if success.nil?
+    #  success = load_without_wedge(fname)
+    #end
+    #success
+  end
+
+end
+

data/lib/loadable/loaders/gem_loader.rb

@@ -0,0 +1,98 @@
+# TODO: Support colon notation again ?
+
+# TODO: If :gem AND :from options are given, perhaps try both
+# instead of either-or?
+
+require 'loadable/mixin'
+require 'loadable/core_ext/rubygems'
+
+module Loadable
+
+  # The Gem Wedge allows gem files to be loaded in a isolated fashion.
+  #
+  #   require 'tracepoint', :from=>'tracepoint'
+  #
+  # The example would load the tracepoint file from the tracepoint gem.
+  # It will also fallback to the RubyWedge if 'tracepoint' is not found
+  # among available gems. Loading can be limited to gems only by using
+  # the `:gem` options instead.
+  #
+  #   require 'tracepoint', :gem=>'tracepoint'
+  #
+  # Now, if the `tracepoint` script is not found among availabe gems,
+  # a LoadError will be raised.
+  #
+  class GemLoader
+
+    include Loadable
+
+    # Load script from specific gem.
+    #
+    # Returns +nil+ if this loader is not applicable, which is determined
+    # by the use of `:gem => 'foo'` or `:from => 'foo'` options.
+    #
+    def call(fname, options={})
+      return unless apply?(fname, options)
+
+      gem_name = options[:gem] || options[:from]
+
+      if vers = options[:version]
+        spec = ::Gem::Specification.find_by_name(gem_name, vers)
+      else
+        spec = ::Gem::Specification.find_by_name(gem_name)
+      end
+
+      if options[:gem]
+        raise_load_error(fname) unless spec
+      else
+        return unless spec
+      end
+
+      file = spec.find_requirable_file(fname)
+      file = spec.find_requirable_file(File.join(gem_name, fname)) unless file
+
+      if file
+        super(file, options)
+      else
+        raise_load_error(fname)
+      end
+    end
+
+    # Iterate over each loadable file in specified gem.
+    #
+    def each(options={}, &block)
+      return unless apply?(nil, options)
+
+      gem_name = (options[:gem] || options[:from]).to_s
+
+      if vers = options[:version]
+        spec = ::Gem::Specification.find_by_name(gem_name, vers)
+      else
+        spec = ::Gem::Specification.find_by_name(gem_name)
+      end
+
+      return unless spec
+
+      #spec.activate
+
+      spec.require_paths.each do |path|
+        traverse(File.join(spec.full_gem_path, path), &block)
+      end
+    end
+
+    # Determine if this load4 wedge is applicable given the +fname+
+    # and +options+.
+    #
+    def apply?(fname, options={})
+      return true if options[:gem]
+      return true if options[:from] && (
+        ::Gem::Specification.find{ |s| options[:from].to_s == s.name }
+      )
+      return false
+    end
+
+  end
+
+end
+
+# Copyright 2010 Thomas Sawyer, Rubyworks (BSD-2-Clause license)

data/lib/loadable/loaders/original_loader.rb

@@ -0,0 +1,63 @@
+require 'loadable/mixin'
+require 'loadable/core_ext/rubygems'
+
+module Loadable
+
+  # The original loader is simply an encpsulation of the Ruby's
+  # built-in #require and #load functionality. This load wedge is
+  # thus the first placed of the $LOADER list and the final 
+  # fallback if no other loader succeeds.
+  #
+  class OriginalLoader
+
+    include Loadable
+
+    alias_method :original_load, :load
+    alias_method :original_require, :require
+
+    #
+    def call(fname, options={})
+      if options[:load]
+        original_load(fname, options[:wrap])
+      else
+        original_require(fname)
+      end
+    end
+
+    # Iterate over each requirable file. Since RubyGems has become
+    # a standard part of Ruby as of 1.9, this includes active and latest
+    # versions of inactive gems.
+    #
+    # NOTE: in older versions of RubyGems, activated gem versions are in
+    # the $LOAD_PATH too. This may cause some duplicate iterations.
+    #
+    def each(options={}, &block)
+      each_loadpath(&block)
+      each_rubygems(&block)
+      self
+    end
+
+  private
+
+    #
+    def each_loadpath(options={}, &block)
+      $LOAD_PATH.uniq.each do |path|
+        path = File.expand_path(path)
+        traverse(path, &block)
+      end
+    end
+
+    #
+    def each_rubygems(options={}, &block)
+      return unless defined?(::Gem)
+      Gem::Specification.current_specs.each do |spec|
+        spec.require_paths.each do |require_path|
+          path = File.join(spec.full_gem_path, require_path)
+          traverse(path, &block)
+        end
+      end
+    end
+
+  end
+
+end

data/lib/loadable/loaders/roll_loader.rb

@@ -0,0 +1,21 @@
+require 'loadable/mixin'
+
+module Loadable
+
+  #
+  class RollLoader
+
+    include Loadable
+
+    #
+    def call(fname, options={})
+    end
+
+    #
+    def each(options={})
+    end
+
+  end
+
+end
+

data/lib/loadable/loaders/ruby_loader.rb

@@ -0,0 +1,81 @@
+# TODO: Maybe add support more refined selection of locations.
+
+# TODO: Add new vendor locations.
+
+require 'rbconfig'
+require 'loadable/mixin'
+
+module Loadable
+
+  # The Ruby Wedge allows standaard libray scripts to be loaded in a isolated
+  # fashion.
+  #
+  #   require 'optparse', :from=>'ruby'
+  #
+  # The example would load optparse standard library regardless of Gem installed
+  # that might have a script by the same name.
+
+  class RubyLoader
+
+    include Loadable
+
+    # Notice that rubylibdir takes precendence.
+    LOCATIONS = ::RbConfig::CONFIG.values_at(
+      'rubylibdir', 'archdir', 'sitelibdir', 'sitearchdir'
+    )
+
+    # Load the the first standard Ruby library matching +file+.
+    #
+    # Returns +nil+ if this loader is not applicable, which is
+    # determined by the use of `:from => 'ruby'` option.
+    #
+    def call(file, options={})
+      return unless apply?(file, options)
+
+      LOCATIONS.each do |site|
+        if path = lookup(site, file, options)
+          return super(path, options)
+        end
+      end
+
+      raise_load_error(file)
+    end
+
+    #
+    def each(options={}, &block)
+      LOCATIONS.each do |path|
+        #path = File.expand_path(path)
+        traverse(path, &block)
+      end
+    end
+
+    # The `#apply?` methods determines if the load wedge is applicable.
+    #
+    # Returns +true+ if this loader is not applicable, which is
+    # determined by the use of `:from => 'ruby'` option, otherwise `false`.
+    #
+    def apply?(fname, options={})
+      options[:from].to_s == 'ruby'
+    end
+
+
+  private
+
+    # Retun first matching file from Ruby's standard library locations.
+    #
+    # Returns +nil+ if this loader is not applicable.
+    #
+    def find(glob, options={})
+      return unless apply?(file, options)
+
+      LOCATIONS.each do |site|
+        path = lookup(site, file, options)
+        return path if path
+      end
+    end
+
+  end
+
+end
+
+# Copyright 2010 Thomas Sawyer, Rubyworks (BSD-2-Clause license)