Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-12-14 06:42:33 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge #2896

Browse source 
2896: docs: Clarify corner caseses with default values r=epage a=epage



Co-authored-by: Ed Page <eopage@gmail.com>
This commit is contained in:
bors[bot] 2021-10-25 16:48:17 +00:00 committed by GitHub
commit 29972e162a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 81 additions and 59 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

130
src/build/arg/mod.rs
View file

@ -1045,6 +1045,8 @@ impl<'help> Arg<'help> {
///
/// **NOTE** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument.
///
/// **NOTE:** An argument is considered present when there is a [`Arg::default_value`]
///
/// # Examples
///
/// ```rust
@ -1095,6 +1097,8 @@ impl<'help> Arg<'help> {
///
/// **NOTE:** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument.
///
/// **NOTE:** An argument is considered present when there is a [`Arg::default_value`]
///
/// # Examples
///
/// ```rust
@ -1143,7 +1147,8 @@ impl<'help> Arg<'help> {
/// .exclusive(true)
/// # ;
/// ```
/// **NOTE:** If using YAML the above example should be laid out as follows
///
/// If using YAML the above example should be laid out as follows
///
/// ```yaml
/// - config
@ -1327,6 +1332,8 @@ impl<'help> Arg<'help> {
///
/// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required
///
/// **NOTE:** This argument is considered present when there is a [`Arg::default_value`]
///
/// # Examples
///
/// ```rust
@ -1388,12 +1395,7 @@ impl<'help> Arg<'help> {
/// if this arg (`self`) is present and its value equals to `val`.
/// If it does, `another_arg` will be marked as required.
///
/// **NOTE:** If using YAML the values should be laid out as follows
///
/// ```yaml
/// requires_if:
/// - [val, arg]
/// ```
/// **NOTE:** This argument is considered present when there is a [`Arg::default_value`]
///
/// # Examples
///
@ -1404,6 +1406,13 @@ impl<'help> Arg<'help> {
/// # ;
/// ```
///
/// If using YAML the values should be laid out as follows
///
/// ```yaml
/// requires_if:
/// - [val, arg]
/// ```
///
/// Setting `Arg::requires_if(val, arg)` requires that the `arg` be used at runtime if the
/// defining argument's value is equal to `val`. If the defining argument is anything other than
/// `val`, the other argument isn't required.
@ -1452,14 +1461,6 @@ impl<'help> Arg<'help> {
/// Allows multiple conditional requirements. The requirement will only become valid if this arg's value
/// equals `val`.
///
/// **NOTE:** If using YAML the values should be laid out as follows
///
/// ```yaml
/// requires_if:
/// - [val, arg]
/// - [val2, arg2]
/// ```
///
/// # Examples
///
/// ```rust
@ -1472,6 +1473,14 @@ impl<'help> Arg<'help> {
/// # ;
/// ```
///
/// If using YAML the values should be laid out as follows
///
/// ```yaml
/// requires_if:
/// - [val, arg]
/// - [val2, arg2]
/// ```
///
/// Setting `Arg::requires_ifs(&["val", "arg"])` requires that the `arg` be used at runtime if the
/// defining argument's value is equal to `val`. If the defining argument's value is anything other
/// than `val`, `arg` isn't required.
@ -1509,12 +1518,7 @@ impl<'help> Arg<'help> {
/// Allows specifying that this argument is [required] only if the specified
/// `arg` is present at runtime and its value equals `val`.
///
/// **NOTE:** If using YAML the values should be laid out as follows
///
/// ```yaml
/// required_if_eq:
/// - [arg, val]
/// ```
/// **NOTE:** This argument is considered present when there is a [`Arg::default_value`]
///
/// # Examples
///
@ -1525,6 +1529,13 @@ impl<'help> Arg<'help> {
/// # ;
/// ```
///
/// If using YAML the values should be laid out as follows
///
/// ```yaml
/// required_if_eq:
/// - [arg, val]
/// ```
///
/// ```rust
/// # use clap::{App, Arg, ErrorKind};
/// let res = App::new("prog")
@ -1607,14 +1618,6 @@ impl<'help> Arg<'help> {
/// conditions are set up in a `(arg, val)` style tuple. The requirement will only become valid
/// if one of the specified `arg`'s value equals its corresponding `val`.
///
/// **NOTE:** If using YAML the values should be laid out as follows
///
/// ```yaml
/// required_if_eq:
/// - [arg, val]
/// - [arg2, val2]
/// ```
///
/// # Examples
///
/// ```rust
@ -1627,6 +1630,14 @@ impl<'help> Arg<'help> {
/// # ;
/// ```
///
/// If using YAML the values should be laid out as follows
///
/// ```yaml
/// required_if_eq:
/// - [arg, val]
/// - [arg2, val2]
/// ```
///
/// Setting `Arg::required_if_eq_any(&[(arg, val)])` makes this arg required if any of the `arg`s
/// are used at runtime and it's corresponding value is equal to `val`. If the `arg`'s value is
/// anything other than `val`, this argument isn't required.
@ -1699,14 +1710,6 @@ impl<'help> Arg<'help> {
/// conditions are set up in a `(arg, val)` style tuple. The requirement will only become valid
/// if every one of the specified `arg`'s value equals its corresponding `val`.
///
/// **NOTE:** If using YAML the values should be laid out as follows
///
/// ```yaml
/// required_if_eq_all:
/// - [arg, val]
/// - [arg2, val2]
/// ```
///
/// # Examples
///
/// ```rust
@ -1719,6 +1722,14 @@ impl<'help> Arg<'help> {
/// # ;
/// ```
///
/// If using YAML the values should be laid out as follows
///
/// ```yaml
/// required_if_eq_all:
/// - [arg, val]
/// - [arg2, val2]
/// ```
///
/// Setting `Arg::required_if_eq_all(&[(arg, val)])` makes this arg required if all of the `arg`s
/// are used at runtime and every value is equal to its corresponding `val`. If the `arg`'s value is
/// anything other than `val`, this argument isn't required.
@ -1785,6 +1796,8 @@ impl<'help> Arg<'help> {
/// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required
/// by default.
///
/// **NOTE:** This argument is considered present when there is a [`Arg::default_value`]
///
/// # Examples
///
/// ```rust
@ -2356,12 +2369,6 @@ impl<'help> Arg<'help> {
/// The regular expression can either be borrowed or moved into `validator_regex`. This happens
/// automatically via [`RegexRef`]'s `Into` implementation.
///
/// **NOTE:** If using YAML then a single vector with two entries should be provided:
///
/// ```yaml
/// validator_regex: [remove-all-files, needs the exact phrase 'remove-all-files' to continue]
/// ```
///
/// # Performance
/// Regular expressions are expensive to compile. You should prefer sharing your regular expression.
/// We use a [`Cow`]-like internal structure to enable both sharing as well as taking ownership of a
@ -2406,6 +2413,11 @@ impl<'help> Arg<'help> {
/// assert!(res.is_err());
/// assert_eq!(res.err().unwrap().kind, ErrorKind::ValueValidation)
/// ```
///
/// If using YAML then a single vector with two entries should be provided:
/// ```yaml
/// validator_regex: [remove-all-files, needs the exact phrase 'remove-all-files' to continue]
/// ```
#[cfg(feature = "regex")]
pub fn validator_regex(
self,
@ -2955,14 +2967,6 @@ impl<'help> Arg<'help> {
///
/// **NOTE:** This implicitly sets [`Arg::takes_value(true)`].
///
/// **NOTE:** If using YAML the values should be laid out as follows (`None` can be represented
/// as `null` in YAML)
///
/// ```yaml
/// default_value_if:
/// - [arg, val, default]
/// ```
///
/// # Examples
///
/// First we use the default value only if another arg is present at runtime.
@ -2982,6 +2986,14 @@ impl<'help> Arg<'help> {
/// assert_eq!(m.value_of("other"), Some("default"));
/// ```
///
/// If using YAML the values should be laid out as follows (`None` can be represented
/// as `null` in YAML)
///
/// ```yaml
/// default_value_if:
/// - [arg, val, default]
/// ```
///
/// Next we run the same test, but without providing `--flag`.
///
/// ```rust
@ -3086,14 +3098,6 @@ impl<'help> Arg<'help> {
/// **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.
///
/// **NOTE:** If using YAML the values should be laid out as follows
///
/// ```yaml
/// default_value_if:
/// - [arg, val, default]
/// - [arg2, null, default2]
/// ```
///
/// # Examples
///
/// First we use the default value only if another arg is present at runtime.
@ -3119,6 +3123,14 @@ impl<'help> Arg<'help> {
/// assert_eq!(m.value_of("other"), Some("chan"));
/// ```
///
/// If using YAML the values should be laid out as follows
///
/// ```yaml
/// default_value_if:
/// - [arg, val, default]
/// - [arg2, null, default2]
/// ```
///
/// Next we run the same test, but without providing `--flag`.
///
/// ```rust

10
src/build/arg_group.rs
View file

@ -249,6 +249,8 @@ impl<'help> ArgGroup<'help> {
/// 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."
///
/// **NOTE:** An argument is considered present when there is a [`Arg::default_value`]
///
/// # Examples
///
/// ```rust
@ -284,6 +286,8 @@ impl<'help> ArgGroup<'help> {
///
/// **NOTE:** The name provided may be an argument, or group name
///
/// **NOTE:** An argument is considered present when there is a [`Arg::default_value`]
///
/// # Examples
///
/// ```rust
@ -319,6 +323,8 @@ impl<'help> ArgGroup<'help> {
///
/// **NOTE:** The names provided may be an argument, or group name
///
/// **NOTE:** An argument is considered present when there is a [`Arg::default_value`]
///
/// # Examples
///
/// ```rust
@ -357,6 +363,8 @@ impl<'help> ArgGroup<'help> {
///
/// **NOTE:** The name provided may be an argument, or group name
///
/// **NOTE:** An argument is considered present when there is a [`Arg::default_value`]
///
/// # Examples
///
/// ```rust
@ -389,6 +397,8 @@ impl<'help> ArgGroup<'help> {
///
/// **NOTE:** The names provided may be an argument, or group name
///
/// **NOTE:** An argument is considered present when there is a [`Arg::default_value`]
///
/// # Examples
///
/// ```rust