diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2022-05-30 12:29:54 -0500 |
---|---|---|
committer | git <svn-admin@ruby-lang.org> | 2022-05-31 02:30:07 +0900 |
commit | c50c9d40511c52594f4d9db909339a7b036e3478 (patch) | |
tree | 84d32f4159708047f60a19cef63fd5d4e2666cc2 /lib/fileutils.rb | |
parent | a78f003c30dde0a303eb15fc073bc6c57df1cfc2 (diff) | |
download | ruby-c50c9d40511c52594f4d9db909339a7b036e3478.tar.gz |
[ruby/fileutils] [DOC] Enhanced RDoc (https://github.com/ruby/fileutils/pull/77)
Treats:
::copy_entry
::copy_file
::copy_stream
::mv
https://github.com/ruby/fileutils/commit/d6d7e5330d
Diffstat (limited to 'lib/fileutils.rb')
-rw-r--r-- | lib/fileutils.rb | 83 |
1 files changed, 69 insertions, 14 deletions
diff --git a/lib/fileutils.rb b/lib/fileutils.rb index 940b035627..f072b770fc 100644 --- a/lib/fileutils.rb +++ b/lib/fileutils.rb @@ -746,7 +746,7 @@ module FileUtils # - <tt>dereference_root: false</tt> - if +src+ is a symbolic link, # does not dereference it. # - <tt>noop: true</tt> - does not copy files. - # - <tt>preserve</tt> - preserves file times. + # - <tt>preserve: true</tt> - preserves file times. # - <tt>remove_destination: true</tt> - removes +dest+ before copying files. # - <tt>verbose: true</tt> - prints an equivalent command: # @@ -788,6 +788,7 @@ module FileUtils # # If +src+ is a directory, recursively copies +src+ to +dest+: # + # system('tree --charset=ascii src1') # src1 # |-- dir0 # | |-- src0.txt @@ -796,6 +797,7 @@ module FileUtils # |-- src2.txt # `-- src3.txt # FileUtils.copy_entry('src1', 'dest1') + # system('tree --charset=ascii dest1') # dest1 # |-- dir0 # | |-- src0.txt @@ -812,7 +814,7 @@ module FileUtils # # - <tt>dereference_root: true</tt> - if +src+ is a symbolic link, # follows the link. - # - <tt>preserve</tt> - preserves file times. + # - <tt>preserve: true</tt> - preserves file times. # - <tt>remove_destination: true</tt> - removes +dest+ before copying files. # def copy_entry(src, dest, preserve = false, dereference_root = false, remove_destination = false) @@ -831,9 +833,18 @@ module FileUtils end module_function :copy_entry + # Copies file from +src+ to +dest+, which should 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: + # + # - <tt>dereference: false</tt> - if +src+ is a symbolic link, + # does not follow the link. + # - <tt>preserve: true</tt> - preserves file times. + # - <tt>remove_destination: true</tt> - removes +dest+ before copying files. # def copy_file(src, dest, preserve = false, dereference = true) ent = Entry_.new(src, nil, dereference) @@ -842,25 +853,69 @@ module FileUtils 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 +dest+: + # + # File.file?('src1.txt') # => true + # system('tree --charset=ascii src1') + # src1 + # |-- src.dat + # `-- src.txt + # Dir.empty?('dest1') # => true + # FileUtils.mv(['src1.txt', 'src1'], 'dest1') + # system('tree --charset=ascii dest1') + # dest1 + # |-- src1 + # | |-- src.dat + # | `-- src.txt + # `-- src1.txt + # + # - <tt>force: true</tt> - 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. + # - <tt>noop: true</tt> - does not move files. + # - <tt>secure: true</tt> - removes +src+ securely + # by calling FileUtils.remove_entry_secure. + # - <tt>verbose: true</tt> - 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 |