tap 0.11.1 → 0.12.0

data/lib/tap/generator/generators/generator/generator_generator.rb

@@ -5,23 +5,33 @@ module Tap::Generator::Generators
   # Generates a new generator.
   class GeneratorGenerator < Tap::Generator::Base
     
+    config :test, true, &c.switch  # specifies creation of a test file
+    
     def manifest(m, const_name)
-      const = Constant.new(const_name.camelize)
-      dir= File.join('lib', const.path)
+      const = Tap::Support::Constant.new(const_name.camelize)
+      dir = app.filepath('lib', const.path)
       
       # make the directory
-      m.directory app.filepath(dir)
+      m.directory dir
       
       # make the generator
-      m.template app.filepath(dir, const.basename + '_generator.rb'), "task.erb", :const => const
+      m.template app.filepath(dir, "#{const.basename}_generator.rb"), "task.erb", :const => const
       
       # make the templates directory
       m.directory app.filepath(dir, 'templates')
+      
+      # make a template file
+      # (note it's easier to do this as a file since erb is
+      # added, and would have to be escaped in a template)
       m.file app.filepath(dir, 'templates', 'template_file.erb') do |file|
-        file.puts "# A sample template file."
-        file.puts "key: <%= key %>"
+        file << "# A sample template file.\nkey: <%= key %>\n"
       end
       
+      if test
+        test_path = app.filepath('test', "#{const.path}_generator_test.rb")
+        m.directory File.dirname(test_path)
+        m.template test_path, "test.erb", :const => const
+      end
     end
   end
 end

data/lib/tap/generator/generators/generator/templates/task.erb

@@ -2,7 +2,7 @@
 # <replace with command line description>
 
 # <%= const.const_name %> Documentation
-class <%= const.const_name %> < Tap::Generator::Base
+class <%= const.const_name %>Generator < Tap::Generator::Base
 
   config :key, 'value'           # a sample config
   
@@ -21,7 +21,7 @@ class <%= const.const_name %> < Tap::Generator::Base
     # template a file in the templates directory using ERB.
     # The (key, value) pairs will be available in the 
     # template as local variables.
-    m.template "<%= const.const_name.underscore %>_file.txt", "template_file.erb", :key => 'value'
+    m.template "<%= const.const_name.underscore %>_file.txt", "template_file.erb", config.to_hash
 
   end
 end <% module_nest(const.nesting, '  ') { target } end %>

data/lib/tap/generator/generators/generator/templates/test.erb

@@ -0,0 +1,26 @@
+require File.join(File.dirname(__FILE__), '<%= '../' * const.nesting_depth %>tap_test_helper.rb') 
+require '<%= const.path %>'
+require 'tap/generator/preview.rb'
+
+class <%= const.name %>Test < Test::Unit::TestCase
+
+  # Preview fakes out a generator for testing
+  Preview = Tap::Generator::Preview
+  
+  acts_as_tap_test 
+  
+  def test_<%= const.basename %>
+    g = <%= const.name %>.new.extend Preview
+    
+    # check the files and directories
+    assert_equal %w{
+      <%= const.const_name.underscore %>_file.txt
+    }, g.process
+    
+    # check the content as necessary
+    assert_equal %q{
+# A sample template file.
+key: value
+}, "\n" + g.builds['<%= const.const_name.underscore %>_file.txt']
+  end
+end

data/lib/tap/generator/generators/root/root_generator.rb

@@ -1,4 +1,4 @@
-require 'tap/root'
+require 'tap/generator/base'
 
 module Tap::Generator::Generators
   
@@ -21,7 +21,7 @@ module Tap::Generator::Generators
   class RootGenerator < Tap::Generator::Base
     
     config :config_file, true, &c.switch   # create a tap.yml file
-    config :tapfile, false, &c.switch      # create a tapfile
+    config :rapfile, false, &c.switch      # create a rapfile
     
     # ::args ROOT, PROJECT_NAME=basename(ROOT)
     def manifest(m, root, project_name=nil)
@@ -30,32 +30,43 @@ module Tap::Generator::Generators
       
       m.directory r.root
       m.directory r['lib']
+      m.directory r['test']
       
       template_files do |source, target|
         case
         when File.directory?(source)
           m.directory r[target]
           next
-        when target == 'gemspec'
-          m.template r[project_name + '.gemspec'], source, :project_name => project_name, :tapfile => tapfile, :config_file => config_file
+        when source =~ /gemspec$/
+          m.template r[project_name + '.gemspec'], source, :project_name => project_name, :config_file => config_file
           next
-        when target =~ /tapfile/i
-          next unless tapfile
+        when source =~ /Rapfile$/
+          next unless rapfile
         end
         
         m.template r[target], source, :project_name => project_name
       end
       
       m.file(r['tap.yml']) do |file|
