* lib/rubygems: Update to RubyGems master 612f85a. Notable changes:

  Fixed installation and activation of git: and path: gems via
  Gem.use_gemdeps

  Improved documentation coverage

* test/rubygems:  ditto.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@43845 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

23 files changed, 315 insertions, 61 deletions

diff --git a/lib/rubygems/available_set.rb b/lib/rubygems/available_set.rb
index 4ab4d77716..d8655afc34 100644
--- a/lib/rubygems/available_set.rb
+++ b/lib/rubygems/available_set.rb
@@ -127,7 +127,7 @@ class Gem::AvailableSet
     end
 
     match.map do |t|
-      Gem::Resolver::InstalledSpecification.new(self, t.spec, t.source)
+      Gem::Resolver::LocalSpecification.new(self, t.spec, t.source)
     end
   end
 
diff --git a/lib/rubygems/basic_specification.rb b/lib/rubygems/basic_specification.rb
index 4f96fcac3d..cfbfbdde92 100644
--- a/lib/rubygems/basic_specification.rb
+++ b/lib/rubygems/basic_specification.rb
@@ -9,6 +9,11 @@ class Gem::BasicSpecification
 
   attr_reader :loaded_from
 
+  ##
+  # Allows correct activation of git: and path: gems.
+
+  attr_writer :full_gem_path # :nodoc:
+
   def self.default_specifications_dir
     File.join(Gem.default_dir, "specifications", "default")
   end
diff --git a/lib/rubygems/installer.rb b/lib/rubygems/installer.rb
index 214652a241..f3172752c2 100644
--- a/lib/rubygems/installer.rb
+++ b/lib/rubygems/installer.rb
@@ -57,6 +57,11 @@ class Gem::Installer
 
   attr_reader :options
 
+  ##
+  # Sets the specification for .gem-less installs.
+
+  attr_writer :spec
+
   @path_warning = false
 
   class << self
diff --git a/lib/rubygems/installer_test_case.rb b/lib/rubygems/installer_test_case.rb
index 62a468a8a2..d03e512451 100644
--- a/lib/rubygems/installer_test_case.rb
+++ b/lib/rubygems/installer_test_case.rb
@@ -56,11 +56,6 @@ class Gem::Installer
   ##
   # Available through requiring rubygems/installer_test_case
 
-  attr_writer :spec
-
-  ##
-  # Available through requiring rubygems/installer_test_case
-
   attr_writer :wrappers
 end
 
diff --git a/lib/rubygems/request_set.rb b/lib/rubygems/request_set.rb
index d91a39cb22..d6337e32d8 100644
--- a/lib/rubygems/request_set.rb
+++ b/lib/rubygems/request_set.rb
@@ -166,29 +166,22 @@ class Gem::RequestSet
 
     installed = []
 
-    sorted_requests.each do |req|
-      if existing.find { |s| s.full_name == req.spec.full_name }
-        yield req, nil if block_given?
-        next
-      end
+    options[:install_dir] = dir
+    options[:only_install_dir] = true
 
-      path = req.download(dir)
+    sorted_requests.each do |request|
+      spec = request.spec
 
-      unless path then # already installed
-        yield req, nil if block_given?
+      if existing.find { |s| s.full_name == spec.full_name } then
+        yield request, nil if block_given?
         next
       end
 
-      options[:install_dir] = dir
-      options[:only_install_dir] = true
-
-      inst = Gem::Installer.new path, options
-
-      yield req, inst if block_given?
-
-      inst.install
+      spec.install options do |installer|
+        yield request, installer if block_given?
+      end
 
-      installed << req
+      installed << request
     end
 
     installed
diff --git a/lib/rubygems/resolver.rb b/lib/rubygems/resolver.rb
index 828c61de01..8f11acc197 100644
--- a/lib/rubygems/resolver.rb
+++ b/lib/rubygems/resolver.rb
@@ -15,12 +15,25 @@ require 'net/http'
 class Gem::Resolver
 
   ##
+  # If the DEBUG_RESOLVER environment variable is set then debugging mode is
+  # enabled for the resolver.  This will display information about the state
+  # of the resolver while a set of dependencies is being resolved.
+
+  DEBUG_RESOLVER = !ENV['DEBUG_RESOLVER'].nil?
+
+  ##
   # Contains all the conflicts encountered while doing resolution
 
   attr_reader :conflicts
 
