tap 0.8.0 → 0.9.0

data/lib/tap/support/combinator.rb

@@ -1,114 +0,0 @@
-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/task_configuration.rb

@@ -1,169 +0,0 @@
-module Tap
-  module Support
-    # == UNDER CONSTRUCTION
-    #
-    # TaskConfiguration holds the class configurations defined in a Tap::Task.
-    # The configurations are stored as an array of declarations like:
-    # [name, default, msg, declaration_class].  In addition, TaskConfiguration
-    # collapse the array of declarations into a hash, which acts as the default
-    # task configuration.
-    #
-    # Storing metadata about the configurations, such as the declaration_class, 
-    # allows the creation of more user-friendly configuration files and facilitates 
-    # incorporation into command-line applications.
-    #
-    # In general, users will not have to interact with TaskConfigurations directly.
-    #
-    # == Example
-    # 
-    #   class BaseTask < Tap::Task
-    #     class_configurations [:one, 1]
-    #   end
-    #
-    #   BaseTask.configurations.hash    # => {:one => 1}
-    #
-    #   class SubTask < BaseTask
-    #     class_configurations(
-    #       [:one, 'one', "the first configuration"],
-    #       [:two, 'two', "the second configuration"])
-    #   end
-    #
-    #   SubTask.configurations.hash    # => {:one => 'one', :two => 'two'}
-    #   
-    # Now you can see how the comments and declaring classes get used in the
-    # configuration files.  Note that configuration keys are stringified
-    # for clarity (this is ok -- they will be symbolized when loaded by a
-    # task).
-    #
-    #   [BaseTask.configurations.format_yaml]
-    #   # BaseTask configuration
-    #   one: 1        
-    #
-    #   [SubTask.configurations.format_yaml]
-    #   # BaseTask configuration
-    #   one: one             # the first configuration
-    #
-    #   # SubTask configuration
-    #   two: two             # the second configuration
-    #
-    class TaskConfiguration
-      attr_reader :declarations, :default, :attributes
-      
-      include Enumerable
-      
-      def initialize
-        @declarations = {}
-        @default = {}
-        @attributes = {}
-      end
-      
-      def dup
-        # ensure the duplication does not pass along 
-        # new references to the same objects
-        another = TaskConfiguration.new
-        another.declarations = self.declarations.dup
-        another.default = self.default.dup
-        another.attributes = self.attributes.dup
-        another
-      end
-      
-      def empty?
-        @declaration.empty?  
-      end
-      
-      def declared?(key)
-        default.has_key?(key.to_sym)
-      end
-      
-      def declare(key, declaration_class)
-        key = key.to_sym
-
-        # Check if the key is already declared...
-        return if declared?(key)
-
-        # Add a declaration array if no declaration have been
-        # created for the class and append the key
-        (declarations[declaration_class] ||= [declarations.length]) << key
-        default[key] = nil
-        attributes[key] = {}
-      end
-      
-      def set(key, value, attributes={})
-        key = key.to_sym
-        raise "configurations cannot be set until they are declared" unless declared?(key)
-        
-        default[key] = value
-        self.attributes[key].merge!(attributes)
-      end
-      
-      def each # :yields: declaration_class, key, default, attributes
-        declarations.each_pair do |declaration_class, keys|
-          keys[1..-1].each do |key|
-            yield(declaration_class, key, default[key], attributes[key])
-          end
-        end
-      end
-      
-      # Nicely formats the configurations into yaml with messages and
-      # declaration class divisions.
-      def format_yaml
-        lines = []
-        declarations.each_pair do |declaration_class, keys|
-          lines << "# #{declaration_class} configuration#{keys.length > 2 ? 's' : ''}"
-          
-          class_name = declaration_class.to_s
-          class_path = class_name.underscore
-          source_file = Dependencies.search_for_file(class_path)
-
-          Tap::Support::TDoc.document(source_file)
-          class_doc = Tap::Support::TDoc[declaration_class]
-          configurations = (class_doc == nil ? [] : class_doc.configurations)
-          
-          keys[1..-1].each do |key|
-            value = default[key]
-            attribs = attributes[key]
-            message = ""
-            configurations.each do |config|
-              if config.name == key.to_s
-                message = config.comment
-                break
-              end
-            end
-
-            # yaml adds a header and a final newline which should be removed:
-            #   {'key' => 'value'}.to_yaml           # => "--- \nkey: value\n"
-            #   {'key' => 'value'}.to_yaml[5...-1]   # => "key: value"
-            yaml = {key.to_s => value}.to_yaml[5...-1]
-            #yaml = "##{yaml}" if value.nil?
-
-            lines << case 
-            when message == nil || message.empty?  
-              # if there is no message, simply add the yaml
-              yaml
-            when yaml !~ /\r?\n/ && message !~ /\r?\n/ && yaml.length < 20 && message.length < 30
-              # shorthand ONLY if the config and message can be expressed in a single line
-              message = message.gsub(/^#\s*/, "")
-              "%-20s # %s" % [yaml, message]
-            else
-              # comment out new lines and add the message
-              message = message.gsub(/\n#\s*/, "\n# ")
-              lines << "# #{message}"
-              yaml
-            end
-          end
-          
-          # add a spacer line
-          lines << ""
-        end
-        
-        lines.join("\n")
-      end
-      
-
-      protected
-      
-      attr_writer :declarations, :default, :attributes 
-
-    end
-  end
-end

data/lib/tap/support/template.rb

@@ -1,81 +0,0 @@
-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

data/lib/tap/support/templater.rb

@@ -1,155 +0,0 @@
-require 'tap/support/template'
-
-module Tap
-  module Support
-    
-    # Templater generates permutations of a hash, treating it as a template for other 
-    # hashes.  Templater looks for various flags on the end of keys to signify operations 
-    # like method execution ('!') and replacement ('=').
-    #
-    #   module TemplateMethods
-    #     def method_call(input)
-    #       self["result"] = "#{input} was processed"
-    #     end
-    #   end
-    #
-    #   t = Templater.new(
-    #        "key"=> "value", 
-    #        "method_call!" => "method input",
-    #        "replacement=" => "replacement input")
-    #   t.run_methods(TemplateMethods)
-    #   t.run_replace do |input|
-    #     "#{input} was replaced"
-    #   end
-    #
-    #   t.templates           
-    #   # => [{"key" => "value", 
-    #         "result" => "method input was processed",
-    #         "replacement" => "replacement input was replaced"}]
-    #
-    # == Creating Template Methods
-    #
-    # The default Template methods may not be sufficient for your needs, but making new
-    # methods (as above) is easy.  Some simple rules apply:
-    #
-    # - Any method can be called from run_methods provided it has a single input.  
-    # - Modules with the methods will extend the hash templates so 'self' indicates the
-    #   template itself.  
-    # - New templates should be added by pushing the template to the templater, which  
-    #   will already be set by the time the method executes 
-    #   (ex: self.templater << new_template).  
-    # 
-    # Also, it's important to note that ANY empty templates at the end of run_methods
-    # are cleared from the templates array.  Thus, if you want to remove a template from
-    # within a method, simply clear self.
-    #
-    # See the Template code for examples.
-    class Templater
-
-      # Convenience method for making a new Templater, running methods
-      # with the input modules, and making replacements using the input
-      # block.  Returns the resulting templates.
-      def self.make_templates(hash, *modules, &block)
-        t = Templater.new(hash)
-        t.run_methods(*modules)
-        t.run_replace(&block)
-        t.templates
-      end
-      
-      attr_reader :templates
-      
-      # Creates a new Templater with the input hash as the initial template.
-      def initialize(hash)
-        @templates = []
-        self << hash
-      end
-      
-      # Shortcut to add a template to the templater, unless the template is empty.
-      def <<(template)
-        self.templates << template unless template.empty? 
-      end
-      
-      # Iterates through the pairs in each template looking for keys matching the
-      # regexp (using =~).  When a matching key is found, it is removed from the 
-      # template and then the template, the key, and the corresponding value are 
-      # passed to the block for further processing. Iteration restarts after each 
-      # match and empty templates are removed upon completion.  All templates are 
-      # extended with Template before iteration.
-      #
-      # Notes:
-      # - run_templater is the foundation of the other run_* methods and may be used
-      #   for custom template processing.
-      # - since =~ is used for comparison, only String keys will be selected
-      #   under normal circumstances.
-      def run_templater(regexp) # :yields: template, key, value
-        templates.each do |template|
-          unless template.respond_to?(:templater)
-            template.extend Template
-            template.templater = self
-          end
-          
-          template.each_pair do |key, value|
-            next unless key =~ regexp
-          
-            # remove the key
-            template.delete(key)
-            yield(template, key, value)
-          
-            # restart the loop as key/value pairs may have changed
-            retry
-          end
-        end
-        
-        templates.delete_if {|t| t.empty?}
-        
-        self
-      end
-      
-      # Iterates through the pairs in each template looking for and executing method calls
-      # as per run_templater. Method calls are indicated by an exclamation attached to the 
-      # key, like 'do_something!'. 
-      #
-      # Templates are extended with the input modules before the method call.  The modules
-      # should provide the methods (an error will be raised if the specified method is not
-      # defined).  Note, templates will by default be extended with the Template module.
-      #
-      #   module MethodModule
-      #     def method_call(input)
-      #       self["result"] = "#{input} was processed"
-      #     end
-      #   end
-      #
-      #   t = Templater.new('method_call!' => 'input')
-      #   t.run_methods(MethodModule)   # calls 'do_something' with the input 'some value',
-      #                                 # after removing the key-value pair
-      #   t.templates                   # => [{"result" => "input was processed"}]
-      #
-      # Notes:
-      # - The method called is the method minus the exclamation, so 'do_something!' calls 
-      #   'do_something' within the template and 'do_something!!' calls 'do_something!'
-      # - Iteration restarts after each method call; inserted method calls will be executed
-      def run_methods(*modules)
-        run_templater(/!$/) do |template, key, value|
-          modules.each {|mod| template.extend mod}
-          template.send(key.chop, value) 
-        end
-      end
-  
-      # Iterates through the pairs in each template looking for replacement keys and
-      # executing the block to make the appropriate replacement value, as per 
-      # run_templater.  Replacement keys are indicated by an equals sign attached to 
-      # the key, like 'key='. The equals sign will be chopped off for these keys, and
-      # the value replaced with the return value of the block.
-      #
-      #   t = Templater.new('replacement=' => 'some value')
-      #   t.run_replace {|value| "#{value} was replaced"}                    
-      #   t.templates                 # => [{"replacement" => "some value was replaced"}]
-      #
-      def run_replace # :yields: value
-        run_templater(/=$/) do |template, key, value|
-          template[key.chop] = yield(value)
-        end  
-      end
-    end
-  end
-end