Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-12-14 14:52:33 +00:00
Code Issues Projects Releases Packages Wiki Activity

api(App): Adds help_about method to App.

Browse source 
Help about text is now customizable and propagates to subcommands. Closes #2080.
This commit is contained in:
pretzelhammer 2020-09-24 17:49:12 -04:00
parent 49f857166f
commit 33caf49793
2 changed files with 184 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

35
src/build/app/mod.rs
View file

@ -83,6 +83,7 @@ pub struct App<'help> {
pub(crate) long_version: Option<&'help str>,
pub(crate) about: Option<&'help str>,
pub(crate) long_about: Option<&'help str>,
pub(crate) help_about: Option<&'help str>,
pub(crate) before_help: Option<&'help str>,
pub(crate) before_long_help: Option<&'help str>,
pub(crate) after_help: Option<&'help str>,
@ -420,6 +421,29 @@ impl<'help> App<'help> {
self
}
/// Sets the help text for the auto-generated help argument and subcommand.
///
/// By default clap sets this to "Prints help information" for the help
/// argument and "Prints this message or the help of the given subcommand(s)"
/// for the help subcommand but if you're using a different convention
/// for your help messages and would prefer a different phrasing you can
/// override it.
///
/// **NOTE:** This setting propagates to subcommands.
///
/// # Examples
///
/// ```no_run
/// # use clap::App;
/// App::new("myprog")
/// .help_about("Print help information") // Impertive tone
/// # ;
/// ```
pub fn help_about<S: Into<&'help str>>(mut self, help_about: S) -> Self {
self.help_about = Some(help_about.into());
self
}
/// (Re)Sets the program's name. This will be displayed when displaying help
/// or version messages.
///
@ -2247,6 +2271,9 @@ impl<'help> App<'help> {
$sc.g_settings = $sc.g_settings | $_self.g_settings;
$sc.term_w = $_self.term_w;
$sc.max_w = $_self.max_w;
if $sc.help_about.is_none() && $_self.help_about.is_some() {
$sc.help_about = $_self.help_about.clone();
}
}
{
// FIXME: This doesn't belong here at all.
@ -2299,7 +2326,7 @@ impl<'help> App<'help> {
debug!("App::_create_help_and_version: Building --help");
let mut help = Arg::new("help")
.long("help")
.about("Prints help information");
.about(self.help_about.unwrap_or("Prints help information"));
if !self.args.args.iter().any(|x| x.short == Some('h')) {
help = help.short('h');
}
@ -2333,8 +2360,10 @@ impl<'help> App<'help> {
{
debug!("App::_create_help_and_version: Building help");
self.subcommands.push(
App::new("help")
.about("Prints this message or the help of the given subcommand(s)"),
App::new("help").about(
self.help_about
.unwrap_or("Prints this message or the help of the given subcommand(s)"),
),
);
}
}

152
tests/help.rs
View file

@ -1825,3 +1825,155 @@ fn after_help_no_args() {
assert_eq!(help, AFTER_HELP_NO_ARGS);
}
static HELP_ABOUT: &str = "myapp 1.0
USAGE:
myapp
FLAGS:
-h, --help Print custom help about text
-V, --version Prints version information";
static HELP_ABOUT_MULTI_SC: &str = "myapp-subcmd-multi 1.0
USAGE:
myapp subcmd multi
FLAGS:
-h, --help Print custom help about text
-V, --version Prints version information";
static HELP_ABOUT_MULTI_SC_OVERRIDE: &str = "myapp-subcmd-multi 1.0
USAGE:
myapp subcmd multi
FLAGS:
-h, --help Print custom help about text from multi
-V, --version Prints version information";
#[test]
fn help_about_short_flag() {
let app = App::new("myapp")
.version("1.0")
.help_about("Print custom help about text");
assert!(utils::compare_output(app, "myapp -h", HELP_ABOUT, false));
}
#[test]
fn help_about_long_flag() {
let app = App::new("myapp")
.version("1.0")
.help_about("Print custom help about text");
assert!(utils::compare_output(
app,
"myapp --help",
HELP_ABOUT,
false
));
}
#[test]
fn help_about_multi_subcmd() {
let app = App::new("myapp")
.help_about("Print custom help about text")
.subcommand(App::new("subcmd").subcommand(App::new("multi").version("1.0")));
assert!(utils::compare_output(
app,
"myapp help subcmd multi",
HELP_ABOUT_MULTI_SC,
false
));
}
#[test]
fn help_about_multi_subcmd_short_flag() {
let app = App::new("myapp")
.help_about("Print custom help about text")
.subcommand(App::new("subcmd").subcommand(App::new("multi").version("1.0")));
assert!(utils::compare_output(
app,
"myapp subcmd multi -h",
HELP_ABOUT_MULTI_SC,
false
));
}
#[test]
fn help_about_multi_subcmd_long_flag() {
let app = App::new("myapp")
.help_about("Print custom help about text")
.subcommand(App::new("subcmd").subcommand(App::new("multi").version("1.0")));
assert!(utils::compare_output(
app,
"myapp subcmd multi --help",
HELP_ABOUT_MULTI_SC,
false
));
}
#[test]
fn help_about_multi_subcmd_override() {
let app = App::new("myapp")
.help_about("Print custom help about text")
.subcommand(
App::new("subcmd").subcommand(
App::new("multi")
.version("1.0")
.help_about("Print custom help about text from multi"),
),
);
assert!(utils::compare_output(
app,
"myapp help subcmd multi",
HELP_ABOUT_MULTI_SC_OVERRIDE,
false
));
}
#[test]
fn help_about_multi_subcmd_override_short_flag() {
let app = App::new("myapp")
.help_about("Print custom help about text")
.subcommand(
App::new("subcmd").subcommand(
App::new("multi")
.version("1.0")
.help_about("Print custom help about text from multi"),
),
);
assert!(utils::compare_output(
app,
"myapp subcmd multi -h",
HELP_ABOUT_MULTI_SC_OVERRIDE,
false
));
}
#[test]
fn help_about_multi_subcmd_override_long_flag() {
let app = App::new("myapp")
.help_about("Print custom help about text")
.subcommand(
App::new("subcmd").subcommand(
App::new("multi")
.version("1.0")
.help_about("Print custom help about text from multi"),
),
);
assert!(utils::compare_output(
app,
"myapp subcmd multi --help",
HELP_ABOUT_MULTI_SC_OVERRIDE,
false
));
}