tap 0.8.0 → 0.9.0

data/lib/tap/support/executable.rb

@@ -0,0 +1,98 @@
+module Tap
+  module Support
+    # Executable wraps methods to make them executable by App.
+    module Executable
+      
+      # The method called when an Executable is executed via _execute
+      attr_reader :_method_name
+    
+      # Indicates whether or not to call in multithread mode.  Default false.
+      attr_accessor :multithread
+
+      # Stores the on complete block.  Default is Executable.default_on_complete_block.
+      attr_reader :on_complete_block
+    
+      protected
+      
+      attr_writer :_method_name
+    
+      public
+
+      def self.initialize(obj, method_name, multithread=false, &on_complete_block)
+        obj.extend Executable
+        obj.instance_variable_set(:@_method_name, method_name)
+        obj.instance_variable_set(:@multithread, multithread)
+        obj.instance_variable_set(:@on_complete_block, on_complete_block)
+        obj
+      end
+    
+      # Sets a block to receive the results of _call.  Raises an error 
+      # if on_complete_block is already set, unless override = true.
+      #
+      # Note the block recieves an audited result and not
+      # the result itself (see Audit for more information).
+      def on_complete(override=false, &block) # :yields: _result
+        unless on_complete_block == nil || override
+          raise "on_complete_block already set: #{self}" 
+        end
+        @on_complete_block = block
+      end
+
+      # Auditing method call.  Executes _method_name for self, but audits 
+      # the result. Sends the audited result to the on_complete_block if set.
+      #
+      # Audits are initialized in the follwing manner:
+      # no inputs:: create a new, empty Audit.  The first value of the audit
+      #             will be the result of call
+      # one input:: forks the input if it is an audit, otherwise initializes
+      #             a new audit using the input
+      # multiple inputs:: merges the inputs into a new Audit.
+      #
+      def _execute(*inputs)
+        audit = case inputs.length
+        when 0 then Audit.new
+        when 1 
+          audit = inputs.first
+          if audit.kind_of?(Audit) 
+            inputs = [audit._current]
+            audit._fork
+          else
+            Audit.new(audit)
+          end 
+        else
+          sources = []
+          inputs.collect! do |input| 
+            if input.kind_of?(Audit) 
+              sources << input._fork
+              input._current
+            else
+              sources << nil
+              input
+            end
+          end
+          Audit.new(inputs, sources)
+        end
+      
+        audit._record(self, send(_method_name, *inputs))
+        on_complete_block.call(audit) if on_complete_block
+      
+        audit
+      end
+    end
+  end
+end
+
+# Tap extends Object with a convenience method to generate methods
+# that can be enqued by App and incorporated into workflows.  
+class Object
+  
+  # Makes a Tap::Support::Executable for the Method returned by
+  # Object#method, setting multithread and the on_complete block 
+  # as specified.  The method will be called on _execute.
+  #
+  # Returns nil if Object#method returns nil.
+  def _method(method_name, multithread=false, &on_complete_block) # :yields:  _result
+    return nil unless m = method(method_name)
+    Tap::Support::Executable.initialize(m, :call, multithread, &on_complete_block)
+  end
+end

data/lib/tap/support/executable_queue.rb

@@ -0,0 +1,82 @@
+module Tap
+  module Support
+    
+    # ExecutableQueue allows thread-safe enqueing and dequeing of 
+    # Executable methods and inputs for execution.  
+    class ExecutableQueue
+      include MonitorMixin
+      
+      # Creates a new ExecutableQueue
+      def initialize
+        # required for MonitorMixin
+        super()
+        @queue = []
+      end
+      
+      # Clears all methods and inputs.  Returns the existing queue as an array.
+      def clear
+        synchronize do
+          current = self.queue
+          self.queue = []
+          current
+        end
+      end
+      
+      # Returns the number of enqueued methods
+      def size
+        queue.length
+      end
+      
+      # True if no methods are enqueued
+      def empty?
+        queue.empty?
+      end
+      
+      # Enqueues the method and inputs. Raises an error if the  
+      # method is not an Executable.
+      def enq(method, inputs)
+        synchronize do
+          check_method(method)
+          queue.push [method, inputs]
+        end
+      end
+      
+      # Enqueues the method and inputs, but to the top of the queue.
+      # Raises an error if the method is not an Executable.
+      def unshift(method, inputs)
+        synchronize do
+          check_method(method)
+          queue.unshift [method, inputs]
+        end
+      end
+      
+      # Dequeues the next method and inputs as an array like
+      # [method, inputs]. Returns nil if the queue is empty.
+      def deq
+        synchronize { queue.shift }
+      end
+      
+      def concat(array)
+        synchronize do
+          array.each do |method, inputs|
+            enq(method, inputs)
+          end
+        end
+      end
+      
+      # Converts self to an array.
+      def to_a
+        queue.dup
+      end
+      
+      protected
+      
+      attr_accessor :queue
+      
+      # Checks if the input method is extended with Executable
+      def check_method(method) # :nodoc:
+        raise "not Executable: #{method}" unless method.kind_of?(Executable)
+      end
+    end 
+  end
+end

