pleasant_path 1.2.0 → 1.3.0

data/lib/pleasant_path/pathname.rb

@@ -1,22 +1,25 @@
+# frozen_string_literal: true
+
 class Pathname
 
-  # {https://ruby-doc.org/core/File/Constants.html#NULL +File::NULL+} as
-  # a Pathname.  On POSIX systems, this should be equivalent to
+  # {https://docs.ruby-lang.org/en/trunk/File/File/Constants.html#NULL +File::NULL+}
+  # as a Pathname.  On POSIX systems, this should be equivalent to
   # +Pathname.new("/dev/null")+.
   NULL = Pathname.new(File::NULL)
 
   # Returns the Pathname unmodified.  Exists for parity with
   # {String#to_pathname}.
   #
-  # @return [Pathname]
+  # @return [self]
   def to_pathname
     self
   end
 
-  # Joins the parent (+dirname+) of the Pathname with the argument.  The
-  # mnemonic for this operator is that the resultant path goes up one
-  # directory level from the original, then goes down to the directory
-  # specified by the argument.
+  # Joins the Pathname +dirname+ with the given +sibling+.
+  #
+  # The mnemonic for this operator is that the result is formed by going
+  # up one directory level from the original path, then going back down
+  # to +sibling+.
   #
   # @example
   #   Pathname.new("path/to/file1") ^ "file2"  # == Pathname.new("path/to/file2")
@@ -27,7 +30,7 @@ class Pathname
     self.dirname / sibling
   end
 
-  # Returns the +basename+ of the Pathname's parent directory.
+  # Returns the +basename+ of the parent directory (+dirname+).
   #
   # @example
   #   Pathname.new("path/to/file").parentname  # == Pathname.new("to")
@@ -48,13 +51,15 @@ class Pathname
   #
   #   Pathname.new("dir1/file2").existence  # == nil
   #
-  # @return [Pathname, nil]
+  # @return [self, nil]
   def existence
     self if self.exist?
   end
 
-  # Computes the longest path that the Pathname and +other+ have in
-  # common.  See also {File.common_path}.
+  # Returns the longest path that the Pathname and +other+ have in
+  # common.
+  #
+  # @see File.common_path
   #
   # @example
   #   f1 = Pathname.new("dir1/file1")
@@ -79,28 +84,21 @@ class Pathname
   # @return [Boolean]
   alias :dir? :directory?
 
-  # True if the directory indicated by the Pathname contains no other
-  # directories or files.
-  #
-  # @example
-  #   FileUtils.mkdir("parent")
-  #   FileUtils.mkdir("parent/dir1")
+  # @deprecated Use +Pathname#empty?+.
   #
-  #   Pathname.new("parent").dir_empty?       # == false
-  #   Pathname.new("parent/dir1").dir_empty?  # == true
+  # Alias of +Pathname#empty?+.
   #
   # @return [Boolean]
-  def dir_empty?
-    self.children(false).empty?
-  end
+  alias :dir_empty? :empty?
 
-  # Returns the immediate (non-recursive) child directories of the
-  # directory indicated by the Pathname.  Returned Pathnames are
-  # prefixed by the original Pathname.
+  # Returns the immediate child directories of the directory indicated
+  # by the Pathname.  Returned Pathnames are prefixed by the original
+  # Pathname.
   #
   # @example
   #   FileUtils.mkdir("parent")
   #   FileUtils.mkdir("parent/dir1")
+  #   FileUtils.mkdir("parent/dir1/dir1")
   #   FileUtils.mkdir("parent/dir2")
   #   FileUtils.touch("parent/file1")
   #
@@ -111,13 +109,15 @@ class Pathname
   #     #    ]
   #
   # @return [Array<Pathname>]
+  # @raise [SystemCallError]
+  #   if the Pathname does not point to an existing directory
   def dirs
     self.children.tap{|c| c.select!(&:dir?) }
   end
 
-  # Returns the recursively descended child directories of the
-  # directory indicated by the Pathname.  Returned Pathnames are
-  # prefixed by the original Pathname.
+  # Returns all (recursive) descendent directories of the directory
+  # indicated by the Pathname.  Returned Pathnames are prefixed by the
+  # original Pathname, and are in depth-first order.
   #
   # @example
   #   FileUtils.mkdir("parent")
@@ -135,18 +135,48 @@ class Pathname
   #
   # @return [Array<Pathname>]
   def dirs_r
-    self.find.select(&:dir?).tap(&:shift)
+    self.find_dirs.to_a
   end
 
-  # Returns the immediate (non-recursive) child files of the directory
-  # indicated by the Pathname.  Returned Pathnames are prefixed by the
-  # original Pathname.
+  # Iterates over all (recursive) descendent directories of the
+  # directory indicated by the Pathname.  Iterated Pathnames are
+  # prefixed by the original Pathname, and are in depth-first order.
+  #
+  # If no block is given, this method returns an Enumerator.  Otherwise,
+  # the block is called with each descendent Pathname, and this method
+  # returns the original Pathname.
+  #
+  # @see https://docs.ruby-lang.org/en/trunk/Pathname.html#method-i-find Pathname#find
+  #
+  # @overload find_dirs()
+  #   @return [Enumerator<Pathname>]
+  #
+  # @overload find_dirs(&block)
+  #   @yieldparam descendent [Pathname]
+  #   @return [Pathname]
+  def find_dirs
+    return to_enum(__method__) unless block_given?
+
+    self.find do |path|
+      if path.file?
+        Find.prune
+      elsif path != self
+        yield path
+      end
+    end
+
+    self
+  end
+
+  # Returns the immediate child files of the directory indicated by the
+  # Pathname.  Returned Pathnames are prefixed by the original Pathname.
   #
   # @example
   #   FileUtils.mkdir("parent")
   #   FileUtils.touch("parent/file1")
-  #   FileUtils.touch("parent/file2")
   #   FileUtils.mkdir("parent/dir1")
+  #   FileUtils.touch("parent/dir1/file1")
+  #   FileUtils.touch("parent/file2")
   #
   #   Pathname.new("parent").files
   #     # == [