+  ##
+  # Set to true if development dependencies should be considered.
+
   attr_accessor :development
 
+  ##
+  # List of dependencies that could not be found in the configured sources.
+
   attr_reader :missing
 
   ##
@@ -57,8 +70,8 @@ class Gem::Resolver
   end
 
   ##
-  # Provide a Resolver that queries only against the already
-  # installed gems.
+  # Creates a Resolver that queries only against the already installed gems
+  # for the +needed+ dependencies.
 
   def self.for_current_gems needed
     new needed, Gem::Resolver::CurrentSet.new
@@ -82,16 +95,14 @@ class Gem::Resolver
     @soft_missing = false
   end
 
-  DEBUG_RESOLVER = !ENV['DEBUG_RESOLVER'].nil?
-
-  def explain(stage, *data)
+  def explain stage, *data # :nodoc:
     if DEBUG_RESOLVER
       d = data.map { |x| x.inspect }.join(", ")
       STDOUT.printf "%20s %s\n", stage.to_s.upcase, d
     end
   end
 
-  def explain_list(stage, data)
+  def explain_list stage, data # :nodoc:
     if DEBUG_RESOLVER
       STDOUT.printf "%20s (%d entries)\n", stage.to_s.upcase, data.size
       data.each do |d|
@@ -117,7 +128,7 @@ class Gem::Resolver
     return spec, activation_request
   end
 
-  def requests s, act, reqs=nil
+  def requests s, act, reqs=nil # :nodoc:
     s.dependencies.reverse_each do |d|
       next if d.type == :development and not @development
       reqs.add Gem::Resolver::DependencyRequest.new(d, act)
@@ -182,7 +193,7 @@ class Gem::Resolver
     return matching_platform, all
   end
 
-  def handle_conflict(dep, existing)
+  def handle_conflict(dep, existing) # :nodoc:
     # There is a conflict! We return the conflict object which will be seen by
     # the caller and be handled at the right level.
 
@@ -252,7 +263,7 @@ class Gem::Resolver
   # +specs+ being a list to ActivationRequest, calculate a new list of
   # ActivationRequest objects.
 
-  def resolve_for needed, specs
+  def resolve_for needed, specs # :nodoc:
     # The State objects that are used to attempt the activation tree.
     states = []
 
@@ -411,5 +422,6 @@ require 'rubygems/resolver/api_specification'
 require 'rubygems/resolver/git_specification'
 require 'rubygems/resolver/index_specification'
 require 'rubygems/resolver/installed_specification'
+require 'rubygems/resolver/local_specification'
 require 'rubygems/resolver/vendor_specification'
 
diff --git a/lib/rubygems/resolver/activation_request.rb b/lib/rubygems/resolver/activation_request.rb
index ca82ac408a..2d48cfa927 100644
--- a/lib/rubygems/resolver/activation_request.rb
+++ b/lib/rubygems/resolver/activation_request.rb
@@ -1,21 +1,33 @@
 ##
-# Specifies a Specification object that should be activated.
-# Also contains a dependency that was used to introduce this
-# activation.
+# Specifies a Specification object that should be activated.  Also contains a
+# dependency that was used to introduce this activation.
 
 class Gem::Resolver::ActivationRequest
 
+  ##
+  # The parent request for this activation request.
+
   attr_reader :request
 
+  ##
+  # The specification to be activated.
+
   attr_reader :spec
 
-  def initialize spec, req, others_possible = true
+  ##
+  # Creates a new ActivationRequest that will activate +spec+.  The parent
+  # +request+ is used to provide diagnostics in case of conflicts.
+  #
+  # +others_possible+ indicates that other specifications may also match this
+  # activation request.
+
+  def initialize spec, request, others_possible = true
     @spec = spec
-    @request = req
+    @request = request
     @others_possible = others_possible
   end
 
-  def == other
+  def == other # :nodoc:
     case other
     when Gem::Specification
       @spec == other
@@ -26,6 +38,9 @@ class Gem::Resolver::ActivationRequest
     end
   end
 
+  ##
+  # Downloads a gem at +path+ and returns the file path.
+
   def download path
     if @spec.respond_to? :source
       source = @spec.source
@@ -38,10 +53,16 @@ class Gem::Resolver::ActivationRequest
     source.download full_spec, path
   end
 
