tap 0.11.1 → 0.12.0

data/lib/tap/support/templater.rb

@@ -1,5 +1,6 @@
 require 'ostruct'
-require 'erb'
+autoload(:ERB, 'erb')
+autoload(:YAML, 'yaml')
 
 module Tap
   module Support
@@ -161,6 +162,13 @@ module Tap
         @_erbout = input
       end
       
+      unless RUBY_VERSION < "1.9"
+        def force_encoding(encoding)
+          @_erbout.force_encoding(encoding)
+          @_erbout
+        end
+      end
+      
       # Redirects output of erb to the redirected_erbout string
       # for the duration of the block.  When redirect completes,
       # the redirected_erbout is concatenated to the main

data/lib/tap/support/versions.rb

@@ -80,6 +80,45 @@ module Tap
         a <=> b
       end
       
+      # Version unique.  Select the latest or earliest versions of each file
+      # in the array.  For paths that have no version, vniq considers any
+      # version to beat no version.  The order of paths is preserved by
+      # default, but the extra sort doing so may be turned off.
+      #
+      #   paths = [
+      #    "/path/to/two-0.0.1.txt",
+      #    "/path/to/one-0.0.1.txt",
+      #    "/path/to/one.txt",
+      #    "/path/to/two-1.0.1.txt",
+      #    "/path/to/three.txt"]
+      #
+      #   vniq(paths)
+      #   # => [
+      #   # "/path/to/one-0.0.1.txt",
+      #   # "/path/to/two-1.0.1.txt",
+      #   # "/path/to/three.txt"]
+      #
+      def vniq(array, earliest=false, preserve_order=true)
+        unique = {}
+        array.sort.each do |path|
+          base, version = deversion(path)
+          (unique[base] ||= []) << version
+        end
+        
+        results = []
+        unique.each_pair do |base, versions|
+          versions = versions.sort {|a, b| compare_versions(a,b) }
+          winner = earliest ? versions.shift : versions.pop
+          results << version(base, winner)
+        end
+        
+        results = results.sort_by do |path|
+          array.index(path)
+        end if preserve_order
+        
+        results
+      end
+      
       private
       
       # Converts an input argument (typically a string or an array) 

data/lib/tap/task.rb

@@ -1,11 +1,13 @@
-require 'tap/support/executable'
-require 'tap/support/lazydoc/method'
-require 'tap/support/lazydoc/definition'
-require 'tap/support/intern'
-autoload(:OptionParser, 'optparse')
+autoload(:ConfigParser, 'config_parser')
 
 module Tap
-
+  autoload(:FileTask, 'tap/file_task')
+  
+  module Support
+    autoload(:Templater, 'tap/support/templater')
+    autoload(:Intern, 'tap/support/intern')
+  end
+  
   # === Task Definition
   #
   # Tasks specify executable code by overridding the process method in
@@ -29,9 +31,8 @@ module Tap
   #   MixedInputs.new.execute(:a, :b)              # => [:a, :b, []]
   #   MixedInputs.new.execute(:a, :b, 1, 2, 3)     # => [:a, :b, [1,2,3]]
   #
-  # Tasks may be create with new, or with intern.  Intern overrides
-  # process with a custom block that gets called with the task instance
-  # and the inputs.
+  # Tasks may be create with new, or with intern.  Intern overrides process
+  # using a block that receives the task instance and the inputs.
   #
   #   no_inputs = Task.intern {|task| [] }
   #   one_input = Task.intern {|task, input| [input] }
@@ -67,8 +68,8 @@ module Tap
   #   t.respond_to?(:three)        # => false
   #
   # Configurations can be validated/transformed using an optional block.  
-  # Tap::Support::Validation pre-packages many common blocks which may
-  # be accessed through the class method 'c':
+  # Many common blocks are pre-packaged and may be accessed through the
+  # class method 'c':
   #
   #   class ValidatingTask < Tap::Task
   #     # string config validated to be a string
@@ -85,40 +86,31 @@ module Tap
   #   t.integer = "1"
   #   t.integer == 1         # => true 
   #
-  #--
-  # === Subclassing
-  # Tasks can be subclassed normally, with one reminder related to batching.
+  # See the {Configurable}[http://tap.rubyforge.org/configurable/]
+  # documentation for more information.
   #
