tap 0.17.1 → 0.18.0

data/doc/Examples/Workflow

@@ -2,7 +2,7 @@
 
 === Sequence
 
-A simple sequence using the --: syntax that joins the previous to next task.
+A simple sequence using the --: syntax.
 
   % tap run -- load 'goodnight moon' --: dump
   goodnight moon

data/lib/tap.rb

@@ -1,5 +1,5 @@
 lib = File.expand_path(File.dirname(__FILE__))
 $:.unshift(lib) unless $:.include?(lib)
 
-require 'tap/constants'
+require 'tap/version'
 require 'tap/exe'

data/lib/tap/app.rb

@@ -4,7 +4,6 @@ require 'tap/app/node'
 require 'tap/app/state'
 require 'tap/app/stack'
 require 'tap/app/queue'
-require 'tap/schema'
 
 module Tap
   
@@ -94,26 +93,6 @@ module Tap
   # 
   # Middleware can be nested with multiple calls to use.
   #
-  # === Dependencies
-  #
-  # Nodes allow the construction of dependency-based workflows.  A node only
-  # executes after its dependencies have been resolved (ie executed).
-  #
-  #   runlist = []
-  #   n0 = app.node { runlist << 0 }
-  #   n1 = app.node { runlist << 1 }
-  #
-  #   n0.depends_on(n1)
-  #   app.enq(n0)
-  #
-  #   app.run
-  #   runlist                        # => [1, 0]
-  #
-  # Dependencies are resolved <em>every time</em> a node executes; individual
-  # dependencies can implement single-execution if desired.  Dependencies are
-  # not resolved with arguments, ie dependency nodes must be able to execute
-  # without inputs.
-  #
   class App
     class << self
       # Sets the current app instance
@@ -148,8 +127,7 @@ module Tap
     # The application queue
     attr_reader :queue
     
-    # A cache of application-specific data.  Internally used to store class
-    # instances of tasks.  Not recommended for casual use.
+    # A cache of application-specific data.
     attr_reader :cache
     
     # The default joins for nodes that have no joins set
@@ -171,7 +149,6 @@ module Tap
       @stack = options[:stack] || Stack.new(self)
       @queue = options[:queue] || Queue.new
       @cache = options[:cache] || {}
-      @trace = []
       @default_joins = []
       on_complete(&block)
       
@@ -220,27 +197,24 @@ module Tap
     
     # Adds the specified middleware to the stack.
     def use(middleware, *argv)
-      @stack = middleware.new(@stack, *argv)
+      synchronize do
+        @stack = middleware.new(@stack, *argv)
+      end
     end
     
-    def build(schema, options={})
-      unless schema.kind_of?(Schema)
-        schema = Schema.new(schema)
-      end
+    # Returns an array of middlware in use by self.
+    def middleware
+      middleware = []
       
-      if resources = options[:resources]
-        schema.resolve! do |type, id|
-          resources[type][id]
+      synchronize do
+        current = stack
+        until current.kind_of?(Stack)
+          middleware << current
+          current = current.stack
         end
       end
       
-      schema.validate!
-      
-      if options[:clean]
-        reset
-      end
-      
-      schema.build!(self)
+      middleware
     end
     
     # Clears the cache, the queue, and resets the stack so that no middleware
@@ -257,36 +231,6 @@ module Tap
       end
     end
     
-    # Dispatches each dependency of node.  A block can be given to do something
-    # else with the nodes (ex: reset single-execution dependencies).  Resolve
-    # will recursively yield dependencies if specified.
-    #
-    # Resolve raises an error for circular dependencies.
-    def resolve(node, recursive=false, &block)
-      node.dependencies.each do |dependency|
-        if @trace.include?(dependency)
-          @trace.push dependency
-          raise DependencyError.new(@trace)
-        end
-
-        # mark the results at the index to prevent
-        # infinite loops with circular dependencies
-        @trace.push dependency
-        
-        if recursive
-          resolve(dependency, recursive, &block)
-        end
-        
-        if block_given?
-          yield(dependency)
-        else
-          dispatch(dependency)
-        end
-        
-        @trace.pop
-      end
-    end
-    
     # Dispatches node to the application stack with the inputs.
     def execute(node, *inputs)
       dispatch(node, inputs)
@@ -295,13 +239,11 @@ module Tap
     # Dispatch sends the node into the application stack with the inputs.
     # Dispatch does the following in order:
     #
-    # - resolve node dependencies using resolve_dependencies
     # - call stack with the node and inputs
     # - call the node joins, if set, or the default_joins with the results
     #
     # Dispatch returns the node result.
     def dispatch(node, inputs=[])
