From ecef11bf2c396eb66af1bca471b2d26917c6e6ff Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 16 Jun 2022 08:08:25 -0700 Subject: [PATCH 1/3] Revisions for module-level doc --- lib/fileutils.rb | 117 ++++++++++++----------------------------------- 1 file changed, 30 insertions(+), 87 deletions(-) diff --git a/lib/fileutils.rb b/lib/fileutils.rb index 5aa761e..97a2555 100644 --- a/lib/fileutils.rb +++ b/lib/fileutils.rb @@ -6,17 +6,7 @@ # for make mjit-headers end -# -# = fileutils.rb -# -# Copyright (c) 2000-2007 Minero Aoki -# -# This program is free software. -# You can distribute/modify this program under the same terms of ruby. -# -# == module FileUtils -# -# Namespace for several file utility methods for copying, moving, removing, etc. +# Namespace for file utility methods for copying, moving, removing, etc. # # == Path Arguments # @@ -59,88 +49,41 @@ # |-- find_executable.rb # `-- helper.rb # -# === Module Functions -# -# require 'fileutils' -# -# FileUtils.cd(dir, **options) -# FileUtils.cd(dir, **options) {|dir| block } -# FileUtils.pwd() -# FileUtils.mkdir(dir, **options) -# FileUtils.mkdir(list, **options) -# FileUtils.mkdir_p(dir, **options) -# FileUtils.mkdir_p(list, **options) -# FileUtils.rmdir(dir, **options) -# FileUtils.rmdir(list, **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) -# FileUtils.cp_r(list, dir, **options) -# FileUtils.mv(src, dest, **options) -# FileUtils.mv(list, dir, **options) -# FileUtils.rm(list, **options) -# FileUtils.rm_r(list, **options) -# FileUtils.rm_rf(list, **options) -# FileUtils.install(src, dest, **options) -# FileUtils.chmod(mode, list, **options) -# FileUtils.chmod_R(mode, list, **options) -# FileUtils.chown(user, group, list, **options) -# FileUtils.chown_R(user, group, list, **options) -# FileUtils.touch(list, **options) -# -# Possible options are: -# -# :force :: forced operation (rewrite files if exist, remove -# directories if not empty, etc.); -# :verbose :: print command to be run, in bash syntax, before -# performing it; -# :preserve :: preserve object's group, user and modification -# time on copying; -# :noop :: no changes are made (usable in combination with -# :verbose which will print the command to run) -# -# Each method documents the options that it honours. See also ::commands, -# ::options and ::options_of methods to introspect which command have which -# options. -# -# All methods that have the concept of a "source" file or directory can take -# either one file or a list of files in that argument. See the method -# documentation for examples. -# -# There are some `low level' methods, which do not accept keyword arguments: +# == Options # -# FileUtils.copy_entry(src, dest, preserve = false, dereference_root = false, remove_destination = false) -# FileUtils.copy_file(src, dest, preserve = false, dereference = true) -# FileUtils.copy_stream(srcstream, deststream) -# FileUtils.remove_entry(path, force = false) -# FileUtils.remove_entry_secure(path, force = false) -# FileUtils.remove_file(path, force = false) -# FileUtils.compare_file(path_a, path_b) -# FileUtils.compare_stream(stream_a, stream_b) -# FileUtils.uptodate?(file, cmp_list) +# Options to the methods are given as keyword arguments. # -# == module FileUtils::Verbose +# The most common options (often useful together) are: # -# This module has all methods of FileUtils module, but it outputs messages -# before acting. This equates to passing the :verbose flag to methods -# in FileUtils. +# - +noop+: Do not actually make modifications. +# - +verbose+: Print a command that is equivalent to the method +# called with the given arguments and options. # -# == module FileUtils::NoWrite +# Other options include: # -# This module has all methods of FileUtils module, but never changes -# files/directories. This equates to passing the :noop flag to methods -# in FileUtils. +# - +dereference_root+: Whether, if the argument is a symbolic, to follow it. +# - +force+: Whether to force the operation +# (overwrite entries, remove non-empty directory, etc.). +# - +group+: Sets an entry's group. +# - +mode+: Sets an entry's permissions. +# - +mtime+: Sets an entry's modification time. +# - +nocreate+: Whether to raise an exception if an entry does not exist +# (rather than creating the entry). +# - +owner+: Sets an entry's owner. +# - +parents+: Whether to remove empty ancestor directories. +# - +preserve+: Whether to preserve an entry's group, user, and modification time +# when copying. +# - +remove_destination+: Whether to remove the destination entry before copying +# to it. +# - +secure+: Whether to remove the source entry securely. # -# == module FileUtils::DryRun +# See also: # -# This module has all methods of FileUtils module, but never changes -# files/directories. This equates to passing the :noop and -# :verbose flags to methods in FileUtils. +# - ::commands: Returns an array of the string names of methods +# that accept keyword options. +# - ::have_option?: Returns whether the given method accepts the given option. +# - ::options: Returns an array of the option names. +# - ::options_of: Returns an array of the option-names that the given method accepts. # # == Avoiding the TOCTTOU Vulnerability # @@ -2411,7 +2354,7 @@ def fu_output_message(msg) #:nodoc: public # Returns an array of the string names of \FileUtils methods - # that accept one or more keyword arguments; + # that accept one or more keyword arguments: # # FileUtils.commands.sort.take(3) # => ["cd", "chdir", "chmod"] # From b8dc08f5f7be69255f3ef1658639bccf4049737a Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 16 Jun 2022 09:50:42 -0700 Subject: [PATCH 2/3] Revisions for module-leval doc --- lib/fileutils.rb | 115 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 79 insertions(+), 36 deletions(-) diff --git a/lib/fileutils.rb b/lib/fileutils.rb index 97a2555..d9e9e24 100644 --- a/lib/fileutils.rb +++ b/lib/fileutils.rb @@ -8,6 +8,85 @@ # Namespace for file utility methods for copying, moving, removing, etc. # +# == What's Here +# +# First, what’s elsewhere. \Module \FileUtils: +# +# - Inherits from {class Object}[https://docs.ruby-lang.org/en/master/Object.html]. +# - Supplements {class File}[https://docs.ruby-lang.org/en/master/File.html] +# (but is not included or extended there). +# +# Here, module \FileUtils provides methods that are useful for: +# +# - {Creating}[rdoc-ref:FileUtils@Creating]. +# - {Deleting}[rdoc-ref:FileUtils@Deleting]. +# - {Querying}[rdoc-ref:FileUtils@Querying]. +# - {Setting}[rdoc-ref:FileUtils@Setting]. +# - {Comparing}[rdoc-ref:FileUtils@Comparing]. +# - {Copying}[rdoc-ref:FileUtils@Copying]. +# - {Moving}[rdoc-ref:FileUtils@Copying]. +# +# === Creating +# +# - ::mkdir: Creates directories. +# - ::mkdir_p, ::makedirs, ::mkpath: Creates directories, +# also creating ancestor directories as needed. +# - ::link_entry: Creates a hard link. +# - ::ln, ::link: Creates hard links. +# - ::ln_s, ::symlink: Creates symbolic links. +# - ::ln_sf: Creates symbolic links, overwriting if necessary. +# +# === Deleting +# +# - ::remove_dir: Removes a directory and its descendants. +# - ::remove_entry: Removes an entry, including its descendants if it is a directory. +# - ::remove_entry_secure: Like ::remove_entry, but removes securely. +# - ::remove_file: Removes a file entry. +# - ::rm, ::remove: Removes entries. +# - ::rm_f, ::safe_unlink: Like ::rm, but removes forcibly. +# - ::rm_r: Removes entries and their descendants. +# - ::rm_rf, ::rmtree: Like ::rm_r, but removes forcibly. +# - ::rmdir: Removes directories and their descendants. +# +# === Querying +# +# - ::collect_method: Returns the names of methods that accept a given option. +# - ::commands: Returns the names of methods that accept options. +# - ::have_option?: Returns whether a given method accepts a given option. +# - ::options: Returns all option names. +# - ::options_of: Returns the names of the options for a given method. +# - ::pwd, ::getwd: Returns the path to the working directory. +# - ::uptodate?: Returns whether a given entry is newer than given other entries. +# +# === Setting +# +# - ::cd, ::chdir: Sets the working directory. +# - ::chmod: Sets permissions for an entry. +# - ::chmod_R: Sets permissions for an entry and its descendants. +# - ::chown: Sets the owner and group for entries. +# - ::chown_R: Sets the owner and group for entries and their descendants. +# - ::touch: Sets modification and access times for entries, +# creating if necessary. +# +# === Comparing +# +# - ::compare_file, ::cmp, ::identical?: Returns whether two entries are identical. +# - ::compare_stream: Returns whether two streams are identical. +# +# === Copying +# +# - ::copy_entry: Recursively copies an entry. +# - ::copy_file: Copies an entry. +# - ::copy_stream: Copies a stream. +# - ::cp, ::copy: Copies files. +# - ::cp_lr: Recursively creates hard links. +# - ::cp_r: Recursively copies files. +# - ::install: Recursively copies files (with options different from ::cp_r). +# +# === Moving +# +# - ::mv, ::move: Moves entries. +# # == Path Arguments # # Some methods in \FileUtils accept _path_ arguments, @@ -49,42 +128,6 @@ # |-- find_executable.rb # `-- helper.rb # -# == Options -# -# Options to the methods are given as keyword arguments. -# -# The most common options (often useful together) are: -# -# - +noop+: Do not actually make modifications. -# - +verbose+: Print a command that is equivalent to the method -# called with the given arguments and options. -# -# Other options include: -# -# - +dereference_root+: Whether, if the argument is a symbolic, to follow it. -# - +force+: Whether to force the operation -# (overwrite entries, remove non-empty directory, etc.). -# - +group+: Sets an entry's group. -# - +mode+: Sets an entry's permissions. -# - +mtime+: Sets an entry's modification time. -# - +nocreate+: Whether to raise an exception if an entry does not exist -# (rather than creating the entry). -# - +owner+: Sets an entry's owner. -# - +parents+: Whether to remove empty ancestor directories. -# - +preserve+: Whether to preserve an entry's group, user, and modification time -# when copying. -# - +remove_destination+: Whether to remove the destination entry before copying -# to it. -# - +secure+: Whether to remove the source entry securely. -# -# See also: -# -# - ::commands: Returns an array of the string names of methods -# that accept keyword options. -# - ::have_option?: Returns whether the given method accepts the given option. -# - ::options: Returns an array of the option names. -# - ::options_of: Returns an array of the option-names that the given method accepts. -# # == Avoiding the TOCTTOU Vulnerability # # For certain methods that recursively remove entries, From ec095e9f2ee69e6b828624ed822c754aafd00c7e Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 16 Jun 2022 14:05:04 -0700 Subject: [PATCH 3/3] Revisions for module-leval doc --- lib/fileutils.rb | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/lib/fileutils.rb b/lib/fileutils.rb index d9e9e24..23aef6e 100644 --- a/lib/fileutils.rb +++ b/lib/fileutils.rb @@ -25,6 +25,7 @@ # - {Comparing}[rdoc-ref:FileUtils@Comparing]. # - {Copying}[rdoc-ref:FileUtils@Copying]. # - {Moving}[rdoc-ref:FileUtils@Copying]. +# - {Options}[rdoc-ref:FileUtils@Options]. # # === Creating # @@ -46,15 +47,10 @@ # - ::rm_f, ::safe_unlink: Like ::rm, but removes forcibly. # - ::rm_r: Removes entries and their descendants. # - ::rm_rf, ::rmtree: Like ::rm_r, but removes forcibly. -# - ::rmdir: Removes directories and their descendants. +# - ::rmdir: Removes directories. # # === Querying # -# - ::collect_method: Returns the names of methods that accept a given option. -# - ::commands: Returns the names of methods that accept options. -# - ::have_option?: Returns whether a given method accepts a given option. -# - ::options: Returns all option names. -# - ::options_of: Returns the names of the options for a given method. # - ::pwd, ::getwd: Returns the path to the working directory. # - ::uptodate?: Returns whether a given entry is newer than given other entries. # @@ -87,6 +83,14 @@ # # - ::mv, ::move: Moves entries. # +# === Options +# +# - ::collect_method: Returns the names of methods that accept a given option. +# - ::commands: Returns the names of methods that accept options. +# - ::have_option?: Returns whether a given method accepts a given option. +# - ::options: Returns all option names. +# - ::options_of: Returns the names of the options for a given method. +# # == Path Arguments # # Some methods in \FileUtils accept _path_ arguments,