-       Tap::App.configurations.inspect(:doc, file) do |templater|
-         next unless templater.receiver == Tap::Root
+        Configurable::Utils.dump(Tap::App.configurations, file) do |key, delegate|
+          default = delegate.default
           
-         templater.configurations.each do |(key, config)| 
-           config.default = nil if key.to_s == 'root'
-         end
-       end
-       Tap::Env.configurations.inspect(:doc, file)
+          # get the description
+          desc = delegate.attributes[:desc]
+          doc = desc.to_s
+          doc = desc.comment if doc.empty?
+          
+          # wrap as lines
+          lines = Lazydoc::Utils.wrap(doc, 50).collect {|line| "# #{line}"}
+          lines << "" unless lines.empty?
+          
+          # setup formatting
+          leader = key == 'root' || default == nil ? '# ' : ''
+          config = {key => default}.to_yaml[5..-1]
+          "#{lines.join("\n")}#{leader}#{config.strip}\n\n"
+        end
       end if config_file
     end
+    
   end
 end

data/lib/tap/generator/generators/root/templates/Rakefile

@@ -62,12 +62,12 @@ Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_files.include( spec.extra_rdoc_files )
   rdoc.rdoc_files.include( spec.files.select {|file| file =~ /^lib.*\.rb$/} )
   
-  # Using Tdoc to template your Rdoc will result in configurations being
+  # Using CDoc to template your RDoc will result in configurations being
   # listed with documentation in a subsection following attributes.  Not
   # necessary, but nice.
-  require 'tap/support/tdoc'
-  rdoc.template = 'tap/support/tdoc/tdoc_html_template' 
-  rdoc.options << '--fmt' << 'tdoc'
+  require 'cdoc'
+  rdoc.template = 'cdoc/cdoc_html_template' 
+  rdoc.options << '--fmt' << 'cdoc'
 end
 
 #

data/lib/tap/generator/generators/root/templates/{tapfile → Rapfile}

@@ -1,11 +1,11 @@
 require 'tap/declarations'
 
 module <%= project_name.camelize %>
-  extend Tap::Declarations
-  
-  # ::desc your basic goodnight moon task
-  # Says goodnight with a configurable message.
-  task(:goodnight, :obj, :message => 'goodnight') do |task, args|
-    puts "#{task.message} #{args.obj}"
+  extend Rap::Declarations
+  
+  # ::desc your basic goodnight moon task
+  # Says goodnight with a configurable message.
+  task(:goodnight, :obj, :message => 'goodnight') do |task, args|
+    puts "#{task.message} #{args.obj}"
   end
 end

data/lib/tap/generator/generators/root/templates/gemspec

@@ -22,6 +22,5 @@ Gem::Specification.new do |s|
   s.files = %W{
 <%= config_file ? "    tap.yml\n" : '' %>
     test/tap_test_helper.rb
-    test/tap_test_suite.rb
   }
 end

data/lib/tap/generator/generators/task/task_generator.rb

@@ -5,15 +5,15 @@ module Tap::Generator::Generators
   # Generates a new Tap::Task and an associated test file.
   class TaskGenerator < Tap::Generator::Base
     
-    config :test, true, &c.switch  # Generates the task without test files.
+    config :test, true, &c.switch  # specifies creation of a test file
     
     def manifest(m, const_name)
-      const = Constant.new(const_name.camelize)
+      const = Tap::Support::Constant.new(const_name.camelize)
       
       task_path = app.filepath('lib', "#{const.path}.rb")
       m.directory File.dirname(task_path)
       m.template task_path, "task.erb", :const => const
-          
+      
       if test
         test_path = app.filepath('test', "#{const.path}_test.rb")
         m.directory File.dirname(test_path)

data/lib/tap/generator/generators/task/templates/test.erb

@@ -14,6 +14,6 @@ class <%= const.name %>Test < Test::Unit::TestCase
     # a more complex test
     task.execute("moon")
     assert_equal ["goodnight moon"], app.results(task)
-    assert_audit_equal ExpAudit[[nil, "moon"], [task, "goodnight moon"]], app._results(task)[0]
+    assert_audit_equal [[nil, "moon"], [task, "goodnight moon"]], app._results(task)[0]
   end
 end

data/lib/tap/generator/manifest.rb

@@ -1,11 +1,17 @@
 module Tap
   module Generator
+    
+    # Manifest records methods called upon it using method_missing.  These
+    # actions are replayed on a generator in order (for generate) or in
+    # reverse order (for destroy).
     class Manifest
