diff options
Diffstat (limited to 'lib/fileutils.rb')
| -rw-r--r-- | lib/fileutils.rb | 81 |
1 files changed, 63 insertions, 18 deletions
diff --git a/lib/fileutils.rb b/lib/fileutils.rb index c115005163..7167eb3068 100644 --- a/lib/fileutils.rb +++ b/lib/fileutils.rb @@ -110,7 +110,11 @@ module FileUtils end # - # Returns the name of the current directory. + # Returns a string containing the path to the current directory: + # + # FileUtils.pwd # => "/rdoc/fileutils" + # + # FileUtils.getwd is an alias for FileUtils.pwd. # def pwd Dir.pwd @@ -121,18 +125,36 @@ module FileUtils module_function :getwd # - # Changes the current directory to the directory +dir+. + # With no block given, + # changes the current directory to the directory + # at the path given by +dir+; returns zero: + # + # FileUtils.pwd # => "/rdoc/fileutils" + # FileUtils.cd('..') + # FileUtils.pwd # => "/rdoc" + # 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+, + # and restores the original current directory; returns the block's value: # - # If this method is called with block, resumes to the previous - # working directory after the block execution has finished. + # FileUtils.pwd # => "/rdoc/fileutils" + # FileUtils.cd('..') { |arg| [arg, FileUtils.pwd] } # => ["..", "/rdoc"] + # FileUtils.pwd # => "/rdoc/fileutils" # - # FileUtils.cd('/') # change directory + # Keyword arguments: # - # FileUtils.cd('/', verbose: true) # change directory and report it + # - <tt>verbose: true</tt> - prints an equivalent command: # - # FileUtils.cd('/') do # change directory - # # ... # do something - # end # return to original directory + # FileUtils.cd('..') + # FileUtils.cd('fileutils') + # + # Output: + # + # cd .. + # cd fileutils + # + # FileUtils.chdir is an alias for FileUtils.cd. # def cd(dir, verbose: nil, &block) # :yield: dir fu_output_message "cd #{dir}" if verbose @@ -146,11 +168,14 @@ module FileUtils module_function :chdir # - # Returns true if +new+ is newer than all +old_list+. - # Non-existent files are older than any file. + # Returns +true+ if the file at path +new+ + # is newer than all the files at paths in array +old_list+.; + # +false+ otherwise: + # + # FileUtils.uptodate?('Rakefile', ['Gemfile', 'README.md']) # => true + # FileUtils.uptodate?('Gemfile', ['Rakefile', 'README.md']) # => false # - # FileUtils.uptodate?('hello.o', %w(hello.c hello.h)) or \ - # system 'make hello.o' + # A non-existent file is considered to be infinitely old. # def uptodate?(new, old_list) return false unless File.exist?(new) @@ -170,12 +195,32 @@ module FileUtils private_module_function :remove_trailing_slash # - # Creates one or more directories. + # Creates directories at the paths in the given +list+ (an array of strings); + # returns +list+. + # + # 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]: + # + # FileUtils.mkdir(%w[tmp0 tmp1]) # => ["tmp0", "tmp1"] + # + # Keyword arguments: + # + # - <tt>mode: <i>integer</i></tt> - also calls <tt>File.chmod(mode, path)</tt>; + # see {File.chmod}[https://docs.ruby-lang.org/en/master/File.html#method-c-chmod]. + # - <tt>noop: true</tt> - does not create directories. + # - <tt>verbose: true</tt> - prints an equivalent command: + # + # FileUtils.mkdir(%w[tmp0 tmp1], verbose: true) + # FileUtils.mkdir(%w[tmp2 tmp3], mode: 0700, verbose: true) + # + # Output: + # + # mkdir tmp0 tmp1 + # mkdir -m 700 tmp2 tmp3 # - # FileUtils.mkdir 'test' - # FileUtils.mkdir %w(tmp data) - # FileUtils.mkdir 'notexist', noop: true # Does not really create. - # FileUtils.mkdir 'tmp', mode: 0700 + # Raises an exception if any path in +list+ 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) list = fu_list(list) |