tap 0.7.9

data/lib/tap/support/batch_queue.rb

@@ -0,0 +1,165 @@
+require 'tap/support/audit'
+require 'monitor'
+
+module Tap
+  module Support
+    
+    # BatchQueue allows thread-safe enqueing and dequeing of tasks and inputs for 
+    # execution.  Until the task is dequeued, additional enqueuements will aggregate  
+    # the inputs into a batch.  The queue order is determined solely by the task;
+    # all accumulated inputs are dequeued at once.
+    #
+    #   # given tasks t1 and t2:
+    #   q = BatchQueue.new
+    #   q.enq t1, 1
+    #   q.enq t2, :a,:b,:c
+    #   q.enq t1, 2,3
+    #  
+    #   q.deq      # => [t1, [1,2,3]]
+    #   q.deq      # => [t2, [:a,:b,:c]]
+    #   q.deq      # => nil
+    #
+    # All BatchQueue methods are monitored such that they may only be accessed
+    # by one thread at a time, in order to ensure that transactions are atomic.
+    class BatchQueue
+      include MonitorMixin
+      
+      # creates a new BatchQueue
+      def initialize
+        super
+        self.clear
+      end
+      
+      # Clears the BatchQueue of all tasks and inputs.
+      def clear
+        synchronize do
+          self.inputs = {}
+          self.tasks = []
+        end
+      end
+      
+      # Returns the number of enqueued tasks (same as length)
+      def size
+        tasks.length
+      end
+      
+      # Returns the number of enqueued tasks (same as size)
+      def length
+        size
+      end
+      
+      # True if no tasks are enqueued
+      def empty?
+        tasks.empty?
+      end
+      
+      # Enqueues the inputs to the task.  If the task has not already been added to the 
+      # queue, then the task will be pushed onto the queue and the inputs registered.  
+      # Otherwise, the inputs will be added to the registered inputs; the task will 
+      # not be added to the queue twice.  If the task is batched, then each task in the
+      # batch will be enqueued in order, with the same inputs (Audit inputs will be forked 
+      # for each task).
+      def enq(task, *inputs)
+        synchronize do 
+          batch = task.batch
+          batch.each do |t|
+            tasks << t unless tasks.include?(t)
+            
+            inputs = inputs.collect do |result| 
+              result.kind_of?(Support::Audit) ? result._fork : result
+            end if batch.length > 1
+            
+            self.inputs[t] = [] unless self.inputs[t]
+            self.inputs[t].concat(inputs)
+          end
+        end
+      end
+      
+      # Enqueues the task and input, then prioritizes the task to the front of the queue.
+      def priority_enq(task, *inputs)
+        synchronize do
+          enq(task, *inputs)
+          prioritize(task)
+        end
+      end
+      
+      # Moves the task to the front of the queue.  Does not queue a task if the task is not 
+      # already in the queue.  If the task is batched, then each task in the batch will be 
+      # prioritized in order.
+      def prioritize(task)
+        synchronize do 
+          task.batch.reverse_each do |t|
+            tasks.unshift(t) if tasks.delete(t)
+          end
+        end
+      end
+      
+      # Moves the task to the back of the queue.  Does not queue a task if the task is not 
+      # already in the queue.  If the task is batched, then each task in the batch will be 
+      # marginalized in order.
+      def marginalize(task)
+        synchronize do 
+          task.batch.each do |t|
+            tasks.push(t) if tasks.delete(t)
+          end
+        end
+      end
+
+      # Returns true if the task is executable with the currently registered inputs
+      # (as determined by task.executable?).
+      def executable?(task)
+        synchronize do 
+          task.executable?(inputs[task])
+        end
+      end
+
+      # Dequeues the next executable task, or the specified task (even if it is not
+      # executable).  The task and the current inputs for the task are returned in 
+      # an array like: [task, inputs]. Returns nil if the task is not in the queue.
+      def deq(task=nil)
+        synchronize do   
+          task = peek if task.nil?
+
+          if tasks.include?(task)
+            [tasks.delete(task), inputs.delete(task)]
+          else
+            nil
+          end
+        end
+      end
+      
+      # Returns the next executable task, or nil if no queued tasks are executable.
+      # The task is not dequeued.
+      def peek
+        synchronize do  
+          tasks.each do |task|
+            next unless executable?(task) 
+            return task
+          end
+          nil
+        end
+      end
+      
+      # Returns the number of executable tasks in the queue.
+      def num_executable
+        synchronize do  
+          tasks.inject(0) do |count, task|
+            executable?(task) ? count + 1 : count
+          end
+        end
+      end
+      
+      # Returns the number of non-executable tasks in the queue.
+      def num_not_executable
+        synchronize do  
+          size - num_executable
+        end
+      end
+
+      protected
+      
+      attr_accessor :inputs, :tasks
+      
+    end 
+  end
+end

data/lib/tap/support/combinator.rb

