tap 0.8.0 → 0.9.0

data/lib/tap/support/batchable.rb

@@ -0,0 +1,59 @@
+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.
+    module Batchable
+      
+      # 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
+      #
+      #  Batchable.batch(t1, t2)
+      #  t3.batch                    # => [t1,t2,t3]
+      #
+      # Returns the new batch.
+      def self.batch(*tasks)
+        merged = []
+        batches = tasks.collect {|task| task.batch }.uniq
+        batches.each do |batch| 
+           merged.concat(batch)
+           batch.clear
+         end
+        merged.uniq!
+        batches.each {|batch| batch.concat(merged) }
+        merged
+      end
+      
+      # The object batch. (must be initializd by classes that
+      # include Batchable)
+      attr_reader :batch
+    
+      # 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 self if batch is empty (ie for the first
+      # call) or a duplicate of self if not.
+      def initialize_batch_obj
+        obj = (batch.empty? ? self : self.dup)
+        batch << obj
+        obj
+      end
+    end
+  end
+end

data/lib/tap/support/class_configuration.rb

@@ -0,0 +1,279 @@
+autoload(:GetOptLong, 'getoptlong')
+
+module Tap
+  module Support
+    # == UNDER CONSTRUCTION
+    #--
+    #
+    # ClassConfiguration holds the class configurations defined in a Tap::Task.
+    # The configurations are stored as an array of declarations_array like:
+    # [name, default, msg, declaration_class].  In addition, ClassConfiguration
+    # collapse the array of declarations_array 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 ClassConfigurations directly.
+    #
+    # === Example
+    # 
+    #   class BaseTask < Tap::Configurable
+    #     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
+    #
+    #--
+    # TODO -
+    # Revisit config formatting... right now it's a bit jacked.
+    #++
+    class ClassConfiguration
+      include Enumerable
+      
+      # The class receiving the configurations
+      attr_reader :receiver
+      
+      # An array of [receiver, configuration keys] arrays tracking
+      # the order in which configurations were declared across all
+      # receivers
+      attr_reader :declarations_array
+      
+      # An array of configuration keys declared by self
+      attr_reader :declarations
+      
+      # A hash of the unprocessed default values
+      attr_reader :unprocessed_default
+      
+      # A hash of the processed default values
+      attr_reader :default
+      
+      # A hash of the processing blocks
+      attr_reader :process_blocks
+
+      # A placeholder to indicate when no value 
+      # was specified during a call to add. 
+      NO_VALUE = Object.new
+    
+      def initialize(receiver, parent=nil)
+        @receiver = receiver
+        @default = parent != nil ? parent.default.dup : {}
+        @unprocessed_default = parent != nil ? parent.unprocessed_default.dup : {}
+        @process_blocks = parent != nil ? parent.process_blocks.dup : {}
+        
+        # use same declarations array?  freeze declarations to ensure order?
+        # definitely falls out of order if parents are modfied after initialization
+        @declarations_array = parent != nil ? parent.declarations_array.dup : []
+        @declarations = []
+        declarations_array << [receiver, @declarations] 
+      end
+      
+      # Returns true if the key has been declared by some receiver.
+      # Note this is distinct from whether or not a particular config
+      # is currently in the default hash.
+      def declared?(key)
+        key = key.to_sym
+        declarations_array.each do |r,array| 
+          return true if array.include?(key)
+        end
+        false
+      end
+      
+      # Returns the class (receiver) that first added the config 
+      # indicated by key.
+      def declaration_class(key)
+        key = key.to_sym
+        declarations_array.each do |r,array| 
+          return r if array.include?(key)
+        end
+        nil
+      end
+      
+      # Returns the configurations first declared by the specified receiver.
+      def declarations_for(receiver)
+        declarations_array.each do |r,array| 
+          return array if r == receiver
+        end
+        nil
+      end
+      
+      # Adds a configuration.  If specified, the value is processed
+      # by the process_block and recorded adefault 
+      #
+      # The existing value and process_block for the
+      # configuration will not be overwritten unless specified. However,
+      # if a configuration is added without specifying a value and no previous 
+      # default value exists, the default and unprocessed_default for the 
+      # configuration will be set to nil.
+      #
+      #--
+      # Note -- existing blocks are NOT overwritten unless a new block is provided.
+      # This allows overide of the default value in subclasses while preserving the 
+      # validation/processing code.
+      def add(key, value=NO_VALUE, &process_block)
+        key = key.to_sym
+        value = unprocessed_default[key] if value == NO_VALUE
+        
+        declarations << key unless declared?(key)
+        process_blocks[key] = process_block if block_given?
+        unprocessed_default[key] = value
+        default[key] = process(key, value)
+
+        self
+      end
+      
+      def remove(key)
+        key = key.to_sym
+        
+        process_blocks.delete(key)
+        unprocessed_default.delete(key)
+        default.delete(key)
+        
+        self
+      end
+      
+      def merge(another)
+        # check for conflicts
+        another.each do |receiver, key|
+          dc = declaration_class(key)
+          next if dc == nil || dc == receiver
+          
+          raise "configuration conflict: #{key} (#{receiver}) already declared by #{dc}"
+        end
+        
+        # add the new configurations
+        another.each do |receiver, key|
+          # preserve the declarations for receiver
+          unless declarations = declarations_for(receiver) 
+            declarations = []
+            declarations_array << [receiver, declarations] 
+          end
+          unless declarations.include?(key)
+            declarations << key 
+            yield(key) if block_given?
+          end
+          
+          add(key, another.unprocessed_default[key], &another.process_blocks[key])
+        end
+      end
+    
+      def each # :yields: receiver, key
+        declarations_array.each do |receiver, keys|
+          keys.each {|key| yield(receiver, key) }
+        end
+      end
+      
+      # Sends value to the process block identified by key and returns the result.
+      # Returns value if no process block has been set for key.
+      def process(key, value)
+        block = process_blocks[key.to_sym]
+        block ? block.call(value) : value
+      end
+    
+      # Nicely formats the configurations into yaml with messages and
+      # declaration class divisions.
+      def format_yaml
+        lines = []
+        declarations_array.each do |receiver, keys|
+          
+          # do not consider keys that have been removed
+          keys = keys.delete_if {|key| !self.default.has_key?(key) }
+          next if keys.empty?
+          
+          lines << "# #{receiver} configuration#{keys.length > 1 ? 's' : ''}"
+          
+          class_doc = Tap::Support::TDoc[receiver]
+          configurations = (class_doc == nil ? [] : class_doc.configurations)
+          keys.each do |key|
+            tdoc_config = configurations.find {|config| config.name == key.to_s }
+ 
+            # 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 => unprocessed_default[key]}.to_yaml[5...-1]
+            message = tdoc_config ? tdoc_config.comment : ""
+            
+            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 < 25 && message.length < 30
+              # shorthand ONLY if the config and message can be expressed in a single line
+              message = message.gsub(/^#\s*/, "")
+              "%-25s # %s" % [yaml, message]
+            else
+              lines << ""
+              # comment out new lines and add the message
+              message.split(/\n/).each do |msg|
+                lines << "# #{msg.strip.gsub(/^#\s*/, '')}"
+              end
+              yaml
+            end
+          end
+        
+          # add a spacer line
+          lines << ""
+        end
+      
+        lines.compact.join("\n")
+      end
+    
+      def opt_map(long_option)
+        raise ArgumentError.new("not a long option: #{long_option}") unless long_option =~ /^--(.*)$/
+        long = $1
+      
+        each do |receiver, key|
+          return key if long == key.to_s
+        end  
+        nil
+      end
+    
+      def to_opts
+        collect do |receiver, key|
+          # Note the receiver is used as a placeholder for desc,
+          # to be resolved using TDoc.
+          attributes = {
+            :long => key,
+            :short => nil,
+            :opt_type => GetoptLong::REQUIRED_ARGUMENT,
+            :desc => receiver  
+          }
+
+          long = attributes[:long]
+          attributes[:long] = "--#{long}" unless long =~ /^-{2}/
+
+          short = attributes[:short].to_s
+          attributes[:short] = "-#{short}" unless short.empty? || short =~ /^-/
+
+          [attributes[:long], attributes[:short], attributes[:opt_type], attributes[:desc]]
+        end  
+      end
+    
+    end
+  end
+end

data/lib/tap/support/configurable.rb

@@ -0,0 +1,92 @@
+module Tap
+  module Support
+    
+    # Configurable encapsulates all configuration-related methods used
+    # by Tasks.  When Configurable is included in a class, the class itself
+    # is extended with Tap::Support::ConfigurableMethods, such that configs
+    # can be declared within the class definition.
+    #
+    #   class ConfigurableClass
+    #     include Configurable
+    # 
+    #     config :one, 'one'
+    #     config :two, 'two'
+    #     config :three, 'three'
+    #   end
+    #
+    #   ConfigurableClass.new.config  # => {:one => 'one', :two => 'two', :three => 'three'}
+    #
+    # See the 'Configuration' section in the Tap::Task documentation for
+    # more details on how Configurable works in practice.
+    module Configurable
+      include Batchable
+    
+      def self.included(mod)
+        mod.extend Support::ConfigurableMethods
+        mod.instance_variable_set(:@configurations, Support::ClassConfiguration.new(mod))
+        mod.instance_variable_set(:@source_files, [])
+      end
+    
+      # The application used to load config_file templates 
+      # (and hence, to initialize batched objects).
+      attr_reader :app
+      
+      # The name used to determine config_file, via
+      # app.config_filepath(name).
+      attr_reader :name
+      
+      # The config file used to load config templates.
+      attr_reader :config_file
+      
+      # A configuration hash.
+      attr_reader :config
+      
+      # Initializes a new Configurable and associated batch objects.  Batch
+      # objects will be initialized for each configuration template specified
+      # in config_file, where config_file = app.config_filepath(name).  
+      def initialize(name=nil, config={}, app=App.instance)
+        @app = app
+        @batch = []
+        @config_file = app.config_filepath(name)
+        
+        config.symbolize_keys! unless config.empty?
+        app.each_config_template(config_file) do |template|
+          template_config = template.empty? ? config : template.symbolize_keys.merge(config)
+          initialize_batch_obj(name, template_config)
+        end
+      end
+    
+      # Sets config with the given configuration overrides, merged with the class
+      # default configuration.  Configurations are symbolized before they are merged,
+      # and validated as specified in the config declarations.
+      def config=(overrides)
+        @config = self.class.configurations.default.dup
+        overrides.each_pair {|key, value| set_config(key.to_sym, value) } 
+        self.config
+      end
+      
+      # Creates a new batched object and adds the object to batch. The batched object 
+      # will be a duplicate of the current object but with a new name and/or 
+      # configurations.
+      def initialize_batch_obj(name=nil, config={})
+        obj = super()
+      
+        obj.name = name.nil? ? self.class.default_name : name
+        obj.config = config
+
+        obj
+      end
+    
+      protected
+    
+      attr_writer :name
+    
+      # Sets the specified configuration, processing the input value using
+      # the block specified in the config declaration.  The input key should
+      # be symbolized.
+      def set_config(key, value)
+        config[key] = self.class.configurations.process(key, value)
+      end
+    end
+  end
+end

data/lib/tap/support/configurable_methods.rb

@@ -0,0 +1,296 @@
+module Tap
+  module Support
+    autoload(:TDoc, 'tap/support/tdoc')
+
+    # ConfigurableMethods encapsulates all class methods used to declare
+    # configurations in Tasks.  ConfigurableMethods extends classes that
+    # include Tap::Support::Configurable.
+    #
+    #   class ConfigurableClass
+    #     include Configurable
+    # 
+    #     config :one, 'one'
+    #     config :two, 'two'
+    #     config :three, 'three'
+    #   end
+    #
+    #   ConfigurableClass.new.config  # => {:one => 'one', :two => 'two', :three => 'three'}
+    #
+    # See the 'Configuration' section in the Tap::Task documentation for
+    # more details on how Configurable works in practice.
+    module ConfigurableMethods
+      
+      # A Tap::Support::ClassConfiguration holding the class configurations.
+      attr_reader :configurations
+      
+      # When subclassed, the configurations are duplicated and passed to 
+      # the child class where they can be extended/modified without affecting
+      # the configurations of the parent class.
+      def inherited(child)
+        super
+        child.instance_variable_set(:@configurations, ClassConfiguration.new(child, @configurations))
+        child.instance_variable_set(:@source_files, source_files.dup)
+      end
+      
+      # EXPERIMENTAL
+      attr_reader :source_files # :nodoc:
+      
+      # EXPERIMENTAL
+      # Identifies source files for TDoc documentation.
+      def source_file(arg) # :nodoc:
+        source_files << arg
+      end
+
+      # Declares a configuration without any accessors.
+      #
+      # With no keys specified, sets config to make no  
+      # accessors for each new configuration.
+      def declare_config(*keys)
+        if keys.empty?
+          self.config_mode = :none 
+        else 
+          keys.each {|key| configurations.add(key)}
+        end
+      end
+
+      # Creates a configuration writer for the input keys.  Works like
+      # attr_writer, except the value is written to config, rather than
+      # a local variable.  In addition, the config will be validated
+      # using validate_config upon setting the value.
+      #
+      # With no keys specified, sets config to create config_writer 
+      # for each new configuration.
+      def config_writer(*keys)
+        if keys.empty?
+          self.config_mode = :config_writer 
+        else 
+          keys.each do |key|
+            configurations.add(key)
+            define_config_writer(key)
+          end
+        end
+      end
+
+      # Creates a configuration reader for the input keys.  Works like
+      # attr_reader, except the value is read from config, rather than
+      # a local variable.
+      #
+      # With no keys specified, sets config to create a config_reader 
+      # for each new configuration.
+      def config_reader(*keys)
+        if keys.empty?
+          self.config_mode = :config_reader 
+        else 
+          keys.each do |key|
+            configurations.add(key)
+            define_config_reader(key)
+          end
+        end
+      end
+
+      # Creates configuration accessors for the input keys.  Works like
+      # attr_accessor, except the value is read from and written to config, 
+      # rather than a local variable.
+      #
+      # With no keys specified, sets config to create a config_accessor 
+      # for each new configuration.
+      def config_accessor(*keys)
+        if keys.empty?
+          self.config_mode = :config_accessor 
+        else 
+          keys.each do |key|
+            configurations.add(key)
+            define_config_reader(key)
+            define_config_writer(key)
+          end
+        end
+      end
+
+      # Sets a class configuration.  Configurations are inherited, but can 
+      # be overridden or added in subclasses. Accessors are created by 
+      # default, but this behavior can be modified by use of the other
+      # config methods.  
+      #
+      #   class SampleClass
+      #     include Configurable
+      #
+      #     config :key, 'value'
+      #     config_reader
+      #     config :reader_only
+      #   end
+      #
+      #   t = SampleClass.new
+      #   t.respond_to?(:reader_only)         # => true
+      #   t.respond_to?(:reader_only=)        # => false
+      #
+      #   t.config               # => {:key => 'value', :reader_only => nil} 
+      #   t.key                  # => 'value'
+      #   t.key = 'another'
+      #   t.config               # => {:key => 'another', :reader_only => nil}
+      #
+      # A block can be specified for validation/pre-processing.  All inputs
+      # set through the config accessors, as well as the instance config= 
+      # method are processed by the block before they set the value in the
+      # config hash.  The config value will be set to the return of the block.
+      #
+      # The Tap::Support::Validation module provides methods to perform 
+      # common checks and transformations.  These can be accessed through 
+      # the class method 'c':
+      #
+      #   class ValidatingClass
+      #     include Configurable
+      # 
+      #     config :one, 'one', &c.check(String)
+      #     config :two, 'two' do |v| 
+      #       v.upcase
+      #     end
+      #   end
+      #
+      #   t = ValidatingClass.new
+      #   
+      #   # note the default values ARE processed
+      #   t.config                  # => {:one => 'one', :two => 'TWO'}
+      #   t.one = 1                 # => ValidationError
+      #   t.config = {:one => 1}    # => ValidationError
+      #
+      #   t.config = {:one => 'str', :two => 'str'}
+      #   t.config                  # => {:one => 'str', :two => 'STR'}
+      #   
+      def config(key, value=nil, &validation)
+        configurations.add(key, value, &validation)
+
+        case config_mode
+        when :config_accessor
+          define_config_writer(key)
+          define_config_reader(key)
+        when :config_writer
+          define_config_writer(key)
+        when :config_reader
+          define_config_reader(key)
+        end
+      end
+      
+      def config_merge(klass)
+        configurations.merge(klass.configurations) do |key|
+          case config_mode
+          when :config_accessor
+            define_config_writer(key)
+            define_config_reader(key)
+          when :config_writer
+            define_config_writer(key)
+          when :config_reader
+            define_config_reader(key)
+          end
+        end
+      end
+      
+      # Returns the default name for the class: class.to_s.underscore
+      def default_name
+        @default_name ||= to_s.underscore
+      end
+
+      # Alias for Batchable.batch
+      def batch(*batchables)
+        Batchable.batch(*batchables)
+      end
+
+      # Returns the TDoc documentation for self. 
+      def tdoc
+        @tdoc ||= Tap::Support::TDoc[self]
+      end
+      
+      # EXPERIMENTAL
+      def help(opts=configurations.to_opts) # :nodoc:
+        return "could not find help for '#{self}'" if tdoc == nil
+
+        sections = tdoc.comment_sections(/Description|Usage/i, true)
+        %Q{#{self}
+        
+#{sections["Description"]}
+Usage:
+#{sections["Usage"]}
+Options:
+#{Tap::Script.usage_options(opts)}
+
+}
+      end
+      
+      # EXPERIMENTAL
+      def argv_enq(app=App.instance, &block) # :nodoc:
+        if block_given?
+          @argv_enq_block = block
+          return
+        end
+        return @argv_enq_block.call(app) if @argv_enq_block ||= nil
+
+        config = {}
+        opts = configurations.to_opts
+        opts << ['--help', nil, GetoptLong::NO_ARGUMENT, "Print this help."]
+        opts << ['--debug', nil, GetoptLong::NO_ARGUMENT, "Trace execution and debug"]
+        opts << ['--use', nil, GetoptLong::REQUIRED_ARGUMENT, "Loads inputs from file."]
+        opts << ['--iterate', nil, GetoptLong::NO_ARGUMENT, "Iterates over inputs."]
+        
+        iterate = false
+        Tap::Script.handle_options(*opts) do |opt, value|
+          case opt
+          when '--help'
+            puts help(opts)
+            exit
+            
+          when '--debug'
+            app.options.debug = true
+            
+          when '--use'
+            hash = YAML.load_file(value)
+            hash.values.each do |args| 
+              ARGV.concat(args)
+            end
+          
+          when '--iterate'
+            iterate = true
+            
+          else
+            key = configurations.opt_map(opt)
+            config[key] = YAML.load(value)
+          end
+        end
+
+        # configure task
+        task = app.task(ARGV.shift, config)
+        iterate ? ARGV.each {|input| task.enq(input) } : task.enq(*ARGV)
+      end
+
+      protected
+
+      attr_writer :config_mode
+
+      # Tracks the current configuration mode, to determine what
+      # in any accessors should be generated for the configuration.
+      # (default :config_accessor)
+      def config_mode
+        @config_mode ||= :config_accessor
+      end
+      
+      # Alias for Tap::Support::Validation
+      def c
+        Validation
+      end
+
+      private
+
+      def define_config_reader(name, key=name) # :nodoc:
+        key = key.to_sym
+        define_method(name) do
+          config[key]
+        end
+      end
+
+      def define_config_writer(name, key=name) # :nodoc:
+        key = key.to_sym
+        define_method("#{name}=") do |value|
+          set_config(key, value)
+        end
+      end
+    end
+  end
+end