+      
+      # Makes a new Manifest.  Method calls on self are recorded to actions.
       def initialize(actions)
         @actions = actions
       end
 
-      # Record an action.
+      # Records an action.
       def method_missing(action, *args, &block)
         @actions << [action, args, block]
       end

data/lib/tap/generator/preview.rb

@@ -0,0 +1,76 @@
+require 'stringio'
+
+module Tap
+  module Generator
+    
+    # Preview is a testing module designed so that process will return an array
+    # of relative filepaths for the created files/directories (which are easy
+    # to specify in a test).  Preview also collects the content of created files
+    # to be tested as needed.
+    #
+    #   class Sample < Tap::Generator::Base
+    #     def manifest(m)
+    #       dir = app.filepath(:root, 'dir')
+    #
+    #       m.directory dir
+    #       m.file(File.join(dir, 'file.txt')) {|io| io << "content"}
+    #     end
+    #   end
+    #
+    # These assertions will pass:
+    #
+    #   s = Sample.new.extend Preview
+    #   assert_equal %w{
+    #     dir
+    #     dir/file.txt
+    #   }, s.process
+    #
+    #   assert_equal "content", s.preview['dir/file.txt']
+    #
+    # Note that relative filepaths are determined from app.root for the
+    # instance; in tests like the one above, it may be prudent to reset
+    # the Tap::App.instance like so:
+    #
+    #   def setup
+    #     Tap::App.instance = Tap::App.new
+    #   end
+    #
+    module Preview
+      
+      # A hash of (relative_path, content) pairs representing
+      # content built to files.
+      attr_accessor :preview
+      
+      def self.extended(base) # :nodoc:
+        base.instance_variable_set(:@preview, {})
+      end
+      
+      # Returns the path of path, relative to app.root.  If path
+      # is app.root, '.' will be returned.
+      def relative_path(path)
+        path = app.relative_filepath(:root, path) || path
+        path.empty? ? "." : path
+      end
+      
+      # Returns the relative path of the target.
+      def directory(target, options={})
+        relative_path(target)
+      end
+      
+      # Returns the relative path of the target.  If a block is given, 
+      # the block will be called with a StringIO and the results stored
+      # in builds.
+      def file(target, options={})
+        target = relative_path(target)
+        
+        if block_given?
+          io = StringIO.new
+          yield(io)
+          preview[target] = io.string
+        end
+        
+        target
+      end
+    end
+  end
+end

data/lib/tap/root.rb

@@ -1,59 +1,58 @@
+require 'configurable'
 require 'tap/support/versions'
-require 'tap/support/configurable'
 autoload(:FileUtils, 'fileutils')
 
 module Tap
   
-  # Root allows you to define a root directory and alias subdirectories, so that  
-  # you can conceptualize what filepaths you need without predefining the full 
-  # filepaths.  Root also simplifies operations on filepaths.
+  # Root allows you to define a root directory and alias relative paths, so
+  # that you can conceptualize what filepaths you need without predefining the
+  # full filepaths.  Root also simplifies operations on filepaths.
   #
-  #  # define a root directory with aliased subdirectories
-  #  r = Root.new '/root_dir', :input => 'in', :output => 'out'
+  #   # define a root directory with aliased relative paths
+  #   r = Root.new '/root_dir', :input => 'in', :output => 'out'
   #  
-  #  # work with directories
-  #  r[:input]                                   # => '/root_dir/in'
-  #  r[:output]                                  # => '/root_dir/out'
-  #  r['implicit']                               # => '/root_dir/implicit'
+  #   # work with aliases
+  #   r[:input]                                   # => '/root_dir/in'
+  #   r[:output]                                  # => '/root_dir/out'
+  #   r['implicit']                               # => '/root_dir/implicit'
   #
-  #  # expanded paths are returned unchanged
-  #  r[File.expand_path('expanded')]             # => File.expand_path('expanded')
+  #   # expanded paths are returned unchanged
+  #   r[File.expand_path('expanded')]             # => File.expand_path('expanded')
   #
-  #  # work with filepaths
-  #  fp = r.filepath(:input, 'path/to/file.txt') # => '/root_dir/in/path/to/file.txt'
-  #  r.relative_filepath(:input, fp)             # => 'path/to/file.txt'
-  #  r.translate(fp, :input, :output)            # => '/root_dir/out/path/to/file.txt'
+  #   # work with filepaths
+  #   fp = r.filepath(:input, 'path/to/file.txt') # => '/root_dir/in/path/to/file.txt'
+  #   r.relative_filepath(:input, fp)             # => 'path/to/file.txt'
+  #   r.translate(fp, :input, :output)            # => '/root_dir/out/path/to/file.txt'
   #  
