root 0.0.1

data/lib/root/string_ext.rb

@@ -0,0 +1,57 @@
+class Root
+    
+  # StringExt provides two common string transformations, camelize and
+  # underscore. StringExt is automatically included in String.
+  #
+  # Both methods are directly taken from the ActiveSupport {Inflections}[http://api.rubyonrails.org/classes/ActiveSupport/CoreExtensions/String/Inflections.html]
+  # module.  StringExt should not cause conflicts if ActiveSupport is
+  # loaded alongside Root.
+  #
+  # ActiveSupport is distributed with an MIT-LICENSE:
+  #
+  #   Copyright (c) 2004-2008 David Heinemeier Hansson
+  # 
+  #   Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 
+  #   associated documentation files (the "Software"), to deal in the Software without restriction, 
+  #   including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 
+  #   and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, 
+  #   subject to the following conditions:
+  # 
+  #   The above copyright notice and this permission notice shall be included in all copies or substantial 
+  #   portions of the Software.
+  # 
+  #   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT 
+  #   LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN 
+  #   NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 
+  #   WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
+  #   SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+  #
+  module StringExt
+    
+    # camelize converts self to UpperCamelCase. If the argument to 
+    # camelize is set to :lower then camelize produces lowerCamelCase.
+    # camelize will also convert '/' to '::' which is useful for
+    # converting paths to namespaces.
+    def camelize(first_letter = :upper)
+      case first_letter
+      when :upper then self.to_s.gsub(/\/(.?)/) { "::" + $1.upcase }.gsub(/(^|_)(.)/) { $2.upcase }
+      when :lower then self.first + camelize[1..-1]
+      end
+    end
+    
+    # The reverse of camelize. Makes an underscored, lowercase form 
+    # from self.  underscore will also change '::' to '/' to convert 
+    # namespaces to paths.
+    def underscore
+      self.gsub(/::/, '/').
+      gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+      gsub(/([a-z\d])([A-Z])/,'\1_\2').
+      tr("-", "_").
+      downcase
+    end
+  end
+end
+
+class String # :nodoc:
+  include Root::StringExt
+end

data/lib/root/utils.rb

