tap 0.10.1 → 0.11.0

data/lib/tap/support/executable.rb

@@ -2,56 +2,250 @@ require 'tap/support/audit'
 
 module Tap
   module Support
-    # Executable wraps methods to make them executable by App.  Methods are 
-    # wrapped by extending the object that receives them; the easiest way
-    # to make an object executable is to use Object#_method.
+    
+    # Executable wraps objects to make them executable by App.
     module Executable
       
-      # The method called when an Executable is executed via _execute
+      # The App receiving self during enq
+      attr_reader :app
+      
+      # The method called during _execute
       attr_reader :_method_name
     
-      # Indicates whether or not to execute in multithread mode.
-      attr_accessor :multithread
-
-      # Stores the on complete block.
+      # The block called when _execute completes
       attr_reader :on_complete_block
-    
+      
+      # An array of dependency indicies that will be resolved on _execute
+      attr_reader :dependencies
+      
+      # The batch for self
+      attr_reader :batch
+      
       public
       
       # Extends obj with Executable and sets up all required variables.  The
       # specified method will be called on _execute.
-      def self.initialize(obj, method_name, multithread=false, &on_complete_block)
+      def self.initialize(obj, method_name, app=App.instance, batch=[], dependencies=[], &on_complete_block)
         obj.extend Executable
+        obj.instance_variable_set(:@app, app)
         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.instance_variable_set(:@dependencies, dependencies)
+        obj.instance_variable_set(:@batch, batch)
+        batch << obj
+        
         obj
       end
-    
-      # Sets a block to receive the results of _execute.  Raises an error 
-      # if an on_complete block is already set.  Override an existing
-      # on_complete block by specifying override = true.
+      
+      # Initializes a new batch object and adds the object to batch.
+      # The object will be a duplicate of self.  (Note this method
+      # can raise an error for objects that don't support dup, 
+      # notably Method objects generated by Object#_method).
+      def initialize_batch_obj
+        obj = self.dup
+        
+        if obj.kind_of?(Executable)
+          batch << obj
+          obj
+        else
+          Executable.initialize(obj, _method_name, app, batch, dependencies, &on_complete_block)
+        end
+      end
+      
+      # Returns true if the batch size is greater than one 
+      # (the one is assumed to be self).  
+      def batched?
+        batch.length > 1
+      end
+
+      # Returns the index of self in batch.
+      def batch_index
+        batch.index(self)
+      end
+      
+      # Merges the batches for self and the specified Executables,
+      # removing duplicates.
+      #
+      #   class BatchExecutable
+      #     include Tap::Support::Executable
+      #     def initialize(batch=[])
+      #       @batch = batch
+      #       batch << self
+      #     end
+      #   end
+      #
+      #   b1 = BatchExecutable.new
+      #   b2 = BatchExecutable.new
+      #   b3 = BatchExecutable.new
+      #
+      #   b1.batch_with(b2, b3)
+      #   b1.batch                   # => [b1, b2, b3]
+      #   b3.batch                   # => [b1, b2, b3]
+      #
+      # Note that batch_with is not recursive (ie it does not 
+      # merge the batches of each member in the batch):
+      #
+      #   b4 = BatchExecutable.new
+      #   b4.batch_with(b3)   
+      #            
+      #   b4.batch                   # => [b4, b1, b2, b3]
+      #   b3.batch                   # => [b4, b1, b2, b3]
+      #   b2.batch                   # => [b1, b2, b3]
+      #   b1.batch                   # => [b1, b2, b3]
+      #
+      # However it does affect all objects that share the same
+      # underlying batch:
+      #
+      #   b5 = BatchExecutable.new(b1.batch)
+      #   b6 = BatchExecutable.new
+      #
+      #   b5.batch.object_id         # => b1.batch.object_id
+      #   b5.batch                   # => [b1, b2, b3, b5]
+      #
+      #   b5.batch_with(b6)
+      #
+      #   b5.batch                   # => [b1, b2, b3, b5, b6]
+      #   b1.batch                   # => [b1, b2, b3, b5, b6]
+      #
+      # Returns self.
+      def batch_with(*executables)
+        batches = [batch] + executables.collect {|executable| executable.batch }
+        batches.uniq!
+        
+        merged = []
+        batches.each do |batch| 
+          merged.concat(batch)
+          batch.clear
+        end
+        
+        merged.uniq!
+        batches.each {|batch| batch.concat(merged) }
+        self
+      end
+      
+      # Enqueues each member of batch (and implicitly self) to app with the
+      # inputs. The number of inputs provided should match the number of
+      # inputs for the _method_name method.
+      def enq(*inputs)
+        batch.each do |executable| 
+          executable.unbatched_enq(*inputs)
+        end
+        self
+      end
+      
+      # Like enq, but only enques self.
+      def unbatched_enq(*inputs)
+        app.queue.enq(self, inputs)
+        self
+      end
+      
+      # Sets a block to receive the results of _execute for each member of 
+      # batch (and implicitly self).  Raises an error if on_complete_block
+      # is already set within the batch.  Override the existing 
+      # on_complete_block by specifying override = true.
       #
