tap 0.19.0 → 1.3.0

data/lib/tap/app/api.rb

@@ -1,5 +1,4 @@
-require 'configurable'
-require 'tap/signals/help'
+require 'tap/app'
 
 module Tap
   class App
@@ -30,7 +29,7 @@ module Tap
         #
         # The parse method uses parser by default, so subclasses can simply
         # modify parser and ensure parse still works correctly.
-        def parser
+        def parser(app)
           opts = ConfigParser.new
           
           unless configurations.empty?
@@ -42,34 +41,44 @@ module Tap
           opts.separator "options:"
         
           # add option to print help
-          opts.on("-h", "--help", "Print this help") do
-            puts "#{self}#{desc.empty? ? '' : ' -- '}#{desc.to_s}"
-            puts help
-            puts opts
-            exit
+          opts.on("--help", "Print this help") do
+            lines = ["#{self}#{desc.empty? ? '' : ' -- '}#{desc.to_s}"]
+            lines << help
+            lines << "usage: tap #{to_s.underscore} #{respond_to?(:args) ? args : nil}"
+            lines << nil
+            lines << opts
+            raise lines.join("\n")
           end
           
           opts
         end
         
+        def parse(argv=ARGV, app=Tap::App.current, &block)
+          parse!(argv.dup, app, &block)
+        end
+        
         # Parses the argv into an instance of self.  Internally parse parses
         # an argh then calls build, 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 arguments destructively.
-        def parse!(argv=ARGV, app=Tap::App.instance)
-          parser = self.parser
-          argv = parser.parse!(argv, :add_defaults => false)
+        #
+        # Returns the instance.  If a block is given, the instance and any
+        # remaining arguments will be yielded to it.
+        def parse!(argv=ARGV, app=Tap::App.current)
+          parser = self.parser(app)
+          args = parser.parse!(argv, :add_defaults => false)
+          obj = build(convert_to_spec(parser, args), app)
           
-          [build({'config' => parser.nested_config}, app), argv]
+          if block_given?
+            yield(obj, args)
+          else
+            parser.warn_ignored_args(args)
+            obj
+          end
         end
-      
+        
         # Returns an instance of self.  By default build calls new with the
         # configurations specified by spec['config'], and app.
-        def build(spec={}, app=Tap::App.instance)
+        def build(spec={}, app=Tap::App.current)
           new(spec['config'] || {}, app)
         end
       
@@ -85,17 +94,23 @@ module Tap
 
           lines.join("\n")
         end
+        
+        protected
+        
+        def convert_to_spec(parser, args)
+          {'config' => parser.nested_config}
+        end
       end
     
       include Configurable
       include Signals
       
-      signal :help, :class => Help, :bind => nil   # signals help
+      define_signal :help, Help                     # signals help
       
-      # The App receiving self during enq
+      # The app for self
       attr_reader :app
       
-      def initialize(config={}, app=Tap::App.instance)
+      def initialize(config={}, app=Tap::App.current)
         @app = app
         initialize_config(config)
       end
@@ -108,7 +123,13 @@ module Tap
       # config is a stringified representation of the configurations for self.
       def to_spec
         config = self.config.to_hash {|hash, key, value| hash[key.to_s] = value }
-        {'config' => config}
+        config.empty? ? {} : {'config' => config}
+      end
+      
+      # Provides an abbreviated version of the default inspect, with only the
+      # class, object_id, and configurations listed.
+      def inspect
+        "#<#{self.class.to_s}:#{object_id} #{config.to_hash.inspect} >"
       end
     end
   end

data/lib/tap/app/queue.rb

@@ -3,16 +3,16 @@ require 'monitor'
 module Tap
   class App
     
-    # Queue allows thread-safe enqueing and dequeing of nodes and inputs for
+    # Queue allows thread-safe enqueing and dequeing of tasks and inputs for
     # execution.
     #
     # === API
     #
     # The following methods are required in alternative implementations of an
-    # applicaton queue, where a job is a [node, inputs] array:
+    # applicaton queue, where a job is a [task, input] array:
     #
-    #   enq(node, inputs)     # pushes the job onto the queue
-    #   unshift(node, inputs) # unshifts the job onto the queue
+    #   enq(task, input)      # pushes the job onto the queue
+    #   unshift(task, input)  # unshifts the job onto the queue
     #   deq                   # shifts a job off the queue
     #   size                  # returns the number of jobs in the queue
     #   clear                 # clears the queue, returns current jobs
