tap 0.11.1 → 0.12.0

data/lib/tap.rb

@@ -1,10 +1,5 @@
-autoload(:YAML, 'yaml')                   # expensive to load
-
-$:.unshift File.expand_path(File.dirname(__FILE__))
+lib = File.expand_path(File.dirname(__FILE__))
+$:.unshift(lib) unless $:.include?(lib)
 
 require 'tap/constants'
-
-# require in order...
-require 'tap/exe'
-require 'tap/task'
-require 'tap/file_task'
+require 'tap/exe'

data/lib/tap/app.rb

@@ -1,50 +1,95 @@
 require 'logger'
+
+require 'tap/root'
 require 'tap/support/aggregator'
 require 'tap/support/dependencies'
 require 'tap/support/executable_queue'
+require 'tap/task'
 
 module Tap
   
   # App coordinates the setup and running of tasks, and provides an interface 
-  # to the application directory structure. All tasks have an App (by default
-  # App.instance) through which tasks access access application-wide resources 
-  # like the logger, executable queue, aggregator, and dependencies.
+  # to the application directory structure. All tasks have an app (by default
+  # App.instance) through which they access application-wide resources like
+  # the logger, executable queue, and dependencies.
   #
   # === Running Tasks
   #
-  # Task enque command are forwarded to App#enq:
+  # Tasks may be enqued and run by an App:
+  #
+  #   app = App.instance
   #
-  #   t0 = Task.intern {|task, input| "#{input}.0" }
-  #   t0.enq('a')
-  #   app.enq(t0, 'b')
+  #   t = Task.intern {|task, *inputs| inputs }
+  #   t.enq('a', 'b', 'c')
+  #   t.enq(1)
+  #   t.enq(2)
+  #   t.enq(3)
   #
   #   app.run
-  #   app.results(t0)                # => ['a.0', 'b.0']
+  #   app.results(t)                 # => [['a', 'b', 'c'], [1], [2], [3]]
   #
-  # When a task completes, the results will be passed to the task on_complete
-  # block, if set, or be collected into an Aggregator (aggregated results may 
-  # be accessed per-task, as shown above); on_complete blocks typically 
-  # execute or enque other tasks, allowing the construction of imperative
-  # workflows:
+  # By default apps simply run tasks and collect the results.  To construct
+  # a workflow, set an on_complete block to receive the audited result and
+  # enque or execute the next series of tasks.  Here is a simple sequence:
   #
-  #   # clear the previous results
-  #   app.aggregator.clear
+  #   t0 = Task.intern {|task| "0" }
+  #   t1 = Task.intern {|task, input| "#{input}:1" }
+  #   t2 = Task.intern {|task, input| "#{input}:2"}
   #
-  #   t1 = Task.intern {|task, input| "#{input}.1" }
   #   t0.on_complete {|_result| t1.enq(_result) }
-  #   t0.enq 'c'
-  #
+  #   t1.on_complete {|_result| t2.enq(_result) }
+  #   
+  #   t0.enq
+  #   app.run
+  #   app.results(t0, t1)            # => []
+  #   app.results(t2)                # => ["0:1:2"]
+  #
+  # Apps may be assigned an on_complete block as well; the app on_complete
+  # block is called when a task has no on_complete block set.  If neither the
+  # task nor the app has an on_complete block, the app stores the audit in
+  # app.aggregator and makes it available through app.results.  Note how after
+  # the sequence, the t0 and t1 results are not in the app (they were handled
+  # by the on_complete block).
+  #
+  # Tracking how inputs evolve through a workflow can be onerous.  To help,
+  # Tap audits changes to the inputs.  Audit values are by convention prefixed
+  # by an underscore; all on_complete block receive the audited values and not
+  # the actual result of a task.  Aggregated audits are available through
+  # app._results.
+  #
+  #   t2.enq("a")
+  #   t1.enq("b")
   #   app.run
-  #   app.results(t0)                # => []
-  #   app.results(t1)                # => ['c.0.1']
+  #   app.results(t2)                # => ["0:1:2", "a:2", "b:1:2"]
+  # 
+  #   t0.name = "zero"
+  #   t1.name = "one"
+  #   t2.name = "two"
+  #
+  #   trails = app._results(t2).collect do |_result|
+  #     _result.dump
+  #   end
   #
