From ba3ae2430d2d6cdcf098756dfd10d6c0aad81191 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Wed, 15 Jun 2022 15:56:36 -0500 Subject: [PATCH] [DOC] More on paths and lists (#88) --- lib/fileutils.rb | 70 ++++++++++++++++++++++++++++-------------------- 1 file changed, 41 insertions(+), 29 deletions(-) diff --git a/lib/fileutils.rb b/lib/fileutils.rb index f257abb..74cd595 100644 --- a/lib/fileutils.rb +++ b/lib/fileutils.rb @@ -168,7 +168,7 @@ # - FileUtils.rm_rf with keyword argument secure: true. # # Finally, this method for moving entries calls \FileUtils.remove_entry_secure -# if the source and destination are on different devices +# if the source and destination are on different file systems # (which means that the "move" is really a copy and remove): # # - FileUtils.mv with keyword argument secure: true. @@ -555,21 +555,6 @@ def ln(src, dest, force: nil, noop: nil, verbose: nil) # "tmp1/tmp3/t2.txt", # "tmp1/tmp3/t3.txt"] # - # If +src+ is an array of paths to files and +dest+ is the path to a directory, - # for each path +filepath+ in +src+, creates a link at dest/filepath - # pointing to that path: - # - # FileUtils.rm_r('tmp1') - # Dir.mkdir('tmp1') - # FileUtils.cp_lr(['tmp0/tmp3/t2.txt', 'tmp0/tmp3/t3.txt'], 'tmp1') - # Dir.glob('**/*.txt') - # # => ["tmp0/tmp2/t0.txt", - # "tmp0/tmp2/t1.txt", - # "tmp0/tmp3/t2.txt", - # "tmp0/tmp3/t3.txt", - # "tmp1/t2.txt", - # "tmp1/t3.txt"] - # # If +src+ and +dest+ are both paths to directories, # creates links dest/src and descendents # pointing to +src+ and its descendents: @@ -586,6 +571,21 @@ def ln(src, dest, force: nil, noop: nil, verbose: nil) # "tmp1/tmp0/tmp3/t2.txt", # "tmp1/tmp0/tmp3/t3.txt"] # + # If +src+ is an array of paths to files and +dest+ is the path to a directory, + # for each path +filepath+ in +src+, creates a link at dest/filepath + # pointing to that path: + # + # FileUtils.rm_r('tmp1') + # Dir.mkdir('tmp1') + # FileUtils.cp_lr(['tmp0/tmp3/t2.txt', 'tmp0/tmp3/t3.txt'], 'tmp1') + # Dir.glob('**/*.txt') + # # => ["tmp0/tmp2/t0.txt", + # "tmp0/tmp2/t1.txt", + # "tmp0/tmp3/t2.txt", + # "tmp0/tmp3/t3.txt", + # "tmp1/t2.txt", + # "tmp1/t3.txt"] + # # Keyword arguments: # # - dereference_root: false - if +src+ is a symbolic link, @@ -621,7 +621,7 @@ def cp_lr(src, dest, noop: nil, verbose: nil, # and +dest+ (a single path) # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]. # - # When +src+ is the path to an existing file: + # If +src+ is the path to an existing file: # # - When +dest+ is the path to a non-existent file, # creates a symbolic link at +dest+ pointing to +src+: @@ -643,7 +643,7 @@ def cp_lr(src, dest, noop: nil, verbose: nil, # # FileUtils.ln_s('src1.txt', 'dest1.txt') # Raises Errno::EEXIST. # - # When +dest+ is the path to a directory, + # If +dest+ is the path to a directory, # creates a symbolic link at dest/src pointing to +src+: # # FileUtils.touch('src2.txt') @@ -651,7 +651,7 @@ def cp_lr(src, dest, noop: nil, verbose: nil, # FileUtils.ln_s('src2.txt', 'destdir2') # File.symlink?('destdir2/src2.txt') # => true # - # When +src+ is an array of paths to existing files and +dest+ is a directory, + # If +src+ is an array of paths to existing files and +dest+ is a directory, # for each child +child+ in +src+ creates a symbolic link dest/child # pointing to +child+: # @@ -751,7 +751,7 @@ def link_entry(src, dest, dereference_root = false, remove_destination = false) end module_function :link_entry - # Copies files from +src+ to +dest+. + # Copies files. # # Arguments +src+ (a single path or an array of paths) # and +dest+ (a single path) @@ -1018,14 +1018,15 @@ def copy_stream(src, dest) end module_function :copy_stream - # Moves files from +src+ (a single path or an array of paths) - # to +dest+ (a single path). - # If +src+ and +dest+ are on different devices, - # first copies, then removes +src+. + # Moves entries. # - # Arguments +src+ and +dest+ + # Arguments +src+ (a single path or an array of paths) + # and +dest+ (a single path) # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]. # + # If +src+ and +dest+ are on different file systems, + # first copies, then removes +src+. + # # May cause a local vulnerability if not called with keyword argument # secure: true; # see {Avoiding the TOCTTOU Vulnerability}[rdoc-ref:FileUtils@Avoiding+the+TOCTTOU+Vulnerability]. @@ -1066,7 +1067,7 @@ def copy_stream(src, dest) # Keyword arguments: # # - force: true - if the move includes removing +src+ - # (that is, if +src+ and +dest+ are on different devices), + # (that is, if +src+ and +dest+ are on different file systems), # ignores raised exceptions of StandardError and its descendants. # - noop: true - does not move files. # - secure: true - removes +src+ securely; @@ -1457,11 +1458,12 @@ def compare_stream(a, b) end module_function :compare_stream - # Copies the file entry at path +src+ to the entry at path +dest+; + # Copies a file entry; # see {install(1)}[https://man7.org/linux/man-pages/man1/install.1.html]. # - # Arguments +src+ and +dest+ - # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]. + # Arguments +src+ (a single path or an array of paths) + # and +dest+ (a single path) + # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]; # # If the entry at +dest+ does not exist, copies from +src+ to +dest+: # @@ -1485,6 +1487,16 @@ def compare_stream(a, b) # FileUtils.install('src2.txt', 'dest2') # File.read('dest2/src2.txt') # => "aaa\n" # + # If +src+ is an array of paths and +dest+ points to a directory, + # copies each path +path+ in +src+ to dest/path: + # + # File.file?('src3.txt') # => true + # File.file?('src3.dat') # => true + # FileUtils.mkdir('dest3') + # FileUtils.install(['src3.txt', 'src3.dat'], 'dest3') + # File.file?('dest3/src3.txt') # => true + # File.file?('dest3/src3.dat') # => true + # # Keyword arguments: # # - group: group - changes the group if not +nil+,