path 1.3.0

data/lib/path/implementation.rb

@@ -0,0 +1,294 @@
+# Path's low-level implementation based on Pathname
+
+class Path
+  # @private
+  SAME_PATHS = if File::FNM_SYSCASE.nonzero?
+    lambda { |a,b| a.casecmp(b).zero? }
+  else
+    lambda { |a,b| a == b }
+  end
+
+  # Returns a cleaned version of +self+ with consecutive slashes and useless dots removed.
+  # The filesystem is not accessed.
+  #
+  # If +consider_symlink+ is +true+, then a more conservative algorithm is used
+  # to avoid breaking symbolic linkages. This may retain more +..+
+  # entries than absolutely necessary, but without accessing the filesystem,
+  # this can't be avoided. See {#realpath}.
+  def clean(consider_symlink = false)
+    consider_symlink ? cleanpath_conservative : cleanpath_aggressive
+  end
+  alias :cleanpath :clean
+
+  # #parent returns the parent directory.
+  # This can be chained.
+  def parent
+    self / '..'
+  end
+
+  # Path#/ appends a path fragment to this one to produce a new Path.
+  #
+  #   p = Path.new("/usr")  # => #<Path /usr>
+  #   p / "bin/ruby"        # => #<Path /usr/bin/ruby>
+  #   p / "/etc/passwd"     # => #<Path /etc/passwd>
+  #
+  # This method doesn't access the file system, it is pure string manipulation.
+  def /(other)
+    Path.new(plus(@path, other.to_s))
+  end
+
+  # Configures the behavior of {Path#+}. The default is +:warning+.
+  #
+  #   Path + :defined # aliased to Path#/
+  #   Path + :warning # calls Path#/ but warns
+  #   Path + :error   # not defined
+  #   Path + :string  # like String#+. Warns if $VERBOSE (-w)
+  #
+  # @param config [:defined, :warning, :error, :string] the configuration value
+  def Path.+(config)
+    unless [:defined, :warning, :error, :string].include? config
+      raise ArgumentError, "Invalid configuration: #{config.inspect}"
+    end
+    if @plus_configured
+      raise "Path.+ has already been called: #{@plus_configured}"
+    end
+    remove_method :+ if method_defined? :+
+    case config
+    when :defined
+      alias :+ :/
+    when :warning
+      def +(other)
+        warn 'Warning: use of deprecated Path#+ as Path#/: ' <<
+             "#{inspect} + #{other.inspect}\n#{caller.first}"
+        self / other
+      end
+    when :error
+      # nothing to do, the method has been removed
+    when :string
+      def +(other)
+        warn 'Warning: use of deprecated Path#+ as String#+: ' <<
+             "#{inspect} + #{other.inspect}\n#{caller.first}" if $VERBOSE
+        Path(to_s + other.to_s)
+      end
+    end
+    @plus_configured = caller.first
+  end
+
+  @plus_configured = nil # Initialization
+  Path + :warning
+  @plus_configured = nil # Let the user overrides this default configuration
+
+  # @!method +(other)
+  #   The behavior depends on the configuration with Path.{Path.+}.
+  #   It might behave as {Path#/}, String#+, give warnings,
+  #   or not be defined at all.
+
+  # Joins paths.
+  #
+  #   path0.join(path1, ..., pathN)
+  #   # is the same as
+  #   path0 / path1 / ... / pathN
+  def join(*paths)
+    result = nil
+    paths.reverse_each { |path|
+      result = Path.new(path) / result
+      return result if result.absolute?
+    }
+    self / result
+  end
+
+  # #relative_path_from returns a relative path from the argument to the
+  # receiver. They must be both relative or both absolute.
+  #
+  # #relative_path_from doesn't access the filesystem. It assumes no symlinks.
+  #
+  # @raise [ArgumentError] if it cannot find a relative path:
+  #   Either the base is relative and contains '..' (in that case you can expand
+  #   both paths) or the paths are absolutes and on different drives (Windows).
+  def relative_path_from(base_directory)
+    dest = clean.path
+    base = Path.new(base_directory).clean.path
+    dest_prefix, dest_names = split_names(dest)
+    base_prefix, base_names = split_names(base)
+
+    unless SAME_PATHS[dest_prefix, base_prefix]
+      raise ArgumentError, "different prefix: #{self.inspect} and #{base_directory.inspect}"
+    end
+    while d = dest_names.first and b = base_names.first and SAME_PATHS[d, b]
+      dest_names.shift
+      base_names.shift
+    end
+    raise ArgumentError, "base_directory has ..: #{base_directory.inspect}" if base_names.include? '..'
+    # the number of names left in base is the ones we have to climb
+    names = base_names.fill('..').concat(dest_names)
+    return Path.new('.') if names.empty?
+    Path.new(*names)
+  end
+  alias :relative_to :relative_path_from
+  alias :% :relative_path_from
+
+  # @private
+  module Helpers
+    private
+
+    # remove the leading . of +ext+ if present.
+    def pure_ext(ext)
+      ext = ext.to_s and ext.start_with?('.') ? ext[1..-1] : ext
+    end
+
+    # add a leading . to +ext+ if missing. Returns '' if +ext+ is empty.
+    def dotted_ext(ext)
+      ext = ext.to_s and (ext.empty? or ext.start_with?('.')) ? ext : ".#{ext}"
+    end
+  end
+
+  include Helpers
+  extend Helpers
+
+  private
+
+  def init
+    @path = validate(@path)
+
+    taint if @path.tainted?
+    @path.freeze
+    freeze
+  end
+
+  def validate(path)
+    raise ArgumentError, "path contains a null byte: #{path.inspect}" if path.include? "\0"
+    path.gsub!(File::ALT_SEPARATOR, '/') if File::ALT_SEPARATOR
+    path = File.expand_path(path) if path.start_with? '~'
+    path
+  end
+
+  # chop_basename(path) -> [pre-basename, basename] or nil
+  def chop_basename(path)
+    base = File.basename(path)
+    if base.empty? or base == '/'
+      return nil
+    else
+      return path[0, path.rindex(base)], base
+    end
+  end
+
+  def is_absolute?(path)
+    path.start_with?('/') or (path =~ /\A[a-zA-Z]:\// and is_root?($&))
+  end
+
+  def is_root?(path)
+    chop_basename(path) == nil and path.include?('/')
+  end
+
+  # split_names(path) -> prefix, [name, ...]
+  def split_names(path)
+    names = []
+    while r = chop_basename(path)
+      path, basename = r
+      names.unshift basename if basename != '.'
+    end
+    return path, names
+  end
+
+  def prepend_prefix(prefix, relnames)
+    relpath = File.join(*relnames)
+    if relpath.empty?
+      File.dirname(prefix)
+    elsif prefix.include? '/'
+      # safe because File.dirname returns a new String
+      add_trailing_separator(File.dirname(prefix)) << relpath
+    else
+      prefix + relpath
+    end
+  end
+
+  def has_trailing_separator?(path)
+    !is_root?(path) and path.end_with?('/')
+  end
+
+  def add_trailing_separator(path) # mutates path
+    path << '/' unless path.end_with? '/'
+    path
+  end
+
+  def del_trailing_separator(path)
+    if r = chop_basename(path)
+      pre, basename = r
+      pre + basename
+    elsif %r{/+\z} =~ path
+      $` + File.dirname(path)[%r{/*\z}]
+    else
+      path
+    end
+  end
+
+  # remove '..' segments since root's parent is root
+  def remove_root_parents(prefix, names)
+    names.shift while names.first == '..' if is_root?(prefix)
+  end
+
+  # Clean the path simply by resolving and removing excess "." and ".." entries.
+  # Nothing more, nothing less.
+  def cleanpath_aggressive
+    pre = @path
+    names = []
+    while r = chop_basename(pre)
+      pre, base = r
+      if base == '.'
+        # do nothing, it can be ignored
+      elsif names.first == '..' and base != '..'
+        # base can be ignored as we go back to its parent
+        names.shift
+      else
+        names.unshift base
+      end
+    end
+    remove_root_parents(pre, names)
+    Path.new(prepend_prefix(pre, names))
+  end
+
+  def cleanpath_conservative
+    path = @path
+    pre, names = split_names(path)
+    remove_root_parents(pre, names)
+    if names.empty?
+      Path.new(File.dirname(pre))
+    else
+      names << '.' if names.last != '..' and File.basename(path) == '.'
+      result = prepend_prefix(pre, names)
+      if names.last != '.' and names.last != '..' and has_trailing_separator?(path)
+        Path.new(add_trailing_separator(result))
+      else
+        Path.new(result)
+      end
+    end
+  end
+
+  def plus(prefix, rel)
+    return rel if is_absolute?(rel)
+    _, names = split_names(rel)
+
+    loop do
+      # break if that was the last segment
+      break unless r = chop_basename(prefix)
+      prefix, name = r
+      next if name == '.'
+
+      # break if we can't resolve anymore
+      if name == '..' or names.first != '..'
+        prefix << name
+        break
+      end
+      names.shift
+    end
+
+    remove_root_parents(prefix, names)
+    has_prefix = chop_basename(prefix)
+    if names.empty?
+      has_prefix ? prefix : File.dirname(prefix)
+    else
+      suffix = File.join(*names)
+      has_prefix ? File.join(prefix, suffix) : prefix + suffix
+    end
+  end
+end

data/lib/path/io.rb

@@ -0,0 +1,104 @@
+class Path
+  # @!group IO
+
+  # Opens the file for reading or writing. See +File.open+.
+  # @yieldparam [File] file
+  def open(*args, &block)
+    File.open(@path, *args, &block)
+  end
+
+  # Iterates over the lines in the file. See +IO.foreach+.
+  # @yieldparam [String] line
+  def each_line(*args, &block)
+    IO.foreach(@path, *args, &block)
+  end
+  alias :lines :each_line
+
+  # Returns all data from the file, or the first +bytes+ bytes if specified.
+  # See +IO.read+.
+  def read(*args)
+    IO.read(@path, *args)
+  end
+
+  if IO.respond_to? :binread
+    # Returns all the bytes from the file, or the first +N+ if specified.
+    # See +IO.binread+.
+    def binread(*args)
+      IO.binread(@path, *args)
+    end
+  else
+    def binread(*args)
+      open('rb', &:read)
+    end
+  end
+
+  # Returns all the lines from the file. See +IO.readlines+.
+  def readlines(*args)
+    IO.readlines(@path, *args)
+  end
+
+  # See +IO.sysopen+.
+  def sysopen(*args)
+    IO.sysopen(@path, *args)
+  end
+
+  if IO.respond_to? :write
+    # Writes +contents+ to +self+. See +IO.write+ or +IO#write+.
+    def write(contents, *open_args)
+      IO.write(@path, contents, *open_args)
+    end
+  else
+    def write(contents, *open_args)
+      open('w', *open_args) { |f| f.write(contents) }
+    end
+  end
+
+  if IO.respond_to? :binwrite
+    # Writes +contents+ to +self+. See +IO.binwrite+.
+    def binwrite(contents, *open_args)
+      IO.binwrite(@path, contents, *open_args)
+    end
+  else
+    def binwrite(contents, *open_args)
+      open('wb', *open_args) { |f| f.write(contents) }
+    end
+  end
+
+  if IO.respond_to? :write and !RUBY_DESCRIPTION.start_with?('jruby')
+    # Appends +contents+ to +self+. See +IO.write+ or +IO#write+.
+    def append(contents, open_args = {})
+      open_args[:mode] = 'a'
+      IO.write(@path, contents, open_args)
+    end
+  else
+    def append(contents, *open_args)
+      open('a', *open_args) { |f| f.write(contents) }
+    end
+  end
+
+  # Rewrites contents of +self+.
+  #
+  #    Path('file').rewrite { |contents| contents.reverse }
+  #
+  # @yieldparam [String] contents
+  # @yieldreturn [String] contents to write
+  def rewrite
+    write yield read
+  end
+
+  # Returns the first +bytes+ bytes of the file.
+  # If the file size is smaller than +bytes+, return the whole contents.
+  def head(bytes)
+    read(bytes)
+  end
+
+  # Returns the last +bytes+ bytes of the file.
+  # If the file size is smaller than +bytes+, return the whole contents.
+  def tail(bytes)
+    return read if size < bytes
+    open { |f|
+      f.seek(-bytes, IO::SEEK_END)
+      f.read
+    }
+  end
+end

data/lib/path/load.rb

@@ -0,0 +1,29 @@
+class Path
+  # @!group Loading
+
+  # The list of loaders. See {Path.register_loader}.
+  LOADERS = {}
+
+  # Registers a new loader (a block which will be called with the Path to load)
+  # for the given extensions (either with the leading dot or not)
+  #
+  #     Path.register_loader('.marshal') { |file| Marshal.load file.read }
+  #
+  # @yieldparam [Path] path
+  def self.register_loader(*extensions, &loader)
+    extensions.each { |ext|
+      LOADERS[pure_ext(ext)] = loader
+    }
+  end
+
+  # Path#load helps loading data from various files.
+  # JSON and YAML loaders are provided by default.
+  # See {Path.register_loader}.
+  def load
+    if LOADERS.key? ext
+      LOADERS[ext].call(self)
+    else
+      raise "Unable to load #{self} (unrecognized extension)"
+    end
+  end
+end

data/lib/path/parts.rb

@@ -0,0 +1,136 @@
+class Path
+  # @!group Path parts
+
+  # Returns the last component of the path. See +File.basename+.
+  def basename(*args)
+    Path.new(File.basename(@path, *args))
+  end
+
+  # basename(extname)
+  def base
+    basename(extname)
+  end
+
+  # Returns all but the last component of the path.
+  #
+  # Don't chain this when the path is relative:
+  #     Path('.').dir # => #<Path .>
+  # Use #parent instead.
+  # See +File.dirname+.
+  def dirname
+    Path.new(File.dirname(@path))
+  end
+  alias :dir :dirname
+
+  # Returns the extension, with a leading dot. See +File.extname+.
+  def extname
+    File.extname(@path)
+  end
+
+  # {#extname} without leading dot.
+  def ext
+    ext = extname
+    ext.empty? ? ext : ext[1..-1]
+  end
+
+  # Returns the #dirname and the #basename in an Array. See +File.split+.
+  def split
+    File.split(@path).map(&Path)
+  end
+
+  # Adds +ext+ as an extension to +path+.
+  # Handle both extensions with or without leading dot.
+  # No-op if +ext+ is +empty?+.
+  #
+  #   Path('file').add_extension('txt') # => #<Path file.txt>
+  def add_extension(ext)
+    return self if ext.to_s.empty?
+    Path.new @path+dotted_ext(ext)
+  end
+  alias :add_ext :add_extension
+
+  # Removes the last extension of +path+.
+  #
+  #   Path('script.rb').without_extension # => #<Path script>
+  #   Path('archive.tar.gz').without_extension # => #<Path archive.tar>
+  def without_extension
+    Path.new @path[0..-extname.size-1]
+  end
+  alias :rm_ext :without_extension
+
+  # Replaces the last extension of +path+ with +ext+.
+  # Handle both extensions with or without leading dot.
+  # Removes last extension if +ext+ is +empty?+.
+  #
+  #   Path('main.c++').replace_extension('cc') # => #<Path main.cc>
+  def replace_extension(ext)
+    return without_extension if ext.to_s.empty?
+    Path.new(@path[0..-extname.size-1] << dotted_ext(ext))
+  end
+  alias :sub_ext :replace_extension
+
+  # Iterates over each component of the path.
+  #
+  #   Path.new("/usr/bin/ruby").each_filename { |filename| ... }
+  #     # yields "usr", "bin", and "ruby".
+  #
+  # @yieldparam [String] filename
+  def each_filename
+    return to_enum(__method__) unless block_given?
+    _, names = split_names(@path)
+    names.each { |filename| yield filename }
+    nil
+  end
+
+  # Iterates over each element in the given path in descending order.
+  #
+  #  Path.new('/path/to/some/file.rb').descend { |v| p v }
+  #     #<Path />
+  #     #<Path /path>
+  #     #<Path /path/to>
+  #     #<Path /path/to/some>
+  #     #<Path /path/to/some/file.rb>
+  #
+  #  Path.new('path/to/some/file.rb').descend { |v| p v }
+  #     #<Path path>
+  #     #<Path path/to>
+  #     #<Path path/to/some>
+  #     #<Path path/to/some/file.rb>
+  #
+  # It doesn't access actual filesystem.
+  # @yieldparam [Path] path
+  def descend
+    return to_enum(:descend) unless block_given?
+    ascend.reverse_each { |v| yield v }
+    nil
+  end
+
+  # Iterates over each element in the given path in ascending order.
+  #
+  #  Path.new('/path/to/some/file.rb').ascend { |v| p v }
+  #     #<Path /path/to/some/file.rb>
+  #     #<Path /path/to/some>
+  #     #<Path /path/to>
+  #     #<Path /path>
+  #     #<Path />
+  #
+  #  Path.new('path/to/some/file.rb').ascend { |v| p v }
+  #     #<Path path/to/some/file.rb>
+  #     #<Path path/to/some>
+  #     #<Path path/to>
+  #     #<Path path>
+  #
+  # It doesn't access actual filesystem.
+  # @yieldparam [Path] path
+  def ascend
+    return to_enum(:ascend) unless block_given?
+    path = @path
+    yield self
+    while r = chop_basename(path)
+      path, = r
+      break if path.empty?
+      yield Path.new(del_trailing_separator(path))
+    end
+  end
+  alias :ancestors :ascend
+end