-  # Here t0 has no results because the on_complete block passed them to t1 in 
-  # a simple sequence.
+  #   "\n" + trails.join("\n")
+  #   # => %q{
+  #   # o-[zero] "0"
+  #   # o-[one] "0:1"
+  #   # o-[two] "0:1:2"
+  #   # 
+  #   # o-[] "a"
+  #   # o-[two] "a:2"
+  #   # 
+  #   # o-[] "b"
+  #   # o-[one] "b:1"
+  #   # o-[two] "b:1:2"
+  #   # }
+  #
+  # See Audit for more details.
   #
   # === Dependencies
   #
-  # Tasks allow the construction of dependency-based workflows such that a 
-  # dependent task only executes after its dependencies have been resolved.
+  # Tasks allow the construction of dependency-based workflows.  A dependent
+  # task only executes after its dependencies have been resolved.
   #
   #   runlist = []
   #   t0 = Task.intern {|task| runlist << task }
@@ -62,114 +107,35 @@ module Tap
   #   app.run
   #   runlist                        # => [t1, t0, t0]
   #
-  # === Batching
-  #
-  # Tasks can be batched, allowing the same input to be enqued to multiple 
-  # tasks at once.
-  #
-  #   t0 = Task.intern  {|task, input| "#{input}.0" }
-  #   t1 = Task.intern  {|task, input| "#{input}.1" }
-  #
-  #   t0.batch_with(t1)
-  #   t0.enq 'a'
-  #   t1.enq 'b'
-  #
-  #   app.run
-  #   app.results(t0)                # => ['a.0', 'b.0']
-  #   app.results(t1)                # => ['a.1', 'b.1']
-  #
   # === Executables
   #
   # App can enque and run any Executable object. Arbitrary methods may be
-  # made into Executables using Object#_method. The mq (method enq) method
-  # generates and enques methods in one step.
+  # made into Executables using Object#_method.
   #
   #   array = []
   #
-  #   # longhand
   #   m = array._method(:push)
   #   m.enq(1)
-  #
-  #   # shorthand
-  #   app.mq(array, :push, 2)
+  #   m.enq(2)
+  #   m.enq(3)
   #
   #   array.empty?                   # => true
   #   app.run
-  #   array                          # => [1, 2]
-  #
-  # === Auditing
-  # 
-  # All results are audited to track how a given input evolves during a workflow.
-  # To illustrate auditing, consider and addition workflow that ends in eights.
-  #
-  #   add_one  = Tap::Task.intern({}, 'add_one')  {|task, input| input += 1 }
-  #   add_five = Tap::Task.intern({}, 'add_five') {|task, input| input += 5 }
-  #
-  #   add_one.on_complete do |_result|
-  #     # _result is the audit; use the _current method
-  #     # to get the current value in the audit trail
-  #     current_value = _result._current
-  #
-  #     if current_value < 3 
-  #       add_one.enq(_result)
-  #     else
-  #       add_five.enq(_result)
-  #     end
-  #   end
-  #   
-  #   add_one.enq(0)
-  #   add_one.enq(1)
-  #   add_one.enq(2)
-  #
-  #   app.run
-  #   app.results(add_five)          # => [8,8,8]
-  #
-  # Although the results are indistinguishable, each achieved the final value
-  # through a different series of tasks. With auditing you can see how each 
-  # input came to the final value of 8:
-  #
-  #   # app.results returns the actual result values
-  #   # app._results returns the audits for these values
-  #   app._results(add_five).each do |_result|
-  #     puts "How #{_result._original} became #{_result._current}:"
-  #     puts _result._to_s
-  #     puts
-  #   end
-  #
-  # Prints:
-  #
-  #   How 2 became 8:
-  #   o-[] 2
-  #   o-[add_one] 3
-  #   o-[add_five] 8
+  #   array                          # => [1, 2, 3]
   #
-  #   How 1 became 8:
-  #   o-[] 1
-  #   o-[add_one] 2
-  #   o-[add_one] 3
-  #   o-[add_five] 8
-  #
-  #   How 0 became 8:
-  #   o-[] 0
-  #   o-[add_one] 1
-  #   o-[add_one] 2
-  #   o-[add_one] 3
-  #   o-[add_five] 8
-  #
-  # See Tap::Support::Audit for more details.
   class App < Root
     class << self
       # Sets the current app instance
       attr_writer :instance
       
       # Returns the current instance of App.  If no instance has been set,
-      # then a new App with the default configuration will be initialized. 
+      # then instance initializes a new App with the default configuration. 
       def instance
         @instance ||= App.new
       end
     end
 
-    # The shared logger
+    # The application logger
     attr_reader :logger
     
     # The application queue
@@ -178,13 +144,19 @@ module Tap
     # The state of the application (see App::State)
     attr_reader :state
     
