tap 0.12.4 → 0.17.0

data/lib/tap/support/intern.rb

@@ -1,29 +1,42 @@
 module Tap
   module Support
     
-    # Generates an Intern module for the specified method_name.
+    # Generates an Intern module to override the specified method_name.  Intern
+    # modules are useful to override a tiny bit of functionality without having
+    # to generate a full subclass.
+    #
     # An Intern module:
+    #
     # - adds an accessor for <method_name>_block
-    # - overrides <method_name> to call the block
+    # - overrides <method_name> to call the block, prepending self to
+    #   the input arguments
+    #
+    # For example:
+    #
+    #   array = [1,2,3].extend Intern(:last)
+    #
+    #   array.last             # => 3
+    #   array.last_block = lambda {|arr| arr.first }
+    #   array.last             # => 3
     #
     def self.Intern(method_name)
       mod = INTERN_MODULES[method_name.to_sym]
       return mod unless mod == nil
-      
+
       mod = INTERN_MODULES[method_name.to_sym] = Module.new
       mod.module_eval %Q{
       attr_accessor :#{method_name}_block
 
       def #{method_name}(*inputs)
-        raise "no #{method_name} block set" unless #{method_name}_block
+        return super unless #{method_name}_block
         inputs.unshift(self)
-      
+
         arity = #{method_name}_block.arity
         n = inputs.length
         unless n == arity || (arity < 0 && (-1-n) <= arity) 
           raise ArgumentError.new("wrong number of arguments (\#{n} for \#{arity})")
         end
-      
+
         #{method_name}_block.call(*inputs)
       end
       }

data/lib/tap/support/templater.rb

@@ -121,8 +121,10 @@ module Tap
       end
       
       class << self
-        def build(template,  attributes={})
-          new(template, attributes).build
+        
+        # Builds the erb template with the specified attributes.
+        def build(template,  attributes={}, filename=nil)
+          new(template, attributes, filename).build
         end
       end
       
@@ -163,6 +165,8 @@ module Tap
       end
       
       unless RUBY_VERSION < "1.9"
+        #-- TODO
+        # check if this is still needed...
         def force_encoding(encoding)
           @_erbout.force_encoding(encoding)
           @_erbout
@@ -188,11 +192,12 @@ module Tap
       
       # Build the template.  All methods of self will be 
       # accessible in the template.
-      def build(attrs={})
+      def build(attrs={}, filename=nil)
         attrs.each_pair do |key, value|
           send("#{key}=", value)
         end
         
+        @template.filename = filename
         @template.result(binding)
         @_erbout
       end

data/lib/tap/task.rb

@@ -1,13 +1,22 @@
-autoload(:ConfigParser, 'config_parser')
+require 'tap/joins'
+require 'tap/root'
+require 'tap/env/string_ext'
 
 module Tap
-  autoload(:FileTask, 'tap/file_task')
-  
   module Support
     autoload(:Templater, 'tap/support/templater')
-    autoload(:Intern, 'tap/support/intern')
   end
   
+  class App
+    # Generates a task initialized to self.
+    def task(config={}, klass=Task, &block)
+      klass.intern(config, self, &block)
+    end
+  end
+  
+  # Tasks are nodes that map to the command line.  Tasks provide support for
+  # configuration, documentation, and provide helpers to build workflows.
+  #
   # === Task Definition
   #
   # Tasks specify executable code by overridding the process method in
@@ -31,17 +40,17 @@ 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
-  # using a block that receives the task instance and the inputs.
+  # 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]]
+  #   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 
   #
@@ -80,16 +89,17 @@ module Tap
   #   end 
   #
   #   t = ValidatingTask.new
-  #   t.string = 1           # !> ValidationError
-  #   t.integer = 1.1        # !> ValidationError
+  #   t.string = 1                 # !> ValidationError
+  #   t.integer = 1.1              # !> ValidationError
   #
   #   t.integer = "1"
