Merge pull request #5304 from KAAtheWiseGit/main

`rm`: make the utility public

.vscode/cspell.dictionaries/acronyms+names.wordlist.txt

@@ -58,6 +58,7 @@ MinGW
 Minix
 NetBSD
 Novell
+Nushell
 OpenBSD
 POSIX
 PowerPC

src/uu/rm/src/rm.rs

@@ -18,22 +18,52 @@ use uucore::{format_usage, help_about, help_section, help_usage, prompt_yes, sho
 use walkdir::{DirEntry, WalkDir};
 
 #[derive(Eq, PartialEq, Clone, Copy)]
-enum InteractiveMode {
+/// Enum, determining when the `rm` will prompt the user about the file deletion
+pub enum InteractiveMode {
+    /// Never prompt
     Never,
+    /// Prompt once before removing more than three files, or when removing
+    /// recursively.
     Once,
+    /// Prompt before every removal
     Always,
+    /// Prompt only on write-protected files
     PromptProtected,
 }
 
-struct Options {
+/// Options for the `rm` command
-    force: bool,
+///
-    interactive: InteractiveMode,
+/// All options are public so that the options can be programmatically
+/// constructed by other crates, such as Nushell. That means that this struct
+/// is part of our public API. It should therefore not be changed without good
+/// reason.
+///
+/// The fields are documented with the arguments that determine their value.
+pub struct Options {
+    /// `-f`, `--force`
+    pub force: bool,
+    /// Iterative mode, determines when the command will prompt.
+    ///
+    /// Set by the following arguments:
+    /// - `-i`: [`InteractiveMode::Always`]
+    /// - `-I`: [`InteractiveMode::Once`]
+    /// - `--interactive`: sets one of the above or [`InteractiveMode::Never`]
+    /// - `-f`: implicitly sets [`InteractiveMode::Never`]
+    ///
+    /// If no other option sets this mode, [`InteractiveMode::PromptProtected`]
+    /// is used
+    pub interactive: InteractiveMode,
     #[allow(dead_code)]
-    one_fs: bool,
+    /// `--one-file-system`
-    preserve_root: bool,
+    pub one_fs: bool,
-    recursive: bool,
+    /// `--preserve-root`/`--no-preserve-root`
-    dir: bool,
+    pub preserve_root: bool,
-    verbose: bool,
+    /// `-r`, `--recursive`
+    pub recursive: bool,
+    /// `-d`, `--dir`
+    pub dir: bool,
+    /// `-v`, `--verbose`
+    pub verbose: bool,
 }
 
 const ABOUT: &str = help_about!("rm.md");
@@ -249,7 +279,13 @@ pub fn uu_app() -> Command {
 }
 
 // TODO: implement one-file-system (this may get partially implemented in walkdir)
-fn remove(files: &[&OsStr], options: &Options) -> bool {
+/// Remove (or unlink) the given files
+///
+/// Returns true if it has encountered an error.
+///
+/// Behavior is determined by the `options` parameter, see [`Options`] for
+/// details.
+pub fn remove(files: &[&OsStr], options: &Options) -> bool {
     let mut had_err = false;
 
     for filename in files {
@@ -268,7 +304,7 @@ fn remove(files: &[&OsStr], options: &Options) -> bool {
                 // TODO: actually print out the specific error
                 // TODO: When the error is not about missing files
                 // (e.g., permission), even rm -f should fail with
-                // outputting the error, but there's no easy eay.
+                // outputting the error, but there's no easy way.
                 if options.force {
                     false
                 } else {