bahuvrihi-tap 0.10.7 → 0.10.8

data/lib/tap/support/lazydoc/definition.rb

@@ -0,0 +1,36 @@
+module Tap
+  module Support
+    module Lazydoc
+      class Definition < Comment
+        attr_accessor :subclass
+        
+        def configurations(fragment_sep=" ", line_sep="\n", strip=true)
+          lines = []
+          subclass.configurations.each do |receiver, key, config|
+            desc = config.desc
+            case desc
+            when Definition
+              lines << "# #{desc.subclass}"
+              lines.concat desc.original_to_s(fragment_sep, nil, strip).collect {|line| "# #{line}"}
+              lines << "#{key}:"
+              lines.concat desc.configurations(fragment_sep).collect {|line| "  #{line}"}
+            else 
+              lines << "# #{desc}"
+              lines << "#{key}: #{config.default}"
+              lines << ""
+            end
+          end
+          
+          lines
+        end
+        
+        alias original_to_s to_s
+        
+        def to_s(fragment_sep=" ", line_sep="\n", strip=true)
+          lines = [original_to_s(fragment_sep, line_sep, strip)] + configurations(fragment_sep)
+          line_sep ? lines.join(line_sep) : lines
+        end
+      end
+    end
+  end
+end

data/lib/tap/support/lazydoc/document.rb

@@ -3,24 +3,38 @@ require 'tap/support/lazydoc/comment'
 module Tap
   module Support
     module Lazydoc
+      
+      # A Document tracks constant attributes and code comments for a particular
+      # source file.  Documents may be assigned a default_const_name to be used
+      # when a constant attribute does not specify a constant.
+      #
+      #   # KeyWithConst::key value a
+      #   # ::key value b
+      #
+      #   doc = Document.new(__FILE__, 'DefaultConst')
+      #   doc.resolve
+      #   doc['KeyWithConst']['key'].value      # => 'value a'
+      #   doc['DefaultConst']['key'].value      # => 'value b'
+      #
       class Document
-        # The source file for self, used during resolve.
+        
+        # The source file for self, used during resolve
         attr_reader :source_file
       
         # An array of Comment objects identifying lines 
-        # resolved or to-be-resolved for self.
+        # resolved or to-be-resolved
         attr_reader :comments
       
-        # A hash of (const_name, attributes) pairs tracking the constant 
+        # A hash of [const_name, attributes] pairs tracking the constant 
         # attributes resolved or to-be-resolved for self.  Attributes
-        # are hashes of (key, comment) pairs.
+        # are hashes of [key, comment] pairs.
         attr_reader :const_attrs
       
         # The default constant name used when no constant name
-        # is specified for a constant attribute.
+        # is specified for a constant attribute
         attr_reader :default_const_name
       
-        # Flag indicating whether or not self has been resolved.
+        # Flag indicating whether or not self has been resolved
         attr_accessor :resolved
       
         def initialize(source_file=nil, default_const_name='')
@@ -50,9 +64,8 @@ module Tap
         end
       
         # Sets the default_const_name for self.  Any const_attrs assigned to 
-        # the previous default_const_name will be removed from const_attrs 
-        # and merged with any const_attrs already assigned to the new 
-        # default_const_name.
+        # the previous default will be removed and merged with those already 
+        # assigned to the new default.
         def default_const_name=(const_name)
           self[const_name].merge!(const_attrs.delete(@default_const_name) || {})
           @default_const_name = const_name
@@ -72,9 +85,12 @@ module Tap
           end
           names
         end
-
-        # Register the specified line number to self.  Returns a 
-        # comment_class instance corresponding to the line.
+        
+        # Register the specified line number to self.  Register
+        # may take an integer or a regexp for late-evaluation.
+        # See Comment#resolve for more details.
+        # 
+        # Returns a comment_class instance corresponding to the line.
         def register(line_number, comment_class=Comment)
           comment = comments.find {|c| c.class == comment_class && c.line_number == line_number }
         
@@ -85,11 +101,19 @@ module Tap
         
           comment
         end