-  # Batched tasks are generated by duplicating an existing instance, hence
-  # all instance variables will point to the same object in the batched
-  # and original task.  At times (as with configurations), this is 
-  # undesirable; the batched task should have it's own copy of an 
-  # instance variable.
+  # === Subclassing
+  # Tasks may be subclassed normally, but be sure to call super as necessary,
+  # in particular when overriding the following methods:
   #
-  # In these cases, the <tt>initialize_copy</tt> should be overridden
-  # and should re-initialize the appropriate variables.  Be sure to call
-  # super to invoke the default <tt>initialize_copy</tt>:
+  #   class Subclass < Tap::Task
+  #     class << self
+  #       def inherited(child)
+  #         super
+  #       end
+  #     end
   #
-  #   class SubclassTask < Tap::Task
-  #     attr_accessor :array
   #     def initialize(*args)
-  #       @array = []
   #       super
   #     end
-  #  
+  #
   #     def initialize_copy(orig)
-  #       @array = orig.array.dup
   #       super
   #     end
   #   end
   #
-  #   t1 = SubclassTask.new
-  #   t2 = t1.initialize_batch_obj
-  #   t1.array == t2.array                         # => true
-  #   t1.array.object_id == t2.array.object_id     # => false
-  #
   class Task
-    include Support::Configurable
+    include Configurable
     include Support::Executable
     
     class << self
@@ -140,15 +132,15 @@ module Tap
       # Returns an instance of self; the instance is a kind of 'global'
       # instance used in class-level dependencies.  See depends_on.
       def instance
-        @instance ||= new
+        @instance ||= new.extend(Support::Dependency)
       end
       
       def inherited(child) # :nodoc:
         unless child.instance_variable_defined?(:@source_file)
-          caller.first =~ Support::Lazydoc::CALLER_REGEXP
+          caller[0] =~ Lazydoc::CALLER_REGEXP
           child.instance_variable_set(:@source_file, File.expand_path($1)) 
         end
-
+        
         child.instance_variable_set(:@dependencies, dependencies.dup)
         super
       end
@@ -168,146 +160,166 @@ module Tap
       end
       
       # Parses the argv into an instance of self and an array of arguments 
-      # (implicitly to be enqued to the instance).  Yields a help string to
-      # the block when the argv indicates 'help'.
-      def parse(argv=ARGV, app=Tap::App.instance, &block) # :yields: help_str
-        parse!(argv.dup, &block)
+      # (implicitly to be enqued to the instance).
+      def parse(argv=ARGV, app=Tap::App.instance)
+        parse!(argv.dup, app)
       end
       
-      # Same as parse, but removes switches destructively. 
-      def parse!(argv=ARGV, app=Tap::App.instance) # :yields: help_str
-        opts = OptionParser.new
-
-        # Add configurations
-        argv_config = {}
-        unless configurations.empty?
-          opts.separator ""
-          opts.separator "configurations:"
-        end
-
-        configurations.each do |receiver, key, config|
-          opts.on(*config.to_optparse_argv) do |value|
-            argv_config[key] = value
-          end
-        end
-
-        # Add options on_tail, giving priority to configurations
+      # Same as parse, but removes switches destructively.
+      def parse!(argv=ARGV, app=Tap::App.instance)
+        opts = ConfigParser.new
+        opts.separator "configurations:"
+        opts.add(configurations)
+        
         opts.separator ""
         opts.separator "options:"
-
-        opts.on_tail("-h", "--help", "Print this help") do
+        
+        # add option to print help
+        opts.on("--help", "Print this help") do
           prg = case $0
           when /rap$/ then 'rap'
           else 'tap run --'
           end
           
-          opts.banner = "#{help}usage: #{prg} #{to_s.underscore} #{args.subject}"
-          if block_given? 
-            yield(opts.to_s)
-          else
-            puts opts
-            exit
-          end
+          puts "#{help}usage: #{prg} #{to_s.underscore} #{args}"
+          puts          
+          puts opts
+          exit
         end
-
-        # Add option for name
+ 
+        # add option to specify the task name
         name = default_name
-        opts.on_tail('--name NAME', /^[^-].*/, 'Specify a name') do |value|
+        opts.on('--name NAME', 'Specifies the task name') do |value|
           name = value
         end
-
-        # Add option to add args
+        
+        # add option to specify a config file
+        config_path = nil
+        opts.on('--config FILE', 'Specifies a config file') do |value|
+          config_path = value
+        end
+ 
+        # add option to load args to ARGV
         use_args = []