@@ -0,0 +1,114 @@
+require 'enumerator'
+
+module Tap 
+  module Support
+    
+    # Combinator provides a method for iterating over all possible combinations
+    # of items in the input sets.
+    #
+    #   c = Combinator.new [1,2], [3,4]
+    #   c.collect         # => [[1,3], [1,4], [2,3], [2,4]]
+    #
+    # Combinator works by iteratively combining each element from the first set (a)
+    # with each element from the second set (b).  When more than two sets are given, 
+    # a Combinator will bundle all but the first set into a new Combinator which 
+    # then acts as the second set.
+    #
+    #   # Note: each element in a set is arrayified
+    #   # to simplify creation of the combination.
+    # 
+    #   c = Combinator.new [1,2], [3,4], [5,6]
+    #   c.a               # => [[1],[2]]
+    #   c.b.class         # => Combinator
+    #   c.b.a             # => [[3],[4]]
+    #   c.b.b             # => [[5],[6]]
+    #
+    # Thus when iterating, each Combinator makes it's pairwise combinations and
+    # works outwards to the final multi-set combinations.
+    class Combinator
+      include Enumerable
+      
+      attr_reader :a, :b
+
+      # Creates a new Combinator.  Input sets must be an Array, or nil.
+      # Within the Array any objects are allowed for combination.
+      def initialize(*sets)
+        @a = make_set(sets.shift)
+        @b = make_set(*sets)
+      end
+
+      # Returns the sets used to initialize the Combinator, minus any 
+      # nil or empty sets.
+      def sets
+        sets_in(a) + sets_in(b)
+      end
+
+      # True if the Combinator has no combinations.
+      def empty?
+        a.empty? && b.empty?
+      end
+
+      # Returns the number of combinations in the Combinator.
+      def length
+        if a.empty? || b.empty?
+          if !a.empty?
+            a.length
+          elsif !b.empty?
+            b.length
+          else
+            0
+          end
+        else
+          a.length * b.length
+        end
+      end
+
+      # Passes each combination as an array to the input block.
+      def each(&block)
+        # if either set is empty, iterate only the non-empty set
+        # note, the two-step check on each ensures that if both 
+        # sets are empty, then neither is iterated.
+        if a.empty? || b.empty?
+          if !a.empty?
+            a.each {|aa| yield aa }
+          elsif !b.empty?
+            b.each {|bb| yield bb }
+          end
+        else
+          # otherwise, iterate all combinations of both  
+          a.each do |aa|
+            b.each do |bb|
+              yield aa + bb
+            end
+          end
+        end
+      end
+
+      private
+
+      def sets_in(set)
+        # recursively de-arrayifies each element in the array
+        case set
+        when Combinator then set.sets
+        when Array then set.empty? ? [] : [set.collect {|s| s.first}]
+        end
+      end
+
+      def make_set(*sets)
+        # recieves an array of arrays or combinators
+        return Combinator.new(*sets) if sets.length > 1 
+        return [] if sets.empty?
+
+        # recursively arrayifies each element in an array
+        set = sets.first
+        case set
+        when Array then set.collect {|s| [s]}
+        when nil then []
+        else
+          raise ArgumentError.new("sets must be arrays or nil")
+        end
+      end
+
+    end
+  end
+end

data/lib/tap/support/logger.rb

@@ -0,0 +1,91 @@
+require 'logger'
+
+module Tap
+  module Support
+    # Logger provides methods to extend Logger objects.  
+    #
+    # The output format is designed to look nice in a command prompt, but provide useful information
+    # if directed at a log file.  The Logger output format is like:
+    #
+    #   I[datetime]           type message
+    #
+    # The first letter ('I' - INFO) indicates the severity of the message, next comes the datetime of the
+    # log, the type of log message, then the message itself.  Specify the log type and message like:
+    #
+    #   logger.type "message"
+    #
+    # 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.
+    module Logger
+      Format = "  %s[%s] %18s %s\n"
+      
+      def self.extended(base)
+        # On OS X (and maybe other systems), $stdout is not sync-ed.  
+        # Set sync to true so that writes are immediately flushed
+        # to the console.
+        base.logdev.dev.sync = true if base.logdev.dev == $stdout
+      end
+      
+      attr_writer :format
+      def format
+        (@format ||= nil) || Format
+      end
+      
+      # Provides direct access to the log device
+      def logdev
+        @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
+      
+      def format_add(level, msg, action=nil, &block)
+        current_format = self.format
+        self.format = yield(current_format)
+        add(level, msg, action.to_s)
+        self.format = current_format
+      end
+      
+      # Overrides the default format message to produce output like:
+      #
+      #   I[H:M:S]           type message
+      #
+      # If no progname is specified, '--' is used.
+      def format_message(severity, timestamp, progname, msg)
+        if timestamp.respond_to?(:strftime) && self.datetime_format
+          timestamp = timestamp.strftime(self.datetime_format) 
+        end
+        
+        format % [severity[0..0], timestamp, progname || '--' , msg]
+      end
+      
+      # Convenience method for creating section breaks in the output, formatted like:
+      #
+      #                     -----  message  -----
+      def section_break(message)
+        @logdev.write("                  -----  #{message}  -----\n")
+      end
+
+      private
+      
+      INFO = Object::Logger::INFO
+      
+      # Specifies that any unknown method calls will be treated as logging calls where the method
+      # is the log type, and the first argument is the message.  Types are underscored before logging.
+      def method_missing(method, *args, &block)
+        add(INFO, args.first, method.to_s.underscore, &block)
+      end
+    end
+  end
+end

