tap 0.19.0 → 1.3.0

data/lib/tap/root.rb

@@ -1,268 +1,191 @@
-require 'configurable'
-require 'tap/root/utils'
+autoload(:FileUtils, 'fileutils')
 
 module Tap
-  
-  # Root abstracts a directory to standardize access to resources organized
-  # within variable directory structures.
-  #
-  #   # define a root directory with aliased relative paths
-  #   root = Root.new(
-  #     :root => '/root_dir', 
-  #     :relative_paths => {:input => 'in', :output => 'out'})
-  #  
-  #   # access aliased paths
-  #   root[:input]                                   # => '/root_dir/in'
-  #   root[:output]                                  # => '/root_dir/out'
-  #   root['implicit']                               # => '/root_dir/implicit'
-  #
-  #   # absolute paths can also be aliased
-  #   root[:abs, true] = "/absolute/path"
-  #   root.path(:abs, "to", "file.txt")              # => '/absolute/path/to/file.txt'
-  #
-  #   # expanded paths are returned unchanged
-  #   path = File.expand_path('expanded')
-  #   root[path]                                     # => path
-  #
-  #   # work with paths
-  #   path = root.path(:input, 'path/to/file.txt')   # => '/root_dir/in/path/to/file.txt'
-  #   root.relative_path(:input, path)               # => 'path/to/file.txt'
-  #   root.translate(path, :input, :output)          # => '/root_dir/out/path/to/file.txt'
-  #
-  # By default, Roots are initialized to the present working directory
-  # (Dir.pwd).
-  #
-  # === Implementation Notes
-  #
-  # 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 '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 paths in 'paths' are expanded
-  # - relative paths are stored in 'relative_paths'
-  # - absolute paths are present in 'paths' but not in 'relative_paths'
-  #
   class Root
-    include Configurable
-    include Utils
-  
-    # The root directory.
-    config_attr(:root, '.', :writer => false, :init => false)
-  
-    # A hash of (alias, relative path) pairs for aliased paths relative
-    # to root.
-    config_attr(:relative_paths, {}, :writer => false, :init => false, :type => :hash)
-  
-    # A hash of (alias, relative path) pairs for aliased absolute paths.
-    config_attr(:absolute_paths, {}, :reader => false, :writer => false, :init => false, :type => :hash)
-  
-    # 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 from the specified configurations.  A directory may be
-    # provided instead of a configuration hash; in that case no aliased relative
-    # or absolute paths are specified.  By default root is the present working
-    # directory.
-    def initialize(config_or_dir=Dir.pwd)
-      # root, relative_paths, and absolute_paths are assigned manually as
-      # an optimization (otherwise assign_paths would get called once for
-      # each configuration)
-      if config_or_dir.kind_of?(String)
-        assign_paths(config_or_dir, {}, {})
-        config_or_dir = {}
-      else
-        root = config_or_dir.delete(:root) || Dir.pwd
-        relative_paths = config_or_dir.delete(:relative_paths) || {}
-        absolute_paths = config_or_dir.delete(:absolute_paths) || {}
-        assign_paths(root, relative_paths, absolute_paths)
+    class << self
+      # The path root type indicating windows, *nix, or some unknown style of
+      # paths (:win, :nix, :unknown).
+      def type
+        @path_root_type ||= begin
+          pwd = File.expand_path('.')
+          
+          case
+          when pwd =~ WIN_ROOT_PATTERN then :win 
+          when pwd[0] == ?/ then :nix
+          else :unknown
+          end
+        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
     
-      initialize_config(config_or_dir)
-    end
-  
-    # Sets the root directory. All paths are reassigned accordingly.
-    def root=(path)
-      assign_paths(path, relative_paths, absolute_paths)
-    end
-
-    # Sets the relative_paths to those provided. 'root' and :root are reserved
-    # aliases and cannot be set using this method (use root= instead).
-    #
-    #   r = 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)
+      # Empty returns true when dir is an existing directory that has no files.
+      def empty?(dir)
+        File.directory?(dir) && (Dir.entries(dir) - ['.', '..']).empty?
+      end
     end
-  
-    # Sets the absolute paths to those provided. 'root' and :root are reserved
-    # aliases and cannot be set using this method (use root= instead).
-    #
-    #   r = Root.new
-    #   r['abs']                            # => File.join(r.root, 'abs')
-    #   r.absolute_paths = {'abs' => '/path/to/dir'}
-    #   r['abs']                            # => '/path/to/dir'
-    #
-    def absolute_paths=(paths)
-      paths = Validation::HASH[paths]
-      assign_paths(root, relative_paths, paths)
+    
+    # Regexp to match a windows-style root path.
+    WIN_ROOT_PATTERN = /\A[A-z]:\//
+    
+    def initialize(path=Dir.pwd, dir=Dir.pwd)
+      @path_root = File.expand_path(path.to_s, dir.to_s)
     end