@@ -155,43 +185,68 @@ class Pathname
   #     #    ]
   #
   # @return [Array<Pathname>]
+  # @raise [SystemCallError]
+  #   if the Pathname does not point to an existing directory
   def files
     self.children.tap{|c| c.select!(&:file?) }
   end
 
-  # Returns the recursively descended child files of the directory
-  # indicated by the Pathname.  Returned Pathnames are prefixed by the
-  # original Pathname.
+  # Returns all (recursive) descendent files of the directory indicated
+  # by the Pathname.  Returned Pathnames are prefixed by the original
+  # Pathname, and are in depth-first order.
   #
   # @example
   #   FileUtils.mkdir("parent")
+  #   FileUtils.touch("parent/file1")
   #   FileUtils.mkdir("parent/dir1")
   #   FileUtils.touch("parent/dir1/file1")
-  #   FileUtils.touch("parent/file1")
+  #   FileUtils.touch("parent/file2")
   #
   #   Pathname.new("parent").files_r
   #     # == [
   #     #      Pathname.new("parent/dir1/file1"),
   #     #      Pathname.new("parent/file1")
+  #     #      Pathname.new("parent/file2")
   #     #    ]
   #
   # @return [Array<Pathname>]
   def files_r
-    self.find.select(&:file?)
+    self.find_files.to_a
   end
 
-  # Changes the current working directory to the directory indicated by
-  # the Pathname.  If a block is given, it is called with the Pathname,
-  # and the original working directory is restored after the block
-  # exits.
+  # Iterates over all (recursive) descendent files of the directory
+  # indicated by the Pathname.  Iterated Pathnames are prefixed by the
+  # original Pathname, and are in depth-first order.
+  #
+  # If no block is given, this method returns an Enumerator.  Otherwise,
+  # the block is called with each descendent Pathname, and this method
+  # returns the original Pathname.
   #
-  # Returns the return value of the block, if one is given.  Otherwise,
-  # returns the Pathname.
+  # @see https://docs.ruby-lang.org/en/trunk/Pathname.html#method-i-find Pathname#find
   #
-  # Raises an exception if the directory indicated by the Pathname does
-  # not exist.
+  # @overload find_files()
+  #   @return [Enumerator<Pathname>]
+  #
+  # @overload find_files(&block)
+  #   @yieldparam descendent [Pathname]
+  #   @return [Pathname]
+  def find_files
+    return to_enum(__method__) unless block_given?
+
+    self.find do |path|
+      yield path if path.file?
+    end
+
+    self
+  end
+
+  # Changes the current working directory to the Pathname.  If no block
+  # is given, this method returns the Pathname.  Otherwise, the block is
+  # called with the Pathname, the original working directory is restored
+  # after the block exits, this method returns the return value of the
+  # block.
   #
-  # See also +Dir::chdir+.
+  # @see https://docs.ruby-lang.org/en/trunk/Dir.html#method-c-chdir Dir.chdir
   #
   # @example
   #   FileUtils.mkdir("dir1")
@@ -205,12 +260,14 @@ class Pathname
   #
   # @overload chdir()
   #   @return [Pathname]
-  # @overload chdir()
-  #   @yieldparam path [Pathname]
-  #   @yieldreturn [Object] block_retval
-  #   @return [block_retval]
+  #
+  # @overload chdir(&block)
+  #   @yieldparam working_dir [Pathname]
+  #   @yieldreturn [Object] retval
+  #   @return [retval]
+  #
   # @raise [SystemCallError]
-  #   if the directory does not exist
+  #   if the Pathname does not point to an existing directory
   def chdir
     if block_given?
       Dir.chdir(self) do |dir|
@@ -222,7 +279,10 @@ class Pathname
     end
   end
 
-  # Alias of +Pathname#mkpath+, but this method returns the Pathname.
+  # Creates the directory indicated by the Pathname, including any
+  # necessary parent directories.  Returns the Pathname.
+  #
+  # @see https://docs.ruby-lang.org/en/trunk/Pathname.html#method-i-mkpath Pathname#mkpath
   #
   # @example
   #   Dir.exist?("path")                # == false
@@ -233,14 +293,16 @@ class Pathname
   #   Dir.exist?("path")                # == true
   #   Dir.exist?("path/to")             # == true
   #
-  # @return [Pathname]
+  # @return [self]
+  # @raise [SystemCallError]
+  #   if the Pathname points to an existing file (non-directory)
   def make_dir
     self.mkpath
     self
   end
 
-  # Creates the parent (+dirname+) directories of the Pathname if they
-  # do not exist, and returns the Pathname.
+  # Creates the directory indicated by the Pathname +dirname+, including
+  # any necessary parent directories.  Returns the Pathname.
   #
   # @example
   #   Dir.exist?("path")                         # == false
@@ -252,16 +314,44 @@ class Pathname
   #   Dir.exist?("path/to")                      # == true
   #   Dir.exist?("path/to/file")                 # == false
   #
-  # @return [Pathname]
+  # @return [self]
+  # @raise [SystemCallError]
+  #   if any element of the +dirname+ points to an existing file
+  #   (non-directory)
   def make_dirname
     self.dirname.make_dir
     self
   end
 
-  # Updates the modification time (mtime) and access time (atime) of the
-  # file indicated by the Pathname, and returns the Pathname.  Creates
-  # the file and any necessary parent directories if they do not exist.
-  # See also +FileUtils.touch+.
+  # Creates the file indicated by the Pathname, including any necessary
+  # parent directories.  Returns the Pathname.
+  #
+  # @example
+  #   Dir.exist?("path")                      # == false
+  #   Dir.exist?("path/to")                   # == false
+  #
+  #   Pathname.new("path/to/file").make_file  # == Pathname.new("path/to/file")
+  #
+  #   Dir.exist?("path")                      # == true
+  #   Dir.exist?("path/to")                   # == true
+  #   File.exist?("path/to/file")             # == true
+  #
+  # @return [Pathname]
+  # @raise [SystemCallError]
+  #   if the Pathname points to an existent directory
+  def make_file
+    self.make_dirname.open("a"){}
+    self
+  end
+
+  # @deprecated Use {Pathname#make_file}.
+  #
+  # Creates the file indicated by the Pathname, including any necessary
+  # parent directories.  If the file already exists, its modification
+  # time (mtime) and access time (atime) are updated.  Returns the
+  # Pathname.
+  #
+  # @see https://docs.ruby-lang.org/en/trunk/FileUtils.html#method-c-touch FileUtils.touch
   #
   # @example
   #   Dir.exist?("path")                       # == false
