Skip to content

Commit 9db4cb1

Browse files
Enhanced RDoc (#82)
Treats ::chmod; adds Pathname usage to ::install.
1 parent b9d5a79 commit 9db4cb1

File tree

1 file changed

+79
-34
lines changed

1 file changed

+79
-34
lines changed

lib/fileutils.rb

Lines changed: 79 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1357,11 +1357,18 @@ def compare_stream(a, b)
13571357
#
13581358
# If the entry at +dest+ does not exist, copies from +src+ to +dest+:
13591359
#
1360+
# # With string paths.
13601361
# File.read('src0.txt') # => "aaa\n"
13611362
# File.exist?('dest0.txt') # => false
13621363
# FileUtils.install('src0.txt', 'dest0.txt')
13631364
# File.read('dest0.txt') # => "aaa\n"
13641365
#
1366+
# # With Pathnames.
1367+
# require 'pathname'
1368+
# src_path = Pathname.new('src0.txt')
1369+
# dest_path = Pathname.new('dest0.txt')
1370+
# FileUtils.install(src_path, dest_path)
1371+
#
13651372
# If +dest+ is a file entry, copies from +src+ to +dest+, overwriting:
13661373
#
13671374
# File.read('src1.txt') # => "aaa\n"
@@ -1379,10 +1386,6 @@ def compare_stream(a, b)
13791386
#
13801387
# Keyword arguments:
13811388
#
1382-
# {chown(2)}[https://man7.org/linux/man-pages/man2/chown.2.html]
1383-
# and {chmod(2)}[https://man7.org/linux/man-pages/man2/chmod.2.html]
1384-
#
1385-
#
13861389
# - <tt>group: <i>group</i></tt> - changes the group if not +nil+,
13871390
# using {File.chown}[https://docs.ruby-lang.org/en/master/File.html#method-c-chown].
13881391
# - <tt>mode: <i>permissions</i></tt> - changes the permissions.
@@ -1520,37 +1523,79 @@ def mode_to_s(mode) #:nodoc:
15201523
end
15211524
private_module_function :mode_to_s
15221525

1526+
# Changes permissions on the entries at the paths given in +list+
1527+
# to the permissions given by +mode+:
1528+
#
1529+
# - Modifies each entry that is a regular file using
1530+
# {File.chmod}[https://docs.ruby-lang.org/en/master/File.html#method-c-chmod].
1531+
# - Modifies each entry that is a symbolic link using
1532+
# {File.lchmod}[https://docs.ruby-lang.org/en/master/File.html#method-c-lchmod].
1533+
#
1534+
# Each path may be either a string or a
1535+
# {Pathname}[https://docs.ruby-lang.org/en/master/Pathname.html].
1536+
#
1537+
# Argument +mode+ may be either an integer or a string:
1538+
#
1539+
# - \Integer +mode+: represents the permission bits to be set:
1540+
#
1541+
# # List is a string path.
1542+
# FileUtils.chmod(0755, 'src0.txt')
1543+
# # List is an array of string paths.
1544+
# FileUtils.chmod(0644, ['src0.txt', 'src0.dat'])
1545+
# # List is a Pathname.
1546+
# require 'pathname'
1547+
# path = Pathname.new('src0.txt')
1548+
# FileUtils.chmod(0755, path)
1549+
#
1550+
# - \String +mode+: represents the permissions to be set:
1551+
#
1552+
# The string is of the form <tt>[targets][[operator][perms[,perms]]</tt>, where:
1553+
#
1554+
# - +targets+ may be any combination of these letters:
1555+
#
1556+
# - <tt>'u'</tt>: permissions apply to the file's owner.
1557+
# - <tt>'g'</tt>: permissions apply to users in the file's group.
1558+
# - <tt>'o'</tt>: permissions apply to other users not in the file's group.
1559+
# - <tt>'a'</tt> (the default): permissions apply to all users.
1560+
#
1561+
# - +operator+ may be one of these letters:
1562+
#
1563+
# - <tt>'+'</tt>: adds permissions.
1564+
# - <tt>'-'</tt>: removes permissions.
1565+
# - <tt>'='</tt>: sets (replaces) permissions.
1566+
#
1567+
# - +perms+ (may be repeated, with separating commas)
1568+
# may be any combination of these letters:
1569+
#
1570+
# - <tt>'r'</tt>: Read.
1571+
# - <tt>'w'</tt>: Write.
1572+
# - <tt>'x'</tt>: Execute (search, for a directory).
1573+
# - <tt>'X'</tt>: Search (for a directories only;
1574+
# must be used with <tt>'+'</tt>)
1575+
# - <tt>'s'</tt>: Uid or gid.
1576+
# - <tt>'t'</tt>: Sticky bit.
1577+
#
1578+
# Examples:
1579+
#
1580+
# FileUtils.chmod('u=wrx,go=rx', 'src1.txt')
1581+
# FileUtils.chmod('u=wrx,go=rx', '/usr/bin/ruby')
1582+
# Keyword arguments:
1583+
#
1584+
# - <tt>noop: true</tt> - does not change permissions; returns +nil+.
1585+
# - <tt>verbose: true</tt> - prints an equivalent command:
1586+
#
1587+
# FileUtils.chmod(0755, 'src0.txt', noop: true, verbose: true)
1588+
# FileUtils.chmod(0644, ['src0.txt', 'src0.dat'], noop: true, verbose: true)
1589+
# FileUtils.chmod('u=wrx,go=rx', 'src1.txt', noop: true, verbose: true)
1590+
# FileUtils.chmod('u=wrx,go=rx', '/usr/bin/ruby', noop: true, verbose: true)
1591+
#
1592+
# Output:
1593+
#
1594+
# chmod 755 src0.txt
1595+
# chmod 644 src0.txt src0.dat
1596+
# chmod u=wrx,go=rx src1.txt
1597+
# chmod u=wrx,go=rx /usr/bin/ruby
15231598
#
1524-
# Changes permission bits on the named files (in +list+) to the bit pattern
1525-
# represented by +mode+.
1526-
#
1527-
# +mode+ is the symbolic and absolute mode can be used.
1528-
#
1529-
# Absolute mode is
1530-
# FileUtils.chmod 0755, 'somecommand'
1531-
# FileUtils.chmod 0644, %w(my.rb your.rb his.rb her.rb)
1532-
# FileUtils.chmod 0755, '/usr/bin/ruby', verbose: true
1533-
#
1534-
# Symbolic mode is
1535-
# FileUtils.chmod "u=wrx,go=rx", 'somecommand'
1536-
# FileUtils.chmod "u=wr,go=rr", %w(my.rb your.rb his.rb her.rb)
1537-
# FileUtils.chmod "u=wrx,go=rx", '/usr/bin/ruby', verbose: true
1538-
#
1539-
# "a" :: is user, group, other mask.
1540-
# "u" :: is user's mask.
1541-
# "g" :: is group's mask.
1542-
# "o" :: is other's mask.
1543-
# "w" :: is write permission.
1544-
# "r" :: is read permission.
1545-
# "x" :: is execute permission.
1546-
# "X" ::
1547-
# is execute permission for directories only, must be used in conjunction with "+"
1548-
# "s" :: is uid, gid.
1549-
# "t" :: is sticky bit.
1550-
# "+" :: is added to a class given the specified mode.
1551-
# "-" :: Is removed from a given class given mode.
1552-
# "=" :: Is the exact nature of the class will be given a specified mode.
1553-
15541599
def chmod(mode, list, noop: nil, verbose: nil)
15551600
list = fu_list(list)
15561601
fu_output_message sprintf('chmod %s %s', mode_to_s(mode), list.join(' ')) if verbose

0 commit comments

Comments
 (0)