tap 0.17.1 → 0.18.0

data/lib/tap/middleware.rb

@@ -0,0 +1,56 @@
+require 'configurable'
+
+module Tap
+  class Middleware
+    class << self
+      
+      # Instantiates an instance of self and causes app to use the instance
+      # as middleware.
+      def parse(argv=ARGV, app=Tap::App.instance)
+        parse!(argv.dup, app)
+      end
+      
+      # Same as parse, but removes arguments destructively.
+      def parse!(argv=ARGV, app=Tap::App.instance)
+        opts = ConfigParser.new
+        opts.separator "configurations:"
+        opts.add(configurations)
+        
+        args = opts.parse!(argv, :add_defaults => false)
+        instantiate({:config => opts.nested_config}, app)
+      end
+      
+      # Instantiates an instance of self and causes app to use the instance
+      # as middleware.
+      def instantiate(argh, app=Tap::App.instance)
+        app.use(self, argh[:config] || {})
+      end
+    end
+    
+    include Configurable
+    
+    # The call stack.
+    attr_reader :stack
+
+    def initialize(stack, config={})
+      @stack = stack
+      initialize_config(config)
+    end
+    
+    # Returns the app at the base of the stack.
+    def app
+      @app ||= begin
+        current = stack
+        until current.kind_of?(App::Stack)
+          current = current.stack
+        end
+        current.app
+      end
+    end
+    
+    # By default call simply calls stack with the node and inputs.
+    def call(node, inputs=[])
+      stack.call(node, inputs)
+    end
+  end
+end

data/lib/tap/schema.rb

@@ -1,11 +1,63 @@
+require 'tap/app'
 require 'tap/schema/utils'
 require 'tap/schema/parser'
 
 module Tap