data/lib/tap/support/rap.rb

@@ -0,0 +1,38 @@
+module Tap
+  module Support
+    
+    # Defines the minimum methods to run (ie to queue and to execute) 
+    # an object from Tap::App, aside from execute which must be 
+    # provided by the object itself.  Does not permit use in workflow
+    # methods (requires results, condition, and on_complete)
+    #
+    # == Advice
+    #
+    # If you ever want to multithread the object, execute should be 
+    # limited to one thread at a time, for example by wrapping it in 
+    # synchronize from the MonitorMixin.  You will probably get away
+    # without doing so unless you're adding the object to the queue
+    # multiple times in succession -- but be on the lookout for 
+    # unexpected results due to unsynchronized execution.
+    module Rap
+      attr_accessor :multithread
+
+      def multithread?
+        multithread
+      end
+
+      def executable?(inputs)
+        true
+      end
+      
+      def batch
+        @batch ||= [self]
+      end
+      
+      def batched?
+        batch.length > 1
+      end
+    end
+  end
+end      
+

data/lib/tap/support/run_error.rb

@@ -0,0 +1,20 @@
+module Tap
+  module Support
+    class RunError < RuntimeError
+      attr_reader :original_error, :terminate_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
+      end
+    end
+  end
+end

data/lib/tap/support/template.rb

@@ -0,0 +1,81 @@
+require 'tap/support/combinator'
+
+module Tap
+  module Support
+    
+    # Template provides the default methods for making hash templates using Templater.  
+    # Methods are provided to make variations of the template, as well as to pattern
+    # templates based on combinations of possible values.  
+    #
+    module Template
+      attr_accessor :templater
+      
+      # Provides a standard way of creating a variations of a template and takes an
+      # array of hashes with the specified variations. The template is treated as the 
+      # default and variations are pushed (<<) to the templater.  The template is 
+      # cleared upon complete, so that it will be removed if used in the context of
+      # a Templater.
+      #
+      #  t = {"default" => "default value"}.extend Template
+      #  t.templater = []
+      #  t.variations([
+      #    {"default" => "non-default value"},
+      #    {"another" => "value"}])
+      # 
+      #  t.templater        
+      #  # => [{"default" => "non-default value"}, 
+      #        {"default" => "default value", "another" => "value"}]
+      #
+      def variations(array)
+        variations!(array)
+        self.clear
+      end
+      
+      # Same as variations but does NOT clear the template (ie the template will
+      # be kept as specified, effectively acting as another variant).  Note that
+      # variations! is called by the 'variations!!' key.
+      def variations!(array)
+        array.each { |var| templater << self.merge(var) }
+      end
+
+      # Provides a standard way of creating variations of a template based on all 
+      # combinations of the keys in the input hash.  The template itself is treated 
+      # as the default and variations are pushed (<<) to the templater. The template 
+      # is cleared upon complete, so that it will be removed if used in the context of
+      # a Templater.
+      #
+      #  t = {"default" => "default value"}.extend Template
+      #  t.templater = []
+      #  t.combinations(
+      #    "letter" => ["a", "b"],
+      #    "number" => [1, 2])
+      #  
+      #  t.templater        
+      #  # => [{"default" => "default value", "letter" => "a", "number" => 1}, 
+      #        {"default" => "default value", "letter" => "a", "number" => 2},
+      #        {"default" => "default value", "letter" => "b", "number" => 1},
+      #        {"default" => "default value", "letter" => "b", "number" => 2}]
+      def combinations(hash)
+        combinations!(hash)
+        self.clear
+      end
+      
+      # Same as combinations but does NOT clear the template (ie the template will
+      # be kept as specified, effectively acting as another variant).  Note that 
+      # combinations! is called by the 'combinations!!' key.
+      def combinations!(hash)
+        keys, values = hash.to_a.transpose
+        values.collect! do |value| 
+          value.kind_of?(Array) ? value : [value]
+        end
+
+        Combinator.new(*values).each do |c|
+          template = {}
+          keys.each_with_index {|key,i| template[key] = c[i] }
+
+          templater << self.merge(template)
+        end
+      end
+    end
+  end
+end