feat(help): Open the door for user styling in the future

Cargo.toml

@@ -71,9 +71,9 @@ suggestions = ["dep:strsim"]
 deprecated = ["clap_derive?/deprecated"] # Guided experience to prepare for next breaking release (at different stages of development, this may become default)
 derive = ["clap_derive"]
 cargo = [] # Disable if you're not using Cargo, enables Cargo-env-var-dependent macros
-wrap_help = ["dep:terminal_size", "textwrap/terminal_size"]
+wrap_help = ["dep:terminal_size"]
 env = [] # Use environment variables during arg parsing
-unicode = ["textwrap/unicode-width", "dep:unicase"]  # Support for unicode characters in arguments and help messages
+unicode = ["dep:unicode-width", "dep:unicase"]  # Support for unicode characters in arguments and help messages
 perf = [] # Optimize for runtime performance
 
 # In-work features
@@ -88,13 +88,13 @@ bench = false
 clap_derive = { path = "./clap_derive", version = "=4.0.0-alpha.0", optional = true }
 clap_lex = { path = "./clap_lex", version = "0.2.2" }
 bitflags = "1.2"
-textwrap = { version = "0.15.0", default-features = false, features = [] }
 unicase = { version = "2.6", optional = true }
 strsim = { version = "0.10",  optional = true }
 atty = { version = "0.2",  optional = true }
 termcolor = { version = "1.1.1", optional = true }
 terminal_size = { version = "0.2.1", optional = true }
 backtrace = { version = "0.3", optional = true }
+unicode-width = { version = "0.1.9", optional = true }
 
 [dev-dependencies]
 trybuild = "1.0.18"
@@ -105,6 +105,7 @@ humantime = "2"
 snapbox = "0.2"
 shlex = "1.1.0"
 static_assertions = "1.1.0"
+unic-emoji-char = "0.9.0"
 
 [[example]]
 name = "demo"

clap_complete/src/shells/elvish.rs

@@ -1,5 +1,6 @@
 use std::io::Write;
 
+use clap::builder::StyledStr;
 use clap::*;
 
 use crate::generator::{utils, Generator};
@@ -59,9 +60,9 @@ fn escape_string(string: &str) -> String {
     string.replace('\'', "''")
 }
 