@@ -29,22 +29,21 @@ module Tap
         @queue = []
       end
       
-      # Enqueues the node and inputs as a job.
-      def enq(node, inputs)
+      # Enqueues the task and input.
+      def enq(task, input)
         synchronize do
-          @queue.push [node, inputs]
+          @queue.push [task, input]
         end
       end
       
-      # Enqueues the node and inputs, but to the top of the queue.
-      def unshift(node, inputs)
+      # Enqueues the task and input, but to the top of the queue.
+      def unshift(task, input)
         synchronize do
-          @queue.unshift [node, inputs]
+          @queue.unshift [task, input]
         end
       end
       
-      # Dequeues the next job as an array like [node, inputs]. Returns nil if
-      # the queue is empty.
+      # Dequeues the next job. Returns nil if the queue is empty.
       def deq
         synchronize { @queue.shift }
       end

data/lib/tap/app/stack.rb

@@ -11,13 +11,13 @@ module Tap
         @app = app
       end
       
-      # Checks app for termination and then calls the node with the inputs:
+      # Checks app for termination and then calls the task with the input:
       #
-      #   node.call(*inputs)
+      #   task.call(input)
       #
-      def call(node, inputs)
+      def call(task, input)
         app.check_terminate
-        node.call(*inputs)
+        task.call(input)
       end
     end
   end

data/lib/tap/declarations.rb

@@ -0,0 +1,200 @@
+require 'tap/join'
+require 'tap/workflow'
+require 'tap/declarations/description'
+require 'tap/declarations/context'
+require 'tap/parser'
+require 'tap/tasks/singleton'
+
+module Tap
+  module Declarations
+    def env
+      app.env
+    end
+    
+    # Returns a new node that executes block on call.
+    def node(var=nil, &node) # :yields: *args
+      def node.joins; @joins ||= []; end
+      app.set(var, node) if var
+      node
+    end
+    
+    # Generates a join between the inputs and outputs.  Join resolves the
+    # class using env and initializes a new instance with the configs and
+    # self. 
+    def join(inputs, outputs, config={}, clas=Tap::Join, &block)
+      inputs  = [inputs]  unless inputs.kind_of?(Array)
+      outputs = [outputs] unless outputs.kind_of?(Array)
+      
+      obj = app.init(clas, config, app)
+      obj.join(inputs, outputs, &block)
+      obj
+    end
+    
+    # Sets the description for use by the next task declaration.
+    def desc(str)
+      @desc = Lazydoc.register_caller(Description)
+      @desc.desc = str
+      @desc
+    end
+    
+    def singleton(&block)
+      baseclass(Tap::Tasks::Singleton, &block)
+    end
+    
+    def baseclass(baseclass=Tap::Task)
+      current = @baseclass
+      begin
+        @baseclass = env.constant(baseclass) unless baseclass.nil?
+        yield if block_given?
+      ensure
+        @baseclass = current if block_given?
+      end
+    end
+    
+    # Nests tasks within the named module for the duration of the block.
+    # Namespaces may be nested.
+    def namespace(namespace)
+      current = @namespace
+      begin
+        unless namespace.nil? || namespace.kind_of?(Module)
+          const_name = namespace.to_s.camelize
+          unless current.const_defined?(const_name)
+            current.const_set(const_name, Module.new)
+          end
+          namespace = current.const_get(const_name)
+        end
+        
+        @namespace = namespace unless namespace.nil?
+        yield if block_given?
+      ensure
+        @namespace = current if block_given?
+      end
+    end
+    
+    def declare(baseclass, const_name, configs={}, &block)
+      const_name = const_name.to_s.camelize
+      subclass = Class.new(env.constant(baseclass))
+      @namespace.const_set(const_name, subclass)
+      
+      # define configs
+      configs.each_pair do |key, value|
+        # specifying a desc prevents lazydoc registration of these lines
+        opts = {:desc => ""}
+        opts[:short] = key if key.to_s.length == 1
+        config_block = Configurable::Validation.guess(value)
+        subclass.send(:config, key, value, opts, &config_block)
+      end
+      
+      # define process
+      if block
+        # determine arity, correcting for the self arg
+        arity = block.arity
+        arity -= arity > 0 ? 1 : -1
+        signature = Array.new(arity < 0 ? arity.abs - 1 : arity, 'arg')
+        signature << '*args' if arity < 0
+        
+        # prevents assessment of process args by lazydoc
+        subclass.const_attrs[:process] = signature.join(' ')
+        subclass.send(:define_method, :process) do |*args|
+          block.call(self, *args)
+        end
+      end
+      
+      # register documentation
+      constant = env.set(subclass, nil)
+      
+      if @desc
+        subclass.desc = @desc
+        constant.register_as(subclass.type, @desc)
+        @desc = nil
+      end
+      
+      subclass
+    end
+    
+    def task(const_name, configs={}, baseclass=@baseclass, &block)
+      @desc ||= Lazydoc.register_caller(Description)
+      const_name, prerequisites = parse_prerequisites(const_name)
+
+      if prerequisites.nil?
+        return declare(baseclass, const_name, configs, &block)
+      end
+
+      tasc = declare(Tap::Workflow, const_name, configs) do |workflow|
+        psr = Parser.new
+        args = psr.parse!(prerequisites)
+        warn "ignoring args: #{args.inspect}" unless args.empty?
+        psr.build_to(app)
+        
+        obj = init("#{const_name.to_s.underscore}/task", workflow.config.to_hash)
+        setup = lambda {|input| exe(obj, input) }
+        
+        [setup, obj]
+      end
+
+      namespace(const_name) do
+        declare(baseclass, 'Task', configs, &block)
+      end
+
+      tasc
+    end
+
+    def work(const_name, definition, configs={}, baseclass=Tap::Workflow, &block)
+      unless definition.kind_of?(String)
+        raise "workflow definition must be a string: #{definition.inspect}"
+      end
+      
+      @desc ||= Lazydoc.register_caller(Description)
+      block ||= lambda {|config| node(0) }
+      task({const_name => definition}, configs, baseclass, &block)
+    end
+    
+    protected
+    
+    def initialize_declare(baseclass=Tap::Task, namespace=Object)
+      @desc = nil
+      @baseclass = baseclass
+      @namespace = namespace
+    end
+
+    private
+
+    def parse_prerequisites(const_name)
+      prerequisites = nil
+
+      if const_name.is_a?(Hash)
+        hash = const_name
+        case hash.length
+        when 0
+          const_name = nil
+        when 1
+          const_name = hash.keys[0]
+          prerequisites = hash[const_name]
+        else
+          raise ArgumentError, "multiple task names specified: #{hash.keys.inspect}"
+        end
+      end
+
+      if const_name.nil?
+        raise ArgumentError, "no constant name specified"
+      end
+      
+      case prerequisites
+      when nil
+      when String
+        prerequisites = Utils.shellsplit(prerequisites)
+      when Array
+        argv = []
+        prerequisites.each do |prereq|
+          argv << '-!'
+          argv << prereq.to_s
+        end
+        prerequisites = argv
+      else
+        prerequisites = ['-!', prerequisites.to_s]
+      end
+      
+      [const_name, prerequisites]
+    end
+  end
+end