-  #  # version filepaths
-  #  r.version('path/to/config.yml', 1.0)        # => 'path/to/config-1.0.yml'
-  #  r.increment('path/to/config-1.0.yml', 0.1)  # => 'path/to/config-1.1.yml'
-  #  r.deversion('path/to/config-1.1.yml')       # => ['path/to/config.yml', "1.1"]
+  #   # version filepaths
+  #   r.version('path/to/config.yml', 1.0)        # => 'path/to/config-1.0.yml'
+  #   r.increment('path/to/config-1.0.yml', 0.1)  # => 'path/to/config-1.1.yml'
+  #   r.deversion('path/to/config-1.1.yml')       # => ['path/to/config.yml', "1.1"]
   #
-  #  # absolute paths can also be aliased 
-  #  r[:abs, true] = "/absolute/path"      
-  #  r.filepath(:abs, "to", "file.txt")          # => '/absolute/path/to/file.txt'
+  #   # absolute paths can also be aliased 
+  #   r[:abs, true] = "/absolute/path"      
+  #   r.filepath(:abs, "to", "file.txt")          # => '/absolute/path/to/file.txt'
   #
-  # By default, Roots are initialized to the present working directory (Dir.pwd).
-  # As in the 'implicit' example, Root infers a path relative to the root directory
-  # whenever it needs to resolve an alias that is not explicitly set.  The only 
-  # exceptions to this are fully expanded paths.  These are returned unchanged.
+  # By default, Roots are initialized to the present working directory
+  # (Dir.pwd).
   #
+  #--
   # === Implementation Notes
   #
-  # Internally Root stores expanded paths all aliased paths in the 'paths' hash.  
-  # Expanding paths ensures they remain constant even when the present working 
+  # Internally Root expands and stores all aliased paths in the 'paths' hash.
+  # Expanding paths ensures they remain constant even when the present working
   # directory (Dir.pwd) changes.
   #
-  # Root keeps a separate 'directories' hash mapping aliases to their subdirectory paths.  
-  # This hash allow reassignment if and when the root directory changes.  By contrast, 
-  # there is no separate data structure storing the absolute paths. An absolute path 
-  # thus has an alias in 'paths' but not 'directories', whereas subdirectory paths
-  # have aliases in both.
+  # Root keeps a separate 'relative_paths' hash mapping aliases to their
+  # relative paths. This hash allow reassignment if and when the root directory
+  # changes.  By contrast, there is no separate data structure storing the
+  # absolute paths. An absolute path thus has an alias in 'paths' but not
+  # 'relative_paths', whereas relative paths have aliases in both.
   #
   # These features may be important to note when subclassing Root:
   # - root and all filepaths in 'paths' are expanded
-  # - subdirectory paths are stored in 'directories'
-  # - absolute paths are present in 'paths' but not in 'directories'
+  # - relative paths are stored in 'relative_paths'
+  # - absolute paths are present in 'paths' but not in 'relative_paths'
   #
   class Root
     # Regexp to match a windows-style root filepath.
@@ -77,12 +76,12 @@ module Tap
         # use dir.length + 1 to remove a leading '/'.   If dir.length + 1 >= expanded.length 
         # as in: relative_filepath('/path', '/path') then the first arg returns nil, and an 
         # empty string is returned
-        expanded_path[( expanded_dir.chomp("/").length + 1)..-1] || ""
+        expanded_path[(expanded_dir.chomp("/").length + 1)..-1] || ""
       end
       
-      # Generates a target filepath translated from the source_dir to 
-      # the target_dir. Raises an error if the filepath is not relative 
-      # to the source_dir.    
+      # Generates a target filepath translated from the source_dir to the
+      # target_dir. Raises an error if the filepath is not relative to the
+      # source_dir.    
       #
       #    Root.translate("/path/to/file.txt", "/path", "/another/path")  # => '/another/path/to/file.txt'
       #
@@ -92,6 +91,16 @@ module Tap
         end
         File.join(target_dir, relative_path)
       end
+      
+      # Returns the path, exchanging the extension with extname.  Extname may
+      # optionally omit the leading period.
+      #
+      #   Root.exchange('path/to/file.txt', '.html')  # => 'path/to/file.html'
+      #   Root.exchange('path/to/file.txt', 'rb')     # => 'path/to/file.rb'
+      #
+      def exchange(path, extname)
+        "#{path.chomp(File.extname(path))}#{extname[0] == ?. ? '' : '.'}#{extname}"
+      end
     
       # Lists all unique paths matching the input glob patterns.  
       def glob(*patterns)
@@ -100,8 +109,8 @@ module Tap
         end.flatten.uniq
       end
     
