tap 0.9.1 → 0.10.0

data/lib/tap/support/aggregator.rb

@@ -1,7 +1,7 @@
 module Tap
-  module Support
-  
-    # Aggregator allows thread-safe collection of Audits, organized
+  module Support
+  
+    # Aggregator allows thread-safe collection of Audits, organized
     # by Audit#_current_source.    
     class Aggregator < Monitor
 
@@ -9,39 +9,39 @@ module Tap
         super
         clear
       end
-      
+      
       # Clears self of all audits.
       def clear
         synchronize { self.hash = Hash.new }
       end
-      
+      
       # The total number of audits recorded in self.
       def size
         synchronize { hash.values.inject(0) {|sum, array| sum + array.length} }
       end
-      
+      
       # True if size == 0
       def empty?
         synchronize { hash.empty? }
       end
-      
+      
       # Stores the Audit according to _result._current_source
       def store(_result)
         synchronize { (hash[_result._current_source] ||= []) << _result }
       end
-      
+      
       # Retreives all aggregated audits for the specified source.
       def retrieve(source)
         synchronize { hash[source] }
       end
-      
+      
       # Retreives all audits for the input sources, joined into an array.
       def retrieve_all(*sources)
         synchronize do
           sources.collect {|src| hash[src] }.flatten.compact
         end
       end
-      
+      
       # Converts self to a hash of (source, audits) pairs.
       def to_hash
         hash.dup
@@ -49,7 +49,7 @@ module Tap
       
       protected
       
-      attr_accessor :hash
+      attr_accessor :hash # :nodoc:
     end
   end
 end

data/lib/tap/support/assignments.rb

@@ -0,0 +1,172 @@
+module Tap
+  module Support
+    
+    # Assignments defines an array of [key, values] pairs that tracks 
+    # which values are assigned to a particular key.  A value may only 
+    # be assigned to one key at a time.  
+    #
+    # Assignments tracks the order in which keys are declared, and the
+    # order in which values are assigned to a key.  This behavior is
+    # used by ClassConfiguration to track the order in which configurations  
+    # are assigned to a class; the order, in turn, is used in the formation
+    # of config files, command line documentation, etc.
+    #
+    # === Example
+    #
+    #   a = Assignments.new
+    #   a.assign(:one, 'one')
+    #   a.assign(:two, 'two')
+    #   a.assign(:one, 'ONE')
+    #   a.to_a          # => [[:one, ['one', 'ONE']], [:two, ['two']]]
+    #
+    #   b = Assignments.new(a)
+    #   b.to_a          # => [[:one, ['one', 'ONE']], [:two, ['two']]]
+    #
+    #   b.unassign('one')
+    #   b.assign(:one, 1)
+    #   b.to_a          # => [[:one, ['ONE', 1]], [:two, ['two']]]
+    #   a.to_a          # => [[:one, ['one', 'ONE']], [:two, ['two']]]
+    #
+    #--
+    # TODO: 
+    #   Assignments may be optimizable... check if an alternate internal 
+    #   storage can be made faster or to take up less memory.  Not that
+    #   that much can be gained period...
+    class Assignments
+      include Enumerable
+      
+      def initialize(parent=nil)
+        existing_array = case parent
+        when Assignments then parent.array
+        when Array then parent
+        when nil then []
+        else 
+          raise ArgumentError.new("cannot convert #{parent.class} to Assignments, Array, or nil")
+        end
+        
+        @array = []
+        existing_array.each do |key, values|
+          assign(key, *values)
+        end
+      end
+      
+      # Adds the key to the declarations.
+      def declare(key)
+        array << [key, []] unless declared?(key)
+      end
+      
+      # Removes all values for the specified key and 
+      # removes the key from declarations.
+      def undeclare(key)
+        array.delete_if {|k, values| k == key}
+      end
+      
+      # Returns true if the key is declared.
+      def declared?(key)
+        array.each do |k, values|
+          return true if k == key
+        end
+        false
+      end
+      
+      # Returns an array of all the declared keys
+      def declarations
+        array.collect {|key, values| key }
+      end
+
+      # Assigns the specified values to the key.  The key will
+      # be declared, if necessary. Raises an error if the key
+      # is nil. 
+      def assign(key, *values)
+        raise ArgumentError.new("nil keys are not allowed") if key == nil
+        
+        # partition the input values into existing and new
+        # values, then check for conflicts.
+        current_values = self.values
+        existing_values, new_values = values.partition {|value| current_values.include?(value) }
+        
+        conflicts = []
+        existing_values.collect do |value|
+          current_key = key_for(value)
+          if current_key != key 
+            conflicts << "#{value} (#{key}) already assigned to #{current_key}"
+          end
+        end
+        
+        unless conflicts.empty?
+          raise ArgumentError.new(conflicts.join("\n"))
+        end
+        
+        declare(key)
+        values_for(key).concat new_values
+      end
+      
+      # Removes the specified value.
+      def unassign(value)
+        array.each do |key, values| 
+          values.delete(value)
+        end
+      end
+      
+      # Returns true if the value has been assigned to a key.
+      def assigned?(value)
+        array.each do |key, values|
+          return true if values.include?(value)
+        end
+        false
+      end
+
+      # Returns the ordered values as an array
+      def values
+        array.collect {|key, values| values}.flatten
+      end
+  
+      # Returns the key for the specified value, or nil 
+      # if the value is unassigned.
+      def key_for(value)
+        array.each do |key, values| 
+          return key if values.include?(value)
+        end
+        nil
+      end
+      
+      # Returns the values for the specified key, or nil if
+      # the key cannot be found.
+      def values_for(key)
+        array.each do |k, values| 
+          return values if k == key
+        end
+        nil
+      end
+
+      # Yields each key, value pair in the order in which
+      # the keys were declared. Keys with no values are 
+      # skipped.
+      def each
+        array.each do |key, values|
+          values.each {|value| yield(key, value) }
+        end
+      end
+      
+      # Yields each key, values pair in the order in which
+      # the keys were declared.
+      def each_pair
+        array.each do |key, values|
+          yield(key, values)
+        end
+      end
+      
+      # Returns the [key, values] as an array
+      def to_a
+        array.collect {|key, values| [key, values.dup] }
+      end
+      
+      protected
+      
+      # An array of [key, values] arrays tracking the 
+      # key and order in which values were assigned. 
+      attr_reader :array
+      
+    end
+  end
+end

