path 1.3.0

data/lib/path/file.rb

@@ -0,0 +1,132 @@
+class Path
+  # @!group File
+
+  # Returns last access time. See +File.atime+.
+  def atime
+    File.atime(@path)
+  end
+
+  # Returns last change time (of the directory entry, not the file itself).
+  # See +File.ctime+.
+  def ctime
+    File.ctime(@path)
+  end
+
+  # Returns last modification time. See +File.mtime+.
+  def mtime
+    File.mtime(@path)
+  end
+
+  # Changes permissions of +path+. See +File.chmod+.
+  def chmod(mode)
+    File.chmod(mode, @path)
+  end
+
+  # Changes permissions of +path+, not following symlink. See +File.lchmod+.
+  def lchmod(mode)
+    File.lchmod(mode, @path)
+  end
+
+  # Changes the owner and group of the file. See +File.chown+.
+  def chown(owner, group)
+    File.chown(owner, group, @path)
+  end
+
+  # Changes the owner and group of +path+, not following symlink.
+  # See +File.lchown+.
+  def lchown(owner, group)
+    File.lchown(owner, group, @path)
+  end
+
+  # Returns "type" of file ("file", "directory", etc). See +File.ftype+.
+  def ftype
+    File.ftype(@path)
+  end
+
+  # Creates a hard link to +target+ and returns self.
+  #
+  # Raises Errno::EEXIST if self already exist.
+  # See +File.link+ (arguments are swapped).
+  def make_link(target)
+    File.link(target, @path)
+    self
+  end
+
+  # Reads the symbolic link. See +File.readlink+.
+  def readlink
+    Path.new(File.readlink(@path))
+  end
+
+  # Renames the file and returns the new Path. See +File.rename+.
+  def rename(to)
+    File.rename(@path, to)
+    Path(to)
+  end
+
+  # Returns the stat of +path+ as a +File::Stat+ object. See +File.stat+.
+  def stat
+    File.stat(@path)
+  end
+
+  # Returns the stat of +path+ as a +File::Stat+ object, not following symlink. See +File.lstat+.
+  def lstat
+    File.lstat(@path)
+  end
+
+  # Returns the file size in bytes. See +File.size+.
+  def size
+    File.size(@path)
+  end
+
+  # Creates a symbolic link to +target+ and returns self.
+  #
+  # Raises Errno::EEXIST if self already exist.
+  # See +File.symlink+ (arguments are swapped).
+  def make_symlink(target)
+    File.symlink(target, @path)
+    self
+  end
+
+  # Truncates the file to +length+ bytes. See +File.truncate+.
+  def truncate(length)
+    File.truncate(@path, length)
+  end
+
+  # Removes a file using +File.unlink+.
+  # This is incompatible with Pathname#unlink,
+  # which can also remove directories.
+  # Use {#rmdir} or {#rm_r} for directories.
+  def unlink
+    File.unlink @path
+  end
+  alias :delete :unlink
+
+  # Updates the access and modification times. See +File.utime+.
+  def utime(atime, mtime)
+    File.utime(atime, mtime, @path)
+  end
+
+  # Expands +path+, making it absolute.
+  # If the path is relative, it is expanded with the current working directory,
+  # unless +dir+ is given as an argument. See +File.expand_path+.
+  def expand(*args)
+    Path.new(File.expand_path(@path, *args))
+  end
+  alias :expand_path :expand
+
+  # Returns the real (absolute) path of +self+ in the actual
+  # filesystem not containing symlinks or useless dots.
+  #
+  # All components of the path must exist when this method is called.
+  def realpath(basedir=nil)
+    Path.new(real_path_internal(true, basedir))
+  end
+
+  # Returns the real (absolute) path of +self+ in the actual filesystem.
+  # The real path doesn't contain symlinks or useless dots.
+  #
+  # The last component of the real path can be nonexistent.
+  def realdirpath(basedir=nil)
+    Path.new(real_path_internal(false, basedir))
+  end
+end

data/lib/path/file_predicates.rb