-      # Lists all unique versions of path matching the glob version patterns.  
-      # If no patterns are specified, then all versions of path will be returned.
+      # Lists all unique versions of path matching the glob version patterns. If
+      # no patterns are specified, then all versions of path will be returned.
       def vglob(path, *vpatterns)
         vpatterns << "*" if vpatterns.empty?
         vpatterns.collect do |vpattern| 
@@ -113,8 +122,8 @@ module Tap
         end.flatten.uniq
       end
       
-      # Path suffix glob.  Globs along the base paths for 
-      # paths that match the specified suffix pattern.
+      # Path suffix glob.  Globs along the base paths for paths that match the
+      # specified suffix pattern.
       def sglob(suffix_pattern, *base_paths)
         base_paths.collect do |base|
           base = File.expand_path(base)
@@ -122,9 +131,9 @@ module Tap
         end.flatten.uniq
       end
       
-      # Like Dir.chdir but makes the directory, if necessary, when 
-      # mkdir is specified. chdir raises an error for non-existant 
-      # directories, as well as non-directory inputs.
+      # Like Dir.chdir but makes the directory, if necessary, when mkdir is 
+      # specified. chdir raises an error for non-existant directories, as well
+      # as non-directory inputs.
       def chdir(dir, mkdir=false, &block)
         dir = File.expand_path(dir)
         
@@ -139,8 +148,20 @@ module Tap
         Dir.chdir(dir, &block)
       end
       
-      # The path root type indicating windows, *nix, or some unknown
-      # style of filepaths (:win, :nix, :unknown).
+      # Prepares the input path by making the parent directory for path. If a
+      # block is given, a file is created at path and passed to it; in this
+      # way files with non-existant parent directories are readily made.
+      #
+      # Returns path.
+      def prepare(path, &block)
+        dirname = File.dirname(path)
+        FileUtils.mkdir_p(dirname) unless File.exists?(dirname)
+        File.open(path, "w", &block) if block_given?
+        path
+      end
+      
+      # The path root type indicating windows, *nix, or some unknown style of
+      # filepaths (:win, :nix, :unknown).
       def path_root_type
         @path_root_type ||= case
         when RUBY_PLATFORM =~ /mswin/ && File.expand_path(".") =~ WIN_ROOT_PATTERN then :win 
@@ -149,25 +170,24 @@ module Tap
         end
       end
       
-      # Returns true if the input path appears to be an expanded path,
-      # based on Root.path_root_type.  
+      # Returns true if the input path appears to be an expanded path, based on
+      # Root.path_root_type.  
       #
-      # If root_type == :win returns true if the path matches 
-      # WIN_ROOT_PATTERN.
+      # If root_type == :win returns true if the path matches WIN_ROOT_PATTERN.
       #
-      #   Root.expanded_path?('C:/path')  # => true
-      #   Root.expanded_path?('c:/path')  # => true
-      #   Root.expanded_path?('D:/path')  # => true
-      #   Root.expanded_path?('path')     # => false
+      #   Root.expanded?('C:/path')  # => true
+      #   Root.expanded?('c:/path')  # => true
+      #   Root.expanded?('D:/path')  # => true
+      #   Root.expanded?('path')     # => false
       #
-      # If root_type == :nix, then expanded? returns true if 
-      # the path begins with '/'.
+      # If root_type == :nix, then expanded? returns true if the path begins
+      # with '/'.
       #
-      #   Root.expanded_path?('/path')  # => true
-      #   Root.expanded_path?('path')   # => false
+      #   Root.expanded?('/path')  # => true
+      #   Root.expanded?('path')   # => false
       #
-      # Otherwise expanded_path? always returns nil.
-      def expanded_path?(path, root_type=path_root_type)
+      # Otherwise expanded? always returns nil.
+      def expanded?(path, root_type=path_root_type)
         case root_type
         when :win 
           path =~ WIN_ROOT_PATTERN ? true : false
@@ -178,6 +198,17 @@ module Tap
         end
       end
       
+      # Trivial indicates when a path does not have content to load.  Returns
+      # true if the file at path is empty, non-existant, a directory, or nil.
+      def trivial?(path)
+        path == nil || !File.file?(path) || File.size(path) == 0
+      end
+      
+      # Empty returns true when dir is an existing directory that has no files.
+      def empty?(dir)
+        File.directory?(dir) && (Dir.entries(dir) - ['.', '..']).empty?
+      end
+      
       # Minimizes a set of paths to the set of shortest basepaths that unqiuely 
       # identify the paths.  The path extension and versions are removed from
       # the basepath if possible.  For example:
@@ -267,8 +298,9 @@ module Tap
         end
       end
       
