bahuvrihi-tap 0.10.0

data/lib/tap/support/batchable.rb

@@ -0,0 +1,47 @@
+require 'tap/support/batchable_class'
+
+module Tap
+  module Support
+
+    # Batchable encapsulates the methods used to support batching
+    # 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
+    
+      def self.included(mod)
+        mod.extend Support::BatchableClass if mod.kind_of?(Class)
+      end
+      
+      # 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).  
+      def batched?
+        batch.length > 1
+      end
+
+      # Returns the index of the self in batch.
+      def batch_index
+        batch.index(self)
+      end
+      
+      # Initializes a new batch object and adds the object to batch.
+      # The object will be a duplicate of self.
+      def initialize_batch_obj
+        obj = self.dup
+        batch << obj
+        obj
+      end
+    end
+  end
+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

data/lib/tap/support/class_configuration.rb

@@ -0,0 +1,194 @@
+require 'tap/support/assignments'
+require 'tap/support/instance_configuration'
+require 'tap/support/configuration'
+
+module Tap
+  module Support
+    
+    # ClassConfiguration tracks and handles the class configurations defined in a 
+    # Configurable class.
+    class ClassConfiguration
+      include Enumerable
+      
+      # The class receiving new configurations
+      attr_reader :receiver
+
+      # Tracks the assignment of the config keys to receivers
+      attr_reader :assignments
+      
+      # A map of config keys and instance methods used to set a 
+      # config (ie the reader and writer for a config)
+      attr_reader :map
+
+      def initialize(receiver, parent=nil)
+        @receiver = receiver
+        
+        if parent != nil
+          @map = parent.map.inject({}) do |hash, (key, config)|
+            hash[key] = config.dup
+            hash
+          end
+          @assignments = Assignments.new(parent.assignments)
+        else
+          @map = {}
+          @assignments = Assignments.new
+        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.
+      def add(name, default=nil, attributes={})
+        self[name] = Configuration.new(name.to_sym, default, attributes)
+      end
+      
+      # Removes the specified configuration.
+      def remove(key)
+        self[key] = nil
+      end
+      
+      # Gets the configuration specified by key.  The key is symbolized.
+      def [](key)
+        map[key.to_sym]  
+      end
+      
+      # Assigns the configuration to key.  A nil config unassigns the
+      # configuration key.  The key is symbolized.
+      def []=(key, config)
+        key = key.to_sym
+        
+        if config == nil
+          assignments.unassign(key)
+          map.delete(key)
+        else
+          assignments.assign(receiver, key) unless assignments.assigned?(key)
+          map[key] = config
+        end
+      end
+      
+      # Returns true if key is a config key.
+      def key?(key)
+        map.has_key?(key)
+      end
+      
+      # Returns all config keys.
+      def keys
+        map.keys
+      end
+      
+      # Returns config keys in order.
+      def ordered_keys
+        assignments.values
+      end
+      
+      # Returns all mapped configs.
+      def values 
+        map.values
+      end
+      
+      # True if map is empty.
+      def empty?
+        map.empty?
+      end
+      
+      # Calls block once for each [receiver, key, config] in self, 
+      # passing those elements as parameters, in the order in
+      # which they were assigned.  
+      def each
+        assignments.each do |receiver, key|
+          yield(receiver, key, map[key])
+        end
+      end
+      
+      # Calls block once for each [key, config] pair in self, 
+      # passing those elements as parameters, in the order in
+      # which they were assigned.
+      def each_pair
+        assignments.each do |receiver, key|
+          yield(key, map[key])
+        end
+      end
+      
+      # Initializes and returns a new InstanceConfiguration set to self 
+      # and bound to the receiver, if specified.
+      def instance_config(receiver=nil)
+        InstanceConfiguration.new(self, receiver)
+      end
+      
+      # Returns a hash of the (key, config.default) values in self.
+      def to_hash
+        hash = {}
+        each_pair {|key, config| hash[key] = config.default }
+        hash
+      end
+      
+      def code_comments
+        code_comments = []
+        values.each do |config| 
+          code_comments << config.desc if config.desc.kind_of?(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
+      # class_doc:: The TDoc for the receiver, from Tap::Support::TDoc[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 %>
+      #
+      # The input template may be a String or an ERB; either may be used to 
+      # initialize the templater.
+      def format_str(template=:doc, target="")
+        Lazydoc.resolve(code_comments)
+        
+        template = case template
+        when :doc then File.read(DOC_TEMPLATE_PATH)
+        when :nodoc then File.read(NODOC_TEMPLATE_PATH)
+        else template
+        end
+        
+        templater = Templater.new(template)
+        assignments.each_pair do |receiver, keys|
+          next if keys.empty?
+          
+          # set the template attributes
+          templater.receiver = receiver
+          templater.configurations = keys.collect do |key|
+            # duplicate config so that any changes to it
+            # during templation will not propogate back
+            # into self
+            [key, map[key].dup]
+          end.compact
+          
+          yield(templater) if block_given?
+          target << templater.build
+        end
+        
+        target
+      end
+    end
+  end
+end
+

data/lib/tap/support/command_line.rb

@@ -0,0 +1,98 @@
+require 'optparse'
+
+module Tap
+  module Support
+    
+    # Under Construction
+    module CommandLine
+      module_function
+
+      # Parses the input string as YAML, if the string matches the YAML document 
+      # specifier (ie it begins with "---\s*\n").  Otherwise returns the string.
+      #
+      #   str = {'key' => 'value'}.to_yaml       # => "--- \nkey: value\n"
+      #   Tap::Script.parse_yaml(str)            # => {'key' => 'value'}
+      #   Tap::Script.parse_yaml("str")          # => "str"
+      def parse_yaml(str)
+        str =~ /\A---\s*\n/ ? YAML.load(str) : str
+      end
+      
+      SPLIT_ARGV_REGEXP = /\A-{2}(\+*)\z/
+      
+      def split(argv)
+        current = []
+        current_split = []
+        splits = [current_split]
+
+        argv.each do |arg|
+          if arg =~ SPLIT_ARGV_REGEXP
+            current_split << current  unless current.empty?
+            current = []
+            current_split = (splits[$1.length] ||= [])
+          else
+            current << arg
+          end
+        end
+
+        current_split << current unless current.empty?
+        splits.delete_if {|split| split.nil? || split.empty? }
+        splits
+      end
+
+      def shift(argv)
+        index = nil
+        argv.each_with_index do |arg, i|
+          if arg !~ /\A-/
+            index = i 
+            break
+          end
+        end
+        index == nil ? nil : argv.delete_at(index)
+      end
+
+      def usage(path, cols=80)
+        parse_usage(File.read(path), cols)
+      end
+        
+      def parse_usage(str, cols=80)
+        scanner = StringScanner.new(str)
+        scanner.scan(/^#!.*?$/)
+        Comment.parse(scanner, false).wrap(cols, 2).strip
+      end
+      
+      def configv(config)
+        desc = config.desc
+        desc.extend(OptParseComment) if desc.kind_of?(Comment)
+          
+        [config.short, argtype(config), desc].compact
+      end
+      
+      def argtype(config)
+        case config.arg_type
+        when :optional 
+          "#{config.long} [#{config.arg_name}]"
+        when :switch 
+          config.long(true)
+        when :flag
+          config.long
+        when :list
+          "#{config.long} a,b,c"
+        when :mandatory, nil
+          "#{config.long} #{config.arg_name}"
+        else
+          raise "unknown arg_type: #{config.arg_type}"
+        end
+      end
+      
+      module OptParseComment
+        def empty?
+          to_str.empty?
+        end
+
+        def to_str
+          subject.to_s =~ /#(.*)$/ ? $1.strip : ""
+        end
+      end
+    end
+  end
+end