tap 0.19.0 → 1.3.0

data/lib/tap/signals.rb

@@ -1,4 +1,7 @@
 require 'tap/signals/module_methods'
+require 'tap/signals/configure'
+require 'tap/signals/help'
+require 'tap/signals/load'
 
 module Tap
   
@@ -8,9 +11,16 @@ module Tap
   # commonly produce a parameters hash.
   #
   module Signals
+    def signals
+      # memoization here is tempting, but a bad idea because the signals must
+      # be recalculated in case of added modules.  see cache_signals for a
+      # better way.
+      self.class.signals
+    end
+    
     def signal(sig, &block)
       sig = sig.to_s
-      unless signal = self.class.signals[sig]
+      unless signal = signals[sig]
         raise "unknown signal: #{sig} (#{self.class})"
       end
       
@@ -19,7 +29,15 @@ module Tap
     
     def signal?(sig)
       sig = sig.to_s
-      self.class.signals.has_key?(sig.to_s)
+      signals.has_key?(sig.to_s)
+    end
+    
+    def sig(signal)
+      signal = signal.class
+      signals.each_pair do |sig, value|
+        return sig if value == signal
+      end
+      nil
     end
   end
 end

data/lib/tap/signals/class_methods.rb

@@ -1,4 +1,5 @@
-require 'tap/signals/signal'
+require 'tap/signal'
+require 'configurable'
 
 module Tap
   module Signals
@@ -69,16 +70,15 @@ module Tap
       # A block may also be provided to pre-process the argv before it is sent
       # to the method; the block return is sent to the method (and so should
       # be an argv).
-      def signal(sig, opts={}) # :yields: sig, argv
+      def signal(sig, opts={}, &block) # :yields: sig, argv
         signature = opts[:signature] || []
         remainder = opts[:remainder] || false
+        opts[:caller_index] ||= 2
         
-        signal = define_signal(sig, opts) do |args|
+        define_signal(sig, opts) do |args|
           argv = convert_to_array(args, signature, remainder)
-          block_given? ? yield(self, argv) : argv
+          block ? block.call(self, argv) : argv
         end
-        
-        register_signal(sig, signal, opts)
       end
       
       # Defines a signal to call a method that receives a single hash as an
@@ -88,24 +88,42 @@ module Tap
       # A block may also be provided to pre-process the hash before it is sent
       # to the method; the block return is sent to the method (and so should
       # be a hash).
-      def signal_hash(sig, opts={}) # :yields: sig, argh
+      def signal_hash(sig, opts={}, &block) # :yields: sig, argh
         signature = opts[:signature] || []
         remainder = opts[:remainder]
+        opts[:caller_index] ||= 2
         
-        signal = define_signal(sig, opts) do |args|
+        define_signal(sig, opts) do |args|
           argh = convert_to_hash(args, signature, remainder)
-          [block_given? ? yield(self, argh) : argh]
+          [block ? block.call(self, argh) : argh]
         end
-        
-        register_signal(sig, signal, opts)
       end
       
-      def signal_class(sig, signal_class=Signal, opts={}, &block) # :yields: sig, argv
+      def define_signal(sig, opts=nil, &block) # :yields: args
+        unless opts.kind_of?(Hash)
+          opts = {:class => opts, :bind => false}
+        end
+        
+        # generate a subclass of signal
+        klass = opts[:class] || Signal
+        signal = Class.new(klass)
+        
+        # bind the new signal
+        method_name = opts.has_key?(:bind) ? opts[:bind] : sig
+        if method_name
+          signal.send(:define_method, :call) do |args|
+            args = process(args)
+            obj.send(method_name, *args, &self.block)
+          end
+        end
+        
         if block_given?
-          signal = Class.new(signal_class)
-          signal.class_eval(&block)
-        else
-          signal = signal_class
+          signal.send(:define_method, :process, &block)
+        end
+        
+        if signal.respond_to?(:desc=)
+          caller_index = opts[:caller_index] || 1
+          signal.desc ||= Lazydoc.register_caller(Lazydoc::Trailer, caller_index)
         end
         
         register_signal(sig, signal, opts)
