tap 0.19.0 → 1.3.0

data/lib/tap/env/manifest.rb

@@ -1,179 +0,0 @@
-require 'tap/env/minimap'
-
-module Tap
-  class Env
-    
-    # Manifests provide concise access to resources within a nested Env.
-    class Manifest
-      class << self
-        
-        # Interns a new Manifest using the block as the builder.
-        def intern(env, cache={}, &block)
-          new(env, block, cache)
-        end
-      end
-      
-      include Enumerable
-      
-      # Matches a compound registry search key.  After the match, if the key is
-      # compound then:
-      #
-      #  $1:: env_key
-      #  $2:: key
-      #
-      # If the key is not compound, $2 is nil and $1 is the key.
-      COMPOUND_KEY = /^((?:[A-z]:(?:\/|\\))?.*?)(?::(.*))?$/
-      
-      # The default summary template
-      DEFAULT_TEMPLATE = %q{<% if !minimap.empty? && count > 1 %>
-<%= env_key %>:
-<% end %>
-<% minimap.each do |key, entry| %>
-  <%= key.ljust(width) %> # <%= entry %>
-<% end %>
-}
-      
-      # The Env queried for manifest data
-      attr_reader :env
-      
-      # An object that responds to call, typically a block, that recieves
-      # an env and returns an array of resources, each of which must be
-      # minimappable.  Alternatively, the builder may return a Minimap.
-      attr_reader :builder
-      
-      # A cache of (dir, [entries]) pairs mapping the root of an env
-      # to the array of resources associated with the env.
-      attr_reader :cache
-      
-      def initialize(env, builder, cache={})
-        @env = env
-        @builder = builder
-        @cache = cache
-        
-        cache.each_value do |value|
-          ensure_minimap(value)
-        end
-      end
-      
-      # Builds the manifest for each env in env.
-      def build
-        self.env.each {|env| entries(env) }
-        self
-      end
-      
-      # Returns the entries associated with env.  If no entries are currently
-      # registered to env, the env is passed to the builder and the results
-      # stored in the cache.
-      def entries(env)
-        cache[env] ||= begin
-          ensure_minimap builder.call(env)
-        end
-      end
-      
-      # Yields each entry for each env to the block.
-      def each
-        self.env.each do |env|
-          entries(env).each do |entry|
-            yield(entry)
-          end
-        end
-      end
-
-      # Searches for the first entry mini-matching the key. A single env can 
-      # be specified by using a compound key like 'env_key:key'.
-      #
-      # If a block is provided, each matching entry is yielded until the
-      # block returns true.  Set env_also to true to return an array like
-      # [env, entry], where env is the env where the entry was found.
-      #
-      # Returns nil if no matching entry is found.  
-      def seek(key, env_also=false)
-        key =~ COMPOUND_KEY
-        envs = if $2
-          # compound key, match for env
-          key = $2
-          [env.minimatch($1)].compact
-        else
-          # not a compound key, search all envs by iterating env
-          env
-        end
-
-        # traverse envs looking for the first
-        # manifest entry matching key
-        envs.each do |env|
-          if entry = entries(env).minimatch(key)
-            next if block_given? && !yield(entry)
-            return env_also ? [env, entry] : entry
-          end
-        end
-
-        nil
-      end
-      
-      # Unseek looks up the key identifying a specific entry.  The entry is
-      # identified by the block, which receives each entry (in order) until
-      # the block returns true.  Returns nil if no entry returns true.
-      #
-      # The env key will be prepended to the result if env_also is set to true.
-      def unseek(env_also=false)
-        self.env.each do |env|
-          objects = entries(env)
-          if value = objects.find {|entry| yield(entry) }
-            key = objects.minihash(true)[value]
-            return env_also ? "#{env.minihash(true)[env]}:#{key}" : key
-          end
-        end
-
-        nil
-      end
-      
-      # Generates a summary of the entries in self.  Summarize uses the inspect
-      # functionality of Env to format the entries for each env in order; the
-      # results are concatenated.
-      #
-      # The template should be ERB; it will have the following local variables:
-      #
-      #   env        the current env being summarized
-      #   minimap    an array of [key, entry] pairs representing
-      #              the minipaths and entries for the env
-      #   width      the maximum width of any key across all envs
-      #   count      the number of envs with at least one entry
-      #
-      # A block may be given to filter and pre-process minimap entries.  Each
-      # (key, entry) pair will be yielded to the block; the block return
-      # replaces the entry and any pairs that return nil are removed.  
-      #
-      def summarize(template=DEFAULT_TEMPLATE)
-        env.inspect(template, :width => 11, :count => 0) do |templater, globals|
-          width = globals[:width]
-
-          minimap = entries(templater.env).minimap
-
-          if block_given?
-            minimap.collect! do |key, entry| 
-              entry = yield(entry)
-              entry ? [key, entry] : nil
-            end
-            minimap.compact! 
-          end
-
-          minimap.each do |key, entry|
-            width = key.length if width < key.length
-          end
-
-          globals[:width] = width
-          globals[:count] += 1 unless minimap.empty?
-
-          templater.minimap = minimap
-        end
-      end
-      
-      private
-      
-      # helper to make obj into a minimap if necessary
-      def ensure_minimap(obj) # :nodoc:
-        obj.kind_of?(Minimap) ? obj : obj.extend(Minimap)
-      end
-    end
-  end
-end