-        opts.on_tail('--use FILE', /^[^-].*/, 'Loads inputs from file') do |value|
-          obj = YAML.load_file(value)
-          case obj
-          when Hash 
-            obj.values.each do |array|
-              # error if value isn't an array
-              use_args.concat(array)
-            end
-          when Array 
-            use_args.concat(obj)
-          else
-            use_args << obj
-          end
+        opts.on('--use FILE', 'Loads inputs to ARGV') do |path|
+          use(path, use_args)
         end
         
-        # parse the argv
-        opts.parse!(argv)
+        # parse!
+        argv = opts.parse!(argv, {}, false)
         
-        # build and reconfigure the instance and any associated
-        # batch objects as specified in the file configurations
-        obj = new({}, name, app)
-        path_configs = load_config(app.config_filepath(name))
-        if path_configs.kind_of?(Array)
-          path_configs.each_with_index do |path_config, i|
-            next if i == 0
-            batch_obj = obj.initialize_batch_obj(path_config, "#{name}_#{i}")
-            batch_obj.reconfigure(argv_config)
-          end
-          path_configs = path_configs[0]
+        # load configurations
+        if config_path == nil && name != nil
+          config_path = app.filepath('config', "#{name}.yml")
         end
-        obj.reconfigure(path_configs).reconfigure(argv_config)
         
-        [obj, (argv + use_args)]
+        config = load_config(config_path)
+        
+        # build and reconfigure the instance
+        instance = new({}, name, app).reconfigure(config).reconfigure(opts.nested_config)
+        
+        [instance, (argv + use_args)]
       end
       
       # A convenience method to parse the argv and execute the instance
       # with the remaining arguments.  If 'help' is specified in the argv, 
       # execute prints the help and exits.
+      #
+      # Returns the non-audited result.
       def execute(argv=ARGV)
-        instance, args = parse(ARGV) do |help|
-          puts help
-          exit
-        end
-
+        instance, args = parse(ARGV)
         instance.execute(*args)
       end
-      
-      # Returns the class lazydoc, resolving if specified.
-      def lazydoc(resolve=true)
-        lazydoc = super(false)
-        lazydoc[self.to_s]['args'] ||= lazydoc.register_method(:process, Support::Lazydoc::Method)
-        super
-      end
 
       DEFAULT_HELP_TEMPLATE = %Q{<% manifest = task_class.manifest %>
-<%= task_class %><%= manifest.subject.to_s.strip.empty? ? '' : ' -- ' %><%= manifest.subject %>
+<%= task_class %><%= manifest.empty? ? '' : ' -- ' %><%= manifest.to_s %>
 
-<% unless manifest.empty? %>
+<% desc = manifest.kind_of?(Lazydoc::Comment) ? manifest.wrap(77, 2, nil) : [] %>
+<% unless desc.empty? %>
 <%= '-' * 80 %>
 
-<% manifest.wrap(77, 2, nil).each do |line| %>
+<% desc.each do |line| %>
   <%= line %>
 <% end %>
 <%= '-' * 80 %>
 <% end %>
 
 }
+      
       # Returns the class help.
       def help
         Tap::Support::Templater.new(DEFAULT_HELP_TEMPLATE, :task_class => self).build
       end
       
+      # Recursively loads path into a nested configuration file.
+      def load_config(path)
+        # optimization to check for trivial paths
+        return {} if Root.trivial?(path)
+        
+        Configurable::Utils.load_file(path, true) do |base, key, value|
+          base[key] ||= value if base.kind_of?(Hash)
+        end
+      end
+      
+      # Loads the contents of path onto argv.
+      def use(path, argv=ARGV)
+        obj = Root.trivial?(path) ? [] : (YAML.load_file(path) || [])
+        
+        case obj
+        when Array then argv.concat(obj)
+        else argv << obj
+        end
+        
+        argv
+      end
+      
       protected
       