-  
-    # Returns the absolute paths registered with self.
-    def absolute_paths
-      abs_paths = {}
-      paths.each do |als, path|
-        unless relative_paths.include?(als) || als.to_s == 'root'
-          abs_paths[als] = path
-        end
-      end
-      abs_paths
+    
+    # Stringifies and expands the path relative to self.  Paths are turned
+    # into strings using to_s.
+    def expand(path)
+      File.expand_path(path.to_s, @path_root)
     end
-
-    # 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 paths 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[:abs, true] = '/abs/path/to/dir'  
-    #   r[:abs]                             # => '/abs/path/to/dir'
-    #
-    #-- 
-    # Implementation Note:
-    #
-    # The syntax for setting an absolute path requires an odd use []=.  
-    # In fact the method receives 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 path.
-    #
-    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
-        path, absolute = absolute, path
-      end
     
-      case
-      when path.nil? 
-        @relative_paths.delete(als)
-        @paths.delete(als)
-      when absolute
-        @relative_paths.delete(als)
-        @paths[als] = File.expand_path(path)
-      else
-        @relative_paths[als] = path
-        @paths[als] = File.expand_path(File.join(root, path))
-      end 
+    # Joins and expands the path segments relative to self.  Segments are
+    # turned to strings using to_s.
+    def path(*segments)
+      segments.collect! {|seg| seg.to_s }
+      expand(File.join(*segments))
     end
-
-    # 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.path_root                         # => '/'
-    #   r['relative/path']                  # => '/root_dir/relative/path'
-    #   r['/expanded/path']                 # => '/expanded/path'
-    #
-    def [](als)
-      path = self.paths[als] 
-      return path unless path == nil
     
-      als = als.to_s 
-      expanded?(als) ? als : File.expand_path(File.join(root, als))
+    # Returns true if the expanded path is relative to self.
+    def relative?(path)
+      expand(path).rindex(@path_root, 0) == 0
     end
   
-    # Resolves the specified alias, joins paths together, and expands the
-    # resulting path.
-    def path(als, *paths)
-      File.expand_path(File.join(self[als], *paths))
-    end
+    # Returns the part of the expanded path relative to self, or nil if the
+    # path is not relative to self.
+    def relative_path(path)
+      path = expand(path)
+      return nil unless relative?(path)
   
-    # Returns true if the path is relative to the specified alias.
-    def relative?(als, path)
-      super(self[als], path)
+      # if path_root_length > path.length then the first arg
+      # returns nil, and an empty string is returned
+      path[path_root_length, path.length - path_root_length] || ""
     end
+    alias rp relative_path
   
-    # Returns the part of path relative to the specified alias.
-    def relative_path(als, path)
-      super(self[als], path)
+    # Returns a new Root for the path, relative to self.
+    def root(path)
+      Root.new(path, self)
+    end
+    
+    # Returns a new Root for the path, relative to self.  Same as root but
+    # raises an error if the path is not relative to self.
+    def sub(path)
+      sub = root(path)
+      unless relative?(sub)
+        raise ArgumentError, "not a sub path: #{sub} (#{self})"
+      end
+      sub
+    end
+    
+    # Returns a new Root for the parent directory for self.
+    def parent
+      root File.dirname(@path_root)
     end
   
-    # Generates a path translated from the aliased source to the aliased target.
-    # Raises an error if path is not relative to the source.
-    # 
-    #   r = Root.new '/root_dir'
-    #   path = r.path(:in, 'path/to/file.txt')  # => '/root_dir/in/path/to/file.txt'
-    #   r.translate(path, :in, :out)            # => '/root_dir/out/path/to/file.txt'
+    # Returns the expanded path, exchanging the extension with extname. 
+    # Extname may optionally omit the leading period.
     #
-    def translate(path, source_als, target_als)
-      super(path, self[source_als], self[target_als])
+    #   root = Root.new("/root")
+    #   root.exchange('path/to/file.txt', '.html')  # => '/root/path/to/file.html'
+    #   root.exchange('path/to/file.txt', 'rb')     # => '/root/path/to/file.rb'
+    #
+    def exchange(path, extname)
+      path = expand(path)
+      "#{path.chomp(File.extname(path))}#{extname[0] == ?. ? '' : '.'}#{extname}"
     end
-
-    # Globs for paths 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)
+    alias ex exchange
+    
+    # Generates a path translated from the source to the target. Raises an
+    # error if path is not relative to the source.
+    def translate(path, source, target)
+      path = expand(path)
+      source = root(source)
+      target = root(target)
+      
+      rp = source.relative_path(path)
+      if rp.nil?
+        raise ArgumentError, "\n#{path}\nis not relative to:\n#{source}"
+      end
+      
+      target.path(rp)
+    end
+    alias tr translate
+    
+    # Globs for unique paths matching the input patterns expanded relative to
+    # self. If no patterns are specified, glob returns all paths matching
+    # './**/*'.
+    def glob(*patterns)
       patterns << "**/*" if patterns.empty?