+  ##
+  # The full name of the specification to be activated.
+
   def full_name
     @spec.full_name
   end
 
+  ##
+  # The Gem::Specification for this activation request.
+
   def full_spec
     Gem::Specification === @spec ? @spec : @spec.spec
   end
@@ -66,7 +87,7 @@ class Gem::Resolver::ActivationRequest
   end
 
   ##
-  # Indicates if the requested gem has already been installed.
+  # True if the requested gem has already been installed.
 
   def installed?
     case @spec
@@ -81,6 +102,9 @@ class Gem::Resolver::ActivationRequest
     end
   end
 
+  ##
+  # The name of this activation request's specification
+
   def name
     @spec.name
   end
@@ -130,6 +154,9 @@ class Gem::Resolver::ActivationRequest
     end
   end
 
+  ##
+  # The version of this activation request's specification
+
   def version
     @spec.version
   end
diff --git a/lib/rubygems/resolver/api_specification.rb b/lib/rubygems/resolver/api_specification.rb
index 0ab8e830c6..67052af82e 100644
--- a/lib/rubygems/resolver/api_specification.rb
+++ b/lib/rubygems/resolver/api_specification.rb
@@ -34,6 +34,10 @@ class Gem::Resolver::APISpecification < Gem::Resolver::Specification
       @dependencies == other.dependencies
   end
 
+  def installable_platform? # :nodoc:
+    Gem::Platform.match @platform
+  end
+
   def pretty_print q # :nodoc:
     q.group 2, '[APISpecification', ']' do
       q.breakable
diff --git a/lib/rubygems/resolver/conflict.rb b/lib/rubygems/resolver/conflict.rb
index 20c6eced31..8830e8d1fb 100644
--- a/lib/rubygems/resolver/conflict.rb
+++ b/lib/rubygems/resolver/conflict.rb
@@ -95,7 +95,6 @@ class Gem::Resolver::Conflict
     path = []
 
     while current do
-      spec_name   = current.spec.full_name
       requirement = current.request.dependency.requirement
       path << "#{current.spec.full_name} (#{requirement})"
 
diff --git a/lib/rubygems/resolver/dependency_request.rb b/lib/rubygems/resolver/dependency_request.rb
index e63b443c62..1d51db4945 100644
--- a/lib/rubygems/resolver/dependency_request.rb
+++ b/lib/rubygems/resolver/dependency_request.rb
@@ -4,16 +4,26 @@
 
 class Gem::Resolver::DependencyRequest
 
+  ##
+  # The wrapped Gem::Dependency
+
   attr_reader :dependency
 
+  ##
+  # The request for this dependency.
+
   attr_reader :requester
 
-  def initialize(dep, act)
-    @dependency = dep
-    @requester = act
+  ##
+  # Creates a new DependencyRequest for +dependency+ from +requester+.
+  # +requester may be nil if the request came from a user.
+
+  def initialize dependency, requester
+    @dependency = dependency
+    @requester  = requester
   end
 
-  def ==(other)
+  def == other # :nodoc:
     case other
     when Gem::Dependency
       @dependency == other
@@ -24,26 +34,39 @@ class Gem::Resolver::DependencyRequest
     end
   end
 
+  ##
+  # Does this dependency request match +spec+
+
   def matches_spec?(spec)
     @dependency.matches_spec? spec
   end
 
+  ##
+  # The name of the gem this dependency request is requesting.
+
   def name
     @dependency.name
   end
 
+  ##
   # Indicate that the request is for a gem explicitly requested by the user
+
   def explicit?
     @requester.nil?
   end
 
-  # Indicate that the requset is for a gem requested as a dependency of another gem
+  ##
+  # Indicate that the request is for a gem requested as a dependency of
+  # another gem
+
   def implicit?
     !explicit?
   end
 
+  ##
   # Return a String indicating who caused this request to be added (only
   # valid for implicit requests)
+
   def request_context
     @requester ? @requester.request : "(unknown)"
   end
@@ -59,6 +82,9 @@ class Gem::Resolver::DependencyRequest
     end
   end
 
+  ##
+  # The version requirement for this dependency request
+
   def requirement
     @dependency.requirement
   end
diff --git a/lib/rubygems/resolver/git_specification.rb b/lib/rubygems/resolver/git_specification.rb
index ac8d4e9aeb..113e7ea9de 100644
--- a/lib/rubygems/resolver/git_specification.rb
+++ b/lib/rubygems/resolver/git_specification.rb
@@ -12,5 +12,24 @@ class Gem::Resolver::GitSpecification < Gem::Resolver::SpecSpecification
       @source == other.source
   end
 
