From f72ea95dc5cf9f10c3b4ec51522dede5d64e9a68 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sat, 28 May 2022 12:25:13 -0700 Subject: [PATCH 1/2] Enhanced RDoc --- lib/fileutils.rb | 84 ++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 70 insertions(+), 14 deletions(-) diff --git a/lib/fileutils.rb b/lib/fileutils.rb index 940b035..0f24686 100644 --- a/lib/fileutils.rb +++ b/lib/fileutils.rb @@ -746,7 +746,7 @@ def cp(src, dest, preserve: nil, noop: nil, verbose: nil) # - dereference_root: false - if +src+ is a symbolic link, # does not dereference it. # - noop: true - does not copy files. - # - preserve - preserves file times. + # - preserve: true - preserves file times. # - remove_destination: true - removes +dest+ before copying files. # - verbose: true - prints an equivalent command: # @@ -788,6 +788,7 @@ def cp_r(src, dest, preserve: nil, noop: nil, verbose: nil, # # If +src+ is a directory, recursively copies +src+ to +dest+: # + # system('tree --charset=ascii src1') # src1 # |-- dir0 # | |-- src0.txt @@ -796,6 +797,7 @@ def cp_r(src, dest, preserve: nil, noop: nil, verbose: nil, # |-- src2.txt # `-- src3.txt # FileUtils.copy_entry('src1', 'dest1') + # system('tree --charset=ascii dest1') # dest1 # |-- dir0 # | |-- src0.txt @@ -812,7 +814,7 @@ def cp_r(src, dest, preserve: nil, noop: nil, verbose: nil, # # - dereference_root: true - if +src+ is a symbolic link, # follows the link. - # - preserve - preserves file times. + # - preserve: true - preserves file times. # - remove_destination: true - removes +dest+ before copying files. # def copy_entry(src, dest, preserve = false, dereference_root = false, remove_destination = false) @@ -831,9 +833,18 @@ def copy_entry(src, dest, preserve = false, dereference_root = false, remove_des end module_function :copy_entry + # Copies file from +src+ to +dest+, which may not be directories: + # + # FileUtils.touch('src0.txt') + # FileUtils.copy_file('src0.txt', 'dest0.txt') + # File.file?('dest0.txt') # => true # - # Copies file contents of +src+ to +dest+. - # Both of +src+ and +dest+ must be a path name. + # Keyword arguments: + # + # - dereference: false - if +src+ is a symbolic link, + # does not follow the link. + # - preserve: true - preserves file times. + # - remove_destination: true - removes +dest+ before copying files. # def copy_file(src, dest, preserve = false, dereference = true) ent = Entry_.new(src, nil, dereference) @@ -842,25 +853,70 @@ def copy_file(src, dest, preserve = false, dereference = true) end module_function :copy_file - # - # Copies stream +src+ to +dest+. - # +src+ must respond to #read(n) and - # +dest+ must respond to #write(str). + # Copies \IO stream +src+ to \IO stream +dest+ via + # {IO.copy_stream}[https://docs.ruby-lang.org/en/master/IO.html#method-c-copy_stream]. # def copy_stream(src, dest) IO.copy_stream(src, dest) end module_function :copy_stream + # Moves files from +src+ to +dest+. + # If +src+ and +dest+ are on different devices, + # first copies, then removes +src+. + # + # If +src+ is the path to a single file or directory and +dest+ does not exist, + # moves +src+ to +dest+: + # + # system('tree --charset=ascii src0') + # src0 + # |-- src0.txt + # `-- src1.txt + # File.exist?('dest0') # => false + # FileUtils.mv('src0', 'dest0') + # File.exist?('src0') # # => false + # system('tree --charset=ascii dest0') + # dest0 + # |-- src0.txt + # `-- src1.txt + # + # If +src+ is an array of paths to files and directories + # and +dest+ is the path to a directory, + # copies from each path in the array to th + # + # File.file?('src1.txt') # => true + # system('tree --charset=ascii src1') + # src1 + # |-- src1.dat + # `-- src1.txt + # Dir.empty?('dest1') # => true + # FileUtils.mv(['src1.txt', 'src1'], 'dest1') + # system('tree --charset=ascii dest1') + # dest1 + # |-- src1 + # | |-- src1.dat + # | `-- src1.txt + # `-- src1.txt + # + # - force: true - attempts to force the move + # even if +dest+ is inappropriate; + # if the move includes removing +src+ + # (that is, if +src+ and +dest+ are on different devices), + # ignores raised exceptions of StandardError and its descendants. + # - noop: true - does not move files. + # - secure: true - removes +src+ securely + # by calling FileUtils.remove_entry_secure. + # - verbose: true - prints an equivalent command: + # + # FileUtils.mv('src0', 'dest0', noop: true, verbose: true) + # FileUtils.mv(['src1.txt', 'src1'], 'dest1', noop: true, verbose: true) # - # Moves file(s) +src+ to +dest+. If +file+ and +dest+ exist on the different - # disk partition, the file is copied then the original file is removed. + # Output: # - # FileUtils.mv 'badname.rb', 'goodname.rb' - # FileUtils.mv 'stuff.rb', '/notexist/lib/ruby', force: true # no error + # mv src0 dest0 + # mv src1.txt src1 dest1 # - # FileUtils.mv %w(junk.txt dust.txt), '/home/foo/.trash/' - # FileUtils.mv Dir.glob('test*.rb'), 'test', noop: true, verbose: true + # FileUtils.move is an alias for FileUtils.mv. # def mv(src, dest, force: nil, noop: nil, verbose: nil, secure: nil) fu_output_message "mv#{force ? ' -f' : ''} #{[src,dest].flatten.join ' '}" if verbose From 16d4fad36f0ffefe3a8a5e4c46ecbbeed5ae3d4c Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Mon, 30 May 2022 08:14:51 -0700 Subject: [PATCH 2/2] Enhanced RDoc --- lib/fileutils.rb | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/lib/fileutils.rb b/lib/fileutils.rb index 0f24686..f072b77 100644 --- a/lib/fileutils.rb +++ b/lib/fileutils.rb @@ -833,7 +833,7 @@ def copy_entry(src, dest, preserve = false, dereference_root = false, remove_des end module_function :copy_entry - # Copies file from +src+ to +dest+, which may not be directories: + # Copies file from +src+ to +dest+, which should not be directories: # # FileUtils.touch('src0.txt') # FileUtils.copy_file('src0.txt', 'dest0.txt') @@ -874,7 +874,7 @@ def copy_stream(src, dest) # `-- src1.txt # File.exist?('dest0') # => false # FileUtils.mv('src0', 'dest0') - # File.exist?('src0') # # => false + # File.exist?('src0') # => false # system('tree --charset=ascii dest0') # dest0 # |-- src0.txt @@ -882,24 +882,23 @@ def copy_stream(src, dest) # # If +src+ is an array of paths to files and directories # and +dest+ is the path to a directory, - # copies from each path in the array to th + # copies from each path in the array to +dest+: # # File.file?('src1.txt') # => true # system('tree --charset=ascii src1') # src1 - # |-- src1.dat - # `-- src1.txt + # |-- src.dat + # `-- src.txt # Dir.empty?('dest1') # => true # FileUtils.mv(['src1.txt', 'src1'], 'dest1') # system('tree --charset=ascii dest1') # dest1 # |-- src1 - # | |-- src1.dat - # | `-- src1.txt + # | |-- src.dat + # | `-- src.txt # `-- src1.txt # - # - force: true - attempts to force the move - # even if +dest+ is inappropriate; + # - force: true - attempts to force the move; # if the move includes removing +src+ # (that is, if +src+ and +dest+ are on different devices), # ignores raised exceptions of StandardError and its descendants.