mirror of
https://github.com/clap-rs/clap
synced 2024-12-15 07:12:32 +00:00
api(App): Adds help_about method to App.
Help about text is now customizable and propagates to subcommands. Closes #2080.
This commit is contained in:
parent
49f857166f
commit
33caf49793
2 changed files with 184 additions and 3 deletions
|
@ -83,6 +83,7 @@ pub struct App<'help> {
|
||||||
pub(crate) long_version: Option<&'help str>,
|
pub(crate) long_version: Option<&'help str>,
|
||||||
pub(crate) about: Option<&'help str>,
|
pub(crate) about: Option<&'help str>,
|
||||||
pub(crate) long_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_help: Option<&'help str>,
|
||||||
pub(crate) before_long_help: Option<&'help str>,
|
pub(crate) before_long_help: Option<&'help str>,
|
||||||
pub(crate) after_help: Option<&'help str>,
|
pub(crate) after_help: Option<&'help str>,
|
||||||
|
@ -420,6 +421,29 @@ impl<'help> App<'help> {
|
||||||
self
|
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
|
/// (Re)Sets the program's name. This will be displayed when displaying help
|
||||||
/// or version messages.
|
/// or version messages.
|
||||||
///
|
///
|
||||||
|
@ -2247,6 +2271,9 @@ impl<'help> App<'help> {
|
||||||
$sc.g_settings = $sc.g_settings | $_self.g_settings;
|
$sc.g_settings = $sc.g_settings | $_self.g_settings;
|
||||||
$sc.term_w = $_self.term_w;
|
$sc.term_w = $_self.term_w;
|
||||||
$sc.max_w = $_self.max_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.
|
// FIXME: This doesn't belong here at all.
|
||||||
|
@ -2299,7 +2326,7 @@ impl<'help> App<'help> {
|
||||||
debug!("App::_create_help_and_version: Building --help");
|
debug!("App::_create_help_and_version: Building --help");
|
||||||
let mut help = Arg::new("help")
|
let mut help = Arg::new("help")
|
||||||
.long("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')) {
|
if !self.args.args.iter().any(|x| x.short == Some('h')) {
|
||||||
help = help.short('h');
|
help = help.short('h');
|
||||||
}
|
}
|
||||||
|
@ -2333,8 +2360,10 @@ impl<'help> App<'help> {
|
||||||
{
|
{
|
||||||
debug!("App::_create_help_and_version: Building help");
|
debug!("App::_create_help_and_version: Building help");
|
||||||
self.subcommands.push(
|
self.subcommands.push(
|
||||||
App::new("help")
|
App::new("help").about(
|
||||||
.about("Prints this message or the help of the given subcommand(s)"),
|
self.help_about
|
||||||
|
.unwrap_or("Prints this message or the help of the given subcommand(s)"),
|
||||||
|
),
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
152
tests/help.rs
152
tests/help.rs
|
@ -1825,3 +1825,155 @@ fn after_help_no_args() {
|
||||||
|
|
||||||
assert_eq!(help, 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
|
||||||
|
));
|
||||||
|
}
|
||||||
|
|
Loading…
Reference in a new issue