Specify default text for optional arguments in help

[epage]

Issue by emilazy
Friday Feb 14, 2020 at 17:05 GMT
Originally opened as clap-rs/clap#1695

---

Describe your use case

Often, the default values of arguments are determined based on runtime computation, e.g. a --threads parameter defaulting to the number of available threads on the system, or a --config option defaulting to an OS-specific path in the user's home directory (e.g. $XDG_CONFIG_HOME/app-name/config.ron on Linux). It's beneficial for usability to be able to summarize the default arguments, e.g. Number of threads to use [default: # of threads on system] or Path to configuration [default: $XDG_CONFIG_HOME/app-name/config.ron].

At present, there's no API to give a (purely cosmetic) default option text for an optional argument.

Currently, I just do:

#[derive(Clap)]
struct Opts {
    /// Option description [default: $XDG_DATA_HOME/...]
    pub path: Option<PathBuf>,
}

but this isn't quite correct (e.g. it doesn't format the default with Colorizer::good).

Arguably this is an X-Y problem and the real feature request is for "computed defaults" (related to #1694), but I think even with such a mechanism there's value in being able to summarize the default path (rather than e.g. inlining volatile variables like $XDG_RUNTIME_DIR in the help text).

Describe the solution you'd like

#[derive(Clap)]
struct Opts {
    /// Option description
    #[clap(default_help = "$XDG_DATA_HOME/...")]
    pub path: Option<PathBuf>,
}

[epage]

Comment by pksunkara
Tuesday Apr 14, 2020 at 22:01 GMT

---

I actually removed the colorizing for default values in #1824. I wanted to rethink quite a bit on how to display all kinds of things like these. But, it's for v3.1