root 0.0.1

data/lib/root/constant_manifest.rb

@@ -0,0 +1,126 @@
+require 'lazydoc'
+require 'root/manifest'
+require 'root/constant'
+require 'root/utils'
+
+class Root
+  
+  # :startdoc:::-
+  #
+  # ConstantManifest builds a manifest of Constant entries using Lazydoc.
+  #
+  # Lazydoc can quickly scan files for constant attributes, and thereby
+  # identify constants based upon a flag like the '::manifest' attribute used
+  # to identify task classes.  ConstantManifest registers paths that will be
+  # scanned for a specific resource, and lazily builds the references to load
+  # them as necessary.
+  # 
+  # :startdoc:::+
+  class ConstantManifest < Manifest
+    
+    # The attribute identifying constants in a file
+    attr_reader :const_attr
+    
+    # An array of registered (root, [paths]) pairs
+    # that will be searched for const_attr
+    attr_reader :search_paths
+    
+    # The current index of search_paths
+    attr_reader :search_path_index
+    
+    # The current index of paths
+    attr_reader :path_index
+    
+    # Initializes a new ConstantManifest that will identify constants
+    # using the specified constant attribute.
+    def initialize(const_attr)
+      @const_attr = const_attr
+      @search_paths = []
+      @search_path_index = 0
+      @path_index = 0
+      super([])
+    end
+    
+    # Registers the files matching pattern under dir.  Returns self.
+    def register(dir, pattern)
+      paths = Dir.glob(File.join(dir, pattern)).select {|file| File.file?(file) }
+      search_paths << [dir, paths.sort]
+      self
+    end
+    
+    # Searches all paths for entries and adds them to self.  Returns self.
+    def build
+      each {|entry| } unless built?
+      self
+    end
+    
+    # True if there are no more paths to search 
+    # (ie search_path_index == search_paths.length)
+    def built?
+      search_path_index == search_paths.length
+    end
+    
+    # Sets search_path_index and path_index to zero and clears entries.
+    # Returns self.
+    def reset
+      @search_paths.each {|path| Lazydoc[path].resolved = false }
+      @entries.clear
+      @search_path_index = 0
+      @path_index = 0
+      super
+    end
+    
+    # Yields each Constant entry to the block.  Unless built?, each
+    # lazily iterates over search_paths to look for new entries.
+    def each
+      entries.each do |entry|
+        yield(entry)
+      end
+      
+      search_paths[search_path_index, search_paths.length - search_path_index].each do |(path_root, paths)|
+        paths[path_index, paths.length - path_index].each do |path|
+          new_entries = resolve(path_root, path)
+          entries.concat(new_entries)
+          
+          @path_index += 1
+          new_entries.each {|entry| yield(entry) }
+        end
+        
+        @search_path_index += 1
+        @path_index = 0
+      end unless built?
+    end
+    
+    protected
+    
+    def minikey(const) # :nodoc:
+      const.path
+    end
+    
+    # Scans path for constants having const_attr, and initializes Constant
+    # objects for each.   If the document has no default_const_name set,
+    # resolve will set the default_const_name based on the relative
+    # filepath from path_root to path.
+    def resolve(path_root, path) # :nodoc:
+      entries = []
+      document = nil
+      
+      Lazydoc::Document.scan(File.read(path), const_attr) do |const_name, key, value|
+        if document == nil
+          relative_path = Utils.relative_filepath(path_root, path).chomp(File.extname(path))
+          document = Lazydoc.register_file(path, relative_path.camelize)
+        end
+        
+        const_name = document.default_const_name if const_name.empty? 
+        comment = Lazydoc::Subject.new(nil, document)
+        comment.value = value
+        
+        document[const_name][key] = comment
+        entries << Constant.new(const_name, path)
+      end
+      
+      entries
+    end
+    
+  end
+end

data/lib/root/gems.rb

