From c2468fd88b977b1c0015fe7f49a822df1d07ea6f Mon Sep 17 00:00:00 2001 From: Burdette Lamar 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(-) (limited to 'lib/fileutils.rb') 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 # # 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 # # 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] - # - # # - group: group - changes the group if not +nil+, # using {File.chown}[https://docs.ruby-lang.org/en/master/File.html#method-c-chown]. # - mode: permissions - changes the permissions. @@ -1520,37 +1523,79 @@ module FileUtils 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 [targets][[operator][perms[,perms]], where: + # + # - +targets+ may be any combination of these letters: + # + # - 'u': permissions apply to the file's owner. + # - 'g': permissions apply to users in the file's group. + # - 'o': permissions apply to other users not in the file's group. + # - 'a' (the default): permissions apply to all users. + # + # - +operator+ may be one of these letters: + # + # - '+': adds permissions. + # - '-': removes permissions. + # - '=': sets (replaces) permissions. + # + # - +perms+ (may be repeated, with separating commas) + # may be any combination of these letters: + # + # - 'r': Read. + # - 'w': Write. + # - 'x': Execute (search, for a directory). + # - 'X': Search (for a directories only; + # must be used with '+') + # - 's': Uid or gid. + # - 't': Sticky bit. + # + # Examples: + # + # FileUtils.chmod('u=wrx,go=rx', 'src1.txt') + # FileUtils.chmod('u=wrx,go=rx', '/usr/bin/ruby') + # Keyword arguments: + # + # - noop: true - does not change permissions; returns +nil+. + # - verbose: true - 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.3