+  ##
+  # Installing a git gem only involves building the extensions and generating
+  # the executables.
+
+  def install options
+    require 'rubygems/installer'
+
+    installer = Gem::Installer.new '', options
+    installer.spec = spec
+
+    yield installer if block_given?
+
+    installer.run_pre_install_hooks
+    installer.build_extensions
+    installer.run_post_build_hooks
+    installer.generate_bin
+    installer.run_post_install_hooks
+  end
+
 end
 
diff --git a/lib/rubygems/resolver/installed_specification.rb b/lib/rubygems/resolver/installed_specification.rb
index 647ff7499a..a9438129fb 100644
--- a/lib/rubygems/resolver/installed_specification.rb
+++ b/lib/rubygems/resolver/installed_specification.rb
@@ -11,16 +11,22 @@ class Gem::Resolver::InstalledSpecification < Gem::Resolver::SpecSpecification
   end
 
   ##
+  # This is a null install as this specification is already installed.
+  # +options+ are ignored.
+
+  def install options
+    yield nil
+  end
+
+  ##
   # Returns +true+ if this gem is installable for the current platform.
 
   def installable_platform?
     # BACKCOMPAT If the file is coming out of a specified file, then we
     # ignore the platform. This code can be removed in RG 3.0.
-    if @source.kind_of? Gem::Source::SpecificFile
-      return true
-    else
-      Gem::Platform.match @spec.platform
-    end
+    return true if @source.kind_of? Gem::Source::SpecificFile
+
+    super
   end
 
   ##
diff --git a/lib/rubygems/resolver/installer_set.rb b/lib/rubygems/resolver/installer_set.rb
index 73d9e39651..e35e0aabec 100644
--- a/lib/rubygems/resolver/installer_set.rb
+++ b/lib/rubygems/resolver/installer_set.rb
@@ -20,6 +20,9 @@ class Gem::Resolver::InstallerSet < Gem::Resolver::Set
 
   attr_accessor :ignore_installed # :nodoc:
 
+  ##
+  # Creates a new InstallerSet that will look for gems in +domain+.
+
   def initialize domain
     @domain = domain
 
diff --git a/lib/rubygems/resolver/local_specification.rb b/lib/rubygems/resolver/local_specification.rb
new file mode 100644
index 0000000000..dcca6c736a
--- /dev/null
+++ b/lib/rubygems/resolver/local_specification.rb
@@ -0,0 +1,16 @@
+##
+# A LocalSpecification comes from a .gem file on the local filesystem.
+
+class Gem::Resolver::LocalSpecification < Gem::Resolver::SpecSpecification
+
+  ##
+  # Returns +true+ if this gem is installable for the current platform.
+
+  def installable_platform?
+    return true if @source.kind_of? Gem::Source::SpecificFile
+
+    super
+  end
+
+end
+
diff --git a/lib/rubygems/resolver/requirement_list.rb b/lib/rubygems/resolver/requirement_list.rb
index 04e437b2a9..fe1d77afc3 100644
--- a/lib/rubygems/resolver/requirement_list.rb
+++ b/lib/rubygems/resolver/requirement_list.rb
@@ -1,19 +1,28 @@
 ##
-# Used internally to hold the requirements being considered
-# while attempting to find a proper activation set.
+# The RequirementList is used to hold the requirements being considered
+# while resolving a set of gems.
+#
+# The RequirementList acts like a queue where the oldest items are removed
+# first.
 
 class Gem::Resolver::RequirementList
 
   include Enumerable
 
+  ##
+  # Creates a new RequirementList.
+
   def initialize
     @list = []
   end
 
-  def initialize_copy(other)
+  def initialize_copy other # :nodoc:
     @list = @list.dup
   end
 
+  ##
+  # Adds Resolver::DependencyRequest +req+ to this requirements list.
+
   def add(req)
     @list.push req
     req
@@ -30,14 +39,23 @@ class Gem::Resolver::RequirementList
     end
   end
 
+  ##
+  # Is the list empty?
+
   def empty?
     @list.empty?
   end
 
+  ##
+  # Remove the oldest DependencyRequest from the list.
+
   def remove
     @list.shift
   end
 
