ruby-changes:72114
From: Burdette <ko1@a...>
Date: Fri, 10 Jun 2022 05:03:47 +0900 (JST)
Subject: [ruby-changes:72114] c2468fd88b (master): [ruby/fileutils] Enhanced RDoc (https://github.com/ruby/fileutils/pull/82)
https://git.ruby-lang.org/ruby.git/commit/?id=c2468fd88b From c2468fd88b977b1c0015fe7f49a822df1d07ea6f Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Thu, 9 Jun 2022 15:03:21 -0500 Subject: [ruby/fileutils] Enhanced RDoc (https://github.com/ruby/fileutils/pull/82) Treats ::chmod; adds Pathname usage to ::install. https://github.com/ruby/fileutils/commit/9db4cb129c --- lib/fileutils.rb | 113 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 79 insertions(+), 34 deletions(-) diff --git a/lib/fileutils.rb b/lib/fileutils.rb index 9208152f90..28ddd2a45c 100644 --- a/lib/fileutils.rb +++ b/lib/fileutils.rb @@ -1357,11 +1357,18 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L1357 # # If the entry at +dest+ does not exist, copies from +src+ to +dest+: # + # # With string paths. # File.read('src0.txt') # => "aaa\n" # File.exist?('dest0.txt') # => false # FileUtils.install('src0.txt', 'dest0.txt') # File.read('dest0.txt') # => "aaa\n" # + # # With Pathnames. + # require 'pathname' + # src_path = Pathname.new('src0.txt') + # dest_path = Pathname.new('dest0.txt') + # FileUtils.install(src_path, dest_path) + # # If +dest+ is a file entry, copies from +src+ to +dest+, overwriting: # # File.read('src1.txt') # => "aaa\n" @@ -1379,10 +1386,6 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L1386 # # Keyword arguments: # - # {chown(2)}[https://man7.org/linux/man-pages/man2/chown.2.html] - # and {chmod(2)}[https://man7.org/linux/man-pages/man2/chmod.2.html] - # - # # - <tt>group: <i>group</i></tt> - changes the group if not +nil+, # using {File.chown}[https://docs.ruby-lang.org/en/master/File.html#method-c-chown]. # - <tt>mode: <i>permissions</i></tt> - changes the permissions. @@ -1520,37 +1523,79 @@ module FileUtils https://github.com/ruby/ruby/blob/trunk/lib/fileutils.rb#L1523 end private_module_function :mode_to_s + # Changes permissions on the entries at the paths given in +list+ + # to the permissions given by +mode+: + # + # - Modifies each entry that is a regular file using + # {File.chmod}[https://docs.ruby-lang.org/en/master/File.html#method-c-chmod]. + # - Modifies each entry that is a symbolic link using + # {File.lchmod}[https://docs.ruby-lang.org/en/master/File.html#method-c-lchmod]. + # + # Each path may be either a string or a + # {Pathname}[https://docs.ruby-lang.org/en/master/Pathname.html]. + # + # Argument +mode+ may be either an integer or a string: + # + # - \Integer +mode+: represents the permission bits to be set: + # + # # List is a string path. + # FileUtils.chmod(0755, 'src0.txt') + # # List is an array of string paths. + # FileUtils.chmod(0644, ['src0.txt', 'src0.dat']) + # # List is a Pathname. + # require 'pathname' + # path = Pathname.new('src0.txt') + # FileUtils.chmod(0755, path) + # + # - \String +mode+: represents the permissions to be set: + # + # The string is of the form <tt>[targets][[operator][perms[,perms]]</tt>, where: + # + # - +targets+ may be any combination of these letters: + # + # - <tt>'u'</tt>: permissions apply to the file's owner. + # - <tt>'g'</tt>: permissions apply to users in the file's group. + # - <tt>'o'</tt>: permissions apply to other users not in the file's group. + # - <tt>'a'</tt> (the default): permissions apply to all users. + # + # - +operator+ may be one of these letters: + # + # - <tt>'+'</tt>: adds permissions. + # - <tt>'-'</tt>: removes permissions. + # - <tt>'='</tt>: sets (replaces) permissions. + # + # - +perms+ (may be repeated, with separating commas) + # may be any combination of these letters: + # + # - <tt>'r'</tt>: Read. + # - <tt>'w'</tt>: Write. + # - <tt>'x'</tt>: Execute (search, for a directory). + # - <tt>'X'</tt>: Search (for a directories only; + # must be used with <tt>'+'</tt>) + # - <tt>'s'</tt>: Uid or gid. + # - <tt>'t'</tt>: Sticky bit. + # + # Examples: + # + # FileUtils.chmod('u=wrx,go=rx', 'src1.txt') + # FileUtils.chmod('u=wrx,go=rx', '/usr/bin/ruby') + # Keyword arguments: + # + # - <tt>noop: true</tt> - does not change permissions; returns +nil+. + # - <tt>verbose: true</tt> - prints an equivalent command: + # + # FileUtils.chmod(0755, 'src0.txt', noop: true, verbose: true) + # FileUtils.chmod(0644, ['src0.txt', 'src0.dat'], noop: true, verbose: true) + # FileUtils.chmod('u=wrx,go=rx', 'src1.txt', noop: true, verbose: true) + # FileUtils.chmod('u=wrx,go=rx', '/usr/bin/ruby', noop: true, verbose: true) + # + # Output: + # + # chmod 755 src0.txt + # chmod 644 src0.txt src0.dat + # chmod u=wrx,go=rx src1.txt + # chmod u=wrx,go=rx /usr/bin/ruby # - # Changes permission bits on the named files (in +list+) to the bit pattern - # represented by +mode+. - # - # +mode+ is the symbolic and absolute mode can be used. - # - # Absolute mode is - # FileUtils.chmod 0755, 'somecommand' - # FileUtils.chmod 0644, %w(my.rb your.rb his.rb her.rb) - # FileUtils.chmod 0755, '/usr/bin/ruby', verbose: true - # - # Symbolic mode is - # FileUtils.chmod "u=wrx,go=rx", 'somecommand' - # FileUtils.chmod "u=wr,go=rr", %w(my.rb your.rb his.rb her.rb) - # FileUtils.chmod "u=wrx,go=rx", '/usr/bin/ruby', verbose: true - # - # "a" :: is user, group, other mask. - # "u" :: is user's mask. - # "g" :: is group's mask. - # "o" :: is other's mask. - # "w" :: is write permission. - # "r" :: is read permission. - # "x" :: is execute permission. - # "X" :: - # is execute permission for directories only, must be used in conjunction with "+" - # "s" :: is uid, gid. - # "t" :: is sticky bit. - # "+" :: is added to a class given the specified mode. - # "-" :: Is removed from a given class given mode. - # "=" :: Is the exact nature of the class will be given a specified mode. - def chmod(mode, list, noop: nil, verbose: nil) list = fu_list(list) fu_output_message sprintf('chmod %s %s', mode_to_s(mode), list.join(' ')) if verbose -- cgit v1.2.1 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/