tap 0.10.1 → 0.11.0

data/lib/tap/support/configurable_class.rb

@@ -1,14 +1,15 @@
 require 'tap/support/class_configuration'
 require 'tap/support/validation'
 require 'tap/support/lazy_attributes'
+require 'tap/support/lazydoc/config'
 
 module Tap
   module Support
     autoload(:Templater, 'tap/support/templater')
     
-    # ConfigurableClass encapsulates class methods used to declare class configurations. 
-    # When configurations are declared using the config method, ConfigurableClass 
-    # generates accessors in the class, much like attr_accessor.  
+    # ConfigurableClass defines class methods used by a Configurable class to
+    # declare configurations.  In addition to registering key-value pairs,
+    # these methods generate readers and writers, much like attr_accessor.  
     #
     #   class ConfigurableClass
     #     extend ConfigurableClass
@@ -21,31 +22,6 @@ module Tap
     #   c.respond_to?('one')                       # => true
     #   c.respond_to?('one=')                      # => true
     # 
-    # If a block is given, the block will be used to create the writer method
-    # for the config.  Used in this manner, config defines a <tt>config_key=</tt> method 
-    # wherein <tt>@config_key</tt> will be set to the return value of the block.
-    #
-    #   class AnotherConfigurableClass
-    #     extend ConfigurableClass
-    #     config(:one, 'one') {|value| value.upcase }
-    #   end
-    #
-    #   ac = AnotherConfigurableClass.new
-    #   ac.one = 'value'
-    #   ac.one               # => 'VALUE'
-    #
-    # The block has class-context in this case.  To have instance-context, use the
-    # config_attr method which defines the writer method using the block directly.
-    #
-    #   class YetAnotherConfigurableClass
-    #     extend ConfigurableClass
-    #     config_attr(:one, 'one') {|value| @one = value.reverse }
-    #   end
-    #
-    #   ac = YetAnotherConfigurableClass.new
-    #   ac.one = 'value'
-    #   ac.one               # => 'eulav'
-    #
     module ConfigurableClass
       include Tap::Support::LazyAttributes
       
@@ -53,11 +29,11 @@ module Tap
       attr_reader :configurations
 
       # Sets the source_file for base and initializes base.configurations.
-      def self.extended(base)
+      def self.extended(base) # :nodoc:
         caller.each_with_index do |line, index|
           case line
           when /\/configurable.rb/ then next
-          when /^(([A-z]:)?[^:]+):(\d+)/
+          when Lazydoc::CALLER_REGEXP
             base.instance_variable_set(:@source_file, File.expand_path($1))
             break
           end
@@ -69,9 +45,9 @@ module Tap
       # When subclassed, the parent.configurations are duplicated and passed to 
       # the child class where they can be extended/modified without affecting
       # the configurations of the parent class.
-      def inherited(child)
+      def inherited(child) # :nodoc:
         unless child.instance_variable_defined?(:@source_file)
-          caller.first =~ /^(([A-z]:)?[^:]+):(\d+)/
+          caller.first =~ Lazydoc::CALLER_REGEXP
           child.instance_variable_set(:@source_file, File.expand_path($1)) 
         end
         
@@ -79,6 +55,7 @@ module Tap
         super
       end
       
+      # Returns the lazydoc for self.
       def lazydoc(resolve=true)
         Lazydoc.resolve_comments(configurations.code_comments) if resolve
         super
@@ -87,8 +64,8 @@ module Tap
       # Loads the contents of path as YAML.  Returns an empty hash if the path 
       # is empty, does not exist, or is not a file.
       def load_config(path)
-        return {} if path == nil || !File.file?(path)
-
+        # the last check prevents YAML from auto-loading itself for empty files
+        return {} if path == nil || !File.file?(path) || File.size(path) == 0
         YAML.load_file(path) || {}
       end
       
@@ -250,8 +227,8 @@ module Tap
         caller.each do |line|
           case line
           when /in .config.$/ then next
-          when /^(([A-z]:)?[^:]+):(\d+)/
-            options[:desc] = Lazydoc.register($1, $3.to_i - 1)
+          when Lazydoc::CALLER_REGEXP
+            options[:desc] = Lazydoc.register($1, $3.to_i - 1, Lazydoc::Config)
             break
           end
         end if options[:desc] == nil