@@ -0,0 +1,151 @@
+# All methods from FileTest and all predicates from File are included
+
+class Path
+  # @!group File predicates
+
+  # See +File.blockdev?+.
+  def blockdev?
+    File.blockdev?(@path)
+  end
+
+  # See +File.chardev?+.
+  def chardev?
+    File.chardev?(@path)
+  end
+
+  # See +File.executable?+.
+  def executable?
+    File.executable?(@path)
+  end
+
+  # See +File.executable_real?+.
+  def executable_real?
+    File.executable_real?(@path)
+  end
+
+  # See +File.exist?+.
+  def exist?
+    File.exist?(@path)
+  end
+  alias :exists? :exist?
+
+  # See +File.grpowned?+.
+  def grpowned?
+    File.grpowned?(@path)
+  end
+
+  # See +File.directory?+.
+  def directory?
+    File.directory?(@path)
+  end
+  alias :dir? :directory?
+
+  # See +File.file?+.
+  def file?
+    File.file?(@path)
+  end
+
+  # See +File.pipe?+.
+  def pipe?
+    File.pipe?(@path)
+  end
+
+  # See +File.socket?+.
+  def socket?
+    File.socket?(@path)
+  end
+
+  # See +File.owned?+.
+  def owned?
+    File.owned?(@path)
+  end
+
+  # See +File.readable?+.
+  def readable?
+    File.readable?(@path)
+  end
+
+  if File.respond_to? :world_readable?
+    # See +File.world_readable?+.
+    def world_readable?
+      File.world_readable?(@path)
+    end
+  else
+    def world_readable?
+      mode = File.stat(@path).mode & 0777
+      mode if (mode & 04).nonzero?
+    end
+  end
+
+  # See +File.readable_real?+.
+  def readable_real?
+    File.readable_real?(@path)
+  end
+
+  # See +File.setuid?+.
+  def setuid?
+    File.setuid?(@path)
+  end
+
+  # See +File.setgid?+.
+  def setgid?
+    File.setgid?(@path)
+  end
+
+  # See +File.size?+.
+  def size?
+    File.size?(@path)
+  end
+
+  # See +File.sticky?+.
+  def sticky?
+    File.sticky?(@path)
+  end
+
+  # See +File.symlink?+.
+  def symlink?
+    File.symlink?(@path)
+  end
+
+  # See +File.writable?+.
+  def writable?
+    File.writable?(@path)
+  end
+
+  if File.respond_to? :world_writable?
+    # See +File.world_writable?+.
+    def world_writable?
+      File.world_writable?(@path)
+    end
+  else
+    def world_writable?
+      mode = File.stat(@path).mode & 0777
+      mode if (mode & 02).nonzero?
+    end
+  end
+
+  # See +File.writable_real?+.
+  def writable_real?
+    File.writable_real?(@path)
+  end
+
+  # See +File.zero?+.
+  # empty? is not defined in File/FileTest, but is is clearer.
+  def zero?
+    File.zero?(@path)
+  end
+  alias :empty? :zero?
+
+  # See +File.identical?+.
+  def identical?(path)
+    File.identical?(@path, path)
+  end
+
+  # Only in File, not FileTest
+
+  # Return +true+ if the receiver matches the given pattern.
+  # See +File.fnmatch?+.
+  def fnmatch?(pattern, *args)
+    File.fnmatch?(pattern, @path, *args)
+  end
+end

data/lib/path/fileutils.rb

