tap 0.18.0 → 0.19.0

data/lib/tap/env/constant.rb

@@ -17,10 +17,10 @@ module Tap
     # === 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.
+    # various development modes, but may cause code to behave unpredictably.
+    # When a Constant unloads, the constant value is removed from the nesting
+    # constant and the require paths are removed from $".  This allows a
+    # require statement to re-require, and in theory, reload the constant.
     #
     #   # [simple.rb]
     #   # class Simple
@@ -39,6 +39,17 @@ module Tap
     # 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.
+    #
+    #--
+    # ==== Rationale for that last statement
+    #
+    # Scripts that require other files will not re-require the other files
+    # because unload doesn't remove the other files from $".  Likewise scripts
+    # that define other constants effectively overwrite the existing constant;
+    # that may or may not be a big deal, but it can cause warnings.  Moreover,
+    # if a script actually DOES something (like create a file), that something
+    # will be repeated when it gets re-required.
+    #
     class Constant
       class << self
       
@@ -72,12 +83,40 @@ module Tap
           end
           const
         end
+        
+        # Scans the directory and pattern for constants and adds them to the
+        # constants hash by name.
+        def scan(dir, pattern="**/*.rb", constants={})
+          if pattern.include?("..")
+            raise "patterns cannot include relative paths: #{pattern.inspect}"
+          end
+          
+          # note changing dir here makes require paths relative to load_path,
+          # hence they can be directly converted into a default_const_name
+          # rather than first performing Root.relative_path
+          Dir.chdir(dir) do
+            Dir.glob(pattern).each do |path| 
+              default_const_name = path.chomp(File.extname(path)).camelize
+
+              # scan for constants
+              Lazydoc::Document.scan(File.read(path)) do |const_name, type, summary|
+                const_name = default_const_name if const_name.empty?
+
+                constant = (constants[const_name] ||= Constant.new(const_name))
+                constant.register_as(type, summary)
+                constant.require_paths << path
+              end
+            end
+          end
+          
+          constants
+        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.
+        # The implementation 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:
@@ -96,19 +135,20 @@ module Tap
       # 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
+      # An array of paths that will be required when the constantize is called
+      # and the constant does not exist.  Require paths are required in order.
+      attr_reader :require_paths
+      
+      # A hash of (type, summary) pairs used to classify self.
+      attr_reader :types
     
       # 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)
+      def initialize(const_name, *require_paths)
         @const_name = const_name
-        @require_path = require_path
-        @comment = comment
+        @require_paths = require_paths
+        @types = {}
       end
     
       # Returns the underscored const_name.
@@ -158,35 +198,45 @@ module Tap
       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
+        another.require_paths == self.require_paths
       end
     
+      # Registers the type and summary with self.  Raises an error if self is
+      # already registerd as the type and override is false.
+      def register_as(type, summary=nil, override=false)
+        if types.include?(type) && !override
+          raise "already registered as a #{type.inspect}"
+        end
+        
+        types[type] = summary
+        self
+      end
+      
       # Looks up and returns the constant indicated by const_name. If the
-      # constant cannot be found, constantize requires require_path and
-      # tries again.
+      # constant cannot be found, constantize requires the require_paths
+      # in order and tries again.
       #
       # Raises a NameError if the constant cannot be found.
-      def constantize
+      def constantize(autorequire=true)
         Constant.constantize(const_name) do
-          require require_path if require_path
+          break unless autorequire
+          
+          require_paths.each do |require_path|
+            require require_path
+          end
+          
           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 $".
+      # are not removed.  If specified, the require_paths 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).
@@ -199,10 +249,10 @@ module Tap
         const = nesting.empty? ? Object : Constant.constantize(nesting) { Object }
       
         if const.const_defined?(name)
-          if unrequire && require_path
+          require_paths.each do |require_path|
             path = File.extname(require_path).empty? ? "#{require_path}.rb" : require_path
             $".delete(path)
-          end
+          end if unrequire
         
           return const.send(:remove_const, name)
         end
@@ -215,12 +265,12 @@ module Tap
       #   "#<Tap::Env::Constant:object_id Const::Name (require_path)>"
       #
       def inspect