@@ -273,16 +363,16 @@ class Pathname
   #   Dir.exist?("path/to")                    # == true
   #   File.exist?("path/to/file")              # == true
   #
-  # @return [Pathname]
+  # @return [self]
   def touch_file
     self.make_dirname
     FileUtils.touch(self)
     self
   end
 
-  # Recursively deletes the directory or file indicated by the Pathname,
-  # and returns the Pathname.  Similar to +Pathname#rmtree+, but does
-  # not raise an exception if the file does not exist.
+  # Recursively deletes the directory or file indicated by the Pathname.
+  # Similar to +Pathname#rmtree+, but does not raise an exception if the
+  # file does not exist.  Returns the Pathname.
   #
   # @example
   #   File.exist?("path/to/file")   # == true
@@ -293,30 +383,92 @@ class Pathname
   #   Dir.exist?("path/to")         # == false
   #   File.exist?("path/to/file")   # == false
   #
-  # @return [Pathname]
+  # @return [self]
   def delete!
     self.rmtree if self.exist?
     self
   end
 
-  # Moves the file or directory indicated by the Pathname to the given
-  # destination, and returns that destination as a Pathname.  Creates
-  # any necessary parent directories if they do not exist.  See also
-  # +FileUtils.mv+.
+  # Finds an available name based on the Pathname.  If the Pathname does
+  # not point to an existing file or directory, returns the Pathname.
+  # Otherwise, iteratively generates and tests names until one is found
+  # that does not point to an existing file or directory.
+  #
+  # Names are generated using a Hash-style format string with three
+  # populated values:
+  #
+  # * +%{name}+: original Pathname basename *without* extname
+  # * +%{ext}+: original Pathname extname, including leading dot
+  # * +%{i}+: iteration counter; can be initialized via +:i+ kwarg
+  #
+  # @example Incremental
+  #   Pathname.new("dir/file.txt").available_name  # == Pathname.new("dir/file.txt")
+  #
+  #   FileUtils.mkdir("dir")
+  #   FileUtils.touch("dir/file.txt")
+  #
+  #   Pathname.new("dir/file.txt").available_name  # == Pathname.new("dir/file_1.txt")
+  #
+  #   FileUtils.touch("dir/file_1.txt")
+  #   FileUtils.touch("dir/file_2.txt")
+  #
+  #   Pathname.new("dir/file.txt").available_name  # == Pathname.new("dir/file_3.txt")
+  #
+  # @example Specifying format
+  #   FileUtils.touch("file.txt")
+  #
+  #   Pathname.new("file.txt").available_name("%{name} (%{i})%{ext}")
+  #     # == Pathname.new("file (1).txt")
+  #
+  # @example Specifying initial counter
+  #   FileUtils.touch("file.txt")
+  #
+  #   Pathname.new("file.txt").available_name(i: 0)
+  #     # == Pathname.new("file_0.txt")
+  #
+  # @param format [String]
+  # @param i [Integer]
+  # @return [Pathname]
+  def available_name(format = "%{name}_%{i}%{ext}", i: 1)
+    return self unless self.exist?
+
+    dirname = File.dirname(self)
+    format = "%{dirname}/" + format unless dirname == "."
+
+    values = {
+      dirname: dirname,
+      name: File.basename(self, ".*"),
+      ext: self.extname,
+      i: i,
+    }
+
+    while (path = format % values) && File.exist?(path)
+      values[:i] += 1
+    end
+
+    path.to_pathname
+  end
+
+  # Moves the file or directory indicated by the Pathname to
+  # +destination+, in the same manner as +FileUtils.mv+.  Creates any
+  # necessary parent directories of the destination.  Returns
+  # +destination+ as a Pathname.
+  #
+  # @see https://docs.ruby-lang.org/en/trunk/FileUtils.html#method-c-mv FileUtils.mv
   #
   # @example
-  #   File.exist?("path/to/file")      # == true
-  #   Dir.exist?("some")               # == false
-  #   Dir.exist?("some/other")         # == false
-  #   File.exist?("some/other/thing")  # == false
+  #   File.exist?("path/to/file")         # == true
+  #   Dir.exist?("other")                 # == false
+  #   Dir.exist?("other/dir")             # == false
+  #   File.exist?("other/dir/same_file")  # == false
   #
-  #   Pathname.new("path/to/file").move("some/other/thing")
-  #     # == Pathname.new("some/other/thing")
+  #   Pathname.new("path/to/file").move("other/dir/same_file")
+  #     # == Pathname.new("other/dir/same_file")
   #
-  #   File.exist?("path/to/file")      # == false
-  #   Dir.exist?("some")               # == true
-  #   Dir.exist?("some/other")         # == true
-  #   File.exist?("some/other/thing")  # == true
+  #   File.exist?("path/to/file")         # == false
+  #   Dir.exist?("other")                 # == true
+  #   Dir.exist?("other/dir")             # == true
+  #   File.exist?("other/dir/same_file")  # == true
   #
   # @param destination [Pathname, String]
   # @return [Pathname]
@@ -327,48 +479,189 @@ class Pathname
     destination
   end
 