@@ -270,10 +247,10 @@ module Tap
       # blocks, such as switch (Validation::SWITCH) and list
       # (Validation::LIST).
       def arg_type(block) # :nodoc:
-        case block
-        when Validation::SWITCH then :switch
-        when Validation::FLAG then :flag
-        when Validation::LIST then :list
+        case 
+        when block == Validation::SWITCH then :switch
+        when block == Validation::FLAG then :flag
+        when block == Validation::LIST then :list
         else nil
         end
       end
@@ -282,12 +259,13 @@ module Tap
       # blocks, such as switch (Validation::ARRAY) and list
       # (Validation::HASH).
       def arg_name(block) # :nodoc:
-        case block
-        when Validation::ARRAY then "'[a, b, c]'"
-        when Validation::HASH then "'{one: 1, two: 2}'"
+        case
+        when block == Validation::ARRAY then "'[a, b, c]'"
+        when block == Validation::HASH then "'{one: 1, two: 2}'"
         else nil
         end
       end
+
     end
   end
 end

data/lib/tap/support/configuration.rb

@@ -1,8 +1,12 @@
 module Tap
   module Support
+    
+    # Represents a configuration declared by a Configurable class.
     class Configuration
       class << self
-        SHORT_REGEXP = /^-[A-z]$/
+        
+        # Matches a short option
+        SHORT_OPTION = /^-[A-z]$/
         
         # Turns the input string into a short-format option.  Raises
         # an error if the option does not match SHORT_REGEXP.
@@ -13,11 +17,12 @@ module Tap
         def shortify(str)
           str = str.to_s
           str = "-#{str}" unless str[0] == ?-
-          raise "invalid short option: #{str}" unless str =~ SHORT_REGEXP
+          raise "invalid short option: #{str}" unless str =~ SHORT_OPTION
           str
         end
-
-        LONG_REGEXP = /^--(\[no-\])?([A-z][\w-]*)$/
+        
+        # Matches a long option
+        LONG_OPTION = /^--(\[no-\])?([A-z][\w-]*)$/
         
         # Turns the input string into a long-format option.  Raises
         # an error if the option does not match LONG_REGEXP.
@@ -33,7 +38,7 @@ module Tap
           str = "--#{str}" unless str.index("--")
           str.gsub!(/_/, '-') if hyphenize
           
-          raise "invalid long option: #{str}" unless str =~ LONG_REGEXP
+          raise "invalid long option: #{str}" unless str =~ LONG_OPTION
           
           if switch_notation && $1.nil?
             str = "--[no-]#{$2}"
@@ -43,12 +48,24 @@ module Tap
         end
       end
       
+      # The name of the configuration
       attr_reader :name
+      
+      # The reader method, by default name
       attr_reader :reader
+      
+      # The writer method, by default name=
       attr_reader :writer
+      
+      # True if the default value may be duplicated
       attr_reader :duplicable
+      
+      # An array of optional metadata for self
       attr_reader :attributes
- 
+      
+      # Initializes a new Configuration with the specified name and default
+      # value.  Options may specify an alternate reader/writer; any
+      # additional options are set as attributes.
       def initialize(name, default=nil, options={})
         @name = name
         self.default = default
@@ -59,11 +76,12 @@ module Tap
       end
 
       # Sets the default value for self and determines if the
-      # default is duplicable (ie not nil, true, false, Symbol, 
-      # Numeric, and responds_to?(:dup)).
+      # default is duplicable.  Non-duplicable values include
+      # nil, true, false, Symbol, Numeric, and any object that
+      # does not respond to dup.
       def default=(value)
         @duplicable = case value
-        when nil, true, false, Symbol, Numeric then false
+        when nil, true, false, Symbol, Numeric, Method then false
         else value.respond_to?(:dup)
         end
         
@@ -88,22 +106,29 @@ module Tap
         @writer = value == nil ? value : value.to_sym
       end
       
+      # The argument name for self: either attributes[:arg_name]
+      # or name.to_s.upcase
       def arg_name
         attributes[:arg_name] || name.to_s.upcase
       end
       
+      # The argument type for self: either attributes[:arg_type]
+       # or :mandatory
       def arg_type
         attributes[:arg_type] || :mandatory
       end
       
