Skip to content

Commit b701353

Browse files
zverokzverok
committed
Update the documentation content and formatting
1 parent 9e925fa commit b701353

File tree

1 file changed

+93
-74
lines changed

1 file changed

+93
-74
lines changed

‎lib/fileutils.rb

Lines changed: 93 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -24,46 +24,56 @@
2424
#
2525
# require 'fileutils'
2626
#
27-
# FileUtils.cd(dir, options)
28-
# FileUtils.cd(dir, options) {|dir| block }
27+
# FileUtils.cd(dir, **options)
28+
# FileUtils.cd(dir, **options) {|dir| block }
2929
# FileUtils.pwd()
30-
# FileUtils.mkdir(dir, options)
31-
# FileUtils.mkdir(list, options)
32-
# FileUtils.mkdir_p(dir, options)
33-
# FileUtils.mkdir_p(list, options)
34-
# FileUtils.rmdir(dir, options)
35-
# FileUtils.rmdir(list, options)
36-
# FileUtils.ln(target, link, options)
37-
# FileUtils.ln(targets, dir, options)
38-
# FileUtils.ln_s(target, link, options)
39-
# FileUtils.ln_s(targets, dir, options)
40-
# FileUtils.ln_sf(target, link, options)
41-
# FileUtils.cp(src, dest, options)
42-
# FileUtils.cp(list, dir, options)
43-
# FileUtils.cp_r(src, dest, options)
44-
# FileUtils.cp_r(list, dir, options)
45-
# FileUtils.mv(src, dest, options)
46-
# FileUtils.mv(list, dir, options)
47-
# FileUtils.rm(list, options)
48-
# FileUtils.rm_r(list, options)
49-
# FileUtils.rm_rf(list, options)
50-
# FileUtils.install(src, dest, options)
51-
# FileUtils.chmod(mode, list, options)
52-
# FileUtils.chmod_R(mode, list, options)
53-
# FileUtils.chown(user, group, list, options)
54-
# FileUtils.chown_R(user, group, list, options)
55-
# FileUtils.touch(list, options)
30+
# FileUtils.mkdir(dir, **options)
31+
# FileUtils.mkdir(list, **options)
32+
# FileUtils.mkdir_p(dir, **options)
33+
# FileUtils.mkdir_p(list, **options)
34+
# FileUtils.rmdir(dir, **options)
35+
# FileUtils.rmdir(list, **options)
36+
# FileUtils.ln(target, link, **options)
37+
# FileUtils.ln(targets, dir, **options)
38+
# FileUtils.ln_s(target, link, **options)
39+
# FileUtils.ln_s(targets, dir, **options)
40+
# FileUtils.ln_sf(target, link, **options)
41+
# FileUtils.cp(src, dest, **options)
42+
# FileUtils.cp(list, dir, **options)
43+
# FileUtils.cp_r(src, dest, **options)
44+
# FileUtils.cp_r(list, dir, **options)
45+
# FileUtils.mv(src, dest, **options)
46+
# FileUtils.mv(list, dir, **options)
47+
# FileUtils.rm(list, **options)
48+
# FileUtils.rm_r(list, **options)
49+
# FileUtils.rm_rf(list, **options)
50+
# FileUtils.install(src, dest, **options)
51+
# FileUtils.chmod(mode, list, **options)
52+
# FileUtils.chmod_R(mode, list, **options)
53+
# FileUtils.chown(user, group, list, **options)
54+
# FileUtils.chown_R(user, group, list, **options)
55+
# FileUtils.touch(list, **options)
5656
#
57-
# The <tt>options</tt> parameter is a hash of options, taken from the list
58-
# <tt>:force</tt>, <tt>:noop</tt>, <tt>:preserve</tt>, and <tt>:verbose</tt>.
59-
# <tt>:noop</tt> means that no changes are made. The other three are obvious.
60-
# Each method documents the options that it honours.
57+
# Possible <tt>options</tt> are:
58+
#
59+
# <tt>:force</tt> :: forced operation (rewrite files if exist, remove
60+
# directories if not empty, etc.);
61+
# <tt>:verbose</tt> :: print command to be run, in bash syntax, before
62+
# performing it;
63+
# <tt>:preserve</tt> :: preserve object's group, user and modification
64+
# time on copying;
65+
# <tt>:noop</tt> :: no changes are made (usable in combination with
66+
# <tt>:verbose</tt> which will print the command to run)
67+
#
68+
# Each method documents the options that it honours. See also ::commands,
69+
# ::options and ::options_of methods to introspect which command have which
70+
# options.
6171
#
6272
# All methods that have the concept of a "source" file or directory can take
6373
# either one file or a list of files in that argument. See the method
6474
# documentation for examples.
6575
#
66-
# There are some `low level' methods, which do not accept any option:
76+
# There are some `low level' methods, which do not accept keyword arguments:
6777
#
6878
# FileUtils.copy_entry(src, dest, preserve = false, dereference_root = false, remove_destination = false)
6979
# FileUtils.copy_file(src, dest, preserve = false, dereference = true)
@@ -119,7 +129,7 @@ def pwd
119129
#
120130
# FileUtils.cd('/') # change directory
121131
#
122-
# FileUtils.cd('/', :verbose => true) # change directory and report it
132+
# FileUtils.cd('/', verbose: true) # change directory and report it
123133
#
124134
# FileUtils.cd('/') do # change directory
125135
# # ... # do something
@@ -164,9 +174,9 @@ def remove_trailing_slash(dir) #:nodoc:
164174
# Creates one or more directories.
165175
#
166176
# FileUtils.mkdir 'test'
167-
# FileUtils.mkdir %w( tmp data )
168-
# FileUtils.mkdir 'notexist', :noop => true # Does not really create.
169-
# FileUtils.mkdir 'tmp', :mode => 0700
177+
# FileUtils.mkdir %w(tmp data)
178+
# FileUtils.mkdir 'notexist', noop: true # Does not really create.
179+
# FileUtils.mkdir 'tmp', mode: 0700
170180
#
171181
def mkdir(list, mode: nil, noop: nil, verbose: nil)
172182
list = fu_list(list)
@@ -185,7 +195,7 @@ def mkdir(list, mode: nil, noop: nil, verbose: nil)
185195
#
186196
# FileUtils.mkdir_p '/usr/local/lib/ruby'
187197
#
188-
# causes to make following directories, if it does not exist.
198+
# causes to make following directories, if they do not exist.
189199
#
190200
# * /usr
191201
# * /usr/local
@@ -249,7 +259,7 @@ def fu_mkdir(path, mode) #:nodoc:
249259
# FileUtils.rmdir 'somedir'
250260
# FileUtils.rmdir %w(somedir anydir otherdir)
251261
# # Does not really remove directory; outputs message.
252-
# FileUtils.rmdir 'somedir', :verbose => true, :noop => true
262+
# FileUtils.rmdir 'somedir', verbose: true, noop: true
253263
#
254264
def rmdir(list, parents: nil, noop: nil, verbose: nil)
255265
list = fu_list(list)
@@ -278,7 +288,7 @@ def rmdir(list, parents: nil, noop: nil, verbose: nil)
278288
#
279289
# In the first form, creates a hard link +link+ which points to +target+.
280290
# If +link+ already exists, raises Errno::EEXIST.
281-
# But if the :force option is set, overwrites +link+.
291+
# But if the +force+ option is set, overwrites +link+.
282292
#
283293
# FileUtils.ln 'gcc', 'cc', verbose: true
284294
# FileUtils.ln '/usr/bin/emacs21', '/usr/bin/emacs'
@@ -304,23 +314,23 @@ def ln(src, dest, force: nil, noop: nil, verbose: nil)
304314
alias link ln
305315
module_function :link
306316