-  # Moves the file or directory indicated by the Pathname into the given
-  # directory, and returns the resultant path as a Pathname.  Creates
-  # any necessary parent directories if they do not exist.
-  #
-  # @example
-  #   File.exist?("path/to/file")     # == true
-  #   Dir.exist?("other")             # == false
-  #   Dir.exist?("other/path")        # == false
-  #   File.exist?("other/path/file")  # == false
-  #
-  #   Pathname.new("path/to/file").move_into("other/path")
-  #     # == Pathname.new("other/path/file")
+  # Moves the file or directory indicated by the Pathname to a
+  # destination, replacing any existing file or directory.
+  #
+  # If a block is given and a file or directory does exist at the
+  # destination, the block is called with the source and destination
+  # Pathnames, and the return value of the block is used as the new
+  # destination.  If the block returns the source Pathname or +nil+, the
+  # move is aborted.
+  #
+  # Creates any necessary parent directories of the destination.
+  # Returns the destination as a Pathname (or the source Pathname in the
+  # case that the move is aborted).
+  #
+  # *WARNING:* Due to system API limitations, the move is performed in
+  # two steps, non-atomically.  First, any file or directory existing
+  # at the destination is deleted.  Next, the source is moved to the
+  # destination.  The second step can fail independently of the first,
+  # e.g. due to insufficient disk space, leaving the file or directory
+  # previously at the destination deleted without replacement.
+  #
+  # @example Without a block
+  #   FileUtils.touch("file")
+  #
+  #   Pathname.new("file").move_as("dir/file")
+  #     # == Pathname.new("dir/file")
+  #
+  #   File.exist?("file")      # == false
+  #   File.exist?("dir/file")  # == true
+  #
+  # @example Error on older source
+  #   FileUtils.touch("file")
+  #   sleep 1
+  #   FileUtils.touch("file.new")
+  #
+  #   Pathname.new("file.new").move_as("file") do |source, destination|
+  #     if source.mtime < destination.mtime
+  #       raise "cannot replace newer file #{destination} with #{source}"
+  #     end
+  #     destination
+  #   end                      # == Pathname.new("file")
+  #
+  #   File.exist?("file.new")  # == false
+  #   File.exist?("file")      # == true
+  #
+  # @example Abort on conflict
+  #   FileUtils.touch("file1")
+  #   FileUtils.touch("file2")
+  #
+  #   Pathname.new("file1").move_as("file2") do |source, destination|
+  #     puts "#{source} not moved to #{destination} due to conflict"
+  #     nil
+  #   end                   # == Pathname.new("file1")
+  #
+  #   File.exist?("file1")  # == true
+  #   File.exist?("file2")  # == true
+  #
+  # @example New destination on conflict
+  #   FileUtils.touch("file1")
+  #   FileUtils.touch("file2")
+  #
+  #   Pathname.new("file1").move_as("file2") do |source, destination|
+  #     destination.available_name
+  #   end                     # == Pathname.new("file2_1")
+  #
+  #   File.exist?("file1")    # == false
+  #   File.exist?("file2")    # == true
+  #   File.exist?("file2_1")  # == true
+  #
+  # @overload move_as(destination)
+  #   @param destination [Pathname, String]
+  #   @return [Pathname]
   #
-  #   File.exist?("path/to/file")     # == false
-  #   Dir.exist?("other")             # == true
-  #   Dir.exist?("other/path")        # == true
-  #   File.exist?("other/path/file")  # == true
+  # @overload move_as(destination, &block)
+  #   @param destination [Pathname, String]
+  #   @yieldparam source [Pathname]
+  #   @yieldparam destination [Pathname]
+  #   @yieldreturn [Pathname, nil]
+  #   @return [Pathname]
+  def move_as(destination)
+    destination = destination.to_pathname
+
+    if block_given? && destination.exist? && self.exist? && !File.identical?(self, destination)
+      destination = (yield self, destination) || self
+    end
+
+    if destination != self
+      if File.identical?(self, destination)
+        # FileUtils.mv raises an ArgumentError when both paths refer to
+        # the same file.  On case-insensitive file systems, this occurs
+        # even when both paths have different casing.  We want to
+        # disregard the ArgumentError at all times, and change the
+        # filename casing when applicable.
+        File.rename(self, destination)
+      else
+        destination.delete!
+        self.move(destination)
+      end
+    end
+
+    destination
+  end
+
+  # Moves the file or directory indicated by the Pathname into
+  # +directory+, replacing any existing file or directory of the same
+  # basename.
+  #
+  # If a block is given and a file or directory does exist at the
+  # resultant destination, the block is called with the source and
+  # destination Pathnames, and the return value of the block is used as
+  # the new destination.  If the block returns the source Pathname or
+  # +nil+, the move is aborted.
+  #
+  # Creates any necessary parent directories of the destination.
+  # Returns the destination as a Pathname (or the source Pathname in the
+  # case that the move is aborted).
+  #
+  # *WARNING:* Due to system API limitations, the move is performed in
+  # two steps, non-atomically.  First, any file or directory existing
+  # at the destination is deleted.  Next, the source is moved to the
+  # destination.  The second step can fail independently of the first,
+  # e.g. due to insufficient disk space, leaving the file or directory
+  # previously at the destination deleted without replacement.
+  #
+  # @see Pathname#move_as
+  #
+  # @example Without a block
+  #   FileUtils.touch("file")
+  #
+  #   Pathname.new("file").move_into("dir")
+  #     # == Pathname.new("dir/file")
+  #
+  #   File.exist?("file")      # == false
+  #   File.exist?("dir/file")  # == true
+  #
+  # @example With a block
+  #   FileUtils.mkpath("files")
+  #   FileUtils.touch("files/file1")
+  #   FileUtils.mkpath("dir/files")
+  #   FileUtils.touch("dir/files/file2")
+  #
+  #   Pathname.new("files").move_into("dir") do |source, destination|
+  #     source                        # == Pathname.new("files")
+  #     destination                   # == Pathname.new("dir/files")
+  #   end                             # == Pathname.new("dir/files")
+  #
+  #   Dir.exist?("files")             # == false
+  #   File.exist?("dir/files/file1")  # == true
+  #   File.exist?("dir/files/file2")  # == false
+  #
+  # @overload move_into(directory)
+  #   @param directory [Pathname, String]
+  #   @return [Pathname]
   #