@@ -0,0 +1,40 @@
+require 'rubygems'
+
+class Root
+  
+  # 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 
+    # will be activated using +gem+ if necessary.
+    def gemspec(gem_name)
+      return gem_name if gem_name.kind_of?(Gem::Specification)
+      
+      # figure the version of the gem, by default >= 0.0.0
+      gem_name.to_s =~ /^([^<=>]*)(.*)$/
+      name, version = $1.strip, $2
+      version = ">= 0.0.0" if version.empty?
+      
+      return nil if name.empty?
+      
+      # load the gem and get the spec
+      gem(name, version)
+      Gem.loaded_specs[name]
+    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)
+      index = latest ?
+        Gem.source_index.latest_specs :
+        Gem.source_index.gems.collect {|(name, spec)| spec }
+      
+      index.select do |spec|
+        yield(spec)
+      end.sort
+    end
+  end
+end

data/lib/root/intern.rb

@@ -0,0 +1,36 @@
+class Root
+  # Generates an Intern module for the specified method_name.
+  #
+  # An Intern module:
+  #
+  # - adds an accessor for <method_name>_block
+  # - overrides <method_name> to call the block
+  #
+  def self.Intern(method_name)
+    mod = INTERN_MODULES[method_name.to_sym]
+    return mod unless mod == nil
+    
+    mod = INTERN_MODULES[method_name.to_sym] = Module.new
+    mod.module_eval %Q{
+    attr_accessor :#{method_name}_block
+
+    def #{method_name}(*inputs)
+      raise "no #{method_name} block set" unless #{method_name}_block
+      inputs.unshift(self)
+    
+      arity = #{method_name}_block.arity
+      n = inputs.length
+      unless n == arity || (arity < 0 && (-1-n) <= arity) 
+        raise ArgumentError.new("wrong number of arguments (\#{n} for \#{arity})")
+      end
+    
+      #{method_name}_block.call(*inputs)
+    end
+    }
+    mod
+  end
+  
+  # An array of already-declared intern modules,
+  # keyed by method_name.
+  INTERN_MODULES = {}
+end

data/lib/root/manifest.rb