+  ##
+  # Returns the oldest five entries from the list.
+
   def next5
     @list[0,5]
   end
diff --git a/lib/rubygems/resolver/specification.rb b/lib/rubygems/resolver/specification.rb
index 7dd4c2e829..d158225474 100644
--- a/lib/rubygems/resolver/specification.rb
+++ b/lib/rubygems/resolver/specification.rb
@@ -56,5 +56,34 @@ class Gem::Resolver::Specification
     "#{@name}-#{@version}"
   end
 
+  ##
+  # Installs this specification using the Gem::Installer +options+.  The
+  # install method yields a Gem::Installer instance, which indicates the
+  # gem will be installed, or +nil+, which indicates the gem is already
+  # installed.
+
+  def install options
+    require 'rubygems/installer'
+
+    destination = options[:install_dir] || Gem.dir
+
+    Gem.ensure_gem_subdirectories destination
+
+    gem = source.download spec, destination
+
+    installer = Gem::Installer.new gem, options
+
+    yield installer if block_given?
+
+    installer.install
+  end
+
+  ##
+  # Returns true if this specification is installable on this platform.
+
+  def installable_platform?
+    Gem::Platform.match spec.platform
+  end
+
 end
 
diff --git a/lib/rubygems/resolver/vendor_set.rb b/lib/rubygems/resolver/vendor_set.rb
index e9cbcd8303..c8826005a7 100644
--- a/lib/rubygems/resolver/vendor_set.rb
+++ b/lib/rubygems/resolver/vendor_set.rb
@@ -32,6 +32,8 @@ class Gem::Resolver::VendorSet < Gem::Resolver::Set
     raise Gem::GemNotFoundException,
           "unable to find #{gemspec} for gem #{name}" unless spec
 
+    spec.full_gem_path = File.expand_path directory
+
     key = "#{spec.name}-#{spec.version}-#{spec.platform}"
 
     @specs[key]        = spec
diff --git a/lib/rubygems/resolver/vendor_specification.rb b/lib/rubygems/resolver/vendor_specification.rb
index 24e033d084..c6a8e58d9b 100644
--- a/lib/rubygems/resolver/vendor_specification.rb
+++ b/lib/rubygems/resolver/vendor_specification.rb
@@ -12,5 +12,13 @@ class Gem::Resolver::VendorSpecification < Gem::Resolver::SpecSpecification
       @source == other.source
   end
 
+  ##
+  # This is a null install as this gem was unpacked into a directory.
+  # +options+ are ignored.
+
+  def install options
+    yield nil
+  end
+
 end
 
diff --git a/lib/rubygems/security/trust_dir.rb b/lib/rubygems/security/trust_dir.rb
index dd51308ee5..76ef89af7f 100644
--- a/lib/rubygems/security/trust_dir.rb
+++ b/lib/rubygems/security/trust_dir.rb
@@ -1,10 +1,26 @@
+##
+# The TrustDir manages the trusted certificates for gem signature
+# verification.
+
 class Gem::Security::TrustDir
 
+  ##
+  # Default permissions for the trust directory and its contents
+
   DEFAULT_PERMISSIONS = {
     :trust_dir    => 0700,
     :trusted_cert => 0600,
   }
 
+  ##
+  # The directory where trusted certificates will be stored.
+
+  attr_reader :dir
+
+  ##
+  # Creates a new TrustDir using +dir+ where the directory and file
+  # permissions will be checked according to +permissions+
+
   def initialize dir, permissions = DEFAULT_PERMISSIONS
     @dir = dir
     @permissions = permissions
@@ -12,8 +28,6 @@ class Gem::Security::TrustDir
     @digester = Gem::Security::DIGEST_ALGORITHM
   end
 
-  attr_reader :dir
-
   ##
   # Returns the path to the trusted +certificate+
 
diff --git a/lib/rubygems/source/git.rb b/lib/rubygems/source/git.rb
index c4f2724645..2794735c96 100644
--- a/lib/rubygems/source/git.rb
+++ b/lib/rubygems/source/git.rb
@@ -91,8 +91,8 @@ class Gem::Source::Git < Gem::Source
       success = system @git, 'reset', '--quiet', '--hard', @reference
 
       success &&=
