tap 0.10.1 → 0.11.0

data/lib/tap/support/assignments.rb

@@ -5,14 +5,12 @@ module Tap
     # 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
+    # Assignments tracks the order of key declaration, 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
+    # used by ClassConfiguration to track the order of configurations  
+    # in 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')
@@ -35,6 +33,9 @@ module Tap
     class Assignments
       include Enumerable
       
+      # Generates a new Assignments using the parent array of
+      # [key, values] pairs.  Uses parent.array if parent is
+      # an Assignments, or [] if parent is nil.
       def initialize(parent=nil)
         existing_array = case parent
         when Assignments then parent.array
@@ -139,7 +140,7 @@ module Tap
         nil
       end
 
-      # Yields each key, value pair in the order in which
+      # Yields each [key, value] pair in the order in which
       # the keys were declared. Keys with no values are 
       # skipped.
       def each
@@ -148,7 +149,7 @@ module Tap
         end
       end
       
-      # Yields each key, values pair in the order in which
+      # Yields each [key, values] pair in the order in which
       # the keys were declared.
       def each_pair
         array.each do |key, values|
@@ -156,7 +157,7 @@ module Tap
         end
       end
       
-      # Returns the [key, values] as an array
+      # Returns self as an array
       def to_a
         array.collect {|key, values| [key, values.dup] }
       end
@@ -164,7 +165,7 @@ module Tap
       protected
       
       # An array of [key, values] arrays tracking the 
-      # key and order in which values were assigned. 
+      # order in which values are assigned. 
       attr_reader :array
       
     end

data/lib/tap/support/audit.rb

@@ -1,47 +1,43 @@
-autoload(:PP, 'pp')
-      
 module Tap
   module Support 
     
     # Marks the merge of multiple Audit trails
     class AuditMerge < Array
+      
+      # True if another is an AuditMerge and passes Array#==
       def ==(another)
         another.kind_of?(AuditMerge) && super
       end
     end
     
-    # Marks a split in an Audit trail
-    class AuditSplit
-      attr_reader :block
-      def initialize(block) @block = block end
-        
-      def ==(another)
-        another.kind_of?(AuditSplit) && another.block == block
-      end
-    end
-    
     # Marks the expansion of an Audit trail
-    class AuditExpand
+    class AuditIterate
       attr_reader :index
       def initialize(index) @index = index end
-        
+      
+      # True if another is an AuditIterate with the same index.
       def ==(another)
-        another.kind_of?(AuditExpand) && another.index == index
+        another.kind_of?(AuditIterate) && another.index == index
+      end
+      
+      # Returns a string like '_iterate(<index>)'.
+      def to_s
+        "_iterate(#{index})"
       end
     end
 
-    # Audit provides a way to track the values (inputs and results) passed
-    # 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. 
+    # Audit provides a way to track the values (inputs and results) passed among 
+    # tasks or, more generally, any Executable.  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) adds to the trail by 
-    # recording it's result using itself as the 'source' of the result.
+    # During execution, the inputs to a task are used to initialize an Audit.
+    # These inputs are the original value of the audit and mark the begining 
+    # of an audit trail; every task adds to the trail by recording it's result
+    # and 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:
+    # Audits can take any object as a source, so for illustration lets use some
+    # symbols:
     #   
     #   # initialize a new audit
     #   a = Audit.new(1, nil)
@@ -50,8 +46,8 @@ module Tap
     #   a._record(:A, 2)
     #   a._record(:B, 3)
     #
-    # Now you can pull up the source and value trails, as well as 
-    # information like the current and original values:
+    # Now you can pull up the source and value trails, as well as the current
+    # and original values:
     #
     #   a._source_trail      # => [nil, :A, :B]
     #   a._value_trail       # => [1, 2, 3]
@@ -62,9 +58,9 @@ module Tap
     #   a._current           # => 3
     #   a._current_source    # => :B
     #
-    # 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.  
+    # Merges are supported by using an array of the merged trails (actually
+    # an AuditMerge) as the source, and an array of the merged values as the 
+    # original value.  
     #
     #   b = Audit.new(10, nil)
     #   b._record(:C, 11)