307-
#
308-
# :call-seq:
309-
# FileUtils.cp_lr(src, dest, noop: nil, verbose: nil, dereference_root: true, remove_destination: false)
310317
#
311318
# Hard link +src+ to +dest+. If +src+ is a directory, this method links
312319
# all its contents recursively. If +dest+ is a directory, links
313320
# +src+ to +dest/src+.
314321
#
315322
# +src+ can be a list of files.
316323
#
317-
# # Installing the library "mylib" under the site_ruby directory.
318-
# FileUtils.rm_r site_ruby + '/mylib', :force => true
324+
# If +dereference_root+ is true, this method dereference tree root.
325+
#
326+
# If +remove_destination+ is true, this method removes each destination file before copy.
327+
#
328+
# FileUtils.rm_r site_ruby + '/mylib', force: true
319329
# FileUtils.cp_lr 'lib/', site_ruby + '/mylib'
320330
#
321331
# # Examples of linking several files to target directory.
322332
# FileUtils.cp_lr %w(mail.rb field.rb debug/), site_ruby + '/tmail'
323-
# FileUtils.cp_lr Dir.glob('*.rb'), '/home/aamine/lib/ruby', :noop => true, :verbose => true
333+
# FileUtils.cp_lr Dir.glob('*.rb'), '/home/aamine/lib/ruby', noop: true, verbose: true
324334
#
325335
# # If you want to link all contents of a directory instead of the
326336
# # directory itself, c.f. src/x -> dest/x, src/y -> dest/y,
@@ -345,7 +355,7 @@ def cp_lr(src, dest, noop: nil, verbose: nil,
345355
#
346356
# In the first form, creates a symbolic link +link+ which points to +target+.
347357
# If +link+ already exists, raises Errno::EEXIST.
348-
# But if the :force option is set, overwrites +link+.
358+
# But if the <tt>force</tt> option is set, overwrites +link+.
349359
#
350360
# FileUtils.ln_s '/usr/bin/ruby', '/usr/local/bin/ruby'
351361
# FileUtils.ln_s 'verylongsourcefilename.c', 'c', force: true
@@ -411,7 +421,7 @@ def link_entry(src, dest, dereference_root = false, remove_destination = false)
411421
#
412422
# FileUtils.cp 'eval.c', 'eval.c.org'
413423
# FileUtils.cp %w(cgi.rb complex.rb date.rb), '/usr/lib/ruby/1.6'
414-
# FileUtils.cp %w(cgi.rb complex.rb date.rb), '/usr/lib/ruby/1.6', :verbose => true
424+
# FileUtils.cp %w(cgi.rb complex.rb date.rb), '/usr/lib/ruby/1.6', verbose: true
415425
# FileUtils.cp 'symlink', 'dest' # copy content, "dest" is not a symlink
416426
#
417427
def cp(src, dest, preserve: nil, noop: nil, verbose: nil)
@@ -433,13 +443,17 @@ def cp(src, dest, preserve: nil, noop: nil, verbose: nil)
433443
#
434444
# +src+ can be a list of files.
435445
#
446+
# If +dereference_root+ is true, this method dereference tree root.
447+
#
448+
# If +remove_destination+ is true, this method removes each destination file before copy.
449+
#
436450
# # Installing Ruby library "mylib" under the site_ruby
437-
# FileUtils.rm_r site_ruby + '/mylib', :force
451+
# FileUtils.rm_r site_ruby + '/mylib', force: true
438452
# FileUtils.cp_r 'lib/', site_ruby + '/mylib'
439453
#
440454
# # Examples of copying several files to target directory.
441455
# FileUtils.cp_r %w(mail.rb field.rb debug/), site_ruby + '/tmail'
442-
# FileUtils.cp_r Dir.glob('*.rb'), '/home/foo/lib/ruby', :noop => true, :verbose => true
456+
# FileUtils.cp_r Dir.glob('*.rb'), '/home/foo/lib/ruby', noop: true, verbose: true
443457
#
444458
# # If you want to copy all contents of a directory instead of the
445459
# # directory itself, c.f. src/x -> dest/x, src/y -> dest/y,
@@ -511,10 +525,10 @@ def copy_stream(src, dest)
511525
# disk partition, the file is copied then the original file is removed.
512526
#
513527
# FileUtils.mv 'badname.rb', 'goodname.rb'
514-
# FileUtils.mv 'stuff.rb', '/notexist/lib/ruby', :force => true # no error
528+
# FileUtils.mv 'stuff.rb', '/notexist/lib/ruby', force: true # no error
515529
#
516530
# FileUtils.mv %w(junk.txt dust.txt), '/home/foo/.trash/'
517-
# FileUtils.mv Dir.glob('test*.rb'), 'test', :noop => true, :verbose => true
531+
# FileUtils.mv Dir.glob('test*.rb'), 'test', noop: true, verbose: true
518532
#
519533
def mv(src, dest, force: nil, noop: nil, verbose: nil, secure: nil)
520534
fu_output_message "mv#{force ? ' -f' : ''} #{[src,dest].flatten.join ' '}" if verbose
@@ -553,7 +567,7 @@ def mv(src, dest, force: nil, noop: nil, verbose: nil, secure: nil)
553567
#
554568
# FileUtils.rm %w( junk.txt dust.txt )
555569
# FileUtils.rm Dir.glob('*.so')
556-
# FileUtils.rm 'NotExistFile', :force => true # never raises exception
570+
# FileUtils.rm 'NotExistFile', force: true # never raises exception
557571
#
558572
def rm(list, force: nil, noop: nil, verbose: nil)
559573
list = fu_list(list)
@@ -572,7 +586,7 @@ def rm(list, force: nil, noop: nil, verbose: nil)
572586
#
573587
# Equivalent to
574588
#
575-
# FileUtils.rm(list, :force => true)
589+
# FileUtils.rm(list, force: true)
576590
#
577591
def rm_f(list, noop: nil, verbose: nil)
578592
rm list, force: true, noop: noop, verbose: verbose
@@ -588,18 +602,18 @@ def rm_f(list, noop: nil, verbose: nil)
588602
# StandardError when :force option is set.
589603
#
590604
# FileUtils.rm_r Dir.glob('/tmp/*')
591-
# FileUtils.rm_r 'some_dir', :force => true
605+
# FileUtils.rm_r 'some_dir', force: true
592606
#
593607
# WARNING: This method causes local vulnerability
594608
# if one of parent directories or removing directory tree are world
595609
# writable (including /tmp, whose permission is 1777), and the current
596610
# process has strong privilege such as Unix super user (root), and the
597611
# system has symbolic link. For secure removing, read the documentation
598-
# of #remove_entry_secure carefully, and set :secure option to true.
599-
# Default is :secure=>false.
612+
# of remove_entry_secure carefully, and set :secure option to true.
613+
# Default is <tt>secure: false</tt>.
600614
#
601-
# NOTE: This method calls #remove_entry_secure if :secure option is set.
602-
# See also #remove_entry_secure.
615+
# NOTE: This method calls remove_entry_secure if :secure option is set.
616+
# See also remove_entry_secure.
603617
#
604618
def rm_r(list, force: nil, noop: nil, verbose: nil, secure: nil)
605619
list = fu_list(list)
@@ -618,10 +632,10 @@ def rm_r(list, force: nil, noop: nil, verbose: nil, secure: nil)
618632
#
619633
# Equivalent to
620634
#
621-
# FileUtils.rm_r(list, :force => true)
635+
# FileUtils.rm_r(list, force: true)
622636
#
623637
# WARNING: This method causes local vulnerability.
624-
# Read the documentation of #rm_r first.
638+
# Read the documentation of rm_r first.
625639
#
626640
def rm_rf(list, noop: nil, verbose: nil, secure: nil)
627641
rm_r list, force: true, noop: noop, verbose: verbose, secure: secure
@@ -635,7 +649,7 @@ def rm_rf(list, noop: nil, verbose: nil, secure: nil)
635649
# This method removes a file system entry +path+. +path+ shall be a
636650
# regular file, a directory, or something. If +path+ is a directory,
637651
# remove it recursively. This method is required to avoid TOCTTOU
638-
# (time-of-check-to-time-of-use) local security vulnerability of #rm_r.
652+
# (time-of-check-to-time-of-use) local security vulnerability of rm_r.
639653
# #rm_r causes security hole when:
640654
#
641655
# * Parent directory is world writable (including /tmp).
@@ -754,7 +768,7 @@ def fu_stat_identical_entry?(a, b) #:nodoc:
754768
# +path+ might be a regular file, a directory, or something.
755769
# If +path+ is a directory, remove it recursively.
756770
#
757-
# See also #remove_entry_secure.
771+
# See also remove_entry_secure.
758772
#
759773
def remove_entry(path, force = false)
760774
Entry_.new(path).postorder_traverse do |ent|
@@ -838,8 +852,8 @@ def compare_stream(a, b)
838852
# mode to +mode+. If +dest+ is a directory, destination is +dest+/+src+.
839853
# This method removes destination before copy.
840854
#
841-
# FileUtils.install 'ruby', '/usr/local/bin/ruby', :mode => 0755, :verbose => true
842-
# FileUtils.install 'lib.rb', '/usr/local/lib/ruby/site_ruby', :verbose => true
855+
# FileUtils.install 'ruby', '/usr/local/bin/ruby', mode: 0755, verbose: true
856+
# FileUtils.install 'lib.rb', '/usr/local/lib/ruby/site_ruby', verbose: true
843857
#
844858
def install(src, dest, mode: nil, owner: nil, group: nil, preserve: nil,
845859
noop: nil, verbose: nil)
@@ -969,12 +983,12 @@ def mode_to_s(mode) #:nodoc:
969983
# Absolute mode is
970984
# FileUtils.chmod 0755, 'somecommand'
971985
# FileUtils.chmod 0644, %w(my.rb your.rb his.rb her.rb)
972-
# FileUtils.chmod 0755, '/usr/bin/ruby', :verbose => true
986+
# FileUtils.chmod 0755, '/usr/bin/ruby', verbose: true
973987
#
974988
# Symbolic mode is
975989
# FileUtils.chmod "u=wrx,go=rx", 'somecommand'
976990
# FileUtils.chmod "u=wr,go=rr", %w(my.rb your.rb his.rb her.rb)
977-
# FileUtils.chmod "u=wrx,go=rx", '/usr/bin/ruby', :verbose => true
991+
# FileUtils.chmod "u=wrx,go=rx", '/usr/bin/ruby', verbose: true
978992
#
979993
# "a" :: is user, group, other mask.
980994
# "u" :: is user's mask.
@@ -1034,7 +1048,7 @@ def chmod_R(mode, list, noop: nil, verbose: nil, force: nil)
10341048
# the attribute.
10351049
#
10361050
# FileUtils.chown 'root', 'staff', '/usr/local/bin/ruby'
1037-
# FileUtils.chown nil, 'bin', Dir.glob('/usr/bin/*'), :verbose => true
1051+
# FileUtils.chown nil, 'bin', Dir.glob('/usr/bin/*'), verbose: true
10381052
#
10391053
def chown(user, group, list, noop: nil, verbose: nil)
10401054
list = fu_list(list)
@@ -1058,7 +1072,7 @@ def chown(user, group, list, noop: nil, verbose: nil)
10581072
# method does not change the attribute.
10591073
#
10601074
# FileUtils.chown_R 'www', 'www', '/var/www/htdocs'
1061-
# FileUtils.chown_R 'cvs', 'cvs', '/var/cvs', :verbose => true
1075+
# FileUtils.chown_R 'cvs', 'cvs', '/var/cvs', verbose: true
10621076
#
10631077
def chown_R(user, group, list, noop: nil, verbose: nil, force: nil)
10641078
list = fu_list(list)
@@ -1607,8 +1621,11 @@ def fu_output_message(msg) #:nodoc:
16071621
tbl
16081622
}
16091623