-        system @git, 'submodule', 'update',
-               '--quiet', '--init', '--recursive', out: IO::NULL if @need_submodules
+        Gem::Util.silent_system @git, 'submodule', 'update',
+               '--quiet', '--init', '--recursive' if @need_submodules
 
       success
     end
@@ -161,7 +161,9 @@ class Gem::Source::Git < Gem::Source
         file      = File.basename spec_file
 
         Dir.chdir directory do
-          Gem::Specification.load file
+          spec = Gem::Specification.load file
+          spec.full_gem_path = File.expand_path '.' if spec
+          spec
         end
       end.compact
     end
diff --git a/lib/rubygems/test_utilities.rb b/lib/rubygems/test_utilities.rb
index 37f54e601e..f7943adcee 100644
--- a/lib/rubygems/test_utilities.rb
+++ b/lib/rubygems/test_utilities.rb
@@ -205,6 +205,10 @@ class Gem::TestCase::SpecFetcherSetup
     @operations << [:clear]
   end
 
+  ##
+  # Returns a Hash of created Specification full names and the corresponding
+  # Specification.
+
   def created_specs
     created = {}
 
@@ -271,7 +275,7 @@ class Gem::TestCase::SpecFetcherSetup
     end
   end
 
-  def setup_fetcher # :nodoc;
+  def setup_fetcher # :nodoc:
     require 'zlib'
     require 'socket'
     require 'rubygems/remote_fetcher'
diff --git a/lib/rubygems/user_interaction.rb b/lib/rubygems/user_interaction.rb
index 0e4449a2ec..fad29b4afd 100644
--- a/lib/rubygems/user_interaction.rb
+++ b/lib/rubygems/user_interaction.rb
@@ -666,6 +666,11 @@ end
 # STDOUT, and STDERR.
 
 class Gem::ConsoleUI < Gem::StreamUI
+
+  ##
+  # The Console UI has no arguments as it defaults to reading input from
+  # stdin, output to stdout and warnings or errors to stderr.
+
   def initialize
     super STDIN, STDOUT, STDERR, true
   end
@@ -675,6 +680,10 @@ end
 # SilentUI is a UI choice that is absolutely silent.
 
 class Gem::SilentUI < Gem::StreamUI
+
+  ##
+  # The SilentUI has no arguments as it does not use any stream.
+
   def initialize
     reader, writer = nil, nil
 
@@ -689,11 +698,11 @@ class Gem::SilentUI < Gem::StreamUI
     super reader, writer, writer, false
   end
 
-  def download_reporter(*args)
+  def download_reporter(*args) # :nodoc:
     SilentDownloadReporter.new(@outs, *args)
   end
 
-  def progress_reporter(*args)
+  def progress_reporter(*args) # :nodoc:
     SilentProgressReporter.new(@outs, *args)
   end
 end
diff --git a/lib/rubygems/util.rb b/lib/rubygems/util.rb
index 42663974a5..408942d398 100644
--- a/lib/rubygems/util.rb
+++ b/lib/rubygems/util.rb
@@ -1,4 +1,10 @@
+##
+# This module contains various utility methods as module methods.
+
 module Gem::Util
+
+  @silent_mutex = nil
+
   ##
   # Zlib::GzipReader wrapper that unzips +data+.
 
@@ -60,4 +66,56 @@ module Gem::Util
     end
   end
 
+  ##
+  # Invokes system, but silences all output.
+
+  def self.silent_system *command
+    require 'thread'
+
+    @silent_mutex ||= Mutex.new
+
+    null_device = Gem.win_platform? ? 'NUL' : '/dev/null'
+
+    @silent_mutex.synchronize do
+      begin
+        stdout = STDOUT.dup
+        stderr = STDERR.dup
+
+        STDOUT.reopen null_device, 'w'
+        STDERR.reopen null_device, 'w'
+
+        return system(*command)
+      ensure
+        STDOUT.reopen stdout
+        STDERR.reopen stderr
+      end
+    end
+  end
+
+  ##
+  # Enumerates the parents of +directory+.
+
+  def self.traverse_parents directory
+    return enum_for __method__, directory unless block_given?
+
+    here = File.expand_path directory
+    start = here
+
+    Dir.chdir start
+
+    begin
+      loop do
+        yield here
+
+        Dir.chdir '..'
+
+        return if Dir.pwd == here # toplevel
+
+        here = Dir.pwd
+      end
+    ensure
+      Dir.chdir start
+    end
+  end
+
 end