bahuvrihi-tap 0.10.4 → 0.10.5

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

@@ -0,0 +1,17 @@
+module Tap
+  module Support
+    module Lazydoc
+      class Config < Comment
+        def empty?
+          to_str.empty?
+        end
+
+        def to_str
+          # currently removes the :no_default: document modifier
+          # which is used during generation of TDoc
+          subject.to_s =~ /#\s*(:no_default:)?\s*(.*)$/ ? $2.strip : ""
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+module Tap
+  module Support
+    module Lazydoc
+      class Declaration < Comment
+        def resolve(lines)
+          super
+            
+          @subject = case
+          when content.empty? || content[0][0].to_s !~ /^::desc(.*)/ then ""
+          else
+            content[0].shift
+            $1.strip
+          end
+            
+          self
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+require 'tap/support/lazydoc/comment'
+
+module Tap
+  module Support
+    module Lazydoc
+      class Document
+        # 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.
+        attr_reader :comments
+      
+        # 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.
+        attr_reader :const_attrs
+      
+        # The default constant name used when no constant name
+        # is specified for a constant attribute.
+        attr_reader :default_const_name
+      
+        # Flag indicating whether or not self has been resolved.
+        attr_accessor :resolved
+      
+        def initialize(source_file=nil, default_const_name='')
+          self.source_file = source_file
+          @default_const_name = default_const_name
+          @comments = []
+          @const_attrs = {}
+          @resolved = false
+          self.reset
+        end
+      
+        # Resets self by clearing const_attrs, comments, and setting
+        # resolved to false.  Generally NOT recommended as this 
+        # clears any work you've done registering lines; to simply
+        # allow resolve to re-scan a document, manually set
+        # resolved to false.
+        def reset
+          @const_attrs.clear
+          @comments.clear
+          @resolved = false
+          self
+        end
+      
+        # Sets the source file for self.  Expands the source file path if necessary.
+        def source_file=(source_file)
+          @source_file = source_file == nil ? nil : File.expand_path(source_file)
+        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.
+        def default_const_name=(const_name)
+          self[const_name].merge!(const_attrs.delete(@default_const_name) || {})
+          @default_const_name = const_name
+        end
+      
+        # Returns the attributes for the specified const_name.
+        def [](const_name)
+          const_attrs[const_name] ||= {}
+        end
+
+        # Register the specified line number to self.  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 }
+        
+          if comment == nil
+            comment = comment_class.new(line_number)
+            comments << comment
+          end
+        
+          comment
+        end
+      
+        def register_method(method, comment_class=Comment)
+          register(/^\s*def\s+#{method}(\W|$)/, comment_class)
+        end
+      
+        def resolve(str=nil)
+          return(false) if resolved
+        
+          str = File.read(source_file) if str == nil
+          Lazydoc.parse(str) do |const_name, key, comment|
+            const_name = default_const_name if const_name.empty?
+            self[const_name][key] = comment
+          end
+        
+          unless comments.empty?
+            lines = str.split(/\r?\n/)  
+            comments.each do |comment|
+              comment.resolve(lines)
+            end
+          end
+        
+          @resolved = true
+        end
+      
+        def to_hash
+          const_hash = {}
+          const_attrs.each_pair do |const_name, attributes|
+            next if attributes.empty?
+          
+            attr_hash = {}
+            attributes.each_pair do |key, comment|
+              attr_hash[key] = (block_given? ? yield(comment) : comment)
+            end
+            const_hash[const_name] = attr_hash
+          end
+          const_hash
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+module Tap
+  module Support
+    module Lazydoc
+      class Method < Comment
+        def resolve(lines)
+          super
+          @subject =~ /def \w+(\((.*?)\))?/
+
+          args = $2.to_s.split(',').collect do |arg|
+            arg = arg.strip.upcase
+            case arg
+            when /^&/ then nil
+            when /^\*/ then arg[1..-1] + "..."
+            else arg
+            end
+          end
+
+          @subject = args.join(', ')
+          self
+        end
+      end
+    end
+  end
+end

data/lib/tap/support/manifest.rb

@@ -40,6 +40,8 @@ module Tap
         entries.empty?
       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
@@ -94,9 +96,9 @@ module Tap
         new_entry
       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 (key, value) entry in self, dynamically 
+      # identifying entries from search_paths if necessary.  New 
+      # entries are identifed using the each_for method.
       def each
         entries.each do |key, path| 
           yield(key, path) 
@@ -134,7 +136,34 @@ module Tap
         entries.collect {|path, value| [hash[path], value] }
       end
       
-      protected
+      # 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.
+      #
+      # 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)
+        end
+        
+        lines << ""
+        lines << "mini-entries:"
+        minimize.each do |mini, value| 
+          lines << "  #{mini}: #{value.inspect}"
+        end
+        lines << ""
+        
+        "#{self.class}:#{object_id} #{lines.join("\n")}"
+      end
 
       # Raised when multiple paths are assigned to the same manifest key.
       class ManifestConflict < StandardError

data/lib/tap/support/validation.rb

@@ -405,6 +405,62 @@ module Tap
       end
       RANGE_OR_NIL = range_or_nil_block
       
+      # Returns a block that checks the input is a Time. String inputs are 
+      # loaded using Time.parse and then converted into times.  Parsed times 
+      # are local unless specified otherwise.
+      #
+      #   time.class               # => Proc
+      #
+      #   now = Time.now
+      #   time.call(now)           # => now
+      #
+      #   time.call('2008-08-08 20:00:00.00 +08:00').getutc.strftime('%Y/%m/%d %H:%M:%S')
+      #   #  => '2008/08/08 12:00:00'
+      #
+      #   time.call('2008-08-08').strftime('%Y/%m/%d %H:%M:%S')
+      #   #  => '2008/08/08 00:00:00'
+      #
+      #   time.call(1)             # => ValidationError
+      #   time.call(nil)           # => ValidationError
+      #
+      # Warning: Time.parse will parse a valid time (Time.now)
+      # even when no time is specified:
+      #
+      #   time.call('str').strftime('%Y/%m/%d %H:%M:%S')      
+      #   # => Time.now.strftime('%Y/%m/%d %H:%M:%S')      
+      #
+      def time()
+        # adding this here is a compromise to lazy-load the parse
+        # method (autoload doesn't work since Time already exists)
+        require 'time' unless Time.respond_to?(:parse)
+        TIME
+      end
+      
+      TIME = lambda do |input|
+        input = Time.parse(input) if input.kind_of?(String)
+        validate(input, [Time])
+      end
+      
+      # Same as time but allows nil:
+      #
+      #   time_or_nil.call('~')    # => nil
+      #   time_or_nil.call(nil)    # => nil
+      def time_or_nil()
+        # adding this check is a compromise to autoload the parse 
+        # method (autoload doesn't work since Time already exists)
+        require 'time' unless Time.respond_to?(:parse)
+        TIME_OR_NIL
+      end
+      
+      TIME_OR_NIL = lambda do |input|
+        input = case input
+        when nil, '~' then nil
+        when String then Time.parse(input)
+        else input
+        end
+        
+        validate(input, [Time, nil])
+      end
     end
   end
 end

data/lib/tap/task.rb

@@ -1,6 +1,7 @@
 require 'tap/support/batchable'
 require 'tap/support/executable'
-require 'tap/support/command_line'
+require 'tap/support/lazydoc/method'
+autoload(:OptionParser, 'optparse')
 
 module Tap
 
@@ -214,52 +215,32 @@ module Tap
         subclass.define_configurations(configs)
         subclass.define_dependencies(dependencies)
         subclass.define_process(block) if block_given?
-  
-        #
-        # Register documentation
-        #
-        const_name = subclass.to_s
-        caller.each_with_index do |line, index|
-          case line
-          when /\/tap\/support\/declarations.rb/ then next
-          when Support::Lazydoc::CALLER_REGEXP
-            subclass.source_file = File.expand_path($1)
-            lzd = subclass.lazydoc(false)
-            lzd[const_name, false]['manifest'] = lzd.register($3.to_i - 1)            
-            break
-          end
-        end
-
-        arity = options[:arity] || (block_given? ? block.arity : -1)
-        comment = Support::Comment.new
-        comment.subject = case
-        when arity > 0
-          Array.new(arity, "INPUT").join(' ')
-        when arity < 0
-          array = Array.new(-1 * arity - 1, "INPUT")
-          array << "INPUTS..."
-          array.join(' ')
-        else ""
-        end
-        subclass.lazydoc(false)[const_name, false]['args'] ||= comment
-
-        subclass.default_name = const_name.underscore
+        subclass.default_name = subclass.to_s.underscore
         subclass
       end
       
-      def instantiate(argv, app=Tap::App.instance) # => instance, argv
+      # Parses the argv into an instance of self and an array of arguments (implicitly
+      # to be enqued to the instance and run by app).  Yields a help string to the
+      # block when the argv indicates 'help'.
+      #
+      def parse(argv=ARGV, app=Tap::App.instance, &block) # :yields: help_str
+        parse!(argv.dup, &block)
+      end
+      
+      # Same as parse, but removes switches destructively. 
+      def parse!(argv=ARGV, app=Tap::App.instance) # :yields: help_str
         opts = OptionParser.new
 
         # Add configurations
-        config = {}
+        argv_config = {}
         unless configurations.empty?
           opts.separator ""
           opts.separator "configurations:"
         end
 
-        configurations.each do |receiver, key, configuration|
-          opts.on(*Support::CommandLine.configv(configuration)) do |value|
-            config[key] = value
+        configurations.each do |receiver, key, config|
+          opts.on(*config.to_optparse_argv) do |value|
+            argv_config[key] = value
           end
         end
 
@@ -269,8 +250,12 @@ module Tap
 
         opts.on_tail("-h", "--help", "Print this help") do
           opts.banner = "#{help}usage: tap run -- #{to_s.underscore} #{args.subject}"
-          puts opts
-          exit
+          if block_given? 
+            yield(opts.to_s)
+          else
+            puts opts
+            exit
+          end
         end
 
         # Add option for name
@@ -295,26 +280,42 @@ module Tap
             use_args << obj
           end
         end
-
+        
+        # parse the argv
         opts.parse!(argv)
+        
+        # build and reconfigure the instance and any associated
+        # batch objects as specified in the file configurations
         obj = new({}, name, app)
-
         path_configs = load_config(app.config_filepath(name))
         if path_configs.kind_of?(Array)
           path_configs.each_with_index do |path_config, i|
-            obj.initialize_batch_obj(path_config, "#{name}_#{i}") unless i == 0
+            next if i == 0
+            batch_obj = obj.initialize_batch_obj(path_config, "#{name}_#{i}")
+            batch_obj.reconfigure(argv_config)
           end
           path_configs = path_configs[0]
         end
-
+        obj.reconfigure(path_configs).reconfigure(argv_config)
+        
+        # recollect arguments
         argv = (argv + use_args).collect {|str| str =~ /\A---\s*\n/ ? YAML.load(str) : str }
 
-        [obj.reconfigure(path_configs).reconfigure(config), argv]
+        [obj, argv]
+      end
+      
+      def execute(argv=ARGV)
+        instance, args = parse(ARGV) do |help|
+          puts help
+          exit
+        end
+
+        instance.execute(*args)
       end
 
       def lazydoc(resolve=true)
         lazydoc = super(false)
-        lazydoc.register_method_pattern('args', :process) unless lazydoc.resolved?
+        lazydoc[self.to_s]['args'] ||= lazydoc.register_method(:process, Support::Lazydoc::Method)
         super
       end
 
@@ -615,5 +616,6 @@ module Tap
       raise ArgumentError, "config '#{name}' is not a hash" unless configs.kind_of?(Hash)
       klass.new(configs, name, &block)
     end
+    
   end
 end