data/lib/tap/support/audit.rb

@@ -1,3 +1,5 @@
+autoload(:PP, 'pp')
+      
 module Tap
   module Support 
     
@@ -28,17 +30,15 @@ module Tap
       end
     end
 
-    # == Overview
-    #
     # Audit provides a way to track the values (inputs and results) passed
-    # among tasks.  Audits allow you to track inputs as they make their
-    # way through a workflow, and have a great deal of importance for 
-    # debugging and record keeping. 
+    # among tasks or, more generally, any Executable method.  Audits allow 
+    # you to track inputs as they make their way through a workflow, and 
+    # have great utility in debugging and record keeping. 
     #
     # During execution, the group of inputs for a task are used to initialize 
     # an Audit.  These inputs mark the begining of an audit trail; every 
-    # task that processes them (including the first) records it's result in 
-    # the trail with the task as the 'source' of the result.
+    # task that processes them (including the first) adds to the trail by 
+    # recording it's result using itself as the 'source' of the result.
     #
     # Since Audits are meant to be fairly general structures, they can take 
     # any object as a source, so for illustration lets use some symbols:
@@ -50,7 +50,7 @@ module Tap
     #   a._record(:A, 2)
     #   a._record(:B, 3)
     #
-    # Now you can pull up the trails of sources and values, as well as 
+    # Now you can pull up the source and value trails, as well as 
     # information like the current and original values:
     #
     #   a._source_trail      # => [nil, :A, :B]
@@ -62,8 +62,9 @@ module Tap
     #   a._current           # => 3
     #   a._current_source    # => :B
     #
-    # Merges are supported by using an array of the merging trails as the 
-    # source, and an array of the merging values as the initial value.  
+    # Merges are supported by using an array of the merging trails (internally
+    # an AuditMerge) as the source, and an array of the merging values as the 
+    # initial value.  
     #
     #   b = Audit.new(10, nil)
     #   b._record(:C, 11)
@@ -84,7 +85,7 @@ module Tap
     # Audit supports forks by duplicating the source and value trails.  Forks
     # can be developed independently.  Importantly, Audits are forked during 
     # a merge; notice the additional record in +a+ doesn't change the source 
-    # trail for +c+ 
+    # trail for +c+:
     #
     #   a1 = a._fork
     #
@@ -120,9 +121,8 @@ module Tap
     #
     #--
     # TODO:
-    # Create an AuditMerge class to mark merges (don't use arrays).  Track nesting level
-    # of ams; see if you can hook this into _to_s process to make extraction/presentation
-    # of audits more managable.
+    # Track nesting level of ams; see if you can hook this into the _to_s process to make 
+    # extraction/presentation of audits more managable.
     #
     # Create a FirstLastArray to minimize the audit data collected.  Allow different audit
     # modes:
@@ -140,8 +140,6 @@ module Tap
     #         `-----`-----`-o-[j] j5
     #
     class Audit
-      autoload(:PP, 'pp')
-      
       class << self
 
         # Creates a new Audit by merging the input audits. The value of the new 
@@ -177,7 +175,11 @@ module Tap
         end
       end
       
-      attr_reader :_sources, :_values
+      # An array of the sources in self
+      attr_reader :_sources
+      
+      # An array of the values in self
+      attr_reader :_values
       
       # An arbitrary constant used to identify when no inputs have been
       # provided to Audit.new.  (nil itself cannot be used as nil is a 