@@ -83,9 +79,9 @@ module Tap
     #   c._value_trail       # => [ [[1,2,3], [10, 11, 12]], "a string value", {'a' => 'hash value'}, ['an', 'array', 'value']]
     #
     # 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+:
+    # can be developed independently.  Audits are also forked during a merge; 
+    # notice the additional record in 'a' doesn't change the source trail for
+    # 'c':
     #
     #   a1 = a._fork
     #
@@ -101,23 +97,23 @@ module Tap
     # to help gain access, as well as a printing method to visualize the
     # audit trail:
     #
-    #   [c._to_s]
-    #   o-[] 1
-    #   o-[A] 2
-    #   o-[B] 3
-    #   | 
-    #   | o-[] 10
-    #   | o-[C] 11
-    #   | o-[D] 12
-    #   | | 
-    #   `-`-o-[E] "a string value"
-    #       o-[F] {"a"=>"hash value"}
-    #       o-[G] ["an", "array", "value"]
+    #   c._to_s
+    #   # =>
+    #   # o-[] 1
+    #   # o-[A] 2
+    #   # o-[B] 3
+    #   # | 
+    #   # | o-[] 10
+    #   # | o-[C] 11
+    #   # | o-[D] 12
+    #   # | | 
+    #   # `-`-o-[E] "a string value"
+    #   #     o-[F] {"a"=>"hash value"}
+    #   #     o-[G] ["an", "array", "value"]
     #
     # In practice, tasks are recored as sources. Thus source trails can be used  
     # to access task configurations and other information that may be useful 
-    # when creating reports or making workflow decisions (ex: raise an 
-    # error after looping to a given task too many times). 
+    # when creating reports or making workflow decisions. 
     #
     #--
     # TODO:
@@ -143,9 +139,9 @@ module Tap
       class << self
 
         # Creates a new Audit by merging the input audits. The value of the new 
-        # Audit will be an array of the _current values of the audits.  The source 
-        # will be an AuditMerge whose values are forks of the audits. Non-Audit 
-        # sources can be provided; they are initialized to Audits before merging.
+        # Audit will be an array of the _current values of the inputs.  The source 
+        # will be an AuditMerge whose values are forks of the inputs. Non-Audit 
+        # sources may be provided; they are initialized to Audits before merging.
         #
         #   a = Audit.new
         #   a._record(:a, 'a')
@@ -181,9 +177,9 @@ module Tap
       # 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 
-      # valid initial value for an audit trail)
+      # An arbitrary object used to identify when no inputs have been
+      # provided to Audit.new.  (nil cannot be used since nil is a valid 
+      # initial value)
       AUDIT_NIL = Object.new
       
       # A new audit takes a value and/or source.  A nil source is typically given
@@ -270,7 +266,7 @@ module Tap
       end
       
       # Produces a new Audit with duplicate sources and values, suitable for
-      # separate development along a separate path.
+      # independent development.
       def _fork
         a = Audit.new
         a._sources = _sources.dup
@@ -278,18 +274,16 @@ module Tap
         a
       end
 
-      # _forks self and records the next value as [<return from block>, AuditSplit.new(block)] 
-      def _split(&block) # :yields: _current
-        _fork._record(AuditSplit.new(block), yield(_current))
-      end
-      
-      # _forks self for each member in _current.  Records the next value as
-      # [item, AuditExpand.new(<index of item>)].  Raises an error if _current 
-      # does not respond to each.
-      def _expand
+      # Produces a fork of self for each item in the current value (_current).
+      # Iterate is useful for developing each item of (say) an array along 
+      # different paths.
+      # 
+      # Records the next value of each fork as [item, AuditIterate.new(<index of item>)].  
+      # Raises an error if _current does not respond to each.
+      def _iterate
         expanded = []
         _current.each do |value|
-          expanded << _fork._record(AuditExpand.new(expanded.length), value)
+          expanded << _fork._record(AuditIterate.new(expanded.length), value)
         end
         expanded
       end

