mirror of
https://github.com/clap-rs/clap
synced 2024-12-14 14:52:33 +00:00
docs: adds addtional blurbs about using multiples with subcommands
This commit is contained in:
parent
0c223f54ed
commit
03455b7751
1 changed files with 38 additions and 5 deletions
|
@ -1891,11 +1891,11 @@ impl<'a, 'b> Arg<'a, 'b> {
|
||||||
/// **WARNING:**
|
/// **WARNING:**
|
||||||
///
|
///
|
||||||
/// Setting `multiple(true)` for an [option] with no other details, allows multiple values
|
/// Setting `multiple(true)` for an [option] with no other details, allows multiple values
|
||||||
/// **and** multiple occurrences because it isn't possible to have more occurrences than values for
|
/// **and** multiple occurrences because it isn't possible to have more occurrences than values
|
||||||
/// options. Because multiple values are allowed, `--option val1 val2 val3` is perfectly valid,
|
/// for options. Because multiple values are allowed, `--option val1 val2 val3` is perfectly
|
||||||
/// be careful when designing a CLI where positional arguments are expected after a option which
|
/// valid, be careful when designing a CLI where positional arguments are expected after a
|
||||||
/// accepts multiple values, as `clap` will continue parsing *values* until it reaches the max
|
/// option which accepts multiple values, as `clap` will continue parsing *values* until it
|
||||||
/// or specific number of values defined, or another flag or option.
|
/// reaches the max or specific number of values defined, or another flag or option.
|
||||||
///
|
///
|
||||||
/// **Pro Tip**:
|
/// **Pro Tip**:
|
||||||
///
|
///
|
||||||
|
@ -1903,6 +1903,36 @@ impl<'a, 'b> Arg<'a, 'b> {
|
||||||
/// occurrence. To do this use [`Arg::number_of_values(1)`] in coordination with
|
/// occurrence. To do this use [`Arg::number_of_values(1)`] in coordination with
|
||||||
/// [`Arg::multiple(true)`].
|
/// [`Arg::multiple(true)`].
|
||||||
///
|
///
|
||||||
|
/// **WARNING:**
|
||||||
|
///
|
||||||
|
/// When using args with `multiple(true)` on [options] or [positionals] (i.e. those args that
|
||||||
|
/// accept values) and [subcommands], one needs to consider the posibility of an argument value
|
||||||
|
/// being the same as a valid subcommand. By default `clap` will parse the argument in question
|
||||||
|
/// as a value *only if* a value is possible at that moment. Otherwise it will be parsed as a
|
||||||
|
/// subcommand. In effect, this means using `multiple(true)` with no additional parameters and
|
||||||
|
/// a possible value that coincides with a subcommand name, the subcommand cannot be called
|
||||||
|
/// unless another argument is passed first.
|
||||||
|
///
|
||||||
|
/// As an example, consider a CLI with an option `--ui-paths=<paths>...` and subcommand `signer`
|
||||||
|
///
|
||||||
|
/// The following would be parsed as values to `--ui-paths`.
|
||||||
|
///
|
||||||
|
/// ```notrust
|
||||||
|
/// $ program --ui-paths path1 path2 signer
|
||||||
|
/// ```
|
||||||
|
///
|
||||||
|
/// This is because `--ui-paths` accepts multiple values. `clap` will continue parsing values
|
||||||
|
/// until another argument is reached and it knows `--ui-paths` is done.
|
||||||
|
///
|
||||||
|
/// By adding additional parameters to `--ui-paths` we can solve this issue. Consider adding
|
||||||
|
/// [`Arg::number_of_values(1)`] as discussed above. The following are all valid, and `signer`
|
||||||
|
/// is parsed as both a subcommand and a value in the second case.
|
||||||
|
///
|
||||||
|
/// ```notrust
|
||||||
|
/// $ program --ui-paths path1 signer
|
||||||
|
/// $ program --ui-paths path1 --ui-paths signer signer
|
||||||
|
/// ```
|
||||||
|
///
|
||||||
/// # Examples
|
/// # Examples
|
||||||
///
|
///
|
||||||
/// ```rust
|
/// ```rust
|
||||||
|
@ -2036,6 +2066,9 @@ impl<'a, 'b> Arg<'a, 'b> {
|
||||||
/// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
|
/// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
|
||||||
/// ```
|
/// ```
|
||||||
/// [option]: ./struct.Arg.html#method.takes_value
|
/// [option]: ./struct.Arg.html#method.takes_value
|
||||||
|
/// [options]: ./struct.Arg.html#method.takes_value
|
||||||
|
/// [subcommands]: ./struct.SubCommand.html
|
||||||
|
/// [positionals]: ./struct.Arg.html#method.index
|
||||||
/// [`Arg::number_of_values(1)`]: ./struct.Arg.html#method.number_of_values
|
/// [`Arg::number_of_values(1)`]: ./struct.Arg.html#method.number_of_values
|
||||||
/// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
|
/// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
|
||||||
pub fn multiple(self, multi: bool) -> Self {
|
pub fn multiple(self, multi: bool) -> Self {
|
||||||
|
|
Loading…
Reference in a new issue