-  # @param directory [Pathname, String]
-  # @return [Pathname]
-  def move_into(directory)
-    self.move(directory / self.basename)
+  # @overload move_into(directory, &block)
+  #   @param directory [Pathname, String]
+  #   @yieldparam source [Pathname]
+  #   @yieldparam destination [Pathname]
+  #   @yieldreturn [Pathname, nil]
+  #   @return [Pathname]
+  def move_into(directory, &block)
+    self.move_as(directory / self.basename, &block)
   end
 
-  # Copies the file or directory indicated by the Pathname to the given
-  # destination, and returns that destination as a Pathname.  Creates
-  # any necessary parent directories if they do not exist.  See also
-  # +FileUtils.cp_r+.
+  # Copies the file or directory indicated by the Pathname to
+  # +destination+, in the same manner as +FileUtils.cp_r+.  Creates any
+  # necessary parent directories of the destination.  Returns
+  # +destination+ as a Pathname.
+  #
+  # @see https://docs.ruby-lang.org/en/trunk/FileUtils.html#method-c-cp_r FileUtils.cp_r
   #
   # @example
-  #   File.exist?("path/to/file")      # == true
-  #   Dir.exist?("some")               # == false
-  #   Dir.exist?("some/other")         # == false
-  #   File.exist?("some/other/thing")  # == false
+  #   File.exist?("path/to/file")         # == true
+  #   Dir.exist?("other")                 # == false
+  #   Dir.exist?("other/dir")             # == false
+  #   File.exist?("other/dir/same_file")  # == false
   #
-  #   Pathname.new("path/to/file").copy("some/other/thing")
-  #     # == Pathname.new("some/other/thing")
+  #   Pathname.new("path/to/file").copy("other/dir/same_file")
+  #     # == Pathname.new("other/dir/same_file")
   #
-  #   File.exist?("path/to/file")      # == true
-  #   Dir.exist?("some")               # == true
-  #   Dir.exist?("some/other")         # == true
-  #   File.exist?("some/other/thing")  # == true
+  #   File.exist?("path/to/file")         # == true
+  #   Dir.exist?("other")                 # == true
+  #   Dir.exist?("other/dir")             # == true
+  #   File.exist?("other/dir/same_file")  # == true
   #
   # @param destination [Pathname, String]
   # @return [Pathname]
@@ -379,86 +672,311 @@ class Pathname
     destination
   end
 
-  # Copies the file or directory indicated by the Pathname into the
-  # given directory, and returns the resultant path as a Pathname.
-  # Creates any necessary parent directories if they do not exist.
-  #
-  # @example
-  #   File.exist?("path/to/file")     # == true
-  #   Dir.exist?("other")             # == false
-  #   Dir.exist?("other/path")        # == false
-  #   File.exist?("other/path/file")  # == false
+  # Copies the file or directory indicated by the Pathname to a
+  # destination, replacing any existing file or directory.
+  #
+  # If a block is given and a file or directory does exist at the
+  # destination, the block is called with the source and destination
+  # Pathnames, and the return value of the block is used as the new
+  # destination.  If the block returns the source Pathname or +nil+, the
+  # copy is aborted.
+  #
+  # Creates any necessary parent directories of the destination.
+  # Returns the destination as a Pathname (or the source Pathname in the
+  # case that the copy is aborted).
+  #
+  # *WARNING:* Due to system API limitations, the copy is performed in
+  # two steps, non-atomically.  First, any file or directory existing
+  # at the destination is deleted.  Next, the source is copied to the
+  # destination.  The second step can fail independently of the first,
+  # e.g. due to insufficient disk space, leaving the file or directory
+  # previously at the destination deleted without replacement.
+  #
+  # @example Without a block
+  #   FileUtils.touch("file")
+  #
+  #   Pathname.new("file").copy_as("dir/file")
+  #     # == Pathname.new("dir/file")
+  #
+  #   File.exist?("file")      # == true
+  #   File.exist?("dir/file")  # == true
+  #
+  # @example Error on older source
+  #   File.write("file", "A")
+  #   sleep 1
+  #   File.write("file.new", "B")
+  #
+  #   Pathname.new("file.new").copy_as("file") do |source, destination|
+  #     if source.mtime < destination.mtime
+  #       raise "cannot replace newer file #{destination} with #{source}"
+  #     end
+  #     destination
+  #   end                    # == Pathname.new("file")
+  #
+  #   File.read("file.new")  # == "B"
+  #   File.read("file")      # == "B"
+  #
+  # @example Abort on conflict
+  #   File.write("file1", "A")
+  #   File.write("file2", "B")
+  #
+  #   Pathname.new("file1").copy_as("file2") do |source, destination|
+  #     puts "#{source} not copied to #{destination} due to conflict"
+  #     nil
+  #   end                 # == Pathname.new("file1")
+  #
+  #   File.read("file1")  # == "A"
+  #   File.read("file2")  # == "B"
+  #
+  # @example New destination on conflict
+  #   File.write("file1", "A")
+  #   File.write("file2", "B")
+  #
+  #   Pathname.new("file1").copy_as("file2") do |source, destination|
+  #     destination.available_name
+  #   end                   # == Pathname.new("file2_1")
+  #
+  #   File.read("file1")    # == "A"
+  #   File.read("file2")    # == "B"
+  #   File.read("file2_1")  # == "A"
+  #
+  # @overload copy_as(destination)
+  #   @param destination [Pathname, String]
+  #   @return [Pathname]
   #
