tap 0.12.4 → 0.17.0

data/lib/tap/env/constant.rb

@@ -0,0 +1,227 @@
+require 'tap/env/string_ext'
+
+module Tap
+  class Env
+  
+    # A Constant serves as a placeholder for an actual constant, sort of like 
+    # autoload.  Use the constantize method to retrieve the actual constant; if
+    # it doesn't exist, constantize requires require_path and tries again.
+    #
+    #   Object.const_defined?(:Net)                      # => false
+    #   $".include?('net/http')                          # => false
+    #
+    #   http = Constant.new('Net::HTTP', 'net/http.rb')
+    #   http.constantize                                 # => Net::HTTP
+    #   $".include?('net/http.rb')                       # => true
+    #
+    # === Unloading
+    #
+    # Constant also supports constant unloading.  Unloading can be useful in
+    # various development modes, but make cause code to behave unpredictably.
+    # When a Constant unloads, the constant value is detached from the nesting
+    # constant and the require path is removed from $".  This allows a require
+    # statement to re-require, and in theory, reload the constant.
+    #
+    #   # [simple.rb]
+    #   # class Simple
+    #   # end
+    #
+    #   const = Constant.new('Simple', 'simple')
+    #   const.constantize                                # => Simple
+    #   Object.const_defined?(:Simple)                   # => true
+    #
+    #   const.unload                                     # => Simple
+    #   Object.const_defined?(:Simple)                   # => false
+    #
+    #   const.constantize                                # => Simple
+    #   Object.const_defined?(:Simple)                   # => true
+    #  
+    # Unloading and reloading works best for scripts that have no side effects;
+    # ie scripts that do not require other files and only define the specified
+    # class or module.
+    class Constant
+      class << self
+      
+        # Constantize tries to look up the specified constant under const. A
+        # block may be given to manually look up missing constants; the last
+        # existing const and any non-existant constant names are yielded to the
+        # block, which is expected to return the desired constant.  For instance
+        # in the example 'Non::Existant' is essentially mapping to ConstName.
+        #
+        #   module ConstName; end
+        #
+        #   Constant.constantize('ConstName')                     # => ConstName
+        #   Constant.constantize('Non::Existant') { ConstName }   # => ConstName
+        #
+        # Raises a NameError for invalid/missing constants.
+        def constantize(const_name, const=Object) # :yields: const, missing_const_names
+          unless CONST_REGEXP =~ const_name
+            raise NameError, "#{const_name.inspect} is not a valid constant name!"
+          end
+        
+          constants = $1.split(/::/)
+          while !constants.empty?
+            unless const_is_defined?(const, constants[0])
+              if block_given? 
+                return yield(const, constants)
+              else
+                raise NameError.new("uninitialized constant #{const_name}", constants[0]) 
+              end
+            end
+            const = const.const_get(constants.shift)
+          end
+          const
+        end
+      
+        private
+      
+        # helper method.  Determines if the named constant is defined in const.
+        # The implementation (annoyingly) has to be different for ruby 1.9 due
+        # to changes in the API.
+        case RUBY_VERSION
+        when /^1.9/
+          def const_is_defined?(const, const_name) # :nodoc:
+            const.const_defined?(const_name, false)
+          end
+        else
+          def const_is_defined?(const, const_name) # :nodoc:
+            const.const_defined?(const_name)
+          end
+        end
+      end
+    
+      # Matches a valid constant
+      CONST_REGEXP = /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/
+    
+      # The full constant name
+      attr_reader :const_name
+    
+      # The path to load to initialize a missing constant
+      attr_reader :require_path
+    
+      # An optional comment
+      attr_accessor :comment
+    
+      # Initializes a new Constant with the specified constant name,
+      # require_path, and comment.  The const_name should be a valid
+      # constant name.
+      def initialize(const_name, require_path=nil, comment=nil)
+        @const_name = const_name
+        @require_path = require_path
+        @comment = comment
+      end
+    
+      # Returns the underscored const_name.
+      #
+      #   Constant.new("Const::Name").path           # => 'const/name'
+      #
+      def path
+        @path ||= const_name.underscore
+      end
+    
+      # Returns the basename of path.
+      #
+      #   Constant.new("Const::Name").basename       # => 'name'
+      #
+      def basename
+        @basename ||= File.basename(path)
+      end
+    
+      # Returns the path, minus the basename of path.
+      #
+      #   Constant.new("Const::Name").dirname        # => 'const'
+      #
+      def dirname
+        @dirname ||= (dirname = File.dirname(path)) == "." ? "" : dirname
+      end
+    
+      # Returns the name of the constant, minus nesting.
+      #
+      #   Constant.new("Const::Name").name           # => 'Name'
+      #
+      def name
+        @name ||= (const_name =~ /.*::(.*)\z/ ? $1 : const_name)
+      end
+    
+      # Returns the nesting constant of const_name.
+      #
+      #   Constant.new("Const::Name").nesting        # => 'Const'
+      #
+      def nesting
+        @nesting ||= (const_name =~ /(.*)::.*\z/ ? $1 : '')
+      end
+    
+      # Returns the number of constants in nesting.
+      #
+      #   Constant.new("Const::Name").nesting_depth  # => 1
+      #
+      def nesting_depth
+        @nesting_depth ||= nesting.split(/::/).length
+      end
+
+      # Returns the Lazydoc document for require_path.
+      def document
+        require_path ? Lazydoc[require_path] : nil 
+      end
+    
+      # True if another is a Constant with the same const_name,
+      # require_path, and comment as self.
+      def ==(another)
+        another.kind_of?(Constant) && 
+        another.const_name == self.const_name &&
+        another.require_path == self.require_path &&
+        another.comment == self.comment
+      end
+    
+      # Looks up and returns the constant indicated by const_name. If the
+      # constant cannot be found, constantize requires require_path and
+      # tries again.
+      #
+      # Raises a NameError if the constant cannot be found.
+      def constantize
+        Constant.constantize(const_name) do
+          require require_path if require_path
+          Constant.constantize(const_name)
+        end
+      end
+    
+      # Undefines the constant indicated by const_name.  The nesting constants
+      # are not removed.  If specified, require_path will be removed from $".
+      #
+      # When removing require_path, unload will add '.rb' to the require_path if
+      # require_path has no extension (this echos the behavior of require).
+      # Other extension names like '.so', '.dll', etc. are not tried and will
+      # not be removed.
+      #
+      # Does nothing if const_name doesn't exist.  Returns the unloaded constant.
+      # Obviously, <em>this method should be used with caution</em>.
+      def unload(unrequire=true)
+        const = nesting.empty? ? Object : Constant.constantize(nesting) { Object }
+      
+        if const.const_defined?(name)
+          if unrequire && require_path
+            path = File.extname(require_path).empty? ? "#{require_path}.rb" : require_path
+            $".delete(path)
+          end
+        
+          return const.send(:remove_const, name)
+        end
+      
+        nil
+      end
+    
+      # Returns a string like:
+      #
+      #   "#<Tap::Env::Constant:object_id Const::Name (require_path)>"
+      #
+      def inspect
+        "#<#{self.class}:#{object_id} #{const_name}#{@require_path == nil ? "" : " (#{@require_path})"}>"
+      end
+      
+      # Returns the minikey for self, ie path.  (see Tap::Env::Minimap)
+      def minikey
+        path
+      end
+    end
+  end
+end

data/lib/tap/env/gems.rb

@@ -0,0 +1,63 @@
+require 'rubygems'
+
+module Tap
+  class Env
+  
+    # Methods for working with {RubyGems}[http://www.rubygems.org/].
+    module Gems
+      module_function
+    
+      # Returns the gemspec for the specified gem.  A gem version 
+      # can be specified in the name, like 'gem >= 1.2'.  The gem
+      # is not activated by this method.
+      def gemspec(gem_name)
+        return gem_name if gem_name.kind_of?(Gem::Specification)
+        
+        dependency = if gem_name.kind_of?(Gem::Dependency)
+          gem_name
+        else
+          # figure the version of the gem, by default >= 0.0.0
+          gem_name.to_s =~ /^([^~<=>]*)(.*)$/
+          name, version = $1.strip, $2
+          return nil if name.empty?
+          version = Gem::Requirement.default if version.empty?
+      
+          # note the last gem matching the dependency requirements
+          # is the latest matching gem
+          Gem::Dependency.new(name, version)
+        end
+        
+        Gem.source_index.search(dependency).last
+      end
+    
+      # Selects gem specs for which the block returns true.  If
+      # latest is specified, only the latest version of each
+      # gem will be passed to the block.
+      def select_gems(latest=true)
+        specs = latest ?
+          Gem.source_index.latest_specs :
+          Gem.source_index.gems.collect {|(name, spec)| spec }
+        
+        # this song and dance is to ensure that specs are sorted
+        # by name (ascending) then version (descending) so that
+        # the latest version of a spec appears first
+        specs_by_name = {}
+        specs.each do |spec|
+          next unless !block_given? || yield(spec) 
+          (specs_by_name[spec.name] ||= []) << spec
+        end
+        
+        specs = []
+        specs_by_name.keys.sort.each do |name|
+          specs_by_name[name].sort_by do |spec| 
+            spec.version
+          end.reverse_each do |spec|
+            specs << spec
+          end
+        end
+        
+        specs
+      end
+    end
+  end
+end

data/lib/tap/env/manifest.rb

@@ -0,0 +1,89 @@
+require 'tap/env/minimap'
+require 'tap/env/constant'
+
+module Tap
+  class Env
+    
+    class Manifest
+      include Enumerable
+      include Minimap
+      
+      # The environment this manifest summarizes
+      attr_reader :env
+      
+      attr_reader :type
+      
+      # Initializes a new Manifest.
+      def initialize(env, type)
+        @env = env
+        @type = type
+      end
+      
+      def entries
+        env.registry[type]
+      end
+      
+      # True if entries are empty.
+      def empty?
+        entries.empty?
+      end
+      
+      def all_empty?
+        env.all? do |current|
+          current.manifest(type).empty?
+        end
+      end
+      
+      # Iterates over each entry in self.
+      def each
+        entries.each {|entry| yield(entry) }
+      end
+      
+      # Searches across env.each for the first entry minimatching key. A single
+      # env can be specified by using a compound key like 'env_key:key'.
+      #
+      # Returns nil if no matching entry is found.
+      def seek(key)
+        env.seek(type, key)
+      end
+      
+      def [](key)
+        entry = seek(key)
+        entry.kind_of?(Constant) ? entry.constantize : entry
+      end
+      
+      # Same as env.inspect but adds manifest to the templater
+      def inspect(template=nil, globals={}, filename=nil)
+        return super() unless template
+
+        env.inspect(template, globals, filename) do |templater, globalz|
+          env = templater.env
+          templater.manifest = env.manifest(type)
+          yield(templater, globalz) if block_given?
+        end
+      end
+
+      SUMMARY_TEMPLATE = %Q{<% if !entries.empty? && count > 1 %>
+<%= env_key %>:
+<% end %>
+<% entries.each do |key, entry| %>
+  <%= key.ljust(width) %> # <%= entry.respond_to?(:comment) ? entry.comment : entry %>
+<% end %>
+}
+
+      def summarize(template=SUMMARY_TEMPLATE)
+        inspect(template, :width => 11, :count => 0) do |templater, globals|
+          width = globals[:width]
+          templater.entries = templater.manifest.minimap.collect! do |key, entry|
+            width = key.length if width < key.length
+            [key, entry]
+          end
+
+          globals[:width] = width
+          globals[:count] += 1 unless templater.entries.empty?
+        end
+      end
+      
+    end
+  end
+end

data/lib/tap/env/minimap.rb

@@ -0,0 +1,292 @@
+module Tap
+  class Env
+    
+    # Minimap adds minimization and search methods to an array of paths.
+    # 
+    #   paths = %w{
+    #     path/to/file-0.1.0.txt 
+    #     path/to/file-0.2.0.txt
+    #     path/to/another_file.txt
+    #   }
+    #   paths.extend Env::Minimap
+    #
+    #   paths.minimatch('file')             # => 'path/to/file-0.1.0.txt'
+    #   paths.minimatch('file-0.2.0')       # => 'path/to/file-0.2.0.txt'
+    #   paths.minimatch('another_file')     # => 'path/to/another_file.txt'
+    #
+    # More generally, Minimap may extend any object responding to each.
+    # Non-string entries are allowed; if the entry responds to minikey, then
+    # minimap will call that method to determine the 'path' to the entry.
+    # Otherwise, to_s is used.  Override the entry_to_minikey method to
+    # change this default behavior.
+    #
+    #   class ConstantMap < Array
+    #     include Env::Minimap
+    #
+    #     def entry_to_minikey(const)
+    #       const.underscore
+    #     end
+    #   end 
+    #
+    #   constants = ConstantMap[Tap::Env::Minimap, Tap::Env]
+    #   constants.minimatch('env')          # => Tap::Env
+    #   constants.minimatch('minimap')      # => Tap::Env::Minimap
+    #
+    module Minimap
+
+      # Provides a minimized map of the entries using keys provided minikey.
+      #
+      #   paths = %w{
+      #     path/to/file-0.1.0.txt 
+      #     path/to/file-0.2.0.txt
+      #     path/to/another_file.txt
+      #   }.extend Minimap
+      #
+      #   paths.minimap
+      #   # => [
+      #   # ['file-0.1.0',  'path/to/file-0.1.0.txt'],
+      #   # ['file-0.2.0',  'path/to/file-0.2.0.txt'],
+      #   # ['another_file','path/to/another_file.txt']]
+      #
+      def minimap
+        hash = {}
+        map = []
+        each {|entry| map << (hash[entry_to_minikey(entry)] = [entry]) }
+        minimize(hash.keys) do |key, mini_key|
+          hash[key].unshift mini_key
+        end
+      
+        map
+      end
+    
+      # Returns the first entry whose minikey mini-matches the input, or nil if
+      # no such entry exists.
+      #
+      #   paths = %w{
+      #     path/to/file-0.1.0.txt 
+      #     path/to/file-0.2.0.txt
+      #     path/to/another_file.txt
+      #   }.extend Minimap
+      #
+      #   paths.minimatch('file-0.2.0')       # => 'path/to/file-0.2.0.txt'
+      #   paths.minimatch('file-0.3.0')       # => nil
+      #
+      def minimatch(key)
+        key = key.to_s
+        each do |entry| 
+          return entry if minimal_match?(entry_to_minikey(entry), key)
+        end
+        nil
+      end
+      
+      # Returns minimap as a hash of (minikey, value) pairs.
+      def minihash(reverse=false)
+        hash = {}
+        minimap.each do |key, value|
+          if reverse
+            hash[value] = key
+          else
+            hash[key] = value
+          end
+        end
+        hash
+      end
+    
+      protected
+    
+      # A hook to convert entries to minikeys.  Returns the entry by default, 
+      # or entry.minikey if the entry responds to minikey.
+      def entry_to_minikey(entry)
+        entry.respond_to?(:minikey) ? entry.minikey : entry.to_s
+      end
+    
+      module_function
+    
+      # Minimizes a set of paths to the set of shortest basepaths that unqiuely 
+      # identify the paths.  The path extension and versions are removed from
+      # the basepath if possible.  For example:
+      #
+      #   Minimap.minimize ['path/to/a.rb', 'path/to/b.rb']
+      #   # => ['a', 'b']
+      #
+      #   Minimap.minimize ['path/to/a-0.1.0.rb', 'path/to/b-0.1.0.rb']
+      #   # => ['a', 'b']
+      #
+      #   Minimap.minimize ['path/to/file.rb', 'path/to/file.txt']
+      #   # => ['file.rb', 'file.txt']
+      #
+      #   Minimap.minimize ['path-0.1/to/file.rb', 'path-0.2/to/file.rb']
+      #   # => ['path-0.1/to/file', 'path-0.2/to/file']
+      #
+      # Minimized paths that carry their extension will always carry
+      # their version as well, but the converse is not true; paths
+      # can be minimized to carry just the version and not the path
+      # extension.
+      #
+      #   Minimap.minimize ['path/to/a-0.1.0.rb', 'path/to/a-0.1.0.txt']
+      #   # => ['a-0.1.0.rb', 'a-0.1.0.txt']
+      #
+      #   Minimap.minimize ['path/to/a-0.1.0.rb', 'path/to/a-0.2.0.rb']
+      #   # => ['a-0.1.0', 'a-0.2.0']
+      #
+      # If a block is given, each (path, mini-path) pair will be passed
+      # to it after minimization.
+      def minimize(paths) # :yields: path, mini_path
+        unless block_given?
+          mini_paths = []
+          minimize(paths) {|p, mp| mini_paths << mp }
+          return mini_paths  
+        end
+      
+        splits = paths.uniq.collect do |path|
+          extname = File.extname(path)
+          extname = '' if extname =~ /^\.\d+$/
+          base = File.basename(path.chomp(extname))
+          version = base =~ /(-\d+(\.\d+)*)$/ ? $1 : ''
+        
+          [dirname_or_array(path), base.chomp(version), extname, version, false, path]
+        end
+
+        while !splits.empty?
+          index = 0
+          splits = splits.collect do |(dir, base, extname, version, flagged, path)|
+            index += 1
+            case
+            when !flagged && just_one?(splits, index, base)
+            
+              # found just one
+              yield(path, base)
+              nil
+            when dir.kind_of?(Array)
+            
+              # no more path segments to use, try to add
+              # back version and extname
+              if dir.empty?
+                dir << File.dirname(base)
+                base = File.basename(base)
+              end
+            
+              case
+              when !version.empty?
+                # add back version (occurs first)
+                [dir, "#{base}#{version}", extname, '', false, path]
+              
+              when !extname.empty?
+              
+                # add back extension (occurs second)
+                [dir, "#{base}#{extname}", '', version, false, path]
+              else
+              
+                # nothing more to distinguish... path is minimized (occurs third)
+                yield(path, min_join(dir[0], base))
+                nil
+              end
+            else
+
+              # shift path segment.  dirname_or_array returns an
+              # array if this is the last path segment to shift.
+              [dirname_or_array(dir), min_join(File.basename(dir), base), extname, version, false, path]
+            end
+          end.compact
+        end
+      end
+    
+      # Returns true if the mini_path matches path.  Matching logic reverses
+      # that of minimize:
+      #
+      # * a match occurs when path ends with mini_path
+      # * if mini_path doesn't specify an extension, then mini_path
+      #   must only match path up to the path extension
+      # * if mini_path doesn't specify a version, then mini_path
+      #   must only match path up to the path basename (minus the
+      #   version and extname)
+      #
+      # For example:
+      #
+      #   Minimap.minimal_match?('dir/file-0.1.0.rb', 'file')           # => true
+      #   Minimap.minimal_match?('dir/file-0.1.0.rb', 'dir/file')       # => true
+      #   Minimap.minimal_match?('dir/file-0.1.0.rb', 'file-0.1.0')     # => true
+      #   Minimap.minimal_match?('dir/file-0.1.0.rb', 'file-0.1.0.rb')  # => true
+      #
+      #   Minimap.minimal_match?('dir/file-0.1.0.rb', 'file.rb')        # => false
+      #   Minimap.minimal_match?('dir/file-0.1.0.rb', 'file-0.2.0')     # => false
+      #   Minimap.minimal_match?('dir/file-0.1.0.rb', 'another')        # => false
+      #
+      # In matching, partial basenames are not allowed but partial directories
+      # are allowed.  Hence:
+      #
+      #   Minimap.minimal_match?('dir/file-0.1.0.txt', 'file')          # => true
+      #   Minimap.minimal_match?('dir/file-0.1.0.txt', 'ile')           # => false
+      #   Minimap.minimal_match?('dir/file-0.1.0.txt', 'r/file')        # => true
+      #
+      def minimal_match?(path, mini_path)
+        extname = non_version_extname(mini_path)
+        version = mini_path =~ /(-\d+(\.\d+)*)#{extname}$/ ? $1 : ''
+ 
+        match_path = case
+        when !extname.empty?
+          # force full match
+          path
+        when !version.empty?
+          # match up to version
+          path.chomp(non_version_extname(path))
+        else
+          # match up base
+          path.chomp(non_version_extname(path)).sub(/(-\d+(\.\d+)*)$/, '')
+        end
+      
+        # key ends with pattern AND basenames of each are equal... 
+        # the last check ensures that a full path segment has 
+        # been specified
+        match_path[-mini_path.length, mini_path.length] == mini_path  && File.basename(match_path) == File.basename(mini_path)
+      end
+    
+      # utility method for minimize -- joins the
+      # dir and path, preventing results like:
+      #
+      #   "./path"
+      #   "//path"
+      #
+      def min_join(dir, path) # :nodoc:
+        case dir
+        when "." then path
+        when "/" then "/#{path}"
+        else "#{dir}/#{path}"
+        end
+      end
+    
+      # utility method for minimize -- returns the 
+      # dirname of path, or an array if the dirname
+      # is effectively empty.
+      def dirname_or_array(path) # :nodoc:
+        dir = File.dirname(path)
+        case dir
+        when path, '.' then []
+        else dir
+        end
+      end
+    
+      # utility method for minimize -- determines if there 
+      # is just one of the base in splits, while flagging
+      # all matching entries.
+      def just_one?(splits, index, base) # :nodoc:
+        just_one = true
+        index.upto(splits.length-1) do |i|
+          if splits[i][1] == base
+            splits[i][4] = true
+            just_one = false
+          end
+        end
+      
+        just_one
+      end
+    
+      # utility method for minimal_match --  returns a non-version 
+      # extname, or an empty string if the path ends in a version.
+      def non_version_extname(path) # :nodoc:
+        extname = File.extname(path)
+        extname =~ /^\.\d+$/ ? '' : extname
+      end
+    end
+  end
+end