tap 0.9.1 → 0.10.0

data/lib/tap/support/versions.rb

@@ -56,7 +56,9 @@ module Tap
       #   deversion("path/to/file.txt")               # => ["path/to/file.txt", nil]
       #
       def deversion(path)
-        path =~ /^(.*)-(\d(\.?\d)*)(.*)?/ ? [$1 + $4, $2] : [path, nil]
+        extname = File.extname(path)
+        extname = '' if extname =~ /^\.\d+$/
+        path =~ /^(.*)-(\d(\.?\d)*)#{extname}$/ ? [$1 + extname, $2] : [path, nil]
       end
       
       # A <=> comparison for versions.  compare_versions can take strings, 
@@ -80,8 +82,8 @@ module Tap
       
       private
       
-      # Converts an input argument (typically a string  or an array) 
-      # to  an array of integers.  Splits version string on "."
+      # Converts an input argument (typically a string or an array) 
+      # to an array of integers.  Splits version string on "."
       def to_integer_array(arg)
         arr = case arg
         when Array then arg

data/lib/tap/task.rb

@@ -1,10 +1,11 @@
+require 'tap/support/framework'
+
 module Tap
-  # = Overview
-  #
+
   # Tasks are the basic organizational unit of Tap.  Tasks provide
   # a standard backbone for creating the working parts of an application
   # by facilitating configuration, batched execution of methods, and 
-  # interaction with the command line.
+  # documentation.
   #
   # The functionality of Task is built from several base modules:
   # - Tap::Support::Batchable
@@ -80,190 +81,104 @@ module Tap
   #   end 
   #
   #   t = ValidatingTask.new
-  #   t.string = 1           # => ValidationError
-  #   t.integer = 1.1        # => ValidationError
+  #   t.string = 1           # !> ValidationError
+  #   t.integer = 1.1        # !> ValidationError
   #
   #   t.integer = "1"
   #   t.integer == 1         # => true 
   #
-  # Tasks have a name that gets used as a relative filepath to find
-  # associated files (for instance config_file). By default the task 
-  # name is based on the task class, such that Tap::Task corresponds
-  # to 'tap/task'.  Custom names can be provided when a task is 
-  # initialized, as can additional and/or overriding configurations.
+  # Tasks have a name that gets used in auditing, and as a relative 
+  # filepath to find associated files (for instance config files). 
+  # By default the task name is based on the task class, such that 
+  # Tap::Task has the default name 'tap/task'.  Configurations
+  # and custom names can be provided when a task is initialized.
   #
-  #   # [/path/to/app/config/example.yml]
-  #   # one: ONE
-  #  
-  #   t = ConfiguredTask.new "example", :three => 'three'
+  #   t = ConfiguredTask.new({:one => 'ONE', :three => 'three'}, "example")
   #   t.name                 # => "example"
-  #   t.app[:config]         # => "/path/to/app/config"
-  #   t.config_file          # => "/path/to/app/config/example.yml"
   #   t.config               # => {:one => 'ONE', :two => 'two', :three => 'three'}
   #
-  # Tasks can be assembled into batches that enque and execute 
-  # collectively. Batched tasks are automatically generated when a
-  # config_file specifies an array of configurations.
-  #
-  #   # [/path/to/app/config/batch.yml]
-  #   # - one: ONE
-  #   # - one: ANOTHER ONE
-  #
-  #   t = ConfiguredTask.new "batch"
-  #   t.batch.size           # => 2
-  #   t1, t2 = t.batch
-  #
-  #   t1.name                # => "batch"
-  #   t1.config              # => {:one => 'ONE', :two => 'two'}
-  #
-  #   t2.name                # => "batch"
-  #   t2.config              # => {:one => 'ANOTHER ONE', :two => 'two'}
-  #
   # === Batches
+  #  
+  # Tasks can be assembled into batches that enque and execute collectively.
+  # Batched tasks are often alternatively-configured derivatives of one 
+  # parent task, although they can be manually assembled using Task.batch.
   #