-  #   t.integer == 1         # => true 
+  #   t.integer == 1               # => true 
   #
   # See the {Configurable}[http://tap.rubyforge.org/configurable/]
   # documentation for more information.
   #
   # === Subclassing
+  #
   # Tasks may be subclassed normally, but be sure to call super as necessary,
   # in particular when overriding the following methods:
   #
@@ -110,29 +120,16 @@ module Tap
   #   end
   #
   class Task
+    include App::Node
     include Configurable
-    include Support::Executable
     
     class << self
       # Returns class dependencies
       attr_reader :dependencies
       
-      # Sets the class default_name
-      attr_writer :default_name
-      
-      # Returns the default name for the class: to_s.underscore
-      def default_name
-        # lazy-setting default_name like this (rather than
-        # within inherited, for example) is an optimization
-        # since many subclass operations end up setting
-        # default_name themselves.
-        @default_name ||= to_s.underscore
-      end
-      
-      # 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.extend(Support::Dependency)
+      # 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:
@@ -146,26 +143,28 @@ module Tap
       end
       
       # Instantiates a new task with the input arguments and overrides
-      # process with the block.  The block will be called with the 
+      # 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(*args, &block) # :yields: task, inputs...
-        instance = new(*args)
+      def intern(config={}, app=Tap::App.instance, &block) # :yields: task, inputs...
+        instance = new(config, app)
         if block_given?
-          instance.extend Support::Intern
+          instance.extend Support::Intern(:process)
           instance.process_block = block
         end
         instance
       end
       
-      # Parses the argv into an instance of self and an array of arguments 
-      # (implicitly to be enqued to the instance).
+      # Parses the argv into an instance of self and an array of arguments
+      # (implicitly to be enqued to the instance).  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)
       end
       
-      # Same as parse, but removes switches destructively.
+      # Same as parse, but removes arguments destructively.
       def parse!(argv=ARGV, app=Tap::App.instance)
         opts = ConfigParser.new
         
@@ -189,51 +188,44 @@ module Tap
           puts opts
           exit
         end
- 
-        # add option to specify the task name
-        name = default_name
-        opts.on('--name NAME', 'Specifies the task name') do |value|
-          name = value
-        end
         
         # 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('--use FILE', 'Loads inputs to ARGV') do |path|
-          use(path, use_args)
+        opts.on('--config FILE', 'Specifies a config file') do |config_file|
+          opts.config.merge!(load_config(config_file))
         end
         
-        # parse!
-        argv = opts.parse!(argv, {}, false)
-        
-        # load configurations
-        config = load_config(config_path)
-        
-        # build and reconfigure the instance
-        instance = new({}, name, app).reconfigure(config).reconfigure(opts.nested_config)
+        # (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
+        }
         
-        [instance, (argv + use_args)]
+        instantiate(argh, app)
       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)
-        instance.execute(*args)
+      # Instantiates an instance of self and returns an instance of self and
+      # an array of arguments (implicitly to be enqued to the instance).
+      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, argh[:args]]
       end
 