@@ -378,7 +380,7 @@ module Tap
       
       protected  
 
-      attr_writer :_sources, :_values
+      attr_writer :_sources, :_values # :nodoc:
 
       private
       

data/lib/tap/support/batchable.rb

@@ -1,16 +1,28 @@
+require 'tap/support/batchable_class'
+
 module Tap
   module Support
 
     # Batchable encapsulates the methods used to support batching
-    # of tasks. See the 'Batches' section in the Tap::Task 
-    # documentation for more details on how Batchable works in 
-    # practice.
+    # of tasks. Classes including Batchable should call <tt>super</tt>
+    # during initialization to initialize batch, or they should 
+    # initialize batch themselves.
+    #
+    # See the 'Batches' section in the Tap::Task documentation for 
+    # details on how Batchable works in practice.
     module Batchable
-      extend Support::BatchableMethods
+    
+      def self.included(mod)
+        mod.extend Support::BatchableClass if mod.kind_of?(Class)
+      end
       
-      # The object batch. (must be initializd by classes that
-      # include Batchable)
+      # The object batch.
       attr_reader :batch
+      
+      def initialize(batch=[])
+        @batch = batch
+        @batch << self
+      end
     
       # Returns true if the batch size is greater than one 
       # (the one being self).  
@@ -21,13 +33,12 @@ module Tap
       # Returns the index of the self in batch.
       def batch_index
         batch.index(self)
-      end   
+      end
       
       # Initializes a new batch object and adds the object to batch.
-      # The object will be self if batch is empty (ie for the first
-      # call) or a duplicate of self if not.
+      # The object will be a duplicate of self.
       def initialize_batch_obj
-        obj = (batch.empty? ? self : self.dup)
+        obj = self.dup
         batch << obj
         obj
       end

data/lib/tap/support/batchable_class.rb

@@ -0,0 +1,107 @@
+module Tap
+  module Support
+    
+    # BatchableClass encapsulates class methods related to Batchable.
+    module BatchableClass
+      
+      # Merges the batches for the specified objects.  All objects 
+      # sharing the individual object batches will be affected, even 
+      # if they are not listed explicitly as an input.
+      #
+      #  t1 = Tap::Task.new
+      #  t2 = Tap::Task.new
+      #  t3 = t2.initialize_batch_obj
+      #
+      #  Tap::Task.batch(t1, t2)
+      #  t3.batch                    # => [t1,t2,t3]
+      #
+      # Returns the new batch.
+      def batch(*batchables)
+        merged = []
+        batches = batchables.collect {|batchable| batchable.batch }.uniq
+        batches.each do |batch| 
+           merged.concat(batch)
+           batch.clear
+         end
+        merged.uniq!
+        batches.each {|batch| batch.concat(merged) }
+        merged
+      end
+      
+      protected
+      
+      # Redefines the specified method(s) as batched methods.  The existing method
+      # is renamed as <tt>unbatched_method</tt> and <tt>method</tt> redefined to 
+      # call <tt>unbatched_method</tt> on each object in the batch.
+      #
+      #   def process(one, two)
+      #     ...
+      #   end
+      #   batch_function(:process)
+      #
+      # Is equivalent to:
+      #
+      #   def unbatched_process(one, two)
+      #     ...
+      #   end
+      #
+      #   def process(one, two)
+      #     batch.each do |t|
+      #      t.unbatched_process(one, two)
+      #     end
+      #     self
+      #   end
+      #
+      # The batched method will accept/pass as many arguments as are defined for
+      # the unbatched method.  Splats are supported, and blocks are supported too 
+      # by passing a block to batch_function:
+      #
+      #   def process(arg, *args, &block)
+      #     ...
+      #   end
+      #   batch_function(:process) {}
+      #
+      # Is equivalent to:
+      #
+      #   def unbatched_process(arg, *args, &block)
+      #     ...
+      #   end
+      #
+      #   def process(*args, &block)
+      #     batch.each do |t|
+      #      t.unbatched_process(*args, &block)
+      #     end
+      #     self
+      #   end
+      #
+      # Obviously there are limitations to batch_function, most notably batching
+      # functions with default values.  In these cases, batch functionality
+      # must be implemented manually.
+      def batch_function(*methods)
+        methods.each do |method_name|
+          unbatched_method = "unbatched_#{method_name}"
+          if method_defined?(unbatched_method)
+            raise "unbatched method already defined: #{unbatched_method}"
+          end
+          
+          arity = instance_method(method_name).arity
+          args = case
+          when arity < 0 then "*args"
+          else Array.new(arity) {|index| "arg#{index}" }.join(", ")
+          end 
+          args += ", &block" if block_given?
+ 
+          class_eval %Q{
+            alias #{unbatched_method} #{method_name}
+            def #{method_name}(#{args})
+              batch.each do |t|
+                t.#{unbatched_method}(#{args})
+              end
+              self
+            end
+          }
+        end
+      end
+    end 
+  end
+end