-      # Sets a class-level dependency.  When task class B depends_on another task 
-      # class A, instances of B are initialized to depend on A.instance, with the
-      # specified arguments.  Returns self.
+      # Sets a class-level dependency; when task class B depends_on another
+      # task class A, instances of B are initialized to depend on A.instance.
+      # If a non-nil name is specified, depends_on will create a reader of 
+      # the resolved dependency value.
+      #
+      #   class A < Tap::Task
+      #     def process
+      #       "result"
+      #     end
+      #   end
+      #
+      #   class B < Tap::Task
+      #     depends_on :a, A
+      #   end
+      #
+      #   b = B.new
+      #   b.dependencies           # => [A.instance]
+      #   b.a                      # => "result"
+      #
+      #   A.instance.resolved?     # => true
+      # 
+      # Normally class-level dependencies are not added to existing instances
+      # but, as a special case, depends_on updates instance to depend on
+      # dependency_class.instance.
+      #
+      # Returns self.
       def depends_on(name, dependency_class)
         unless dependencies.include?(dependency_class)
           dependencies << dependency_class
         end
         
-        # returns the resolved result of the dependency
-        define_method(name) do
-          instance = dependency_class.instance
-          instance.resolve
-          instance._result._current
+        # update instance with the dependency if necessary
+        if instance_variable_defined?(:@instance)
+          instance.depends_on(dependency_class.instance)
+        end
+        
+        if name
+          # returns the resolved result of the dependency
+          define_method(name) do
+            dependency_class.instance.resolve.value
+          end
+        
+          public(name)
         end
         
-        public(name)
         self
       end
       
@@ -391,50 +403,29 @@ module Tap
         end
         
         if block_given?
+          # prevent lazydoc registration of the process method
+          subclass.registered_methods.delete(:process)
           subclass.send(:define_method, :process, &block)
         end
         
-        # define methods
-        instance_var = "@#{name}".to_sym
-        reader = (options[:reader] ||= "#{name}_config".to_sym)
-        writer = (options[:writer] ||= "#{name}_config=".to_sym)
-        
-        attr_reader name
-        
-        define_method(reader) do
-          # return the config for the instance
-          instance_variable_get(instance_var).config
-        end
-        
-        define_method(writer) do |value|
-          # initialize or reconfigure the instance of subclass
-          if instance_variable_defined?(instance_var) 
-            instance_variable_get(instance_var).reconfigure(value)
-          else
-            instance_variable_set(instance_var, subclass.new(value))
-          end
-        end
-        public(name, reader, writer)
+        # register documentation
+        # TODO: register subclass in documentation
+        options[:desc] ||= Lazydoc.register_caller(Lazydoc::Trailer, 1)
         
         # add the configuration
-        if options[:desc] == nil
-          caller[0] =~ Support::Lazydoc::CALLER_REGEXP
-          desc = Support::Lazydoc.register($1, $3.to_i - 1, Support::Lazydoc::Definition)
-          desc.subclass = subclass
-          options[:desc] = desc
-        end
-        
-        configurations.add(name, subclass.configurations.instance_config, options)
+        nest(name, subclass, options) {|overrides| subclass.new(overrides) }
       end
     end
     
     instance_variable_set(:@source_file, __FILE__)
     instance_variable_set(:@default_name, 'tap/task')
     instance_variable_set(:@dependencies, [])
+    
     lazy_attr :manifest
-    lazy_attr :args
+    lazy_attr :args, :process
+    lazy_register :process, Lazydoc::Arguments
     
-    # The name of self.
+    # The name of self
     #--
     # Currently names may be any object.  Audit makes use of name
     # via to_s, as does app when figuring configuration filepaths. 
@@ -442,25 +433,16 @@ module Tap
 
     # Initializes a new Task.
     def initialize(config={}, name=nil, app=App.instance)
-      super()
-
       @name = name || self.class.default_name
       @app = app
-      @_method_name = :execute_with_callbacks
+      @method_name = :execute_with_callbacks
       @on_complete_block = nil
       @dependencies = []
-      @batch = [self]
       
-      case config
-      when Support::InstanceConfiguration
-        # update is prudent to ensure all configs have an input
-        # (and hence, all configs will be initialized)
-        @config = config.update(self.class.configurations)
-        config.bind(self)
-      else 
-        initialize_config(config)
-      end
+      # initialize configs
+      initialize_config(config)
       
+      # setup class dependencies
       self.class.dependencies.each do |dependency_class|
         depends_on(dependency_class.instance)
       end
@@ -468,15 +450,6 @@ module Tap
       workflow
     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(overrides={}, name=nil)
-      obj = super().reconfigure(overrides)
-      obj.name = name if name
-      obj 
-    end
-    
     # The method for processing inputs into outputs.  Override this method in
     # subclasses to provide class-specific process logic.  The number of 
     # arguments specified by process corresponds to the number of arguments