-      # Returns true if the mini_path matches path.  Matching logic
-      # reverses that of minimize: 
+      # Returns true if the mini_path matches path.  Matching logic reverses
+      # that of minimize:
+      #
       # * a match occurs when path ends with mini_path
       # * if mini_path doesn't specify an extension, then mini_path
       #   must only match path up to the path extension
@@ -324,11 +356,12 @@ module Tap
       #   windows     '\'        Root.split('C:\path\to\file')  # => ["C:", "path", "to", "file"]
       #   *nix        '/'        Root.split('/path/to/file')    # => ["", "path", "to", "file"]
       # 
-      # The path is always expanded relative to the expand_dir; so '.' and '..' are 
-      # resolved.  However, unless expand_path == true, only the segments relative
-      # to the expand_dir are returned.  
+      # The path is always expanded relative to the expand_dir; so '.' and
+      # '..' are resolved.  However, unless expand_path == true, only the
+      # segments relative to the expand_dir are returned.  
       #
-      # On windows (note that expanding paths allows the use of slashes or backslashes):
+      # On windows (note that expanding paths allows the use of slashes or
+      # backslashes):
       #
       #   Dir.pwd                                               # => 'C:/'
       #   Root.split('path\to\..\.\to\file')                    # => ["C:", "path", "to", "file"]
@@ -365,6 +398,7 @@ module Tap
       #
       #   "./path"
       #   "//path"
+      #
       def min_join(dir, path) # :nodoc:
         case dir
         when "." then path
@@ -407,89 +441,99 @@ module Tap
       end
       
     end
-  
+    
+    include Configurable
     include Support::Versions
-    include Support::Configurable
-
+    
     # The root directory.
     config_attr(:root, '.', :writer => false)
     
-    # A hash of (alias, relative path) pairs for aliased subdirectories.
-    config_attr(:directories, {}, :writer => false)
+    # A hash of (alias, relative path) pairs for aliased paths relative
+    # to root.
+    config_attr(:relative_paths, {}, :writer => false)
     
     # A hash of (alias, relative path) pairs for aliased absolute paths.
     config_attr(:absolute_paths, {}, :reader => false, :writer => false)
     
-    # A hash of (alias, expanded path) pairs for aliased subdirectories and absolute paths.
+    # A hash of (alias, expanded path) pairs for expanded relative and
+    # absolute paths.
     attr_reader :paths
     
     # The filesystem root, inferred from self.root
     # (ex '/' on *nix or something like 'C:/' on Windows).
     attr_reader :path_root
     
-    # Creates a new Root with the given root directory, aliased directories
+    # Creates a new Root with the given root directory, aliased relative paths
     # and absolute paths.  By default root is the present working directory 
-    # and no aliased directories or absolute paths are specified.  
-    def initialize(root=Dir.pwd, directories={}, absolute_paths={})
-      assign_paths(root, directories, absolute_paths)
-      @config = self.class.configurations.instance_config(self)
+    # and no aliased relative or absolute paths are specified.  
+    def initialize(root=Dir.pwd, relative_paths={}, absolute_paths={})
+      assign_paths(root, relative_paths, absolute_paths)
+      @config = DelegateHash.new(self.class.configurations, {}, self)
     end
     
     # Sets the root directory. All paths are reassigned accordingly.
     def root=(path)
-      assign_paths(path, directories, absolute_paths)
+      assign_paths(path, relative_paths, absolute_paths)
     end
   
-    # Sets the directories to those provided. 'root' and :root are reserved
-    # and cannot be set using this method (use root= instead).
+    # Sets the relative_paths to those provided. 'root' and :root are reserved
+    # aliases and cannot be set using this method (use root= instead).
     #
-    # r['alt'] # => File.join(r.root, 'alt')
-    # r.directories = {'alt' => 'dir'}
-    # r['alt'] # => File.join(r.root, 'dir')
-    def directories=(dirs)
-      assign_paths(root, dirs, absolute_paths)
+    #   r = Tap::Root.new
+    #   r['alt']                            # => File.join(r.root, 'alt')
+    #   r.relative_paths = {'alt' => 'dir'}
+    #   r['alt']                            # => File.join(r.root, 'dir')
+    #
+    def relative_paths=(paths)
+      paths = Validation::HASH[paths]
+      assign_paths(root, paths, absolute_paths)
     end
     
     # Sets the absolute paths to those provided. 'root' and :root are reserved
-    # directory keys and cannot be set using this method (use root= instead).
+    # aliases and cannot be set using this method (use root= instead).
+    #
+    #   r = Tap::Root.new
+    #   r['abs']                            # => File.join(r.root, 'abs')
+    #   r.absolute_paths = {'abs' => '/path/to/dir'}
+    #   r['abs']                            # => '/path/to/dir'
     #