-    # A Tap::Support::Aggregator to collect the results of 
+    # A Tap::Support::Aggregator that collects the results of 
     # methods that have no on_complete block
     attr_reader :aggregator
     
     # A Tap::Support::Dependencies to track dependencies.
     attr_reader :dependencies
     
+    # The block called when an executable completes and has no
+    # on_complete_block set.  An on_complete_block effectively
+    # takes the place of aggregation (ie when set, no results
+    # will be collected by self).
+    attr_reader :on_complete_block
+    
     config :debug, false, &c.flag                 # Flag debugging
     config :force, false, &c.flag                 # Force execution at checkpoints
     config :quiet, false, &c.flag                 # Suppress logging
@@ -199,7 +171,7 @@ module Tap
       
       module_function
       
-      # Returns the string corresponding to the input state value.  
+      # Returns a string corresponding to the input state value.  
       # Returns nil for unknown states.
       #
       #   State.state_str(0)        # => 'READY'
@@ -209,16 +181,19 @@ module Tap
       end
     end  
     
+    include MonitorMixin
+    
     # Creates a new App with the given configuration.  
-    def initialize(config={}, logger=DEFAULT_LOGGER)
+    def initialize(config={}, logger=DEFAULT_LOGGER, &block)
       super()
       
       @state = State::READY
       @queue = Support::ExecutableQueue.new
       @aggregator = Support::Aggregator.new
       @dependencies = Support::Dependencies.new
+      @on_complete_block = block
       
-      initialize_config(config)
+      reconfigure(config)
       self.logger = logger
     end
     
@@ -250,20 +225,7 @@ module Tap
       logger.add(level, msg, action.to_s) if !quiet || verbose
     end
     
-    # Returns the configuration filepath for the specified task name,
-    # File.join(app['config'], task_name + ".yml"). Returns nil if 
-    # task_name is nil.
-    def config_filepath(name)
-      name == nil ? nil : filepath('config', "#{name}.yml")
-    end
-    
-    # Sets state = State::READY unless the app is running.  Returns self.
-    def ready
-      @state = State::READY unless state == State::RUN
-      self
-    end
-
-    # Sequentially calls execute with the [executable, inputs] pairs in
+    # Sequentially calls execute with the (executable, inputs) pairs in
     # queue; run continues until the queue is empty and then returns self.
     #
     # ==== Run State
@@ -280,8 +242,10 @@ module Tap
     # Calls to run when the state is not State::READY do nothing and
     # return immediately.
     def run
-      return self unless state == State::READY
-      @state = State::RUN
+      synchronize do
+        return self unless state == State::READY
+        @state = State::RUN
+      end
 
       # TODO: log starting run
       begin
@@ -296,7 +260,7 @@ module Tap
         raise if debug?
         log($!.class, $!.message)
       ensure
-        @state = State::READY
+        synchronize { @state = State::READY }
       end
       
       # TODO: log run complete
@@ -309,7 +273,7 @@ module Tap
     #
     # Does nothing unless state is State::RUN.
     def stop
-      @state = State::STOP if state == State::RUN
+      synchronize { @state = State::STOP if state == State::RUN }
       self
     end
 
@@ -321,7 +285,7 @@ module Tap
     #
     # Does nothing if state == State::READY.
     def terminate
-      @state = State::TERMINATE unless state == State::READY
+      synchronize { @state = State::TERMINATE unless state == State::READY }
       self
     end
     
@@ -333,18 +297,18 @@ module Tap
       "state: #{state} (#{State.state_str(state)}) queue: #{queue.size} results: #{aggregator.size}"
     end
     
-    # Enques the task (or Executable) with the inputs.  If the task is batched, 
-    # then each task in task.batch will be enqued with the inputs.  Returns task.
+    # Enques the task (or Executable) with the inputs.  Raises an error if the
+    # input is not an Executable, or is not assigned to self.  Returns task.
     def enq(task, *inputs)
-      case task
-      when Tap::Task
-        raise ArgumentError, "not assigned to enqueing app: #{task}" unless task.app == self
-        task.enq(*inputs)
-      when Support::Executable
-        queue.enq(task, inputs)
-      else
-        raise ArgumentError, "not a Task or Executable: #{task}"
+      unless task.kind_of?(Support::Executable)
+        raise ArgumentError, "not an Executable: #{task.inspect}"
+      end
+      
+      unless task.app == self
+        raise ArgumentError, "not assigned to enqueing app: #{task.inspect}"
       end
