uutils · Its-Just-Nans · Apr 25, 2025 · Apr 25, 2025 · Apr 25, 2025 · Apr 25, 2025
diff --git a/Cargo.toml b/Cargo.toml
@@ -23,7 +23,7 @@ edition.workspace = true
 all-features = true
 
 [features]
-default = ["feat_common_core"]
+default = ["feat_common_core", "dep:zip"]
 ## OS feature shortcodes
 macos = ["feat_os_macos"]
 unix = ["feat_os_unix"]
@@ -35,7 +35,7 @@ expensive_tests = []
 # "test_risky_names" == enable tests that create problematic file names (would make a network share inaccessible to Windows, breaks SVN on Mac OS, etc.)
 test_risky_names = []
 # * only build `uudoc` when `--feature uudoc` is activated
-uudoc = ["zip", "dep:uuhelp_parser"]
+uudoc = ["dep:zip", "dep:uuhelp_parser"]
 ## features
 # "feat_acl" == enable support for ACLs (access control lists; by using`--features feat_acl`)
 # NOTE:
@@ -542,6 +542,7 @@ phf_codegen = { workspace = true }
 [[bin]]
 name = "coreutils"
 path = "src/bin/coreutils.rs"
+required-features = ["default"]
 
 [[bin]]
 name = "uudoc"

diff --git a/src/bin/coreutils.rs b/src/bin/coreutils.rs
@@ -10,19 +10,34 @@ use clap_complete::Shell;
 use std::cmp;
 use std::ffi::OsStr;
 use std::ffi::OsString;
+use std::fs::File;
+use std::io::Read;
+use std::io::Seek;
 use std::io::{self, Write};
 use std::path::{Path, PathBuf};
 use std::process;
 use uucore::display::Quotable;
+use zip::ZipArchive;
 
 const VERSION: &str = env!("CARGO_PKG_VERSION");
 
