Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOC] More on paths and lists #88

Merged
merged 2 commits into from
Jun 15, 2022
Merged

[DOC] More on paths and lists #88

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c7cb3c5
More on paths and lists
BurdetteLamar Jun 15, 2022
509163f
More on paths and lists
BurdetteLamar Jun 15, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 41 additions & 29 deletions lib/fileutils.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,7 +168,7 @@
# - FileUtils.rm_rf with keyword argument <tt>secure: true</tt>.
#
# 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 <tt>secure: true</tt>.
Expand Down Expand Up @@ -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 <tt>dest/filepath</tt>
# 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 <tt>dest/src</tt> and descendents
# pointing to +src+ and its descendents:
Expand All @@ -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 <tt>dest/filepath</tt>
# 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:
#
# - <tt>dereference_root: false</tt> - if +src+ is a symbolic link,
Expand Down Expand Up @@ -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+:
Expand All @@ -643,15 +643,15 @@ 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 <tt>dest/src</tt> pointing to +src+:
#
# FileUtils.touch('src2.txt')
# FileUtils.mkdir('destdir2')
# 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 <tt>dest/child</tt>
# pointing to +child+:
#
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
# <tt>secure: true</tt>;
# see {Avoiding the TOCTTOU Vulnerability}[rdoc-ref:FileUtils@Avoiding+the+TOCTTOU+Vulnerability].
Expand Down Expand Up @@ -1066,7 +1067,7 @@ def copy_stream(src, dest)
# Keyword arguments:
#
# - <tt>force: true</tt> - 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.
# - <tt>noop: true</tt> - does not move files.
# - <tt>secure: true</tt> - removes +src+ securely;
Expand Down Expand Up @@ -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+:
#
Expand All @@ -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 <tt>dest/path</tt>:
#
# 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:
#
# - <tt>group: <i>group</i></tt> - changes the group if not +nil+,
Expand Down