+      
+      queue.enq(task, inputs)
       task
     end
 
@@ -367,20 +331,32 @@ module Tap
     #
     #   t0 = Task.intern  {|task, input| "#{input}.0" }
     #   t1 = Task.intern  {|task, input| "#{input}.1" }
-    #   t2 = Task.intern  {|task, input| "#{input}.2" }
-    #   t1.batch_with(t2)
     #
     #   t0.enq(0)
     #   t1.enq(1)
     #
     #   app.run
-    #   app.results(t0, t1.batch)     # => ["0.0", "1.1", "1.2"]
     #   app.results(t1, t0)           # => ["1.1", "0.0"]
     #
     def results(*tasks)
-      _results(tasks).collect {|_result| _result._current}
+      _results(tasks).collect {|_result| _result.value }
+    end
+    
+    # Sets a block to receive the results tasks with no on_complete_block
+    # set.  Raises an error if an on_complete_block is already set.
+    # Override the existing on_complete_block by specifying override = true.
+    #
+    # Note: the block recieves an audited result and not the result
+    # itself (see Audit for more information).
+    def on_complete(override=false, &block) # :yields: _result
+      unless on_complete_block == nil || override
+        raise "on_complete_block already set: #{self}" 
+      end
+      @on_complete_block = block
+      self
     end
     
+    # Returns a string like: "#<Tap::App:#{object_id} root: #{root} >"
     def inspect
       "#<#{self.class.to_s}:#{object_id} root: #{root} >"
     end

data/lib/tap/constants.rb

@@ -1,7 +1,7 @@
 module Tap
   MAJOR = 0
-  MINOR = 11
-  TINY = 1
+  MINOR = 12
+  TINY = 0
   
   VERSION="#{MAJOR}.#{MINOR}.#{TINY}" 
   WEBSITE="http://tap.rubyforge.org"

data/lib/tap/env.rb

@@ -1,14 +1,23 @@
 require 'tap/support/constant_manifest'
-require 'tap/support/gems'
 
 module Tap
-
+  module Support
+    autoload(:Templater, 'tap/support/templater')
+    autoload(:Gems, 'tap/support/gems')
+  end
+  
+  # Envs are locations on the filesystem that have resources associated with
+  # them (commands, tasks, generators, etc).  Envs may point to files, but it's
+  # more commonly environments are set to a directory and resources are various
+  # files within the directory.
+  #
+  #
   #--
   # Note that gems and env_paths reset envs -- custom modifications to envs will be lost
   # whenever these configs are reset.
   class Env
     include Enumerable
-    include Support::Configurable
+    include Configurable
     include Support::Minimap
     
     class << self
@@ -38,68 +47,45 @@ module Tap
       #   #  File.expand_path("./path/to/config.yml") => e1, 
       #   #  File.expand_path("./path/to/dir/#{Tap::Env::DEFAULT_CONFIG_FILE}") => e2 }
       #
-      # The Env is initialized using configurations read from the env config file using
-      # load_config, and a Root initialized to the config file directory. An instance 
-      # will be initialized regardless of whether the config file or directory exists.
-      def instantiate(path_or_root, default_config={}, logger=nil, &block)
-        path = path_or_root.kind_of?(Root) ? path_or_root.root : path_or_root
-        path = pathify(path)
+      # The Env is initialized using configurations read from the env config
+      # file. An instance will be initialized regardless of whether the config
+      # file or directory exists.
+      def instantiate(path_or_root)
+        path = config_path(path_or_root.kind_of?(Root) ? path_or_root.root : path_or_root)
+        return instances[path] if instances.has_key?(path)
         
-        begin
-          root = path_or_root.kind_of?(Root) ? path_or_root : Root.new(File.dirname(path))
-          config = default_config.merge(load_config(path))
-          
-          # note the assignment of env to instances MUST occur before
-          # reconfigure to prevent infinite looping
-          (instances[path] = new({}, root, logger)).reconfigure(config, &block)
-        rescue(Exception)
-          raise Env::ConfigError.new($!, path)
-        end
-      end
-      
-      def instance_for(path)
-        path = pathify(path)
-        instances.has_key?(path) ? instances[path] : instantiate(path)
-      end
-      
-      def pathify(path)
-        if File.directory?(path) || (!File.exists?(path) && File.extname(path) == "")
-          path = File.join(path, DEFAULT_CONFIG_FILE) 
-        end
-        File.expand_path(path)
+        config = load_config(path)
+        root = path_or_root.kind_of?(Root) ? path_or_root : File.dirname(path)
+        
+        # note the assignment of env to instances MUST occur
+        # before reconfigure to prevent infinite looping
+        (instances[path] = new(root)).reconfigure(config)
       end
       