-  # Tasks facilitate batch processing of inputs using batched tasks.  Often 
-  # a batch consists of the the same task class instantiated with a variety 
-  # of configurations.  Once batched, tasks enque together; when any one of 
-  # the tasks is enqued, the entire batch is enqued.
-  #
-  #   runlist = []
-  #   t1 = Task.new {|task, input| runlist << input}
+  #   app = Tap::App.instance
+  #   t1 = Tap::Task.new(:key => 'one') do |task, input| 
+  #     input + task.config[:key]
+  #   end
   #   t1.batch               # => [t1]
   #
-  #   t2 = t1.initialize_batch_obj            
+  #   t2 = t1.initialize_batch_obj(:key => 'two')
   #   t1.batch               # => [t1, t2]
   #   t2.batch               # => [t1, t2]
   #   
-  #   t1.enq 1
-  #   t2.enq 2
-  #   t1.app.run
-  #
-  #   runlist                # => [1,1,2,2]
-  #
-  # Here runlist reflects that t1 and t2 were run in succession with the 1 
-  # input, and then the 2 input. 
-  #
-  # === Non-Task Tasks
-  #
-  # The essential behavior of a Task is expressed in the Tap::Task::Base 
-  # module.  Using this module, non-task classes can be made to behave like 
-  # tasks.  An even more fundamental module, Tap::Executable, allows any 
-  # method to behave in this manner.
-  #
-  # Configurations are specific to Task but batches are not.  Non-task 
-  # tasks can be batched.  Executable methods cannot be batched.
-  #
-  # See Tap::Task::Base and Tap::Support::Executable for more details as 
-  # well as Tap::Support::Rake::Task, which makes Rake[http://rake.rubyforge.org/] 
-  # tasks behave like Tap tasks.
-  class Task
-   
-    # Defines the essential behavior of a Task.  Using this module, 
-    # non-task classes can be made to behave like tasks; ie they can 
-    # be enqued, batched, and incorporated into workflows. 
-    module Base 
-      include Support::Executable
-      
-      attr_reader :app
-      
-      # Initializes obj to behave like a Task.  The input method will be
-      # called when obj is run by Tap::App.
-      def self.initialize(obj, method_name, app=App.instance)
-        obj.extend Base
-        obj.extend Support::Batchable
-        obj.instance_variable_set(:@app, app)
-        obj.instance_variable_set(:@batch, [])
-        obj.instance_variable_set(:@multithread, false)
-        obj.instance_variable_set(:@on_complete_block, nil)
-        obj.instance_variable_set(:@_method_name, method_name)
-        obj.initialize_batch_obj
-        obj
-      end
-    
-      # Enqueues self and self.batch to app with the inputs.  
-      # The number of inputs provided should match the number 
-      # of inputs specified by the arity of the _method_name method.
-      def enq(*inputs)
-        batch.each {|t| t.unbatched_enq(*inputs) }
-        self
-      end
-      
-      # Like enq, but only enques self and not self.batch.
-      def unbatched_enq(*inputs)
-        app.queue.enq(self, inputs)
-      end
-      
-      alias :unbatched_on_complete :on_complete
-      
-      # Sets the on_complete_block for self and self.batch.
-      # Use unbatched_on_complete to set the on_complete_block
-      # for just self.
-      def on_complete(override=false, &block)
-        batch.each {|t| t.unbatched_on_complete(override, &block)}
-        self
-      end
-      
-      alias :unbatched_multithread= :multithread=
-      
-      # Sets the multithread for self and self.batch.  Use 
-      # unbatched_multithread= to set multithread for just self.
-      def multithread=(value)
-        batch.each {|t| t.unbatched_multithread = value }
-        self
-      end
-      
-      # Raises a TerminateError if app.state == State::TERMINATE.
-      # check_terminate may be called at any time to provide a 
-      # breakpoint in long-running processes.
-      def check_terminate
-        if app.state == App::State::TERMINATE
-          raise App::TerminateError.new
-        end
-      end      
-    end
-    
-    include Base
-    include Support::Configurable
-    extend Support::CommandLineMethods
+  #   t1.enq 't1_by_'
+  #   t2.enq 't2_by_'
+  #   app.run
+  #
+  #   app.results(t1)        # => ["t1_by_one", "t2_by_one"]
+  #   app.results(t2)        # => ["t1_by_two", "t2_by_two"]
+  #
+  # Here the results reflects that t1 and t2 were run in succession with the 
+  # input to t1, and then the input to t2.
+  #
+  # === Subclassing
+  # Tasks can be subclassed normally, with one reminder related to batching.
+  #
+  # Batched tasks are generated by duplicating an existing instance, hence
+  # all instance variables will point to the same object in the batched
+  # and original task.  At times (as with configurations), this is 
+  # undesirable; the batched task should have it's own copy of an 
+  # instance variable.
+  #
+  # In these cases, the <tt>initialize_copy</tt> should be overridden
+  # and should re-initialize the appropriate variables.  Be sure to call
+  # super to invoke the default <tt>initialize_copy</tt>:
+  #
+  #   class SubclassTask < Tap::Task
+  #     attr_accessor :array
+  #     def initialize(*args)
+  #       @array = []
+  #       super
+  #     end
+  #  
+  #     def initialize_copy(orig)
+  #       @array = orig.array.dup
+  #       super
+  #     end
+  #   end
+  #
+  #   t1 = SubclassTask.new
+  #   t2 = t1.initialize_batch_obj
+  #   t1.array == t2.array                         # => true
+  #   t1.array.object_id == t2.array.object_id     # => false
+  #
+  class Task 
+    include Support::Executable
+    include Support::Framework
     
     attr_reader :task_block
     
