fix(help)!: Provide styled usage to user

This will open us up to providing the user with access to the styled
version in the future.

CHANGELOG.md

@@ -226,6 +226,7 @@ Easier to catch changes:
 - `ErrorKind::EmptyValue` replaced with `ErrorKind::InvalidValue` to remove an unnecessary special case (#3676, #3968)
 - `ErrorKind::UnrecognizedSubcommand` replaced with `ErrorKind::InvalidSubcommand` to remove an unnecessary special case (#3676)
 - Changed the default type of `allow_external_subcommands` from `String` to `OsString` as that is less likely to cause bugs in user applications (#3990)
+- `Command::render_usage` now returns a `StyledStr`
 - *(derive)* Changed the default for arguments from `parse` to `value_parser`, removing `parse` support (#3827, #3981)
   - `#[clap(value_parser)]` and `#[clap(action)]` are now redundant
 - *(derive)* `subcommand_required(true).arg_required_else_help(true)` is set instead of `SubcommandRequiredElseHelp` to give more meaningful errors when subcommands are missing and to reduce redundancy (#3280)

src/builder/command.rs

@@ -869,8 +869,8 @@ impl Command {
     /// let mut cmd = Command::new("myprog");
     /// println!("{}", cmd.render_usage());
     /// ```
-    pub fn render_usage(&mut self) -> String {
-        self.render_usage_().unwrap_or_default().to_string()
+    pub fn render_usage(&mut self) -> StyledStr {
+        self.render_usage_().unwrap_or_default()
     }
 
     pub(crate) fn render_usage_(&mut self) -> Option<StyledStr> {

tests/builder/positionals.rs

@@ -211,13 +211,13 @@ fn positional_hyphen_does_not_panic() {
 #[test]
 fn single_positional_usage_string() {
     let mut cmd = Command::new("test").arg(arg!([FILE] "some file"));
-    crate::utils::assert_eq(cmd.render_usage(), "Usage: test [FILE]");
+    crate::utils::assert_eq(cmd.render_usage().to_string(), "Usage: test [FILE]");
 }
 
 #[test]
 fn single_positional_multiple_usage_string() {
     let mut cmd = Command::new("test").arg(arg!([FILE]... "some file"));
-    crate::utils::assert_eq(cmd.render_usage(), "Usage: test [FILE]...");
+    crate::utils::assert_eq(cmd.render_usage().to_string(), "Usage: test [FILE]...");
 }
 
 #[test]
@@ -226,7 +226,7 @@ fn multiple_positional_usage_string() {
         .arg(arg!([FILE] "some file"))
         .arg(arg!([FILES]... "some file"));
     crate::utils::assert_eq(
-        cmd.render_usage(),
+        cmd.render_usage().to_string(),
         "\
 Usage: test [FILE] [FILES]...",
     );
@@ -237,13 +237,16 @@ fn multiple_positional_one_required_usage_string() {
     let mut cmd = Command::new("test")
         .arg(arg!(<FILE> "some file"))
         .arg(arg!([FILES]... "some file"));
-    crate::utils::assert_eq(cmd.render_usage(), "Usage: test <FILE> [FILES]...");
+    crate::utils::assert_eq(
+        cmd.render_usage().to_string(),
+        "Usage: test <FILE> [FILES]...",
+    );
 }
 
 #[test]
 fn single_positional_required_usage_string() {
     let mut cmd = Command::new("test").arg(arg!(<FILE> "some file"));
-    crate::utils::assert_eq(cmd.render_usage(), "Usage: test <FILE>");
+    crate::utils::assert_eq(cmd.render_usage().to_string(), "Usage: test <FILE>");
 }
 
 // This tests a programmer error and will only succeed with debug_assertions

tests/builder/subcommands.rs

@@ -343,7 +343,10 @@ fn subcommand_placeholder_test() {
         .subcommand_value_name("TEST_PLACEHOLDER")
         .subcommand_help_heading("TEST_HEADER");
 
-    assert_eq!(&cmd.render_usage(), "Usage: myprog [TEST_PLACEHOLDER]");
+    assert_eq!(
+        &cmd.render_usage().to_string(),
+        "Usage: myprog [TEST_PLACEHOLDER]"
+    );
 
     let mut help_text = Vec::new();
     cmd.write_help(&mut help_text)