-      def manifest(name, &block) # :yields: env (returns manifest)
+      def manifest(name, &block) # :yields: env (and should return a manifest)
         name = name.to_sym
         define_method(name) do
           self.manifests[name] ||= block.call(self).bind(self, name)
         end
       end
       
-      # Returns the gemspecs for all installed gems with a DEFAULT_CONFIG_FILE. 
-      # If latest==true, then only the specs for the most current gems will be 
-      # returned.
-      def gemspecs(latest=true)
-        Support::Gems.select_gems(latest) do |spec|
-          File.exists?(File.join(spec.full_gem_path, DEFAULT_CONFIG_FILE))
+      private
+      
+      def config_path(path) # :nodoc:
+        if File.directory?(path) || (!File.exists?(path) && File.extname(path) == "")
+          path = File.join(path, DEFAULT_CONFIG_FILE) 
         end
+        
+        File.expand_path(path)
       end
       
-      protected
-      
-      # Defines a config that collects the input into a unique,
-      # compact array where each member has been resolved using
-      # root[].  In short, ['lib', nil, 'lib', 'alt] becomes
-      # [root['lib'], root['alt']].
-      #
-      # Single and nil arguments are allowed; they are arrayified
-      # and handled as above.  Path configs raise an error if
-      # modified when the instance is active.
-      def path_config(key, value=[]) 
-        instance_variable = "@#{key}".to_sym
-        config_attr(key, value) do |input|
-          check_configurable
-          instance_variable_set(instance_variable, [*input].compact.collect {|path| root[path]}.uniq)
+      # helper to load path as YAML.  load_file returns a hash if the path
+      # loads to nil or false (as happens for empty files)
+      def load_config(path) # :nodoc:
+        begin
+          Root.trivial?(path) ? {} : (YAML.load_file(path) || {})
+        rescue(Exception)
+          raise Env::ConfigError.new($!, path)
         end
       end
     end
@@ -110,17 +96,19 @@ module Tap
     # The default config file path
     DEFAULT_CONFIG_FILE = "tap.yml"
     
-    # The Root directory structure for self.
-    attr_reader :root
-    
-    # Gets or sets the logger for self
-    attr_accessor :logger
+    # An array of nested Envs, by default comprised of the env_path
+    # + gem environments (in that order).  Nested environments are
+    # activated/deactivated with self.
+    attr_reader :envs
     
-    # Specify files to require when self is activated.
-    config :requires, [], &c.array_or_nil
-    
-    # Specify files to load when self is activated.
-    config :loads, [], &c.array_or_nil
+    # The Root directory structure for self.
+    nest(:root, Tap::Root) do |config|
+      case config
+      when Root then config
+      when String then Root.new(config)
+      else Root.new.reconfigure(config)
+      end
+    end
     
     # Specify gems to load as nested Envs.  Gems may be specified 
     # by name and/or version, like 'gemname >= 1.2'; by default the 
@@ -128,14 +116,24 @@ module Tap
     #
     # Gems are immediately loaded (via gem) through this method.
     config_attr :gems, [] do |input|
-      check_configurable
       specs_by_name = {}
+      
+      input = YAML.load(input) if input.kind_of?(String)
+      input = case input
+      when :latest, :all
+        Support::Gems.select_gems(input == :latest) do |spec|
+          env_config = File.join(spec.full_gem_path, Tap::Env::DEFAULT_CONFIG_FILE)
+          File.exists?(env_config)
+        end
+      else input
+      end
+      
       @gems = [*input].compact.collect do |gem_name| 
         spec = Support::Gems.gemspec(gem_name)
         
         case spec
         when nil then log(:warn, "unknown gem: #{gem_name}", Logger::WARN)
-        else Env.instance_for(spec.full_gem_path)
+        else Env.instantiate(spec.full_gem_path)
         end
         
         (specs_by_name[spec.name] ||= []) << spec
@@ -157,21 +155,28 @@ module Tap
 
     # Specify configuration files to load as nested Envs.
     config_attr :env_paths, [] do |input|
-      check_configurable
+      input = YAML.load(input) if input.kind_of?(String)
       @env_paths = [*input].compact.collect do |path| 
-        Env.instance_for(root[path]).env_path
+        Env.instantiate(root[path]).env_path
       end.uniq
       reset_envs
     end
     
     # Designate load paths.