@@ -161,32 +179,7 @@ module Tap
         super
       end
       
-      def define_signal(sig, opts={}, &block) # :nodoc:
-        # generate a subclass of signal
-        klass = opts[:class] || Signal
-        signal = Class.new(klass)
-        
-        # bind the new signal
-        method_name = opts.has_key?(:bind) ? opts[:bind] : sig
-        if method_name
-          signal.send(:define_method, :call) do |args|
-            args = process(args)
-            obj.send(method_name, *args, &self.block)
-          end
-        end
-        
-        if block_given?
-          signal.send(:define_method, :process, &block)
-        end
-        
-        signal
-      end
-      
       def register_signal(sig, signal, opts={}) # :nodoc:
-        if signal.respond_to?(:desc=)
-          signal.desc ||= Lazydoc.register_caller(Lazydoc::Trailer, 2)
-        end
-        
         signal_registry[sig.to_s] = signal
         cache_signals(@signals != nil)
         
@@ -195,8 +188,10 @@ module Tap
           const_name = opts.has_key?(:const_name) ? opts[:const_name] : sig.to_s.capitalize
           const_name = const_name.to_s
           
-          if const_name =~ /\A[A-Z]\w*\z/ && !const_defined?(const_name)
-            const_set(const_name, signal)
+          if const_name =~ /\A[A-Z]\w*\z/
+            unless const_defined?(const_name) && const_get(const_name) == signal
+              const_set(const_name, signal)
+            end
           end
         end
         

data/lib/tap/signals/configure.rb

@@ -0,0 +1,19 @@
+module Tap
+  module Signals
+    class Configure < Signal
+      def call(config)
+        if config.kind_of?(Array)
+          psr = ConfigParser.new(:add_defaults => false)
+          psr.add(obj.class.configurations)
+          args = psr.parse!(config)
+          psr.warn_ignored_args(args)
+          
+          config = psr.config
+        end
+        
+        obj.reconfigure(config)
+        obj.config
+      end
+    end
+  end
+end

data/lib/tap/signals/help.rb

@@ -1,12 +1,10 @@
-require 'tap/signals'
-
 module Tap
   module Signals
     class Help < Signal
       
-      def call(args)
-        argv = convert_to_array(args, ['sig'])
-        argv.empty? ? list : desc(*argv)
+      def call(input)
+        args = convert_to_array(input, ['sig'])
+        args.empty? ? list : process(*args)
       end
       
       def list
@@ -22,10 +20,10 @@ module Tap
           lines << "  /#{key.ljust(width)}#{desc}"
         end
         
-        "signals: (#{obj.class})\n#{lines.join("\n")}"
+        "signals (#{obj.class})\n#{lines.join("\n")}"
       end
       
-      def desc(sig)
+      def process(sig)
         clas = obj.signal(sig).class
         
         if clas.respond_to?(:desc)

data/lib/tap/signals/load.rb

@@ -0,0 +1,49 @@
+require 'tap/utils'
+
+module Tap
+  module Signals
+    class Load < Signal
+      include Utils
+      
+      def call(args)
+        args.each {|path| process(path) }
+        obj
+      end
+      
+      def process(path)
+        if File.exists?(path)
+          File.open(path) do |io|
+            each_signal(io) do |sig, args|
+              obj.signal(sig).call(args)
+            end
+          end
+        end
+        
+        obj
+      end
+      
+      def each_signal(io)
+        offset = -1 * ($/.length + 1)
+
+        carryover = nil
+        io.each_line do |line|
+          if line[offset] == ?\\
+            carryover ||= []
+            carryover << line[0, line.length + offset]
+            carryover << $/
+            next
+          end
+
+          if carryover
+            carryover << line
+            line = carryover.join
+            carryover = nil
+          end
+
+          sig, *args = shellsplit(line)
+          yield(sig, args) if sig
+        end
+      end
+    end
+  end
+end

data/lib/tap/signals/module_methods.rb

@@ -7,6 +7,7 @@ module Tap
     
       # Extends including classes with Configurable::ClassMethods
       def included(base)