-      DEFAULT_HELP_TEMPLATE = %Q{<% manifest = task_class.manifest %>
-<%= task_class %><%= manifest.empty? ? '' : ' -- ' %><%= manifest.to_s %>
+      DEFAULT_HELP_TEMPLATE = %Q{<% desc = task_class::desc %>
+<%= task_class %><%= desc.empty? ? '' : ' -- ' %><%= desc.to_s %>
 
-<% desc = manifest.kind_of?(Lazydoc::Comment) ? manifest.wrap(77, 2, nil) : [] %>
+<% desc = desc.kind_of?(Lazydoc::Comment) ? desc.wrap(77, 2, nil) : [] %>
 <% unless desc.empty? %>
 <%= '-' * 80 %>
 
@@ -253,51 +245,34 @@ module Tap
       # Recursively loads path into a nested configuration file.
       def load_config(path)
         # optimization to check for trivial paths
-        return {} if Root.trivial?(path)
+        return {} if Root::Utils.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.
+      # 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 resolved dependency value.
+      # the dependency instance.
       #
       #   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.
+      #   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)
@@ -305,15 +280,10 @@ module Tap
           dependencies << dependency_class
         end
         
-        # 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
+            dependency_class.instance(app)
           end
         
           public(name)
@@ -322,14 +292,13 @@ module Tap
         self
       end
       
-      # Defines a task subclass with the specified configurations and process block.
-      # During initialization the subclass is instantiated and made accessible 
-      # through a reader by the specified name.  
+      # Defines a task subclass with the specified configurations and process
+      # block. During initialization the subclass is instantiated and made
+      # accessible through the name method.  
       #
-      # Defined tasks may be configured during initialization, through config, or 
-      # directly through the instance; in effect you get tasks with nested configs 
-      # which greatly facilitates workflows.  Indeed, defined tasks are often 
-      # joined in the workflow method.
+      # Defined tasks may be configured during through config, or directly
+      # through the instance; in effect you get tasks with nested configs which
+      # can greatly facilitate workflows.
       #
       #   class AddALetter < Tap::Task
       #     config :letter, 'a'
@@ -341,7 +310,8 @@ module Tap
       #     define :b, AddALetter, {:letter => 'b'}
       #     define :c, AddALetter, {:letter => 'c'}
       #
-      #     def workflow
+      #     def initialize(*args)
+      #       super
       #       a.sequence(b, c)
       #     end
       # 
@@ -394,8 +364,6 @@ module Tap
       def define(name, baseclass=Tap::Task, configs={}, options={}, &block)
         # define the subclass
         subclass = Class.new(baseclass)
-        subclass.default_name = name.to_s
-        
         configs.each_pair do |key, value|
           subclass.send(:config, key, value)
         end
@@ -416,25 +384,34 @@ module Tap
     end
     
     instance_variable_set(:@source_file, __FILE__)
-    instance_variable_set(:@default_name, 'tap/task')
     instance_variable_set(:@dependencies, [])
     
-    lazy_attr :manifest
+    lazy_attr :desc, 'task'
     lazy_attr :args, :process
     lazy_register :process, Lazydoc::Arguments
     
-    # 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. 
-    attr_accessor :name
+    ###############################################################
+    # [depreciated] manifest will be removed at 1.0
+    lazy_attr :manifest
+    def self.desc(resolve=true)
+      comment = const_attrs['task'] ||= self.manifest
+      resolve && comment.kind_of?(Lazydoc::Comment) ? comment.resolve : comment
+    end
+    def self.manifest
+      # :::-
+      #"warn manifest is depreciated, use ::task instead"
+      # :::+
+      const_attrs['manifest'] ||= Lazydoc::Subject.new(nil, lazydoc)
+    end
+    ###############################################################
+    
+    # The App receiving self during enq
+    attr_reader :app
 
     # Initializes a new Task.
-    def initialize(config={}, name=nil, app=App.instance)
-      @name = name || self.class.default_name
+    def initialize(config={}, app=Tap::App.instance)
       @app = app
-      @method_name = :execute_with_callbacks
-      @on_complete_block = nil
+      @joins = []
       @dependencies = []
       
       # initialize configs
@@ -442,10 +419,20 @@ module Tap
       
       # setup class dependencies
       self.class.dependencies.each do |dependency_class|
-        depends_on(dependency_class.instance)
+        depends_on dependency_class.instance(app)
       end
-      
-      workflow
+    end
+    
+    # Auditing method call.  Resolves dependencies, executes method_name,
+    # and sends the audited result to the on_complete_block (if set).
+    #
+    # Returns the audited result.
+    def execute(*inputs)
+      app.dispatch(self, inputs)
+    end
+    
+    def call(*inputs)
+      process(*inputs)
     end
     
     # The method for processing inputs into outputs.  Override this method in
@@ -459,65 +446,82 @@ module Tap
     #     end
     #   end
     #
-    #   t = TaskWithTwoInputs.new
+    #   results = []
+    #   app = Tap::App.new {|result| results << result }
+    #
+    #   t = TaskWithTwoInputs.new({}, app)
     #   t.enq(1,2).enq(3,4)
-    #   t.app.run
-    #   t.app.results(t)         # => [[2,1], [4,3]]
+    #   
+    #   app.run
+    #   results                 # => [[2,1], [4,3]]
     #
     # By default, process simply returns the inputs.
     def process(*inputs)
       inputs
     end
     
-    # Logs the inputs to the application logger (via app.log)
-    def log(action, msg="", level=Logger::INFO)
-      # TODO - add a task identifier?
-      app.log(action, msg, level)
+    # Enqueues self to app with the inputs. The number of inputs provided
+    # should match the number of inputs for the method_name method.
+    def enq(*inputs)
+      app.queue.enq(self, inputs)
+      self
     end
     
-    # Returns self.name
-    def to_s
-      name.to_s
+    # Sets a sequence workflow pattern for the tasks; each task
+    # enques the next task with it's results, starting with self.
+    def sequence(*tasks)
+      options = tasks[-1].kind_of?(Hash) ? tasks.pop : {}
+      
+      current_task = self
+      tasks.each do |next_task|
+        Join.new(options, app).join([current_task], [next_task])
+        current_task = next_task
+      end
     end
-    
-    # Provides an abbreviated version of the default inspect, with only
-    # the task class, object_id, name, and configurations listed.
-    def inspect
-      "#<#{self.class.to_s}:#{object_id} #{name} #{config.to_hash.inspect} >"
+
+    # Sets a fork workflow pattern for self; each target will enque the
+    # results of self.
+    def fork(*targets)
+      options = targets[-1].kind_of?(Hash) ? targets.pop : {}
+      Join.new(options, app).join([self], targets)
     end
-    
-    protected
 
-    # Hook to define a workflow for defined tasks.
-    def workflow
+    # Sets a simple merge workflow pattern for the source tasks. Each 
+    # source enques self with it's result; no synchronization occurs, 
+    # nor are results grouped before being enqued.
+    def merge(*sources)
+      options = sources[-1].kind_of?(Hash) ? sources.pop : {}
+      Join.new(options, app).join(sources, [self])
     end
-    
-    # Hook to execute code before inputs are processed.
-    def before_execute() end
-  
-    # Hook to execute code after inputs are processed.
-    def after_execute() end
 
-    # Hook to handle unhandled errors from processing inputs on a task level.  
-    # By default on_execute_error simply re-raises the unhandled error.
-    def on_execute_error(err)
-      raise err
+    # Sets a synchronized merge workflow for the source tasks.  Results 
+    # from each source are collected and enqued as a single group to
+    # self.  The collective results are not enqued until all sources
+    # have completed.  See Joins::Sync.
+    def sync_merge(*sources)
+      options = sources[-1].kind_of?(Hash) ? sources.pop : {}
+      Joins::Sync.new(options, app).join(sources, [self])
+    end
+
+    # Sets a switch workflow pattern for self.  On complete, switch yields
+    # the result to the block and the block should return the index of the
+    # target to enque with the results. No target will be enqued if the
+    # index is false or nil.  An error is raised if no target can be found
+    # for the specified index. See Joins::Switch.
+    def switch(*targets, &block) # :yields: result
+      options = targets[-1].kind_of?(Hash) ? targets.pop : {}
+      Joins::Switch.new(options, app).join([self], targets, &block)
     end
     
-    private
-    
-    # execute_with_callbacks is the method called by _execute
-    def execute_with_callbacks(*inputs) # :nodoc:
-      before_execute
-      begin
-        result = process(*inputs)
-      rescue
-        on_execute_error($!)
-      end
-      after_execute
-       
-      result
+    # Logs the inputs to the application logger (via app.log)
+    def log(action, msg="", level=Logger::INFO)
+      app.log(action, msg, level)
     end
     
+    # Provides an abbreviated version of the default inspect, with only
+    # the task class, object_id, and configurations listed.
+    def inspect
+      "#<#{self.class.to_s}:#{object_id} #{config.to_hash.inspect} >"
+    end
   end
 end