data/lib/tap/support/class_configuration.rb

@@ -5,20 +5,29 @@ require 'tap/support/configuration'
 module Tap
   module Support
     
-    # ClassConfiguration tracks and handles the class configurations defined in a 
-    # Configurable class.
+    # ClassConfiguration tracks configurations defined by a Configurable class.
     class ClassConfiguration
       include Enumerable
       
-      # The class receiving new configurations
+      config_templates_dir = File.expand_path File.dirname(__FILE__) + "/../generator/generators/config/templates"
+
+      # The path to the :doc template (see inspect)
+      DOC_TEMPLATE_PATH = File.join(config_templates_dir, 'doc.erb')
+
+      # The path to the :nodoc template (see inspect)
+      NODOC_TEMPLATE_PATH = File.join(config_templates_dir, 'nodoc.erb')
+      
+      # The Configurable class receiving new configurations
       attr_reader :receiver
 
-      # Tracks the assignment of the config keys to receivers
+      # An Assignments tracking the assignment of config keys to receivers
       attr_reader :assignments
       
-      # A map of (key, config) pairs.
+      # A map of [key, Configuration] pairs
       attr_reader :map
-
+      
+      # Generates a new ClassConfiguration for the receiver.  If a parent is 
+      # provided, configurations will be inherited from it.
       def initialize(receiver, parent=nil)
         @receiver = receiver
         
@@ -34,9 +43,9 @@ module Tap
         end
       end
 
-      # Initializes a Configuration using the inputs and sets it in self
-      # using name as a key, overriding the current config by that name,
-      # if it exists.  Returns the new config.
+      # Initializes a Configuration using the inputs and sets using name 
+      # as a key.  Any existing config by the same name is overridden. 
+      # Returns the new config.
       def add(name, default=nil, attributes={})
         self[name] = Configuration.new(name.to_sym, default, attributes)
       end
@@ -46,12 +55,12 @@ module Tap
         self[key] = nil
       end
       
-      # Gets the configuration specified by key.  The key is symbolized.
+      # Gets the config specified by key.  The key is symbolized.
       def [](key)
         map[key.to_sym]  
       end
       
-      # Assigns the configuration to key.  A nil config unassigns the
+      # Assigns the config to key.  A nil config unassigns the
       # configuration key.  The key is symbolized.
       def []=(key, config)
         key = key.to_sym
@@ -91,7 +100,7 @@ module Tap
       end
       
       # Calls block once for each [receiver, key, config] in self, 
-      # passing those elements as parameters, in the order in
+      # passing those elements as parameters in the order in
       # which they were assigned.  
       def each
         assignments.each do |receiver, key|
@@ -100,7 +109,7 @@ module Tap
       end
       
       # Calls block once for each [key, config] pair in self, 
-      # passing those elements as parameters, in the order in
+      # passing those elements as parameters in the order in
       # which they were assigned.
       def each_pair
         assignments.each do |receiver, key|
@@ -114,7 +123,7 @@ module Tap
         InstanceConfiguration.new(self, receiver, store)
       end
       
-      # Returns a hash of the (key, config.default) values in self.
+      # Returns a hash of the [key, config.default] pairs in self.
       def to_hash
         hash = {}
         each_pair {|key, config| hash[key] = config.default }
@@ -125,41 +134,21 @@ module Tap
       def code_comments
         code_comments = []
         values.each do |config| 
-          code_comments << config.desc if config.desc.kind_of?(Comment)
+          code_comments << config.desc if config.desc.kind_of?(Lazydoc::Comment)
         end
         code_comments
       end
       