-      
+        
+        # Registers a regexp matching methods by the specified
+        # name.
         def register_method(method, comment_class=Comment)
           register(/^\s*def\s+#{method}(\W|$)/, comment_class)
         end
       
+        # Scans str for constant attributes and adds them to to self.  Code
+        # comments are also resolved against str.  If no str is specified,
+        # the contents of source_file are used instead.
+        #
+        # Resolve does nothing if resolved == true.  Returns true if str
+        # was resolved, or false otherwise.
         def resolve(str=nil)
           return(false) if resolved
         

data/lib/tap/support/manifest.rb

@@ -1,180 +1,169 @@
-require 'tap/root'
+require 'tap/support/minimap'
 
 module Tap
   module Support
+    
+    # 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
-        def normalize(key)
-          key.to_s.downcase.gsub(/\s/, "_").delete(":")
+        
+        # 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 Support::Intern(:minikey)
+            instance.minikey_block = block
+          end
+          instance
         end
       end
       
       include Enumerable
+      include Minimap
       
-      # An array of (key, value) entries in self.
-      attr_reader :entries
+      # 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 of search_paths to identify entries.
-      attr_reader :search_paths
+      # An array entries in self.
+      attr_reader :entries
       
-      # The index of the search_path that will be searched
-      # next when building the manifest.
-      attr_reader :search_path_index
+      # The bound Tap::Env, or nil.
+      attr_reader :env
       
-      def initialize(search_paths)
-        self.search_paths = search_paths
-      end
+      # The reader on Tap::Env accessing manifests of the
+      # same type as self. reader is set during bind.
+      attr_reader :reader
       
-      # Returns an array of the entries keys.
-      def keys
-        entries.collect {|(key, value)| key }
+      # Initializes a new, unbound Manifest.
+      def initialize(entries=[])
+        @entries = entries
+        @env = nil
+        @reader = nil
       end
       
-      # Returns an array of the entries values.
-      def values
-        entries.collect {|(key, value)| value }
-      end
-      
-      # True if entries are empty.
-      def empty?
-        entries.empty?
+      # 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
       
-      # Sets the search_paths for self.  Setting search_paths
-      # clears all entries and puts search_path_index to zero.
-      def search_paths=(search_paths)
-        @entries = []
-        @search_paths = search_paths
-        @search_path_index = 0
+      # Unbinds self from env.  Returns self.
+      def unbind
+        @env = nil
+        @reader = nil
+        self
       end
       
-      # Clears entries and sets the search_path_index to zero.
-      def reset
-        @entries.clear
-        @search_path_index = 0
+      # True if the env and reader have been set.
+      def bound?
+        @env != nil && @reader != nil
       end
       
-      # Builds the manifest, identifying all entries from search_paths.
-      # Returns self.
+      # A hook for dynamically building entries.  By default build simply
+      # returns self
       def build
-        each {|k, v|} unless built?
         self
       end
       
-      # True if all search paths have been checked for entries
-      # (ie search_path_index == search_paths.length).
+      # A hook to flag when self is built.  By default built? returns true.
       def built?
-        @search_path_index == search_paths.length
+        true
       end
       
-      # Abstract method which should return each (key, value) entry
-      # for a given search path.  Raises a NotImplementedError
-      # if left not implemented.
-      def entries_for(search_path)
-        [[search_path, search_path]]
+      # A hook to reset a build.  By default reset simply returns self.
+      def reset
+        self
       end
       
-      # Adds the (key, value) pair to entries and returns the new entry.
-      # Checks that entries does not already assign key a conflicting value;
-      # raises an error if this is the case, or returns the existing entry.
-      #
-      # Keys are normalized using Manifest.normalize before storing.
-      def store(key, value)
-        key = Manifest.normalize(key)
-        existing = entries.find {|(k, v)| key == k } 
-        
-        if existing
-          if existing[1] != value
-            raise ManifestConflict.new(key, value, existing[1])
-          else
-            return existing
-          end
-        end
-        
-        new_entry = [key, value]
-        entries << new_entry
-        new_entry
+      # True if entries are empty.
+      def empty?
+        entries.empty?
       end
       
-      # Iterates over each (key, value) entry in self, dynamically 
-      # identifying entries from search_paths if necessary.  New 
-      # entries are identifed using the each_for method.
+      # Iterates over each entry entry in self.
       def each
-        entries.each do |key, path| 
-          yield(key, path) 
-        end
-        
-        unless built?
-          n_to_skip = @search_path_index
-          search_paths.each do |search_path|
-            # advance to the current search path
-            if n_to_skip > 0
-              n_to_skip -= 1
-              next
-            end
-            @search_path_index += 1
-            
-            # collect new entries and yield afterwards to ensure
-            # that all entries for the search_path get stored
-            new_entries = entries_for(*search_path)
-            next if new_entries == nil
-            
-            new_entries.each {|(key, value)| store(key, value) }
-            new_entries.each {|(key, value)| yield(key, value) }
-          end
-        end
+        entries.each {|entry| yield(entry) }
       end
       
-      # Returns an array of (mini_key, value) pairs, matching
-      # entries by index.
-      def minimize
-        hash = {}
-        Tap::Root.minimize(keys) do |path, mini_path|
-          hash[path] = mini_path
-        end
-        
-        entries.collect {|path, value| [hash[path], value] }
+      # Alias for Minimap#minimatch.
+      def [](key)
+        minimatch(key)
       end
       
-      # Returns the first [key, value] entry where the key mini-matches 
-      # the input pattern, or nil if no matching entry is found.  This
-      # method identifies new entries as in each, as needed.
+      # 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.
       #
-      # See Tap::Root.minimal_match? for details on mini-matching.
-      def [](pattern)
-        each do |key, value| 
-          return [key, value] if Root.minimal_match?(key, pattern)
-        end
-        nil
-      end
-      
-      def inspect
-        lines = ["", "search paths:"]
-        search_paths.each_with_index do |path, index|
-          indent = (index == search_path_index ? "* " : "  ")
-          lines << (indent + path.inspect)
+      # 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
         
-        lines << ""
-        lines << "mini-entries:"
-        minimize.each do |mini, value| 
-          lines << "  #{mini}: #{value.inspect}"
+        # 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
-        lines << ""
         
-        "#{self.class}:#{object_id} #{lines.join("\n")}"
+        nil
       end
-
-      # Raised when multiple paths are assigned to the same manifest key.
-      class ManifestConflict < StandardError
-        attr_reader :key, :value, :existing
+      
+      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
         
-        def initialize(key, value, existing)
-          @key = key
-          @value = value
-          @existing = existing
-          super("attempted to store '%s': %s\nbut already was\n%s" % [key, value, existing])
+        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/tap/support/minimap.rb

@@ -0,0 +1,90 @@
+require 'tap/root'
+
+module Tap
+  module Support
+    
+    # Minimap adds minimization and search methods to an array of paths (see 
+    # Tap::Root.minimize and Tap::Root.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 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 Minimap
+    #
+    #     def minikey(const)
+    #       const.underscore
+    #     end
+    #   end 
+    #
+    #   constants = ConstantMap[Tap::Support::Minimap Tap::Root]
+    #   constants.minimatch('root')         # => Tap::Root
+    #   constants.minimatch('minimap')      # => Tap::Support::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[minikey(entry)] = [entry]) }
+        Tap::Root.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)
+        each do |entry| 
+          return entry if Tap::Root.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
+end