Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-12-04 18:19:13 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs: Highlight notes/warnings in a block

Browse source
This commit is contained in:
Ed Page 2024-11-08 11:07:48 -06:00
parent c54ffa17f5
commit 6f78e2a3ff
20 changed files with 686 additions and 42 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
clap_builder/src/builder/action.rs
View file

@ -32,10 +32,14 @@ use crate::util::AnyValueId;
pub enum ArgAction { pub enum ArgAction {
/// When encountered, store the associated value(s) in [`ArgMatches`][crate::ArgMatches] /// When encountered, store the associated value(s) in [`ArgMatches`][crate::ArgMatches]
/// ///
/// <div class="warning">
///
/// **NOTE:** If the argument has previously been seen, it will result in a /// **NOTE:** If the argument has previously been seen, it will result in a
/// [`ArgumentConflict`][crate::error::ErrorKind::ArgumentConflict] unless /// [`ArgumentConflict`][crate::error::ErrorKind::ArgumentConflict] unless
/// [`Command::args_override_self(true)`][crate::Command::args_override_self] is set. /// [`Command::args_override_self(true)`][crate::Command::args_override_self] is set.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -87,10 +91,14 @@ pub enum ArgAction {
/// No value is allowed. To optionally accept a value, see /// No value is allowed. To optionally accept a value, see
/// [`Arg::default_missing_value`][super::Arg::default_missing_value] /// [`Arg::default_missing_value`][super::Arg::default_missing_value]
/// ///
/// <div class="warning">
///
/// **NOTE:** If the argument has previously been seen, it will result in a /// **NOTE:** If the argument has previously been seen, it will result in a
/// [`ArgumentConflict`][crate::error::ErrorKind::ArgumentConflict] unless /// [`ArgumentConflict`][crate::error::ErrorKind::ArgumentConflict] unless
/// [`Command::args_override_self(true)`][crate::Command::args_override_self] is set. /// [`Command::args_override_self(true)`][crate::Command::args_override_self] is set.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -162,10 +170,14 @@ pub enum ArgAction {
/// No value is allowed. To optionally accept a value, see /// No value is allowed. To optionally accept a value, see
/// [`Arg::default_missing_value`][super::Arg::default_missing_value] /// [`Arg::default_missing_value`][super::Arg::default_missing_value]
/// ///
/// <div class="warning">
///
/// **NOTE:** If the argument has previously been seen, it will result in a /// **NOTE:** If the argument has previously been seen, it will result in a
/// [`ArgumentConflict`][crate::error::ErrorKind::ArgumentConflict] unless /// [`ArgumentConflict`][crate::error::ErrorKind::ArgumentConflict] unless
/// [`Command::args_override_self(true)`][crate::Command::args_override_self] is set. /// [`Command::args_override_self(true)`][crate::Command::args_override_self] is set.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust

4
clap_builder/src/builder/app_settings.rs
View file

@ -35,9 +35,13 @@ impl std::ops::BitOr for AppFlags {
/// Application level settings, which affect how [`Command`] operates /// Application level settings, which affect how [`Command`] operates
/// ///
/// <div class="warning">
///
/// **NOTE:** When these settings are used, they apply only to current command, and are *not* /// **NOTE:** When these settings are used, they apply only to current command, and are *not*
/// propagated down or up through child or parent subcommands /// propagated down or up through child or parent subcommands
/// ///
/// </div>
///
/// [`Command`]: crate::Command /// [`Command`]: crate::Command
#[derive(Debug, PartialEq, Copy, Clone)] #[derive(Debug, PartialEq, Copy, Clone)]
#[repr(u8)] #[repr(u8)]

267
clap_builder/src/builder/arg.rs
View file

@ -98,10 +98,14 @@ impl Arg {
/// The name is used to check whether or not the argument was used at /// The name is used to check whether or not the argument was used at
/// runtime, get values, set relationships with other args, etc.. /// runtime, get values, set relationships with other args, etc..
/// ///
/// <div class="warning">
///
/// **NOTE:** In the case of arguments that take values (i.e. [`Arg::action(ArgAction::Set)`]) /// **NOTE:** In the case of arguments that take values (i.e. [`Arg::action(ArgAction::Set)`])
/// and positional arguments (i.e. those without a preceding `-` or `--`) the name will also /// and positional arguments (i.e. those without a preceding `-` or `--`) the name will also
/// be displayed when the user prints the usage/help information of the program. /// be displayed when the user prints the usage/help information of the program.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -188,8 +192,12 @@ impl Arg {
/// own arguments, in which case `clap` simply will not assign those to the auto-generated /// own arguments, in which case `clap` simply will not assign those to the auto-generated
/// `version` or `help` arguments. /// `version` or `help` arguments.
/// ///
/// <div class="warning">
///
/// **NOTE:** Any leading `-` characters will be stripped /// **NOTE:** Any leading `-` characters will be stripped
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// To set `long` use a word containing valid UTF-8. If you supply a double leading /// To set `long` use a word containing valid UTF-8. If you supply a double leading
@ -456,19 +464,35 @@ impl Arg {
/// Specifies the index of a positional argument **starting at** 1. /// Specifies the index of a positional argument **starting at** 1.
/// ///
/// <div class="warning">
///
/// **NOTE:** The index refers to position according to **other positional argument**. It does /// **NOTE:** The index refers to position according to **other positional argument**. It does
/// not define position in the argument list as a whole. /// not define position in the argument list as a whole.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** You can optionally leave off the `index` method, and the index will be /// **NOTE:** You can optionally leave off the `index` method, and the index will be
/// assigned in order of evaluation. Utilizing the `index` method allows for setting /// assigned in order of evaluation. Utilizing the `index` method allows for setting
/// indexes out of order /// indexes out of order
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** This is only meant to be used for positional arguments and shouldn't to be used /// **NOTE:** This is only meant to be used for positional arguments and shouldn't to be used
/// with [`Arg::short`] or [`Arg::long`]. /// with [`Arg::short`] or [`Arg::long`].
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** When utilized with [`Arg::num_args(1..)`], only the **last** positional argument /// **NOTE:** When utilized with [`Arg::num_args(1..)`], only the **last** positional argument
/// may be defined as having a variable number of arguments (i.e. with the highest index) /// may be defined as having a variable number of arguments (i.e. with the highest index)
/// ///
/// </div>
///
/// # Panics /// # Panics
/// ///
/// [`Command`] will [`panic!`] if indexes are skipped (such as defining `index(1)` and `index(3)` /// [`Command`] will [`panic!`] if indexes are skipped (such as defining `index(1)` and `index(3)`
@ -516,14 +540,26 @@ impl Arg {
/// This is a "var arg" and everything that follows should be captured by it, as if the user had /// This is a "var arg" and everything that follows should be captured by it, as if the user had
/// used a `--`. /// used a `--`.
/// ///
/// <div class="warning">
///
/// **NOTE:** To start the trailing "var arg" on unknown flags (and not just a positional /// **NOTE:** To start the trailing "var arg" on unknown flags (and not just a positional
/// value), set [`allow_hyphen_values`][Arg::allow_hyphen_values]. Either way, users still /// value), set [`allow_hyphen_values`][Arg::allow_hyphen_values]. Either way, users still
/// have the option to explicitly escape ambiguous arguments with `--`. /// have the option to explicitly escape ambiguous arguments with `--`.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** [`Arg::value_delimiter`] still applies if set. /// **NOTE:** [`Arg::value_delimiter`] still applies if set.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** Setting this requires [`Arg::num_args(..)`]. /// **NOTE:** Setting this requires [`Arg::num_args(..)`].
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -554,22 +590,42 @@ impl Arg {
/// allows one to access this arg early using the `--` syntax. Accessing an arg early, even with /// allows one to access this arg early using the `--` syntax. Accessing an arg early, even with
/// the `--` syntax is otherwise not possible. /// the `--` syntax is otherwise not possible.
/// ///
/// <div class="warning">
///
/// **NOTE:** This will change the usage string to look like `$ prog [OPTIONS] [-- <ARG>]` if /// **NOTE:** This will change the usage string to look like `$ prog [OPTIONS] [-- <ARG>]` if
/// `ARG` is marked as `.last(true)`. /// `ARG` is marked as `.last(true)`.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** This setting will imply [`crate::Command::dont_collapse_args_in_usage`] because failing /// **NOTE:** This setting will imply [`crate::Command::dont_collapse_args_in_usage`] because failing
/// to set this can make the usage string very confusing. /// to set this can make the usage string very confusing.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE**: This setting only applies to positional arguments, and has no effect on OPTIONS /// **NOTE**: This setting only applies to positional arguments, and has no effect on OPTIONS
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** Setting this requires [taking values][Arg::num_args] /// **NOTE:** Setting this requires [taking values][Arg::num_args]
/// ///
/// **CAUTION:** Using this setting *and* having child subcommands is not /// </div>
///
/// <div class="warning">
///
/// **WARNING:** Using this setting *and* having child subcommands is not
/// recommended with the exception of *also* using /// recommended with the exception of *also* using
/// [`crate::Command::args_conflicts_with_subcommands`] /// [`crate::Command::args_conflicts_with_subcommands`]
/// (or [`crate::Command::subcommand_negates_reqs`] if the argument marked `Last` is also /// (or [`crate::Command::subcommand_negates_reqs`] if the argument marked `Last` is also
/// marked [`Arg::required`]) /// marked [`Arg::required`])
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -704,8 +760,12 @@ impl Arg {
/// ///
/// i.e. when using this argument, the following argument *must* be present. /// i.e. when using this argument, the following argument *must* be present.
/// ///
/// <div class="warning">
///
/// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required /// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -812,11 +872,15 @@ impl Arg {
/// Specifies that an argument can be matched to all child [`Subcommand`]s. /// Specifies that an argument can be matched to all child [`Subcommand`]s.
/// ///
/// <div class="warning">
///
/// **NOTE:** Global arguments *only* propagate down, **not** up (to parent commands), however /// **NOTE:** Global arguments *only* propagate down, **not** up (to parent commands), however
/// their values once a user uses them will be propagated back up to parents. In effect, this /// their values once a user uses them will be propagated back up to parents. In effect, this
/// means one should *define* all global arguments at the top level, however it doesn't matter /// means one should *define* all global arguments at the top level, however it doesn't matter
/// where the user *uses* the global argument. /// where the user *uses* the global argument.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// Assume an application with two subcommands, and you'd like to define a /// Assume an application with two subcommands, and you'd like to define a
@ -994,6 +1058,8 @@ impl Arg {
/// - Using an equals and no space such as `-o=value` or `--option=value` /// - Using an equals and no space such as `-o=value` or `--option=value`
/// - Use a short and no space such as `-ovalue` /// - Use a short and no space such as `-ovalue`
/// ///
/// <div class="warning">
///
/// **WARNING:** /// **WARNING:**
/// ///
/// Setting a variable number of values (e.g. `1..=10`) for an argument without /// Setting a variable number of values (e.g. `1..=10`) for an argument without
@ -1012,6 +1078,8 @@ impl Arg {
/// - Require a flag occurrence per value with [`ArgAction::Append`] /// - Require a flag occurrence per value with [`ArgAction::Append`]
/// - Require positional arguments to appear after `--` with [`Arg::last`] /// - Require positional arguments to appear after `--` with [`Arg::last`]
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// Option: /// Option:
@ -1155,8 +1223,12 @@ impl Arg {
/// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to /// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to
/// use all capital letters for the value name. /// use all capital letters for the value name.
/// ///
/// <div class="warning">
///
/// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`] /// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`]
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -1218,11 +1290,19 @@ impl Arg {
/// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to /// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to
/// use all capital letters for the value name. /// use all capital letters for the value name.
/// ///
/// **Pro Tip:** It may help to use [`Arg::next_line_help(true)`] if there are long, or /// <div class="warning">
///
/// **TIP:** It may help to use [`Arg::next_line_help(true)`] if there are long, or
/// multiple value names in order to not throw off the help text alignment of all options. /// multiple value names in order to not throw off the help text alignment of all options.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`] and [`Arg::num_args(1..)`]. /// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`] and [`Arg::num_args(1..)`].
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -1273,8 +1353,12 @@ impl Arg {
/// ///
/// See [`ValueHint`] for more information. /// See [`ValueHint`] for more information.
/// ///
/// <div class="warning">
///
/// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`]. /// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`].
/// ///
/// </div>
///
/// For example, to take a username as argument: /// For example, to take a username as argument:
/// ///
/// ```rust /// ```rust
@ -1322,10 +1406,18 @@ impl Arg {
/// [`Arg::required_if_eq_all`] is case-insensitive. /// [`Arg::required_if_eq_all`] is case-insensitive.
/// ///
/// ///
/// <div class="warning">
///
/// **NOTE:** Setting this requires [taking values][Arg::num_args] /// **NOTE:** Setting this requires [taking values][Arg::num_args]
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** To do unicode case folding, enable the `unicode` feature flag. /// **NOTE:** To do unicode case folding, enable the `unicode` feature flag.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -1381,18 +1473,30 @@ impl Arg {
/// ///
/// See also [`trailing_var_arg`][Arg::trailing_var_arg]. /// See also [`trailing_var_arg`][Arg::trailing_var_arg].
/// ///
/// <div class="warning">
///
/// **NOTE:** Setting this requires [taking values][Arg::num_args] /// **NOTE:** Setting this requires [taking values][Arg::num_args]
/// ///
/// </div>
///
/// <div class="warning">
///
/// **WARNING:** Prior arguments with `allow_hyphen_values(true)` get precedence over known /// **WARNING:** Prior arguments with `allow_hyphen_values(true)` get precedence over known
/// flags but known flags get precedence over the next possible positional argument with /// flags but known flags get precedence over the next possible positional argument with
/// `allow_hyphen_values(true)`. When combined with [`Arg::num_args(..)`], /// `allow_hyphen_values(true)`. When combined with [`Arg::num_args(..)`],
/// [`Arg::value_terminator`] is one way to ensure processing stops. /// [`Arg::value_terminator`] is one way to ensure processing stops.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **WARNING**: Take caution when using this setting combined with another argument using /// **WARNING**: Take caution when using this setting combined with another argument using
/// [`Arg::num_args`], as this becomes ambiguous `$ prog --arg -- -- val`. All /// [`Arg::num_args`], as this becomes ambiguous `$ prog --arg -- -- val`. All
/// three `--, --, val` will be values when the user may have thought the second `--` would /// three `--, --, val` will be values when the user may have thought the second `--` would
/// constitute the normal, "Only positional args follow" idiom. /// constitute the normal, "Only positional args follow" idiom.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -1443,8 +1547,12 @@ impl Arg {
/// This is similar to [`Arg::allow_hyphen_values`] except that it only allows numbers, /// This is similar to [`Arg::allow_hyphen_values`] except that it only allows numbers,
/// all other undefined leading hyphens will fail to parse. /// all other undefined leading hyphens will fail to parse.
/// ///
/// <div class="warning">
///
/// **NOTE:** Setting this requires [taking values][Arg::num_args] /// **NOTE:** Setting this requires [taking values][Arg::num_args]
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -1472,8 +1580,12 @@ impl Arg {
/// ///
/// i.e. an equals between the option and associated value. /// i.e. an equals between the option and associated value.
/// ///
/// <div class="warning">
///
/// **NOTE:** Setting this requires [taking values][Arg::num_args] /// **NOTE:** Setting this requires [taking values][Arg::num_args]
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// Setting `require_equals` requires that the option have an equals sign between /// Setting `require_equals` requires that the option have an equals sign between
@ -1573,11 +1685,19 @@ impl Arg {
/// argument until it reaches another valid argument, or one of the other more specific settings /// argument until it reaches another valid argument, or one of the other more specific settings
/// for multiple values is used (such as [`num_args`]). /// for multiple values is used (such as [`num_args`]).
/// ///
/// <div class="warning">
///
/// **NOTE:** This setting only applies to [options] and [positional arguments] /// **NOTE:** This setting only applies to [options] and [positional arguments]
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** When the terminator is passed in on the command line, it is **not** stored as one /// **NOTE:** When the terminator is passed in on the command line, it is **not** stored as one
/// of the values /// of the values
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -1636,7 +1756,12 @@ impl Arg {
/// may not be exactly what you are expecting and using [`Arg::trailing_var_arg`] /// may not be exactly what you are expecting and using [`Arg::trailing_var_arg`]
/// may be more appropriate. /// may be more appropriate.
/// ///
/// <div class="warning">
///
/// **NOTE:** Implicitly sets [`Arg::action(ArgAction::Set)`] [`Arg::num_args(1..)`], /// **NOTE:** Implicitly sets [`Arg::action(ArgAction::Set)`] [`Arg::num_args(1..)`],
///
/// </div>
///
/// [`Arg::allow_hyphen_values(true)`], and [`Arg::last(true)`] when set to `true`. /// [`Arg::allow_hyphen_values(true)`], and [`Arg::last(true)`] when set to `true`.
/// ///
/// [`Arg::action(ArgAction::Set)`]: Arg::action() /// [`Arg::action(ArgAction::Set)`]: Arg::action()
@ -1654,10 +1779,18 @@ impl Arg {
/// Value for the argument when not present. /// Value for the argument when not present.
/// ///
/// Like with command-line values, this will be split by [`Arg::value_delimiter`].
///
/// <div class="warning">
///
/// **NOTE:** If the user *does not* use this argument at runtime [`ArgMatches::contains_id`] will /// **NOTE:** If the user *does not* use this argument at runtime [`ArgMatches::contains_id`] will
/// still return `true`. If you wish to determine whether the argument was used at runtime or /// still return `true`. If you wish to determine whether the argument was used at runtime or
/// not, consider [`ArgMatches::value_source`][crate::ArgMatches::value_source]. /// not, consider [`ArgMatches::value_source`][crate::ArgMatches::value_source].
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** This setting is perfectly compatible with [`Arg::default_value_if`] but slightly /// **NOTE:** This setting is perfectly compatible with [`Arg::default_value_if`] but slightly
/// different. `Arg::default_value` *only* takes effect when the user has not provided this arg /// different. `Arg::default_value` *only* takes effect when the user has not provided this arg
/// at runtime. `Arg::default_value_if` however only takes effect when the user has not provided /// at runtime. `Arg::default_value_if` however only takes effect when the user has not provided
@ -1666,7 +1799,7 @@ impl Arg {
/// at runtime, nor were the conditions met for `Arg::default_value_if`, the `Arg::default_value` /// at runtime, nor were the conditions met for `Arg::default_value_if`, the `Arg::default_value`
/// will be applied. /// will be applied.
/// ///
/// Like with command-line values, this will be split by [`Arg::value_delimiter`]. /// </div>
/// ///
/// # Examples /// # Examples
/// ///
@ -1760,12 +1893,16 @@ impl Arg {
/// argument is a common example. By supplying a default, such as `default_missing_value("always")`, /// argument is a common example. By supplying a default, such as `default_missing_value("always")`,
/// the user can quickly just add `--color` to the command line to produce the desired color output. /// the user can quickly just add `--color` to the command line to produce the desired color output.
/// ///
/// Like with command-line values, this will be split by [`Arg::value_delimiter`].
///
/// <div class="warning">
///
/// **NOTE:** using this configuration option requires the use of the /// **NOTE:** using this configuration option requires the use of the
/// [`.num_args(0..N)`][Arg::num_args] and the /// [`.num_args(0..N)`][Arg::num_args] and the
/// [`.require_equals(true)`][Arg::require_equals] configuration option. These are required in /// [`.require_equals(true)`][Arg::require_equals] configuration option. These are required in
/// order to unambiguously determine what, if any, value was supplied for the argument. /// order to unambiguously determine what, if any, value was supplied for the argument.
/// ///
/// Like with command-line values, this will be split by [`Arg::value_delimiter`]. /// </div>
/// ///
/// # Examples /// # Examples
/// ///
@ -2080,8 +2217,12 @@ impl Arg {
/// ///
/// If [`Arg::long_help`] is not specified, this message will be displayed for `--help`. /// If [`Arg::long_help`] is not specified, this message will be displayed for `--help`.
/// ///
/// <div class="warning">
///
/// **NOTE:** Only `Arg::help` is used in completion script generation in order to be concise /// **NOTE:** Only `Arg::help` is used in completion script generation in order to be concise
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to /// Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to
@ -2132,8 +2273,12 @@ impl Arg {
/// ///
/// If [`Arg::help`] is not specified, this message will be displayed for `-h`. /// If [`Arg::help`] is not specified, this message will be displayed for `-h`.
/// ///
/// <div class="warning">
///
/// **NOTE:** Only [`Arg::help`] is used in completion script generation in order to be concise /// **NOTE:** Only [`Arg::help`] is used in completion script generation in order to be concise
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to /// Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to
@ -2201,9 +2346,13 @@ impl Arg {
/// ///
/// To change, see [`Command::next_display_order`][crate::Command::next_display_order]. /// To change, see [`Command::next_display_order`][crate::Command::next_display_order].
/// ///
/// <div class="warning">
///
/// **NOTE:** This setting is ignored for [positional arguments] which are always displayed in /// **NOTE:** This setting is ignored for [positional arguments] which are always displayed in
/// [index] order. /// [index] order.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -2271,9 +2420,13 @@ impl Arg {
/// This can be helpful for arguments with very long or complex help messages. /// 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. /// This can also be helpful for arguments with very long flag names, or many/long value names.
/// ///
/// <div class="warning">
///
/// **NOTE:** To apply this setting to all arguments and subcommands, consider using /// **NOTE:** To apply this setting to all arguments and subcommands, consider using
/// [`crate::Command::next_line_help`] /// [`crate::Command::next_line_help`]
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -2323,8 +2476,12 @@ impl Arg {
/// Do not display the argument in help message. /// Do not display the argument in help message.
/// ///
/// <div class="warning">
///
/// **NOTE:** This does **not** hide the argument from usage strings on error /// **NOTE:** This does **not** hide the argument from usage strings on error
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// Setting `Hidden` will hide the argument when displaying help text /// Setting `Hidden` will hide the argument when displaying help text
@ -2370,11 +2527,15 @@ impl Arg {
/// This is useful for args with many values, or ones which are explained elsewhere in the /// This is useful for args with many values, or ones which are explained elsewhere in the
/// help text. /// help text.
/// ///
/// **NOTE:** Setting this requires [taking values][Arg::num_args]
///
/// To set this for all arguments, see /// To set this for all arguments, see
/// [`Command::hide_possible_values`][crate::Command::hide_possible_values]. /// [`Command::hide_possible_values`][crate::Command::hide_possible_values].
/// ///
/// <div class="warning">
///
/// **NOTE:** Setting this requires [taking values][Arg::num_args]
///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -2403,8 +2564,12 @@ impl Arg {
/// ///
/// This is useful when default behavior of an arg is explained elsewhere in the help text. /// This is useful when default behavior of an arg is explained elsewhere in the help text.
/// ///
/// <div class="warning">
///
/// **NOTE:** Setting this requires [taking values][Arg::num_args] /// **NOTE:** Setting this requires [taking values][Arg::num_args]
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -2494,11 +2659,19 @@ impl Arg {
/// Hides an argument from short help (`-h`). /// Hides an argument from short help (`-h`).
/// ///
/// <div class="warning">
///
/// **NOTE:** This does **not** hide the argument from usage strings on error /// **NOTE:** This does **not** hide the argument from usage strings on error
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** Setting this option will cause next-line-help output style to be used /// **NOTE:** Setting this option will cause next-line-help output style to be used
/// when long help (`--help`) is called. /// when long help (`--help`) is called.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -2578,11 +2751,19 @@ impl Arg {
/// Hides an argument from long help (`--help`). /// Hides an argument from long help (`--help`).
/// ///
/// <div class="warning">
///
/// **NOTE:** This does **not** hide the argument from usage strings on error /// **NOTE:** This does **not** hide the argument from usage strings on error
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** Setting this option will cause next-line-help output style to be used /// **NOTE:** Setting this option will cause next-line-help output style to be used
/// when long help (`--help`) is called. /// when long help (`--help`) is called.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// Setting `hide_long_help(true)` will hide the argument when displaying long help text /// Setting `hide_long_help(true)` will hide the argument when displaying long help text
@ -2749,6 +2930,10 @@ impl Arg {
/// ///
/// If `default` is set to `None`, `default_value` will be removed. /// If `default` is set to `None`, `default_value` will be removed.
/// ///
/// Like with command-line values, this will be split by [`Arg::value_delimiter`].
///
/// <div class="warning">
///
/// **NOTE:** This setting is perfectly compatible with [`Arg::default_value`] but slightly /// **NOTE:** This setting is perfectly compatible with [`Arg::default_value`] but slightly
/// different. `Arg::default_value` *only* takes effect when the user has not provided this arg /// different. `Arg::default_value` *only* takes effect when the user has not provided this arg
/// at runtime. This setting however only takes effect when the user has not provided a value at /// at runtime. This setting however only takes effect when the user has not provided a value at
@ -2756,7 +2941,7 @@ impl Arg {
/// and `Arg::default_value_if`, and the user **did not** provide this arg at runtime, nor were /// and `Arg::default_value_if`, and the user **did not** provide this arg at runtime, nor were
/// the conditions met for `Arg::default_value_if`, the `Arg::default_value` will be applied. /// the conditions met for `Arg::default_value_if`, the `Arg::default_value` will be applied.
/// ///
/// Like with command-line values, this will be split by [`Arg::value_delimiter`]. /// </div>
/// ///
/// # Examples /// # Examples
/// ///
@ -2894,10 +3079,14 @@ impl Arg {
/// ///
/// The method takes a slice of tuples in the `(arg, predicate, default)` format. /// The method takes a slice of tuples in the `(arg, predicate, default)` format.
/// ///
/// Like with command-line values, this will be split by [`Arg::value_delimiter`].
///
/// <div class="warning">
///
/// **NOTE**: The conditions are stored in order and evaluated in the same order. I.e. the first /// **NOTE**: The conditions are stored in order and evaluated in the same order. I.e. the first
/// if multiple conditions are true, the first one found will be applied and the ultimate value. /// if multiple conditions are true, the first one found will be applied and the ultimate value.
/// ///
/// Like with command-line values, this will be split by [`Arg::value_delimiter`]. /// </div>
/// ///
/// # Examples /// # Examples
/// ///
@ -3014,9 +3203,13 @@ impl Arg {
/// Set this arg as [required] as long as the specified argument is not present at runtime. /// Set this arg as [required] as long as the specified argument is not present at runtime.
/// ///
/// **Pro Tip:** Using `Arg::required_unless_present` implies [`Arg::required`] and is therefore not /// <div class="warning">
///
/// **TIP:** Using `Arg::required_unless_present` implies [`Arg::required`] and is therefore not
/// mandatory to also set. /// mandatory to also set.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -3084,9 +3277,13 @@ impl Arg {
/// * supplies the `self` arg. /// * supplies the `self` arg.
/// * supplies *all* of the `names` arguments. /// * supplies *all* of the `names` arguments.
/// ///
/// <div class="warning">
///
/// **NOTE:** If you wish for this argument to only be required unless *any of* these args are /// **NOTE:** If you wish for this argument to only be required unless *any of* these args are
/// present see [`Arg::required_unless_present_any`] /// present see [`Arg::required_unless_present_any`]
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -3163,9 +3360,13 @@ impl Arg {
/// * supplies the `self` arg. /// * supplies the `self` arg.
/// * supplies *one or more* of the `unless` arguments. /// * supplies *one or more* of the `unless` arguments.
/// ///
/// <div class="warning">
///
/// **NOTE:** If you wish for this argument to be required unless *all of* these args are /// **NOTE:** If you wish for this argument to be required unless *all of* these args are
/// present see [`Arg::required_unless_present_all`] /// present see [`Arg::required_unless_present_all`]
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -3653,19 +3854,39 @@ impl Arg {
/// This argument is mutually exclusive with the specified argument. /// This argument is mutually exclusive with the specified argument.
/// ///
/// <div class="warning">
///
/// **NOTE:** Conflicting rules take precedence over being required by default. Conflict rules /// **NOTE:** Conflicting rules take precedence over being required by default. Conflict rules
/// only need to be set for one of the two arguments, they do not need to be set for each. /// only need to be set for one of the two arguments, they do not need to be set for each.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** Defining a conflict is two-way, but does *not* need to defined for both arguments /// **NOTE:** Defining a conflict is two-way, but does *not* need to defined for both arguments
/// (i.e. if A conflicts with B, defining `A.conflicts_with(B)` is sufficient. You do not /// (i.e. if A conflicts with B, defining `A.conflicts_with(B)` is sufficient. You do not
/// need to also do `B.conflicts_with(A)`) /// need to also do `B.conflicts_with(A)`)
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** [`Arg::conflicts_with_all(names)`] allows specifying an argument which conflicts with more than one argument. /// **NOTE:** [`Arg::conflicts_with_all(names)`] allows specifying an argument which conflicts with more than one argument.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument. /// **NOTE** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** All arguments implicitly conflict with themselves. /// **NOTE:** All arguments implicitly conflict with themselves.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -3713,15 +3934,27 @@ impl Arg {
/// ///
/// See [`Arg::conflicts_with`]. /// See [`Arg::conflicts_with`].
/// ///
/// <div class="warning">
///
/// **NOTE:** Conflicting rules take precedence over being required by default. Conflict rules /// **NOTE:** Conflicting rules take precedence over being required by default. Conflict rules
/// only need to be set for one of the two arguments, they do not need to be set for each. /// only need to be set for one of the two arguments, they do not need to be set for each.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** Defining a conflict is two-way, but does *not* need to defined for both arguments /// **NOTE:** Defining a conflict is two-way, but does *not* need to defined for both arguments
/// (i.e. if A conflicts with B, defining `A.conflicts_with(B)` is sufficient. You do not need /// (i.e. if A conflicts with B, defining `A.conflicts_with(B)` is sufficient. You do not need
/// need to also do `B.conflicts_with(A)`) /// need to also do `B.conflicts_with(A)`)
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument. /// **NOTE:** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -3767,11 +4000,19 @@ impl Arg {
/// will override each other in POSIX style (whichever argument was specified at runtime /// will override each other in POSIX style (whichever argument was specified at runtime
/// **last** "wins") /// **last** "wins")
/// ///
/// <div class="warning">
///
/// **NOTE:** When an argument is overridden it is essentially as if it never was used, any /// **NOTE:** When an argument is overridden it is essentially as if it never was used, any
/// conflicts, requirements, etc. are evaluated **after** all "overrides" have been removed /// conflicts, requirements, etc. are evaluated **after** all "overrides" have been removed
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** Overriding an argument implies they [conflict][Arg::conflicts_with`]. /// **NOTE:** Overriding an argument implies they [conflict][Arg::conflicts_with`].
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -3807,11 +4048,19 @@ impl Arg {
/// i.e. this argument and the following argument will override each other in POSIX style /// i.e. this argument and the following argument will override each other in POSIX style
/// (whichever argument was specified at runtime **last** "wins") /// (whichever argument was specified at runtime **last** "wins")
/// ///
/// <div class="warning">
///
/// **NOTE:** When an argument is overridden it is essentially as if it never was used, any /// **NOTE:** When an argument is overridden it is essentially as if it never was used, any
/// conflicts, requirements, etc. are evaluated **after** all "overrides" have been removed /// conflicts, requirements, etc. are evaluated **after** all "overrides" have been removed
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** Overriding an argument implies they [conflict][Arg::conflicts_with_all`]. /// **NOTE:** Overriding an argument implies they [conflict][Arg::conflicts_with_all`].
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust

24
clap_builder/src/builder/arg_group.rs
View file

@ -289,14 +289,22 @@ impl ArgGroup {
/// This is unless conflicting with another argument. A required group will be displayed in /// This is unless conflicting with another argument. A required group will be displayed in
/// the usage string of the application in the format `<arg|arg2|arg3>`. /// the usage string of the application in the format `<arg|arg2|arg3>`.
/// ///
/// <div class="warning">
///
/// **NOTE:** This setting only applies to the current [`Command`] / [`Subcommand`]s, and not /// **NOTE:** This setting only applies to the current [`Command`] / [`Subcommand`]s, and not
/// globally. /// globally.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** By default, [`ArgGroup::multiple`] is set to `false` which when combined with /// **NOTE:** By default, [`ArgGroup::multiple`] is set to `false` which when combined with
/// `ArgGroup::required(true)` states, "One and *only one* arg must be used from this group. /// `ArgGroup::required(true)` states, "One and *only one* arg must be used from this group.
/// Use of more than one arg is an error." Vice setting `ArgGroup::multiple(true)` which /// Use of more than one arg is an error." Vice setting `ArgGroup::multiple(true)` which
/// states, '*At least* one arg from this group must be used. Using multiple is OK." /// states, '*At least* one arg from this group must be used. Using multiple is OK."
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -335,8 +343,12 @@ impl ArgGroup {
/// [argument requirement rules], you can name other arguments or groups that must be present /// [argument requirement rules], you can name other arguments or groups that must be present
/// when any one of the arguments from this group is used. /// when any one of the arguments from this group is used.
/// ///
/// <div class="warning">
///
/// **NOTE:** The name provided may be an argument or group name /// **NOTE:** The name provided may be an argument or group name
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -380,8 +392,12 @@ impl ArgGroup {
/// [argument requirement rules], you can name other arguments or groups that must be present /// [argument requirement rules], you can name other arguments or groups that must be present
/// when one of the arguments from this group is used. /// when one of the arguments from this group is used.
/// ///
/// <div class="warning">
///
/// **NOTE:** The names provided may be an argument or group name /// **NOTE:** The names provided may be an argument or group name
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -426,8 +442,12 @@ impl ArgGroup {
/// other arguments or groups that must *not* be present when one of the arguments from this /// other arguments or groups that must *not* be present when one of the arguments from this
/// group are used. /// group are used.
/// ///
/// <div class="warning">
///
/// **NOTE:** The name provided may be an argument, or group name /// **NOTE:** The name provided may be an argument, or group name
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -468,8 +488,12 @@ impl ArgGroup {
/// Exclusion rules function just like [argument exclusion rules], you can name other arguments /// Exclusion rules function just like [argument exclusion rules], you can name other arguments
/// or groups that must *not* be present when one of the arguments from this group are used. /// or groups that must *not* be present when one of the arguments from this group are used.
/// ///
/// <div class="warning">
///
/// **NOTE:** The names provided may be an argument, or group name /// **NOTE:** The names provided may be an argument, or group name
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust

297
clap_builder/src/builder/command.rs
View file

@ -640,11 +640,15 @@ impl Command {
/// Parse [`env::args_os`], returning a [`clap::Result`] on failure. /// Parse [`env::args_os`], returning a [`clap::Result`] on failure.
/// ///
/// <div class="warning">
///
/// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are /// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are
/// used. It will return a [`clap::Error`], where the [`kind`] is a /// used. It will return a [`clap::Error`], where the [`kind`] is a
/// [`ErrorKind::DisplayHelp`] or [`ErrorKind::DisplayVersion`] respectively. You must call /// [`ErrorKind::DisplayHelp`] or [`ErrorKind::DisplayVersion`] respectively. You must call
/// [`Error::exit`] or perform a [`std::process::exit`]. /// [`Error::exit`] or perform a [`std::process::exit`].
/// ///
/// </div>
///
/// # Panics /// # Panics
/// ///
/// If contradictory arguments or settings exist (debug builds). /// If contradictory arguments or settings exist (debug builds).
@ -675,9 +679,13 @@ impl Command {
/// Parse the specified arguments, [exiting][Error::exit] on failure. /// Parse the specified arguments, [exiting][Error::exit] on failure.
/// ///
/// <div class="warning">
///
/// **NOTE:** The first argument will be parsed as the binary name unless /// **NOTE:** The first argument will be parsed as the binary name unless
/// [`Command::no_binary_name`] is used. /// [`Command::no_binary_name`] is used.
/// ///
/// </div>
///
/// # Panics /// # Panics
/// ///
/// If contradictory arguments or settings exist (debug builds). /// If contradictory arguments or settings exist (debug builds).
@ -709,14 +717,22 @@ impl Command {
/// Parse the specified arguments, returning a [`clap::Result`] on failure. /// Parse the specified arguments, returning a [`clap::Result`] on failure.
/// ///
/// <div class="warning">
///
/// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are /// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are
/// used. It will return a [`clap::Error`], where the [`kind`] is a [`ErrorKind::DisplayHelp`] /// used. It will return a [`clap::Error`], where the [`kind`] is a [`ErrorKind::DisplayHelp`]
/// or [`ErrorKind::DisplayVersion`] respectively. You must call [`Error::exit`] or /// or [`ErrorKind::DisplayVersion`] respectively. You must call [`Error::exit`] or
/// perform a [`std::process::exit`] yourself. /// perform a [`std::process::exit`] yourself.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** The first argument will be parsed as the binary name unless /// **NOTE:** The first argument will be parsed as the binary name unless
/// [`Command::no_binary_name`] is used. /// [`Command::no_binary_name`] is used.
/// ///
/// </div>
///
/// # Panics /// # Panics
/// ///
/// If contradictory arguments or settings exist (debug builds). /// If contradictory arguments or settings exist (debug builds).
@ -755,14 +771,22 @@ impl Command {
/// ///
/// Like [`Command::try_get_matches_from`] but doesn't consume the `Command`. /// Like [`Command::try_get_matches_from`] but doesn't consume the `Command`.
/// ///
/// <div class="warning">
///
/// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are /// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are
/// used. It will return a [`clap::Error`], where the [`kind`] is a [`ErrorKind::DisplayHelp`] /// used. It will return a [`clap::Error`], where the [`kind`] is a [`ErrorKind::DisplayHelp`]
/// or [`ErrorKind::DisplayVersion`] respectively. You must call [`Error::exit`] or /// or [`ErrorKind::DisplayVersion`] respectively. You must call [`Error::exit`] or
/// perform a [`std::process::exit`] yourself. /// perform a [`std::process::exit`] yourself.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** The first argument will be parsed as the binary name unless /// **NOTE:** The first argument will be parsed as the binary name unless
/// [`Command::no_binary_name`] is used. /// [`Command::no_binary_name`] is used.
/// ///
/// </div>
///
/// # Panics /// # Panics
/// ///
/// If contradictory arguments or settings exist (debug builds). /// If contradictory arguments or settings exist (debug builds).
@ -1087,8 +1111,12 @@ impl Command {
/// Try not to fail on parse errors, like missing option values. /// Try not to fail on parse errors, like missing option values.
/// ///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands. /// **NOTE:** This choice is propagated to all child subcommands.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -1125,8 +1153,12 @@ impl Command {
/// This is the equivalent to saying the `foo` arg using [`Arg::overrides_with("foo")`] for all /// This is the equivalent to saying the `foo` arg using [`Arg::overrides_with("foo")`] for all
/// defined arguments. /// defined arguments.
/// ///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands. /// **NOTE:** This choice is propagated to all child subcommands.
/// ///
/// </div>
///
/// [`Arg::overrides_with("foo")`]: crate::Arg::overrides_with() /// [`Arg::overrides_with("foo")`]: crate::Arg::overrides_with()
#[inline] #[inline]
pub fn args_override_self(self, yes: bool) -> Self { pub fn args_override_self(self, yes: bool) -> Self {
@ -1140,12 +1172,20 @@ impl Command {
/// Disables the automatic delimiting of values after `--` or when [`Arg::trailing_var_arg`] /// Disables the automatic delimiting of values after `--` or when [`Arg::trailing_var_arg`]
/// was used. /// was used.
/// ///
/// <div class="warning">
///
/// **NOTE:** The same thing can be done manually by setting the final positional argument to /// **NOTE:** The same thing can be done manually by setting the final positional argument to
/// [`Arg::value_delimiter(None)`]. Using this setting is safer, because it's easier to locate /// [`Arg::value_delimiter(None)`]. Using this setting is safer, because it's easier to locate
/// when making changes. /// when making changes.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands. /// **NOTE:** This choice is propagated to all child subcommands.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```no_run /// ```no_run
@ -1170,10 +1210,18 @@ impl Command {
/// ///
/// To customize how the output is styled, see [`Command::styles`]. /// To customize how the output is styled, see [`Command::styles`].
/// ///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands. /// **NOTE:** This choice is propagated to all child subcommands.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** Default behaviour is [`ColorChoice::Auto`]. /// **NOTE:** Default behaviour is [`ColorChoice::Auto`].
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```no_run /// ```no_run
@ -1201,10 +1249,18 @@ impl Command {
/// Sets the [`Styles`] for terminal output /// Sets the [`Styles`] for terminal output
/// ///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands. /// **NOTE:** This choice is propagated to all child subcommands.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** Default behaviour is [`Styles::default`]. /// **NOTE:** Default behaviour is [`Styles::default`].
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```no_run /// ```no_run
@ -1237,10 +1293,18 @@ impl Command {
/// **`unstable-v5` feature**: Defaults to unbound, being subject to /// **`unstable-v5` feature**: Defaults to unbound, being subject to
/// [`Command::max_term_width`]. /// [`Command::max_term_width`].
/// ///
/// <div class="warning">
///
/// **NOTE:** This setting applies globally and *not* on a per-command basis. /// **NOTE:** This setting applies globally and *not* on a per-command basis.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** This requires the `wrap_help` feature /// **NOTE:** This requires the `wrap_help` feature
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -1267,10 +1331,18 @@ impl Command {
/// ///
/// **`unstable-v5` feature**: Defaults to 100. /// **`unstable-v5` feature**: Defaults to 100.
/// ///
/// <div class="warning">
///
/// **NOTE:** This setting applies globally and *not* on a per-command basis. /// **NOTE:** This setting applies globally and *not* on a per-command basis.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** This requires the `wrap_help` feature /// **NOTE:** This requires the `wrap_help` feature
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -1345,8 +1417,12 @@ impl Command {
/// ///
/// Defaults to `false`; subcommands have independent version strings from their parents. /// Defaults to `false`; subcommands have independent version strings from their parents.
/// ///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands. /// **NOTE:** This choice is propagated to all child subcommands.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```no_run /// ```no_run
@ -1373,8 +1449,12 @@ impl Command {
/// Places the help string for all arguments and subcommands on the line after them. /// Places the help string for all arguments and subcommands on the line after them.
/// ///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands. /// **NOTE:** This choice is propagated to all child subcommands.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```no_run /// ```no_run
@ -1395,8 +1475,12 @@ impl Command {
/// Disables `-h` and `--help` flag. /// Disables `-h` and `--help` flag.
/// ///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands. /// **NOTE:** This choice is propagated to all child subcommands.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -1450,8 +1534,12 @@ impl Command {
/// Disables the `help` [`subcommand`]. /// Disables the `help` [`subcommand`].
/// ///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands. /// **NOTE:** This choice is propagated to all child subcommands.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -1481,8 +1569,12 @@ impl Command {
/// Disables colorized help messages. /// Disables colorized help messages.
/// ///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands. /// **NOTE:** This choice is propagated to all child subcommands.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```no_run /// ```no_run
@ -1503,11 +1595,19 @@ impl Command {
/// Panic if help descriptions are omitted. /// Panic if help descriptions are omitted.
/// ///
/// <div class="warning">
///
/// **NOTE:** When deriving [`Parser`][crate::Parser], you could instead check this at /// **NOTE:** When deriving [`Parser`][crate::Parser], you could instead check this at
/// compile-time with `#![deny(missing_docs)]` /// compile-time with `#![deny(missing_docs)]`
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands. /// **NOTE:** This choice is propagated to all child subcommands.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -1563,7 +1663,11 @@ impl Command {
/// To set this per argument, see /// To set this per argument, see
/// [`Arg::hide_possible_values`][crate::Arg::hide_possible_values]. /// [`Arg::hide_possible_values`][crate::Arg::hide_possible_values].
/// ///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands. /// **NOTE:** This choice is propagated to all child subcommands.
///
/// </div>
#[inline] #[inline]
pub fn hide_possible_values(self, yes: bool) -> Self { pub fn hide_possible_values(self, yes: bool) -> Self {
if yes { if yes {
@ -1578,12 +1682,20 @@ impl Command {
/// For example, to match an argument named `--test`, one could use `--t`, `--te`, `--tes`, and /// For example, to match an argument named `--test`, one could use `--t`, `--te`, `--tes`, and
/// `--test`. /// `--test`.
/// ///
/// <div class="warning">
///
/// **NOTE:** The match *must not* be ambiguous at all in order to succeed. i.e. to match /// **NOTE:** The match *must not* be ambiguous at all in order to succeed. i.e. to match
/// `--te` to `--test` there could not also be another argument or alias `--temp` because both /// `--te` to `--test` there could not also be another argument or alias `--temp` because both
/// start with `--te` /// start with `--te`
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands. /// **NOTE:** This choice is propagated to all child subcommands.
/// ///
/// </div>
///
/// [aliases]: crate::Command::aliases() /// [aliases]: crate::Command::aliases()
#[inline] #[inline]
pub fn infer_long_args(self, yes: bool) -> Self { pub fn infer_long_args(self, yes: bool) -> Self {
@ -1599,17 +1711,29 @@ impl Command {
/// For example, to match a subcommand named `test`, one could use `t`, `te`, `tes`, and /// For example, to match a subcommand named `test`, one could use `t`, `te`, `tes`, and
/// `test`. /// `test`.
/// ///
/// <div class="warning">
///
/// **NOTE:** The match *must not* be ambiguous at all in order to succeed. i.e. to match `te` /// **NOTE:** The match *must not* be ambiguous at all in order to succeed. i.e. to match `te`
/// to `test` there could not also be a subcommand or alias `temp` because both start with `te` /// to `test` there could not also be a subcommand or alias `temp` because both start with `te`
/// ///
/// **CAUTION:** This setting can interfere with [positional/free arguments], take care when /// </div>
///
/// <div class="warning">
///
/// **WARNING:** This setting can interfere with [positional/free arguments], take care when
/// designing CLIs which allow inferred subcommands and have potential positional/free /// 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 /// arguments whose values could start with the same characters as subcommands. If this is the
/// case, it's recommended to use settings such as [`Command::args_conflicts_with_subcommands`] in /// case, it's recommended to use settings such as [`Command::args_conflicts_with_subcommands`] in
/// conjunction with this setting. /// conjunction with this setting.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands. /// **NOTE:** This choice is propagated to all child subcommands.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```no_run /// ```no_run
@ -1664,13 +1788,21 @@ impl Command {
/// This should only be used when absolutely necessary, such as when the binary name for your /// This should only be used when absolutely necessary, such as when the binary name for your
/// application is misleading, or perhaps *not* how the user should invoke your program. /// application is misleading, or perhaps *not* how the user should invoke your program.
/// ///
/// **Pro-tip:** When building things such as third party `cargo` /// <div class="warning">
///
/// **TIP:** When building things such as third party `cargo`
/// subcommands, this setting **should** be used! /// subcommands, this setting **should** be used!
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** This *does not* change or set the name of the binary file on /// **NOTE:** This *does not* change or set the name of the binary file on
/// disk. It only changes what clap thinks the name is for the purposes of /// disk. It only changes what clap thinks the name is for the purposes of
/// error or help messages. /// error or help messages.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -1705,13 +1837,21 @@ impl Command {
/// Sets the author(s) for the help message. /// Sets the author(s) for the help message.
/// ///
/// **Pro-tip:** Use `clap`s convenience macro [`crate_authors!`] to /// <div class="warning">
///
/// **TIP:** Use `clap`s convenience macro [`crate_authors!`] to
/// automatically set your application's author(s) to the same thing as your /// automatically set your application's author(s) to the same thing as your
/// crate at compile time. /// crate at compile time.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** A custom [`help_template`][Command::help_template] is needed for author to show /// **NOTE:** A custom [`help_template`][Command::help_template] is needed for author to show
/// up. /// up.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -1731,9 +1871,6 @@ impl Command {
/// ///
/// If [`Command::long_about`] is not specified, this message will be displayed for `--help`. /// If [`Command::long_about`] is not specified, this message will be displayed for `--help`.
/// ///
/// **NOTE:** Only `Command::about` (short format) is used in completion
/// script generation in order to be concise.
///
/// See also [`crate_description!`](crate::crate_description!). /// See also [`crate_description!`](crate::crate_description!).
/// ///
/// # Examples /// # Examples
@ -1756,9 +1893,13 @@ impl Command {
/// If not set, [`Command::about`] will be used for long help in addition to short help /// If not set, [`Command::about`] will be used for long help in addition to short help
/// (`-h`). /// (`-h`).
/// ///
/// <div class="warning">
///
/// **NOTE:** Only [`Command::about`] (short format) is used in completion /// **NOTE:** Only [`Command::about`] (short format) is used in completion
/// script generation in order to be concise. /// script generation in order to be concise.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -1872,10 +2013,14 @@ impl Command {
/// ///
/// If [`Command::long_version`] is not specified, this message will be displayed for `--version`. /// If [`Command::long_version`] is not specified, this message will be displayed for `--version`.
/// ///
/// **Pro-tip:** Use `clap`s convenience macro [`crate_version!`] to /// <div class="warning">
///
/// **TIP:** Use `clap`s convenience macro [`crate_version!`] to
/// automatically set your application's version to the same thing as your /// automatically set your application's version to the same thing as your
/// crate at compile time. /// crate at compile time.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -1895,10 +2040,14 @@ impl Command {
/// ///
/// If [`Command::version`] is not specified, this message will be displayed for `-V`. /// If [`Command::version`] is not specified, this message will be displayed for `-V`.
/// ///
/// **Pro-tip:** Use `clap`s convenience macro [`crate_version!`] to /// <div class="warning">
///
/// **TIP:** Use `clap`s convenience macro [`crate_version!`] to
/// automatically set your application's version to the same thing as your /// automatically set your application's version to the same thing as your
/// crate at compile time. /// crate at compile time.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -1921,10 +2070,16 @@ impl Command {
/// Overrides the `clap` generated usage string for help and error messages. /// Overrides the `clap` generated usage string for help and error messages.
/// ///
/// <div class="warning">
///
/// **NOTE:** Using this setting disables `clap`s "context-aware" usage /// **NOTE:** Using this setting disables `clap`s "context-aware" usage
/// strings. After this setting is set, this will be *the only* usage string /// strings. After this setting is set, this will be *the only* usage string
/// displayed to the user! /// displayed to the user!
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** Multiple usage lines may be present in the usage argument, but /// **NOTE:** Multiple usage lines may be present in the usage argument, but
/// some rules need to be followed to ensure the usage lines are formatted /// some rules need to be followed to ensure the usage lines are formatted
/// correctly by the default help formatter: /// correctly by the default help formatter:
@ -1933,6 +2088,8 @@ impl Command {
/// - Indent all subsequent usage lines with seven spaces. /// - Indent all subsequent usage lines with seven spaces.
/// - The last line must not end with a newline. /// - The last line must not end with a newline.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -1968,11 +2125,15 @@ impl Command {
/// ///
/// This should only be used when the auto-generated message does not suffice. /// This should only be used when the auto-generated message does not suffice.
/// ///
/// <div class="warning">
///
/// **NOTE:** This **only** replaces the help message for the current /// **NOTE:** This **only** replaces the help message for the current
/// command, meaning if you are using subcommands, those help messages will /// command, meaning if you are using subcommands, those help messages will
/// still be auto-generated unless you specify a [`Command::override_help`] for /// still be auto-generated unless you specify a [`Command::override_help`] for
/// them as well. /// them as well.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -2004,9 +2165,6 @@ impl Command {
/// Sets the help template to be used, overriding the default format. /// Sets the help template to be used, overriding the default format.
/// ///
/// **NOTE:** The template system is by design very simple. Therefore, the
/// tags have to be written in the lowercase and without spacing.
///
/// Tags are given inside curly brackets. /// Tags are given inside curly brackets.
/// ///
/// Valid tags are: /// Valid tags are:
@ -2149,8 +2307,12 @@ impl Command {
/// Exit gracefully if no arguments are present (e.g. `$ myprog`). /// Exit gracefully if no arguments are present (e.g. `$ myprog`).
/// ///
/// <div class="warning">
///
/// **NOTE:** [`subcommands`] count as arguments /// **NOTE:** [`subcommands`] count as arguments
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -2369,8 +2531,12 @@ impl Command {
/// ///
/// Allows the subcommand to be used as if it were an [`Arg::long`]. /// Allows the subcommand to be used as if it were an [`Arg::long`].
/// ///
/// <div class="warning">
///
/// **NOTE:** Any leading `-` characters will be stripped. /// **NOTE:** Any leading `-` characters will be stripped.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// To set `long_flag` use a word containing valid UTF-8 codepoints. If you supply a double leading /// To set `long_flag` use a word containing valid UTF-8 codepoints. If you supply a double leading
@ -2410,14 +2576,22 @@ impl Command {
/// alias. This is more efficient and easier than creating multiple hidden subcommands as one /// alias. This is more efficient and easier than creating multiple hidden subcommands as one
/// only needs to check for the existence of this command, and not all aliased variants. /// only needs to check for the existence of this command, and not all aliased variants.
/// ///
/// <div class="warning">
///
/// **NOTE:** Aliases defined with this method are *hidden* from the help /// **NOTE:** Aliases defined with this method are *hidden* from the help
/// message. If you're looking for aliases that will be displayed in the help /// message. If you're looking for aliases that will be displayed in the help
/// message, see [`Command::visible_alias`]. /// message, see [`Command::visible_alias`].
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** When using aliases and checking for the existence of a /// **NOTE:** When using aliases and checking for the existence of a
/// particular subcommand within an [`ArgMatches`] struct, one only needs to /// particular subcommand within an [`ArgMatches`] struct, one only needs to
/// search for the original name and not all aliases. /// search for the original name and not all aliases.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -2501,14 +2675,22 @@ impl Command {
/// given aliases. This is more efficient, and easier than creating multiple hidden subcommands /// given aliases. This is more efficient, and easier than creating multiple hidden subcommands
/// as one only needs to check for the existence of this command and not all aliased variants. /// as one only needs to check for the existence of this command and not all aliased variants.
/// ///
/// <div class="warning">
///
/// **NOTE:** Aliases defined with this method are *hidden* from the help /// **NOTE:** Aliases defined with this method are *hidden* from the help
/// message. If looking for aliases that will be displayed in the help /// message. If looking for aliases that will be displayed in the help
/// message, see [`Command::visible_aliases`]. /// message, see [`Command::visible_aliases`].
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** When using aliases and checking for the existence of a /// **NOTE:** When using aliases and checking for the existence of a
/// particular subcommand within an [`ArgMatches`] struct, one only needs to /// particular subcommand within an [`ArgMatches`] struct, one only needs to
/// search for the original name and not all aliases. /// search for the original name and not all aliases.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -2595,15 +2777,23 @@ impl Command {
/// than creating hidden subcommands as one only needs to check for /// than creating hidden subcommands as one only needs to check for
/// the existence of this command and not all aliased variants. /// the existence of this command and not all aliased variants.
/// ///
/// <div class="warning">
///
/// **NOTE:** The alias defined with this method is *visible* from the help /// **NOTE:** The alias defined with this method is *visible* from the help
/// message and displayed as if it were just another regular subcommand. If /// message and displayed as if it were just another regular subcommand. If
/// looking for an alias that will not be displayed in the help message, see /// looking for an alias that will not be displayed in the help message, see
/// [`Command::alias`]. /// [`Command::alias`].
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** When using aliases and checking for the existence of a /// **NOTE:** When using aliases and checking for the existence of a
/// particular subcommand within an [`ArgMatches`] struct, one only needs to /// particular subcommand within an [`ArgMatches`] struct, one only needs to
/// search for the original name and not all aliases. /// search for the original name and not all aliases.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -2694,15 +2884,23 @@ impl Command {
/// than creating multiple hidden subcommands as one only needs to check for /// than creating multiple hidden subcommands as one only needs to check for
/// the existence of this command and not all aliased variants. /// the existence of this command and not all aliased variants.
/// ///
/// <div class="warning">
///
/// **NOTE:** The alias defined with this method is *visible* from the help /// **NOTE:** The alias defined with this method is *visible* from the help
/// message and displayed as if it were just another regular subcommand. If /// message and displayed as if it were just another regular subcommand. If
/// looking for an alias that will not be displayed in the help message, see /// looking for an alias that will not be displayed in the help message, see
/// [`Command::alias`]. /// [`Command::alias`].
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** When using aliases, and checking for the existence of a /// **NOTE:** When using aliases, and checking for the existence of a
/// particular subcommand within an [`ArgMatches`] struct, one only needs to /// particular subcommand within an [`ArgMatches`] struct, one only needs to
/// search for the original name and not all aliases. /// search for the original name and not all aliases.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -2881,14 +3079,22 @@ impl Command {
/// ///
/// Arguments will be stored in the `""` argument in the [`ArgMatches`] /// Arguments will be stored in the `""` argument in the [`ArgMatches`]
/// ///
/// <div class="warning">
///
/// **NOTE:** Use this setting with caution, /// **NOTE:** Use this setting with caution,
/// as a truly unexpected argument (i.e. one that is *NOT* an external subcommand) /// as a truly unexpected argument (i.e. one that is *NOT* an external subcommand)
/// will **not** cause an error and instead be treated as a potential subcommand. /// will **not** cause an error and instead be treated as a potential subcommand.
/// One should check for such cases manually and inform the user appropriately. /// One should check for such cases manually and inform the user appropriately.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** A built-in subcommand will be parsed as an external subcommand when escaped with /// **NOTE:** A built-in subcommand will be parsed as an external subcommand when escaped with
/// `--`. /// `--`.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -2930,8 +3136,12 @@ impl Command {
/// The default parser is for `OsString`. This can be used to switch it to `String` or another /// The default parser is for `OsString`. This can be used to switch it to `String` or another
/// type. /// type.
/// ///
/// <div class="warning">
///
/// **NOTE:** Setting this requires [`Command::allow_external_subcommands`] /// **NOTE:** Setting this requires [`Command::allow_external_subcommands`]
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -3090,8 +3300,12 @@ impl Command {
/// using this setting would allow you to set those arguments to [`Arg::required(true)`] /// using this setting would allow you to set those arguments to [`Arg::required(true)`]
/// and yet receive no error so long as the user uses a valid subcommand instead. /// and yet receive no error so long as the user uses a valid subcommand instead.
/// ///
/// <div class="warning">
///
/// **NOTE:** This defaults to false (using subcommand does *not* negate requirements) /// **NOTE:** This defaults to false (using subcommand does *not* negate requirements)
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// This first example shows that it is an error to not use a required argument /// This first example shows that it is an error to not use a required argument
@ -3171,15 +3385,27 @@ impl Command {
/// [`allow_external_subcommands`][Command::allow_external_subcommands] if you want to specifically /// [`allow_external_subcommands`][Command::allow_external_subcommands] if you want to specifically
/// get the unrecognized binary name. /// get the unrecognized binary name.
/// ///
/// <div class="warning">
///
/// **NOTE:** Multicall can't be used with [`no_binary_name`] since they interpret /// **NOTE:** Multicall can't be used with [`no_binary_name`] since they interpret
/// the command name in incompatible ways. /// the command name in incompatible ways.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** The multicall command cannot have arguments. /// **NOTE:** The multicall command cannot have arguments.
/// ///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** Applets are slightly semantically different from subcommands, /// **NOTE:** Applets are slightly semantically different from subcommands,
/// so it's recommended to use [`Command::subcommand_help_heading`] and /// so it's recommended to use [`Command::subcommand_help_heading`] and
/// [`Command::subcommand_value_name`] to change the descriptive text as above. /// [`Command::subcommand_value_name`] to change the descriptive text as above.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// `hostname` is an example of a multicall executable. /// `hostname` is an example of a multicall executable.
@ -3744,15 +3970,15 @@ impl Command {
} }
} }
// Get a unique list of all arguments of all commands and continuous subcommands the given argument conflicts with. /// Get a unique list of all arguments of all commands and continuous subcommands the given argument conflicts with.
// ///
// This behavior follows the propagation rules of global arguments. /// This behavior follows the propagation rules of global arguments.
// It is useful for finding conflicts for arguments declared as global. /// It is useful for finding conflicts for arguments declared as global.
// ///
// ### Panics /// ### Panics
// ///
// If the given arg contains a conflict with an argument that is unknown to /// If the given arg contains a conflict with an argument that is unknown to
// this `Command`. /// this `Command`.
fn get_global_arg_conflicts_with(&self, arg: &Arg) -> Vec<&Arg> // FIXME: This could probably have been an iterator fn get_global_arg_conflicts_with(&self, arg: &Arg) -> Vec<&Arg> // FIXME: This could probably have been an iterator
{ {
arg.blacklist arg.blacklist
@ -3774,19 +4000,24 @@ impl Command {
.collect() .collect()
} }
// Get a list of subcommands which contain the provided Argument /// Get a list of subcommands which contain the provided Argument
// ///
// This command will only include subcommands in its list for which the subcommands /// This command will only include subcommands in its list for which the subcommands
// parent also contains the Argument. /// parent also contains the Argument.
// ///
// This search follows the propagation rules of global arguments. /// This search follows the propagation rules of global arguments.
// It is useful to finding subcommands, that have inherited a global argument. /// It is useful to finding subcommands, that have inherited a global argument.
// ///
// **NOTE:** In this case only Sucommand_1 will be included /// <div class="warning">
// Subcommand_1 (contains Arg) ///
// Subcommand_1.1 (doesn't contain Arg) /// **NOTE:** In this case only `Sucommand_1` will be included
// Subcommand_1.1.1 (contains Arg) /// ```text
// /// Subcommand_1 (contains Arg)
/// Subcommand_1.1 (doesn't contain Arg)
/// Subcommand_1.1.1 (contains Arg)
/// ```
///
/// </div>
fn get_subcommands_containing(&self, arg: &Arg) -> Vec<&Self> { fn get_subcommands_containing(&self, arg: &Arg) -> Vec<&Self> {
let mut vec = Vec::new(); let mut vec = Vec::new();
for idx in 0..self.subcommands.len() { for idx in 0..self.subcommands.len() {

4
clap_builder/src/builder/os_str.rs
View file

@ -2,8 +2,12 @@ use crate::builder::Str;
/// A UTF-8-encoded fixed string /// A UTF-8-encoded fixed string
/// ///
/// <div class="warning">
///
/// **NOTE:** To support dynamic values (i.e. `OsString`), enable the `string` /// **NOTE:** To support dynamic values (i.e. `OsString`), enable the `string`
/// feature /// feature
///
/// </div>
#[derive(Default, Clone, Eq, PartialEq, PartialOrd, Ord, Hash)] #[derive(Default, Clone, Eq, PartialEq, PartialOrd, Ord, Hash)]
pub struct OsStr { pub struct OsStr {
name: Inner, name: Inner,

8
clap_builder/src/builder/possible_value.rs
View file

@ -9,10 +9,14 @@ use crate::util::eq_ignore_case;
/// ///
/// See also [`PossibleValuesParser`][crate::builder::PossibleValuesParser] /// See also [`PossibleValuesParser`][crate::builder::PossibleValuesParser]
/// ///
/// <div class="warning">
///
/// **NOTE:** Most likely you can use strings, rather than `PossibleValue` as it is only required /// **NOTE:** Most likely you can use strings, rather than `PossibleValue` as it is only required
/// to [hide] single values from help messages and shell completions or to attach [help] to /// to [hide] single values from help messages and shell completions or to attach [help] to
/// possible values. /// possible values.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust
@ -45,9 +49,13 @@ impl PossibleValue {
/// ///
/// The name will be used to decide whether this value was provided by the user to an argument. /// The name will be used to decide whether this value was provided by the user to an argument.
/// ///
/// <div class="warning">
///
/// **NOTE:** In case it is not [hidden] it will also be shown in help messages for arguments /// **NOTE:** In case it is not [hidden] it will also be shown in help messages for arguments
/// that use it as a [possible value] and have not hidden them through [`Arg::hide_possible_values(true)`]. /// that use it as a [possible value] and have not hidden them through [`Arg::hide_possible_values(true)`].
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust

4
clap_builder/src/builder/str.rs
View file

@ -1,7 +1,11 @@
/// A UTF-8-encoded fixed string /// A UTF-8-encoded fixed string
/// ///
/// <div class="warning">
///
/// **NOTE:** To support dynamic values (i.e. `String`), enable the `string` /// **NOTE:** To support dynamic values (i.e. `String`), enable the `string`
/// feature /// feature
///
/// </div>
#[derive(Default, Clone, Eq, PartialEq, PartialOrd, Ord, Hash)] #[derive(Default, Clone, Eq, PartialEq, PartialOrd, Ord, Hash)]
pub struct Str { pub struct Str {
name: Inner, name: Inner,

4
clap_builder/src/builder/value_parser.rs
View file

@ -1267,10 +1267,14 @@ where
/// Parse number that fall within a range of values /// Parse number that fall within a range of values
/// ///
/// <div class="warning">
///
/// **NOTE:** To capture negative values, you will also need to set /// **NOTE:** To capture negative values, you will also need to set
/// [`Arg::allow_negative_numbers`][crate::Arg::allow_negative_numbers] or /// [`Arg::allow_negative_numbers`][crate::Arg::allow_negative_numbers] or
/// [`Arg::allow_hyphen_values`][crate::Arg::allow_hyphen_values]. /// [`Arg::allow_hyphen_values`][crate::Arg::allow_hyphen_values].
/// ///
/// </div>
///
/// # Example /// # Example
/// ///
/// Usage: /// Usage:

16
clap_builder/src/derive.rs
View file

@ -20,7 +20,11 @@ use std::ffi::OsString;
/// ///
/// See also [`Subcommand`] and [`Args`]. /// See also [`Subcommand`] and [`Args`].
/// ///
/// <div class="warning">
///
/// **NOTE:** Deriving requires the `derive` feature flag /// **NOTE:** Deriving requires the `derive` feature flag
///
/// </div>
pub trait Parser: FromArgMatches + CommandFactory + Sized { pub trait Parser: FromArgMatches + CommandFactory + Sized {
/// Parse from `std::env::args_os()`, [exit][Error::exit] on error. /// Parse from `std::env::args_os()`, [exit][Error::exit] on error.
fn parse() -> Self { fn parse() -> Self {
@ -214,7 +218,11 @@ pub trait FromArgMatches: Sized {
/// `Args`. /// `Args`.
/// - `Variant(ChildArgs)`: No attribute is used with enum variants that impl `Args`. /// - `Variant(ChildArgs)`: No attribute is used with enum variants that impl `Args`.
/// ///
/// <div class="warning">
///
/// **NOTE:** Deriving requires the `derive` feature flag /// **NOTE:** Deriving requires the `derive` feature flag
///
/// </div>
pub trait Args: FromArgMatches + Sized { pub trait Args: FromArgMatches + Sized {
/// Report the [`ArgGroup::id`][crate::ArgGroup::id] for this set of arguments /// Report the [`ArgGroup::id`][crate::ArgGroup::id] for this set of arguments
fn group_id() -> Option<crate::Id> { fn group_id() -> Option<crate::Id> {
@ -245,7 +253,11 @@ pub trait Args: FromArgMatches + Sized {
/// - `#[command(flatten)] Variant(SubCmd)`: Attribute can only be used with enum variants that impl /// - `#[command(flatten)] Variant(SubCmd)`: Attribute can only be used with enum variants that impl
/// `Subcommand`. /// `Subcommand`.
/// ///
/// <div class="warning">
///
/// **NOTE:** Deriving requires the `derive` feature flag /// **NOTE:** Deriving requires the `derive` feature flag
///
/// </div>
pub trait Subcommand: FromArgMatches + Sized { pub trait Subcommand: FromArgMatches + Sized {
/// Append to [`Command`] so it can instantiate `Self` via /// Append to [`Command`] so it can instantiate `Self` via
/// [`FromArgMatches::from_arg_matches_mut`] /// [`FromArgMatches::from_arg_matches_mut`]
@ -272,7 +284,11 @@ pub trait Subcommand: FromArgMatches + Sized {
/// - Call [`EnumValueParser`][crate::builder::EnumValueParser] /// - Call [`EnumValueParser`][crate::builder::EnumValueParser]
/// - Allowing using the `#[arg(default_value_t)]` attribute without implementing `Display`. /// - Allowing using the `#[arg(default_value_t)]` attribute without implementing `Display`.
/// ///
/// <div class="warning">
///
/// **NOTE:** Deriving requires the `derive` feature flag /// **NOTE:** Deriving requires the `derive` feature flag
///
/// </div>
pub trait ValueEnum: Sized + Clone { pub trait ValueEnum: Sized + Clone {
/// All possible argument values, in display order. /// All possible argument values, in display order.
fn value_variants<'a>() -> &'a [Self]; fn value_variants<'a>() -> &'a [Self];

4
clap_builder/src/error/format.rs
View file

@ -26,8 +26,12 @@ pub trait ErrorFormatter: Sized {
/// ///
/// No context is included. /// No context is included.
/// ///
/// <div class="warning">
///
/// **NOTE:** Consider removing the `error-context` default feature if using this to remove all /// **NOTE:** Consider removing the `error-context` default feature if using this to remove all
/// overhead for [`RichFormatter`]. /// overhead for [`RichFormatter`].
///
/// </div>
#[non_exhaustive] #[non_exhaustive]
pub struct KindFormatter; pub struct KindFormatter;

16
clap_builder/src/macros.rs
View file

@ -79,12 +79,16 @@ macro_rules! crate_description {
/// Allows you to pull the name from your Cargo.toml at compile time. /// Allows you to pull the name from your Cargo.toml at compile time.
/// ///
/// <div class="warning">
///
/// **NOTE:** This macro extracts the name from an environment variable `CARGO_PKG_NAME`. /// **NOTE:** This macro extracts the name from an environment variable `CARGO_PKG_NAME`.
/// When the crate name is set to something different from the package name, /// When the crate name is set to something different from the package name,
/// use environment variables `CARGO_CRATE_NAME` or `CARGO_BIN_NAME`. /// use environment variables `CARGO_CRATE_NAME` or `CARGO_BIN_NAME`.
/// See [the Cargo Book](https://doc.rust-lang.org/cargo/reference/environment-variables.html) /// See [the Cargo Book](https://doc.rust-lang.org/cargo/reference/environment-variables.html)
/// for more information. /// for more information.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```no_run /// ```no_run
@ -104,6 +108,8 @@ macro_rules! crate_name {
/// Allows you to build the `Command` instance from your Cargo.toml at compile time. /// Allows you to build the `Command` instance from your Cargo.toml at compile time.
/// ///
/// <div class="warning">
///
/// **NOTE:** Changing the values in your `Cargo.toml` does not trigger a re-build automatically, /// **NOTE:** Changing the values in your `Cargo.toml` does not trigger a re-build automatically,
/// and therefore won't change the generated output until you recompile. /// and therefore won't change the generated output until you recompile.
/// ///
@ -111,6 +117,8 @@ macro_rules! crate_name {
/// `Cargo.toml` is changed by including this in your `src/main.rs` file /// `Cargo.toml` is changed by including this in your `src/main.rs` file
/// `include_str!("../Cargo.toml");` /// `include_str!("../Cargo.toml");`
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```no_run /// ```no_run
@ -430,9 +438,13 @@ macro_rules! arg_impl {
/// ///
/// Allows creation of basic settings for the [`Arg`]. /// Allows creation of basic settings for the [`Arg`].
/// ///
/// <div class="warning">
///
/// **NOTE**: Not all settings may be set using the usage string method. Some properties are /// **NOTE**: Not all settings may be set using the usage string method. Some properties are
/// only available via the builder pattern. /// only available via the builder pattern.
/// ///
/// </div>
///
/// # Syntax /// # Syntax
/// ///
/// Usage strings typically following the form: /// Usage strings typically following the form:
@ -467,9 +479,13 @@ macro_rules! arg_impl {
/// A long flag is a `--` followed by either a bare-word or a string, like `--foo` or /// A long flag is a `--` followed by either a bare-word or a string, like `--foo` or
/// `--"foo"`. /// `--"foo"`.
/// ///
/// <div class="warning">
///
/// **NOTE:** Dashes in the long name (e.g. `--foo-bar`) is not supported and quoting is required /// **NOTE:** Dashes in the long name (e.g. `--foo-bar`) is not supported and quoting is required
/// (e.g. `--"foo-bar"`). /// (e.g. `--"foo-bar"`).
/// ///
/// </div>
///
/// See [`Arg::long`][crate::Arg::long]. /// See [`Arg::long`][crate::Arg::long].
/// ///
/// ### Values (Value Notation) /// ### Values (Value Notation)

20
clap_builder/src/parser/matches/arg_matches.rs
View file

@ -83,9 +83,13 @@ impl ArgMatches {
/// ///
/// Returns `None` if the option wasn't present. /// Returns `None` if the option wasn't present.
/// ///
/// <div class="warning">
///
/// *NOTE:* This will always return `Some(value)` if [`default_value`] has been set. /// *NOTE:* This will always return `Some(value)` if [`default_value`] has been set.
/// [`ArgMatches::value_source`] can be used to check if a value is present at runtime. /// [`ArgMatches::value_source`] can be used to check if a value is present at runtime.
/// ///
/// </div>
///
/// # Panic /// # Panic
/// ///
/// If the argument definition and access mismatch. To handle this case programmatically, see /// If the argument definition and access mismatch. To handle this case programmatically, see
@ -374,9 +378,13 @@ impl ArgMatches {
/// ///
/// Returns `None` if the option wasn't present. /// Returns `None` if the option wasn't present.
/// ///
/// <div class="warning">
///
/// *NOTE:* This will always return `Some(value)` if [`default_value`] has been set. /// *NOTE:* This will always return `Some(value)` if [`default_value`] has been set.
/// [`ArgMatches::value_source`] can be used to check if a value is present at runtime. /// [`ArgMatches::value_source`] can be used to check if a value is present at runtime.
/// ///
/// </div>
///
/// # Panic /// # Panic
/// ///
/// If the argument definition and access mismatch. To handle this case programmatically, see /// If the argument definition and access mismatch. To handle this case programmatically, see
@ -485,9 +493,13 @@ impl ArgMatches {
/// Check if values are present for the argument or group id /// Check if values are present for the argument or group id
/// ///
/// <div class="warning">
///
/// *NOTE:* This will always return `true` if [`default_value`] has been set. /// *NOTE:* This will always return `true` if [`default_value`] has been set.
/// [`ArgMatches::value_source`] can be used to check if a value is present at runtime. /// [`ArgMatches::value_source`] can be used to check if a value is present at runtime.
/// ///
/// </div>
///
/// # Panics /// # Panics
/// ///
/// If `id` is not a valid argument or group name (debug builds). To handle this case programmatically, see /// If `id` is not a valid argument or group name (debug builds). To handle this case programmatically, see
@ -612,9 +624,13 @@ impl ArgMatches {
/// ///
/// The examples should clear this up. /// The examples should clear this up.
/// ///
/// <div class="warning">
///
/// *NOTE:* If an argument is allowed multiple times, this method will only give the *first* /// *NOTE:* If an argument is allowed multiple times, this method will only give the *first*
/// index. See [`ArgMatches::indices_of`]. /// index. See [`ArgMatches::indices_of`].
/// ///
/// </div>
///
/// # Panics /// # Panics
/// ///
/// If `id` is not a valid argument or group id (debug builds). /// If `id` is not a valid argument or group id (debug builds).
@ -760,9 +776,13 @@ impl ArgMatches {
/// refer to the *values* `-o val` would therefore not represent two distinct indices, only the /// refer to the *values* `-o val` would therefore not represent two distinct indices, only the
/// index for `val` would be recorded. This is by design. /// index for `val` would be recorded. This is by design.
/// ///
/// <div class="warning">
///
/// *NOTE:* For more information about how clap indices compared to argv indices, see /// *NOTE:* For more information about how clap indices compared to argv indices, see
/// [`ArgMatches::index_of`] /// [`ArgMatches::index_of`]
/// ///
/// </div>
///
/// # Panics /// # Panics
/// ///
/// If `id` is not a valid argument or group id (debug builds). /// If `id` is not a valid argument or group id (debug builds).

4
clap_builder/src/util/color.rs
View file

@ -6,8 +6,12 @@ use crate::derive::ValueEnum;
pub enum ColorChoice { pub enum ColorChoice {
/// Enables colored output only when the output is going to a terminal or TTY. /// Enables colored output only when the output is going to a terminal or TTY.
/// ///
/// <div class="warning">
///
/// **NOTE:** This is the default behavior of `clap`. /// **NOTE:** This is the default behavior of `clap`.
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust

8
clap_complete/src/aot/generator/mod.rs
View file

@ -68,9 +68,13 @@ pub trait Generator {
/// Generate a completions file for a specified shell at compile-time. /// Generate a completions file for a specified shell at compile-time.
/// ///
/// <div class="warning">
///
/// **NOTE:** to generate the file at compile time you must use a `build.rs` "Build Script" or a /// **NOTE:** to generate the file at compile time you must use a `build.rs` "Build Script" or a
/// [`cargo-xtask`](https://github.com/matklad/cargo-xtask) /// [`cargo-xtask`](https://github.com/matklad/cargo-xtask)
/// ///
/// </div>
///
/// # Examples /// # Examples
/// ///
/// The following example generates a bash completion script via a `build.rs` script. In this /// The following example generates a bash completion script via a `build.rs` script. In this
@ -160,9 +164,13 @@ pub trait Generator {
/// Assuming we compiled with debug mode, it would be somewhere similar to /// Assuming we compiled with debug mode, it would be somewhere similar to
/// `<project>/target/debug/build/myapp-<hash>/out/myapp.bash`. /// `<project>/target/debug/build/myapp-<hash>/out/myapp.bash`.
/// ///
/// <div class="warning">
///
/// **NOTE:** Please look at the individual [shells][crate::shells] /// **NOTE:** Please look at the individual [shells][crate::shells]
/// to see the name of the files generated. /// to see the name of the files generated.
/// ///
/// </div>
///
/// Using [`ValueEnum::value_variants()`][clap::ValueEnum::value_variants] you can easily loop over /// Using [`ValueEnum::value_variants()`][clap::ValueEnum::value_variants] you can easily loop over
/// all the supported shell variants to generate all the completions at once too. /// all the supported shell variants to generate all the completions at once too.
/// ///

4
clap_complete/src/aot/generator/utils.rs
View file

@ -18,7 +18,11 @@ pub fn all_subcommands(cmd: &Command) -> Vec<(String, String)> {
/// Finds the subcommand [`clap::Command`] from the given [`clap::Command`] with the given path. /// Finds the subcommand [`clap::Command`] from the given [`clap::Command`] with the given path.
/// ///
/// <div class="warning">
///
/// **NOTE:** `path` should not contain the root `bin_name`. /// **NOTE:** `path` should not contain the root `bin_name`.
///
/// </div>
pub fn find_subcommand_with_path<'cmd>(p: &'cmd Command, path: Vec<&str>) -> &'cmd Command { pub fn find_subcommand_with_path<'cmd>(p: &'cmd Command, path: Vec<&str>) -> &'cmd Command {
let mut cmd = p; let mut cmd = p;

8
clap_complete/src/env/mod.rs vendored
View file

@ -24,6 +24,8 @@
//! //!
//! To source your completions: //! To source your completions:
//! //!
//! <div class="warning">
//!
//! **WARNING:** We recommend re-sourcing your completions on upgrade. //! **WARNING:** We recommend re-sourcing your completions on upgrade.
//! These completions work by generating shell code that calls into `your_program` while completing. //! These completions work by generating shell code that calls into `your_program` while completing.
//! That interface is unstable and a mismatch between the shell code and `your_program` may result //! That interface is unstable and a mismatch between the shell code and `your_program` may result
@ -31,6 +33,8 @@
//! For this reason, we recommend generating the shell code anew on shell startup so that it is //! For this reason, we recommend generating the shell code anew on shell startup so that it is
//! "self-correcting" on shell launch, rather than writing the generated completions to a file. //! "self-correcting" on shell launch, rather than writing the generated completions to a file.
//! //!
//! </div>
//!
//! Bash //! Bash
//! ```bash //! ```bash
//! echo "source <(COMPLETE=bash your_program)" >> ~/.bashrc //! echo "source <(COMPLETE=bash your_program)" >> ~/.bashrc
@ -355,9 +359,13 @@ pub trait EnvCompleter {
/// - `bin`: see [`CompleteEnv::bin`] /// - `bin`: see [`CompleteEnv::bin`]
/// - `completer`: see [`CompleteEnv::completer`] /// - `completer`: see [`CompleteEnv::completer`]
/// ///
/// <div class="warning">
///
/// **WARNING:** There are no stability guarantees between the call to /// **WARNING:** There are no stability guarantees between the call to
/// [`EnvCompleter::write_complete`] that this generates and actually calling [`EnvCompleter::write_complete`]. /// [`EnvCompleter::write_complete`] that this generates and actually calling [`EnvCompleter::write_complete`].
/// Caching the results of this call may result in invalid or no completions to be generated. /// Caching the results of this call may result in invalid or no completions to be generated.
///
/// </div>
fn write_registration( fn write_registration(
&self, &self,
var: &str, var: &str,

12
clap_lex/src/lib.rs
View file

@ -133,8 +133,12 @@ pub struct RawArgs {
impl RawArgs { impl RawArgs {
//// Create an argument list to parse //// Create an argument list to parse
/// ///
/// <div class="warning">
///
/// **NOTE:** The argument returned will be the current binary. /// **NOTE:** The argument returned will be the current binary.
/// ///
/// </div>
///
/// # Example /// # Example
/// ///
/// ```rust,no_run /// ```rust,no_run
@ -362,14 +366,22 @@ impl<'s> ParsedArg<'s> {
/// Treat as a value /// Treat as a value
/// ///
/// <div class="warning">
///
/// **NOTE:** May return a flag or an escape. /// **NOTE:** May return a flag or an escape.
///
/// </div>
pub fn to_value_os(&self) -> &OsStr { pub fn to_value_os(&self) -> &OsStr {
self.inner self.inner
} }
/// Treat as a value /// Treat as a value
/// ///
/// <div class="warning">
///
/// **NOTE:** May return a flag or an escape. /// **NOTE:** May return a flag or an escape.
///
/// </div>
pub fn to_value(&self) -> Result<&str, &OsStr> { pub fn to_value(&self) -> Result<&str, &OsStr> {
self.inner.to_str().ok_or(self.inner) self.inner.to_str().ok_or(self.inner)
} }

4
examples/pacman.md
View file

@ -75,5 +75,9 @@ For more information, try '--help'.
``` ```
<div class="warning">
**NOTE:** Keep in mind that subcommands, flags, and long flags are *case sensitive*: `-Q` and `-q` are different flags/subcommands. For example, you can have both `-Q` subcommand and `-q` flag, and they will be properly disambiguated. **NOTE:** Keep in mind that subcommands, flags, and long flags are *case sensitive*: `-Q` and `-q` are different flags/subcommands. For example, you can have both `-Q` subcommand and `-q` flag, and they will be properly disambiguated.
Let's make a quick program to illustrate. Let's make a quick program to illustrate.
</div>

8
src/_derive/mod.rs
View file

@ -126,10 +126,14 @@
//! magic attributes documentation for details. This allows users to access the //! magic attributes documentation for details. This allows users to access the
//! raw behavior of an attribute via `<attr>(<value>)` syntax. //! raw behavior of an attribute via `<attr>(<value>)` syntax.
//! //!
//! <div class="warning">
//!
//! **NOTE:** Some attributes are inferred from [Arg Types](#arg-types) and [Doc //! **NOTE:** Some attributes are inferred from [Arg Types](#arg-types) and [Doc
//! Comments](#doc-comments). Explicit attributes take precedence over inferred //! Comments](#doc-comments). Explicit attributes take precedence over inferred
//! attributes. //! attributes.
//! //!
//! </div>
//!
//! ### Command Attributes //! ### Command Attributes
//! //!
//! These correspond to a [`Command`][crate::Command] which is used for both top-level parsers and //! These correspond to a [`Command`][crate::Command] which is used for both top-level parsers and
@ -349,6 +353,8 @@
//! } //! }
//! ``` //! ```
//! //!
//! <div class="warning">
//!
//! **NOTE:** Attributes have priority over doc comments! //! **NOTE:** Attributes have priority over doc comments!
//! //!
//! **Top level doc comments always generate `Command::about/long_about` calls!** //! **Top level doc comments always generate `Command::about/long_about` calls!**
@ -357,6 +363,8 @@
//! the doc comment. To clear `long_about`, you can use //! the doc comment. To clear `long_about`, you can use
//! `#[command(long_about = None)]`. //! `#[command(long_about = None)]`.
//! //!
//! </div>
//!
//! ### Pre-processing //! ### Pre-processing
//! //!
//! ```rust //! ```rust