From fb6d5b906037ef0e957446fc696e6a7d07790325 Mon Sep 17 00:00:00 2001 From: naruse Date: Sun, 12 Mar 2017 18:01:40 +0000 Subject: merge revision(s) 57811: [Backport #9829] docs for FileUtils.ln methods * lib/fileutils.rb: [DOC] add clarifying call-seq's for FileUtil.ln, ln_s, and ln_sf, with better argument names for the created link and link target. Reported by Mike Vastola. [ruby-core:62532] [Bug #9829] * lib/fileutils.rb: [DOC] further improve descriptions of FileUtils.ln and related methods; improve examples: relative links probably won't work in other dir, avoid `include', use more generic homedir name. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_2_4@57940 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- lib/fileutils.rb | 70 ++++++++++++++++++++++++++++++-------------------------- 1 file changed, 37 insertions(+), 33 deletions(-) (limited to 'lib') diff --git a/lib/fileutils.rb b/lib/fileutils.rb index 5d769ac32b..6662b90932 100644 --- a/lib/fileutils.rb +++ b/lib/fileutils.rb @@ -24,11 +24,11 @@ # FileUtils.mkdir_p(list, options) # FileUtils.rmdir(dir, options) # FileUtils.rmdir(list, options) -# FileUtils.ln(old, new, options) -# FileUtils.ln(list, destdir, options) -# FileUtils.ln_s(old, new, options) -# FileUtils.ln_s(list, destdir, options) -# FileUtils.ln_sf(src, dest, 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) @@ -259,23 +259,24 @@ module FileUtils module_function :rmdir # - # ln(old, new, **options) + # :call-seq: + # FileUtils.ln(target, link, force: nil, noop: nil, verbose: nil) + # FileUtils.ln(target, dir, force: nil, noop: nil, verbose: nil) + # FileUtils.ln(targets, dir, force: nil, noop: nil, verbose: nil) # - # Creates a hard link +new+ which points to +old+. - # If +new+ already exists and it is a directory, creates a link +new/old+. - # If +new+ already exists and it is not a directory, raises Errno::EEXIST. - # But if :force option is set, overwrite +new+. + # 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+. # - # FileUtils.ln 'gcc', 'cc', :verbose => true + # FileUtils.ln 'gcc', 'cc', verbose: true # FileUtils.ln '/usr/bin/emacs21', '/usr/bin/emacs' # - # ln(list, destdir, **options) + # In the second form, creates a link +dir/target+ pointing to +target+. + # In the third form, creates several hard links in the directory +dir+, + # pointing to each item in +targets+. + # If +dir+ is not a directory, raises Errno::ENOTDIR. # - # Creates several hard links in a directory, with each one pointing to the - # item in +list+. If +destdir+ is not a directory, raises Errno::ENOTDIR. - # - # include FileUtils - # cd '/sbin' + # FileUtils.cd '/sbin' # FileUtils.ln %w(cp mv mkdir), '/bin' # Now /sbin/cp and /bin/cp are linked. # def ln(src, dest, force: nil, noop: nil, verbose: nil) @@ -292,24 +293,24 @@ module FileUtils module_function :link # - # ln_s(old, new, **options) + # :call-seq: + # FileUtils.ln_s(target, link, force: nil, noop: nil, verbose: nil) + # FileUtils.ln_s(target, dir, force: nil, noop: nil, verbose: nil) + # FileUtils.ln_s(targets, dir, force: nil, noop: nil, verbose: nil) # - # Creates a symbolic link +new+ which points to +old+. If +new+ already - # exists and it is a directory, creates a symbolic link +new/old+. If +new+ - # already exists and it is not a directory, raises Errno::EEXIST. But if - # :force option is set, overwrite +new+. + # 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+. # # FileUtils.ln_s '/usr/bin/ruby', '/usr/local/bin/ruby' - # FileUtils.ln_s 'verylongsourcefilename.c', 'c', :force => true - # - # ln_s(list, destdir, **options) + # FileUtils.ln_s 'verylongsourcefilename.c', 'c', force: true # - # Creates several symbolic links in a directory, with each one pointing to the - # item in +list+. If +destdir+ is not a directory, raises Errno::ENOTDIR. + # In the second form, creates a link +dir/target+ pointing to +target+. + # In the third form, creates several symbolic links in the directory +dir+, + # pointing to each item in +targets+. + # If +dir+ is not a directory, raises Errno::ENOTDIR. # - # If +destdir+ is not a directory, raises Errno::ENOTDIR. - # - # FileUtils.ln_s Dir.glob('bin/*.rb'), '/home/aamine/bin' + # FileUtils.ln_s Dir.glob('/bin/*.rb'), '/home/foo/bin' # def ln_s(src, dest, force: nil, noop: nil, verbose: nil) fu_output_message "ln -s#{force ? 'f' : ''} #{[src,dest].flatten.join ' '}" if verbose @@ -324,10 +325,13 @@ module FileUtils alias symlink ln_s module_function :symlink + # + # :call-seq: + # FileUtils.ln_sf(*args) # # Same as # - # FileUtils.ln_s(src, dest, :force => true) + # FileUtils.ln_s(*args, force: true) # def ln_sf(src, dest, noop: nil, verbose: nil) ln_s src, dest, force: true, noop: noop, verbose: verbose @@ -370,7 +374,7 @@ module FileUtils # # # 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/aamine/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, @@ -444,7 +448,7 @@ module FileUtils # FileUtils.mv 'badname.rb', 'goodname.rb' # FileUtils.mv 'stuff.rb', '/notexist/lib/ruby', :force => true # no error # - # FileUtils.mv %w(junk.txt dust.txt), '/home/aamine/.trash/' + # FileUtils.mv %w(junk.txt dust.txt), '/home/foo/.trash/' # FileUtils.mv Dir.glob('test*.rb'), 'test', :noop => true, :verbose => true # def mv(src, dest, force: nil, noop: nil, verbose: nil, secure: nil) -- cgit v1.2.3