-    # Creates a new Task with the specified attributes.  
-    #
-    # === Subclassing
-    # Batched tasks are generated by duplicating an existing instance, hence
-    # it is a good idea to set shared instance variables BEFORE calling super
-    # in a subclass initialize method.  Non-shared instance variables can be
-    # set by overriding the initialize_batch_obj method:
-    #
-    #   class SubclassTask < Tap::Task
-    #     attr_accessor :shared_variable, :instance_specific_variable
-    #
-    #     def initialize(*args)
-    #       @shared_variable = Object.new
-    #       super
-    #     end
-    #  
-    #     def initialize_batch_obj(*args)
-    #       task = super
-    #       task.instance_specific_variable = Object.new
-    #       task
-    #     end
-    #   end
-    #
-    #   t1 = SubclassTask.new
-    #   t2 = t1.initialize_batch_obj
-    #   t1.shared_variable == t2.shared_variable                           # => true
-    #   t1.instance_specific_variable == t2.instance_specific_variable     # => false
-    #
-    def initialize(name=nil, config={}, app=App.instance, &task_block)
+    def initialize(config={}, name=nil, app=App.instance, &task_block)
+      super(config, name, app)
+      
       @task_block = (task_block == nil ? default_task_block : task_block)
       @multithread = false
       @on_complete_block = nil
       @_method_name = :execute
-      super(name, config, app)
     end
     
+    # Enqueues self and self.batch to app with the inputs.  
+    # The number of inputs provided should match the number 
+    # of inputs specified by the arity of the _method_name method.
+    def enq(*inputs)
+      app.queue.enq(self, inputs)
+    end
+    
+    batch_function :enq, :multithread=
+    batch_function(:on_complete) {}
+    
     # Executes self with the given inputs.  Execute provides hooks for subclasses
     # to insert standard execution code: before_execute, on_execute_error,
     # and after_execute.  Override any/all of these methods as needed.
@@ -321,17 +236,6 @@ module Tap
       
       task_block.call(*inputs)
     end
-
-    # Logs the inputs to the application logger (via app.log)
-    def log(action, msg="", level=Logger::INFO)
-      # TODO - add a task identifier?
-      app.log(action, msg, level)
-    end
-    
-    # Returns self.name
-    def to_s
-      name
-    end
     
     protected
     

data/lib/tap/tasks/dump.rb