-      # Note the block recieves an audited result and not
-      # the result itself (see Audit for more information).
+      # 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
+        batch.each do |executable| 
+          executable.unbatched_on_complete(override, &block)
+        end
+        self
+      end
+      
+      # Like on_complete, but only sets the on_complete_block for self.
+      def unbatched_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
+        self
+      end
+      
+      # Sets a sequence workflow pattern for the tasks; each task
+      # enques the next task with it's results, starting with self.  
+      # See Joins::Sequence.
+      def sequence(*tasks, &block) # :yields: _result
+        Joins::Sequence.join(self, tasks, &block)
+      end
+
+      # Sets a fork workflow pattern for self; each target
+      # will enque the results of self.  See Joins::Fork.
+      def fork(*targets, &block) # :yields: _result
+        Joins::Fork.join(self, targets, &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.
+      # Sets a simple merge workflow pattern for the source tasks. Each 
+      # source enques self with it's result; no synchronization occurs, 
+      # nor are results grouped before being enqued.  See Joins::Merge.
+      def merge(*sources, &block) # :yields: _result
+        Joins::Merge.join(self, sources, &block)
+      end
+
+      # Sets a synchronized merge workflow for the source tasks.  Results 
+      # from each source are collected and enqued as a single group to
+      # self.  The collective results are not enqued until all sources
+      # have completed.  See Joins::SyncMerge.
+      #
+      # Raises an error if a source returns twice before the target is enqued.
+      def sync_merge(*sources, &block) # :yields: _result
+        Joins::SyncMerge.join(self, sources, &block)
+      end
+
+      # Sets a switch workflow pattern for self.  When _execute completes, 
+      # switch yields the audited result to the block which should return
+      # the index of the target to enque with the results. No target will 
+      # be enqued if the index is false or nil; an error is raised if no 
+      # target can be found for the specified index. See Joins::Switch.
+      def switch(*targets, &block) # :yields: _result
+        Joins::Switch.join(self, targets, &block)
+      end
+      
+      # Adds the dependency to each member in batch (and implicitly self).
+      # The dependency will be resolved with the input arguments during 
+      # _execute, using resolve_dependencies.
+      def depends_on(dependency)
+        batch.each do |e| 
+          e.unbatched_depends_on(dependency)
+        end
+        self
+      end
+      
+      # Like depends_on, but only adds the dependency to self.
+      def unbatched_depends_on(dependency)
+        raise ArgumentError, "cannot depend on self" if dependency == self
+        
+        app.dependencies.register(dependency)
+        dependencies << dependency unless dependencies.include?(dependency)
+        self
+      end
+      
+      # Resolves dependencies. (See Dependency#resolve).
+      def resolve_dependencies
+        dependencies.each {|dependency| dependency.resolve }
+        self
+      end
+      
+      # Resets dependencies so they will be re-resolved on
+      # resolve_dependencies. (See Dependency#reset).
+      def reset_dependencies
+        dependencies.each {|dependency| dependency.reset }
+        self
+      end
+      
+      # Auditing method call.  Resolves dependencies, executes _method_name,
+      # and 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.
+      # no inputs:: Creates 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)
+        resolve_dependencies
+        
         audit = case inputs.length
         when 0 then Audit.new
         when 1 
@@ -77,10 +271,30 @@ module Tap
         end
       
         audit._record(self, send(_method_name, *inputs))
-        on_complete_block.call(audit) if on_complete_block
-      
+        on_complete_block ? on_complete_block.call(audit) : app.aggregator.store(audit)
+        
         audit
       end
+      
+      # Calls _execute with the inputs and returns the un-audited result.
+      # Execute is not a batched method.
+      def execute(*inputs)
+        _execute(*inputs)._current
+      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
+      
+      def inspect
+        "#<#{self.class.to_s}:#{object_id} _method: #{_method_name} batch_length: #{batch.length} app: #{app}>"
+      end
+      
     end
   end
 end
@@ -92,7 +306,7 @@ end
 #   push_to_array = array._method(:push)
 #
 #   task = Tap::Task.new  
-#   task.app.sequence(task, push_to_array)
+#   task.sequence(push_to_array)
 #
 #   task.enq(1).enq(2,3)
 #   task.app.run
@@ -101,11 +315,12 @@ end
 #
 class Object
   
-  # Initializes a Tap::Support::Executable using the Method returned by
-  # Object#method(method_name), setting multithread and the on_complete 
-  # block as specified.  Returns nil if Object#method returns nil.
-  def _method(method_name, multithread=false, &on_complete_block) # :yields:  _result
+  # Initializes a Tap::Support::Executable using the object returned by
+  # Object#method(method_name).
+  #
+  # Returns nil if Object#method returns nil.
+  def _method(method_name, app=Tap::App.instance)
     return nil unless m = method(method_name)
-    Tap::Support::Executable.initialize(m, :call, multithread, &on_complete_block)
+    Tap::Support::Executable.initialize(m, :call, app)
   end
 end

data/lib/tap/support/executable_queue.rb

@@ -71,7 +71,7 @@ module Tap
       
       protected
       
-      attr_accessor :queue
+      attr_accessor :queue # :nodoc:
       
       # Checks if the input method is extended with Executable
       def check_method(method) # :nodoc:

data/lib/tap/support/gems/rake.rb

@@ -21,8 +21,28 @@ module Tap
       
         attr_accessor :env
        
-        def collect_tasks
-          ARGV.collect! do |arg|
+        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]
+              app.mq(task, :invoke, *args)
+            end
+          end  
+        end
+        
+        def collect_tasks(*args)
+          # a little song and dance for compliance with
+          # rake pre- and post-0.8.2
+          argv = args.empty? ? ARGV : args[0]
+          argv.collect! do |arg|
             next(arg) unless arg =~ /^:([a-z_\d]+):(.*)$/
             env_pattern = $1
             rake_task = $2