data/lib/tap/declarations/context.rb

@@ -0,0 +1,31 @@
+module Tap
+  module Declarations
+    class Context
+      include Declarations
+      include Tap::Utils
+      
+      attr_reader :app
+      
+      def initialize(app, ns=nil)
+        @app = app
+        initialize_declare
+        namespace(ns)
+      end
+      
+      # Runs the command with system and raises an error if the command
+      # fails.
+      def sh(*cmd)
+        app.log :sh, cmd.join(' ')
+        system(*cmd) or raise "Command failed with status (#{$?.exitstatus}): [#{cmd.join(' ')}]"
+      end
+      
+      def node(num)
+        app.get(num.to_s)
+      end
+      
+      def method_missing(sym, *args, &block)
+        app.send(sym, *args, &block)
+      end
+    end
+  end
+end

data/lib/tap/declarations/description.rb

@@ -0,0 +1,33 @@
+module Tap
+  module Declarations
+    # :startdoc:::-
+    # A special type of Lazydoc::Comment designed to handle the comment syntax
+    # for task declarations.
+    #
+    # Description instances can be assigned a description, or they may parse
+    # one directly from the comment.  Comment lines with the constant attribute
+    # '::' will have the value set as desc.
+    # :startdoc:::+
+    class Description < Lazydoc::Comment
+    
+      # The description for self.
+      attr_accessor :desc
+    
+      # Parses in-comment descriptions from prepended lines, if present.
+      def prepend(line)
+        if line =~ /\s::(?:\s+(.*?)\s*)?$/
+          self.desc = $1.to_s
+          false
+        else
+          super
+        end
+      end
+    
+      # Resolves and returns the description.
+      def to_s
+        resolve
+        desc.to_s
+      end
+    end
+  end
+end