-    # r['abs'] # => File.join(r.root, 'abs')
-    # r.absolute_paths = {'abs' => '/path/to/dir'}
-    # r['abs'] # => '/path/to/dir'
     def absolute_paths=(paths)
-      assign_paths(root, directories, paths)
+      paths = Validation::HASH[paths]
+      assign_paths(root, relative_paths, paths)
     end
     
     # Returns the absolute paths registered with self.
     def absolute_paths
       abs_paths = {}
-      paths.each do |da, path| 
-        abs_paths[da] = path unless directories.include?(da) || da.to_s == 'root'
+      paths.each do |als, path|
+        unless relative_paths.include?(als) || als.to_s == 'root'
+          abs_paths[als] = path
+        end
       end
       abs_paths
     end
 
-    # Sets an alias for the subdirectory relative to the root directory.  
-    # The aliases 'root' and :root cannot be set with this method 
-    # (use root= instead).  Absolute filepaths can be set using the 
-    # second syntax.  
+    # Sets an alias for the path relative to the root directory.  The aliases
+    # 'root' and :root cannot be set with this method (use root= instead).
+    # Absolute filepaths can be set using the second syntax.  
     #
-    #  r = Root.new '/root_dir'
-    #  r[:dir] = 'path/to/dir'
-    #  r[:dir]       # => '/root_dir/path/to/dir'
+    #   r = Root.new '/root_dir'
+    #   r[:dir] = 'path/to/dir'
+    #   r[:dir]                             # => '/root_dir/path/to/dir'
     #
-    #  r[:abs, true] = '/abs/path/to/dir'  
-    #  r[:abs]       # => '/abs/path/to/dir'
+    #   r[:abs, true] = '/abs/path/to/dir'  
+    #   r[:abs]                             # => '/abs/path/to/dir'
     # 
     #--
-    # Implementation Notes:
+    # Implementation Note:
+    #
     # The syntax for setting an absolute filepath requires an odd use []=.  
     # In fact the method recieves the arguments (:dir, true, '/abs/path/to/dir') 
     # rather than (:dir, '/abs/path/to/dir', true), meaning that internally path 
     # and absolute are switched when setting an absolute filepath.
-    #++
-    def []=(dir, path, absolute=false)
-      raise ArgumentError, "The directory key '#{dir}' is reserved." if dir.to_s == 'root'
+    #
+    def []=(als, path, absolute=false)
+      raise ArgumentError, "the alias #{als.inspect} is reserved" if als.to_s == 'root'
   
       # switch the paths if absolute was provided
       unless absolute == false
@@ -500,84 +544,106 @@ module Tap
       
       case
       when path.nil? 
-        @directories.delete(dir)
-        @paths.delete(dir)
+        @relative_paths.delete(als)
+        @paths.delete(als)
       when absolute
-        @directories.delete(dir)
-        @paths[dir] = File.expand_path(path)
+        @relative_paths.delete(als)
+        @paths[als] = File.expand_path(path)
       else
-        @directories[dir] = path
-        @paths[dir] = File.expand_path(File.join(root, path))
+        @relative_paths[als] = path
+        @paths[als] = File.expand_path(File.join(root, path))
       end 
     end
   
-    # Returns the expanded path for the specified alias.  If the alias 
-    # has not been set, then the path is inferred to be 'root/dir' unless
-    # the path is relative to path_root.  These paths are returned 
-    # directly.
+    # Returns the expanded path for the specified alias.  If the alias has not
+    # been set, then the path is inferred to be 'root/als'.  Expanded paths
+    # are returned directly.
     #
-    #  r = Root.new '/root_dir', :dir => 'path/to/dir'
-    #  r[:dir]                 # => '/root_dir/path/to/dir'
+    #   r = Root.new '/root_dir', :dir => 'path/to/dir'
+    #   r[:dir]                             # => '/root_dir/path/to/dir'
     #
-    #  r.path_root             # => '/'
-    #  r['relative/path']      # => '/root_dir/relative/path'
-    #  r['/expanded/path']     # => '/expanded/path'
+    #   r.path_root                         # => '/'
+    #   r['relative/path']                  # => '/root_dir/relative/path'
+    #   r['/expanded/path']                 # => '/expanded/path'
     #
-    def [](dir)
-      path = self.paths[dir] 
+    def [](als)
+      path = self.paths[als] 
       return path unless path == nil
       
-      dir = dir.to_s 
-      Root.expanded_path?(dir) ? dir : File.expand_path(File.join(root, dir))
+      als = als.to_s 
+      Root.expanded?(als) ? als : File.expand_path(File.join(root, als))
     end
     
