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

Merge pull request #5811 from epage/notes

Browse source 
docs: Highlight notes/warnings in a block
This commit is contained in:
Ed Page 2024-11-08 12:06:47 -06:00 committed by GitHub
commit 424a2431c9
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
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 {
/// 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
/// [`ArgumentConflict`][crate::error::ErrorKind::ArgumentConflict] unless
/// [`Command::args_override_self(true)`][crate::Command::args_override_self] is set.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -87,10 +91,14 @@ pub enum ArgAction {
/// No value is allowed. To optionally accept a value, see
/// [`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
/// [`ArgumentConflict`][crate::error::ErrorKind::ArgumentConflict] unless
/// [`Command::args_override_self(true)`][crate::Command::args_override_self] is set.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -162,10 +170,14 @@ pub enum ArgAction {
/// No value is allowed. To optionally accept a value, see
/// [`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
/// [`ArgumentConflict`][crate::error::ErrorKind::ArgumentConflict] unless
/// [`Command::args_override_self(true)`][crate::Command::args_override_self] is set.
///
/// </div>
///
/// # Examples
///
/// ```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
///
/// <div class="warning">
///
/// **NOTE:** When these settings are used, they apply only to current command, and are *not*
/// propagated down or up through child or parent subcommands
///
/// </div>
///
/// [`Command`]: crate::Command
#[derive(Debug, PartialEq, Copy, Clone)]
#[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
/// 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)`])
/// 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.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -188,8 +192,12 @@ impl Arg {
/// own arguments, in which case `clap` simply will not assign those to the auto-generated
/// `version` or `help` arguments.
///
/// <div class="warning">
///
/// **NOTE:** Any leading `-` characters will be stripped
///
/// </div>
///
/// # Examples
///
/// 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.
///
/// <div class="warning">
///
/// **NOTE:** The index refers to position according to **other positional argument**. It does
/// 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
/// assigned in order of evaluation. Utilizing the `index` method allows for setting
/// 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
/// with [`Arg::short`] or [`Arg::long`].
///
/// </div>
///
/// <div class="warning">
///
/// **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)
///
/// </div>
///
/// # Panics
///
/// [`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
/// used a `--`.
///
/// <div class="warning">
///
/// **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
/// have the option to explicitly escape ambiguous arguments with `--`.
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** [`Arg::value_delimiter`] still applies if set.
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** Setting this requires [`Arg::num_args(..)`].
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -554,22 +590,42 @@ impl Arg {
/// allows one to access this arg early using the `--` syntax. Accessing an arg early, even with
/// the `--` syntax is otherwise not possible.
///
/// <div class="warning">
///
/// **NOTE:** This will change the usage string to look like `$ prog [OPTIONS] [-- <ARG>]` if
/// `ARG` is marked as `.last(true)`.
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** This setting will imply [`crate::Command::dont_collapse_args_in_usage`] because failing
/// 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
///
/// </div>
///
/// <div class="warning">
///
/// **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
/// [`crate::Command::args_conflicts_with_subcommands`]
/// (or [`crate::Command::subcommand_negates_reqs`] if the argument marked `Last` is also
/// marked [`Arg::required`])
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -704,8 +760,12 @@ impl Arg {
///
/// 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
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -812,11 +872,15 @@ impl Arg {
/// 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
/// 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
/// where the user *uses* the global argument.
///
/// </div>
///
/// # Examples
///
/// 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`
/// - Use a short and no space such as `-ovalue`
///
/// <div class="warning">
///
/// **WARNING:**
///
/// 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 positional arguments to appear after `--` with [`Arg::last`]
///
/// </div>
///
/// # Examples
///
/// Option:
@ -1155,8 +1223,12 @@ impl Arg {
/// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to
/// use all capital letters for the value name.
///
/// <div class="warning">
///
/// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`]
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -1218,11 +1290,19 @@ impl Arg {
/// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to
/// 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.
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`] and [`Arg::num_args(1..)`].
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -1273,8 +1353,12 @@ impl Arg {
///
/// See [`ValueHint`] for more information.
///
/// <div class="warning">
///
/// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`].
///
/// </div>
///
/// For example, to take a username as argument:
///
/// ```rust
@ -1322,10 +1406,18 @@ impl Arg {
/// [`Arg::required_if_eq_all`] is case-insensitive.
///
///
/// <div class="warning">
///
/// **NOTE:** Setting this requires [taking values][Arg::num_args]
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** To do unicode case folding, enable the `unicode` feature flag.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -1381,18 +1473,30 @@ impl Arg {
///
/// See also [`trailing_var_arg`][Arg::trailing_var_arg].
///
/// <div class="warning">
///
/// **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
/// flags but known flags get precedence over the next possible positional argument with
/// `allow_hyphen_values(true)`. When combined with [`Arg::num_args(..)`],
/// [`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
/// [`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
/// constitute the normal, "Only positional args follow" idiom.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -1443,8 +1547,12 @@ impl Arg {
/// This is similar to [`Arg::allow_hyphen_values`] except that it only allows numbers,
/// all other undefined leading hyphens will fail to parse.
///
/// <div class="warning">
///
/// **NOTE:** Setting this requires [taking values][Arg::num_args]
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -1472,8 +1580,12 @@ impl Arg {
///
/// i.e. an equals between the option and associated value.
///
/// <div class="warning">
///
/// **NOTE:** Setting this requires [taking values][Arg::num_args]
///
/// </div>
///
/// # Examples
///
/// 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
/// for multiple values is used (such as [`num_args`]).
///
/// <div class="warning">
///
/// **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
/// of the values
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -1636,7 +1756,12 @@ impl Arg {
/// may not be exactly what you are expecting and using [`Arg::trailing_var_arg`]
/// may be more appropriate.
///
/// <div class="warning">
///
/// **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::action(ArgAction::Set)`]: Arg::action()
@ -1654,10 +1779,18 @@ impl Arg {
/// 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
/// 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].
///
/// </div>
///
/// <div class="warning">
///
/// **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
/// 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`
/// will be applied.
///
/// Like with command-line values, this will be split by [`Arg::value_delimiter`].
/// </div>
///
/// # Examples
///
@ -1760,12 +1893,16 @@ impl Arg {
/// 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.
///
/// 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
/// [`.num_args(0..N)`][Arg::num_args] and the
/// [`.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.
///
/// Like with command-line values, this will be split by [`Arg::value_delimiter`].
/// </div>
///
/// # Examples
///
@ -2080,8 +2217,12 @@ impl Arg {
///
/// 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
///
/// </div>
///
/// # Examples
///
/// 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`.
///
/// <div class="warning">
///
/// **NOTE:** Only [`Arg::help`] is used in completion script generation in order to be concise
///
/// </div>
///
/// # Examples
///
/// 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].
///
/// <div class="warning">
///
/// **NOTE:** This setting is ignored for [positional arguments] which are always displayed in
/// [index] order.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -2271,9 +2420,13 @@ impl Arg {
/// 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.
///
/// <div class="warning">
///
/// **NOTE:** To apply this setting to all arguments and subcommands, consider using
/// [`crate::Command::next_line_help`]
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -2323,8 +2476,12 @@ impl Arg {
/// Do not display the argument in help message.
///
/// <div class="warning">
///
/// **NOTE:** This does **not** hide the argument from usage strings on error
///
/// </div>
///
/// # Examples
///
/// 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
/// help text.
///
/// **NOTE:** Setting this requires [taking values][Arg::num_args]
///
/// To set this for all arguments, see
/// [`Command::hide_possible_values`][crate::Command::hide_possible_values].
///
/// <div class="warning">
///
/// **NOTE:** Setting this requires [taking values][Arg::num_args]
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -2403,8 +2564,12 @@ impl Arg {
///
/// 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]
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -2494,11 +2659,19 @@ impl Arg {
/// Hides an argument from short help (`-h`).
///
/// <div class="warning">
///
/// **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
/// when long help (`--help`) is called.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -2578,11 +2751,19 @@ impl Arg {
/// Hides an argument from long help (`--help`).
///
/// <div class="warning">
///
/// **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
/// when long help (`--help`) is called.
///
/// </div>
///
/// # Examples
///
/// 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.
///
/// 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
/// 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
@ -2756,7 +2941,7 @@ impl Arg {
/// 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.
///
/// Like with command-line values, this will be split by [`Arg::value_delimiter`].
/// </div>
///
/// # Examples
///
@ -2894,10 +3079,14 @@ impl Arg {
///
/// 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
/// 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
///
@ -3014,9 +3203,13 @@ impl Arg {
/// 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.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -3084,9 +3277,13 @@ impl Arg {
/// * supplies the `self` arg.
/// * 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
/// present see [`Arg::required_unless_present_any`]
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -3163,9 +3360,13 @@ impl Arg {
/// * supplies the `self` arg.
/// * 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
/// present see [`Arg::required_unless_present_all`]
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -3653,19 +3854,39 @@ impl Arg {
/// This argument is mutually exclusive with the specified argument.
///
/// <div class="warning">
///
/// **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.
///
/// </div>
///
/// <div class="warning">
///
/// **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 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.
///
/// </div>
///
/// <div class="warning">
///
/// **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.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -3713,15 +3934,27 @@ impl Arg {
///
/// See [`Arg::conflicts_with`].
///
/// <div class="warning">
///
/// **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.
///
/// </div>
///
/// <div class="warning">
///
/// **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
/// 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.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -3767,11 +4000,19 @@ impl Arg {
/// will override each other in POSIX style (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
/// 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`].
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -3807,11 +4048,19 @@ impl Arg {
/// i.e. this argument and the following argument will override each other in POSIX style
/// (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
/// 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`].
///
/// </div>
///
/// # Examples
///
/// ```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
/// 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
/// globally.
///
/// </div>
///
/// <div class="warning">
///
/// **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.
/// 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."
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -335,8 +343,12 @@ impl ArgGroup {
/// [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.
///
/// <div class="warning">
///
/// **NOTE:** The name provided may be an argument or group name
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -380,8 +392,12 @@ impl ArgGroup {
/// [argument requirement rules], you can name other arguments or groups that must be present
/// when one of the arguments from this group is used.
///
/// <div class="warning">
///
/// **NOTE:** The names provided may be an argument or group name
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -426,8 +442,12 @@ impl ArgGroup {
/// other arguments or groups that must *not* be present when one of the arguments from this
/// group are used.
///
/// <div class="warning">
///
/// **NOTE:** The name provided may be an argument, or group name
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -468,8 +488,12 @@ impl ArgGroup {
/// 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.
///
/// <div class="warning">
///
/// **NOTE:** The names provided may be an argument, or group name
///
/// </div>
///
/// # Examples
///
/// ```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.
///
/// <div class="warning">
///
/// **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`] or [`ErrorKind::DisplayVersion`] respectively. You must call
/// [`Error::exit`] or perform a [`std::process::exit`].
///
/// </div>
///
/// # Panics
///
/// If contradictory arguments or settings exist (debug builds).
@ -675,9 +679,13 @@ impl Command {
/// Parse the specified arguments, [exiting][Error::exit] on failure.
///
/// <div class="warning">
///
/// **NOTE:** The first argument will be parsed as the binary name unless
/// [`Command::no_binary_name`] is used.
///
/// </div>
///
/// # Panics
///
/// If contradictory arguments or settings exist (debug builds).
@ -709,14 +717,22 @@ impl Command {
/// 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
/// used. It will return a [`clap::Error`], where the [`kind`] is a [`ErrorKind::DisplayHelp`]
/// or [`ErrorKind::DisplayVersion`] respectively. You must call [`Error::exit`] or
/// perform a [`std::process::exit`] yourself.
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** The first argument will be parsed as the binary name unless
/// [`Command::no_binary_name`] is used.
///
/// </div>
///
/// # Panics
///
/// 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`.
///
/// <div class="warning">
///
/// **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`]
/// or [`ErrorKind::DisplayVersion`] respectively. You must call [`Error::exit`] or
/// perform a [`std::process::exit`] yourself.
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** The first argument will be parsed as the binary name unless
/// [`Command::no_binary_name`] is used.
///
/// </div>
///
/// # Panics
///
/// 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.
///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -1125,8 +1153,12 @@ impl Command {
/// This is the equivalent to saying the `foo` arg using [`Arg::overrides_with("foo")`] for all
/// defined arguments.
///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands.
///
/// </div>
///
/// [`Arg::overrides_with("foo")`]: crate::Arg::overrides_with()
#[inline]
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`]
/// was used.
///
/// <div class="warning">
///
/// **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
/// when making changes.
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands.
///
/// </div>
///
/// # Examples
///
/// ```no_run
@ -1170,10 +1210,18 @@ impl Command {
///
/// To customize how the output is styled, see [`Command::styles`].
///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands.
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** Default behaviour is [`ColorChoice::Auto`].
///
/// </div>
///
/// # Examples
///
/// ```no_run
@ -1201,10 +1249,18 @@ impl Command {
/// Sets the [`Styles`] for terminal output
///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands.
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** Default behaviour is [`Styles::default`].
///
/// </div>
///
/// # Examples
///
/// ```no_run
@ -1237,10 +1293,18 @@ impl Command {
/// **`unstable-v5` feature**: Defaults to unbound, being subject to
/// [`Command::max_term_width`].
///
/// <div class="warning">
///
/// **NOTE:** This setting applies globally and *not* on a per-command basis.
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** This requires the `wrap_help` feature
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -1267,10 +1331,18 @@ impl Command {
///
/// **`unstable-v5` feature**: Defaults to 100.
///
/// <div class="warning">
///
/// **NOTE:** This setting applies globally and *not* on a per-command basis.
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** This requires the `wrap_help` feature
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -1345,8 +1417,12 @@ impl Command {
///
/// Defaults to `false`; subcommands have independent version strings from their parents.
///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands.
///
/// </div>
///
/// # Examples
///
/// ```no_run
@ -1373,8 +1449,12 @@ impl Command {
/// 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.
///
/// </div>
///
/// # Examples
///
/// ```no_run
@ -1395,8 +1475,12 @@ impl Command {
/// Disables `-h` and `--help` flag.
///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -1450,8 +1534,12 @@ impl Command {
/// Disables the `help` [`subcommand`].
///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -1481,8 +1569,12 @@ impl Command {
/// Disables colorized help messages.
///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands.
///
/// </div>
///
/// # Examples
///
/// ```no_run
@ -1503,11 +1595,19 @@ impl Command {
/// Panic if help descriptions are omitted.
///
/// <div class="warning">
///
/// **NOTE:** When deriving [`Parser`][crate::Parser], you could instead check this at
/// compile-time with `#![deny(missing_docs)]`
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -1563,7 +1663,11 @@ impl Command {
/// To set this per argument, see
/// [`Arg::hide_possible_values`][crate::Arg::hide_possible_values].
///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands.
///
/// </div>
#[inline]
pub fn hide_possible_values(self, yes: bool) -> Self {
if yes {
@ -1578,12 +1682,20 @@ impl Command {
/// For example, to match an argument named `--test`, one could use `--t`, `--te`, `--tes`, and
/// `--test`.
///
/// <div class="warning">
///
/// **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
/// start with `--te`
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands.
///
/// </div>
///
/// [aliases]: crate::Command::aliases()
#[inline]
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
/// `test`.
///
/// <div class="warning">
///
/// **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`
///
/// **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
/// 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
/// conjunction with this setting.
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands.
///
/// </div>
///
/// # Examples
///
/// ```no_run
@ -1664,13 +1788,21 @@ impl Command {
/// 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.
///
/// **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!
///
/// </div>
///
/// <div class="warning">
///
/// **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
/// error or help messages.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -1705,13 +1837,21 @@ impl Command {
/// 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
/// crate at compile time.
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** A custom [`help_template`][Command::help_template] is needed for author to show
/// up.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -1731,9 +1871,6 @@ impl Command {
///
/// 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!).
///
/// # Examples
@ -1756,9 +1893,13 @@ impl Command {
/// If not set, [`Command::about`] will be used for long help in addition to short help
/// (`-h`).
///
/// <div class="warning">
///
/// **NOTE:** Only [`Command::about`] (short format) is used in completion
/// script generation in order to be concise.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -1872,10 +2013,14 @@ impl Command {
///
/// 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
/// crate at compile time.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -1895,10 +2040,14 @@ impl Command {
///
/// 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
/// crate at compile time.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -1921,10 +2070,16 @@ impl Command {
/// Overrides the `clap` generated usage string for help and error messages.
///
/// <div class="warning">
///
/// **NOTE:** Using this setting disables `clap`s "context-aware" usage
/// strings. After this setting is set, this will be *the only* usage string
/// displayed to the user!
///
/// </div>
///
/// <div class="warning">
///
/// **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
/// correctly by the default help formatter:
@ -1933,6 +2088,8 @@ impl Command {
/// - Indent all subsequent usage lines with seven spaces.
/// - The last line must not end with a newline.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -1968,11 +2125,15 @@ impl Command {
///
/// 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
/// command, meaning if you are using subcommands, those help messages will
/// still be auto-generated unless you specify a [`Command::override_help`] for
/// them as well.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -2004,9 +2165,6 @@ impl Command {
/// 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.
///
/// Valid tags are:
@ -2149,8 +2307,12 @@ impl Command {
/// Exit gracefully if no arguments are present (e.g. `$ myprog`).
///
/// <div class="warning">
///
/// **NOTE:** [`subcommands`] count as arguments
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -2369,8 +2531,12 @@ impl Command {
///
/// Allows the subcommand to be used as if it were an [`Arg::long`].
///
/// <div class="warning">
///
/// **NOTE:** Any leading `-` characters will be stripped.
///
/// </div>
///
/// # Examples
///
/// 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
/// 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
/// message. If you're looking for aliases that will be displayed in the help
/// message, see [`Command::visible_alias`].
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** When using aliases and checking for the existence of a
/// particular subcommand within an [`ArgMatches`] struct, one only needs to
/// search for the original name and not all aliases.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -2501,14 +2675,22 @@ impl Command {
/// 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.
///
/// <div class="warning">
///
/// **NOTE:** Aliases defined with this method are *hidden* from the help
/// message. If looking for aliases that will be displayed in the help
/// message, see [`Command::visible_aliases`].
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** When using aliases and checking for the existence of a
/// particular subcommand within an [`ArgMatches`] struct, one only needs to
/// search for the original name and not all aliases.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -2595,15 +2777,23 @@ impl Command {
/// than creating hidden subcommands as one only needs to check for
/// 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
/// 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
/// [`Command::alias`].
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** When using aliases and checking for the existence of a
/// particular subcommand within an [`ArgMatches`] struct, one only needs to
/// search for the original name and not all aliases.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -2694,15 +2884,23 @@ impl Command {
/// than creating multiple hidden subcommands as one only needs to check for
/// 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
/// 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
/// [`Command::alias`].
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** When using aliases, and checking for the existence of a
/// particular subcommand within an [`ArgMatches`] struct, one only needs to
/// search for the original name and not all aliases.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -2881,14 +3079,22 @@ impl Command {
///
/// Arguments will be stored in the `""` argument in the [`ArgMatches`]
///
/// <div class="warning">
///
/// **NOTE:** Use this setting with caution,
/// 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.
/// 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
/// `--`.
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -2930,8 +3136,12 @@ impl Command {
/// The default parser is for `OsString`. This can be used to switch it to `String` or another
/// type.
///
/// <div class="warning">
///
/// **NOTE:** Setting this requires [`Command::allow_external_subcommands`]
///
/// </div>
///
/// # Examples
///
/// ```rust
@ -3090,8 +3300,12 @@ impl Command {
/// 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.
///
/// <div class="warning">
///
/// **NOTE:** This defaults to false (using subcommand does *not* negate requirements)
///
/// </div>
///
/// # Examples
///
/// 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
/// get the unrecognized binary name.
///
/// <div class="warning">
///
/// **NOTE:** Multicall can't be used with [`no_binary_name`] since they interpret
/// the command name in incompatible ways.
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** The multicall command cannot have arguments.
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** Applets are slightly semantically different from subcommands,
/// so it's recommended to use [`Command::subcommand_help_heading`] and
/// [`Command::subcommand_value_name`] to change the descriptive text as above.
///
/// </div>
///
/// # Examples
///
/// `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.
//
// This behavior follows the propagation rules of global arguments.
// It is useful for finding conflicts for arguments declared as global.
//
// ### Panics
//
// If the given arg contains a conflict with an argument that is unknown to
// this `Command`.
/// 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.
/// It is useful for finding conflicts for arguments declared as global.
///
/// ### Panics
///
/// If the given arg contains a conflict with an argument that is unknown to
/// this `Command`.
fn get_global_arg_conflicts_with(&self, arg: &Arg) -> Vec<&Arg> // FIXME: This could probably have been an iterator
{
arg.blacklist
@ -3774,19 +4000,24 @@ impl Command {
.collect()
}
// Get a list of subcommands which contain the provided Argument
//
// This command will only include subcommands in its list for which the subcommands
// parent also contains the Argument.
//
// This search follows the propagation rules of global arguments.
// It is useful to finding subcommands, that have inherited a global argument.
//
// **NOTE:** In this case only Sucommand_1 will be included
// Subcommand_1 (contains Arg)
// Subcommand_1.1 (doesn't contain Arg)
// Subcommand_1.1.1 (contains Arg)
//
/// Get a list of subcommands which contain the provided Argument
///
/// This command will only include subcommands in its list for which the subcommands
/// parent also contains the Argument.
///
/// This search follows the propagation rules of global arguments.
/// It is useful to finding subcommands, that have inherited a global argument.
///
/// <div class="warning">
///
/// **NOTE:** In this case only `Sucommand_1` will be included
/// ```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> {
let mut vec = Vec::new();
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
///
/// <div class="warning">
///
/// **NOTE:** To support dynamic values (i.e. `OsString`), enable the `string`
/// feature
///
/// </div>
#[derive(Default, Clone, Eq, PartialEq, PartialOrd, Ord, Hash)]
pub struct OsStr {
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]
///
/// <div class="warning">
///
/// **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
/// possible values.
///
/// </div>
///
/// # Examples
///
/// ```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.
///
/// <div class="warning">
///
/// **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)`].
///
/// </div>
///
/// # Examples
///
/// ```rust

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

@ -1,7 +1,11 @@
/// A UTF-8-encoded fixed string
///
/// <div class="warning">
///
/// **NOTE:** To support dynamic values (i.e. `String`), enable the `string`
/// feature
///
/// </div>
#[derive(Default, Clone, Eq, PartialEq, PartialOrd, Ord, Hash)]
pub struct Str {
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
///
/// <div class="warning">
///
/// **NOTE:** To capture negative values, you will also need to set
/// [`Arg::allow_negative_numbers`][crate::Arg::allow_negative_numbers] or
/// [`Arg::allow_hyphen_values`][crate::Arg::allow_hyphen_values].
///
/// </div>
///
/// # Example
///
/// Usage:

16
clap_builder/src/derive.rs
View file

@ -20,7 +20,11 @@ use std::ffi::OsString;
///
/// See also [`Subcommand`] and [`Args`].
///
/// <div class="warning">
///
/// **NOTE:** Deriving requires the `derive` feature flag
///
/// </div>
pub trait Parser: FromArgMatches + CommandFactory + Sized {
/// Parse from `std::env::args_os()`, [exit][Error::exit] on error.
fn parse() -> Self {
@ -214,7 +218,11 @@ pub trait FromArgMatches: Sized {
/// `Args`.
/// - `Variant(ChildArgs)`: No attribute is used with enum variants that impl `Args`.
///
/// <div class="warning">
///
/// **NOTE:** Deriving requires the `derive` feature flag
///
/// </div>
pub trait Args: FromArgMatches + Sized {
/// Report the [`ArgGroup::id`][crate::ArgGroup::id] for this set of arguments
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
/// `Subcommand`.
///
/// <div class="warning">
///
/// **NOTE:** Deriving requires the `derive` feature flag
///
/// </div>
pub trait Subcommand: FromArgMatches + Sized {
/// Append to [`Command`] so it can instantiate `Self` via
/// [`FromArgMatches::from_arg_matches_mut`]
@ -272,7 +284,11 @@ pub trait Subcommand: FromArgMatches + Sized {
/// - Call [`EnumValueParser`][crate::builder::EnumValueParser]
/// - Allowing using the `#[arg(default_value_t)]` attribute without implementing `Display`.
///
/// <div class="warning">
///
/// **NOTE:** Deriving requires the `derive` feature flag
///
/// </div>
pub trait ValueEnum: Sized + Clone {
/// All possible argument values, in display order.
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.
///
/// <div class="warning">
///
/// **NOTE:** Consider removing the `error-context` default feature if using this to remove all
/// overhead for [`RichFormatter`].
///
/// </div>
#[non_exhaustive]
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.
///
/// <div class="warning">
///
/// **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,
/// use environment variables `CARGO_CRATE_NAME` or `CARGO_BIN_NAME`.
/// See [the Cargo Book](https://doc.rust-lang.org/cargo/reference/environment-variables.html)
/// for more information.
///
/// </div>
///
/// # Examples
///
/// ```no_run
@ -104,6 +108,8 @@ macro_rules! crate_name {
/// 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,
/// 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
/// `include_str!("../Cargo.toml");`
///
/// </div>
///
/// # Examples
///
/// ```no_run
@ -430,9 +438,13 @@ macro_rules! arg_impl {
///
/// 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
/// only available via the builder pattern.
///
/// </div>
///
/// # Syntax
///
/// 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
/// `--"foo"`.
///
/// <div class="warning">
///
/// **NOTE:** Dashes in the long name (e.g. `--foo-bar`) is not supported and quoting is required
/// (e.g. `--"foo-bar"`).
///
/// </div>
///
/// See [`Arg::long`][crate::Arg::long].
///
/// ### 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.
///
/// <div class="warning">
///
/// *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.
///
/// </div>
///
/// # Panic
///
/// 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.
///
/// <div class="warning">
///
/// *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.
///
/// </div>
///
/// # Panic
///
/// 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
///
/// <div class="warning">
///
/// *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.
///
/// </div>
///
/// # Panics
///
/// 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.
///
/// <div class="warning">
///
/// *NOTE:* If an argument is allowed multiple times, this method will only give the *first*
/// index. See [`ArgMatches::indices_of`].
///
/// </div>
///
/// # Panics
///
/// 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
/// 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
/// [`ArgMatches::index_of`]
///
/// </div>
///
/// # Panics
///
/// 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 {
/// 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`.
///
/// </div>
///
/// # Examples
///
/// ```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.
///
/// <div class="warning">
///
/// **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)
///
/// </div>
///
/// # Examples
///
/// 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
/// `<project>/target/debug/build/myapp-<hash>/out/myapp.bash`.
///
/// <div class="warning">
///
/// **NOTE:** Please look at the individual [shells][crate::shells]
/// to see the name of the files generated.
///
/// </div>
///
/// 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.
///

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.
///
/// <div class="warning">
///
/// **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 {
let mut cmd = p;

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

@ -24,6 +24,8 @@
//!
//! To source your completions:
//!
//! <div class="warning">
//!
//! **WARNING:** We recommend re-sourcing your completions on upgrade.
//! 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
@ -31,6 +33,8 @@
//! 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.
//!
//! </div>
//!
//! Bash
//! ```bash
//! echo "source <(COMPLETE=bash your_program)" >> ~/.bashrc
@ -355,9 +359,13 @@ pub trait EnvCompleter {
/// - `bin`: see [`CompleteEnv::bin`]
/// - `completer`: see [`CompleteEnv::completer`]
///
/// <div class="warning">
///
/// **WARNING:** There are no stability guarantees between the call to
/// [`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.
///
/// </div>
fn write_registration(
&self,
var: &str,

12
clap_lex/src/lib.rs
View file

@ -133,8 +133,12 @@ pub struct RawArgs {
impl RawArgs {
//// Create an argument list to parse
///
/// <div class="warning">
///
/// **NOTE:** The argument returned will be the current binary.
///
/// </div>
///
/// # Example
///
/// ```rust,no_run
@ -362,14 +366,22 @@ impl<'s> ParsedArg<'s> {
/// Treat as a value
///
/// <div class="warning">
///
/// **NOTE:** May return a flag or an escape.
///
/// </div>
pub fn to_value_os(&self) -> &OsStr {
self.inner
}
/// Treat as a value
///
/// <div class="warning">
///
/// **NOTE:** May return a flag or an escape.
///
/// </div>
pub fn to_value(&self) -> Result<&str, &OsStr> {
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.
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
//! raw behavior of an attribute via `<attr>(<value>)` syntax.
//!
//! <div class="warning">
//!
//! **NOTE:** Some attributes are inferred from [Arg Types](#arg-types) and [Doc
//! Comments](#doc-comments). Explicit attributes take precedence over inferred
//! attributes.
//!
//! </div>
//!
//! ### Command Attributes
//!
//! 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!
//!
//! **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
//! `#[command(long_about = None)]`.
//!
//! </div>
//!
//! ### Pre-processing
//!
//! ```rust