data/lib/tap/env/minimap.rb

@@ -1,308 +0,0 @@
-module Tap
-  class Env
-    
-    # Minimap adds minimization and search methods to an array of paths.  The
-    # minimized paths are refered to as 'minipaths' and represent the shortest
-    # basename that uniquely identifies a path within a collection of paths.
-    # File extensions and versions are removed when possible.
-    # 
-    #   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.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']]
-    #
-    # Minipaths can be used as keys to uniquely match a path.  Longer, more
-    # complete paths may also be used (they add specificity, even though it
-    # is not needed).  Likewise shorter paths may be used; the minimatch
-    # method returns the first matching path.
-    #
-    #   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('to/another_file')  # => 'path/to/another_file.txt'
-    #
-    # === Usage
-    #
-    # Minimap may extend any object responding to each, or be included in
-    # classes that implement each.  Non-string entries are converted to paths
-    # by calling entry.path, if entry responds to path, or entry.to_s if it
-    # does not.  Override the entry_to_path method to change this default
-    # behavior.
-    #
-    #   class ConstantMap < Array
-    #     include Env::Minimap
-    #
-    #     def entry_to_path(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
-
-      # Determines the minipaths for each entry in self and returns a mapping
-      # of the minipaths to their corresponding entry.
-      #
-      #   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_path(entry)] = [entry]) }
-        minimize(hash.keys) do |key, mini_key|
-          hash[key].unshift mini_key
-        end
-      
-        map
-      end
-    
-      # Returns the first entry that 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_path(entry), key)
-        end
-        nil
-      end
-      
-      # Returns minimap as a hash of (minipath, 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 paths.  Returns entry.to_s by default, 
-      # or entry.path if the entry responds to path.
-      def entry_to_path(entry)
-        entry.respond_to?(:path) ? entry.path : entry.to_s
-      end
-    
-      module_function
-    
-      # Determines the shortest basepaths that unqiuely identifies a path
-      # within a collection of 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, minipath) pair will be passed
-      # to it after minimization.
-      def minimize(paths) # :yields: path, minipath
-        unless block_given?
-          minipaths = []
-          minimize(paths) {|path, minipath| minipaths << minipath }
-          return minipaths  
-        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 minipath matches path.  Matching logic reverses
-      # that of minimize:
-      #
-      # * a match occurs when path ends with minipath
-      # * if minipath doesn't specify an extension, then minipath
-      #   must only match path up to the path extension
-      # * if minipath doesn't specify a version, then minipath
-      #   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, minipath)
-        extname = non_version_extname(minipath)
-        version = minipath =~ /(-\d+(\.\d+)*)#{extname}$/ ? $1 : ''
- 
-        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 to base
-          path.chomp(non_version_extname(path)).sub(/(-\d+(\.\d+)*)$/, '')
-        end
-      
-        # match if path ends with minipath. note the basename check ensures a full
-        # path segment has been specified. (ex: 'ile' should not match 'file.txt')
-        path[-minipath.length, minipath.length] == minipath && File.basename(path) == File.basename(minipath)
-      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