-    path_config :load_paths, ["lib"]
+    config_attr :load_paths, ["lib"] do |paths|
+      raise "load_paths cannot be modified once active" if active?
+      @load_paths = resolve_paths(paths)
+    end
     
     # Designate paths for discovering and executing commands. 
-    path_config :command_paths, ["cmd"]
+    config_attr :command_paths, ["cmd"] do |paths|
+      @command_paths = resolve_paths(paths)
+    end
     
     # Designate paths for discovering generators.  
-    path_config :generator_paths, ["lib"]
+    config_attr :generator_paths, ["lib"] do |paths|
+      @generator_paths = resolve_paths(paths)
+    end
     
     manifest(:commands) do |env|
       paths = []
@@ -203,10 +208,8 @@ module Tap
       # generators.cache = env.cache[:generators]
       generators
     end
-
-    def initialize(config={}, root=Tap::Root.new, logger=nil)
-      @root = root 
-      @logger = logger
+    
+    def initialize(path_root_or_config=Dir.pwd)
       @envs = []
       @active = false
       @manifests = {}
@@ -215,27 +218,31 @@ module Tap
       @gems = []
       @env_paths = []
       
-      initialize_config(config)
+      initialize_config case path_root_or_config
+      when String, Root then {:root => path_root_or_config}
+      else path_root_or_config
+      end
     end
     
-    # Sets envs removing duplicates and instances of self.
-    def envs=(envs)
-      @envs = envs.uniq.delete_if {|e| e == self }
-      @envs.freeze
-      @flat_envs = nil
+    # Clears manifests so they may be regenerated.
+    def reset
+      @manifests.clear
     end
     
-    # An array of nested Envs, by default comprised of the
-    # env_path + gem environments (in that order).  These
-    # nested Envs are activated/deactivated with self.
-    #
-    # Returns a flattened array of the unique nested envs
-    # when flat == true.
-    def envs(flat=false)
-      flat ? (@flat_envs ||= self.flatten_envs.freeze) : @envs
+    # Returns the key for self in Env.instances.
+    def env_path
+      Env.instances.each_pair {|path, env| return path if env == self }
+      nil
+    end
+    
+    # Sets envs removing duplicates and instances of self.  Setting envs
+    # overrides any environments specified by env_path and gem.
+    def envs=(envs)
+      raise "envs cannot be modified once active" if active?
+      @envs = envs.uniq.delete_if {|e| e == self }
     end
     
-    # Unshifts env onto envs, removing duplicates.  
+    # Unshifts env onto envs, removing duplicates.
     # Self cannot be unshifted onto self.
     def unshift(env)
       unless env == self || envs[0] == env
@@ -256,27 +263,24 @@ module Tap
     
     # Passes each nested env to the block in order, starting with self.
     def each
-      envs(true).each {|e| yield(e) }
+      visit_envs.each {|e| yield(e) }
     end
     
     # Passes each nested env to the block in reverse order, ending with self.
     def reverse_each
-      envs(true).reverse_each {|e| yield(e) }
+      visit_envs.reverse_each {|e| yield(e) }
     end
     
-    # Visits each nested env in order, starting with self, and passing
-    # to the block the env and any arguments generated by the parent of 
-    # the env.  The initial arguments are set when recursive_each is 
-    # first called; subsequent arguements are the return values of the 
-    # block.
+    # Recursively injects the memo to each env of self.  Each env in envs
+    # receives the same memo from the parent.
     #
-    #   e0, e1, e2, e3, e4 = ('a'..'e').collect {|name| Tap::Env.new(:name => name) }
+    #   a,b,c,d,e = ('a'..'e').collect {|name| Tap::Env.new(:name => name) }
     # 
-    #   e0.push(e1).push(e2)
-    #   e1.push(e3).push(e4)
+    #   a.push(b).push(c)
+    #   b.push(d).push(e)
     # 
     #   lines = []
-    #   e0.recursive_each(0) do |env, nesting_depth|
+    #   a.recursive_inject(0) do |nesting_depth, env|
     #     lines << "\n#{'..' * nesting_depth}#{env.config[:name]} (#{nesting_depth})"
     #     nesting_depth + 1
     #   end
@@ -289,151 +293,74 @@ module Tap
     #   # ....e (2)
     #   # ..c (1)}
     #
-    def recursive_each(*args, &block) # :yields: env, *parent_args
-      each_nested_env(self, [], args, &block)
-    end
-    
-    # Returns the total number of unique envs nested in self (including self).
-    def count
-      envs(true).length
+    def recursive_inject(memo, &block) # :yields: memo, env
+      inject_envs(memo, &block)
     end
     