@@ -0,0 +1,109 @@
+require 'fileutils'
+
+class Path
+  # @!group File utilities
+
+  # Creates a full path, including any intermediate directories that don't yet exist.
+  # See +FileUtils.mkpath+.
+  def mkpath
+    FileUtils.mkpath(@path)
+    self
+  end
+  alias :mkdir_p :mkpath
+
+  # Deletes a directory and all beneath it. See +FileUtils.rm_r+.
+  def rmtree
+    # The name "rmtree" is borrowed from File::Path of Perl.
+    # File::Path provides "mkpath" and "rmtree".
+    FileUtils.rm_r(@path)
+    self
+  end
+  alias :rm_r :rmtree
+
+  # Removes the file using +FileUtils.rm+.
+  def rm
+    FileUtils.rm(@path)
+    self
+  end
+
+  # Removes the file, ignoring errors, using +FileUtils.rm_f+.
+  def rm_f
+    FileUtils.rm_f(@path)
+    self
+  end
+  alias :safe_unlink :rm_f
+
+  # Removes the file or directory recursively, ignoring errors,
+  # using +FileUtils.rm_f+.
+  def rm_rf
+    FileUtils.rm_rf(@path)
+    self
+  end
+
+  # Copies the file to +to+. See +FileUtils.cp+.
+  def cp(to)
+    # TODO: remove :preserve when all implement it correctly (r31123)
+    FileUtils.cp(@path, to, :preserve => true)
+  end
+  alias :copy :cp
+
+  # Copies the file or directory recursively to the directory +to+.
+  # See +FileUtils.cp_r+.
+  def cp_r(to)
+    FileUtils.cp_r(@path, to)
+  end
+
+  # Updates access and modification time or create an empty file.
+  def touch
+    if exist?
+      now = Time.now
+      File.utime(now, now, @path)
+    else
+      open('w') {}
+    end
+    self
+  end
+
+  # {#touch} preceded by +dir.+{#mkpath}.
+  def touch!
+    dir.mkpath
+    touch
+  end
+
+  # Moves +self+ to the +to+ directory.
+  def mv(to)
+    FileUtils.mv(@path, to)
+    to
+  end
+  alias :move :mv
+
+  # Install +file+ into +path+ (the "prefix", which should be a directory).
+  # If +file+ is not same as +path/file+, replaces it.
+  # See +FileUtils.install+ (arguments are swapped).
+  def install(file, options = {})
+    FileUtils.install(file, @path, options)
+  end
+
+  # Recusively changes permissions. See +FileUtils.chmod_R+ and +File.chmod+.
+  def chmod_r(mode)
+    FileUtils.chmod_R(mode, @path)
+  end
+
+  # Recusively changes owner and group. See +FileUtils.chown_R+ and +File.chown+.
+  def chown_r(owner, group)
+    FileUtils.chown_R(owner, group, @path)
+  end
+
+  # Whether the contents of +path+ and +file+ are identical.
+  # See +FileUtils.compare_file+.
+  def has_same_contents?(file)
+    FileUtils.compare_file(@path, file)
+  end
+
+  # Returns whether +self+ is newer than all +others+.
+  # Non-existent files are older than any file.
+  # See +FileUtils.uptodate?+.
+  def uptodate?(*others)
+    FileUtils.uptodate?(@path, others)
+  end
+end

data/lib/path/find.rb

@@ -0,0 +1,23 @@
+class Path
+  # Path#find is an iterator to traverse a directory tree in a depth first
+  # manner. It yields a Path for each file under "this" directory.
+  #
+  # Returns an enumerator if no block is given.
+  #
+  # Since it is implemented by +find.rb+, +Find.prune+ can be used
+  # to control the traversal.
+  #
+  # If +self+ is +.+, yielded paths begin with a filename in the
+  # current directory, not +./+.
+  #
+  # @yieldparam [Path] path
+  def find
+    return to_enum(__method__) unless block_given?
+    require 'find'
+    if @path == '.'
+      Find.find(@path) { |f| yield Path.new(f.sub(%r{\A\./}, '')) }
+    else
+      Find.find(@path) { |f| yield Path.new(f) }
+    end
+  end
+end

data/lib/path/identity.rb