-  #   Pathname.new("path/to/file").copy_into("other/path")
-  #     # == Pathname.new("other/path/file")
+  # @overload copy_as(destination, &block)
+  #   @param destination [Pathname, String]
+  #   @yieldparam source [Pathname]
+  #   @yieldparam destination [Pathname]
+  #   @yieldreturn [Pathname, nil]
+  #   @return [Pathname]
+  def copy_as(destination)
+    destination = destination.to_pathname
+
+    if block_given? && destination.exist? && self.exist? && !File.identical?(self, destination)
+      destination = yield self, destination
+      destination = nil if destination == self
+    end
+
+    if destination
+      destination.delete! unless File.identical?(self, destination)
+      self.copy(destination)
+    end
+
+    destination || self
+  end
+
+
+  # Copies the file or directory indicated by the Pathname into
+  # +directory+, replacing any existing file or directory of the same
+  # basename.
+  #
+  # If a block is given and a file or directory does exist at the
+  # resultant destination, the block is called with the source and
+  # destination Pathnames, and the return value of the block is used as
+  # the new destination.  If the block returns the source Pathname or
+  # +nil+, the copy is aborted.
+  #
+  # Creates any necessary parent directories of the destination.
+  # Returns the destination as a Pathname (or the source Pathname in the
+  # case that the copy is aborted).
+  #
+  # *WARNING:* Due to system API limitations, the copy is performed in
+  # two steps, non-atomically.  First, any file or directory existing
+  # at the destination is deleted.  Next, the source is copied to the
+  # destination.  The second step can fail independently of the first,
+  # e.g. due to insufficient disk space, leaving the file or directory
+  # previously at the destination deleted without replacement.
+  #
+  # @see Pathname#copy_as
+  #
+  # @example Without a block
+  #   FileUtils.touch("file")
+  #
+  #   Pathname.new("file").copy_into("dir")
+  #     # == Pathname.new("dir/file")
+  #
+  #   File.exist?("file")      # == true
+  #   File.exist?("dir/file")  # == true
+  #
+  # @example With a block
+  #   FileUtils.mkpath("files")
+  #   FileUtils.touch("files/file1")
+  #   FileUtils.mkpath("dir/files")
+  #   FileUtils.touch("dir/files/file2")
+  #
+  #   Pathname.new("files").copy_into("dir") do |source, destination|
+  #     source                        # == Pathname.new("files")
+  #     destination                   # == Pathname.new("dir/files")
+  #   end                             # == Pathname.new("dir/files")
+  #
+  #   File.exist?("files/file1")      # == true
+  #   File.exist?("dir/files/file1")  # == true
+  #   File.exist?("dir/files/file2")  # == false
+  #
+  # @overload copy_into(directory)
+  #   @param directory [Pathname, String]
+  #   @return [Pathname]
   #
-  #   File.exist?("path/to/file")     # == true
-  #   Dir.exist?("other")             # == true
-  #   Dir.exist?("other/path")        # == true
-  #   File.exist?("other/path/file")  # == true
+  # @overload copy_into(directory, &block)
+  #   @param directory [Pathname, String]
+  #   @yieldparam source [Pathname]
+  #   @yieldparam destination [Pathname]
+  #   @yieldreturn [Pathname, nil]
+  #   @return [Pathname]
+  def copy_into(directory, &block)
+    self.copy_as(directory / self.basename, &block)
+  end
+
+  # Alias of +Pathname#move_as+.
   #
-  # @param directory [Pathname, String]
   # @return [Pathname]
-  def copy_into(directory)
-    self.copy(directory / self.basename)
-  end
+  alias :rename_as :move_as
 
-  # Renames the file or directory indicated by the Pathname, but
-  # preserves its location as indicated by +dirname+.  Returns the
-  # resultant path as a Pathname.
+  # Renames the file or directory indicated by the Pathname relative to
+  # its +dirname+, replacing any existing file or directory of the same
+  # basename.
   #
-  # @example
-  #   File.exist?("path/to/file")   # == true
+  # If a block is given and a file or directory does exist at the
+  # resultant destination, the block is called with the source and
+  # destination Pathnames, and the return value of the block is used as
+  # the new destination.  If the block returns the source Pathname or
+  # +nil+, the rename is aborted.
   #
-  #   Pathname.new("path/to/file").rename_basename("other")
-  #     # == Pathname.new("path/to/other")
+  # Returns the destination as a Pathname (or the source Pathname in the
+  # case that the rename is aborted).
   #
-  #   File.exist?("path/to/file")   # == false
-  #   File.exist?("path/to/other")  # == true
+  # *WARNING:* Due to system API limitations, the rename is performed in
+  # two steps, non-atomically.  First, any file or directory existing
+  # at the destination is deleted.  Next, the source is moved to the
+  # destination.  The second step can fail independently of the first,
+  # e.g. due to insufficient disk space, leaving the file or directory
+  # previously at the destination deleted without replacement.
   #
-  # @param new_basename [String]
-  # @return [Pathname]
-  def rename_basename(new_basename)
-    new_path = self.dirname / new_basename
-    self.rename(new_path)
-    new_path
+  # @see Pathname#move_as
+  #
+  # @example Without a block
+  #   FileUtils.mkpath("dir")
+  #   FileUtils.touch("dir/file")
+  #
+  #   Pathname.new("dir/file").rename_basename("same_file")
+  #     # == Pathname.new("dir/same_file")
+  #
+  #   File.exist?("dir/file")       # == false
+  #   File.exist?("dir/same_file")  # == true
+  #
+  # @example With a block
+  #   FileUtils.mkpath("dir")
+  #   FileUtils.touch("dir/file1")
+  #   FileUtils.touch("dir/file2")
+  #
+  #   Pathname.new("dir/file1").rename_basename("file2") do |source, destination|
+  #     source                  # == Pathname.new("dir/file1")
+  #     destination             # == Pathname.new("dir/file2")
+  #   end                       # == Pathname.new("dir/file2")
+  #
+  #   File.exist?("dir/file1")  # == false
+  #   File.exist?("dir/file2")  # == true
+  #
+  # @overload rename_basename(new_basename)
+  #   @param new_basename [Pathname, String]
+  #   @return [Pathname]
+  #
+  # @overload rename_basename(new_basename, &block)
+  #   @param new_basename [Pathname, String]
+  #   @yieldparam source [Pathname]
+  #   @yieldparam destination [Pathname]
+  #   @yieldreturn [Pathname, nil]
+  #   @return [Pathname]
+  def rename_basename(new_basename, &block)
+    self.move_as(self.dirname / new_basename, &block)
   end
 
-  # Renames the file extension of the file indicated by the Pathname.
-  # If the file has no extension, the new extension is appended.
+  # Changes the file extension (+extname+) of the file indicated by the
+  # Pathname, replacing any existing file or directory of the same
+  # resultant basename.
   #