@@ -0,0 +1,56 @@
+module Tap
+  module Tasks
+    # :startdoc::manifest the default dump task
+    #
+    # A dump task to print application results to a file or IO.  The results are
+    # printed in a format allowing dumped results to be reloaded and used as
+    # inputs to other tasks.  See Tap::Load for more details.
+    #
+    # Often dump is used as the final task in a round of tasks; if no filepath is 
+    # specified, the results are printed to stdout.
+    #  
+    #   % tap run -- [your tasks] --+ dump FILEPATH
+    #
+    class Dump < Tap::FileTask
+    
+      config :date_format, '%Y-%m-%d %H:%M:%S'   # the date format
+      config :audit, true, &c.switch             # include the audit trails
+      config :date, true, &c.switch              # include a date
+    
+      def process(target=$stdout)
+        case target
+        when IO then dump_to(target)
+        else
+          log_basename(:dump, target)
+          prepare(target)
+          File.open(target, "wb") {|file| dump_to(file) }
+        end
+      end
+    
+      # Dumps the current results in app.aggregator to the io.
+      # The dump will include the result audits and a date,
+      # as specified in config.
+      def dump_to(io)
+        trails = []
+        results = {}
+        app.aggregator.to_hash.each_pair do |src, _results|
+          name = src.respond_to?(:name) ? src.name : ''
+
+          results["#{name} (#{src.object_id})"] = _results.collect {|_audit| _audit._current }
+          _results.each {|_audit| trails << _audit._to_s }
+        end
+      
+        if audit
+          io.puts "# audit:"
+          trails.each {|trail| io.puts "# #{trail.gsub("\n", "\n# ")}"}
+        end
+        
+        if date
+          io.puts "# date: #{Time.now.strftime(date_format)}"
+        end
+        
+        YAML::dump(results, io)
+      end
+    end
+  end
+end

data/lib/tap/tasks/rake.rb

@@ -0,0 +1,93 @@
+require 'rake'
+
+module Tap
+  module Tasks
+    # :startdoc::manifest run rake tasks
+    # 
+    # Simply enques the specified rake task(s) for execution.  Useful when a
+    # rake task needs to be executed within a workflow.  For example these
+    # are equivalent:
+    #
+    #   % tap run -- rake test
+    #   % rake test
+    # 
+    # The only exeception is in the use of the --help option.  Use --rake-help
+    # to access the rake help, and --help to access this help.
+    #
+    class Rake < Tap::Task
+    
+      # Modifies Rake::Application by adding a hook to the standard_exception_handling
+      # method.  This allows more fine-grained use of Rake::Applications by Tap.
+      module Application
+        def enq_top_level(app)
+          # takes the place of rake.top_level
+          if options.show_tasks
+            display_tasks_and_comments
+            exit
+          elsif options.show_prereqs
+            display_prerequisites
+            exit
+          else
+            top_level_tasks.each do |task_string|
+              name, args = parse_task_string(task_string)
+              task = self[name]
+            
+              unless task.kind_of?(Tap::Support::Executable)
+                Tap::Support::Executable.initialize(task, :invoke)
+              end
+            
+              app.enq(task, *args)
+            end
+          end  
+        end
+      end
+    
+      class << self
+      
+        # Overrides Tap::Support::FrameworkClass#instantiate to do  
+        # nothing so that all args get passed forward to rake.
+        def instantiate(argv, app=Tap::App.instance) # => instance, argv
+          if argv.include?('--help')
+            puts help
+            exit
+          end
+          [new({}, default_name, app), argv.collect {|arg| arg == '--rake-help' ? '--help' : arg}]
+        end
+      end
+    
+      #--
+      # def on_complete(override=false, &block)
+      #   @rake_tasks.each do |task|
+      #     task.on_complete(override, &block)
+      #   end
+      # end
+      #++
+      
+      def enq(*argv)
+        rake = ::Rake.application
+        unless rake.kind_of?(Application)
+          rake.extend Application
+        end
+
+        # run as if from command line using argv
+        current_argv = ARGV.dup
+        begin
+          ARGV.clear
+          ARGV.concat(argv)
+    
+          # now follow the same protocol as 
+          # in run, handling options
+          rake.init
+          rake.load_rakefile
+        ensure
+          ARGV.clear
+          ARGV.concat(current_argv)
+        end
+      
+        rake.enq_top_level(app)
+      
+        nil
+      end
+    end
+  end
+end