@@ -55,13 +75,13 @@ module Tap
               fail "No Rakefile found for '#{env_pattern}' (looking for: #{@rakefiles.join(', ')})"
             end
           end
-        
+          
           super
         end
       
-        def have_rakefile(indir=nil)
-          return super() if indir == nil
-          Tap::Root.indir(indir) { super() }
+        def have_rakefile(dir=nil)
+          return super() if dir == nil
+          Tap::Root.chdir(dir) { super() }
         end
 
         protected
@@ -86,5 +106,6 @@ end
 end
 
 Rake.application.extend Tap::Support::Gems::Rake
-Tap::Env.manifests[:rakefiles] = Tap::Support::RakeManifest
-
+Tap::Env.manifest(:rakefiles) do |env|
+  Tap::Support::Gems::RakeManifest.new(env)
+end

data/lib/tap/support/gems.rb

@@ -1,36 +1,13 @@
-autoload(:Gem, 'rubygems')
+require 'rubygems'
 
 module Tap
   module Support
-    module Gems
-      module_function
-      
-      # Finds the home directory for the user (method taken from Rubygems).
-      def find_home
-        ['HOME', 'USERPROFILE'].each do |homekey|
-          return ENV[homekey] if ENV[homekey]
-        end
-
-        if ENV['HOMEDRIVE'] && ENV['HOMEPATH'] then
-          return "#{ENV['HOMEDRIVE']}:#{ENV['HOMEPATH']}"
-        end
-
-        begin
-          File.expand_path("~")
-        rescue
-          if File::ALT_SEPARATOR then
-              "C:/"
-          else
-              "/"
-          end
-        end
-      end
-
-      # The home directory for the user.
-      def user_home
-        @user_home ||= find_home
-      end
-      
+    
+    # Methods for working with {RubyGems}[http://www.rubygems.org/] 
+    # and other gems frequently used by Tap.
+    module Gems
+      module_function
+
       # Returns the gemspec for the specified gem.  A gem version 
       # can be specified in the name, like 'gem >= 1.2'.  The gem 
       # will be activated using +gem+ if necessary.