-  # @example replace extension
-  #   File.exist?("path/to/file.abc")   # == true
+  # If a block is given and a file or directory does exist at the
+  # resultant destination, the block is called with the source and
+  # destination Pathnames, and the return value of the block is used as
+  # the new destination.  If the block returns the source Pathname or
+  # +nil+, the rename is aborted.
   #
-  #   Pathname.new("path/to/file.abc").rename_extname(".xyz")
-  #     # == Pathname.new("path/to/file.xyz")
+  # Returns the destination as a Pathname (or the source Pathname in the
+  # case that the rename is aborted).
   #
-  #   File.exist?("path/to/file.abc")   # == false
-  #   File.exist?("path/to/file.xyz")   # == true
+  # *WARNING:* Due to system API limitations, the rename is performed in
+  # two steps, non-atomically.  First, any file or directory existing
+  # at the destination is deleted.  Next, the source is moved to the
+  # destination.  The second step can fail independently of the first,
+  # e.g. due to insufficient disk space, leaving the file or directory
+  # previously at the destination deleted without replacement.
   #
-  # @example remove extension
-  #   File.exist?("path/to/file.abc")   # == true
+  # @see Pathname#move_as
   #
-  #   Pathname.new("path/to/file.abc").rename_extname("")
-  #     # == Pathname.new("path/to/file")
+  # @example Replace extension
+  #   FileUtils.mkpath("dir")
+  #   FileUtils.touch("dir/file.abc")
   #
-  #   File.exist?("path/to/file.abc")   # == false
-  #   File.exist?("path/to/file")       # == true
+  #   Pathname.new("dir/file.abc").rename_extname(".xyz")
+  #     # == Pathname.new("dir/file.xyz")
   #
-  # @param new_extname [String]
-  # @return [Pathname]
-  def rename_extname(new_extname)
+  #   File.exist?("dir/file.abc")  # == false
+  #   File.exist?("dir/file.xyz")  # == true
+  #
+  # @example Add extension
+  #   FileUtils.mkpath("dir")
+  #   FileUtils.touch("dir/file")
+  #
+  #   Pathname.new("dir/file").rename_extname(".abc")
+  #     # == Pathname.new("dir/file.abc")
+  #
+  #   File.exist?("dir/file")      # == false
+  #   File.exist?("dir/file.abc")  # == true
+  #
+  # @example Remove extension
+  #   FileUtils.mkpath("dir")
+  #   FileUtils.touch("dir/file.abc")
+  #
+  #   Pathname.new("dir/file.abc").rename_extname("")
+  #     # == Pathname.new("dir/file")
+  #
+  #   File.exist?("dir/file.abc")  # == false
+  #   File.exist?("dir/file")      # == true
+  #
+  # @example With a block
+  #   FileUtils.mkpath("dir")
+  #   FileUtils.touch("dir/file.abc")
+  #   FileUtils.touch("dir/file.xyz")
+  #
+  #   Pathname.new("dir/file.abc").rename_extname(".xyz") do |source, destination|
+  #     source                     # == Pathname.new("dir/file.abc")
+  #     destination                # == Pathname.new("dir/file.xyz")
+  #   end                          # == Pathname.new("dir/file.xyz")
+  #
+  #   File.exist?("dir/file.abc")  # == false
+  #   File.exist?("dir/file.xyz")  # == true
+  #
+  # @overload rename_extname(new_extname)
+  #   @param new_extname [String]
+  #   @return [Pathname]
+  #
+  # @overload rename_extname(new_extname, &block)
+  #   @param new_extname [String]
+  #   @yieldparam source [Pathname]
+  #   @yieldparam destination [Pathname]
+  #   @yieldreturn [Pathname, nil]
+  #   @return [Pathname]
+  def rename_extname(new_extname, &block)
     unless new_extname.start_with?(".") || new_extname.empty?
       new_extname = ".#{new_extname}"
     end
-    new_path = self.sub_ext(new_extname)
-    self.rename(new_path)
-    new_path
+    self.move_as(self.sub_ext(new_extname), &block)
   end
 
-  # Writes given text to the file indicated by the Pathname, and returns
-  # the Pathname.  The file is overwritten if it already exists.  Any
-  # necessary parent directories are created if they do not exist.
+  # Writes +text+ to the file indicated by the Pathname, overwriting the
+  # file if it exists.  Creates the file if it does not exist, including
+  # any necessary parent directories.  Returns the Pathname.
   #
   # @example
   #   Dir.exist?("path")           # == false
@@ -471,15 +989,15 @@ class Pathname
   #   File.read("path/to/file")    # == "hello world"
   #
   # @param text [String]
-  # @return [Pathname]
+  # @return [self]
   def write_text(text)
     self.make_dirname.open("w"){|f| f.write(text) }
     self
   end
 
-  # Appends given text to the file indicated by the Pathname, and
-  # returns the Pathname.  The file is created if it does not exist.
-  # Any necessary parent directories are created if they do not exist.
+  # Appends +text+ to the file indicated by the Pathname.  Creates the
+  # file if it does not exist, including any necessary parent
+  # directories.  Returns the Pathname.
   #
   # @example
   #   Dir.exist?("path")           # == false
@@ -492,16 +1010,16 @@ class Pathname
   #   File.read("path/to/file")    # == "hello world"
   #
   # @param text [String]
-  # @return [Pathname]
+  # @return [self]
   def append_text(text)
     self.make_dirname.open("a"){|f| f.write(text) }
     self
   end
 
-  # Writes each object as a string plus a succeeding new line character
-  # (<code>$/</code>) to the file indicated by the Pathname.  Returns
-  # the Pathname.  The file is overwritten if it already exists.  Any
-  # necessary parent directories are created if they do not exist.
+  # Writes each object in +lines+ as a string plus end-of-line (EOL)
+  # characters to the file indicated by the Pathname, overwriting the
+  # file if it exists.  Creates the file if it does not exist, including
+  # any necessary parent directories.  Returns the Pathname.
   #
   # @example
   #   File.exist?("path/to/file")  # false
@@ -512,16 +1030,17 @@ class Pathname
   #   File.read("path/to/file")    # == "one\ntwo\n"
   #
   # @param lines [Enumerable<#to_s>]