@@ -0,0 +1,168 @@
+require 'root/minimap'
+require 'root/intern'
+
+class Root
+    
+  # Stores an array of paths and makes them available for lookup by minipath.
+  # Manifests may be bound to a Tap::Env, allowing searches across a full
+  # environment (including nested environments).
+  #
+  # Manifest has a number of hooks used by subclasses like ConstantManifest
+  # to lazily add entries as needed.
+  class Manifest
+    class << self
+      
+      # Interns a new manifest, overriding the minikey method with the block
+      # (the minikey method converts entries to the path used during minimap
+      # and minimatch lookup, see Minimap).
+      def intern(*args, &block)
+        instance = new(*args)
+        if block_given?
+          instance.extend Intern(:minikey)
+          instance.minikey_block = block
+        end
+        instance
+      end
+    end
+    
+    include Enumerable
+    include Minimap
+    
+    # Matches a compound manifest search key.  After the match, if the key is
+    # compound then:
+    #
+    #  $1:: env_key
+    #  $4:: key
+    #
+    # If the key is not compound, $4 is nil and $1 is the key.
+    SEARCH_REGEXP = /^(([A-z]:)?.*?)(:(.*))?$/
+    
+    # An array entries in self.
+    attr_reader :entries
+    
+    # The bound Env, or nil.
+    attr_reader :env
+    
+    # The reader on Env accessing manifests of the same type as this value.
+    # Reader is set during bind.
+    attr_reader :reader
+    
+    # Initializes a new, unbound Manifest.
+    def initialize(entries=[])
+      @entries = entries
+      @env = nil
+      @reader = nil
+    end
+    
+    # Binds self to an env and reader.  The manifests returned by env.reader
+    # will be used during traversal methods like search.  Raises an error if
+    # env does not respond to reader; returns self.
+    def bind(env, reader)
+      if env == nil
+        raise ArgumentError, "env may not be nil" 
+      end
+      
+      unless env.respond_to?(reader)
+        raise ArgumentError, "env does not respond to #{reader}"
+      end
+      
+      @env = env
+      @reader = reader
+      self
+    end
+    
+    # Unbinds self from env.  Returns self.
+    def unbind
+      @env = nil
+      @reader = nil
+      self
+    end
+    
+    # True if the env and reader have been set.
+    def bound?
+      @env != nil && @reader != nil
+    end
+    
+    # A hook for dynamically building entries.  By default build simply
+    # returns self
+    def build
+      self
+    end
+    
+    # A hook to flag when self is built.  By default built? returns true.
+    def built?
+      true
+    end
+    
+    # A hook to reset a build.  By default reset simply returns self.
+    def reset
+      self
+    end
+    
+    # True if entries are empty.
+    def empty?
+      entries.empty?
+    end
+    
+    # Iterates over each entry entry in self.
+    def each
+      entries.each {|entry| yield(entry) }
+    end
+    
+    # Alias for Minimap#minimatch.
+    def [](key)
+      minimatch(key)
+    end
+    
+    # Search 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.
+    #
+    # Search raises an error unless bound?
+    def search(key)
+      raise "cannot search unless bound" unless bound?
+      
+      key =~ SEARCH_REGEXP
+      envs = if $4 != nil
+        # compound key, match for env
+        key = $4
+        [env.minimatch($1)].compact
+      else
+        # not a compound key, search all
+        # envs by iterating env itself
+        env
+      end
+      
+      # traverse envs looking for the first
+      # manifest entry matching key
+      envs.each do |env|
+        if result = env.send(reader).minimatch(key)
+          return result
+        end
+      end
+      
+      nil
+    end
+    
+    def inspect(traverse=true)
+      if traverse && bound?
+        lines = []
+        env.each do |env|
+          manifest = env.send(reader).build
+          next if manifest.empty?
+          
+          lines << "== #{env.root.root}"
+          manifest.minimap.each do |mini, value| 
+            lines << "  #{mini}: #{value.inspect}"
+          end
+        end
+        return lines.join("\n")
+      end
+      
+      lines = minimap.collect do |mini, value| 
+        "  #{mini}: #{value.inspect}"
+      end
+      "#{self.class}:#{object_id} (#{bound? ? env.root.root : ''})\n#{lines.join("\n")}"
+    end
+  end
+end

data/lib/root/minimap.rb

@@ -0,0 +1,88 @@
+require 'root/utils'
+
+class Root
+    
+  # Minimap adds minimization and search methods to an array of paths (see
+  # Utils.minimize and Utils.minimal_match?).
+  # 
+  #   paths = %w{
+  #     path/to/file-0.1.0.txt 
+  #     path/to/file-0.2.0.txt
+  #     path/to/another_file.txt
+  #   }
+  #   paths.extend Root::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.
+  # Override the minikey method to convert objects into paths.
+  #
+  #   class ConstantMap < Array
+  #     include Root::Minimap
+  #
+  #     def minikey(const)
+  #       const.underscore
+  #     end
+  #   end 
+  #
+  #   constants = ConstantMap[Root::Minimap, Root]
+  #   constants.minimatch('root')         # => Root
+  #   constants.minimatch('minimap')      # => Root::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 Root::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[minikey(entry)] = [entry]) }
+      Utils.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 Root::Minimap
+    #
+    #   paths.minimatch('file-0.2.0')       # => 'path/to/file-0.2.0.txt'
+    #   paths.minimatch('file-0.3.0')       # => nil
+    #
+    def minimatch(key)
+      each do |entry| 
+        return entry if Utils.minimal_match?(minikey(entry), key)
+      end
+      nil
+    end
+    
+    protected
+    
+    # A hook to convert a non-path entry into a path for minimap and
+    # minimatch.  Returns the entry by default.
+    def minikey(entry)
+      entry
+    end
+  end
+end