-fn get_tooltip<T: ToString>(help: Option<&str>, data: T) -> String {
+fn get_tooltip<T: ToString>(help: Option<&StyledStr>, data: T) -> String {
     match help {
-        Some(help) => escape_string(help),
+        Some(help) => escape_string(&help.to_string()),
         _ => data.to_string(),
     }
 }

clap_complete/src/shells/fish.rs

@@ -93,7 +93,7 @@ fn gen_fish_inner(
         }
 
         if let Some(data) = option.get_help() {
-            template.push_str(format!(" -d '{}'", escape_string(data)).as_str());
+            template.push_str(format!(" -d '{}'", escape_string(&data.to_string())).as_str());
         }
 
         template.push_str(value_completion(option).as_str());
@@ -118,7 +118,7 @@ fn gen_fish_inner(
         }
 
         if let Some(data) = flag.get_help() {
-            template.push_str(format!(" -d '{}'", escape_string(data)).as_str());
+            template.push_str(format!(" -d '{}'", escape_string(&data.to_string())).as_str());
         }
 
         buffer.push_str(template.as_str());
@@ -132,7 +132,7 @@ fn gen_fish_inner(
         template.push_str(format!(" -a \"{}\"", &subcommand.get_name()).as_str());
 
         if let Some(data) = subcommand.get_about() {
-            template.push_str(format!(" -d '{}'", escape_string(data)).as_str())
+            template.push_str(format!(" -d '{}'", escape_string(&data.to_string())).as_str())
         }
 
         buffer.push_str(template.as_str());
@@ -164,7 +164,7 @@ fn value_completion(option: &Arg) -> String {
                     Some(format!(
                         "{}\t{}",
                         escape_string(value.get_name()).as_str(),
-                        escape_string(value.get_help().unwrap_or_default()).as_str()
+                        escape_string(&value.get_help().unwrap_or_default().to_string())
                     ))
                 })
                 .collect::<Vec<_>>()

clap_complete/src/shells/powershell.rs

@@ -1,5 +1,6 @@
 use std::io::Write;
 
+use clap::builder::StyledStr;
 use clap::*;
 
 use crate::generator::{utils, Generator};
@@ -64,9 +65,9 @@ fn escape_string(string: &str) -> String {
     string.replace('\'', "''")
 }
 
-fn get_tooltip<T: ToString>(help: Option<&str>, data: T) -> String {
+fn get_tooltip<T: ToString>(help: Option<&StyledStr>, data: T) -> String {
     match help {
-        Some(help) => escape_string(help),
+        Some(help) => escape_string(&help.to_string()),
         _ => data.to_string(),
     }
 }

clap_complete/src/shells/zsh.rs

@@ -153,7 +153,7 @@ fn subcommands_of(p: &Command) -> String {
         let text = format!(
             "'{name}:{help}' \\",
             name = name,
-            help = escape_help(subcommand.get_about().unwrap_or_default())
+            help = escape_help(&subcommand.get_about().unwrap_or_default().to_string())
         );
 
         if !text.is_empty() {
@@ -372,7 +372,8 @@ fn value_completion(arg: &Arg) -> Option<String> {
                             Some(format!(
                                 r#"{name}\:"{tooltip}""#,
                                 name = escape_value(value.get_name()),
-                                tooltip = value.get_help().map(escape_help).unwrap_or_default()
+                                tooltip =
+                                    escape_help(&value.get_help().unwrap_or_default().to_string()),
                             ))
                         }
                     })
@@ -445,7 +446,7 @@ fn write_opts_of(p: &Command, p_global: Option<&Command>) -> String {
     for o in p.get_opts() {
         debug!("write_opts_of:iter: o={}", o.get_id());
 
-        let help = o.get_help().map(escape_help).unwrap_or_default();
+        let help = escape_help(&o.get_help().unwrap_or_default().to_string());
         let conflicts = arg_conflicts(p, o, p_global);
 
         let multiple = "*";
@@ -541,7 +542,7 @@ fn write_flags_of(p: &Command, p_global: Option<&Command>) -> String {
     for f in utils::flags(p) {
         debug!("write_flags_of:iter: f={}", f.get_id());
 
-        let help = f.get_help().map(escape_help).unwrap_or_default();
+        let help = escape_help(&f.get_help().unwrap_or_default().to_string());
         let conflicts = arg_conflicts(p, &f, p_global);
 
         let multiple = "*";
@@ -634,7 +635,8 @@ fn write_positionals_of(p: &Command) -> String {
             name = arg.get_id(),
             help = arg
                 .get_help()
-                .map_or("".to_owned(), |v| " -- ".to_owned() + v)
+                .map(|s| s.to_string())
+                .map_or("".to_owned(), |v| " -- ".to_owned() + &v)
                 .replace('[', "\\[")
                 .replace(']', "\\]")
                 .replace('\'', "'\\''")

clap_complete/tests/snapshots/basic.bash

@@ -39,7 +39,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="-c [<SUBCOMMAND>...]"
+            opts="-c [SUBCOMMAND]..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

clap_complete/tests/snapshots/feature_sample.bash

@@ -39,7 +39,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="[<SUBCOMMAND>...]"
+            opts="[SUBCOMMAND]..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

clap_complete/tests/snapshots/quoting.bash

@@ -138,7 +138,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="[<SUBCOMMAND>...]"
+            opts="[SUBCOMMAND]..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

clap_complete/tests/snapshots/special_commands.bash

@@ -48,7 +48,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="[<SUBCOMMAND>...]"
+            opts="[SUBCOMMAND]..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

clap_complete/tests/snapshots/sub_subcommands.bash

@@ -45,7 +45,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="[<SUBCOMMAND>...]"
+            opts="[SUBCOMMAND]..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -73,7 +73,7 @@ _my-app() {
             return 0
             ;;
         my__app__some_cmd__help)
-            opts="[<SUBCOMMAND>...]"
+            opts="[SUBCOMMAND]..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

clap_complete_fig/src/fig.rs

@@ -28,7 +28,7 @@ impl Generator for Fig {
         write!(
             &mut buffer,
             "  description: \"{}\",\n",
-            escape_string(cmd.get_about().unwrap_or_default())
+            escape_string(&cmd.get_about().unwrap_or_default().to_string())
         )
         .unwrap();
 
@@ -101,7 +101,7 @@ fn gen_fig_inner(
                     buffer,
                     "{:indent$}description: \"{}\",\n",
                     "",
-                    escape_string(data),
+                    escape_string(&data.to_string()),
                     indent = indent + 4
                 )
                 .unwrap();
@@ -205,7 +205,7 @@ fn gen_options(cmd: &Command, indent: usize) -> String {
                     &mut buffer,
                     "{:indent$}description: \"{}\",\n",
                     "",
-                    escape_string(data),
+                    escape_string(&data.to_string()),
                     indent = indent + 4
                 )
                 .unwrap();
@@ -314,7 +314,7 @@ fn gen_options(cmd: &Command, indent: usize) -> String {
                     &mut buffer,
                     "{:indent$}description: \"{}\",\n",
                     "",
-                    escape_string(data).as_str(),
+                    escape_string(&data.to_string()).as_str(),
                     indent = indent + 4
                 )
                 .unwrap();
@@ -426,7 +426,7 @@ fn gen_args(arg: &Arg, indent: usize) -> String {
                     &mut buffer,
                     "{:indent$}description: \"{}\",\n",
                     "",
-                    escape_string(help),
+                    escape_string(&help.to_string()),
                     indent = indent + 6
                 )
                 .unwrap();

clap_mangen/src/render.rs

@@ -17,7 +17,7 @@ pub(crate) fn about(roff: &mut Roff, cmd: &clap::Command) {
 
 pub(crate) fn description(roff: &mut Roff, cmd: &clap::Command) {
     if let Some(about) = cmd.get_long_about().or_else(|| cmd.get_about()) {
-        for line in about.lines() {
+        for line in about.to_string().lines() {
             if line.trim().is_empty() {
                 roff.control("PP", []);
             } else {
@@ -110,7 +110,7 @@ pub(crate) fn options(roff: &mut Roff, cmd: &clap::Command) {
         let mut arg_help_written = false;
         if let Some(help) = opt.get_long_help().or_else(|| opt.get_help()) {
             arg_help_written = true;
-            body.push(roman(help));
+            body.push(roman(help.to_string()));
         }
 
         roff.control("TP", []);
@@ -224,7 +224,7 @@ pub(crate) fn subcommands(roff: &mut Roff, cmd: &clap::Command, section: &str) {
         roff.text([roman(&name)]);
 
         if let Some(about) = sub.get_about().or_else(|| sub.get_long_about()) {
-            for line in about.lines() {
+            for line in about.to_string().lines() {
                 roff.text([roman(line)]);
             }
         }
@@ -242,7 +242,7 @@ pub(crate) fn version(cmd: &clap::Command) -> String {
 
 pub(crate) fn after_help(roff: &mut Roff, cmd: &clap::Command) {
     if let Some(about) = cmd.get_after_long_help().or_else(|| cmd.get_after_help()) {
-        for line in about.lines() {
+        for line in about.to_string().lines() {
             roff.text([roman(line)]);
         }
     }