Merge pull request #3457 from epage/docs

docs: Update stale references to AppSettings

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

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!(

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() {
             "*:"

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<String>)` or `Variant(Vec<OsString>)`
 
 ### Arg Attributes

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,

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
 

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

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

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!(<cmd> ... "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]

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
     ///

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.

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.