+      # The long version of name.
       def long(switch_notation=false, hyphenize=true)
         Configuration.longify(attributes[:long] || name.to_s, switch_notation, hyphenize)
       end
       
+      # The short version of name.
       def short
         attributes[:short] ? Configuration.shortify(attributes[:short]) : nil
       end
       
+      # The description for self: attributes[:desc]
       def desc
         attributes[:desc]
       end
@@ -119,6 +144,27 @@ module Tap
         self.default(false) == another.default(false)
       end
       
+      # Returns self as an argv that can be used to register
+      # an option with OptionParser.
+      def to_optparse_argv
+        argtype = case arg_type
+        when :optional 
+          "#{long} [#{arg_name}]"
+        when :switch 
+          long(true)
+        when :flag
+          long
+        when :list
+          "#{long} a,b,c"
+        when :mandatory, nil
+          "#{long} #{arg_name}"
+        else
+          raise "unknown arg_type: #{arg_type}"
+        end
+
+        [short, argtype, desc].compact
+      end
+      
     end
   end
 end

data/lib/tap/support/constant.rb

@@ -1,18 +1,79 @@
-require 'tap/support/constant_utils'
-class String # :nodoc:
-  include Tap::Support::ConstantUtils
-end
+require 'tap/support/string_ext'
 
 module Tap
   module Support
+    
+    # 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')
+    #   http.constantize                                 # => Net::HTTP
+    #   $".include?('net/http')                          # => true
+    #
     class Constant
+      class << self
+        
+        # Tries to find a declared constant under base with the specified
+        # const_name.  When a constant is missing, constantize yields
+        # the current base and any non-existant constant names the block,
+        # if given, or raises a NameError.  The block is expected 
+        # to return the proper constant.
+        #
+        #   module ConstName; end
+        #
+        #   Constant.constantize('ConstName')                     # => ConstName
+        #   Constant.constantize('Non::Existant') { ConstName }   # => ConstName
+        #
+        def constantize(const_name, base=Object) # :yields: base, missing_const_names
+          unless /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/ =~ const_name
+            raise NameError, "#{const_name.inspect} is not a valid constant name!"
+          end
+          
+          constants = $1.split(/::/)
+          while !constants.empty?
+            unless const_is_defined?(base, constants[0])
+              if block_given? 
+                return yield(base, constants)
+              else
+                raise NameError.new("uninitialized constant #{const_name}", constants[0]) 
+              end
+            end
+            base = base.const_get(constants.shift)
+          end
+          base
+        end
+        
+        private
+        
+        # helper method.  Determines if a constant named
+        # name 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, name) # :nodoc:
+            const.const_defined?(name, false)
+          end
+        else
+          def const_is_defined?(const, name) # :nodoc:
+            const.const_defined?(name)
+          end
+        end
+      end
       
-      # The camelized name for self.
+      # The constant name
       attr_reader :name
       
-      # The path to load to initialize the constant name.
+      # The path to load to initialize a missing constant
       attr_reader :require_path
-  
+      
+      # Initializes a new Constant with the specified constant
+      # name and require_path.  The name should be a valid
+      # constant name.
       def initialize(name, require_path=nil)
         @name = name
         @require_path = require_path
@@ -48,23 +109,36 @@ module Tap
         @nesting_depth ||= nesting.split(/::/).length
       end
   
-      # Returns the document for require_path, if set, or nil otherwise.
+      # Returns the Lazydoc document for require_path.
       def document
-        require_path ? Support::Lazydoc[require_path] : nil 
+        require_path ? Lazydoc[require_path] : nil 
       end
       
+      # True if another is a Constant with the same name
+      # and require_path as self.
       def ==(another)
         another.kind_of?(Constant) && 
         another.name == self.name &&
         another.require_path == self.require_path
       end
-  
+      
+      # Looks up and returns the constant indicated by name.
+      # If the constant cannot be found, the constantize
+      # requires require_path and tries again.  
+      #
+      # Raises a NameError if the constant cannot be found.
       def constantize
-        name.try_constantize do |const_name|
-          require require_path
-          name.constantize
+        Constant.constantize(name) do
+          require require_path if require_path
+          Constant.constantize(name)
         end
       end