data/lib/tap/support/logger.rb

@@ -19,6 +19,12 @@ module Tap
     # Typed logging occurs through +method_missing+.  Any type is possible so long as the logger doesn't
     # already have a method of the input type.
     #++
+    #
+    #--
+    # TODO
+    # multiplex logger so that logging can be directed to two locations; a log file and the console for
+    # example, or log files in multiple locations.
+    #++
     module Logger
       Format = "  %s[%s] %18s %s\n"
       
@@ -39,20 +45,8 @@ module Tap
         @logdev
       end
       
-      def tick(mark=".")
-        @logdev.write mark
-      end
-      
-      def monitor(action="beginning", msg="", &block)
-        begin_time = Time.now
-        format_add(INFO, msg, action) {|format| format.chomp("\n")}
-
-        result = yield
-        
-        format_add(INFO, "#{Time.now-begin_time}s", "completed") {|format| "\n" + format}
-        result
-      end
-      
+      # Same as add, but uses the format provided by the block.
+      # BUG: not thread safe
       def format_add(level, msg, action=nil, &block)
         current_format = self.format
         self.format = yield(current_format)
@@ -65,7 +59,7 @@ module Tap
       #   I[H:M:S]           type message
       #
       # If no progname is specified, '--' is used.
-      def format_message(severity, timestamp, progname, msg)
+      def format_message(severity, timestamp, progname, msg, format=self.format)
         if timestamp.respond_to?(:strftime) && self.datetime_format
           timestamp = timestamp.strftime(self.datetime_format) 
         end

data/lib/tap/support/rake.rb

@@ -1,54 +1,43 @@
-require 'rake'
-
-module Rake # :nodoc:
-  # Modifies Rake::Task to behave like a Tap::Task.  
-  class Task # :nodoc:
-    alias_method(:tap_original_execute, :execute)
-    alias_method(:tap_original_invoke, :invoke)
-    alias_method(:tap_original_initialize, :initialize)
-    
-    def initialize(*args)
-      tap_original_initialize(*args)
-      self.extend Tap::Task::Base
-      self.extend InstanceMethods
-    end
-    
-    def invoke
-      @lock.synchronize do
-        if application.options.trace
-          puts "** Invoke #{name} #{format_trace_flags}"
-        end
-        return if @already_invoked
-        @already_invoked = true
-        invoke_prerequisites
-        tap_original_execute if needed?
-      end
-    end
-    
-    module InstanceMethods # :nodoc:
-      
-      def iterate=(input)
-        raise "iterate cannot be set to true for Rake tasks." if input == true
-      end
-      
-      protected 
-      
-      def on_execute(audited_inputs)
-        invoke
-        audited_inputs._record(self, nil)
-      end
-    end
-  end
-end
-
-module Tap
-  module Support
-    # == UNDER CONSTRUCTION
-    module Rake 
-      
-      def task(td, config=nil)
-        Object::Rake.application.lookup(td) || super
-      end
-    end
-  end
-end
+require 'rake'
+
+module Tap
+  module Support
+    
+    # Used to modify an App so that it will lookup Rake tasks as well as Tap tasks.  Simply use:
+    #   app.extend(RakeLookup)
+    #--
+    # Note: Do not refactor Tap:Support::Rake without attending  to the line in 'script/run' that 
+    # extends app.  As it stands, this module is loaded as needed using Dependencies.
+    module Rake
+      def task(td, config={}, &block)
+        Object::Rake.application.lookup(td) || super
+      end
+
+      # Modifies Rake::Task to behave like Tap::Task.  The essential code is this:
+      #
+      #   module Tap::Support::Rake::Task
+      #     def new(*args)
+      #       task = super
+      #       Tap::Task::Base.initialize(task, :invoke)
+      #       task
+      #     end
+      #   end
+      #
+      # Here the new method creates a new Rake task as normal, then initializes the 
+      # Rake task based on the invoke method.  The modifed code is applied to Rake
+      # in the following fashion:
+      #
+      #   Rake::Task.extend(Tap::Support::Rake::Task)
+      #
+      module Task
+        def new(*args)
+          task = super
+          Tap::Task::Base.initialize(task, :invoke)
+          task
+        end
+      end
+    end
+  end
+end
+
+Rake::Task.extend(Tap::Support::Rake::Task)

data/lib/tap/support/run_error.rb

@@ -1,20 +1,39 @@
 module Tap
-  module Support
+  module Support
+    # Raised when an exception is raised during App#run.  All errors generated during
+    # termination are collected into the RunError.
     class RunError < RuntimeError
-      attr_reader :original_error, :terminate_errors
+      attr_reader :errors
   
-      def initialize(original_error, terminate_errors)
-        @original_error = original_error
-        @terminate_errors = terminate_errors
-      end
-  
-      def message
-        "#{original_error.class} #{original_error.message}"
-      end
-      
-      def backtrace
-        original_error.backtrace
+      def initialize(errors)
+        @errors = errors
+        @backtrace = nil
+      end
+      
+      #The join of all the error messages.
+      def message
+        lines = []
+        errors.each_with_index do |error, i| 
+          lines << "\nRunError [#{i}] #{error.class} #{error.message}"
+        end
+        lines.join + "\n"
       end