@@ -0,0 +1,163 @@
+class Path
+  class << self
+    # @!group Identity
+
+    # Creates a new Path. See {#initialize}.
+    def new(*args)
+      if args.size == 1 and Path === args.first
+        args.first
+      else
+        super(*args)
+      end
+    end
+    alias :[] :new
+
+    # A class constructor.
+    #
+    #   %w[foo bar].map(&Path) # == [Path('foo'), Path('bar')]
+    def to_proc
+      lambda { |path| new(path) }
+    end
+
+    # Whether +object+ looks like a path.
+    # The current test checks if the object responds to
+    # #to_path, #path or #to_str.
+    def like? object
+      [:to_path, :path, :to_str].any? { |meth| object.respond_to? meth }
+    end
+
+    # A matcher responding to #===. Useful for case clauses, grep, etc.
+    # See {Path.like?}.
+    #
+    #   case obj
+    #   when Path.like then Path(obj)
+    #   # ...
+    #   end
+    def like
+      @like ||= begin
+        matcher = Object.new
+        def matcher.===(object)
+          Path.like?(object)
+        end
+        matcher
+      end
+    end
+  end
+
+  # @!group Identity
+
+  # Creates a new Path.
+  # If multiple arguments are given, they are joined with File.join.
+  # The path will have File::ALT_SEPARATOR replaced with '/' and
+  # if it begins with a '~', it will be expanded (using File.expand_path).
+  # Accepts an Array of Strings, a Tempfile, anything that respond to #path,
+  # #to_path or #to_str with a String and defaults to calling #to_s.
+  #
+  # @param parts [Array<String>, Tempfile, #to_path, #path, #to_str, #to_s] the path-like object(s)
+  def initialize(*parts)
+    path = parts.size > 1 ? File.join(*parts) : parts.first
+    @path = case path
+    when Tempfile
+      @_tmpfile = path # We would not want it to be GC'd
+      path.path.dup
+    when String
+      path.dup
+    else
+      if path.respond_to? :to_path and String === path.to_path
+        path.to_path.dup
+      elsif path.respond_to? :path and String === path.path
+        path.path.dup
+      elsif path.respond_to? :to_str and String === path.to_str
+        path.to_str.dup
+      else
+        path.to_s.dup
+      end
+    end
+
+    init
+  end
+
+  # Returns the +path+ as a String.
+  # {#path} is implemented for better readability (+file.path+ instead of +file.to_s+) and as an accessor.
+  # {#to_path} is implemented so Path objects are usable with +open+, etc.
+  # {#to_str} is implemented so Path objects are usable with +open+, etc with Ruby 1.8 (it is not defined in Ruby 1.9).
+  attr_reader :path
+  alias :to_s :path
+  alias :to_path :path
+  alias :to_str :path if RUBY_VERSION < '1.9'
+
+  # Compare this path with +other+. The comparison is string-based.
+  # Be aware that two different paths (+foo.txt+ and +./foo.txt+)
+  # can refer to the same file.
+  def == other
+    Path === other and @path == other.path
+  end
+  alias :eql? :==
+
+  # Provides for comparing paths, case-sensitively.
+  def <=>(other)
+    return nil unless Path === other
+    @path.tr('/', "\0") <=> other.path.tr('/', "\0")
+  end
+
+  # The hash value of the +path+.
+  def hash
+    @path.hash
+  end
+
+  # Returns the +path+ as a Symbol.
+  def to_sym
+    @path.to_sym
+  end
+
+  # A representation of the +path+.
+  def inspect
+    "#<Path #{@path}>"
+  end
+
+  # YAML loading.
+  def yaml_initialize(tag, ivars)
+    @path = ivars['path']
+    init
+  end
+
+  # Psych loading.
+  def init_with(coder)
+    @path = coder['path']
+    init
+  end
+
+  # JSON dumping.
+  def to_json(*args)
+    {
+      'json_class' => 'Path',
+      'data'       => @path
+    }.to_json(*args)
+  end
+
+  # JSON loading.
+  def self.json_create json
+    new json['data']
+  end
+
+  # Marshal dumping.
+  def marshal_dump
+    @path
+  end
+
+  # Marshal loading.
+  def marshal_load path
+    @path = path
+    init
+  end
+end
+
+unless defined?(NO_PATH_GLOBAL_FUNCTION)
+  module Kernel
+    # A shorthand method to create a {Path}. Same as {Path.new}.
+    def Path(*args)
+      Path.new(*args)
+    end
+    private :Path
+  end
+end