+      
+      # Returns a string like:
+      #   "#<Tap::Support::Constant:object_id Const::Name (require_path)>"
+      def inspect
+        "#<#{self.class}:#{object_id} #{name}#{@require_path == nil ? "" : " (#{@require_path})"}>"
+      end
     end
   end
 end

data/lib/tap/support/constant_manifest.rb

@@ -0,0 +1,116 @@
+require 'tap/support/manifest'
+require 'tap/support/constant'
+
+module Tap
+  module Support
+    
+    # ConstantManifest builds a manifest of Constant entries using Lazydoc.
+    # The idea is that Lazydoc can find files with resouces of a specific type
+    # (ex tasks) and Constant can reference those resouces and load them as 
+    # necessary. ConstantManifest registers paths so that they may be lazily
+    # scanned when searching for a specific resource.
+    class ConstantManifest < Support::Manifest
+      
+      # The attribute identifying resources in a file
+      attr_reader :const_attr
+      
+      # Registered [root, [paths]] pairs that will be searched
+      # for the 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
+      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
+        # Support::Lazydoc[path].resolved = false
+        @entries.clear
+        @search_path_index = 0
+        @path_index = 0
+        super
+      end
+      
+      # Yields each 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
+            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)
+        entries = []
+        if document = Lazydoc.scan_doc(path, const_attr)
+          if document.default_const_name.empty?
+            relative_path = Root.relative_filepath(path_root, path).chomp(File.extname(path))
+            document.default_const_name = relative_path.camelize
+          end
+          
+          document.const_attrs.each_pair do |const_name, attrs|
+            if attrs.has_key?(const_attr)
+              entries << Constant.new(const_name, path)
+            end
+          end
+        end
+        
+        entries
+      end
+      
+    end
+  end
+end

data/lib/tap/support/dependencies.rb

@@ -0,0 +1,54 @@
+require 'tap/support/dependency'
+
+module Tap
+  module Support
+    
+    # Dependencies tracks Executable dependencies and results, and provides
+    # for thread-safe resolution of dependencies.
+    class Dependencies < Monitor
+      
+      # Initializes a new Dependencies
+      def initialize
+        super 
+        @resolve_stack = []
+      end
+      
+      # Thread-safe registration of instance as a dependency.  During
+      # registration, instance is extended with the Dependency module.
+      # Returns self.
+      def register(instance)
+        synchronize do
+          unless instance.kind_of?(Dependency)
+            instance.extend Dependency
+          end
+        end
+        self
+      end
+      
+      # Thread-safe resolution of the instance.  Resolve checks for
+      # circular dependencies, then yields control to the block,
+      # which is responsible for the actual resolution.
+      def resolve(instance)
+        synchronize do
+          if @resolve_stack.include?(instance)
+            raise CircularDependencyError.new(@resolve_stack)
+          end
+          
+          # mark the results at the index to prevent
+          # infinite loops with circular dependencies
+          @resolve_stack.push instance
+          yield()
+          @resolve_stack.pop
+        end
+        self
+      end
+      
+      # Raised when Dependencies#resolve detects a circular dependency.
+      class CircularDependencyError < StandardError
+        def initialize(resolve_stack)
+          super "circular dependency: [#{resolve_stack.join(', ')}]"
+        end
+      end
+    end
+  end
+end

data/lib/tap/support/dependency.rb

@@ -0,0 +1,44 @@
+module Tap
+  module Support
+    
+    # Constrains an Executable to only _execute once, and provides several
+    # methods making the Executable behave like a Dependency.
+    module Dependency
+      
+      # The audited result of self
+      attr_accessor :_result
+      
+      def self.extended(base) # :nodoc:
+        base.instance_variable_set(:@_result, nil)
+      end
+      
+      # Conditional _execute; only calls _method_name if
+      # resolved? is false (thus assuring self will only
+      # be executed once).
+      #
+      # Returns _result.
+      def _execute(*args)
+        app.dependencies.resolve(self) do
+          @_result = super
+        end unless resolved?
+        _result
+      end
+      
+      # Alias for _execute().
+      def resolve
+        _execute
+      end
+      
+      # True if _result is non-nil.
+      def resolved?
+        @_result != nil
+      end
+      
+      # Resets the dependency by setting _result to nil.
+      def reset
+        @_result = nil
+      end
+      
+    end
+  end
+end