+      
+      #The join of all the error backtraces.
+      def backtrace
+        # backtrace gets called every time RunError is re-raised, leading to multiple
+        # repeats of the error backtraces.  This ensures the additional backtrace 
+        # information is only added once.
+        return @backtrace unless @backtrace == nil
+        return nil unless @backtrace = super
+        
+        errors.each_with_index do |error, i| 
+          @backtrace [-1] += "\n\n---------------------- RunError [#{i}] ----------------------\n#{error.class} #{error.message}"
+          @backtrace.concat(error.backtrace ||  ["missing backtrace"])
+        end
+        @backtrace
+      end
+    
     end
   end
 end

data/lib/tap/support/shell_utils.rb

@@ -0,0 +1,47 @@
+require 'tempfile'
+
+module Tap
+  module Support
+    # Provides several shell utility methods for calling programs.
+    module ShellUtils
+      
+      module_function
+      
+      # Run the system command +cmd+, passing the result to the block, if given.
+      # Raises an error if the command fails. Uses the same semantics as 
+      # Kernel::exec and Kernel::system.
+      #
+      # Based on FileUtils#sh from Rake.
+      def sh(*cmd) # :yields: ok, status
+        ok = system(*cmd)
+
+        if block_given?
+          yield(ok, $?)
+        else
+          ok or raise "Command failed with status (#{$?.exitstatus}): [#{ cmd.join(' ')}]"
+        end
+      end
+      
+      # Runs the system command +cmd+ using sh, redirecting the output to the 
+      # specified file path.  Uses the redirection command:
+      #
+      #   "> \"#{path}\" 2>&1 #{cmd}"
+      #
+      # This redirection has been tested on Windows, OS X, and Fedora.  See 
+      # http://www.robvanderwoude.com/redirection.html for pointers on
+      # redirection.  The website notes that this style of redirection SHOULD
+      # NOT be used with commands that contain other redirections.  
+      def redirect_sh(cmd, path, &block) # :yields: ok, status
+        sh( "> \"#{path}\" 2>&1 #{cmd}", &block)
+      end
+      
+      # Runs the system command +cmd+ and returns the output as a string.
+      def capture_sh(cmd, quiet=false, &block) # :yields: ok, status
+        tempfile = Tempfile.new('shell_utils')
+        tempfile.close
+        redirect_sh(cmd, tempfile.path, &block)
+        quiet == true ? "" : File.read(tempfile.path)
+      end
+    end
+  end
+end

data/lib/tap/support/tdoc.rb

@@ -10,7 +10,7 @@ module Tap
     # documentation for Task configurations, when they are present.  TDoc provides an extension
     # to the standard RDoc HTMLGenerator and template.  
     #
-    # == Usage
+    # === Usage
     # To generate task documentation with configuration information, TDoc must be loaded and 
     # the appropriate flags passed to rdoc .  Essentially what you want is:
     #
@@ -40,7 +40,7 @@ module Tap
     # TDoc may also be utilized programatically, but you should be aware that RDoc in Ruby
     # can raise errors and/or cause namespace conflicts (see below).
     #
-    # == Implementation
+    # === Implementation
     # RDoc is a beast to utilize in a  non-standard way.  One way to make RDoc parse unexpected
     # flags like 'config_accessor' or the 'c' config specifier is to use the '--accessor' option
     # (see 'rdoc --help' or the RDoc documentation for more details).  
@@ -54,7 +54,7 @@ module Tap
     # Similarly, the configuration attributes will not appear in the output unless you specify a 
     # template that utilizes them.
     #
-    # == Namespace conflicts
+    # === Namespace conflicts
     # RDoc creates a namespace conflict with other libraries that define RubyToken and RubyLex
     # in the Object namespace (the prime example being IRB).  TDoc checks for such a conflict
     # and redfines the RDoc RubyToken and RubyLex within the RDoc namespace. Essentially:
@@ -90,7 +90,7 @@ module Tap
         @stats = RDoc::Stats.new
         @options = Options.instance
         @options.parse(argv, RDoc::RDoc::GENERATORS)
-        @load_paths = $:
+        @load_paths = ($: + Dependencies.load_paths + Dependencies.load_once_paths).uniq
       end
       
       class << self
@@ -106,11 +106,12 @@ module Tap
         end
         
         def search_for_source_files(klass)
-          source_files = search_for_files(klass.to_s.underscore)
-          while klass.superclass.kind_of?(Tap::Task)
-            klass = klass.superclass
-            break if klass.configurations.empty?
+          source_files = []
+          # searches back for all configurable source files, so that
+          # inherited configs can be documented.
+          while klass.include?(Tap::Support::Configurable)
             source_files.concat(search_for_files(klass.to_s.underscore))
+            klass = klass.superclass
           end
           
           source_files.uniq