+        super
         base.extend ClassMethods
         base.extend ModuleMethods unless base.kind_of?(Class)
 

data/lib/tap/task.rb

@@ -1,58 +1,10 @@
-require 'tap/joins'
-require 'tap/root'
+require 'tap/app/api'
 
 module Tap
-  class App
-    # 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)
-      instance = klass.new(config, self)
-      if block_given?
-        instance.extend Intern
-        instance.process_block = block
-      end
-      instance
-    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
-  # subclasses. The number of inputs to process corresponds to the inputs
-  # given to execute or enq.
-  #
-  #   class NoInput < Tap::Task
-  #     def process(); []; end
-  #   end
-  #
-  #   class OneInput < Tap::Task
-  #     def process(input); [input]; end
-  #   end
-  #
-  #   class MixedInputs < Tap::Task
-  #     def process(a, b, *args); [a,b,args]; end
-  #   end
-  #
-  #   NoInput.new.execute                          # => []
-  #   OneInput.new.execute(:a)                     # => [:a]
-  #   MixedInputs.new.execute(:a, :b)              # => [:a, :b, []]
-  #   MixedInputs.new.execute(:a, :b, 1, 2, 3)     # => [:a, :b, [1,2,3]]
-  #
   # === Configuration 
   #
   # Tasks are configurable.  By default each task will be configured as 
@@ -121,263 +73,77 @@ module Tap
   #   end
   #
   class Task < App::Api
-    include App::Node
-    
     class << self
-      
-      def parser
+      def parser(app)
         opts = super
         
-        # add option to print help
-        opts.on!("--help", "Print this help") do
-          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 "#{self}#{desc.empty? ? '' : ' -- '}#{desc.to_s}"
-          puts help
-          puts "usage: tap run -- #{to_s.underscore} #{args}"
-          puts          
-          puts opts
-          exit
-        end
-        
-        opts.on('--enque', 'Manually enques self') do
-          opts['enque'] = true
-        end
-        
         # add option to specify a config file
         opts.on('--config FILE', 'Specifies a config file') do |config_file|
-          opts.config.merge!(load_config(config_file))
+          configs = Configurable::Utils.load_file(config_file, true)
+          opts.config.merge!(configs)
         end
         
         opts
       end
-      
-      # Same as parse, but removes arguments destructively.
-      def parse!(argv=ARGV, app=Tap::App.instance)
-        parser = self.parser
-        
-        # (note defaults are not added so they will not
-        # conflict with string keys from a config file)
-        argv = parser.parse!(argv, :add_defaults => false)
-        enque = parser.config.delete('enque')
-        instance = build({'config' => parser.nested_config}, app)
-        
-        instance.enq(*argv) if enque
-        [instance, argv]
-      end
-      
-      # Recursively loads path into a nested configuration file.
-      def load_config(path) # :nodoc:
-        # optimization to check for trivial paths
-        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
-      
-      protected
-      
-      # 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 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'
-      #     def process(input); input << letter; end
-      #   end
-      #
-      #   class AlphabetSoup < Tap::Task
-      #     define :a, AddALetter, {:letter => 'a'}
-      #     define :b, AddALetter, {:letter => 'b'}
-      #     define :c, AddALetter, {:letter => 'c'}
-      #
-      #     def initialize(*args)
-      #       super
-      #       a.sequence(b, c)
-      #     end
-      # 
-      #     def process
-      #       a.execute("")
-      #     end
-      #   end
-      #
-      #   AlphabetSoup.new.process            # => 'abc'
-      #
-      #   i = AlphabetSoup.new(:a => {:letter => 'x'}, :b => {:letter => 'y'}, :c => {:letter => 'z'})
-      #   i.process                           # => 'xyz'
-      #
-      #   i.config[:a] = {:letter => 'p'}
-      #   i.config[:b][:letter] = 'q'
-      #   i.c.letter = 'r'
-      #   i.process                           # => 'pqr'
-      #
-      # ==== Usage
-      #
-      # Define is basically the equivalent of:
-      #
-      #   class Sample < Tap::Task
-      #     Name = baseclass.subclass(config, &block)
-      #     
-      #     # accesses an instance of Name
-      #     attr_reader :name
-      #
-      #     # register name as a config, but with a
-      #     # non-standard reader and writer
-      #     config :name, {}, {:reader => :name_config, :writer => :name_config=}.merge(options)
-      #
-      #     # reader for name.config
-      #     def name_config; ...; end
-      #
-      #     # reconfigures name with input
-      #     def name_config=(input); ...; end
-      #
-      #     def initialize(*args)
-      #       super
-      #       @name = Name.new(config[:name])
-      #     end
-      #   end
-      #
-      # Note the following:
-      # * define will set a constant like name.camelize
-      # * the block defines the process method in the subclass
-      # * three methods are created by define: name, name_config, name_config=
-      #
-      def define(name, baseclass=Tap::Task, configs={}, options={}, &block)
-        # define the subclass
-        subclass = Class.new(baseclass)
-        configs.each_pair do |key, value|
-          subclass.send(:config, key, value)
-        end
-        
-        if block_given?
-          # prevent lazydoc registration of the process method
-          subclass.registered_methods.delete(:process)
-          subclass.send(:define_method, :process, &block)
-        end
-        
-        # register documentation
-        # TODO: register subclass in documentation
-        options[:desc] ||= Lazydoc.register_caller(Lazydoc::Trailer, 1)
-        
-        # add the configuration
-        nest(name, subclass, {:const_name => name.to_s.camelize}.merge!(options))
-      end
     end
     