-      resolve(node)
       result = stack.call(node, inputs)
       
       joins = node.joins.empty? ? default_joins : node.joins
@@ -430,8 +372,8 @@ module Tap
       target
     end
     
-    # Sets the block to receive the audited result of nodes with no join
-    # (ie the block is set as default_join).
+    # Sets the block to receive the result of nodes with no joins
+    # (ie the block is set as a default_join).
     def on_complete(&block) # :yields: _result
       self.default_joins << block if block
       self
@@ -443,12 +385,5 @@ module Tap
     # called on an running App.  They are handled by the run rescue code.
     class TerminateError < RuntimeError
     end
-    
-    # Raised when Tap::App#resolve detects a circular dependency.
-    class DependencyError < StandardError
-      def initialize(trace)
-        super "circular dependency: [#{trace.join(', ')}]"
-      end
-    end
   end
 end

data/lib/tap/app/node.rb

@@ -9,9 +9,6 @@ module Tap
       # The joins called when call completes
       attr_accessor :joins
       
-      # An array of node dependencies
-      attr_reader :dependencies
-      
       # Interns a new node by extending the block with Node. 
       def self.intern(&block)
         block.extend self
@@ -20,7 +17,6 @@ module Tap
       # Sets up required variables for extended objects.
       def self.extended(obj) # :nodoc:
         obj.instance_variable_set(:@joins, [])
-        obj.instance_variable_set(:@dependencies, [])
       end
       
       # Sets the block as a join for self.
@@ -28,16 +24,6 @@ module Tap
         self.joins << block if block
         self
       end
-      
-      # Adds the dependency to self.  Dependencies are resolved by an app
-      # during App#dispatch and must be valid nodes.
-      def depends_on(dependency)
-        raise "cannot depend on self" if dependency == self
-        unless dependencies.include?(dependency)
-          dependencies << dependency
-        end
-        self
-      end
     end
   end
 end

data/lib/tap/env.rb

@@ -1,6 +1,6 @@
 require 'tap/root'
 require 'tap/env/manifest'
-require 'tap/support/templater'
+require 'tap/templater'
 autoload(:YAML, 'yaml')
 
 module Tap
@@ -65,7 +65,7 @@ module Tap
         end
       end
       
-      def scan(load_path, pattern='**/*.rb')
+      def scan_dir(load_path, pattern='**/*.rb')
         Dir.chdir(load_path) do 
           Dir.glob(pattern).each do |require_path|
             next unless File.file?(require_path)
@@ -73,15 +73,9 @@ module Tap
             default_const_name = require_path.chomp('.rb').camelize
             
             # note: the default const name has to be set here to allow for implicit
-            # constant attributes (because a dir is needed to figure the relative path).
-            # A conflict could arise if the same path is globed from two different
-            # dirs... no surefire solution.
-            document = Lazydoc[require_path]
-            case document.default_const_name
-            when nil then document.default_const_name = default_const_name
-            when default_const_name
-            else raise "found a conflicting default const name"
-            end
+            # constant attributes. An error can arise if the same path is globed
+            # from two different dirs... no surefire solution.
+            Lazydoc[require_path].default_const_name = default_const_name
             
             # scan for constants
             Lazydoc::Document.scan(File.read(require_path)) do |const_name, type, comment|
@@ -100,6 +94,27 @@ module Tap
           end
         end
       end
+      
+      def scan(path, key='[a-z_]+')
+        Lazydoc::Document.scan(File.read(path), key) do |const_name, type, comment|
+          if const_name.empty?
+            unless const_name = Lazydoc[path].default_const_name
+              raise "could not determine a constant name for #{type} in: #{path.inspect}"
+            end
+          end
+          
+          constant = Constant.new(const_name, path, comment)
+          yield(type, constant)
+          
+          ###############################################################
+          # [depreciated] manifest as a task key will be removed at 1.0
+          if type == 'manifest'
+            warn "depreciation: ::task should be used instead of ::manifest as a resource key (#{require_path})"
+            yield('task', constant)
+          end
+          ###############################################################
+        end
+      end
     end
     self.instance = nil
     
@@ -441,9 +456,8 @@ module Tap
         load_paths.each do |load_path|
           next unless File.directory?(load_path)
           
-          Env.scan(load_path) do |type, constant|
-            entries = registry[type.to_sym] ||= []
-            entries << constant
+          Env.scan_dir(load_path) do |type, constant|
+            (registry[type.to_sym] ||= []) << constant
           end
         end
         
@@ -468,6 +482,15 @@ module Tap
       builders[type] = block
     end
     