+const COMPLETION: &str = "completion";
+const MANPAGE: &str = "manpage";
+
 include!(concat!(env!("OUT_DIR"), "/uutils_map.rs"));
 
 fn usage<T>(utils: &UtilityMap<T>, name: &str) {
     println!("{name} {VERSION} (multi-call binary)\n");
     println!("Usage: {name} [function [arguments...]]");
-    println!("       {name} --list\n");
+    println!("       {name} --list");
+    println!();
+    println!("Functions:");
+    println!("      {COMPLETION}",);
+    println!("           {}", get_completion_args(utils).render_usage());
+    println!("      '{MANPAGE}'",);
+    println!("           {}", get_manpage_args(utils).render_usage());
+    println!("      '<uutils>' [arguments...]");
+    println!();
     println!("Options:");
     println!("      --list    lists all defined functions, one per row\n");
     println!("Currently defined functions:\n");
@@ -95,8 +110,14 @@ fn main() {
         };
 
         match util {
-            "completion" => gen_completions(args, &utils),
-            "manpage" => gen_manpage(args, &utils),
+            COMPLETION => {
+                gen_completions(args, &utils);
+                process::exit(0);
+            }
+            MANPAGE => {
+                gen_manpage(args, &utils);
+                process::exit(0);
+            }
             "--list" => {
                 let mut utils: Vec<_> = utils.keys().collect();
                 utils.sort();
@@ -148,18 +169,11 @@ fn main() {
     }
 }
 
-/// Prints completions for the utility in the first parameter for the shell in the second parameter to stdout
-/// # Panics
-/// Panics if the utility map is empty
-fn gen_completions<T: uucore::Args>(
-    args: impl Iterator<Item = OsString>,
-    util_map: &UtilityMap<T>,
-) -> ! {
+fn get_completion_args<T>(util_map: &UtilityMap<T>) -> clap::Command {
     let all_utilities: Vec<_> = std::iter::once("coreutils")
         .chain(util_map.keys().copied())
         .collect();
-
-    let matches = Command::new("completion")
+    Command::new(COMPLETION)
         .about("Prints completions to stdout")
         .arg(
             Arg::new("utility")
@@ -171,7 +185,17 @@ fn gen_completions<T: uucore::Args>(
                 .value_parser(clap::builder::EnumValueParser::<Shell>::new())
                 .required(true),
         )
-        .get_matches_from(std::iter::once(OsString::from("completion")).chain(args));
+}
+
+/// Prints completions for the utility in the first parameter for the shell in the second parameter to stdout
+/// # Panics
+/// Panics if the utility map is empty
+fn gen_completions<T: uucore::Args>(
+    args: impl Iterator<Item = OsString>,
+    util_map: &UtilityMap<T>,
+) {
+    let matches = get_completion_args(util_map)
+        .get_matches_from(std::iter::once(OsString::from(COMPLETION)).chain(args));
 
     let utility = matches.get_one::<String>("utility").unwrap();
     let shell = *matches.get_one::<Shell>("shell").unwrap();
@@ -185,42 +209,49 @@ fn gen_completions<T: uucore::Args>(
 
     clap_complete::generate(shell, &mut command, bin_name, &mut io::stdout());
     io::stdout().flush().unwrap();
-    process::exit(0);
 }
 
-/// Generate the manpage for the utility in the first parameter
-/// # Panics
-/// Panics if the utility map is empty
-fn gen_manpage<T: uucore::Args>(
-    args: impl Iterator<Item = OsString>,
-    util_map: &UtilityMap<T>,
-) -> ! {
+fn get_manpage_args<T>(util_map: &UtilityMap<T>) -> clap::Command {
     let all_utilities: Vec<_> = std::iter::once("coreutils")
         .chain(util_map.keys().copied())
         .collect();
+    Command::new(MANPAGE).about("Prints manpage to stdout").arg(
+        Arg::new("utility")
+            .value_parser(clap::builder::PossibleValuesParser::new(all_utilities))
+            .required(true),
+    )
+}
 
-    let matches = Command::new("manpage")
-        .about("Prints manpage to stdout")
-        .arg(
-            Arg::new("utility")
-                .value_parser(clap::builder::PossibleValuesParser::new(all_utilities))
-                .required(true),
-        )
-        .get_matches_from(std::iter::once(OsString::from("manpage")).chain(args));
+/// Generate the manpage for the utility in the first parameter
+/// # Panics
+/// Panics if the utility map is empty
+fn gen_manpage<T: uucore::Args>(args: impl Iterator<Item = OsString>, util_map: &UtilityMap<T>) {
+    let tldr_zip = File::open("docs/tldr.zip")
+        .ok()
+        .and_then(|f| ZipArchive::new(f).ok());
+
+    if tldr_zip.is_none() {
+        // Could not open tldr.zip
+    }
+    let matches = get_manpage_args(util_map)
+        .get_matches_from(std::iter::once(OsString::from(MANPAGE)).chain(args));
 
     let utility = matches.get_one::<String>("utility").unwrap();
 
     let command = if utility == "coreutils" {
         gen_coreutils_app(util_map)
     } else {
-        util_map.get(utility).unwrap().1()
+        let mut cmd = util_map.get(utility).unwrap().1();
+        if let Ok(examples) = get_zip_examples(utility) {
+            cmd = cmd.after_help(examples);
+        }
+        cmd
     };
 
     let man = clap_mangen::Man::new(command);
     man.render(&mut io::stdout())
         .expect("Man page generation failed");
     io::stdout().flush().unwrap();
-    process::exit(0);
 }
 
 /// # Panics
@@ -239,3 +270,64 @@ fn gen_coreutils_app<T: uucore::Args>(util_map: &UtilityMap<T>) -> Command {
     }
     command
 }
+
+/// # Errors
+/// Returns an error if the tldr.zip file cannot be opened or read
+fn get_zip_examples(name: &str) -> io::Result<String> {
+    fn get_zip_content(archive: &mut ZipArchive<impl Read + Seek>, name: &str) -> Option<String> {
+        let mut s = String::new();
+        archive.by_name(name).ok()?.read_to_string(&mut s).unwrap();
+        Some(s)
+    }
+
+    let mut w = io::BufWriter::new(Vec::new());
+    let file = File::open("docs/tldr.zip")?;
+    let mut tldr_zip = match ZipArchive::new(file) {
+        Ok(zip) => zip,
+        Err(e) => {
+            return Err(io::Error::new(
+                io::ErrorKind::NotFound,
+                format!("Error reading tldr.zip: {}", e),
+            ));
+        }
+    };
+
+    let content = if let Some(f) =
+        get_zip_content(&mut tldr_zip, &format!("pages/common/{}.md", name))
+    {
+        f
+    } else if let Some(f) = get_zip_content(&mut tldr_zip, &format!("pages/linux/{}.md", name)) {
+        f
+    } else {
+        return Err(io::Error::new(
+            io::ErrorKind::NotFound,
+            "Could not find tldr examples",
+        ));
+    };
+
+    writeln!(w, "Examples")?;
+    writeln!(w)?;
+    for line in content.lines().skip_while(|l| !l.starts_with('-')) {
+        if let Some(l) = line.strip_prefix("- ") {
+            writeln!(w, "{l}")?;
+        } else if line.starts_with('`') {
+            writeln!(w, "{}", line.trim_matches('`'))?;
+        } else if line.is_empty() {
+            writeln!(w)?;
+        } else {
+            // println!("Not sure what to do with this line:");
+            // println!("{line}");
+        }
+    }
+    writeln!(w)?;
+    writeln!(
+        w,
+        "> The examples are provided by the [tldr-pages project](https://tldr.sh) under the [CC BY 4.0 License](https://github.com/tldr-pages/tldr/blob/main/LICENSE.md)."
+    )?;
+    writeln!(w, "\n\n\n")?;
+    writeln!(
+        w,
+        "> Please note that, as uutils is a work in progress, some examples might fail."
+    )?;
+    Ok(String::from_utf8(w.into_inner().unwrap()).unwrap())
+}