+    # An array of joins for self
+    attr_reader :joins
+    
+    signal :enq                    # enque self
+    signal :exe                    # execute self
+    
     lazy_attr :args, :process
     lazy_register :process, Lazydoc::Arguments
     
-    signal :enq
-    
-    # Initializes a new Task.
-    def initialize(config={}, app=Tap::App.instance)
+    def initialize(config={}, app=Tap::App.current)
+      @app = app
       @joins = []
-      super
-    end
-    
-    def associations
-      [nil, joins]
-    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)
+      initialize_config(config)
     end
     
-    def call(*inputs)
-      process(*inputs)
+    # Call splats the input to process and exists to provide subclasses
+    # a way to wrap process behavior.
+    def call(input)
+      process(*input)
     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
-    # the task should have when enqued or executed.  
-    #
+    # The method for processing inputs into outputs. Override this method in
+    # subclasses to provide class-specific process logic. The arguments given
+    # to enq/exe should correspond to the arguments required by process. The
+    # process return is the result passed to joins.
+    #    
     #   class TaskWithTwoInputs < Tap::Task
     #     def process(a, b)
     #       [b,a]
     #     end
     #   end
-    #
+    #   
     #   results = []
-    #   app = Tap::App.new {|result| results << result }
+    #   app = Tap::App.new
     #
-    #   t = TaskWithTwoInputs.new({}, app)
-    #   t.enq(1,2).enq(3,4)
-    #   
+    #   task = TaskWithTwoInputs.new({}, app)
+    #   task.enq(1,2).enq(3,4)
+    #   task.on_complete {|result| results << result }
+    #    
     #   app.run
     #   results                 # => [[2,1], [4,3]]
-    #
+    #    
     # By default, process simply returns the inputs.
     def process(*inputs)
       inputs
     end
     
-    # 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
+    # Enques self with an array of inputs (directly use app.enq to enque with
+    # a non-array input, or override in a subclass).
+    def enq(*args)
+      app.enq(self, args)
     end
     
-    # 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
-
-    # 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
-
-    # 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
-
-    # 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)
+    # Executes self with an array of inputs (directly use app.exe to execute
+    # with a non-array input, or override in a subclass).
+    def exe(*args)
+      app.exe(self, args)
     end
     
     # Logs the inputs to the application logger (via app.log)
@@ -385,10 +151,15 @@ module Tap
       app.log(action, msg, level) { yield }
     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} >"
+    # Sets the block as a join for self.
+    def on_complete(&block) # :yields: result
+      joins << block if block
+      self
+    end
+    
+    # Returns the associations array: [nil, joins]
+    def associations
+      [nil, joins]
     end
   end
 end