@@ -49,6 +26,9 @@ module Tap
         Gem.loaded_specs[name]
       end
       
+      # Selects gem specs for which the block returns true.  If
+      # latest is specified, only the latest version of each
+      # gem will be passed to the block.
       def select_gems(latest=true)
         index = latest ?
           Gem.source_index.latest_specs :

data/lib/tap/support/instance_configuration.rb

@@ -47,11 +47,24 @@ module Tap
         @class_config = class_config
       end
       
+      # Updates self to ensure that each class_config key
+      # has a value in self; the config.default value is
+      # set if a value does not already exist.
+      #
+      # Returns self.
+      def update(class_config=self.class_config)
+        class_config.each_pair do |key, config|
+          self[key] ||= config.default
+        end
+        self
+      end
+      
       # Binds self to the specified receiver.  Mapped keys are
       # removed from store and sent to their writer method on 
       # receiver.
       def bind(receiver)
-        raise ArgumentError.new("receiver cannot be nil") if receiver == nil
+        raise "already bound to: #{@receiver}" if bound?
+        raise ArgumentError, "receiver cannot be nil" if receiver == nil
         
         class_config.each_pair do |key, config|
           receiver.send(config.writer, store.delete(key)) if config.writer
@@ -88,7 +101,7 @@ module Tap
       
       # Associates the value the key.  If bound? and the key
       # is a class_config key, then the value will be forwarded
-      # to the class_config.writer method on the receiver.
+      # to the config.writer method on the receiver.
       def []=(key, value)
         case 
         when bound? && config = class_config.map[key.to_sym]
@@ -99,7 +112,7 @@ module Tap
       
       # Retrieves the value corresponding to the key. If bound? 
       # and the key is a class_config key, then the value is
-      # obtained from the :key method on the receiver.
+      # obtained from the config.reader method on the receiver.
       def [](key)
         case 
         when bound? && config = class_config.map[key.to_sym]
@@ -138,6 +151,19 @@ module Tap
         hash
       end
       
+      def to_yaml(opts)
+        hash = {}
+        store.each_pair do |key, value|
+          hash[key.to_s] = value
+        end
+        
+        class_config.each_pair do |key, config|
+          hash[key.to_s] = bound? ? self[key] : config.default
+        end
+        
+        hash.to_yaml(opts)
+      end
+      
       # Overrides default inspect to show the to_hash values.
       def inspect
         "#<#{self.class}:#{object_id} to_hash=#{to_hash.inspect}>"

data/lib/tap/support/intern.rb

@@ -0,0 +1,46 @@
+module Tap
+  module Support
+    
+    # Generates an Intern module for the specified method_name.
+    # An Intern module:
+    # - adds an accessor for <method_name>_block
+    # - overrides <method_name> to call the block
+    # - ensures initialize_batch_obj extends the batch object
+    #   with the same Intern module
+    #
+    def self.Intern(method_name)
+      mod = INTERN_MODULES[method_name.to_sym]
+      return mod unless mod == nil
+      
+      mod = INTERN_MODULES[method_name.to_sym] = Module.new
+      mod.module_eval %Q{
+      attr_accessor :#{method_name}_block
+
+      def #{method_name}(*inputs)
+        raise "no #{method_name} block set" unless #{method_name}_block
+        inputs.unshift(self)
+      
+        arity = #{method_name}_block.arity
+        n = inputs.length
+        unless n == arity || (arity < 0 && (-1-n) <= arity) 
+          raise ArgumentError.new("wrong number of arguments (\#{n} for \#{arity})")
+        end
+      
+        #{method_name}_block.call(*inputs)
+      end
+      
+      def initialize_batch_obj(*args)
+        super(*args).extend Tap::Support::Intern(:#{method_name})
+      end
+      }
+      mod
+    end
+    
+    # An array of already-declared intern modules,
+    # keyed by method_name.
+    INTERN_MODULES = {}
+    
+    # An Intern module for :process.
+    Intern = Support.Intern(:process)
+  end
+end