+  class App
+    def build(schema, options={})
+      options = {
+        :clean => true,
+        :validate => true
+      }.merge(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
+      
+      if options[:clean]
+        reset
+      end
+      
+      schema.build!(self, options[:validate])
+    end
+    
+    def to_schema
+      schema = Schema.new
+      queue.to_a.each do |task, inputs|
+        schema.add(task, inputs)
+      end
+      
+      middleware.reverse_each do |m|
+        schema.use(m)
+      end
+      
+      index = 0
+      schema.tasks.keys.each do |task|
+        schema.rename(task, index)
+        index += 1
+      end
+      
+      if block_given?
+        schema.resources.each_pair do |type, resource|
+          yield(type, resource)
+        end
+      end
+      
+      schema
+    end
+  end
+  
   class Schema
     class << self
       def load(str)
-        new(YAML.load(str) || {})
+        schema = YAML.load(str)
+        new(schema ? Utils.symbolize(schema) : {})
       end
       
       def load_file(path)
@@ -51,11 +103,86 @@ module Tap
     # An array of middleware to build onto the app.
     attr_reader :middleware
     
+    # The app used to build self
+    attr_reader :app
+    
     def initialize(schema={})
-      @tasks = schema['tasks'] || {}
-      @joins = schema['joins'] || []
-      @queue = schema['queue'] || []
-      @middleware = schema['middleware'] || []
+      @tasks = schema[:tasks] || {}
+      @joins = schema[:joins] || []
+      @queue = schema[:queue] || []
+      @middleware = schema[:middleware] || []
+      
+      @app = nil
+    end
+    
+    def add(node, inputs=nil)
+      collect_tasks(node).collect do |task|
+        tasks[task] = task.to_hash
+        task.joins
+      end.flatten.uniq.each do |join|
+        joins << [join.inputs, join.outputs, join.to_hash]
+      end
+      
+      if inputs
+        queue << [node, inputs]
+      end
+      
+      self
+    end
+    
+    def use(middleware)
+      self.middleware << middleware.to_hash
+      self
+    end
+    
+    def resources
+      {
+        :task => tasks.values,
+        :join => joins.collect {|join| join[2] },
+        :middleware => middleware
+      }
+    end
+    
+    # Renames the current_key task to new_key.  References in joins and
+    # queue are updated by rename.  Raises an error if built? or if the
+    # specified task does not exist.
+    def rename(current_key, new_key)
+      if built?
+        raise "cannot rename if built"
+      end
+      
+      # rename task
+      unless task = tasks.delete(current_key)
+        raise "unknown task: #{current_key.inspect}"
+      end
+      tasks[new_key] = task
+      
+      # update join references
+      joins.each do |inputs, outputs, join|
+        inputs.each_index do |index|
+          inputs[index] = new_key if inputs[index] == current_key
+        end
+        
+        outputs.each_index do |index|
+          outputs[index] = new_key if outputs[index] == current_key
+        end
+      end
+      
+      # update queue references, note both array and 
+      # reference-style entries must be handled
+      queue.each_index do |index|
+        if queue[index].kind_of?(Array)
+          if queue[index][0] == current_key
+            queue[index][0] = new_key
+          end
+        else
+          if queue[index] == current_key
+            queue[index] = new_key
+          end
+        end
+      end
+      
+      self
     end
     
     def resolve!
@@ -91,13 +218,13 @@ module Tap
       errors = []
       tasks.each_value do |task|
         unless resolved?(task)
-          errors << "unknown task: #{task.inspect}"
+          errors << "unresolvable task: #{task.inspect}"
         end
       end
       
       joins.each do |inputs, outputs, join|
         unless resolved?(join)
-          errors << "unknown join: #{join.inspect}"
+          errors << "unresolvable join: #{join.inspect}"
         end
         
         inputs.each do |key| 
@@ -125,7 +252,7 @@ module Tap
       
       middleware.each do |m|
         unless resolved?(m)
-          errors << "unknown middleware: #{m}"
+          errors << "unresolvable middleware: #{m.inspect}"
         end
       end
       
@@ -163,11 +290,14 @@ module Tap
       self
     end
     
-    def build!(app)
+    def build!(app, validate=true)
+      validate! if validate
+      
       # instantiate tasks
       tasks.each_pair do |key, task|
         tasks[key] = instantiate(task, app)
       end
+      tasks.freeze
       
       # build the workflow
       joins.collect! do |inputs, outputs, join|
@@ -175,26 +305,47 @@ module Tap
         outputs = outputs.collect {|key| tasks[key] }
         instantiate(join, app).join(inputs, outputs)
       end
+      joins.freeze
       
       # utilize middleware
       middleware.collect! do |middleware|
         instantiate(middleware, app)
       end
+      middleware.freeze
       
       # enque tasks
       queue.each do |(key, inputs)|
         app.enq(tasks[key], *inputs)
       end
+      queue.clear.freeze
+      
+      @app = app
+      self
+    end
+    
+    def built?
+      @app != nil
+    end
+    
+    def enque(key, *inputs)
+      unless built?
+        raise "cannot enque unless built"
+      end
+      
+      unless task = tasks[key]
+        raise "unknown task: #{key.inspect}"
+      end
       
-      tasks
+      app.queue.enq(task, inputs)
+      task
     end
     
     # Creates an hash dump of self.
     def to_hash
-      { 'tasks' => tasks, 
-        'joins' => joins, 
-        'queue' => queue, 
-        'middleware' => middleware
+      { :tasks => tasks, 
+        :joins => joins, 
+        :queue => queue, 
+        :middleware => middleware
       }
     end
     
@@ -202,5 +353,22 @@ module Tap
     def dump(io=nil)
       YAML.dump(to_hash, io)
     end
+    
+    protected
+    
+    # helper to collect all tasks and tasks joined to task
+    def collect_tasks(task, collection=[]) # :nodoc:
+      unless collection.include?(task)
+        collection << task
+        
+        task.joins.each do |join|
+          (join.inputs + join.outputs).each do |input|
+            collect_tasks(input, collection)
+          end
+        end
+      end
+      
+      collection
+    end
   end
 end

data/lib/tap/schema/utils.rb

@@ -1,10 +1,11 @@
 module Tap
   class Schema
     module Utils
+      module_function
       
       def instantiate(data, app)
         case data
-        when Hash  then data['class'].instantiate(symbolize(data), app)
+        when Hash  then data[:class].instantiate(data, app)
         when Array then data.shift.parse!(data, app)
         else raise "cannot instantiate: #{data.inspect}"
         end
@@ -12,7 +13,7 @@ module Tap
       
       def resolved?(data)
         case data
-        when Hash  then data['class'].respond_to?(:instantiate)
+        when Hash  then data[:class].respond_to?(:instantiate)
         when Array then data[0].respond_to?(:parse!)
         else false
         end
@@ -24,7 +25,8 @@ module Tap
         case data
         when Hash
           unless resolved?(data)
-            data['class'] = yield(data['id']) || data['id']
+            data = symbolize(data)
+            data[:class] = yield(data[:id]) || data[:id]
           end
         when Array 
           data[0] = yield(data[0]) || data[0]

data/lib/tap/task.rb

@@ -3,14 +3,28 @@ require 'tap/root'
 require 'tap/env/string_ext'
 
 module Tap
-  module Support
-    autoload(:Templater, 'tap/support/templater')
-  end
-  
   class App
-    # Generates a task initialized to self.
+    # Generates a task with the specified config, initialized to self.
+    #
+    # A block may be provided to overrride the process method; it will be
+    # called with the task instance, plus any inputs.
+    #
+    #   no_inputs = app.task {|task| [] }
+    #   one_input = app.task {|task, input| [input] }
+    #   mixed_inputs = app.task {|task, a, b, *args| [a, b, args] }
+    #
+    #   no_inputs.execute                            # => []
+    #   one_input.execute(:a)                        # => [:a]
+    #   mixed_inputs.execute(:a, :b)                 # => [:a, :b, []]
+    #   mixed_inputs.execute(:a, :b, 1, 2, 3)        # => [:a, :b, [1,2,3]]
+    #
     def task(config={}, klass=Task, &block)
-      klass.intern(config, self, &block)
+      instance = klass.new(config, self)
+      if block_given?
+        instance.extend Intern
+        instance.process_block = block
+      end
+      instance
     end
   end
   
@@ -40,18 +54,6 @@ 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 created with new, or with intern.  Intern overrides process
-  # using a block that receives the task and the inputs.
-  #
-  #   no_inputs = Task.intern {|task| [] }
-  #   one_input = Task.intern {|task, input| [input] }
-  #   mixed_inputs = Task.intern {|task, a, b, *args| [a, b, args] }
-  #
-  #   no_inputs.execute                            # => []
-  #   one_input.execute(:a)                        # => [:a]
-  #   mixed_inputs.execute(:a, :b)                 # => [:a, :b, []]
-  #   mixed_inputs.execute(:a, :b, 1, 2, 3)        # => [:a, :b, [1,2,3]]
-  #
   # === Configuration 
   #
   # Tasks are configurable.  By default each task will be configured as 
@@ -124,47 +126,31 @@ module Tap
     include Configurable
     
     class << self
-      # Returns class dependencies
-      attr_reader :dependencies
-      
-      # Returns or initializes the instance of self cached with app.
-      def instance(app=Tap::App.instance, auto_initialize=true)
-        app.cache[self] ||= (auto_initialize ? new({}, app) : nil)
-      end
-      
       def inherited(child) # :nodoc:
         unless child.instance_variable_defined?(:@source_file)
           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
       
-      # Instantiates a new task with the input arguments and overrides
-      # process with the block.  The block will be called with the task
-      # instance, plus any inputs.
-      #
-      # Simply instantiates a new task if no block is given.
-      def intern(config={}, app=Tap::App.instance, &block) # :yields: task, inputs...
-        instance = new(config, app)
-        if block_given?
-          instance.extend Support::Intern(:process)
-          instance.process_block = block
-        end
-        instance
-      end
-      
       # 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)
-        parse!(argv.dup, app)
+      #
+      # ==== Block Overrides
+      #
+      # For convenience, parse will yield the internal ConfigParser to the
+      # block, if given.  This functionality was added to Task so they are
+      # more flexible in executable files but it is not a part of the API
+      # requirements for parse/parse!.
+      #
+      def parse(argv=ARGV, app=Tap::App.instance, &block) # :yields: opts
+        parse!(argv.dup, app, &block)
       end
       
       # Same as parse, but removes arguments destructively.
-      def parse!(argv=ARGV, app=Tap::App.instance)
+      def parse!(argv=ARGV, app=Tap::App.instance) # :yields: opts
         opts = ConfigParser.new
         
         unless configurations.empty?
@@ -177,12 +163,17 @@ module Tap
         
         # add option to print help
         opts.on("--help", "Print this help") do
-          prg = case $0
-          when /rap$/ then 'rap'
-          else 'tap run --'
+          lines = desc.kind_of?(Lazydoc::Comment) ? desc.wrap(77, 2, nil) : []
+          lines.collect! {|line| "  #{line}"}
+          unless lines.empty?
+            line = '-' * 80
+            lines.unshift(line)
+            lines.push(line)
           end
-          
-          puts "#{help}usage: #{prg} #{to_s.underscore} #{args}"
+
+          puts "#{self}#{desc.empty? ? '' : ' -- '}#{desc.to_s}"
+          puts lines.join("\n")
+          puts "usage: tap run -- #{to_s.underscore} #{args}"
           puts          
           puts opts
           exit
@@ -193,6 +184,8 @@ module Tap
           opts.config.merge!(load_config(config_file))
         end
         
+        yield(opts) if block_given?
+        
         # (note defaults are not added so they will not
         # conflict with string keys from a config file)
         argv = opts.parse!(argv, :add_defaults => false)
@@ -200,45 +193,13 @@ module Tap
         instantiate({:config => opts.nested_config}, app)
       end
       
-      # Instantiates an instance of self and returns an instance of self and
-      # an array of arguments (implicitly to be enqued to the instance).
+      # Instantiates an instance of self and returns an instance of self.
       def instantiate(argh={}, app=Tap::App.instance)
-        config = argh[:config] || {}
-        instance = new(config, app)
-        
-        if argh[:cache]
-          if app.cache.has_key?(self) && app.cache[self] != instance
-            raise "cache already has an instance for: #{self}"
-          end
-        
-          app.cache[self] = instance
-        end
-        
-        instance
-      end
-
-      DEFAULT_HELP_TEMPLATE = %Q{<% desc = task_class::desc %>
-<%= task_class %><%= desc.empty? ? '' : ' -- ' %><%= desc.to_s %>
-
-<% desc = desc.kind_of?(Lazydoc::Comment) ? desc.wrap(77, 2, nil) : [] %>
-<% unless desc.empty? %>
-<%= '-' * 80 %>
-
-<% 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
+        new(argh[:config] || {}, app)
       end
       
       # Recursively loads path into a nested configuration file.
-      def load_config(path)
+      def load_config(path) # :nodoc:
         # optimization to check for trivial paths
         return {} if Root::Utils.trivial?(path)
         
@@ -249,44 +210,6 @@ module Tap
       
       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 shared
-      # instance of A.  The shared instance is specific to an app and can
-      # be accessed through instance(app).
-      #
-      # If a non-nil name is specified, depends_on will create a reader of 
-      # the dependency instance.
-      #
-      #   class A < Tap::Task
-      #   end
-      #
-      #   class B < Tap::Task
-      #     depends_on :a, A
-      #   end
-      #
-      #   app = Tap::App.new
-      #   b = B.new({}, app)
-      #   b.dependencies           # => [A.instance(app)]
-      #   b.a                      # => A.instance(app)
-      #
-      # Returns self.
-      def depends_on(name, dependency_class)
-        unless dependencies.include?(dependency_class)
-          dependencies << dependency_class
-        end
-        
-        if name
-          # returns the resolved result of the dependency
-          define_method(name) do
-            dependency_class.instance(app)
-          end
-        
-          public(name)
-        end
-        
-        self
-      end
-      
       # Defines a task subclass with the specified configurations and process
       # block. During initialization the subclass is instantiated and made
       # accessible through the name method.  
@@ -379,7 +302,6 @@ module Tap
     end
     
     instance_variable_set(:@source_file, __FILE__)
-    instance_variable_set(:@dependencies, [])
     
     lazy_attr :desc, 'task'
     lazy_attr :args, :process
@@ -407,15 +329,9 @@ module Tap
     def initialize(config={}, app=Tap::App.instance)
       @app = app
       @joins = []
-      @dependencies = []
       
       # initialize configs
       initialize_config(config)
-      
-      # setup class dependencies
-      self.class.dependencies.each do |dependency_class|
-        depends_on dependency_class.instance(app)
-      end
     end
     
     # Auditing method call.  Resolves dependencies, executes method_name,
@@ -518,5 +434,12 @@ module Tap
     def inspect
       "#<#{self.class.to_s}:#{object_id} #{config.to_hash.inspect} >"
     end
+    
+    def to_hash
+      {
+        :class => self.class,
+        :config => config.to_hash
+      }
+    end
   end
 end