-    # Processes and resets the input configurations for both root
-    # and self. Reconfiguration consists of the following steps:
+    # Activates self by doing the following, in order:
     #
-    # * partition overrides into env, root, and other configs
-    # * reconfigure root with the root configs
-    # * reconfigure self with the env configs
-    # * yield other configs to the block (if given)
+    # * sets Env.instance to self (unless already set)
+    # * activate nested environments
+    # * unshift load_paths to $LOAD_PATH
     #
-    # Reconfigure will always yields to the block, even if there
-    # are no non-root, non-env configurations.  Unspecified 
-    # configurations are NOT reconfigured.  (Note this means 
-    # that existing path configurations like load_paths will 
-    # not automatically be reset using reconfigured root.)
-    def reconfigure(overrides={})
-      check_configurable
-      
-      # partiton config into its parts
-      env_configs = {}
-      root_configs = {}
-      other_configs = {}
-      
-      env_configurations = self.class.configurations
-      root_configurations = root.class.configurations
-      overrides.each_pair do |key, value|
-        key = key.to_sym
-    
-        partition = case 
-        when env_configurations.key?(key) then env_configs
-        when root_configurations.key?(key) then root_configs
-        else other_configs
-        end
-    
-        partition[key] = value
-      end
-    
-      # reconfigure root so it can resolve path_configs
-      root.reconfigure(root_configs)
-      
-      # reconfigure self
-      super(env_configs)
-      
-      # handle other configs 
-      case
-      when block_given?
-        yield(other_configs) 
-      when !other_configs.empty?
-        log(:warn, "ignoring non-env configs: #{other_configs.keys.join(',')}", Logger::DEBUG)
-      end
-      
-      self
-    end
-    
-    # Returns the path for self in Env.instances.
-    def env_path
-      Env.instances.each_pair {|path, env| return path if env == self }
-      nil
-    end
-    
-    # Logs the action and message at the input level (default INFO).
-    # Logging is suppressed if no logger is set.
-    def log(action, msg="", level=Logger::INFO)
-      logger.add(level, msg, action.to_s) if logger
-    end
-    
-    # Activates self by unshifting load_paths for self to the load_path_targets.
-    # Once active, self can be referenced from Env.instance and the current
-    # configurations are frozen.  Env.instance is deactivated, if set, before
-    # self is activated. Returns true if activate succeeded, or false if self 
-    # is already active.
+    # Once active, the current envs and load_paths are frozen and cannot be
+    # modified until deactivated. Returns true if activate succeeded, or
+    # false if self is already active.
     def activate
       return false if active?
       
       @active = true
       @@instance = self if @@instance == nil
       
-      # freeze array configs like load_paths
-      config.each_pair do |key, value|
-        case value
-        when Array then value.freeze
-        end
-      end
+      # freeze envs and load paths
+      @envs.freeze
+      @load_paths.freeze
       
       # activate nested envs
       envs.reverse_each do |env|
         env.activate
       end
-
+      
       # add load paths
       load_paths.reverse_each do |path|
         $LOAD_PATH.unshift(path)
       end
-    
-      $LOAD_PATH.uniq!
-      
-      # perform requires
-      requires.each do |path|
-        require path
-      end
       
-      # perform loads
-      loads.each do |path|
-        load path
-      end
+      $LOAD_PATH.uniq!
       
       true
     end
     
-    # Deactivates self by clearing manifests and deleting load_paths for self 
-    # from the load_path_targets. Env.instance will no longer reference self 
-    # and the configurations are unfrozen (using duplication).
+    # Deactivates self by doing the following in order:
     #
+    # * deactivates nested environments
+    # * removes load_paths from $LOAD_PATH
+    # * sets Env.instance to nil (if set to self)
+    # * clears cached manifest data
+    #
+    # Once deactivated, envs and load_paths are unfrozen and may be modified.
     # Returns true if deactivate succeeded, or false if self is not active.
     def deactivate
       return false unless active?
+      @active = false
+      
+      # dectivate nested envs
+      envs.reverse_each do |env|
+        env.deactivate
+      end
       
       # remove load paths
       load_paths.each do |path|
         $LOAD_PATH.delete(path)
       end
-
-      # unfreeze array configs by duplicating
-      self.config.class_config.each_pair do |key, value|
-        value = send(key)
-        case value
-        when Array then instance_variable_set("@#{key}", value.dup)
-        end
-      end
       
-      @active = false
-      @manifests.clear
-      @@instance = nil if @@instance == self
+      # unfreeze envs and load paths
+      @envs = @envs.dup
+      @load_paths = @load_paths.dup
       
-      # dectivate nested envs
-      envs.reverse_each do |env|
-        env.deactivate
-      end
+      # clear cached data
+      @@instance = nil if @@instance == self
+      @manifests.clear
       
       true
     end
@@ -444,36 +371,30 @@ module Tap
     end
     
     # Searches each env for the first existing file or directory at 
-    # env.root.filepath(dir, path).  Paths are expanded, and search_path
+    # env.root.filepath(dir, path).  Paths are expanded, and search
     # checks to make sure the file is, in fact, relative to env.root[dir].
     # An optional block may be used to check the file; the file will only
     # be returned if the block returns true.
     #
     # Returns nil if no file can be found.
-    def search_path(dir, path)
+    def search(dir, path, strict=true)
       each do |env|
         directory = env.root.filepath(dir)
         file = env.root.filepath(dir, path)
+        next unless File.exists?(file)
         
-        # check the file is relative to the
-        # directory, and that the file exists.
-        if file.rindex(directory, 0) == 0 && 
-          File.exists?(file) && 
-          (!block_given? || yield(file))
-          return file
+        # check the file is relative to directory
+        if strict && file.rindex(directory, 0) != 0
+          raise "not relative to search dir: #{file} (#{directory})"
         end
+        
+        # filter
+        return file if !block_given? || yield(file)
       end
       
       nil
     end
     
-    # def reset(name, &block)
-    #   each do |env|
-    #     env.manifests[name].each(&block)
-    #     env.manifests[name] = nil
-    #   end
-    # end
-    
     # 
     TEMPLATES = {}
     TEMPLATES[:commands] = %Q{<% if count > 1 %>
@@ -542,7 +463,7 @@ module Tap
       
       attrs = {}
       templaters = []
-      recursive_each(*args) do |env, *argv|
+      recursive_inject(args) do |argv, env|
         templater = Support::Templater.new(template, :env => env)
         next_args = block_given? ? yield(templater, attrs, *argv) : argv
         templaters << templater if next_args
@@ -564,46 +485,51 @@ module Tap
       env.root.root
     end
     
-    # Raises an error if self is already active (and hence, configurations
-    # should not be modified)
-    def check_configurable
-      raise "path configurations are disabled when active" if active?
-    end
-    
     # Resets envs using the current env_paths and gems.
     def reset_envs
       self.envs = env_paths.collect do |path| 
-        Env.instance_for(path)
+        Env.instantiate(path)
       end + gems.collect do |spec|
-        Env.instance_for(spec.full_gem_path)
+        Env.instantiate(spec.full_gem_path)
       end
     end
     
-    # Recursively iterates through envs collecting all envs into
-    # the target.  The result is a unique array of all nested 
-    # envs, in order, beginning with self.
-    def flatten_envs(target=[])
-      unless target.include?(self)
-        target << self
+    # Arrayifies, compacts, and resolves input paths using root, and
+    # removes duplicates.  In short
+    #
+    #   resolve_paths ['lib', nil, 'lib', 'alt]  # => [root['lib'], root['alt']]
+    #
+    def resolve_paths(paths) # :nodoc:
+      paths = YAML.load(paths) if paths.kind_of?(String)
+      [*paths].compact.collect {|path| root[path]}.uniq
+    end
+    
+    # Recursively iterates through envs, starting with self, and
+    # collects the visited envs in order.
+    def visit_envs(visited=[], &block) # :nodoc:
+      unless visited.include?(self)
+        visited << self
+        yield(self) if block_given?
+        
         envs.each do |env|
-          env.flatten_envs(target)
+          env.visit_envs(visited, &block)
         end
       end
       
-      target
+      visited
     end
     
-    private
-    
-    def each_nested_env(env, visited, args, &block)
-      return if visited.include?(env)
-      
-      visited << env
-      next_args = yield(env, *args)
-      next_args = [] if next_args == nil
-      env.envs.each do |nested_env|
-        each_nested_env(nested_env, visited, next_args, &block)
+    # helper to recursively inject a memo to the children of env
+    def inject_envs(memo, visited=[], &block)  # :nodoc:
+      unless visited.include?(self)
+        visited << self
+        next_memo = yield(memo, self)
+        envs.each do |env|
+          env.inject_envs(next_memo, visited, &block)
+        end
       end
+      
+      visited
     end
     
     # Raised when there is a Env-level configuration error.