-    # Constructs expanded filepaths relative to the path of the specified alias. 
-    def filepath(dir, *filename)
-      # TODO - consider filename.compact so nils will not raise errors
-      File.expand_path(File.join(self[dir], *filename))
+    # Resolves the specified alias, joins the paths together, and expands the
+    # resulting filepath.
+    def filepath(als, *paths)
+      File.expand_path(File.join(self[als], *paths))
     end
   
     # Retrieves the filepath relative to the path of the specified alias.  
-    def relative_filepath(dir, filepath)
-      Root.relative_filepath(self[dir], filepath)
+    def relative_filepath(als, path)
+      Root.relative_filepath(self[als], path)
+    end
+    
+    # Same as filepath but raises an error if the result is not a subpath of
+    # the aliased directory.
+    def subpath(als, *paths)
+      dir = self[als]
+      path = filepath(als, *paths)
+      
+      if path.rindex(dir, 0) != 0
+        raise "not a subpath: #{path} (#{dir})"
+      end
+      
+      path
     end
   
-    # Generates a target filepath translated from the aliased source_dir to 
-    # the aliased target_dir. Raises an error if the filepath is not relative 
-    # to the aliased source_dir.
+    # Generates a filepath translated from the aliased source dir to the
+    # aliased target dir. Raises an error if the filepath is not relative
+    # to the source dir.
     # 
-    #  fp = r.filepath(:in, 'path/to/file.txt')    # => '/root_dir/in/path/to/file.txt'
-    #  r.translate(fp, :in, :out)                  # => '/root_dir/out/path/to/file.txt'
-    def translate(filepath, source_dir, target_dir)
-      Root.translate(filepath, self[source_dir], self[target_dir])
+    #   r = Tap::Root.new '/root_dir'
+    #   path = r.filepath(:in, 'path/to/file.txt')    # => '/root_dir/in/path/to/file.txt'
+    #   r.translate(path, :in, :out)                  # => '/root_dir/out/path/to/file.txt'
+    #
+    def translate(path, source_als, target_als)
+      Root.translate(path, self[source_als], self[target_als])
     end
   
-    # Lists all files in the aliased dir matching the input patterns.  Patterns 
-    # should be valid inputs for +Dir.glob+.  If no patterns are specified, lists 
-    # all files/folders matching '**/*'.
-    def glob(dir, *patterns)
+    # Lists all files along the aliased path matching the input patterns.
+    # Patterns should join with the aliased path make valid globs for 
+    # Dir.glob.  If no patterns are specified, glob returns all paths
+    # matching 'als/**/*'.
+    def glob(als, *patterns)
       patterns << "**/*" if patterns.empty?
-      patterns.collect! {|pattern| filepath(dir, pattern)}
+      patterns.collect! {|pattern| filepath(als, pattern)}
       Root.glob(*patterns)
     end
   
-    # Lists all versions of filename in the aliased dir matching the version patterns.
-    # If no patterns are specified, then all versions of filename will be returned.
-    def vglob(dir, filename, *vpatterns)
-      Root.vglob(filepath(dir, filename), *vpatterns)
+    # Lists all versions of path in the aliased dir matching the version
+    # patterns. If no patterns are specified, then all versions of path
+    # will be returned.
+    def vglob(als, path, *vpatterns)
+      Root.vglob(filepath(als, path), *vpatterns)
+    end
+    
+    # Changes pwd to the specified directory using Root.chdir.
+    def chdir(als, mkdir=false, &block)
+      Root.chdir(self[als], mkdir, &block)
     end
     
-    # chdirs to the specified directory using Root.chdir.
-    def chdir(dir, mkdir=false, &block)
-      Root.chdir(self[dir], mkdir, &block)
+    # Constructs a path from the inputs (using filepath) and prepares it using
+    # Root.prepare.  Returns the path.
+    def prepare(als, *paths, &block)
+      Root.prepare(filepath(als, *paths), &block)
     end
     
     private
   
-    # reassigns all paths with the input root, directories, and absolute_paths
-    def assign_paths(root, directories, absolute_paths)
+    # reassigns all paths with the input root, relative_paths, and absolute_paths
+    def assign_paths(root, relative_paths, absolute_paths)
       @root = File.expand_path(root)
-      @directories = {}
+      @relative_paths = {}
       @paths = {'root' => @root, :root => @root}
 
       @path_root = File.dirname(@root)
@@ -585,7 +651,7 @@ module Tap
         @path_root = parent 
       end
     
-      directories.each_pair {|dir, path| self[dir] = path }
+      relative_paths.each_pair {|dir, path| self[dir] = path }
       absolute_paths.each_pair {|dir, path| self[dir, true] = path }
     end