-      # The path to the :doc template (see format_str)
-      DOC_TEMPLATE_PATH = File.expand_path File.dirname(__FILE__) + "/../generator/generators/config/templates/doc.erb"
-      
-      # The path to the :nodoc template (see format_str)
-      NODOC_TEMPLATE_PATH = File.expand_path File.dirname(__FILE__) + "/../generator/generators/config/templates/nodoc.erb"
-
-      # Formats the configurations using the specified template.  Two default
-      # templates are defined, <tt>:doc</tt> and <tt>:nodoc</tt>.  These map 
-      # to the contents of DOC_TEMPLATE_PATH and NODOC_TEMPLATE_PATH and 
-      # correspond to the documented and undocumented config generator templates.
-      #
-      # == Custom Templates
-      #
-      # format_str initializes a Templater which formats each [receiver, configurations] 
-      # pair in turn, and puts the output to the target using <tt><<</tt>.   The 
-      # templater is assigned the following attributes for use in formatting:
-      #
-      # receiver:: The receiver
-      # configurations:: An array of configurations and associated comments
-      # 
-      # In the template these can be accessed as any ERB locals, for example:
-      #
-      #   <%= receiver.to_s %>
-      #   <% configurations.each do |key, config, comment| %>
-      #   ...
-      #   <% end %>
+      # Inspects the configurations using the specified template.  Templates
+      # are used for format each [receiver, configurations] pair in self.
+      # See DEFAULT_TEMPLATE as a model.  The results of each template cycle
+      # are pushed to target.
       #
-      # The input template may be a String or an ERB; either may be used to 
-      # initialize the templater.
-      def format_str(template=:doc, target="")
+      # Two default templates are defined, <tt>:doc</tt> and <tt>:nodoc</tt>.
+      # These map to the contents of DOC_TEMPLATE_PATH and NODOC_TEMPLATE_PATH
+      # and correspond to the documented and undocumented 
+      # Tap::Generator::Generators::ConfigGenerator templates.
+      def inspect(template=:doc, target="")
         Lazydoc.resolve_comments(code_comments)
         
         template = case template

data/lib/tap/support/combinator.rb

@@ -0,0 +1,125 @@
+require 'enumerator'
+
+module Tap 
+  module Support
+    
+    # Combinator provides a method for iterating over all combinations
+    # of items in the input sets.
+    #
+    #   c = Combinator.new [1,2], [3,4]
+    #   c.to_a            # => [[1,3], [1,4], [2,3], [2,4]]
+    #
+    # Combinators can take any object that responds to each as an
+    # input set; normally arrays are used.
+    #
+    # === Implementation
+    #
+    # Combinator iteratively combines each element from the first set (a)
+    # with each element from the second set (b).  When more than two sets
+    # are given, the second and remaining sets are bundled into a
+    # Combinator, which then acts as the second set.
+    #
+    #   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]]
+    #
+    # Note that internally each item in a set is stored as a single-item
+    # array; the arrays are added during combination.  Thus when 
+    # iterating, the combinations are calculated like:
+    #
+    #   ([1] + [3]) + [5] # => [1,3,5]
+    #
+    # This is probably not the fastest implementation, but it works.
+    class Combinator
+      include Enumerable
+      
+      # The first set
+      attr_reader :a
+      
+      # The second set
+      attr_reader :b
+
+      # Creates a new Combinator.  Each input must respond
+      # to each, or be nil.
+      def initialize(*sets)
+        @a = make_set(sets.shift)
+        @b = make_set(*sets)
+      end
+
+      # Returns the sets used to initialize the Combinator.
+      def sets
+        sets_in(a) + sets_in(b)
+      end
+
+      # True if length is zero.
+      def empty?
+        a.empty? && b.empty?
+      end
+
+      # Returns the number of combinations returned by each.
+      def length
+        case
+        when !(@a.empty? || @b.empty?)
+          @a.length * @b.length
+        when @a.empty? 
+          @b.length
+        when @b.empty?
+          @a.length
+        end
+      end
+
+      # Passes each combination as an array to the input block.
+      def each # :yields: combination
+        case
+        when !(@a.empty? || @b.empty?)
+          @a.each do |a|
+            @b.each do |b|
+              yield(a + b)
+            end
+          end
+        when @a.empty? 
+          @b.each {|b| yield(b) }
+        when @b.empty? 
+          @a.each {|a| yield(a) }
+        end
+      end
+
+      private
+      
+      # makes a Combinator out of multiple sets or collects the
+      # objects of a single set as arrays:
+      #
+      #   make_set([1,2,3], [4,5,6])  # => Combinator.new([1,2,3], [4,5,6])
+      #   make_set([1,2,3])           # => [[1],[2],[3]]
+      #
+      def make_set(*sets) # :nodoc:
+        # recieves an array of arrays or combinators
+        return Combinator.new(*sets) if sets.length > 1 
+        return sets if sets.empty?
+        
+        set = sets[0]
+        return [] if set == nil
+        
+        unless set.respond_to?(:each)
+          raise ArgumentError, "does not respond to each: #{set}"
+        end
+        
+        # recursively arrayifies each element
+        arrayified_set = []
+        set.each {|s| arrayified_set << [s]}
+        arrayified_set
+      end
+
+      # basically the reverse of make_set
+      def sets_in(set) # :nodoc:
+        case set
+        when Combinator then set.sets
+        when Array then set.empty? ? [] : [set.collect {|s| s[0]}]
+        end
+      end
+      
+    end
+  end
+end

