From 97e36451cfb68b7079ed176e69db0769cabd549f Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 11 Feb 2022 15:58:12 -0600 Subject: [PATCH 1/2] docs: Update stale references to AppSettings --- README.md | 2 +- examples/derive_ref/README.md | 2 +- examples/multicall-busybox.md | 2 +- examples/multicall-hostname.md | 2 +- examples/tutorial_builder/README.md | 4 +--- examples/tutorial_derive/README.md | 4 +--- src/build/app.rs | 34 ++++++++++++++--------------- src/build/arg.rs | 20 ++++++++--------- src/build/value_hint.rs | 4 ++-- src/error/kind.rs | 24 ++++++++++---------- src/parse/matches/arg_matches.rs | 4 ++-- 11 files changed, 47 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 625e6946fa2..4cf89ca61db 100644 --- a/README.md +++ b/README.md @@ -151,7 +151,7 @@ Why use the procedural [Builder API](https://github.com/clap-rs/clap/blob/v3.0.1 **Warning:** These may contain breaking changes between minor releases. * **unstable-replace**: Enable [`App::replace`](https://github.com/clap-rs/clap/issues/2836) -* **unstable-multicall**: Enable [`AppSettings::Multicall`](https://github.com/clap-rs/clap/issues/2861) +* **unstable-multicall**: Enable [`App::multicall`](https://github.com/clap-rs/clap/issues/2861) * **unstable-grouped**: Enable [`ArgMatches::grouped_values_of`](https://github.com/clap-rs/clap/issues/2924) ## Sponsors diff --git a/examples/derive_ref/README.md b/examples/derive_ref/README.md index 993b9cf841e..917a85bd5d1 100644 --- a/examples/derive_ref/README.md +++ b/examples/derive_ref/README.md @@ -144,7 +144,7 @@ And for `Subcommand` variants: - `skip`: Ignore this variant - `flatten`: Delegates to the variant for more subcommands (must implement `Subcommand`) - `subcommand`: Nest subcommands under the current set of subcommands (must implement `Subcommand`) -- `external_subcommand`: `clap::AppSettings::AllowExternalSubcommand` +- `external_subcommand`: `clap::App::allow_external_subcommand(true)` - Variant must be either `Variant(Vec)` or `Variant(Vec)` ### Arg Attributes diff --git a/examples/multicall-busybox.md b/examples/multicall-busybox.md index 040b0088fe9..723d03319c0 100644 --- a/examples/multicall-busybox.md +++ b/examples/multicall-busybox.md @@ -2,7 +2,7 @@ Example of a busybox-style multicall program -See the documentation for clap::AppSettings::Multicall for rationale. +See the documentation for `clap::App::multicall` for rationale. This example omits every command except true and false, which are the most trivial to implement, diff --git a/examples/multicall-hostname.md b/examples/multicall-hostname.md index a59aa0ab8cd..1bbb521fc1f 100644 --- a/examples/multicall-hostname.md +++ b/examples/multicall-hostname.md @@ -2,7 +2,7 @@ Example of a `hostname-style` multicall program -See the documentation for clap::AppSettings::Multicall for rationale. +See the documentation for `clap::App::multicall` for rationale. This example omits the implementation of displaying address config diff --git a/examples/tutorial_builder/README.md b/examples/tutorial_builder/README.md index b5ebc695de7..59ac563f9bc 100644 --- a/examples/tutorial_builder/README.md +++ b/examples/tutorial_builder/README.md @@ -109,9 +109,7 @@ clap [..] ``` -You can use `AppSettings` to change the application level behavior of clap. You -can apply the setting to the top level command (`app.setting()`) or to it and -all subcommands (`app.global_setting()`). +You can use `App` methods to change the application level behavior of clap. [Example:](02_app_settings.rs) ```console diff --git a/examples/tutorial_derive/README.md b/examples/tutorial_derive/README.md index 9f97bb4999b..c8ab0ea5fef 100644 --- a/examples/tutorial_derive/README.md +++ b/examples/tutorial_derive/README.md @@ -111,9 +111,7 @@ clap [..] ``` -You can use `AppSettings` to change the application level behavior of clap. You -can apply the setting to the top level command (`app.setting()`) or to it and -all subcommands (`app.global_setting()`). +You can use `App` methods to change the application level behavior of clap. [Example:](02_app_settings.rs) ```console diff --git a/src/build/app.rs b/src/build/app.rs index 09fc0da3485..6ab599671f0 100644 --- a/src/build/app.rs +++ b/src/build/app.rs @@ -514,7 +514,7 @@ impl<'help> App<'help> { /// Parse the specified arguments, exiting on failure. /// /// **NOTE:** The first argument will be parsed as the binary name unless - /// [`AppSettings::NoBinaryName`] is used. + /// [`App::no_binary_name`] is used. /// /// # Panics /// @@ -552,7 +552,7 @@ impl<'help> App<'help> { /// perform a [`std::process::exit`] yourself. /// /// **NOTE:** The first argument will be parsed as the binary name unless - /// [`AppSettings::NoBinaryName`] is used. + /// [`App::no_binary_name`] is used. /// /// # Panics /// @@ -597,7 +597,7 @@ impl<'help> App<'help> { /// perform a [`std::process::exit`] yourself. /// /// **NOTE:** The first argument will be parsed as the binary name unless - /// [`AppSettings::NoBinaryName`] is used. + /// [`App::no_binary_name`] is used. /// /// # Panics /// @@ -851,7 +851,7 @@ impl<'help> App<'help> { /// # Examples /// /// ```rust - /// # use clap::{App, arg, AppSettings}; + /// # use clap::{App, arg}; /// let m = App::new("myprog") /// .no_binary_name(true) /// .arg(arg!( ... "commands to run")) @@ -1293,7 +1293,7 @@ impl<'help> App<'help> { /// **CAUTION:** This setting can interfere with [positional/free arguments], take care when /// designing CLIs which allow inferred subcommands and have potential positional/free /// arguments whose values could start with the same characters as subcommands. If this is the - /// case, it's recommended to use settings such as [`AppSettings::ArgsNegateSubcommands`] in + /// case, it's recommended to use settings such as [`App::args_conflicts_with_subcommands`] in /// conjunction with this setting. /// /// **NOTE:** This choice is propagated to all child subcommands. @@ -2635,7 +2635,7 @@ impl<'help> App<'help> { /// # Examples /// /// ```rust - /// # use clap::{App, Arg, AppSettings, }; + /// # use clap::{App, Arg}; /// App::new("myprog") /// .subcommand( /// App::new("test").hide(true) @@ -2658,7 +2658,7 @@ impl<'help> App<'help> { /// # Examples /// /// ```rust - /// # use clap::{App, AppSettings, ErrorKind}; + /// # use clap::{App, ErrorKind}; /// let err = App::new("myprog") /// .subcommand_required(true) /// .subcommand(App::new("test")) @@ -2689,7 +2689,7 @@ impl<'help> App<'help> { /// # Examples /// /// ```rust - /// # use clap::{App, AppSettings}; + /// # use clap::App; /// // Assume there is an external subcommand named "subcmd" /// let m = App::new("myprog") /// .allow_external_subcommands(true) @@ -2736,7 +2736,7 @@ impl<'help> App<'help> { /// #[cfg_attr(not(unix), doc = " ```ignore")] #[cfg_attr(unix, doc = " ```")] - /// # use clap::{App, AppSettings}; + /// # use clap::App; /// // Assume there is an external subcommand named "subcmd" /// let m = App::new("myprog") /// .allow_invalid_utf8_for_external_subcommands(true) @@ -2784,7 +2784,7 @@ impl<'help> App<'help> { /// # Examples /// /// ```rust - /// # use clap::{App, AppSettings}; + /// # use clap::App; /// App::new("myprog") /// .args_conflicts_with_subcommands(true); /// ``` @@ -2824,7 +2824,7 @@ impl<'help> App<'help> { /// # Examples /// /// ```rust - /// # use clap::{App, AppSettings, Arg}; + /// # use clap::{App, Arg}; /// let app = App::new("app").subcommand(App::new("sub")).arg( /// Arg::new("arg") /// .long("arg") @@ -2874,7 +2874,7 @@ impl<'help> App<'help> { /// This first example shows that it is an error to not use a required argument /// /// ```rust - /// # use clap::{App, Arg, AppSettings, ErrorKind}; + /// # use clap::{App, Arg, ErrorKind}; /// let err = App::new("myprog") /// .subcommand_negates_reqs(true) /// .arg(Arg::new("opt").required(true)) @@ -2891,7 +2891,7 @@ impl<'help> App<'help> { /// valid subcommand is used. /// /// ```rust - /// # use clap::{App, Arg, AppSettings, ErrorKind}; + /// # use clap::{App, Arg, ErrorKind}; /// let noerr = App::new("myprog") /// .subcommand_negates_reqs(true) /// .arg(Arg::new("opt").required(true)) @@ -2926,7 +2926,7 @@ impl<'help> App<'help> { /// such as deduplicating code across multiple programs /// without loading a shared library at runtime. /// - /// Multicall can't be used with [`NoBinaryName`] since they interpret + /// Multicall can't be used with [`no_binary_name`] since they interpret /// the command name in incompatible ways. /// /// # Examples @@ -2949,7 +2949,7 @@ impl<'help> App<'help> { /// This does not allow the subcommand to be passed as the first non-path argument. /// /// ```rust - /// # use clap::{App, AppSettings, ErrorKind}; + /// # use clap::{App, ErrorKind}; /// let mut app = App::new("hostname") /// .multicall(true) /// .subcommand(App::new("hostname")) @@ -2976,7 +2976,7 @@ impl<'help> App<'help> { /// and as subcommands of the "main" applet. /// /// ```rust - /// # use clap::{App, AppSettings}; + /// # use clap::App; /// fn applet_commands() -> [App<'static>; 2] { /// [App::new("true"), App::new("false")] /// } @@ -3003,7 +3003,7 @@ impl<'help> App<'help> { /// so it's recommended to use [`App::subcommand_help_heading`] and /// [`App::subcommand_value_name`] to change the descriptive text as above. /// - /// [`NoBinaryName`]: crate::AppSettings::NoBinaryName + /// [`no_binary_name`]: crate::App::no_binary_name /// [`App::subcommand_value_name`]: crate::App::subcommand_value_name /// [`App::subcommand_help_heading`]: crate::App::subcommand_help_heading #[inline] diff --git a/src/build/arg.rs b/src/build/arg.rs index 4975ca4ae9b..6d3bd67ab22 100644 --- a/src/build/arg.rs +++ b/src/build/arg.rs @@ -486,8 +486,9 @@ impl<'help> Arg<'help> { /// **NOTE:** Setting this requires [`Arg::takes_value`] /// /// **CAUTION:** Using this setting *and* having child subcommands is not - /// recommended with the exception of *also* using [`crate::AppSettings::ArgsNegateSubcommands`] - /// (or [`crate::AppSettings::SubcommandsNegateReqs`] if the argument marked `Last` is also + /// recommended with the exception of *also* using + /// [`crate::App::args_conflicts_with_subcommands`] + /// (or [`crate::App::subcommand_negates_reqs`] if the argument marked `Last` is also /// marked [`Arg::required`]) /// /// # Examples @@ -1468,9 +1469,9 @@ impl<'help> Arg<'help> { /// To take a full command line and its arguments (for example, when writing a command wrapper): /// /// ``` - /// # use clap::{App, AppSettings, Arg, ValueHint}; + /// # use clap::{App, Arg, ValueHint}; /// App::new("prog") - /// .setting(AppSettings::TrailingVarArg) + /// .trailing_var_arg(true) /// .arg( /// Arg::new("command") /// .takes_value(true) @@ -2333,7 +2334,7 @@ impl<'help> Arg<'help> { /// ``` /// /// Will result in everything after `--` to be considered one raw argument. This behavior - /// may not be exactly what you are expecting and using [`crate::AppSettings::TrailingVarArg`] + /// may not be exactly what you are expecting and using [`crate::App::trailing_var_arg`] /// may be more appropriate. /// /// **NOTE:** Implicitly sets [`Arg::takes_value(true)`] [`Arg::multiple_values(true)`], @@ -2372,9 +2373,6 @@ impl<'help> Arg<'help> { /// /// **NOTE:** This implicitly sets [`Arg::takes_value(true)`]. /// - /// **NOTE:** This setting effectively disables `AppSettings::ArgRequiredElseHelp` if used in - /// conjunction as it ensures that some argument will always be present. - /// /// # Examples /// /// First we use the default value without providing any value at runtime. @@ -2920,8 +2918,8 @@ impl<'help> Arg<'help> { /// This can be helpful for arguments with very long or complex help messages. /// This can also be helpful for arguments with very long flag names, or many/long value names. /// - /// **NOTE:** To apply this setting to all arguments consider using - /// [`crate::AppSettings::NextLineHelp`] + /// **NOTE:** To apply this setting to all arguments and subcommands, consider using + /// [`crate::App::next_line_help`] /// /// # Examples /// @@ -3018,7 +3016,7 @@ impl<'help> Arg<'help> { /// **NOTE:** Setting this requires [`Arg::takes_value`] /// /// To set this for all arguments, see - /// [`AppSettings::HidePossibleValues`][crate::AppSettings::HidePossibleValues]. + /// [`App::hide_possible_values`][crate::App::hide_possible_values]. /// /// # Examples /// diff --git a/src/build/value_hint.rs b/src/build/value_hint.rs index b61a3e778e0..3f8d591ce68 100644 --- a/src/build/value_hint.rs +++ b/src/build/value_hint.rs @@ -48,11 +48,11 @@ pub enum ValueHint { /// common when writing shell wrappers that execute anther command, for example `sudo` or `env`. /// /// This hint is special, the argument must be a positional argument and have - /// [`.multiple_values(true)`] and App must use [`AppSettings::TrailingVarArg`]. The result is that the + /// [`.multiple_values(true)`] and App must use [`App::trailing_var_arg(true)`]. The result is that the /// command line `my_app ls -la /` will be parsed as `["ls", "-la", "/"]` and clap won't try to /// parse the `-la` argument itself. /// - /// [`AppSettings::TrailingVarArg`]: crate::AppSettings::TrailingVarArg + /// [`App::trailing_var_arg(true)`]: crate::App::trailing_var_arg /// [`.multiple_values(true)`]: crate::Arg::multiple_values() CommandWithArguments, /// Name of a local operating system user. diff --git a/src/error/kind.rs b/src/error/kind.rs index 9f82e4ef050..b93601d9585 100644 --- a/src/error/kind.rs +++ b/src/error/kind.rs @@ -252,15 +252,15 @@ pub enum ErrorKind { /// ``` MissingRequiredArgument, - /// Occurs when a subcommand is required (as defined by [`AppSettings::SubcommandRequired`]), + /// Occurs when a subcommand is required (as defined by [`App::subcommand_required`]), /// but the user does not provide one. /// /// # Examples /// /// ```rust - /// # use clap::{App, AppSettings, ErrorKind}; + /// # use clap::{App, ErrorKind}; /// let err = App::new("prog") - /// .setting(AppSettings::SubcommandRequired) + /// .subcommand_required(true) /// .subcommand(App::new("test")) /// .try_get_matches_from(vec![ /// "myprog", @@ -270,7 +270,7 @@ pub enum ErrorKind { /// # ; /// ``` /// - /// [`AppSettings::SubcommandRequired`]: crate::AppSettings::SubcommandRequired + /// [`App::subcommand_required`]: crate::App::subcommand_required MissingSubcommand, /// Occurs when the user provides multiple values to an argument which doesn't allow that. @@ -293,7 +293,7 @@ pub enum ErrorKind { /// /// To allow arbitrary data /// - Set [`Arg::allow_invalid_utf8`] for argument values - /// - Set [`AppSettings::AllowInvalidUtf8ForExternalSubcommands`] for external-subcommand + /// - Set [`App::allow_invalid_utf8_for_external_subcommands`] for external-subcommand /// values /// /// # Platform Specific @@ -304,7 +304,7 @@ pub enum ErrorKind { /// #[cfg_attr(not(unix), doc = " ```ignore")] #[cfg_attr(unix, doc = " ```")] - /// # use clap::{App, Arg, ErrorKind, AppSettings}; + /// # use clap::{App, Arg, ErrorKind}; /// # use std::os::unix::ffi::OsStringExt; /// # use std::ffi::OsString; /// let result = App::new("prog") @@ -319,7 +319,7 @@ pub enum ErrorKind { /// ``` /// /// [`Arg::allow_invalid_utf8`]: crate::Arg::allow_invalid_utf8 - /// [`AppSettings::AllowInvalidUtf8ForExternalSubcommands`]: crate::AppSettings::AllowInvalidUtf8ForExternalSubcommands + /// [`App::allow_invalid_utf8_for_external_subcommands`]: crate::App::allow_invalid_utf8_for_external_subcommands InvalidUtf8, /// Not a true "error" as it means `--help` or similar was used. @@ -340,16 +340,15 @@ pub enum ErrorKind { DisplayHelp, /// Occurs when either an argument or a [`Subcommand`] is required, as defined by - /// [`AppSettings::ArgRequiredElseHelp`] and - /// [`AppSettings::SubcommandRequiredElseHelp`], but the user did not provide + /// [`App::arg_required_else_help`] , but the user did not provide /// one. /// /// # Examples /// /// ```rust - /// # use clap::{App, Arg, AppSettings, ErrorKind, }; + /// # use clap::{App, Arg, ErrorKind, }; /// let result = App::new("prog") - /// .setting(AppSettings::ArgRequiredElseHelp) + /// .arg_required_else_help(true) /// .subcommand(App::new("config") /// .about("Used for configuration") /// .arg(Arg::new("config_file") @@ -360,8 +359,7 @@ pub enum ErrorKind { /// ``` /// /// [`Subcommand`]: crate::Subcommand - /// [`AppSettings::ArgRequiredElseHelp`]: crate::AppSettings::ArgRequiredElseHelp - /// [`AppSettings::SubcommandRequiredElseHelp`]: crate::AppSettings::SubcommandRequiredElseHelp + /// [`App::arg_required_else_help`]: crate::App::arg_required_else_help DisplayHelpOnMissingArgumentOrSubcommand, /// Not a true "error" as it means `--version` or similar was used. diff --git a/src/parse/matches/arg_matches.rs b/src/parse/matches/arg_matches.rs index b8acb9c52ea..dbc86b5c21c 100644 --- a/src/parse/matches/arg_matches.rs +++ b/src/parse/matches/arg_matches.rs @@ -962,10 +962,10 @@ impl ArgMatches { /// with pattern matching! /// /// ```rust - /// # use clap::{App, AppSettings}; + /// # use clap::App; /// // Assume there is an external subcommand named "subcmd" /// let app_m = App::new("myprog") - /// .setting(AppSettings::AllowExternalSubcommands) + /// .allow_external_subcommands(true) /// .get_matches_from(vec![ /// "myprog", "subcmd", "--option", "value", "-fff", "--flag" /// ]); From 1e4ec5f4f01f4376c6f166e6225072c161a8f7d9 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 11 Feb 2022 15:59:03 -0600 Subject: [PATCH 2/2] fix: Deprecation warnings --- clap_complete/src/shells/bash.rs | 2 +- clap_complete/src/shells/zsh.rs | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/clap_complete/src/shells/bash.rs b/clap_complete/src/shells/bash.rs index 2d5a77240c1..3848437aeeb 100644 --- a/clap_complete/src/shells/bash.rs +++ b/clap_complete/src/shells/bash.rs @@ -172,7 +172,7 @@ fn option_details_for_path(app: &App, path: &str) -> String { } fn vals_for(o: &Arg) -> String { - debug!("vals_for: o={}", o.get_name()); + debug!("vals_for: o={}", o.get_id()); if let Some(vals) = o.get_possible_values() { format!( diff --git a/clap_complete/src/shells/zsh.rs b/clap_complete/src/shells/zsh.rs index 0b6f7eda1ae..e5887134868 100644 --- a/clap_complete/src/shells/zsh.rs +++ b/clap_complete/src/shells/zsh.rs @@ -442,7 +442,7 @@ fn write_opts_of(p: &App, p_global: Option<&App>) -> String { let mut ret = vec![]; for o in p.get_opts() { - debug!("write_opts_of:iter: o={}", o.get_name()); + debug!("write_opts_of:iter: o={}", o.get_id()); let help = o.get_help().map_or(String::new(), escape_help); let conflicts = arg_conflicts(p, o, p_global); @@ -626,7 +626,7 @@ fn write_positionals_of(p: &App) -> String { let mut ret = vec![]; for arg in p.get_positionals() { - debug!("write_positionals_of:iter: arg={}", arg.get_name()); + debug!("write_positionals_of:iter: arg={}", arg.get_id()); let cardinality = if arg.is_multiple_values_set() || arg.is_multiple_occurrences_set() { "*:"