tap 0.17.0 → 0.17.1

data/History

@@ -1,3 +1,12 @@
+== 0.17.1 / 2009-06-06
+
+* documentation and interface updates
+* reworked load to allow recurrent loads
+* modified stack to check_terminate before calling a node
+* fixed parsing of empty breaks in command line schema
+* simplified/standardized YAML schema syntax
+* added support for middleware to parser
+
 == 0.17.0 / 2009-05-25
 
 Significant reorganization and update to Tap internals.

data/README

@@ -20,7 +20,7 @@ and a
 {server}[http://tap.rubyforge.org/tap-server/index.html] 
 to execute workflows via HTTP.
 
-* {Tutorial}[link:files/doc/Tutorial.html], {API}[link:files/doc/API.html], {Structure}[link:files/doc/Class%20Reference.html]
+* {Tutorial}[http://tap.rubyforge.org/tap-suite/files/doc/Tutorial.html], {API}[link:files/doc/API.html], {Structure}[link:files/doc/Class%20Reference.html]
 * Website[http://tap.rubyforge.org]
 * Lighthouse[http://bahuvrihi.lighthouseapp.com/projects/9908-tap-task-application/tickets]
 * Github[http://github.com/bahuvrihi/tap/tree/master]

data/cmd/run.rb

@@ -2,8 +2,8 @@
 #
 # examples:
 #   tap run --help                     Prints this help
-#   tap run -w workflow.yml            Build and run a workflow
-#   tap run -w workflow.yml a b c      Same with [a, b, c] ARGV
+#   tap run -s schema.yml              Build and run a workflow
+#   tap run -s schema.yml a b c        Same with [a, b, c] ARGV
 #
 # schema:
 #   tap run -- task --help             Prints help for task
@@ -19,13 +19,11 @@ app = Tap::App.new
 
 # separate out argv schema
 argv = []
-break_regexp = Tap::Schema::Parser::BREAK
-while !ARGV.empty? && ARGV[0] !~ break_regexp
+while !ARGV.empty? && ARGV[0] !~ Tap::Schema::Parser::BREAK
   argv << ARGV.shift
 end
 
 # parse options
-schemas = []
 ConfigParser.new(app.config) do |opts|
   opts.separator ""
   opts.separator "configurations:"
@@ -66,20 +64,6 @@ ConfigParser.new(app.config) do |opts|
     exit(0)
   end
   
-  opts.on('-m', '--middleware MIDDLEWARE', 'Specify app middleware') do |key|
-    middleware = env[:middleware][key] or raise("unknown middleware: #{key}")
-    app.use(middleware)
-  end
-  
-  opts.on("-s", "--schema FILE", "Build the schema file") do |path|
-    unless File.exists?(path)
-      puts "No such schema file - #{path}"
-      exit(1)
-    end
-    
-    schemas << Tap::Schema.load_file(path)
-  end
-  
 end.parse!(argv, :clear_config => false, :add_defaults => false)
 
 #
@@ -87,17 +71,29 @@ end.parse!(argv, :clear_config => false, :add_defaults => false)
 #
 
 begin
+  if ARGV.empty?
+    msg = "No schema specified"
+    
+    unless argv.empty?
+      args = argv[0, 3].join(' ') + (argv.length > 3 ? ' ...' : '')
+      msg = "#{msg} (did you mean 'tap run -- #{args}'?)"
+    end
+    
+    puts msg
+    exit(0)
+  end
+  
   # parse argv schema
-  schemas << Tap::Schema.parse(ARGV)
+  schema = Tap::Schema.parse(ARGV)
+  app.build(schema, :resources => env)
+  
   ARGV.replace(argv)
+  Tap::Exe.set_signals(app)
   
-  env.run(schemas, app)
+  app.run
 rescue
   raise if $DEBUG
   puts $!.message
-  if $!.message == "no nodes specified" && !ARGV.empty?
-    puts "(did you mean 'tap run -- #{ARGV.join(' ')}'?)"
-  end
   exit(1)
 end
 

data/doc/API

@@ -34,12 +34,12 @@ Note the middleware API is essentially the same as for {Rack}[http://rack.rubyfo
 
 == Tap::Schema
 
-Schema describe workflows as data.  To build a workflow from a schema, workflow classes need to instantiate themselves using the schema data. The <tt>parse</tt> and <tt>instantiate</tt> methods are provided to do so.  
+Schema describe workflows as data.  To build a workflow from a schema, workflow classes need to instantiate themselves using the schema data. The <tt>parse!</tt> and <tt>instantiate</tt> methods are provided to do so.  
 
-  WorkflowClass.parse(argv=ARGV, app=App.instance)
+  WorkflowClass.parse!(argv=ARGV, app=App.instance)
   WorkflowClass.instantiate(argh, app=App.instance)
   
-As implied in by the inputs, <tt>parse</tt> instantiates from an array, while <tt>instantiate</tt> instantiates from a hash with symbol keys.  If <tt>parse</tt> receives a string, it must be able to convert it to an array (ex using Shellwords).
+As implied in by the inputs, <tt>parse!</tt> instantiates from an array, while <tt>instantiate</tt> instantiates from a hash with symbol keys.  If <tt>parse!</tt> receives a string, it must be able to convert it to an array (ex using Shellwords).
 
 How the class actually performs the instantiation is up to the class but typically parse creates a hash and calls instantiate.
 

data/lib/tap/app.rb

@@ -4,6 +4,7 @@ require 'tap/app/node'
 require 'tap/app/state'
 require 'tap/app/stack'
 require 'tap/app/queue'
+require 'tap/schema'
 
 module Tap
   
@@ -167,7 +168,7 @@ module Tap
       super() # monitor
       
       @state = State::READY
-      @stack = options[:stack] || Stack.new
+      @stack = options[:stack] || Stack.new(self)
       @queue = options[:queue] || Queue.new
       @cache = options[:cache] || {}
       @trace = []
@@ -218,8 +219,28 @@ module Tap
     end
     
     # Adds the specified middleware to the stack.
-    def use(middleware)
-      @stack = middleware.new(@stack)
+    def use(middleware, *argv)
+      @stack = middleware.new(@stack, *argv)
+    end
+    
+    def build(schema, options={})
+      unless schema.kind_of?(Schema)
+        schema = Schema.new(schema)
+      end
+      
+      if resources = options[:resources]
+        schema.resolve! do |type, id|
+          resources[type][id]
+        end
+      end
+      
+      schema.validate!
+      
+      if options[:clean]
+        reset
+      end
+      
+      schema.build!(self)
     end
     
     # Clears the cache, the queue, and resets the stack so that no middleware
@@ -230,7 +251,7 @@ module Tap
           raise "cannot reset unless READY"
         end
         
-        @stack = Stack.new
+        @stack = Stack.new(self)
         cache.clear
         queue.clear
       end
@@ -312,23 +333,19 @@ module Tap
         return self unless state == State::READY
         @state = State::RUN
       end
-
-      # TODO: log starting run
+      
       begin
-        until queue.empty? || state != State::RUN
-          dispatch(*queue.deq)
+        while state == State::RUN
+          break unless entry = queue.deq
+          dispatch(*entry)
         end
       rescue(TerminateError)
         # gracefully fail for termination errors
-      rescue(Exception)
-        # handle other errors accordingly
-        raise if debug?
-        log($!.class, $!.message)
+        queue.unshift(*entry)
       ensure
         synchronize { @state = State::READY }
       end
       
-      # TODO: log run complete
       self
     end
     
@@ -362,6 +379,7 @@ module Tap
     # check_terminate to provide breakpoints in long-running processes.
     def check_terminate
       if state == App::State::TERMINATE
+        yield if block_given?
         raise App::TerminateError.new
       end
     end
@@ -402,13 +420,6 @@ module Tap
         target.puts "# date: #{Time.now.strftime(options[:date_format])}" if options[:date]
         target.puts "# info: #{info}" if options[:info]
         
-        # # print load paths and requires
-        # target.puts "# load paths"
-        # target.puts $:.to_yaml
-        # 
-        # target.puts "# requires"
-        # target.puts $".to_yaml
-        
         # dump yaml, fixing as necessary
         yaml = YAML.dump(self)
         yaml.gsub!(/\&(.*!ruby\/object:.*?)\s*\?/) {"? &#{$1} " } if YAML.const_defined?(:Syck)

data/lib/tap/app/stack.rb

@@ -4,11 +4,19 @@ module Tap
     # The base of the application call stack.
     class Stack
       
-      # Calls the node with the inputs:
+      # The application using this stack.
+      attr_reader :app
+      
+      def initialize(app)
+        @app = app
+      end
+      
+      # Checks app for termination and then calls the node with the inputs:
       #
       #   node.call(*inputs)
       #
       def call(node, inputs)
+        app.check_terminate
         node.call(*inputs)
       end
     end

data/lib/tap/constants.rb

@@ -1,7 +1,7 @@
 module Tap
   MAJOR = 0
   MINOR = 17
-  TINY = 0
+  TINY = 1
   
   VERSION="#{MAJOR}.#{MINOR}.#{TINY}" 
   WEBSITE="http://tap.rubyforge.org"

data/lib/tap/exe.rb

@@ -94,20 +94,7 @@ module Tap
       end
     end
     
-    def build(schema, app=Tap::App.instance)
-      schema.resolve! do |type, id, data|
-        klass = self[type][id]
-        if !klass && block_given?
-          klass = yield(type, id, data)
-        end
-        
-        klass || id
-      end
-      schema.validate!
-      schema.build(app)
-    end
-    
-    def set_signals(app)
+    def self.set_signals(app)
       # info signal -- Note: some systems do 
       # not support the INFO signal 
       # (windows, fedora, at least)
@@ -139,20 +126,5 @@ module Tap
         end
       end if signals.include?("INT")
     end
-    
-    def run(schemas, app=Tap::App.instance, &block)
-      schemas = [schemas] unless schemas.kind_of?(Array)
-      schemas.each do |schema|
-        build(schema, app, &block)
-      end
-      
-      if app.queue.empty?
-        raise "no nodes specified"
-      end
-
-      set_signals(app)
-      app.run
-    end
-    
   end
 end

data/lib/tap/schema.rb

@@ -38,11 +38,12 @@ module Tap
     attr_reader :joins
     
     # An array of [key, [args]] data that indicates the tasks and arguments
-    # to be added to an application during build.  If args are not specified,
-    # then the arguments specified in the task schema are used.
+    # to be added to an application during build.  A key may be specified
+    # alone if tasks[key] is an array; in that case, the arguments remaining
+    # in tasks[key] after instantiation will be used.
     #
     #   queue:
-    #   - key                  # uses tasks[key] arguments
+    #   - key                  # uses tasks[key]
     #   - [key, [1, 2, 3]]     # enques tasks[key] with [1, 2, 3]
     #
     attr_reader :queue
@@ -51,76 +52,76 @@ module Tap
     attr_reader :middleware
     
     def initialize(schema={})
-      @tasks = hashify(schema['tasks'] || {})
-      
-      @joins = dehashify(schema['joins'] || []).collect do |join|
-        inputs, outputs, join = dehashify(join)
-        [inputs, outputs, join]
-      end
-      
-      @queue = dehashify(schema['queue'] || []).collect do |queue|
-        dehashify(queue)
-      end
-      
-      @middleware = dehashify(schema['middleware'] || [])
+      @tasks = schema['tasks'] || {}
+      @joins = schema['joins'] || []
+      @queue = schema['queue'] || []
+      @middleware = schema['middleware'] || []
     end
     
     def resolve!
-      tasks.dup.each_pair do |key, task|
+      tasks.each_pair do |key, task|
         task ||= {}
-        tasks[key] = resolve(task) do |id, data|
-          yield(:task, id || key, data)
+        tasks[key] = resolve(task) do |id|
+          yield(:task, id || key)
         end
       end
       
       joins.collect! do |inputs, outputs, join|
         join ||= {}
-        join = resolve(join) do |id, data|
-          yield(:join, id || 'join', data)
+        join = resolve(join) do |id|
+          yield(:join, id || 'join')
         end
         [inputs, outputs, join]
       end
       
       middleware.collect! do |m|
-        resolve(m) do |id, data|
-          yield(:middleware, id, data)
+        resolve(m) do |id|
+          yield(:middleware, id)
         end
       end
       
+      queue.collect! do |(key, inputs)|
+        [key, inputs || tasks[key]]
+      end
+      
       self
     end
     
     def validate!
       errors = []
-      tasks.each do |key, task|
+      tasks.each_value do |task|
         unless resolved?(task)
-          errors << "unknown task: #{task}"
+          errors << "unknown task: #{task.inspect}"
         end
       end
       
       joins.each do |inputs, outputs, join|
         unless resolved?(join)
-          errors << "unknown join: #{join}"
+          errors << "unknown join: #{join.inspect}"
         end
         
         inputs.each do |key| 
           unless tasks.has_key?(key)
-            errors << "missing join input: #{key}"
+            errors << "missing join input: #{key.inspect}"
           end
         end
         
         outputs.each do |key| 
           unless tasks.has_key?(key)
-            errors << "missing join output: #{key}"
+            errors << "missing join output: #{key.inspect}"
           end
         end
       end
       
-      # queue.each do |(key, args)| 
-      #   unless tasks.has_key?(key)
-      #     errors << "missing task: #{key}"
-      #   end
-      # end
+      queue.each do |(key, args)| 
+        if tasks.has_key?(key)
+          unless args.kind_of?(Array)
+            errors << "non-array args: #{args.inspect}"
+          end
+        else
+          errors << "missing task: #{key}"
+        end
+      end
       
       middleware.each do |m|
         unless resolved?(m)
@@ -130,7 +131,7 @@ module Tap
       
       unless errors.empty?
         prefix = if errors.length > 1
-          "#{errors.length} build errors\n"
+          "#{errors.length} schema errors\n"
         else
            ""
         end
@@ -162,75 +163,32 @@ module Tap
       self
     end
     
-    def scrub!
-      tasks.each do |key, task|
-        yield(task)
-      end
-      
-      joins.each do |inputs, outputs, join|
-        yield(join)
-      end
-    end
-    
-    def build(app)
+    def build!(app)
       # instantiate tasks
-      tasks = {}
-      arguments = {}
-      self.tasks.each_pair do |key, task|
-        instance, args = instantiate(task, app)
-      
-        tasks[key] = instance
-        arguments[key] = args
+      tasks.each_pair do |key, task|
+        tasks[key] = instantiate(task, app)
       end
       
       # build the workflow
-      self.joins.each do |inputs, outputs, join|
+      joins.collect! do |inputs, outputs, join|
         inputs = inputs.collect {|key| tasks[key] }
         outputs = outputs.collect {|key| tasks[key] }
         instantiate(join, app).join(inputs, outputs)
       end
       
       # utilize middleware
-      self.middleware.each do |middleware|
+      middleware.collect! do |middleware|
         instantiate(middleware, app)
       end
       
       # enque tasks
       queue.each do |(key, inputs)|
-        unless inputs
-          inputs = arguments[key]
-        end
-        
-        app.enq(tasks[key], *inputs) if inputs
+        app.enq(tasks[key], *inputs)
       end
       
       tasks
     end
     
-    def traverse
-      map = {}
-      self.tasks.each_pair do |key, task|
-        map[key] = [[],[]]
-      end
-      
-      index = 0
-      self.joins.each do |inputs, outputs, join|
-        inputs.each do |key|
-          map[key][1] << index
-        end
-        
-        outputs.each do |key|
-          map[key][0] << index
-        end
-        
-        index += 1
-      end
-      
-      map.keys.sort.collect do |key|
-        [key, *map[key]]
-      end
-    end
-    
     # Creates an hash dump of self.
     def to_hash
       { 'tasks' => tasks, 

data/lib/tap/schema/parser.rb

@@ -30,12 +30,11 @@ module Tap
     #   schema.joins                  # => [['join', [1],[2]]]
     #
     # In the example, the indicies of the tasks participating in the sequence
-    # are inferred as the last and next tasks in the schema, and obviously the
-    # location of the sequence break is significant.  This isn't the case when
-    # the tasks in a join are explicitly specified.  These both sequence a to
-    # b, and b to c.
+    # are inferred as the last and next tasks in the schema.  Alternatively
+    # the tasks participating in the sequence may be written out directly;
+    # these also sequence b to c.
     #
-    #   schema = Parser.new("a -- b -- c --0:1 --1:2").schema
+    #   schema = Parser.new("a -- b -- c --1:2").schema
     #   schema.tasks                  
     #   # => {
     #   # 0 => ["a"], 
@@ -44,11 +43,10 @@ module Tap
     #   # }
     #   schema.joins                  
     #   # => [
-    #   # [[0],[1]],
-    #   # [[1],[2]],
+    #   # [[1],[2]]
     #   # ]
     #
-    #   schema = Parser.new("a --1:2 --0:1 b -- c").schema
+    #   schema = Parser.new("a --1:2 b -- c").schema
     #   schema.tasks
     #   # => {
     #   # 0 => ["a"], 
@@ -57,8 +55,7 @@ module Tap
     #   # }
     #   schema.joins                  
     #   # => [
-    #   # [[1],[2]],
-    #   # [[0],[1]],
+    #   # [[1],[2]]
     #   # ]
     #
     # ==== Multi-Join Syntax
@@ -149,17 +146,17 @@ module Tap
         # Matches any breaking arg. Examples:
         #
         #   --
-        #   --+
         #   --1:2
         #   --[1][2]
         #   --[1,2,3][4,5,6]is.join
+        #   --.middleware
         #
         # After the match:
         #
         #   $1:: The string after the break
         #        (ex: '--' => '', '--:' => ':', '--[1,2][3,4]is.join' => '[1,2][3,4]is.join')
         #
-        BREAK =  /\A--(\z|[\d\:\[].*\z)/
+        BREAK =  /\A--(\z|[\d\:\[\.].*\z)/
 
         # Matches a sequence break. Examples:
         #
@@ -204,6 +201,18 @@ module Tap
         #
         JOIN_MODIFIER = /\A([A-z]*)(?:\.(.*))?\z/
         
+        # Matches a generic middleware break. Examples:
+        #
+        #   ". middleware --flag"
+        #   .middleware
+        #
+        # After the match:
+        #
+        #   $1:: The modifier string.
+        #        (ex: '.middleware' => 'middleware')
+        #
+        MIDDLEWARE = /\A\.(.*)\z/
+        
         # Parses an indicies str along commas, and collects the indicies
         # as integers. Ex:
         #
@@ -258,8 +267,8 @@ module Tap
 
         # Parses the match of a JOIN regexp into a [input_indicies,
         # output_indicies, metadata] array. The inputs corresponds to $1, $2,
-        # and $3 for a match to a JOIN regexp.  A join type of  'join' is
-        # assumed unless otherwise specified.
+        # and $3 for the match.  A join type of  'join' is assumed unless
+        # otherwise specified.
         #
         #   parse_join("1", "2,3", "")         # => [[1], [2,3]]
         #   parse_join("", "", "is.type")      # => [[], [], ['type', '-i', '-s']]
@@ -288,6 +297,13 @@ module Tap
             Shellwords.shellwords(modifier)
           end
         end
+        
+        # Parses the match of a MIDDLEWARE regexp into metadata array.
+        # The input corresponds to $1 for the match. Currently this
+        # method is an alias for Shellwords.shellwords.
+        def parse_middleware(one)
+          Shellwords.shellwords(one)
+        end
       end
       
       include Utils
@@ -309,17 +325,17 @@ module Tap
 
       # Same as parse, but removes parsed args from argv.
       def parse!(argv)
-        @current_index = 0
         @schema = Schema.new
         
         # prevent the addition of an empty task to schema
-        return if argv.empty?
+        return schema if argv.empty?
         
         argv = Shellwords.shellwords(argv) if argv.kind_of?(String)
-        argv.unshift('--')
+        argv.unshift('--') unless argv[0] =~ BREAK
         
+        @current_index = -1
+        @current = nil
         escape = false
-        current_task = nil
         while !argv.empty?
           arg = argv.shift
 
@@ -329,7 +345,7 @@ module Tap
             if arg == ESCAPE_END
               escape = false
             else
-              (current_task ||= task(current_index)) << arg
+              current << arg
             end
 
             next
@@ -345,13 +361,9 @@ module Tap
             break
           
           when BREAK
-            # a breaking argument was reached:
-            # unless the current argv is empty,
-            # append and start a new definition
-            if current_task && !current_task.empty?
-              self.current_index += 1
-              current_task = nil
-            end
+            # a breaking argument was reached
+            @current_index += 1
+            @current = nil
             
             # parse the break string for any
             # schema modifications
@@ -361,18 +373,28 @@ module Tap
             # add all other non-breaking args to
             # the current argv; this includes
             # both inputs and configurations
-            (current_task ||= task(current_index)) << arg
+            current << arg
             
           end
         end
         
+        # determine the queue as all tasks not
+        # used as a join output
+        queue = schema.tasks.keys
+        schema.joins.each {|join| queue -= join[1] }
+        schema.queue.concat(queue)
+        
         schema
       end
       
       protected
       
       # The index of the task currently being parsed.
-      attr_accessor :current_index # :nodoc:
+      attr_reader :current_index # :nodoc:
+      
+      def current
+        @current ||= task(current_index)
+      end
       
       # helper to initialize a task at the specified index
       def task(index) # :nodoc:
@@ -388,26 +410,16 @@ module Tap
       def parse_break(arg) # :nodoc:
         case arg
         when ""
-          unless schema.queue.include?(current_index)
-            schema.queue << current_index
-          end
         when SEQUENCE
-          parse_sequence($1, $2).each {|join| set_join(join) }
+          schema.joins.concat parse_sequence($1, $2)
         when JOIN
-          set_join(parse_join($1, $2, $3))
+          schema.joins << parse_join($1, $2, $3)
+        when MIDDLEWARE
+          schema.middleware << parse_middleware($1)
         else
           raise ArgumentError, "invalid break argument: #{arg}"
         end
       end
-      
-      # constructs the specified join and removes the targets of the
-      # join from the queue
-      def set_join(join) # :nodoc:
-        join[1].each do |output|
-          schema.queue.delete(output)
-        end
-        schema.joins << join
-      end
     end
   end
 end

data/lib/tap/schema/utils.rb

@@ -1,19 +1,19 @@
 module Tap
   class Schema
     module Utils
-      module_function
       
       def instantiate(data, app)
         case data
         when Hash  then data['class'].instantiate(symbolize(data), app)
-        when Array then data.shift.parse(data, app)
+        when Array then data.shift.parse!(data, app)
+        else raise "cannot instantiate: #{data.inspect}"
         end
       end
       
       def resolved?(data)
         case data
         when Hash  then data['class'].respond_to?(:instantiate)
-        when Array then data[0].respond_to?(:parse)
+        when Array then data[0].respond_to?(:parse!)
         else false
         end
       end
@@ -23,9 +23,11 @@ module Tap
         
         case data
         when Hash
-          data['class'] = yield(data['id'], data)
+          unless resolved?(data)
+            data['class'] = yield(data['id']) || data['id']
+          end
         when Array 
-          data[0] = yield(data[0], data)
+          data[0] = yield(data[0]) || data[0]
         end
         
         data
@@ -34,8 +36,6 @@ module Tap
       # Symbolizes the keys of hash.  Returns non-hash values directly and
       # raises an error in the event of a symbolize conflict.
       def symbolize(hash)
-        return hash unless hash.kind_of?(Hash)
-        
         result = {}
         hash.each_pair do |key, value|
           key = key.to_sym || key
@@ -49,34 +49,6 @@ module Tap
         result
       end
       
-      # Returns the values for hash sorted by key.  Returns non-hash objects
-      # directly.
-      def dehashify(obj)
-        case obj
-        when nil   then []
-        when Hash  then obj.keys.sort.collect {|key| obj[key] }
-        else obj
-        end
-      end
-      
-      # Returns obj as a hash, using the index of each element as the 
-      # key for the element.  The object must respond to each.  Returns
-      # hashes directly.
-      def hashify(obj)
-        case obj
-        when nil  then {}
-        when Hash then obj
-        else
-          index = 0
-          hash = {}
-          obj.each do |entry|
-            hash[index] = entry
-            index += 1
-          end
-          hash
-        end
-      end
-      
     end
   end
 end

data/lib/tap/task.rb

@@ -156,8 +156,7 @@ module Tap
         instance
       end
       
-      # Parses the argv into an instance of self and an array of arguments
-      # (implicitly to be enqued to the instance).  By default parse 
+      # Parses the argv into an instance of self.  By default parse 
       # parses an argh then calls instantiate, but there is no requirement
       # that this occurs in subclasses.
       def parse(argv=ARGV, app=Tap::App.instance)
@@ -197,12 +196,8 @@ module Tap
         # (note defaults are not added so they will not
         # conflict with string keys from a config file)
         argv = opts.parse!(argv, :add_defaults => false)
-        argh = { 
-          :config => opts.nested_config,
-          :args => argv
-        }
         
-        instantiate(argh, app)
+        instantiate({:config => opts.nested_config}, app)
       end
       
       # Instantiates an instance of self and returns an instance of self and
@@ -219,7 +214,7 @@ module Tap
           app.cache[self] = instance
         end
         
-        [instance, argh[:args]]
+        instance
       end
 
       DEFAULT_HELP_TEMPLATE = %Q{<% desc = task_class::desc %>

data/lib/tap/tasks/dump.rb

@@ -30,7 +30,7 @@ module Tap
     # Dump serves as a baseclass for more complicated dumps.  A YAML dump
     # (see {tap-tasks}[http://tap.rubyforge.org/tap-tasks]) looks like this:
     #
-    #   class Yaml < Tap::Dump
+    #   class Yaml < Tap::Tasks::Dump
     #     def dump(obj, io)
     #       YAML.dump(obj, io)
     #     end

data/lib/tap/tasks/load.rb

@@ -24,39 +24,97 @@ module Tap
     # Load serves as a baseclass for more complicated loads.  A YAML load
     # (see {tap-tasks}[http://tap.rubyforge.org/tap-tasks]) looks like this:
     #
-    #   class Yaml < Tap::Load
+    #   class Yaml < Tap::Tasks::Load
     #     def load(io)
     #       YAML.load(io)
     #     end
     #   end
     #
+    # Load is constructed to reque itself in cases where objects are to
+    # be loaded sequentially from the same io.  Load will reque until the
+    # end-of-file is reached, but this behavior can be modified by
+    # overriding the complete? method.  An example is a prompt task:
+    #
+    #   class Prompt < Tap::Tasks::Load
+    #     config :exit_seq, "\n"
+    #
+    #     def load(io)
+    #       if io.eof?
+    #         nil
+    #       else
+    #         io.readline
+    #       end
+    #     end
+    #
+    #     def complete?(io, line)
+    #       line == nil || line == exit_seq
+    #     end
+    #   end
+    #
+    # If the use_close configuration is specified, load will close io upon
+    # completion.  Files opened by load are always closed upon completion.
+    #
     class Load < Tap::Task
       
-      config :file, false, &c.flag         # opens the input as a file
+      config :file, false, &c.flag                         # Opens the input as a file
+      config :use_close, false, :long => :close, &c.flag   # Close the input when complete
       
-      # The default process simply reads the input data and returns it.
-      # See load.
+      # Loads data from io.  Process will open the input io object, load
+      # a result, then check to see if the loading is complete (using the
+      # complete? method).  Unless loading is complete, process will enque
+      # io to self.  Process will close io when loading is complete, provided
+      # use_close or file is specified.
       def process(io=$stdin)
-        # read on an empty stdin ties up the command line;
-        # this facilitates the intended behavior
-        if io.kind_of?(IO) && io.stat.size == 0
-          io = '' 
+        io = open(io)
+        result = load(io)
+        
+        if complete?(io, result)
+          if use_close || file
+            close(io)
+          end
+        else
+          enq(io)
         end
+        
+        result
+      end
       
-        if io.kind_of?(String)
-          io = StringIO.new(io)
-        end unless file
-      
-        open_io(io) do |data|
-          load(data)
+      # Opens the io; specifically this means:
+      #
+      # * Opening a File (file true)
+      # * Creating a StringIO for String inputs
+      # * Opening an IO for integer file descriptors
+      # * Returning all other objects
+      #
+      def open(io)
+        return File.open(io) if file
+        
+        case io
+        when String
+          StringIO.new(io)
+        when Integer
+          IO.open(io)
+        else 
+          io
         end
       end
-    
-      # Loads data from the io; the return of load is the return of process.  By
-      # default load simply reads data from io.
+      
+      # Loads data from io using io.read.  Load is intended as a hook
+      # for subclasses.
       def load(io)
         io.read
       end
+      
+      # Closes io.
+      def close(io)
+        io.close
+      end
+      
+      # Returns io.eof?  Override in subclasses for the desired behavior
+      # (see process).
+      def complete?(io, last)
+        io.eof?
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: tap
 version: !ruby/object:Gem::Version 
-  version: 0.17.0
+  version: 0.17.1
 platform: ruby
 authors: 
 - Simon Chiang
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-05-25 00:00:00 -06:00
+date: 2009-06-06 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency