ruby-changes:57972
From: zverok <ko1@a...>
Date: Fri, 27 Sep 2019 13:05:51 +0900 (JST)
Subject: [ruby-changes:57972] 366dd9d803 (master): [ruby/fileutils] Update the documentation content and formatting
https://git.ruby-lang.org/ruby.git/commit/?id=366dd9d803 From 366dd9d80308e6526502ef636b63893b3fb41af2 Mon Sep 17 00:00:00 2001 From: zverok <zverok.offline@g...> Date: Sun, 10 Mar 2019 13:09:59 +0200 Subject: [ruby/fileutils] Update the documentation content and formatting https://github.com/ruby/fileutils/commit/b701353c53 diff --git a/lib/fileutils.rb b/lib/fileutils.rb index 1132176..ee903e2 100644 --- a/lib/fileutils.rb +++ b/lib/fileutils.rb @@ -24,46 +24,56 @@ require_relative "fileutils/version" https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L24 # # require 'fileutils' # -# FileUtils.cd(dir, options) -# FileUtils.cd(dir, options) {|dir| block } +# FileUtils.cd(dir, **options) +# FileUtils.cd(dir, **options) {|dir| block } # FileUtils.pwd() -# FileUtils.mkdir(dir, options) -# FileUtils.mkdir(list, options) -# FileUtils.mkdir_p(dir, options) -# FileUtils.mkdir_p(list, options) -# FileUtils.rmdir(dir, options) -# FileUtils.rmdir(list, options) -# FileUtils.ln(target, link, options) -# FileUtils.ln(targets, dir, options) -# FileUtils.ln_s(target, link, options) -# FileUtils.ln_s(targets, dir, options) -# FileUtils.ln_sf(target, link, options) -# FileUtils.cp(src, dest, options) -# FileUtils.cp(list, dir, options) -# FileUtils.cp_r(src, dest, options) -# FileUtils.cp_r(list, dir, options) -# FileUtils.mv(src, dest, options) -# FileUtils.mv(list, dir, options) -# FileUtils.rm(list, options) -# FileUtils.rm_r(list, options) -# FileUtils.rm_rf(list, options) -# FileUtils.install(src, dest, options) -# FileUtils.chmod(mode, list, options) -# FileUtils.chmod_R(mode, list, options) -# FileUtils.chown(user, group, list, options) -# FileUtils.chown_R(user, group, list, options) -# FileUtils.touch(list, options) +# FileUtils.mkdir(dir, **options) +# FileUtils.mkdir(list, **options) +# FileUtils.mkdir_p(dir, **options) +# FileUtils.mkdir_p(list, **options) +# FileUtils.rmdir(dir, **options) +# FileUtils.rmdir(list, **options) +# FileUtils.ln(target, link, **options) +# FileUtils.ln(targets, dir, **options) +# FileUtils.ln_s(target, link, **options) +# FileUtils.ln_s(targets, dir, **options) +# FileUtils.ln_sf(target, link, **options) +# FileUtils.cp(src, dest, **options) +# FileUtils.cp(list, dir, **options) +# FileUtils.cp_r(src, dest, **options) +# FileUtils.cp_r(list, dir, **options) +# FileUtils.mv(src, dest, **options) +# FileUtils.mv(list, dir, **options) +# FileUtils.rm(list, **options) +# FileUtils.rm_r(list, **options) +# FileUtils.rm_rf(list, **options) +# FileUtils.install(src, dest, **options) +# FileUtils.chmod(mode, list, **options) +# FileUtils.chmod_R(mode, list, **options) +# FileUtils.chown(user, group, list, **options) +# FileUtils.chown_R(user, group, list, **options) +# FileUtils.touch(list, **options) # -# The <tt>options</tt> parameter is a hash of options, taken from the list -# <tt>:force</tt>, <tt>:noop</tt>, <tt>:preserve</tt>, and <tt>:verbose</tt>. -# <tt>:noop</tt> means that no changes are made. The other three are obvious. -# Each method documents the options that it honours. +# Possible <tt>options</tt> are: +# +# <tt>:force</tt> :: forced operation (rewrite files if exist, remove +# directories if not empty, etc.); +# <tt>:verbose</tt> :: print command to be run, in bash syntax, before +# performing it; +# <tt>:preserve</tt> :: preserve object's group, user and modification +# time on copying; +# <tt>:noop</tt> :: no changes are made (usable in combination with +# <tt>:verbose</tt> which will print the command to run) +# +# Each method documents the options that it honours. See also ::commands, +# ::options and ::options_of methods to introspect which command have which +# options. # # All methods that have the concept of a "source" file or directory can take # either one file or a list of files in that argument. See the method # documentation for examples. # -# There are some `low level' methods, which do not accept any option: +# There are some `low level' methods, which do not accept keyword arguments: # # FileUtils.copy_entry(src, dest, preserve = false, dereference_root = false, remove_destination = false) # FileUtils.copy_file(src, dest, preserve = false, dereference = true) @@ -119,7 +129,7 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L129 # # FileUtils.cd('/') # change directory # - # FileUtils.cd('/', :verbose => true) # change directory and report it + # FileUtils.cd('/', verbose: true) # change directory and report it # # FileUtils.cd('/') do # change directory # # ... # do something @@ -164,9 +174,9 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L174 # Creates one or more directories. # # FileUtils.mkdir 'test' - # FileUtils.mkdir %w( tmp data ) - # FileUtils.mkdir 'notexist', :noop => true # Does not really create. - # FileUtils.mkdir 'tmp', :mode => 0700 + # FileUtils.mkdir %w(tmp data) + # FileUtils.mkdir 'notexist', noop: true # Does not really create. + # FileUtils.mkdir 'tmp', mode: 0700 # def mkdir(list, mode: nil, noop: nil, verbose: nil) list = fu_list(list) @@ -185,7 +195,7 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L195 # # FileUtils.mkdir_p '/usr/local/lib/ruby' # - # causes to make following directories, if it does not exist. + # causes to make following directories, if they do not exist. # # * /usr # * /usr/local @@ -249,7 +259,7 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L259 # FileUtils.rmdir 'somedir' # FileUtils.rmdir %w(somedir anydir otherdir) # # Does not really remove directory; outputs message. - # FileUtils.rmdir 'somedir', :verbose => true, :noop => true + # FileUtils.rmdir 'somedir', verbose: true, noop: true # def rmdir(list, parents: nil, noop: nil, verbose: nil) list = fu_list(list) @@ -278,7 +288,7 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L288 # # In the first form, creates a hard link +link+ which points to +target+. # If +link+ already exists, raises Errno::EEXIST. - # But if the :force option is set, overwrites +link+. + # But if the +force+ option is set, overwrites +link+. # # FileUtils.ln 'gcc', 'cc', verbose: true # FileUtils.ln '/usr/bin/emacs21', '/usr/bin/emacs' @@ -305,22 +315,22 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L315 module_function :link # - # :call-seq: - # FileUtils.cp_lr(src, dest, noop: nil, verbose: nil, dereference_root: true, remove_destination: false) - # # Hard link +src+ to +dest+. If +src+ is a directory, this method links # all its contents recursively. If +dest+ is a directory, links # +src+ to +dest/src+. # # +src+ can be a list of files. # - # # Installing the library "mylib" under the site_ruby directory. - # FileUtils.rm_r site_ruby + '/mylib', :force => true + # If +dereference_root+ is true, this method dereference tree root. + # + # If +remove_destination+ is true, this method removes each destination file before copy. + # + # FileUtils.rm_r site_ruby + '/mylib', force: true # FileUtils.cp_lr 'lib/', site_ruby + '/mylib' # # # Examples of linking several files to target directory. # FileUtils.cp_lr %w(mail.rb field.rb debug/), site_ruby + '/tmail' - # FileUtils.cp_lr Dir.glob('*.rb'), '/home/aamine/lib/ruby', :noop => true, :verbose => true + # FileUtils.cp_lr Dir.glob('*.rb'), '/home/aamine/lib/ruby', noop: true, verbose: true # # # If you want to link all contents of a directory instead of the # # directory itself, c.f. src/x -> dest/x, src/y -> dest/y, @@ -345,7 +355,7 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L355 # # In the first form, creates a symbolic link +link+ which points to +target+. # If +link+ already exists, raises Errno::EEXIST. - # But if the :force option is set, overwrites +link+. + # But if the <tt>force</tt> option is set, overwrites +link+. # # FileUtils.ln_s '/usr/bin/ruby', '/usr/local/bin/ruby' # FileUtils.ln_s 'verylongsourcefilename.c', 'c', force: true @@ -411,7 +421,7 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L421 # # FileUtils.cp 'eval.c', 'eval.c.org' # FileUtils.cp %w(cgi.rb complex.rb date.rb), '/usr/lib/ruby/1.6' - # FileUtils.cp %w(cgi.rb complex.rb date.rb), '/usr/lib/ruby/1.6', :verbose => true + # FileUtils.cp %w(cgi.rb complex.rb date.rb), '/usr/lib/ruby/1.6', verbose: true # FileUtils.cp 'symlink', 'dest' # copy content, "dest" is not a symlink # def cp(src, dest, preserve: nil, noop: nil, verbose: nil) @@ -433,13 +443,17 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L443 # # +src+ can be a list of files. # + # If +dereference_root+ is true, this method dereference tree root. + # + # If +remove_destination+ is true, this method removes each destination file before copy. + # # # Installing Ruby library "mylib" under the site_ruby - # FileUtils.rm_r site_ruby + '/mylib', :force + # FileUtils.rm_r site_ruby + '/mylib', force: true # FileUtils.cp_r 'lib/', site_ruby + '/mylib' # # # Examples of copying several files to target directory. # FileUtils.cp_r %w(mail.rb field.rb debug/), site_ruby + '/tmail' - # FileUtils.cp_r Dir.glob('*.rb'), '/home/foo/lib/ruby', :noop => true, :verbose => true + # FileUtils.cp_r Dir.glob('*.rb'), '/home/foo/lib/ruby', noop: true, verbose: true # # # If you want to copy all contents of a directory instead of the # # directory itself, c.f. src/x -> dest/x, src/y -> dest/y, @@ -511,10 +525,10 @@ module Fil (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/