@@ -0,0 +1,391 @@
+require 'root/versions'
+autoload(:FileUtils, 'fileutils')
+
+class Root
+  module Utils
+    include Versions
+    
+    # Regexp to match a windows-style root filepath.
+    WIN_ROOT_PATTERN = /^[A-z]:\//
+    
+    module_function
+    
+    # Returns the filepath of path relative to dir.  Both dir and path are
+    # expanded before the relative filepath is determined.  Returns nil if 
+    # the path is not relative to dir.
+    #
+    #   relative_filepath('dir', "dir/path/to/file.txt")  # => "path/to/file.txt"
+    #
+    def relative_filepath(dir, path, dir_string=Dir.pwd)
+      expanded_dir = File.expand_path(dir, dir_string)
+      expanded_path = File.expand_path(path, dir_string)
+
+      return nil unless expanded_path.index(expanded_dir) == 0
+    
+      # 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] || ""
+    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.    
+    #
+    #    translate("/path/to/file.txt", "/path", "/another/path")  # => '/another/path/to/file.txt'
+    #
+    def translate(path, source_dir, target_dir)
+      unless relative_path = relative_filepath(source_dir, path)
+        raise ArgumentError, "\n#{path}\nis not relative to:\n#{source_dir}"
+      end
+      File.join(target_dir, relative_path)
+    end
+    
+    # Returns the path, exchanging the extension with extname.  Extname may
+    # optionally omit the leading period.
+    #
+    #   exchange('path/to/file.txt', '.html')  # => 'path/to/file.html'
+    #   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)
+      patterns.collect do |pattern| 
+        Dir.glob(pattern)
+      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.
+    def vglob(path, *vpatterns)
+      vpatterns << "*" if vpatterns.empty?
+      vpatterns.collect do |vpattern| 
+        results = Dir.glob(version(path, vpattern)) 
+  
+        # extra work to include the default version path for any version
+        results << path if vpattern == "*" && File.exists?(path)
+        results
+      end.flatten.uniq
+    end
+    
+    # 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)
+        Dir.glob(File.join(base, suffix_pattern))
+      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.
+    def chdir(dir, mkdir=false, &block)
+      dir = File.expand_path(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
+    
+    # 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 
+      when File.expand_path(".")[0] == ?/ then :nix
+      else :unknown
+      end
+    end
+    
+    # Returns true if the input path appears to be an expanded path, based on
+    # path_root_type.  
+    #
+    # If root_type == :win returns true if the path matches WIN_ROOT_PATTERN.
+    #
+    #   expanded?('C:/path')  # => true
+    #   expanded?('c:/path')  # => true
+    #   expanded?('D:/path')  # => true
+    #   expanded?('path')     # => false
+    #
+    # If root_type == :nix, then expanded? returns true if the path begins
+    # with '/'.
+    #
+    #   expanded?('/path')  # => true
+    #   expanded?('path')   # => false
+    #
+    # Otherwise expanded? always returns nil.
+    def expanded?(path, root_type=path_root_type)
+      case root_type
+      when :win 
+        path =~ WIN_ROOT_PATTERN ? true : false
+      when :nix  
+        path[0] == ?/
+      else
+        nil
+      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:
+    #
+    #   minimize ['path/to/a.rb', 'path/to/b.rb']
+    #   # => ['a', 'b']
+    #
+    #   minimize ['path/to/a-0.1.0.rb', 'path/to/b-0.1.0.rb']
+    #   # => ['a', 'b']
+    #
+    #   minimize ['path/to/file.rb', 'path/to/file.txt']
+    #   # => ['file.rb', 'file.txt']
+    #
+    #   minimize ['path-0.1/to/file.rb', 'path-0.2/to/file.rb']
+    #   # => ['path-0.1/to/file', 'path-0.2/to/file']
+    #
+    # Minimized paths that carry their extension will always carry
+    # their version as well, but the converse is not true; paths
+    # can be minimized to carry just the version and not the path
+    # extension.
+    #
+    #   minimize ['path/to/a-0.1.0.rb', 'path/to/a-0.1.0.txt']
+    #   # => ['a-0.1.0.rb', 'a-0.1.0.txt']
+    #
+    #   minimize ['path/to/a-0.1.0.rb', 'path/to/a-0.2.0.rb']
+    #   # => ['a-0.1.0', 'a-0.2.0']
+    #
+    # If a block is given, each (path, mini-path) pair will be passed
+    # to it after minimization.
+    def minimize(paths) # :yields: path, mini_path
+      unless block_given?
+        mini_paths = []
+        minimize(paths) {|p, mp| mini_paths << mp }
+        return mini_paths  
+      end
+      
+      splits = paths.uniq.collect do |path|
+        extname = File.extname(path)
+        extname = '' if extname =~ /^\.\d+$/
+        base = File.basename(path.chomp(extname))
+        version = base =~ /(-\d+(\.\d+)*)$/ ? $1 : ''
+        
+        [dirname_or_array(path), base.chomp(version), extname, version, false, path]
+      end
+
+      while !splits.empty?
+        index = 0
+        splits = splits.collect do |(dir, base, extname, version, flagged, path)|
+          index += 1
+          case
+          when !flagged && just_one?(splits, index, base)
+            
+            # found just one
+            yield(path, base)
+            nil
+          when dir.kind_of?(Array)
+            
+            # no more path segments to use, try to add
+            # back version and extname
+            if dir.empty?
+              dir << File.dirname(base)
+              base = File.basename(base)
+            end
+            
+            case
+            when !version.empty?
+              # add back version (occurs first)
+              [dir, "#{base}#{version}", extname, '', false, path]
+              
+            when !extname.empty?
+              
+              # add back extension (occurs second)
+              [dir, "#{base}#{extname}", '', version, false, path]
+            else
+              
+              # nothing more to distinguish... path is minimized (occurs third)
+              yield(path, min_join(dir[0], base))
+              nil
+            end
+          else
+
+            # shift path segment.  dirname_or_array returns an
+            # array if this is the last path segment to shift.
+            [dirname_or_array(dir), min_join(File.basename(dir), base), extname, version, false, path]
+          end
+        end.compact
+      end
+    end
+    
+    # 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
+    # * if mini_path doesn't specify a version, then mini_path
+    #   must only match path up to the path basename (minus the
+    #   version and extname)
+    #
+    # For example:
+    #
+    #   minimal_match?('dir/file-0.1.0.rb', 'file')           # => true
+    #   minimal_match?('dir/file-0.1.0.rb', 'dir/file')       # => true
+    #   minimal_match?('dir/file-0.1.0.rb', 'file-0.1.0')     # => true
+    #   minimal_match?('dir/file-0.1.0.rb', 'file-0.1.0.rb')  # => true
+    #
+    #   minimal_match?('dir/file-0.1.0.rb', 'file.rb')        # => false
+    #   minimal_match?('dir/file-0.1.0.rb', 'file-0.2.0')     # => false
+    #   minimal_match?('dir/file-0.1.0.rb', 'another')        # => false
+    #
+    # In matching, partial basenames are not allowed but partial directories
+    # are allowed.  Hence:
+    #
+    #   minimal_match?('dir/file-0.1.0.txt', 'file')          # => true
+    #   minimal_match?('dir/file-0.1.0.txt', 'ile')           # => false
+    #   minimal_match?('dir/file-0.1.0.txt', 'r/file')        # => true
+    #
+    def minimal_match?(path, mini_path)
+      extname = non_version_extname(mini_path)
+      version = mini_path =~ /(-\d+(\.\d+)*)#{extname}$/ ? $1 : ''
+ 
+      match_path = case
+      when !extname.empty?
+        # force full match
+        path
+      when !version.empty?
+        # match up to version
+        path.chomp(non_version_extname(path))
+      else
+        # match up base
+        path.chomp(non_version_extname(path)).sub(/(-\d+(\.\d+)*)$/, '')
+      end
+      
+      # key ends with pattern AND basenames of each are equal... 
+      # the last check ensures that a full path segment has 
+      # been specified
+      match_path[-mini_path.length, mini_path.length] == mini_path  && File.basename(match_path) == File.basename(mini_path)
+    end
+    
+    # Returns the path segments for the given path, splitting along the path 
+    # divider.  Root paths are always represented by a string, if only an 
+    # empty string.
+    #
+    #   os          divider    example
+    #   windows     '\'        split('C:\path\to\file')  # => ["C:", "path", "to", "file"]
+    #   *nix        '/'        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.  
+    #
+    # On windows (note that expanding paths allows the use of slashes or
+    # backslashes):
+    #
+    #   Dir.pwd                                               # => 'C:/'
+    #   split('path\to\..\.\to\file')                    # => ["C:", "path", "to", "file"]
+    #   split('path/to/.././to/file', false)             # => ["path", "to", "file"]
+    #
+    # On *nix (or more generally systems with '/' roots):
+    #
+    #   Dir.pwd                                               # => '/'
+    #   split('path/to/.././to/file')                    # => ["", "path", "to", "file"]
+    #   split('path/to/.././to/file', false)             # => ["path", "to", "file"]
+    #
+    def split(path, expand_path=true, expand_dir=Dir.pwd)
+      path = if expand_path
+        File.expand_path(path, expand_dir)
+      else
+        # normalize the path by expanding it, then
+        # work back to the relative filepath as needed
+        expanded_dir = File.expand_path(expand_dir)
+        expanded_path = File.expand_path(path, expand_dir)
+        expanded_path.index(expanded_dir) != 0 ? expanded_path : relative_filepath(expanded_dir, expanded_path)
+      end
+
+      segments = path.scan(/[^\/]+/)
+
+      # add back the root filepath as needed on *nix 
+      segments.unshift "" if path[0] == ?/
+      segments
+    end
+    
+    # utility method for minimize -- joins the
+    # dir and path, preventing results like:
+    #
+    #   "./path"
+    #   "//path"
+    #
+    def min_join(dir, path) # :nodoc:
+      case dir
+      when "." then path
+      when "/" then "/#{path}"
+      else "#{dir}/#{path}"
+      end
+    end
+    
+    # utility method for minimize -- returns the 
+    # dirname of path, or an array if the dirname
+    # is effectively empty.
+    def dirname_or_array(path) # :nodoc:
+      dir = File.dirname(path)
+      case dir
+      when path, '.' then []
+      else dir
+      end
+    end
+    
+    # utility method for minimize -- determines if there 
+    # is just one of the base in splits, while flagging
+    # all matching entries.
+    def just_one?(splits, index, base) # :nodoc:
+      just_one = true
+      index.upto(splits.length-1) do |i|
+        if splits[i][1] == base
+          splits[i][4] = true
+          just_one = false
+        end
+      end
+      
+      just_one
+    end
+    
+    # utility method for minimal_match --  returns a non-version 
+    # extname, or an empty string if the path ends in a version.
+    def non_version_extname(path) # :nodoc:
+      extname = File.extname(path)
+      extname =~ /^\.\d+$/ ? '' : extname
+    end
+    
+  end
+end

data/lib/root/versions.rb

@@ -0,0 +1,134 @@
+class Root
+    
+  # Version provides methods for adding, removing, and incrementing versions
+  # at the end of filepaths.  Versions are all formatted like:
+  # 'filepath-version.extension'.
+  #
+  module Versions
+    
+    # Adds a version to the filepath.  Versioned filepaths follow the format:
+    # 'path-version.extension'.  If no version is specified, then the
+    # filepath is returned.
+    #
+    #   version("path/to/file.txt", 1.0)            # => "path/to/file-1.0.txt"
+    #
+    def version(path, version)
+      version = version.to_s.strip
+      if version.empty? 
+        path
+      else
+        extname = File.extname(path)
+        path.chomp(extname) + '-' + version + extname
+      end
+    end
+    
+    # Increments the version of the filepath by the specified increment.  
+    #
+    #   increment("path/to/file-1.0.txt", "0.0.1")  # => "path/to/file-1.0.1.txt"
+    #   increment("path/to/file.txt", 1.0)          # => "path/to/file-1.0.txt"
+    #
+    def increment(path, increment)
+      path, version = deversion(path)
+      
+      # split the version and increment into integer arrays of equal length
+      increment, version = [increment, version].collect do |vstr| 
+        begin
+          vstr.to_s.split(/\./).collect {|v| v.to_i}
+        rescue
+          raise "Bad version or increment: #{vstr}"
+        end
+      end
+      version.concat Array.new(increment.length - version.length, 0) if increment.length > version.length
+
+      # add the increment to version
+      0.upto(version.length-1) do |i|
+        version[i] += (increment[i] || 0)
+      end
+
+      self.version(path, version.join("."))
+    end
+    
+    # Splits the version from the input path, then returns the path and
+    # version. If no version is specified, then the returned version will be
+    # nil.
+    #
+    #   deversion("path/to/file-1.0.txt")           # => ["path/to/file.txt", "1.0"]
+    #   deversion("path/to/file.txt")               # => ["path/to/file.txt", nil]
+    #
+    def deversion(path)
+      extname = File.extname(path)
+      extname = '' if extname =~ /^\.\d+$/
+      path =~ /^(.*)-(\d(\.?\d)*)#{extname}$/ ? [$1 + extname, $2] : [path, nil]
+    end
+    
+    # A <=> comparison for versions.  compare_versions can take strings,
+    # integers, or even arrays representing the parts of a version.
+    #
+    #   compare_versions("1.0.0", "0.9.9")          # => 1
+    #   compare_versions(1.1, 1.1)                  # => 0
+    #   compare_versions([0,9], [0,9,1])            # => -1
+    def compare_versions(a,b)
+      a, b = [a,b].collect {|item| to_integer_array(item) }
+      
+      # equalize the lengths of the integer arrays
+      d = b.length - a.length
+      case 
+      when d < 0 then b.concat Array.new(-d, 0)
+      when d > 0 then a.concat Array.new(d, 0)
+      end 
+    
+      a <=> b
+    end
+    
+    # Version unique.  Select the latest or earliest versions of each file
+    # in the array.  For paths that have no version, vniq considers any
+    # version to beat no version.  The order of paths is preserved by
+    # default, but the extra sort doing so may be turned off.
+    #
+    #   paths = [
+    #    "/path/to/two-0.0.1.txt",
+    #    "/path/to/one-0.0.1.txt",
+    #    "/path/to/one.txt",
+    #    "/path/to/two-1.0.1.txt",
+    #    "/path/to/three.txt"]
+    #
+    #   vniq(paths)
+    #   # => [
+    #   # "/path/to/one-0.0.1.txt",
+    #   # "/path/to/two-1.0.1.txt",
+    #   # "/path/to/three.txt"]
+    #
+    def vniq(array, earliest=false, preserve_order=true)
+      unique = {}
+      array.sort.each do |path|
+        base, version = deversion(path)
+        (unique[base] ||= []) << version
+      end
+      
+      results = []
+      unique.each_pair do |base, versions|
+        versions = versions.sort {|a, b| compare_versions(a,b) }
+        winner = earliest ? versions.shift : versions.pop
+        results << version(base, winner)
+      end
+      
+      results = results.sort_by do |path|
+        array.index(path)
+      end if preserve_order
+      
+      results
+    end
+    
+    private
+    
+    # Converts an input argument (typically a string or an array) to an
+    # array of integers.  Splits version string on "."
+    def to_integer_array(arg)
+      arr = case arg
+      when Array then arg
+      else arg.to_s.split('.')
+      end
+      arr.collect {|i| i.to_i}
+    end
+  end
+end