ruby-changes:72153
From: Burdette <ko1@a...>
Date: Tue, 14 Jun 2022 00:39:58 +0900 (JST)
Subject: [ruby-changes:72153] 9a381c240c (master): [ruby/fileutils] [DOC] Clarify path arguments (https://github.com/ruby/fileutils/pull/85)
https://git.ruby-lang.org/ruby.git/commit/?id=9a381c240c From 9a381c240c4a0daa2d00a40cf98eefd035a31c66 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Mon, 13 Jun 2022 10:39:41 -0500 Subject: [ruby/fileutils] [DOC] Clarify path arguments (https://github.com/ruby/fileutils/pull/85) https://github.com/ruby/fileutils/commit/5f9ef9ddc8 --- lib/fileutils.rb | 149 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 105 insertions(+), 44 deletions(-) diff --git a/lib/fileutils.rb b/lib/fileutils.rb index d1cfa83b1e..9b1a26ce5c 100644 --- a/lib/fileutils.rb +++ b/lib/fileutils.rb @@ -18,6 +18,15 @@ end https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L18 # # Namespace for several file utility methods for copying, moving, removing, etc. # +# == Path Arguments +# +# Some methods in \FileUtils accept _path_ arguments, +# which are interpreted as paths to filesystem entries: +# +# - If the argument is a string, that value is the path. +# - If the argument has method +:to_path+, it is converted via that method. +# - If the argument has method +:to_str+, it is converted via that method. +# # == About the Examples # # Some examples here involve trees of file entries. @@ -207,10 +216,11 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L216 alias getwd pwd module_function :getwd + # Changes the working directory to the given +dir+, which + # should be {interpretable as a path}[rdoc-ref:FileUtils@Path+Arguments]: # # With no block given, - # changes the current directory to the directory - # at the path given by +dir+; returns zero: + # changes the current directory to the directory at +dir+; returns zero: # # FileUtils.pwd # => "/rdoc/fileutils" # FileUtils.cd('..') @@ -218,7 +228,7 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L228 # FileUtils.cd('fileutils') # # With a block given, changes the current directory to the directory - # at the path given by +dir+, calls the block with argument +dir+, + # at +dir+, calls the block with argument +dir+, # and restores the original current directory; returns the block's value: # # FileUtils.pwd # => "/rdoc/fileutils" @@ -253,7 +263,10 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L263 # # Returns +true+ if the file at path +new+ # is newer than all the files at paths in array +old_list+; - # +false+ otherwise: + # +false+ otherwise. + # + # Argument +new+ and the elements of +old_list+ + # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]: # # FileUtils.uptodate?('Rakefile', ['Gemfile', 'README.md']) # => true # FileUtils.uptodate?('Gemfile', ['Rakefile', 'README.md']) # => false @@ -279,9 +292,12 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L292 # # Creates directories at the paths in the given +list+ - # (an array of strings or a single string); + # (a single path or an array of paths); # returns +list+ if it is an array, <tt>[list]</tt> otherwise. # + # Argument +list+ or its elements + # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]. + # # With no keyword arguments, creates a directory at each +path+ in +list+ # by calling: <tt>Dir.mkdir(path, mode)</tt>; # see {Dir.mkdir}[https://docs.ruby-lang.org/en/master/Dir.html#method-c-mkdir]: @@ -304,7 +320,7 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L320 # mkdir tmp0 tmp1 # mkdir -m 700 tmp2 tmp3 # - # Raises an exception if any path in +list+ points to an existing + # Raises an exception if any path points to an existing # file or directory, or if for any reason a directory cannot be created. # def mkdir(list, mode: nil, noop: nil, verbose: nil) @@ -324,6 +340,9 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L340 # also creating ancestor directories as needed; # returns +list+ if it is an array, <tt>[list]</tt> otherwise. # + # Argument +list+ or its elements + # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]. + # # With no keyword arguments, creates a directory at each +path+ in +list+, # along with any needed ancestor directories, # by calling: <tt>Dir.mkdir(path, mode)</tt>; @@ -396,6 +415,9 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L415 # (an array of strings or a single string); # returns +list+, if it is an array, <tt>[list]</tt> otherwise. # + # Argument +list+ or its elements + # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]. + # # With no keyword arguments, removes the directory at each +path+ in +list+, # by calling: <tt>Dir.rmdir(path)</tt>; # see {Dir.rmdir}[https://docs.ruby-lang.org/en/master/Dir.html#method-c-rmdir]: @@ -442,6 +464,9 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L464 # Creates {hard links}[https://en.wikipedia.org/wiki/Hard_link]. # + # Arguments +src+ and +dest+ + # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]. + # # When +src+ is the path to an existing file # and +dest+ is the path to a non-existent file, # creates a hard link at +dest+ pointing to +src+; returns zero: @@ -506,6 +531,9 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L531 # Creates {hard links}[https://en.wikipedia.org/wiki/Hard_link]. # + # Arguments +src+ and +dest+ + # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]. + # # If +src+ is the path to a directory and +dest+ does not exist, # creates links +dest+ and descendents pointing to +src+ and its descendents: # @@ -587,6 +615,9 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L615 # Creates {symbolic links}[https://en.wikipedia.org/wiki/Symbolic_link]. # + # Arguments +src+ and +dest+ + # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]. + # # When +src+ is the path to an existing file: # # - When +dest+ is the path to a non-existent file, @@ -671,6 +702,9 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L702 # Creates {hard links}[https://en.wikipedia.org/wiki/Hard_link]; returns +nil+. # + # Arguments +src+ and +dest+ + # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]. + # # If +src+ is the path to a file and +dest+ does not exist, # creates a hard link at +dest+ pointing to +src+: # @@ -716,6 +750,9 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L750 # Copies files from +src+ to +dest+. # + # Arguments +src+ and +dest+ + # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]. + # # If +src+ is the path to a file and +dest+ is not the path to a directory, # copies +src+ to +dest+: # @@ -778,6 +815,8 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L815 # Recursively copies files from +src+ to +dest+. # + # Arguments +src+ and +dest+ + # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]. # # If +src+ is the path to a file and +dest+ is not the path to a directory, # copies +src+ to +dest+: @@ -862,6 +901,9 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L901 # Recursively copies files from +src+ to +dest+. # + # Arguments +src+ and +dest+ + # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]. + # # If +src+ is the path to a file, copies +src+ to +dest+: # # FileUtils.touch('src0.txt') @@ -916,7 +958,12 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L958 end module_function :copy_entry - # Copies file from +src+ to +dest+, which should not be directories: + # Copies file from +src+ to +dest+, which should not be directories. + # + # Arguments +src+ and +dest+ + # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]. + # + # Examples: # # FileUtils.touch('src0.txt') # FileUtils.copy_file('src0.txt', 'dest0.txt') @@ -948,6 +995,9 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L995 # If +src+ and +dest+ are on different devices, # first copies, then removes +src+. # + # Arguments +src+ and +dest+ + # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]. + # # 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]. @@ -1037,10 +1087,12 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L1087 alias move mv module_function :move - # Removes entries at the paths in the given +list+ - # (an array of strings or a single string); + # Removes entries at the paths in the given +list+; # returns +list+, if it is an array, <tt>[list]</tt> otherwise. # + # Argument +list+ or its elements + # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]. + # # With no keyword arguments, removes files at the paths given in +list+: # # FileUtils.touch(['src0.txt', 'src0.dat']) @@ -1079,6 +1131,9 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L1131 # # FileUtils.rm(list, force: true, **kwargs) # + # Argument +list+ or its elements + # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments]. + # # See FileUtils.rm for keyword arguments. # # FileUtils.safe_unlink is an alias for FileUtils.rm_f. @@ -1095,6 +1150,9 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L1150 # (an array of strings or a single string); # returns +list+, if it is an array, <tt (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/