From 54228ef7d7ff5dccf3a268ff95b86fc9b9a2f6b2 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Mon, 29 Nov 2021 16:10:52 -0600 Subject: [PATCH] docs: Prefer `global_setting` I've been finding I've been setting `AppSettings` without it which is likely leading to bugs. This tries to raise the visibility by using it based on the setting being used and not whether the application needs it. --- README.md | 2 +- clap_derive/examples/subcommand_aliases.rs | 2 +- src/build/app/mod.rs | 10 +++++----- src/build/app/settings.rs | 22 +++++++++++----------- 4 files changed, 18 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 7a9d4c3d..0c4c8bd7 100644 --- a/README.md +++ b/README.md @@ -135,7 +135,7 @@ The first example shows the simplest way to use `clap`, by defining a struct. If // // This example demonstrates clap's full 'custom derive' style of creating arguments which is the // simplest method of use, but sacrifices some flexibility. -use clap::{AppSettings, Parser}; +use clap::Parser; /// This doc string acts as a help message when the user runs '--help' /// as do all doc strings on fields diff --git a/clap_derive/examples/subcommand_aliases.rs b/clap_derive/examples/subcommand_aliases.rs index cddd5094..e01d91a2 100644 --- a/clap_derive/examples/subcommand_aliases.rs +++ b/clap_derive/examples/subcommand_aliases.rs @@ -4,7 +4,7 @@ use clap::{AppSettings, Parser}; #[derive(Parser, Debug)] // https://docs.rs/clap/2/clap/enum.AppSettings.html#variant.InferSubcommands -#[clap(setting = AppSettings::InferSubcommands)] +#[clap(global_setting = AppSettings::InferSubcommands)] enum Opt { // https://docs.rs/clap/2/clap/struct.App.html#method.alias #[clap(alias = "foobar")] diff --git a/src/build/app/mod.rs b/src/build/app/mod.rs index 7453cb3e..01aaa5ed 100644 --- a/src/build/app/mod.rs +++ b/src/build/app/mod.rs @@ -935,14 +935,14 @@ impl<'help> App<'help> { /// # use clap::{App, AppSettings}; /// App::new("myprog") /// .setting(AppSettings::SubcommandRequired) - /// .setting(AppSettings::WaitOnError) + /// .setting(AppSettings::AllowLeadingHyphen) /// # ; /// ``` /// or /// ```no_run /// # use clap::{App, AppSettings}; /// App::new("myprog") - /// .setting(AppSettings::SubcommandRequired | AppSettings::WaitOnError) + /// .setting(AppSettings::SubcommandRequired | AppSettings::AllowLeadingHyphen) /// # ; /// ``` #[inline] @@ -964,14 +964,14 @@ impl<'help> App<'help> { /// # use clap::{App, AppSettings}; /// App::new("myprog") /// .unset_setting(AppSettings::SubcommandRequired) - /// .unset_setting(AppSettings::WaitOnError) + /// .setting(AppSettings::AllowLeadingHyphen) /// # ; /// ``` /// or /// ```no_run /// # use clap::{App, AppSettings}; /// App::new("myprog") - /// .unset_setting(AppSettings::SubcommandRequired | AppSettings::WaitOnError) + /// .unset_setting(AppSettings::SubcommandRequired | AppSettings::AllowLeadingHyphen) /// # ; /// ``` #[inline] @@ -994,7 +994,7 @@ impl<'help> App<'help> { /// ```no_run /// # use clap::{App, AppSettings}; /// App::new("myprog") - /// .global_setting(AppSettings::SubcommandRequired) + /// .global_setting(AppSettings::AllowNegativeNumbers) /// # ; /// ``` #[inline] diff --git a/src/build/app/settings.rs b/src/build/app/settings.rs index 61e3105b..c36f34b6 100644 --- a/src/build/app/settings.rs +++ b/src/build/app/settings.rs @@ -268,7 +268,7 @@ pub enum AppSettings { /// ```rust /// # use clap::{App, Arg, AppSettings}; /// let res = App::new("myprog") - /// .setting(AppSettings::AllowNegativeNumbers) + /// .global_setting(AppSettings::AllowNegativeNumbers) /// .arg(Arg::new("num")) /// .try_get_matches_from(vec![ /// "myprog", "-20" @@ -547,7 +547,7 @@ pub enum AppSettings { /// ```no_run /// # use clap::{App, Arg, AppSettings}; /// App::new("myprog") - /// .setting(AppSettings::DontCollapseArgsInUsage) + /// .global_setting(AppSettings::DontCollapseArgsInUsage) /// .get_matches(); /// ``` DontCollapseArgsInUsage, @@ -645,7 +645,7 @@ pub enum AppSettings { /// ```no_run /// # use clap::{App, Arg, AppSettings}; /// App::new("myprog") - /// .setting(AppSettings::DeriveDisplayOrder) + /// .global_setting(AppSettings::DeriveDisplayOrder) /// .get_matches(); /// ``` /// @@ -750,7 +750,7 @@ pub enum AppSettings { /// # use clap::{App, Arg, AppSettings}; /// App::new("myprog") /// .version("v1.1") - /// .setting(AppSettings::PropagateVersion) + /// .global_setting(AppSettings::PropagateVersion) /// .subcommand(App::new("test")) /// .get_matches(); /// // running `$ myprog test --version` will display @@ -803,7 +803,7 @@ pub enum AppSettings { /// ```rust /// # use clap::{App, Arg, AppSettings}; /// App::new("myprog") - /// .setting(AppSettings::HelpExpected) + /// .global_setting(AppSettings::HelpExpected) /// .arg( /// Arg::new("foo").help("It does foo stuff") /// // As required via AppSettings::HelpExpected, a help message was supplied @@ -816,7 +816,7 @@ pub enum AppSettings { /// ```rust,no_run /// # use clap::{App, Arg, AppSettings}; /// App::new("myapp") - /// .setting(AppSettings::HelpExpected) + /// .global_setting(AppSettings::HelpExpected) /// .arg( /// Arg::new("foo") /// // Someone forgot to put .about("...") here @@ -835,7 +835,7 @@ pub enum AppSettings { /// ```rust /// # use clap::{App, arg, AppSettings}; /// let app = App::new("app") - /// .setting(AppSettings::IgnoreErrors) + /// .global_setting(AppSettings::IgnoreErrors) /// .arg(arg!(-c --config "Sets a custom config file").required(false)) /// .arg(arg!(-x --stuff "Sets a custom stuff file").required(false)) /// .arg(arg!(f: -f "Flag")); @@ -869,7 +869,7 @@ pub enum AppSettings { /// ```no_run /// # use clap::{App, Arg, AppSettings}; /// let m = App::new("prog") - /// .setting(AppSettings::InferSubcommands) + /// .global_setting(AppSettings::InferSubcommands) /// .subcommand(App::new("test")) /// .get_matches_from(vec![ /// "prog", "te" @@ -921,7 +921,7 @@ pub enum AppSettings { /// ```no_run /// # use clap::{App, Arg, AppSettings}; /// App::new("myprog") - /// .setting(AppSettings::NextLineHelp) + /// .global_setting(AppSettings::NextLineHelp) /// .get_matches(); /// ``` NextLineHelp, @@ -1004,7 +1004,7 @@ pub enum AppSettings { /// ```rust /// # use clap::{App, Arg, AppSettings}; /// App::new("myprog") - /// .setting(AppSettings::UseLongFormatForHelpSubcommand) + /// .global_setting(AppSettings::UseLongFormatForHelpSubcommand) /// .subcommand(App::new("test") /// .arg(Arg::new("foo") /// .help("short form about message") @@ -1075,7 +1075,7 @@ pub enum AppSettings { /// ```rust /// # use clap::{App, Arg, AppSettings}; /// App::new("myprog") - /// .setting(AppSettings::WaitOnError); + /// .global_setting(AppSettings::WaitOnError); /// ``` WaitOnError,