mirror of
https://github.com/clap-rs/clap
synced 2024-12-14 23:02:31 +00:00
bfa02fd418
This ports our example testing over to [trycmd](https://docs.rs/) so we can: - More thoroughly test our examples - Provide always-up-to-date example usage The old way of testing automatically picked up examples. This new way requires we have a `.md` file that uses the example in some way. Notes: - Moved overall example description to the `.md` file - I added cross-linking between related examples - `14_groups` had a redundant paragraph (twice talked about "one and only one"
53 lines
2.2 KiB
Markdown
53 lines
2.2 KiB
Markdown
`ArgGroup`s are a family of related arguments and way for you to say, "Any of these arguments".
|
|
By placing arguments in a logical group, you can make easier requirement and exclusion rules
|
|
instead of having to list each individually, or when you want a rule to apply "any but not all"
|
|
arguments.
|
|
|
|
Perhaps the most common use of `ArgGroup`s is to require one and *only* one argument to be
|
|
present out of a given set. Imagine that you had multiple arguments, and you want one of them to
|
|
be required, but making all of them required isn't feasible because perhaps they conflict with
|
|
each other. For example, lets say that you were building an application where one could set a
|
|
given version number by supplying a string with an option argument, i.e. `--set-ver v1.2.3`, you
|
|
also wanted to support automatically using a previous version number and simply incrementing one
|
|
of the three numbers. So you create three flags `--major`, `--minor`, and `--patch`. All of
|
|
these arguments shouldn't be used at one time but you want to specify that *at least one* of
|
|
them is used. For this, you can create a group.
|
|
```bash
|
|
$ 14_groups
|
|
? failed
|
|
error: The following required arguments were not provided:
|
|
<--set-ver <ver>|--major|--minor|--patch>
|
|
|
|
USAGE:
|
|
14_groups[EXE] [OPTIONS] <--set-ver <ver>|--major|--minor|--patch> [INPUT_FILE]
|
|
|
|
For more information try --help
|
|
$ 14_groups --major
|
|
Version: 2.2.3
|
|
$ 14_groups --major --minor
|
|
? failed
|
|
error: The argument '--major' cannot be used with '--minor'
|
|
|
|
USAGE:
|
|
14_groups[EXE] [OPTIONS] <--set-ver <ver>|--major|--minor|--patch> [INPUT_FILE]
|
|
|
|
For more information try --help
|
|
```
|
|
|
|
You can also do things such as name an ArgGroup as a confliction or requirement, meaning any
|
|
of the arguments that belong to that group will cause a failure if present, or must present
|
|
respectively.
|
|
```bash
|
|
$ 14_groups --major -c config.toml
|
|
? failed
|
|
error: The following required arguments were not provided:
|
|
<INPUT_FILE|--spec-in <SPEC_IN>>
|
|
|
|
USAGE:
|
|
14_groups[EXE] -c <config> <--set-ver <ver>|--major|--minor|--patch> <INPUT_FILE|--spec-in <SPEC_IN>>
|
|
|
|
For more information try --help
|
|
$ 14_groups --major -c config.toml --spec-in input.txt
|
|
Version: 2.2.3
|
|
Doing work using input input.txt and config config.toml
|
|
```
|