Skip to content

Commit

Permalink
Merge clap-rs#2896
Browse files Browse the repository at this point in the history 
2896: docs: Clarify corner caseses with default values r=epage a=epage



Co-authored-by: Ed Page <eopage@gmail.com>
  • Loading branch information
@bors @epage
bors[bot] and epage committed Oct 25, 2021
2 parents d646288 + 45ef072 commit 29972e1
Show file tree
Hide file tree
Showing 2 changed files with 81 additions and 59 deletions.
130 changes: 71 additions & 59 deletions src/build/arg/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
///
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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
///
Expand All @@ -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")
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down
10 changes: 10 additions & 0 deletions src/build/arg_group.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 29972e1

Please sign in to comment.