fix(help): Replace help writers with renderers

The writer is less convenient and isn't offering any performance
benefits of avoidign the extra allocations, so let's render instead.

This supersedes clap-rs#3874

Fixes clap-rs#3873

CHANGELOG.md

@@ -257,6 +257,7 @@ Deprecated
 - `Command::trailing_var_arg` in favor of `Arg::trailing_var_arg` to make it clearer which arg it is meant to apply to (#4187)
 - `Command::allow_hyphen_values` in favor of `Arg::allow_hyphen_values` to make it clearer which arg it is meant to apply to (#4187)
 - `Command::allow_negative_numbers` in favor of `Arg::allow_negative_numbers` to make it clearer which arg it is meant to apply to (#4187)
+- *(help)* Deprecated `Command::write_help` and `Command::write_long_help` in favor of `Command::render_help` and `Command::render_long_help`
 - *(derive)* `structopt` and `clap` attributes in favor of the more specific `command`, `arg`, and `value` to open the door for [more features](https://github.com/clap-rs/clap/issues/1807) and [clarify relationship to the builder](https://github.com/clap-rs/clap/discussions/4090) (#1807, #4180)
 - *(derive)* `#[clap(value_parser)]` and `#[clap(action)]` defaulted attributes (its the default) (#3976)
 
@@ -273,6 +274,7 @@ Behavior Changes
 - *(error)* `Error::apply` for changing the formatter for dropping binary size (#4111)
 - *(help)* Show `PossibleValue::help` in long help (`--help`) (#3312)
 - *(help)* New `{tab}` variable for `Command::help_template` (#4161)
+- *(help)* `Command::render_help` and `Command::render_long_help`
 
 ### Fixes
 

clap_bench/benches/04_new_help.rs

@@ -1,13 +1,10 @@
 use clap::Command;
 use clap::{arg, Arg, ArgAction};
 use criterion::{criterion_group, criterion_main, Criterion};
-use std::io::Cursor;
 
 fn build_help(cmd: &mut Command) -> String {
-    let mut buf = Cursor::new(Vec::with_capacity(50));
-    cmd.write_help(&mut buf).unwrap();
-    let content = buf.into_inner();
-    String::from_utf8(content).unwrap()
+    let help = cmd.render_help();
+    help.to_string()
 }
 
 fn app_example1() -> Command {

clap_bench/benches/05_ripgrep.rs

@@ -6,7 +6,6 @@
 use clap::{value_parser, Arg, ArgAction, Command};
 use criterion::{criterion_group, criterion_main, Criterion};
 use std::collections::HashMap;
-use std::io::Cursor;
 
 use lazy_static::lazy_static;
 
@@ -281,10 +280,8 @@ fn app_long() -> Command {
 
 /// Build the help text of an application.
 fn build_help(cmd: &mut Command) -> String {
-    let mut buf = Cursor::new(Vec::with_capacity(50));
-    cmd.write_help(&mut buf).unwrap();
-    let content = buf.into_inner();
-    String::from_utf8(content).unwrap()
+    let help = cmd.render_help();
+    help.to_string()
 }
 
 /// Build a clap application parameterized by usage strings.

src/builder/command.rs

@@ -759,9 +759,9 @@ impl Command {
         c.print()
     }
 
-    /// Writes the short help message (`-h`) to a [`io::Write`] object.
+    /// Render the short help message (`-h`) to a [`StyledStr`]
     ///
-    /// See also [`Command::write_long_help`].
+    /// See also [`Command::render_long_help`].
     ///
     /// # Examples
     ///
@@ -770,24 +770,24 @@ impl Command {
     /// use std::io;
     /// let mut cmd = Command::new("myprog");
     /// let mut out = io::stdout();
-    /// cmd.write_help(&mut out).expect("failed to write to stdout");
+    /// let help = cmd.render_help();
+    /// println!("{}", help);
     /// ```
     /// [`io::Write`]: std::io::Write
     /// [`-h` (short)]: Arg::help()
     /// [`--help` (long)]: Arg::long_help()
-    pub fn write_help<W: io::Write>(&mut self, w: &mut W) -> io::Result<()> {
+    pub fn render_help(&mut self) -> StyledStr {
         self._build_self(false);
 
         let mut styled = StyledStr::new();
         let usage = Usage::new(self);
         write_help(&mut styled, self, &usage, false);
-        write!(w, "{}", styled)?;
-        w.flush()
+        styled
     }
 
-    /// Writes the long help message (`--help`) to a [`io::Write`] object.
+    /// Render the long help message (`--help`) to a [`StyledStr`].
     ///
-    /// See also [`Command::write_help`].
+    /// See also [`Command::render_help`].
     ///
     /// # Examples
     ///
@@ -796,11 +796,41 @@ impl Command {
     /// use std::io;
     /// let mut cmd = Command::new("myprog");
     /// let mut out = io::stdout();
-    /// cmd.write_long_help(&mut out).expect("failed to write to stdout");
+    /// let help = cmd.render_long_help();
+    /// println!("{}", help);
     /// ```
     /// [`io::Write`]: std::io::Write
     /// [`-h` (short)]: Arg::help()
     /// [`--help` (long)]: Arg::long_help()
+    pub fn render_long_help(&mut self) -> StyledStr {
+        self._build_self(false);
+
+        let mut styled = StyledStr::new();
+        let usage = Usage::new(self);
+        write_help(&mut styled, self, &usage, true);
+        styled
+    }
+
+    #[doc(hidden)]
+    #[cfg_attr(
+        feature = "deprecated",
+        deprecated(since = "4.0.0", note = "Replaced with `Command::render_help`")
+    )]
+    pub fn write_help<W: io::Write>(&mut self, w: &mut W) -> io::Result<()> {
+        self._build_self(false);
+
+        let mut styled = StyledStr::new();
+        let usage = Usage::new(self);
+        write_help(&mut styled, self, &usage, false);
+        write!(w, "{}", styled)?;
+        w.flush()
+    }
+
+    #[doc(hidden)]
+    #[cfg_attr(
+        feature = "deprecated",
+        deprecated(since = "4.0.0", note = "Replaced with `Command::render_long_help`")
+    )]
     pub fn write_long_help<W: io::Write>(&mut self, w: &mut W) -> io::Result<()> {
         self._build_self(false);
 

tests/builder/help.rs

@@ -1954,11 +1954,7 @@ fn after_help_no_args() {
         .disable_version_flag(true)
         .after_help("This is after help.");
 
-    let help = {
-        let mut output = Vec::new();
-        cmd.write_help(&mut output).unwrap();
-        String::from_utf8(output).unwrap()
-    };
+    let help = cmd.render_help().to_string();
 
     assert_eq!(help, AFTER_HELP_NO_ARGS);
 }
@@ -2680,9 +2676,8 @@ Options:
     cmd.build();
     let subcmd = cmd.find_subcommand_mut("test").unwrap();
 
-    let mut buf = Vec::new();
-    subcmd.write_help(&mut buf).unwrap();
-    utils::assert_eq(EXPECTED, String::from_utf8(buf).unwrap());
+    let help = subcmd.render_help().to_string();
+    utils::assert_eq(EXPECTED, help);
 }
 
 #[test]

tests/builder/multiple_values.rs

@@ -426,8 +426,7 @@ fn optional_value() {
     assert!(m.contains_id("port"));
     assert_eq!(m.get_one::<String>("port").unwrap(), "42");
 
-    let mut help = Vec::new();
-    cmd.write_help(&mut help).unwrap();
+    let help = cmd.render_help().to_string();
     const HELP: &str = "\
 Usage: test [OPTIONS]
 

tests/builder/subcommands.rs

@@ -348,13 +348,9 @@ fn subcommand_placeholder_test() {
         "Usage: myprog [TEST_PLACEHOLDER]"
     );
 
-    let mut help_text = Vec::new();
-    cmd.write_help(&mut help_text)
-        .expect("Failed to write to internal buffer");
+    let help_text = cmd.render_help().to_string();
 
-    assert!(String::from_utf8(help_text)
-        .unwrap()
-        .contains("TEST_HEADER:"));
+    assert!(help_text.contains("TEST_HEADER:"));
 }
 
 #[test]
@@ -630,9 +626,8 @@ Options:
     let subcmd = cmd.find_subcommand_mut("foo").unwrap();
     let subcmd = subcmd.find_subcommand_mut("bar").unwrap();
 
-    let mut buf = Vec::new();
-    subcmd.write_help(&mut buf).unwrap();
-    utils::assert_eq(EXPECTED, String::from_utf8(buf).unwrap());
+    let help = subcmd.render_help().to_string();
+    utils::assert_eq(EXPECTED, help);
 }
 
 #[test]

tests/derive/app_name.rs

@@ -1,14 +1,16 @@
 use clap::CommandFactory;
 use clap::Parser;
+
+use crate::utils::get_help;
+use crate::utils::get_long_help;
+
 #[test]
 fn app_name_in_short_help_from_struct() {
     #[derive(Parser)]
     #[command(name = "my-cmd")]
     struct MyApp {}
 
-    let mut help = Vec::new();
-    MyApp::command().write_help(&mut help).unwrap();
-    let help = String::from_utf8(help).unwrap();
+    let help = get_help::<MyApp>();
 
     assert!(help.contains("my-cmd"));
 }
@@ -19,9 +21,7 @@ fn app_name_in_long_help_from_struct() {
     #[command(name = "my-cmd")]
     struct MyApp {}
 
-    let mut help = Vec::new();
-    MyApp::command().write_long_help(&mut help).unwrap();
-    let help = String::from_utf8(help).unwrap();
+    let help = get_help::<MyApp>();
 
     assert!(help.contains("my-cmd"));
 }
@@ -32,9 +32,7 @@ fn app_name_in_short_help_from_enum() {
     #[command(name = "my-cmd")]
     enum MyApp {}
 
-    let mut help = Vec::new();
-    MyApp::command().write_help(&mut help).unwrap();
-    let help = String::from_utf8(help).unwrap();
+    let help = get_help::<MyApp>();
 
     assert!(help.contains("my-cmd"));
 }
@@ -45,9 +43,7 @@ fn app_name_in_long_help_from_enum() {
     #[command(name = "my-cmd")]
     enum MyApp {}
 
-    let mut help = Vec::new();
-    MyApp::command().write_long_help(&mut help).unwrap();
-    let help = String::from_utf8(help).unwrap();
+    let help = get_long_help::<MyApp>();
 
     assert!(help.contains("my-cmd"));
 }

tests/derive/arguments.rs

@@ -12,9 +12,10 @@
 // commit#ea76fa1b1b273e65e3b0b1046643715b49bec51f which is licensed under the
 // MIT/Apache 2.0 license.
 
-use clap::CommandFactory;
 use clap::Parser;
 
+use crate::utils::get_help;
+
 #[test]
 fn required_argument() {
     #[derive(Parser, PartialEq, Debug)]
@@ -51,9 +52,7 @@ fn auto_value_name() {
         my_special_arg: i32,
     }
 
-    let mut help = Vec::new();
-    Opt::command().write_help(&mut help).unwrap();
-    let help = String::from_utf8(help).unwrap();
+    let help = get_help::<Opt>();
 
     assert!(help.contains("MY_SPECIAL_ARG"));
     // Ensure the implicit `num_vals` is just 1
@@ -71,9 +70,7 @@ fn explicit_value_name() {
         my_special_arg: i32,
     }
 
-    let mut help = Vec::new();
-    Opt::command().write_help(&mut help).unwrap();
-    let help = String::from_utf8(help).unwrap();
+    let help = get_help::<Opt>();
 
     assert!(help.contains("BROWNIE_POINTS"));
     assert!(!help.contains("MY_SPECIAL_ARG"));

tests/derive/help.rs

@@ -276,9 +276,7 @@ Options:
     use clap::CommandFactory;
     let mut cmd = Args::command();
 
-    let mut buffer: Vec<u8> = Default::default();
-    cmd.write_help(&mut buffer).unwrap();
-    let help = String::from_utf8(buffer).unwrap();
+    let help = cmd.render_help().to_string();
     snapbox::assert_eq(HELP, help);
 }
 
@@ -330,9 +328,7 @@ Options:
     use clap::CommandFactory;
     let mut cmd = Args::command();
 
-    let mut buffer: Vec<u8> = Default::default();
-    cmd.write_help(&mut buffer).unwrap();
-    let help = String::from_utf8(buffer).unwrap();
+    let help = cmd.render_help().to_string();
     snapbox::assert_eq(HELP, help);
 }
 
@@ -383,9 +379,7 @@ Options:
     use clap::CommandFactory;
     let mut cmd = Args::command();
 
-    let mut buffer: Vec<u8> = Default::default();
-    cmd.write_help(&mut buffer).unwrap();
-    let help = String::from_utf8(buffer).unwrap();
+    let help = cmd.render_help().to_string();
     snapbox::assert_eq(HELP, help);
 }
 
@@ -428,9 +422,7 @@ Options:
     use clap::CommandFactory;
     let mut cmd = Args::command();
 
-    let mut buffer: Vec<u8> = Default::default();
-    cmd.write_long_help(&mut buffer).unwrap();
-    let help = String::from_utf8(buffer).unwrap();
+    let help = cmd.render_long_help().to_string();
     snapbox::assert_eq(HELP, help);
 }
 

tests/derive/utils.rs

@@ -15,11 +15,7 @@ pub const FULL_TEMPLATE: &str = "\
 {all-args}{after-help}";
 
 pub fn get_help<T: CommandFactory>() -> String {
-    let mut output = Vec::new();
-    <T as CommandFactory>::command()
-        .write_help(&mut output)
-        .unwrap();
-    let output = String::from_utf8(output).unwrap();
+    let output = <T as CommandFactory>::command().render_help().to_string();
 
     eprintln!("\n%%% HELP %%%:=====\n{}\n=====\n", output);
     eprintln!("\n%%% HELP (DEBUG) %%%:=====\n{:?}\n=====\n", output);
@@ -28,11 +24,9 @@ pub fn get_help<T: CommandFactory>() -> String {
 }
 
 pub fn get_long_help<T: CommandFactory>() -> String {
-    let mut output = Vec::new();
-    <T as CommandFactory>::command()
-        .write_long_help(&mut output)
-        .unwrap();
-    let output = String::from_utf8(output).unwrap();
+    let output = <T as CommandFactory>::command()
+        .render_long_help()
+        .to_string();
 
     eprintln!("\n%%% LONG_HELP %%%:=====\n{}\n=====\n", output);
     eprintln!("\n%%% LONG_HELP (DEBUG) %%%:=====\n{:?}\n=====\n", output);
@@ -41,14 +35,12 @@ pub fn get_long_help<T: CommandFactory>() -> String {
 }
 
 pub fn get_subcommand_long_help<T: CommandFactory>(subcmd: &str) -> String {
-    let mut output = Vec::new();
-    <T as CommandFactory>::command()
+    let output = <T as CommandFactory>::command()
         .get_subcommands_mut()
         .find(|s| s.get_name() == subcmd)
         .unwrap()
-        .write_long_help(&mut output)
-        .unwrap();
-    let output = String::from_utf8(output).unwrap();
+        .render_long_help()
+        .to_string();
 
     eprintln!(
         "\n%%% SUBCOMMAND `{}` HELP %%%:=====\n{}\n=====\n",