-        "#<#{self.class}:#{object_id} #{const_name}#{@require_path == nil ? "" : " (#{@require_path})"}>"
+        "#<#{self.class}:#{object_id} #{const_name} #{require_paths.inspect}>"
       end
       
-      # Returns the minikey for self, ie path.  (see Tap::Env::Minimap)
-      def minikey
-        path
+      # Returns const_name
+      def to_s
+        const_name
       end
     end
   end

data/lib/tap/env/context.rb

@@ -0,0 +1,61 @@
+module Tap
+  class Env
+    
+    # Context instances track information shared by a set of Env instances, for
+    # instance cached manifest data.  Caching cross-env data in a shared space
+    # simplifies managment of this data, especially when dumping and loading it
+    # from a static file.
+    #
+    # Contexts also ensure that only one env in initialized to a given
+    # directory (at least among envs that share the same context). This
+    # prevents errors that arise when one env eventually nests itself.
+    class Context
+      
+      # A hash of cached manifest data
+      attr_reader :cache
+      
+      # The config file basename
+      attr_reader :basename
+      
+      # An array of Env instances registered with self
+      attr_reader :instances
+      
+      # Initializes a new Context.  Options can specify a cache or a basename.
+      def initialize(options={})
+        options = {
+          :cache => {},
+          :basename => nil
+        }.merge(options)
+        
+        @cache = options[:cache]
+        @basename = options[:basename]
+        @instances = []
+      end
+      
+      # Registers env with self by adding env to instances.  Raises an error
+      # if instances contains an env with the same root directory.
+      def register(env)
+        path = env.root.root
+        
+        if instance(path)
+          raise "context already has an env for: #{path}"
+        end
+        
+        instances << env
+        self
+      end
+      
+      # Gets the instance for the directory currently in instances, or nil
+      # if such an instance does not exist.
+      def instance(dir)
+        instances.find {|env| env.root.root == dir }
+      end
+      
+      # Returns the config filepath for the directory (ie basename under dir).
+      # If basename is nil, then config_file always return nil.
+      def config_file(dir)
+        basename ? File.join(dir, basename) : nil
+      end
+    end
+  end
+end

data/lib/tap/env/manifest.rb

@@ -1,89 +1,179 @@
 require 'tap/env/minimap'
-require 'tap/env/constant'
 
 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
-      include Minimap
       
-      # The environment this manifest summarizes
+      # 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
       
-      attr_reader :type
+      # 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
       
-      # Initializes a new Manifest.
-      def initialize(env, type)
-        @env = env
-        @type = type
-      end
+      # 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 entries
-        env.registry[type]
+      def initialize(env, builder, cache={})
+        @env = env
+        @builder = builder
+        @cache = cache
+        
+        cache.each_value do |value|
+          ensure_minimap(value)
+        end
       end
       
-      # True if entries are empty.
-      def empty?
-        entries.empty?
+      # Builds the manifest for each env in env.
+      def build
+        self.env.each {|env| entries(env) }
+        self
       end
       
-      def all_empty?
-        env.all? do |current|
-          current.manifest(type).empty?
+      # 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
       
-      # Iterates over each entry in self.
+      # Yields each entry for each env to the block.
       def each
-        entries.each {|entry| yield(entry) }
+        self.env.each do |env|
+          entries(env).each do |entry|
+            yield(entry)
+          end
+        end
       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'.
+
+      # 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, value_only=true)
-        env.seek(type, key, value_only)
+      # 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
       
-      def [](key)
-        entry = seek(key)
-        entry.kind_of?(Constant) ? entry.constantize : entry
+      # 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
       
-      # Same as env.inspect but adds manifest to the templater
-      def inspect(template=nil, globals={}, filename=nil)
-        return super() unless template
+      # 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]
 
-        env.inspect(template, globals, filename) do |templater, globalz|
-          env = templater.env
-          templater.manifest = env.manifest(type)
-          yield(templater, globalz) if block_given?
-        end
-      end
+          minimap = entries(templater.env).minimap
 
-      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 %>
-}
+          if block_given?
+            minimap.collect! do |key, entry| 
+              entry = yield(entry)
+              entry ? [key, entry] : nil
+            end
+            minimap.compact! 
+          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|
+          minimap.each do |key, entry|
             width = key.length if width < key.length
-            [key, entry]
           end
 
           globals[:width] = width
-          globals[:count] += 1 unless templater.entries.empty?
+          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