-      patterns.collect! {|pattern| path(als, pattern)}
-      super(*patterns)
+      patterns.collect! {|pattern| expand(pattern) }
+      Dir[*patterns].uniq
     end
-
-    # 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 version_glob(als, path, *vpatterns)
-      super(path(als, path), *vpatterns)
+    
+    # Changes to the specified directory using Dir.chdir, keeping the same
+    # block semantics as that method.  The directory will be created if
+    # necessary and mkdir is specified.  Raises an error for non-existant
+    # directories, as well as non-directory inputs.
+    def chdir(dir, mkdir=false, &block)
+      dir = expand(dir)
+    
+      unless File.directory?(dir)
+        if !File.exists?(dir) && mkdir
+          FileUtils.mkdir_p(dir)
+        else
+          raise ArgumentError, "not a directory: #{dir}"
+        end
+      end
+    
+      Dir.chdir(dir, &block)
     end
-  
-    # Changes pwd to the specified directory using Root.chdir.
-    def chdir(als, mkdir=false, &block)
-      super(self[als], mkdir, &block)
+    
+    # Makes the specified directory and parent directories (as required).
+    def mkdir(*path)
+      path = self.path(*path)
+      FileUtils.mkdir_p(path) unless File.directory?(path)
+      path
     end
-  
-    # Constructs a path from the inputs and prepares it using
-    # Root.prepare.  Returns the path.
-    def prepare(als, *paths, &block)
-      super(path(als, *paths), &block)
+    
+    # Opens the path in the specified mode, using the same semantics as
+    # File.open.
+    def open(path, mode='r', &block)
+      path = expand(path)
+      File.open(path, mode, &block)
     end
-  
+    
+    # Prepares a file at the path by making paths's parent directory. The file
+    # is opened in the mode and passed to the block, if given. The mode is
+    # ignored if no block is given.
+    #
+    # Returns path.
+    def prepare(*path)
+      path = self.path(*path)
+      dirname = File.dirname(path)
+      FileUtils.mkdir_p(dirname) unless File.exists?(dirname)
+      File.open(path, 'w') {|io| yield(io) } if block_given?
+      path
+    end
+    
+    # Returns path.
+    def to_s
+      @path_root
+    end
+    
     private
-  
-    # reassigns all paths with the input root, relative_paths, and absolute_paths
-    def assign_paths(root, relative_paths, absolute_paths) # :nodoc:
-      @root = File.expand_path(root)
-      @relative_paths = {}
-      @paths = {'root' => @root, :root => @root}
-
-      @path_root = File.dirname(@root)
-      while @path_root != (parent = File.dirname(@path_root))
-        @path_root = parent 
+    
+    # helper to memoize and return the length of path root, plus a trailing
+    # separator; used in determining relative paths
+    def path_root_length # :nodoc:
+      @path_root_length ||= begin
+        length = @path_root.length
+        unless @path_root == File::SEPARATOR
+          length += File::SEPARATOR.length
+        end
+        length
       end
-  
-      relative_paths.each_pair {|dir, path| self[dir] = path }
-      absolute_paths.each_pair {|dir, path| self[dir, true] = path }
-    end  
+    end
   end
 end

data/lib/tap/signal.rb

@@ -0,0 +1,72 @@
+require 'tap/utils'
+
+module Tap
+  # Signal attaches an object and allows a specific method to be triggered
+  # through a standard interface.
+  class Signal
+    class << self
+      # A description of self
+      attr_accessor :desc
+    end
+  
+    # The object receiving signals through self.
+    attr_reader :obj
+  
+    # An optional block, used at the signal's discretion (normally passed to
+    # the method the signal targets on obj).
+    attr_reader :block
+  
+    def initialize(obj, &block)
+      @obj = obj
+      @block = block
+    end
+  
+    # Calls process with the input args and returns the result.
+    def call(args)
+      process(args)
+    end
+  
+    # Simply returns the input args.
+    def process(args)
+      args
+    end
+
+    def inspect
+      "#<#{self.class}:#{object_id}>"
+    end
+    
+    protected
+  
+    def convert_to_array(obj, signature=[], options=false)
+      return obj if obj.kind_of?(Array)
+    
+      argv = signature.collect {|key| obj[key] }
+    
+      if options
+        opts = {}
+        (obj.keys - signature).each do |key|
+          opts[key] = obj[key]
+        end
+      
+        argv << opts
+      end
+    
+      argv
+    end
+  
+    def convert_to_hash(obj, signature=[], remainder=nil)
+      return obj if obj.kind_of?(Hash)
+    
+      args, argh = obj, {}
+      signature.each do |key|
+        argh[key] = args.shift
+      end
+    
+      if remainder
+        argh[remainder] = args
+      end
+    
+      argh
+    end
+  end
+end