+    #--
+    # Potential bug, constants can be added twice.
+    def scan(path, key='[a-z_]+')
+      registry = self.registry
+      Env.scan(path, key) do |type, constant|
+        (registry[type.to_sym] ||= []) << constant
+      end
+    end
+    
     def manifest(type) # :yields: env
       type = type.to_sym
       
@@ -488,9 +511,11 @@ module Tap
       registries.clear
     end
     
-    #--
-    # Environment-seek
-    def eeek(type, key)
+    # Searches across each for the first registered object minimatching key. A
+    # single env can be specified by using a compound key like 'env_key:key'.
+    #
+    # Returns nil if no matching object is found.
+    def seek(type, key, value_only=true)
       key =~ COMPOUND_KEY
       envs = if $2
         # compound key, match for env
@@ -504,21 +529,24 @@ module Tap
       # traverse envs looking for the first
       # manifest entry matching key
       envs.each do |env|
-        if result = env.manifest(type).minimatch(key)
-          return [env, result]
+        if value = env.manifest(type).minimatch(key)
+          return value_only ? value : [env, value]
         end
       end
     
       nil
     end
     
-    # Searches across each for the first registered object minimatching key. A
-    # single env can be specified by using a compound key like 'env_key:key'.
-    #
-    # Returns nil if no matching object is found.
-    def seek(type, key, &block) # :yields: env, key
-      env, result = eeek(type, key, &block)
-      result
+    def reverse_seek(type, key_only=true, &block)
+      each do |env|
+        manifest = env.manifest(type)
+        if value = manifest.find(&block)
+          key = manifest.minihash(true)[value]
+          return key_only ? key : "#{minihash(true)[env]}:#{key}"
+        end
+      end
+    
+      nil
     end
     
     # All templaters are yielded to the block before any are built.  This
@@ -530,7 +558,7 @@ module Tap
       
       env_keys = minihash(true)
       collect do |env|
-        templater = Support::Templater.new(template, :env => env, :env_key => env_keys[env])
+        templater = Templater.new(template, :env => env, :env_key => env_keys[env])
         yield(templater, globals) if block_given? 
         templater
       end.collect! do |templater|

data/lib/tap/env/manifest.rb

@@ -43,8 +43,8 @@ module Tap
       # env can be specified by using a compound key like 'env_key:key'.
       #
       # Returns nil if no matching entry is found.
-      def seek(key)
-        env.seek(type, key)
+      def seek(key, value_only=true)
+        env.seek(type, key, value_only)
       end
       
       def [](key)

data/lib/tap/intern.rb

@@ -0,0 +1,50 @@
+module Tap
+  # 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, 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)
+      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
+    }
+    mod
+  end
+  
+  # An array of already-declared intern modules,
+  # keyed by method_name.
+  INTERN_MODULES = {}
+  
+  # An Intern module for :process.
+  Intern = Tap::Intern(:process)
+end

data/lib/tap/join.rb

@@ -1,5 +1,5 @@
 require 'tap/app'
-require 'tap/support/intern'
+require 'tap/intern'
 
 module Tap
   class App
@@ -9,7 +9,7 @@ module Tap
     end
   end
   
-  # :startdoc::join a simple, unsyncrhonized, multi-way join
+  # :startdoc::join an unsyncrhonized, multi-way join
   #
   # Join defines an unsynchronized, multi-way join where n inputs send their
   # results to m outputs.  Flags can augment how the results are passed, in
@@ -25,10 +25,7 @@ module Tap
         super
       end
       
-      # Parses the argv into an array like [inputs, outputs, instance] where
-      # inputs and outputs implicitly define the inputs and output for the
-      # instance.  By default parse parses an argh then calls instantiate,
-      # but there is no requirement that this occurs in subclasses.
+      # Parses the argv into an instance of self.
       def parse(argv=ARGV, app=Tap::App.instance)
         parse!(argv.dup, app)
       end
@@ -47,8 +44,7 @@ module Tap
         }, app)
       end
       
-      # Instantiates an instance of self and return an array like [inputs,
-      # outputs, instance].
+      # Instantiates an instance of self.
       def instantiate(argh, app=Tap::App.instance)
         new(argh[:config] || {}, app)
       end
@@ -61,7 +57,7 @@ module Tap
       def intern(config={}, app=Tap::App.instance, &block) # :yields: join, result
         instance = new(config, app)
         if block_given?
-          instance.extend Support::Intern(:call)
+          instance.extend Intern(:call)
           instance.call_block = block
         end
         instance
@@ -151,6 +147,13 @@ module Tap
       end
     end
     
+    def to_hash
+      {
+        :class => self.class,
+        :config => config.to_hash
+      }
+    end
+    
     protected
     
     # Dispatches the results to the node.