data/lib/tap/support/configurable.rb

@@ -21,7 +21,7 @@ module Tap
     #   c.config.class         # => InstanceConfiguration
     #   c.config               # => {:one => 'one', :two => 'two', :three => 'three'}
     #
-    # The <tt>config</tt> object acts as a kind of forwarding hash; declared configurations
+    # The <tt>config</tt> object acts as a forwarding hash; declared configurations
     # map to accessors while undeclared configurations are stored internally:
     #
     #   c.config[:one] = 'ONE'
@@ -33,8 +33,8 @@ module Tap
     #   c.config[:undeclared] = 'value'
     #   c.config.store         # => {:undeclared => 'value'}
     #
-    # The writer method for a configuration can be modified by providing a block to config.  
-    # The Validation module provides a number of common validation and string-transform 
+    # The writer for a configuration can be defined by providing a block to config.  
+    # The Validation module provides a number of common validation/transform 
     # blocks which can be accessed through the class method 'c':
     #
     #   class SubClass < ConfigClass
@@ -55,21 +55,21 @@ module Tap
     #   s.two = nil            # !> ValidationError
     #   s.two = 'str'          # !> ValidationError
     #
-    # As shown above, configurations are inherited from the parent and can be
+    # As shown above, configurations are inherited from the parent and may be
     # overridden in subclasses.  See ConfigurableClass for more details.
     #
     module Configurable
       
       # Extends including classes with ConfigurableClass
-      def self.included(mod)
+      def self.included(mod) # :nodoc:
         mod.extend Support::ConfigurableClass if mod.kind_of?(Class)
       end
       
-      # The instance configurations for self
+      # An InstanceConfiguration with configurations for self
       attr_reader :config
       
-      # Reconfigures self with the given configuration overrides.  Only
-      # the specified configs are modified.  Override keys are symbolized.
+      # Reconfigures self with the given overrides.  Only the specified configs
+      # are modified.  Keys are symbolized.
       #
       # Returns self.
       def reconfigure(overrides={})
@@ -81,9 +81,9 @@ module Tap
         self
       end
       
-      # Reinitializes config with a copy of orig.config (this assures
-      # that duplicates have their own copy of configurations, 
-      # separate from the original object).
+      # Reinitializes configurations in the copy such that
+      # the new object has it's own set of configurations,
+      # separate from the original object.
       def initialize_copy(orig)
         super
         initialize_config(orig.config)
@@ -91,9 +91,8 @@ module Tap
       
       protected
       
-      # Initializes config to an InstanceConfiguration specific for self.
-      # Default config values are assigned or overridden if specified in
-      # overrides. Override keys are symbolized.
+      # Initializes config to an InstanceConfiguration. Default config values 
+      # are overridden as specified by overrides. Keys are symbolized.
       def initialize_config(overrides={})
         class_config = self.class.configurations
         @config = class_config.instance_config