1624+
public
1625+
16101626
#
1611-
# Returns an Array of method names which have any options.
1627+
# Returns an Array of names of high-level methods that accept any keyword
1628+
# arguments.
16121629
#
16131630
# p FileUtils.commands #=> ["chmod", "cp", "cp_r", "install", ...]
16141631
#
@@ -1647,22 +1664,24 @@ def self.options_of(mid)
16471664
end
16481665

16491666
#
1650-
# Returns an Array of method names which have the option +opt+.
1667+
# Returns an Array of methods names which have the option +opt+.
16511668
#
16521669
# p FileUtils.collect_method(:preserve) #=> ["cp", "cp_r", "copy", "install"]
16531670
#
16541671
def self.collect_method(opt)
16551672
OPT_TABLE.keys.select {|m| OPT_TABLE[m].include?(opt) }
16561673
end
16571674

1658-
LOW_METHODS = singleton_methods(false) - collect_method(:noop).map(&:intern)
1659-
module LowMethods
1675+
private
1676+
1677+
LOW_METHODS = singleton_methods(false) - collect_method(:noop).map(&:intern) # :nodoc:
1678+
module LowMethods # :nodoc: internal use only
16601679
private
16611680
def _do_nothing(*)end
16621681
::FileUtils::LOW_METHODS.map {|name| alias_method name, :_do_nothing}
16631682
end
16641683

1665-
METHODS = singleton_methods() - [:private_module_function,
1684+
METHODS = singleton_methods() - [:private_module_function, # :nodoc:
16661685
:commands, :options, :have_option?, :options_of, :collect_method]
16671686

16681687
#

0 commit comments

Comments
 (0)