-  # @return [Pathname]
-  def write_lines(lines)
-    self.make_dirname.open("w"){|f| f.write_lines(lines) }
+  # @param eol [String]
+  # @return [self]
+  def write_lines(lines, eol: $/)
+    self.make_dirname.open("w"){|f| f.write_lines(lines, eol: eol) }
     self
   end
 
-  # Appends each object as a string plus a succeeding new line character
-  # (<code>$/</code>) to the file indicated by the Pathname.  Returns
-  # the Pathname.  The file is created if it does not exist.  Any
-  # necessary parent directories are created if they do not exist.
+  # Appends each object in +lines+ as a string plus end-of-line (EOL)
+  # characters to the file indicated by the Pathname.  Creates the file
+  # if it does not exist, including any necessary parent directories.
+  # Returns the Pathname.
   #
   # @example
   #   File.exist?("path/to/file")  # false
@@ -532,9 +1051,10 @@ class Pathname
   #   File.read("path/to/file")    # == "one\ntwo\nthree\nfour\n"
   #
   # @param lines [Enumerable<#to_s>]
-  # @return [Pathname]
-  def append_lines(lines)
-    self.make_dirname.open("a"){|f| f.write_lines(lines) }
+  # @param eol [String]
+  # @return [self]
+  def append_lines(lines, eol: $/)
+    self.make_dirname.open("a"){|f| f.write_lines(lines, eol: eol) }
     self
   end
 
@@ -543,31 +1063,33 @@ class Pathname
   # @return [String]
   alias :read_text :read
 
-  # Reads from the file indicated by the Pathname all lines, and returns
-  # them as an array, end-of-line characters excluded.  The
-  # <code>$/</code> global string specifies what end-of-line characters
-  # to look for.  See also {IO#read_lines}.
+  # Reads all lines from the file indicated by the Pathname, and returns
+  # them with all end-of-line (EOL) characters stripped.
+  #
+  # @see IO#read_lines
   #
-  # (Not to be confused with +Pathname#readlines+ which retains
-  # end-of-line characters in every string it returns.)
+  # @note Not to be confused with +Pathname#readlines+, which retains
+  #   end-of-line (EOL) characters.
   #
   # @example
   #   File.read("path/to/file")                # == "one\ntwo\n"
   #
   #   Pathname.new("path/to/file").read_lines  # == ["one", "two"]
   #
+  # @param eol [String]
   # @return [Array<String>]
-  def read_lines
-    self.open("r"){|f| f.read_lines }
+  def read_lines(eol: $/)
+    self.open("r"){|f| f.read_lines(eol: eol) }
   end
 
-  # Reads the contents of the file indicated by the Pathname into memory
-  # as a string, and yields the string to the given block for editing.
+  # Reads the entire contents of the file indicated by the Pathname as a
+  # string, and yields that string to the given block for editing.
   # Writes the return value of the block back to the file, overwriting
-  # previous contents.  Returns the file's new contents.  See also
-  # {File.edit_text}.
+  # previous contents.  Returns the return value of the block.
+  #
+  # @see File.edit_text
   #
-  # @example update JSON data file
+  # @example Update JSON data file
   #   File.read("data.json")  # == '{"nested":{"key":"value"}}'
   #
   #   Pathname.new("data.json").edit_text do |text|
@@ -578,23 +1100,24 @@ class Pathname
   #
   #   File.read("data.json")  # == '{"nested":{"key":"new value"}}'
   #
-  # @yield [text] edits current file contents
-  # @yieldparam text [String] current contents
-  # @yieldreturn [String] new contents
+  # @yield [text]
+  # @yieldparam text [String]
+  # @yieldreturn [String]
   # @return [String]
   def edit_text(&block)
     File.edit_text(self, &block)
   end
 
-  # Reads the contents of the file indicated by the Pathname into memory
-  # as an array of lines, and yields the array to the given block for
+  # Reads the entire contents of the file indicated by the Pathname as
+  # an array of lines, and yields that array to the given block for
   # editing.  Writes the return value of the block back to the file,
-  # overwriting previous contents.  The <code>$/</code> global string
-  # specifies what end-of-line characters to use for both reading and
-  # writing.  Returns the array of lines that comprises the file's new
-  # contents.  See also {File.edit_lines}.
+  # overwriting previous contents.  End-of-line (EOL) characters are
+  # stripped when reading, and appended after each line when writing.
+  # Returns the return value of the block.
   #
-  # @example dedup lines of file
+  # @see File.edit_lines
+  #
+  # @example Dedup lines of file
   #   File.read("entries.txt")  # == "AAA\nBBB\nBBB\nCCC\nAAA\n"
   #
   #   Pathname.new("entries.txt").edit_lines(&:uniq)
@@ -602,16 +1125,17 @@ class Pathname
   #
   #   File.read("entries.txt")  # == "AAA\nBBB\nCCC\n"
   #
-  # @yield [lines] edits current file contents
-  # @yieldparam lines [Array<String>] current contents
-  # @yieldreturn [Array<String>] new contents
+  # @param eol [String]
+  # @yield [lines]
+  # @yieldparam lines [Array<String>]
+  # @yieldreturn [Array<String>]
   # @return [Array<String>]
-  def edit_lines(&block)
-    File.edit_lines(self, &block)
+  def edit_lines(eol: $/, &block)
+    File.edit_lines(self, eol: eol, &block)
   end
 
-  # Appends the contents of another file to the destination indicated by
-  # Pathname.  Returns the destination Pathname.
+  # Appends the contents of file indicated by +source+ to the file
+  # indicated by the Pathname.  Returns the Pathname.
   #
   # @example
   #   File.read("yearly.log")  # == "one\ntwo\n"
@@ -623,7 +1147,7 @@ class Pathname
   #   File.read("yearly.log")  # == "one\ntwo\nthree\nfour\n"
   #
   # @param source [String, Pathname]
-  # @return [Pathname]
+  # @return [self]
   def append_file(source)
     self.open("a"){|destination| IO::copy_stream(source, destination) }
     self