uudoc,uucore_procs: move md parsing to HelpParser

Cargo.toml

@@ -359,6 +359,8 @@ selinux = { workspace=true, optional = true }
 textwrap = { workspace=true }
 zip = { workspace=true, optional = true }
 
+help_parser = { path="src/help_parser" }
+
 # * uutils
 uu_test  = { optional=true, version="0.0.17", package="uu_test", path="src/uu/test" }
 #
@@ -512,3 +514,6 @@ path = "src/bin/coreutils.rs"
 name = "uudoc"
 path = "src/bin/uudoc.rs"
 required-features = ["uudoc"]
+
+[package.metadata.cargo-udeps.ignore]
+normal = ["help_parser"]

src/bin/uudoc.rs

@@ -11,6 +11,8 @@ use std::fs::File;
 use std::io::{self, Read, Seek, Write};
 use zip::ZipArchive;
 
+use help_parser::HelpParser;
+
 include!(concat!(env!("OUT_DIR"), "/uutils_map.rs"));
 
 fn main() -> io::Result<()> {
@@ -133,7 +135,7 @@ impl<'a, 'b> MDWriter<'a, 'b> {
         write!(self.w, "# {}\n\n", self.name)?;
         self.additional()?;
         self.usage()?;
-        self.description()?;
+        self.about()?;
         self.options()?;
         self.after_help()?;
         self.examples()
@@ -177,54 +179,34 @@ impl<'a, 'b> MDWriter<'a, 'b> {
     }
 
     fn usage(&mut self) -> io::Result<()> {
-        writeln!(self.w, "\n```")?;
-        let mut usage: String = self
-            .command
-            .render_usage()
-            .to_string()
-            .lines()
-            .map(|l| l.strip_prefix("Usage:").unwrap_or(l))
-            .map(|l| l.trim())
-            .filter(|l| !l.is_empty())
-            .collect::<Vec<_>>()
-            .join("\n");
-        usage = usage
-            .to_string()
-            .replace(uucore::execution_phrase(), self.name);
-        writeln!(self.w, "{}", usage)?;
-        writeln!(self.w, "```")
-    }
+        if let Some(markdown) = &self.markdown {
+            let usage = HelpParser::parse_usage(&markdown);
+            let usage = usage.replace("{}", self.name);
 
-    fn description(&mut self) -> io::Result<()> {
-        if let Some(after_help) = self.markdown_section("about") {
-            return writeln!(self.w, "\n\n{}", after_help);
+            writeln!(self.w, "\n```")?;
+            writeln!(self.w, "{}", usage)?;
+            writeln!(self.w, "```")
+        } else {
+            Ok(())
         }
+    }
 
-        if let Some(about) = self
-            .command
-            .get_long_about()
-            .or_else(|| self.command.get_about())
-        {
-            writeln!(self.w, "{}", about)
+    fn about(&mut self) -> io::Result<()> {
+        if let Some(markdown) = &self.markdown {
+            writeln!(self.w, "{}", HelpParser::parse_about(&markdown))
         } else {
             Ok(())
         }
     }
 
     fn after_help(&mut self) -> io::Result<()> {
-        if let Some(after_help) = self.markdown_section("after help") {
-            return writeln!(self.w, "\n\n{}", after_help);
+        if let Some(markdown) = &self.markdown {
+            if let Some(after_help) = HelpParser::parse_section("after help", &markdown) {
+                return writeln!(self.w, "\n\n{after_help}");
+            }
         }
 
-        if let Some(after_help) = self
-            .command
-            .get_after_long_help()
-            .or_else(|| self.command.get_after_help())
-        {
-            writeln!(self.w, "\n\n{}", after_help)
-        } else {
-            Ok(())
-        }
+        Ok(())
     }
 
     fn examples(&mut self) -> io::Result<()> {
@@ -327,32 +309,6 @@ impl<'a, 'b> MDWriter<'a, 'b> {
         }
         writeln!(self.w, "</dl>\n")
     }
-
-    fn markdown_section(&self, section: &str) -> Option<String> {
-        let md = self.markdown.as_ref()?;
-        let section = section.to_lowercase();
-
-        fn is_section_header(line: &str, section: &str) -> bool {
-            line.strip_prefix("##")
-                .map_or(false, |l| l.trim().to_lowercase() == section)
-        }
-
-        let result = md
-            .lines()
-            .skip_while(|&l| !is_section_header(l, &section))
-            .skip(1)
-            .take_while(|l| !l.starts_with("##"))
-            .collect::<Vec<_>>()
-            .join("\n")
-            .trim()
-            .to_string();
-
-        if !result.is_empty() {
-            Some(result)
-        } else {
-            None
-        }
-    }
 }
 
 fn get_zip_content(archive: &mut ZipArchive<impl Read + Seek>, name: &str) -> Option<String> {

src/help_parser/Cargo.toml

@@ -0,0 +1,5 @@
+[package]
+name = "help_parser"
+version = "0.0.17"
+edition = "2021"
+license = "MIT"

src/help_parser/src/lib.rs

@@ -0,0 +1,212 @@
+// This file is part of the uutils coreutils package.
+//
+// For the full copyright and license information, please view the LICENSE
+// file that was distributed with this source code.
+
+pub struct HelpParser;
+
+/// `HelpParser` provides functions to parse the markdown code of help files.
+///
+/// The structure of the markdown code is assumed to be:
+///
+/// # util name
+///
+/// ```text
+/// usage info
+/// ```
+///
+/// About text
+///
+/// ## Section 1
+///
+/// Some content
+///
+/// ## Section 2
+///
+/// Some content
+///
+impl HelpParser {
+    const MARKDOWN_CODE_FENCES: &str = "```";
+
+    /// Parses the text between the first markdown code block and the next header, if any,
+    /// into an about string.
+    pub fn parse_about(content: &str) -> String {
+        content
+            .lines()
+            .skip_while(|l| !l.starts_with(Self::MARKDOWN_CODE_FENCES))
+            .skip(1)
+            .skip_while(|l| !l.starts_with(Self::MARKDOWN_CODE_FENCES))
+            .skip(1)
+            .take_while(|l| !l.starts_with('#'))
+            .collect::<Vec<_>>()
+            .join("\n")
+            .trim()
+            .to_string()
+    }
+
+    /// Parses the first markdown code block into a usage string
+    ///
+    /// The code fences are removed and the name of the util is replaced
+    /// with `{}` so that it can be replaced with the appropriate name
+    /// at runtime.
+    pub fn parse_usage(content: &str) -> String {
+        content
+            .lines()
+            .skip_while(|l| !l.starts_with(Self::MARKDOWN_CODE_FENCES))
+            .skip(1)
+            .take_while(|l| !l.starts_with(Self::MARKDOWN_CODE_FENCES))
+            .map(|l| {
+                // Replace the util name (assumed to be the first word) with "{}"
+                // to be replaced with the runtime value later.
+                if let Some((_util, args)) = l.split_once(' ') {
+                    format!("{{}} {args}\n")
+                } else {
+                    "{}\n".to_string()
+                }
+            })
+            .collect::<Vec<_>>()
+            .join("")
+            .trim()
+            .to_string()
+    }
+
+    /// Get a single section from content
+    ///
+    /// The section must be a second level section (i.e. start with `##`).
+    pub fn parse_section(section: &str, content: &str) -> Option<String> {
+        fn is_section_header(line: &str, section: &str) -> bool {
+            line.strip_prefix("##")
+                .map_or(false, |l| l.trim().to_lowercase() == section)
+        }
+
+        let section = &section.to_lowercase();
+
+        // We cannot distinguish between an empty or non-existing section below,
+        // so we do a quick test to check whether the section exists
+        if content.lines().all(|l| !is_section_header(l, section)) {
+            return None;
+        }
+
+        Some(
+            content
+                .lines()
+                .skip_while(|&l| !is_section_header(l, section))
+                .skip(1)
+                .take_while(|l| !l.starts_with("##"))
+                .collect::<Vec<_>>()
+                .join("\n")
+                .trim()
+                .to_string(),
+        )
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_parse_section() {
+        let input = "\
+            # ls\n\
+            ## some section\n\
+            This is some section\n\
+            \n\
+            ## ANOTHER SECTION
+            This is the other section\n\
+            with multiple lines\n";
+
+        assert_eq!(
+            HelpParser::parse_section("some section", input).unwrap(),
+            "This is some section"
+        );
+        assert_eq!(
+            HelpParser::parse_section("SOME SECTION", input).unwrap(),
+            "This is some section"
+        );
+        assert_eq!(
+            HelpParser::parse_section("another section", input).unwrap(),
+            "This is the other section\nwith multiple lines"
+        );
+    }
+
+    #[test]
+    fn test_parse_non_existing_section() {
+        let input = "\
+            # ls\n\
+            ## some section\n\
+            This is some section\n\
+            \n\
+            ## ANOTHER SECTION
+            This is the other section\n\
+            with multiple lines\n";
+
+        assert!(HelpParser::parse_section("non-existing section", input).is_none());
+    }
+
+    #[test]
+    fn test_parse_usage() {
+        let input = "\
+            # ls\n\
+            ```\n\
+            ls -l\n\
+            ```\n\
+            ## some section\n\
+            This is some section\n\
+            \n\
+            ## ANOTHER SECTION
+            This is the other section\n\
+            with multiple lines\n";
+
+        assert_eq!(HelpParser::parse_usage(input), "{} -l");
+    }
+
+    #[test]
+    fn test_parse_multi_line_usage() {
+        let input = "\
+            # ls\n\
+            ```\n\
+            ls -a\n\
+            ls -b\n\
+            ls -c\n\
+            ```\n\
+            ## some section\n\
+            This is some section\n";
+
+        assert_eq!(HelpParser::parse_usage(input), "{} -a\n{} -b\n{} -c");
+    }
+
+    #[test]
+    fn test_parse_about() {
+        let input = "\
+            # ls\n\
+            ```\n\
+            ls -l\n\
+            ```\n\
+            \n\
+            This is the about section\n\
+            \n\
+            ## some section\n\
+            This is some section\n";
+
+        assert_eq!(HelpParser::parse_about(input), "This is the about section");
+    }
+
+    #[test]
+    fn test_parse_multi_line_about() {
+        let input = "\
+            # ls\n\
+            ```\n\
+            ls -l\n\
+            ```\n\
+            \n\
+            about a\n\
+            \n\
+            about b\n\
+            \n\
+            ## some section\n\
+            This is some section\n";
+
+        assert_eq!(HelpParser::parse_about(input), "about a\n\nabout b");
+    }
+}

src/uucore_procs/Cargo.toml

@@ -18,3 +18,4 @@ proc-macro = true
 [dependencies]
 proc-macro2 = "1.0"
 quote = "1.0"
+help_parser = { path="../help_parser", version="0.0.17" }