diff options
Diffstat (limited to '')
| -rw-r--r-- | vendor/clap-3.2.20/examples/cargo-example-derive.md (renamed from vendor/clap/examples/cargo-example-derive.md) | 2 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/cargo-example-derive.rs (renamed from vendor/clap/examples/cargo-example-derive.rs) | 4 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/cargo-example.md (renamed from vendor/clap/examples/cargo-example.md) | 2 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/cargo-example.rs (renamed from vendor/clap/examples/cargo-example.rs) | 2 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/demo.md (renamed from vendor/clap/examples/demo.md) | 9 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/demo.rs (renamed from vendor/clap/examples/demo.rs) | 2 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/derive_ref/augment_subcommands.rs (renamed from vendor/clap/examples/derive_ref/augment_subcommands.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/derive_ref/custom-bool.md (renamed from vendor/clap/examples/derive_ref/custom-bool.md) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/derive_ref/custom-bool.rs (renamed from vendor/clap/examples/derive_ref/custom-bool.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/derive_ref/flatten_hand_args.rs (renamed from vendor/clap/examples/derive_ref/flatten_hand_args.rs) | 8 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/derive_ref/hand_subcommand.rs (renamed from vendor/clap/examples/derive_ref/hand_subcommand.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/derive_ref/interop_tests.md (renamed from vendor/clap/examples/derive_ref/interop_tests.md) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/escaped-positional-derive.md (renamed from vendor/clap/examples/escaped-positional-derive.md) | 4 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/escaped-positional-derive.rs (renamed from vendor/clap/examples/escaped-positional-derive.rs) | 4 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/escaped-positional.md (renamed from vendor/clap/examples/escaped-positional.md) | 4 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/escaped-positional.rs (renamed from vendor/clap/examples/escaped-positional.rs) | 9 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/git-derive.md (renamed from vendor/clap/examples/git-derive.md) | 4 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/git-derive.rs (renamed from vendor/clap/examples/git-derive.rs) | 4 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/git.md (renamed from vendor/clap/examples/git.md) | 2 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/multicall-busybox.md (renamed from vendor/clap/examples/multicall-busybox.md) | 6 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/multicall-busybox.rs (renamed from vendor/clap/examples/multicall-busybox.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/multicall-hostname.rs (renamed from vendor/clap/examples/multicall-hostname.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/pacman.md (renamed from vendor/clap/examples/pacman.md) | 2 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/repl.rs (renamed from vendor/clap/examples/repl.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_builder/01_quick.rs (renamed from vendor/clap/examples/tutorial_builder/01_quick.rs) | 4 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_builder/02_app_settings.rs (renamed from vendor/clap/examples/tutorial_builder/02_app_settings.rs) | 4 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_builder/02_apps.rs (renamed from vendor/clap/examples/tutorial_builder/02_apps.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_builder/03_04_subcommands.rs (renamed from vendor/clap/examples/tutorial_builder/03_04_subcommands.rs) | 4 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_builder/03_05_default_values.rs (renamed from vendor/clap/examples/tutorial_builder/03_05_default_values.rs) | 4 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_builder/04_01_possible.rs (renamed from vendor/clap/examples/tutorial_builder/04_01_possible.rs) | 4 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_builder/04_02_parse.rs (renamed from vendor/clap/examples/tutorial_builder/04_02_parse.rs) | 4 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_builder/04_02_validate.rs (renamed from vendor/clap/examples/tutorial_builder/04_02_validate.rs) | 4 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_builder/04_04_custom.rs (renamed from vendor/clap/examples/tutorial_builder/04_04_custom.rs) | 15 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_derive/01_quick.rs (renamed from vendor/clap/examples/tutorial_derive/01_quick.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_derive/02_app_settings.rs (renamed from vendor/clap/examples/tutorial_derive/02_app_settings.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_derive/02_apps.rs (renamed from vendor/clap/examples/tutorial_derive/02_apps.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_derive/03_01_flag_bool.rs (renamed from vendor/clap/examples/tutorial_derive/03_01_flag_bool.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_derive/03_01_flag_count.rs (renamed from vendor/clap/examples/tutorial_derive/03_01_flag_count.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_derive/03_02_option.rs (renamed from vendor/clap/examples/tutorial_derive/03_02_option.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_derive/03_03_positional.rs (renamed from vendor/clap/examples/tutorial_derive/03_03_positional.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_derive/03_04_subcommands.rs (renamed from vendor/clap/examples/tutorial_derive/03_04_subcommands.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_derive/03_04_subcommands_alt.rs (renamed from vendor/clap/examples/tutorial_derive/03_04_subcommands_alt.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_derive/03_05_default_values.rs (renamed from vendor/clap/examples/tutorial_derive/03_05_default_values.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_derive/04_02_parse.rs (renamed from vendor/clap/examples/tutorial_derive/04_02_parse.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_derive/04_02_validate.rs (renamed from vendor/clap/examples/tutorial_derive/04_02_validate.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/tutorial_derive/04_04_custom.rs (renamed from vendor/clap/examples/tutorial_derive/04_04_custom.rs) | 0 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/typed-derive.md (renamed from vendor/clap/examples/typed-derive.md) | 4 | ||||
| -rw-r--r-- | vendor/clap-3.2.20/examples/typed-derive.rs (renamed from vendor/clap/examples/typed-derive.rs) | 4 | ||||
| -rw-r--r-- | vendor/clap/examples/README.md | 40 | ||||
| -rw-r--r-- | vendor/clap/examples/derive_ref/README.md | 440 | ||||
| -rw-r--r-- | vendor/clap/examples/derive_ref/augment_args.rs | 30 | ||||
| -rw-r--r-- | vendor/clap/examples/git.rs | 103 | ||||
| -rw-r--r-- | vendor/clap/examples/multicall-hostname.md | 14 | ||||
| -rw-r--r-- | vendor/clap/examples/pacman.rs | 114 | ||||
| -rw-r--r-- | vendor/clap/examples/tutorial_builder/02_crate.rs | 19 | ||||
| -rw-r--r-- | vendor/clap/examples/tutorial_builder/03_01_flag_bool.rs | 21 | ||||
| -rw-r--r-- | vendor/clap/examples/tutorial_builder/03_01_flag_count.rs | 16 | ||||
| -rw-r--r-- | vendor/clap/examples/tutorial_builder/03_02_option.rs | 11 | ||||
| -rw-r--r-- | vendor/clap/examples/tutorial_builder/03_03_positional.rs | 9 | ||||
| -rw-r--r-- | vendor/clap/examples/tutorial_builder/04_01_enum.rs | 32 | ||||
| -rw-r--r-- | vendor/clap/examples/tutorial_builder/04_03_relations.rs | 82 | ||||
| -rw-r--r-- | vendor/clap/examples/tutorial_builder/05_01_assert.rs | 26 | ||||
| -rw-r--r-- | vendor/clap/examples/tutorial_builder/README.md | 658 | ||||
| -rw-r--r-- | vendor/clap/examples/tutorial_derive/02_crate.rs | 17 | ||||
| -rw-r--r-- | vendor/clap/examples/tutorial_derive/04_01_enum.rs | 28 | ||||
| -rw-r--r-- | vendor/clap/examples/tutorial_derive/04_03_relations.rs | 72 | ||||
| -rw-r--r-- | vendor/clap/examples/tutorial_derive/05_01_assert.rs | 21 | ||||
| -rw-r--r-- | vendor/clap/examples/tutorial_derive/README.md | 639 |
68 files changed, 31 insertions, 2480 deletions
diff --git a/vendor/clap/examples/cargo-example-derive.md b/vendor/clap-3.2.20/examples/cargo-example-derive.md index 994c6d4d8..2c7a11b88 100644 --- a/vendor/clap/examples/cargo-example-derive.md +++ b/vendor/clap-3.2.20/examples/cargo-example-derive.md @@ -1,5 +1,3 @@ -*Jump to [source](cargo-example-derive.rs)* - For more on creating a custom subcommand, see [the cargo book](https://doc.rust-lang.org/cargo/reference/external-tools.html#custom-subcommands). The crate [`clap-cargo`](https://github.com/crate-ci/clap-cargo) can help in diff --git a/vendor/clap/examples/cargo-example-derive.rs b/vendor/clap-3.2.20/examples/cargo-example-derive.rs index 6667a4a7d..f0aad29c7 100644 --- a/vendor/clap/examples/cargo-example-derive.rs +++ b/vendor/clap-3.2.20/examples/cargo-example-derive.rs @@ -1,8 +1,6 @@ -// Note: this requires the `derive` feature - use clap::Parser; -#[derive(Parser)] +#[derive(Parser)] // requires `derive` feature #[clap(name = "cargo")] #[clap(bin_name = "cargo")] enum Cargo { diff --git a/vendor/clap/examples/cargo-example.md b/vendor/clap-3.2.20/examples/cargo-example.md index 9279cc492..6fb6a3c4d 100644 --- a/vendor/clap/examples/cargo-example.md +++ b/vendor/clap-3.2.20/examples/cargo-example.md @@ -1,5 +1,3 @@ -*Jump to [source](cargo-example.rs)* - For more on creating a custom subcommand, see [the cargo book](https://doc.rust-lang.org/cargo/reference/external-tools.html#custom-subcommands). The crate [`clap-cargo`](https://github.com/crate-ci/clap-cargo) can help in diff --git a/vendor/clap/examples/cargo-example.rs b/vendor/clap-3.2.20/examples/cargo-example.rs index 45ae67c81..d9a909f4f 100644 --- a/vendor/clap/examples/cargo-example.rs +++ b/vendor/clap-3.2.20/examples/cargo-example.rs @@ -1,5 +1,3 @@ -// Note: this requires the `cargo` feature - fn main() { let cmd = clap::Command::new("cargo") .bin_name("cargo") diff --git a/vendor/clap/examples/demo.md b/vendor/clap-3.2.20/examples/demo.md index 9b0e7e260..93ee49c37 100644 --- a/vendor/clap/examples/demo.md +++ b/vendor/clap-3.2.20/examples/demo.md @@ -1,8 +1,3 @@ -*Jump to [source](demo.rs)* - -**This requires enabling the `derive` feature flag.** - -Used to validate README.md's content ```console $ demo --help clap [..] @@ -17,4 +12,8 @@ OPTIONS: -n, --name <NAME> Name of the person to greet -V, --version Print version information +$ demo --name Me +Hello Me! + ``` +*(version number and `.exe` extension on windows replaced by placeholders)* diff --git a/vendor/clap/examples/demo.rs b/vendor/clap-3.2.20/examples/demo.rs index 957489724..a7cecfb0c 100644 --- a/vendor/clap/examples/demo.rs +++ b/vendor/clap-3.2.20/examples/demo.rs @@ -1,5 +1,3 @@ -// Note: this requires the `derive` feature - use clap::Parser; /// Simple program to greet a person diff --git a/vendor/clap/examples/derive_ref/augment_subcommands.rs b/vendor/clap-3.2.20/examples/derive_ref/augment_subcommands.rs index 199da98b4..199da98b4 100644 --- a/vendor/clap/examples/derive_ref/augment_subcommands.rs +++ b/vendor/clap-3.2.20/examples/derive_ref/augment_subcommands.rs diff --git a/vendor/clap/examples/derive_ref/custom-bool.md b/vendor/clap-3.2.20/examples/derive_ref/custom-bool.md index 619f9ba8e..619f9ba8e 100644 --- a/vendor/clap/examples/derive_ref/custom-bool.md +++ b/vendor/clap-3.2.20/examples/derive_ref/custom-bool.md diff --git a/vendor/clap/examples/derive_ref/custom-bool.rs b/vendor/clap-3.2.20/examples/derive_ref/custom-bool.rs index d3c321e72..d3c321e72 100644 --- a/vendor/clap/examples/derive_ref/custom-bool.rs +++ b/vendor/clap-3.2.20/examples/derive_ref/custom-bool.rs diff --git a/vendor/clap/examples/derive_ref/flatten_hand_args.rs b/vendor/clap-3.2.20/examples/derive_ref/flatten_hand_args.rs index 74d10edec..c10e0b29f 100644 --- a/vendor/clap/examples/derive_ref/flatten_hand_args.rs +++ b/vendor/clap-3.2.20/examples/derive_ref/flatten_hand_args.rs @@ -15,8 +15,8 @@ impl FromArgMatches for CliArgs { } fn from_arg_matches_mut(matches: &mut ArgMatches) -> Result<Self, Error> { Ok(Self { - foo: *matches.get_one::<bool>("foo").expect("defaulted by clap"), - bar: *matches.get_one::<bool>("bar").expect("defaulted by clap"), + foo: matches.get_flag("foo"), + bar: matches.get_flag("bar"), quuz: matches.remove_one::<String>("quuz"), }) } @@ -25,8 +25,8 @@ impl FromArgMatches for CliArgs { self.update_from_arg_matches_mut(&mut matches) } fn update_from_arg_matches_mut(&mut self, matches: &mut ArgMatches) -> Result<(), Error> { - self.foo |= *matches.get_one::<bool>("foo").expect("defaulted by clap"); - self.bar |= *matches.get_one::<bool>("bar").expect("defaulted by clap"); + self.foo |= matches.get_flag("foo"); + self.bar |= matches.get_flag("bar"); if let Some(quuz) = matches.remove_one::<String>("quuz") { self.quuz = Some(quuz); } diff --git a/vendor/clap/examples/derive_ref/hand_subcommand.rs b/vendor/clap-3.2.20/examples/derive_ref/hand_subcommand.rs index e9423bdc0..e9423bdc0 100644 --- a/vendor/clap/examples/derive_ref/hand_subcommand.rs +++ b/vendor/clap-3.2.20/examples/derive_ref/hand_subcommand.rs diff --git a/vendor/clap/examples/derive_ref/interop_tests.md b/vendor/clap-3.2.20/examples/derive_ref/interop_tests.md index 746fe1878..746fe1878 100644 --- a/vendor/clap/examples/derive_ref/interop_tests.md +++ b/vendor/clap-3.2.20/examples/derive_ref/interop_tests.md diff --git a/vendor/clap/examples/escaped-positional-derive.md b/vendor/clap-3.2.20/examples/escaped-positional-derive.md index 3b5f8fe56..fa39a2c03 100644 --- a/vendor/clap/examples/escaped-positional-derive.md +++ b/vendor/clap-3.2.20/examples/escaped-positional-derive.md @@ -1,6 +1,4 @@ -*Jump to [source](escaped-positional-derive.rs)* - -**This requires enabling the `derive` feature flag.** +**This requires enabling the [`derive` feature flag][crate::_features].** You can use `--` to escape further arguments. diff --git a/vendor/clap/examples/escaped-positional-derive.rs b/vendor/clap-3.2.20/examples/escaped-positional-derive.rs index 54dbc853b..fd8fde4ed 100644 --- a/vendor/clap/examples/escaped-positional-derive.rs +++ b/vendor/clap-3.2.20/examples/escaped-positional-derive.rs @@ -1,8 +1,6 @@ -// Note: this requires the `derive` feature - use clap::Parser; -#[derive(Parser)] +#[derive(Parser)] // requires `derive` feature #[clap(author, version, about, long_about = None)] struct Cli { #[clap(short = 'f', action)] diff --git a/vendor/clap/examples/escaped-positional.md b/vendor/clap-3.2.20/examples/escaped-positional.md index 1f71a8736..987b26139 100644 --- a/vendor/clap/examples/escaped-positional.md +++ b/vendor/clap-3.2.20/examples/escaped-positional.md @@ -1,6 +1,4 @@ -*Jump to [source](escaped-positional.rs)* - -**This requires enabling the `cargo` feature flag.** +**This requires enabling the [`cargo` feature flag][crate::_features].** You can use `--` to escape further arguments. diff --git a/vendor/clap/examples/escaped-positional.rs b/vendor/clap-3.2.20/examples/escaped-positional.rs index a0fff790b..fdcb930fb 100644 --- a/vendor/clap/examples/escaped-positional.rs +++ b/vendor/clap-3.2.20/examples/escaped-positional.rs @@ -1,9 +1,7 @@ -// Note: this requires the `cargo` feature - use clap::{arg, command, value_parser, ArgAction}; fn main() { - let matches = command!() + let matches = command!() // requires `cargo` feature .arg(arg!(eff: -f).action(ArgAction::SetTrue)) .arg( arg!(pea: -p <PEAR>) @@ -22,10 +20,7 @@ fn main() { // This is what will happen with `myprog -f -p=bob -- sloppy slop slop`... // -f used: true - println!( - "-f used: {:?}", - *matches.get_one::<bool>("eff").expect("defaulted by clap") - ); + println!("-f used: {:?}", matches.get_flag("eff")); // -p's value: Some("bob") println!("-p's value: {:?}", matches.get_one::<String>("pea")); // 'slops' values: Some(["sloppy", "slop", "slop"]) diff --git a/vendor/clap/examples/git-derive.md b/vendor/clap-3.2.20/examples/git-derive.md index dc27776f5..aa1ca6d9d 100644 --- a/vendor/clap/examples/git-derive.md +++ b/vendor/clap-3.2.20/examples/git-derive.md @@ -1,6 +1,4 @@ -*Jump to [source](git-derive.rs)* - -**This requires enabling the `derive` feature flag.** +**This requires enabling the [`derive` feature flag][crate::_features].** Git is an example of several common subcommand patterns. diff --git a/vendor/clap/examples/git-derive.rs b/vendor/clap-3.2.20/examples/git-derive.rs index ecbda3fe9..ac500ddad 100644 --- a/vendor/clap/examples/git-derive.rs +++ b/vendor/clap-3.2.20/examples/git-derive.rs @@ -1,12 +1,10 @@ -// Note: this requires the `derive` feature - use std::ffi::OsString; use std::path::PathBuf; use clap::{Args, Parser, Subcommand}; /// A fictional versioning CLI -#[derive(Debug, Parser)] +#[derive(Debug, Parser)] // requires `derive` feature #[clap(name = "git")] #[clap(about = "A fictional versioning CLI", long_about = None)] struct Cli { diff --git a/vendor/clap/examples/git.md b/vendor/clap-3.2.20/examples/git.md index 2cdfe653b..9e413415a 100644 --- a/vendor/clap/examples/git.md +++ b/vendor/clap-3.2.20/examples/git.md @@ -1,5 +1,3 @@ -*Jump to [source](git.rs)* - Git is an example of several common subcommand patterns. Help: diff --git a/vendor/clap/examples/multicall-busybox.md b/vendor/clap-3.2.20/examples/multicall-busybox.md index a09418403..5ca2cad5b 100644 --- a/vendor/clap/examples/multicall-busybox.md +++ b/vendor/clap-3.2.20/examples/multicall-busybox.md @@ -1,8 +1,4 @@ -*Jump to [source](multicall-busybox.rs)* - -Example of a busybox-style multicall program - -See the documentation for `clap::Command::multicall` for rationale. +See the documentation for [`Command::multicall`][crate::App::multicall] for rationale. This example omits every command except true and false, which are the most trivial to implement, diff --git a/vendor/clap/examples/multicall-busybox.rs b/vendor/clap-3.2.20/examples/multicall-busybox.rs index 2e7f976c1..2e7f976c1 100644 --- a/vendor/clap/examples/multicall-busybox.rs +++ b/vendor/clap-3.2.20/examples/multicall-busybox.rs diff --git a/vendor/clap/examples/multicall-hostname.rs b/vendor/clap-3.2.20/examples/multicall-hostname.rs index b57680a5c..b57680a5c 100644 --- a/vendor/clap/examples/multicall-hostname.rs +++ b/vendor/clap-3.2.20/examples/multicall-hostname.rs diff --git a/vendor/clap/examples/pacman.md b/vendor/clap-3.2.20/examples/pacman.md index 7f6c5a7d3..b8ddd09d9 100644 --- a/vendor/clap/examples/pacman.md +++ b/vendor/clap-3.2.20/examples/pacman.md @@ -1,5 +1,3 @@ -*Jump to [source](pacman.rs)* - [`pacman`](https://wiki.archlinux.org/index.php/pacman) defines subcommands via flags. Here, `-S` is a short flag subcommand: diff --git a/vendor/clap/examples/repl.rs b/vendor/clap-3.2.20/examples/repl.rs index c509adee6..c509adee6 100644 --- a/vendor/clap/examples/repl.rs +++ b/vendor/clap-3.2.20/examples/repl.rs diff --git a/vendor/clap/examples/tutorial_builder/01_quick.rs b/vendor/clap-3.2.20/examples/tutorial_builder/01_quick.rs index 61cc3432d..393d6aeae 100644 --- a/vendor/clap/examples/tutorial_builder/01_quick.rs +++ b/vendor/clap-3.2.20/examples/tutorial_builder/01_quick.rs @@ -1,11 +1,9 @@ -// Note: this requires the `cargo` feature - use std::path::PathBuf; use clap::{arg, command, value_parser, ArgAction, Command}; fn main() { - let matches = command!() + let matches = command!() // requires `cargo` feature .arg(arg!([name] "Optional name to operate on")) .arg( arg!( diff --git a/vendor/clap/examples/tutorial_builder/02_app_settings.rs b/vendor/clap-3.2.20/examples/tutorial_builder/02_app_settings.rs index 7bbedd3eb..5f374d7f0 100644 --- a/vendor/clap/examples/tutorial_builder/02_app_settings.rs +++ b/vendor/clap-3.2.20/examples/tutorial_builder/02_app_settings.rs @@ -1,9 +1,7 @@ -// Note: this requires the `cargo` feature - use clap::{arg, command, AppSettings, ArgAction}; fn main() { - let matches = command!() + let matches = command!() // requires `cargo` feature .global_setting(AppSettings::DeriveDisplayOrder) .allow_negative_numbers(true) .arg(arg!(--two <VALUE>).action(ArgAction::Set)) diff --git a/vendor/clap/examples/tutorial_builder/02_apps.rs b/vendor/clap-3.2.20/examples/tutorial_builder/02_apps.rs index db9da18f9..db9da18f9 100644 --- a/vendor/clap/examples/tutorial_builder/02_apps.rs +++ b/vendor/clap-3.2.20/examples/tutorial_builder/02_apps.rs diff --git a/vendor/clap/examples/tutorial_builder/03_04_subcommands.rs b/vendor/clap-3.2.20/examples/tutorial_builder/03_04_subcommands.rs index 1dd1cbf09..fbe23809e 100644 --- a/vendor/clap/examples/tutorial_builder/03_04_subcommands.rs +++ b/vendor/clap-3.2.20/examples/tutorial_builder/03_04_subcommands.rs @@ -1,9 +1,7 @@ -// Note: this requires the `cargo` feature - use clap::{arg, command, Command}; fn main() { - let matches = command!() + let matches = command!() // requires `cargo` feature .propagate_version(true) .subcommand_required(true) .arg_required_else_help(true) diff --git a/vendor/clap/examples/tutorial_builder/03_05_default_values.rs b/vendor/clap-3.2.20/examples/tutorial_builder/03_05_default_values.rs index c68e87973..cb3e3831f 100644 --- a/vendor/clap/examples/tutorial_builder/03_05_default_values.rs +++ b/vendor/clap-3.2.20/examples/tutorial_builder/03_05_default_values.rs @@ -1,9 +1,7 @@ -// Note: this requires the `cargo` feature - use clap::{arg, command}; fn main() { - let matches = command!() + let matches = command!() // requires `cargo` feature .arg(arg!([NAME]).default_value("alice")) .get_matches(); diff --git a/vendor/clap/examples/tutorial_builder/04_01_possible.rs b/vendor/clap-3.2.20/examples/tutorial_builder/04_01_possible.rs index f7b0cfb34..3da7aca74 100644 --- a/vendor/clap/examples/tutorial_builder/04_01_possible.rs +++ b/vendor/clap-3.2.20/examples/tutorial_builder/04_01_possible.rs @@ -1,9 +1,7 @@ -// Note: this requires the `cargo` feature - use clap::{arg, command}; fn main() { - let matches = command!() + let matches = command!() // requires `cargo` feature .arg( arg!(<MODE>) .help("What mode to run the program in") diff --git a/vendor/clap/examples/tutorial_builder/04_02_parse.rs b/vendor/clap-3.2.20/examples/tutorial_builder/04_02_parse.rs index c2f3cc533..13f41a18e 100644 --- a/vendor/clap/examples/tutorial_builder/04_02_parse.rs +++ b/vendor/clap-3.2.20/examples/tutorial_builder/04_02_parse.rs @@ -1,9 +1,7 @@ -// Note: this requires the `cargo` feature - use clap::{arg, command, value_parser}; fn main() { - let matches = command!() + let matches = command!() // requires `cargo` feature .arg( arg!(<PORT>) .help("Network port to use") diff --git a/vendor/clap/examples/tutorial_builder/04_02_validate.rs b/vendor/clap-3.2.20/examples/tutorial_builder/04_02_validate.rs index e60018a46..ea2f32e67 100644 --- a/vendor/clap/examples/tutorial_builder/04_02_validate.rs +++ b/vendor/clap-3.2.20/examples/tutorial_builder/04_02_validate.rs @@ -1,11 +1,9 @@ -// Note: this requires the `cargo` feature - use std::ops::RangeInclusive; use clap::{arg, command}; fn main() { - let matches = command!() + let matches = command!() // requires `cargo` feature .arg( arg!(<PORT>) .help("Network port to use") diff --git a/vendor/clap/examples/tutorial_builder/04_04_custom.rs b/vendor/clap-3.2.20/examples/tutorial_builder/04_04_custom.rs index 3dc080505..fb40b2fc4 100644 --- a/vendor/clap/examples/tutorial_builder/04_04_custom.rs +++ b/vendor/clap-3.2.20/examples/tutorial_builder/04_04_custom.rs @@ -1,12 +1,10 @@ -// Note: this requires the `cargo` feature - use std::path::PathBuf; use clap::{arg, command, value_parser, ArgAction, ErrorKind}; fn main() { // Create application like normal - let mut cmd = command!() + let mut cmd = command!() // requires `cargo` feature // Add the version arguments .arg(arg!(--"set-ver" <VER> "set version manually").required(false)) .arg(arg!(--major "auto inc major").action(ArgAction::SetTrue)) @@ -36,10 +34,7 @@ fn main() { // See if --set-ver was used to set the version manually let version = if let Some(ver) = matches.get_one::<String>("set-ver") { - if *matches.get_one::<bool>("major").expect("defaulted by clap") - || *matches.get_one::<bool>("minor").expect("defaulted by clap") - || *matches.get_one::<bool>("patch").expect("defaulted by clap") - { + if matches.get_flag("major") || matches.get_flag("minor") || matches.get_flag("patch") { cmd.error( ErrorKind::ArgumentConflict, "Can't do relative and absolute version change", @@ -50,9 +45,9 @@ fn main() { } else { // Increment the one requested (in a real program, we'd reset the lower numbers) let (maj, min, pat) = ( - *matches.get_one::<bool>("major").expect("defaulted by clap"), - *matches.get_one::<bool>("minor").expect("defaulted by clap"), - *matches.get_one::<bool>("patch").expect("defaulted by clap"), + matches.get_flag("major"), + matches.get_flag("minor"), + matches.get_flag("patch"), ); match (maj, min, pat) { (true, false, false) => major += 1, diff --git a/vendor/clap/examples/tutorial_derive/01_quick.rs b/vendor/clap-3.2.20/examples/tutorial_derive/01_quick.rs index 2c2031061..2c2031061 100644 --- a/vendor/clap/examples/tutorial_derive/01_quick.rs +++ b/vendor/clap-3.2.20/examples/tutorial_derive/01_quick.rs diff --git a/vendor/clap/examples/tutorial_derive/02_app_settings.rs b/vendor/clap-3.2.20/examples/tutorial_derive/02_app_settings.rs index 6a06929bb..6a06929bb 100644 --- a/vendor/clap/examples/tutorial_derive/02_app_settings.rs +++ b/vendor/clap-3.2.20/examples/tutorial_derive/02_app_settings.rs diff --git a/vendor/clap/examples/tutorial_derive/02_apps.rs b/vendor/clap-3.2.20/examples/tutorial_derive/02_apps.rs index b97ce1eed..b97ce1eed 100644 --- a/vendor/clap/examples/tutorial_derive/02_apps.rs +++ b/vendor/clap-3.2.20/examples/tutorial_derive/02_apps.rs diff --git a/vendor/clap/examples/tutorial_derive/03_01_flag_bool.rs b/vendor/clap-3.2.20/examples/tutorial_derive/03_01_flag_bool.rs index de677d8c6..de677d8c6 100644 --- a/vendor/clap/examples/tutorial_derive/03_01_flag_bool.rs +++ b/vendor/clap-3.2.20/examples/tutorial_derive/03_01_flag_bool.rs diff --git a/vendor/clap/examples/tutorial_derive/03_01_flag_count.rs b/vendor/clap-3.2.20/examples/tutorial_derive/03_01_flag_count.rs index 680f7f5e5..680f7f5e5 100644 --- a/vendor/clap/examples/tutorial_derive/03_01_flag_count.rs +++ b/vendor/clap-3.2.20/examples/tutorial_derive/03_01_flag_count.rs diff --git a/vendor/clap/examples/tutorial_derive/03_02_option.rs b/vendor/clap-3.2.20/examples/tutorial_derive/03_02_option.rs index 75b67afe7..75b67afe7 100644 --- a/vendor/clap/examples/tutorial_derive/03_02_option.rs +++ b/vendor/clap-3.2.20/examples/tutorial_derive/03_02_option.rs diff --git a/vendor/clap/examples/tutorial_derive/03_03_positional.rs b/vendor/clap-3.2.20/examples/tutorial_derive/03_03_positional.rs index 7478951f1..7478951f1 100644 --- a/vendor/clap/examples/tutorial_derive/03_03_positional.rs +++ b/vendor/clap-3.2.20/examples/tutorial_derive/03_03_positional.rs diff --git a/vendor/clap/examples/tutorial_derive/03_04_subcommands.rs b/vendor/clap-3.2.20/examples/tutorial_derive/03_04_subcommands.rs index 62a45a97e..62a45a97e 100644 --- a/vendor/clap/examples/tutorial_derive/03_04_subcommands.rs +++ b/vendor/clap-3.2.20/examples/tutorial_derive/03_04_subcommands.rs diff --git a/vendor/clap/examples/tutorial_derive/03_04_subcommands_alt.rs b/vendor/clap-3.2.20/examples/tutorial_derive/03_04_subcommands_alt.rs index b6124936c..b6124936c 100644 --- a/vendor/clap/examples/tutorial_derive/03_04_subcommands_alt.rs +++ b/vendor/clap-3.2.20/examples/tutorial_derive/03_04_subcommands_alt.rs diff --git a/vendor/clap/examples/tutorial_derive/03_05_default_values.rs b/vendor/clap-3.2.20/examples/tutorial_derive/03_05_default_values.rs index 10a1ec808..10a1ec808 100644 --- a/vendor/clap/examples/tutorial_derive/03_05_default_values.rs +++ b/vendor/clap-3.2.20/examples/tutorial_derive/03_05_default_values.rs diff --git a/vendor/clap/examples/tutorial_derive/04_02_parse.rs b/vendor/clap-3.2.20/examples/tutorial_derive/04_02_parse.rs index 6336a9cf1..6336a9cf1 100644 --- a/vendor/clap/examples/tutorial_derive/04_02_parse.rs +++ b/vendor/clap-3.2.20/examples/tutorial_derive/04_02_parse.rs diff --git a/vendor/clap/examples/tutorial_derive/04_02_validate.rs b/vendor/clap-3.2.20/examples/tutorial_derive/04_02_validate.rs index 7dac79c9f..7dac79c9f 100644 --- a/vendor/clap/examples/tutorial_derive/04_02_validate.rs +++ b/vendor/clap-3.2.20/examples/tutorial_derive/04_02_validate.rs diff --git a/vendor/clap/examples/tutorial_derive/04_04_custom.rs b/vendor/clap-3.2.20/examples/tutorial_derive/04_04_custom.rs index 454d489c1..454d489c1 100644 --- a/vendor/clap/examples/tutorial_derive/04_04_custom.rs +++ b/vendor/clap-3.2.20/examples/tutorial_derive/04_04_custom.rs diff --git a/vendor/clap/examples/typed-derive.md b/vendor/clap-3.2.20/examples/typed-derive.md index 7c61f70d9..9c7615c63 100644 --- a/vendor/clap/examples/typed-derive.md +++ b/vendor/clap-3.2.20/examples/typed-derive.md @@ -1,6 +1,4 @@ -*Jump to [source](typed-derive.rs)* - -**This requires enabling the `derive` feature flag.** +**This requires enabling the [`derive` feature flag][crate::_features].** Help: ```console diff --git a/vendor/clap/examples/typed-derive.rs b/vendor/clap-3.2.20/examples/typed-derive.rs index 85c750f9c..31084029d 100644 --- a/vendor/clap/examples/typed-derive.rs +++ b/vendor/clap-3.2.20/examples/typed-derive.rs @@ -1,9 +1,7 @@ -// Note: this requires the `derive` feature - use clap::Parser; use std::error::Error; -#[derive(Parser, Debug)] +#[derive(Parser, Debug)] // requires `derive` feature struct Args { /// Implicitly using `std::str::FromStr` #[clap(short = 'O', value_parser)] diff --git a/vendor/clap/examples/README.md b/vendor/clap/examples/README.md deleted file mode 100644 index 2034ab80e..000000000 --- a/vendor/clap/examples/README.md +++ /dev/null @@ -1,40 +0,0 @@ -# Examples - -- Basic demo: [derive](demo.md) -- Typed arguments: [derive](typed-derive.md) - - Topics: - - Custom `parse()` -- Custom cargo command: [builder](cargo-example.md), [derive](cargo-example-derive.md) - - Topics: - - Subcommands - - Cargo plugins -- git-like interface: [builder](git.md), [derive](git-derive.md) - - Topics: - - Subcommands - - External subcommands - - Optional subcommands - - Default subcommands -- pacman-like interface: [builder](pacman.md) - - Topics: - - Flag subcommands - - Conflicting arguments -- Escaped positionals with `--`: [builder](escaped-positional.md), [derive](escaped-positional-derive.md) -- Multi-call - - busybox: [builder](multicall-busybox.md) - - Topics: - - Subcommands - - hostname: [builder](multicall-hostname.md) - - Topics: - - Subcommands -- repl: [builder](repl.rs) - - Topics: - - Read-Eval-Print Loops / Custom command lines - -## Contributing - -New examples: -- Building: They must be added to [Cargo.toml](../Cargo.toml) with the appropriate `required-features`. -- Testing: Ensure there is a markdown file with [trycmd](https://docs.rs/trycmd) syntax -- Link the `.md` file from here - -See also the general [CONTRIBUTING](../CONTRIBUTING.md). diff --git a/vendor/clap/examples/derive_ref/README.md b/vendor/clap/examples/derive_ref/README.md deleted file mode 100644 index a3b0c084d..000000000 --- a/vendor/clap/examples/derive_ref/README.md +++ /dev/null @@ -1,440 +0,0 @@ -# Derive Reference - -1. [Overview](#overview) -2. [Attributes](#attributes) - 1. [Terminology](#terminology) - 2. [Command Attributes](#command-attributes) - 3. [Arg Attributes](#arg-attributes) - 4. [Arg Enum Attributes](#arg-enum-attributes) - 5. [Possible Value Attributes](#possible-value-attributes) -3. [Arg Types](#arg-types) -4. [Doc Comments](#doc-comments) -5. [Tips](#tips) -6. [Mixing Builder and Derive APIS](#mixing-builder-and-derive-apis) - -## Overview - -To derive `clap` types, you need to enable the `derive` feature flag. - -See [demo.rs](../demo.rs) and [demo.md](../demo.md) for a brief example. - -Let's start by breaking down the anatomy of the derive attributes: -```rust -use clap::{Parser, Args, Subcommand, ValueEnum}; - -/// Doc comment -#[derive(Parser)] -#[clap(APP ATTRIBUTE)] -struct Cli { - /// Doc comment - #[clap(ARG ATTRIBUTE)] - field: UserType, - - #[clap(value_enum, ARG ATTRIBUTE...)] - field: EnumValues, - - #[clap(flatten)] - delegate: Struct, - - #[clap(subcommand)] - command: Command, -} - -/// Doc comment -#[derive(Args)] -#[clap(PARENT APP ATTRIBUTE)] -struct Struct { - /// Doc comment - #[clap(ARG ATTRIBUTE)] - field: UserType, -} - -/// Doc comment -#[derive(Subcommand)] -#[clap(PARENT APP ATTRIBUTE)] -enum Command { - /// Doc comment - #[clap(APP ATTRIBUTE)] - Variant1(Struct), - - /// Doc comment - #[clap(APP ATTRIBUTE)] - Variant2 { - /// Doc comment - #[clap(ARG ATTRIBUTE)] - field: UserType, - } -} - -/// Doc comment -#[derive(ValueEnum)] -#[clap(ARG ENUM ATTRIBUTE)] -enum EnumValues { - /// Doc comment - #[clap(POSSIBLE VALUE ATTRIBUTE)] - Variant1, -} - -fn main() { - let cli = Cli::parse(); -} -``` - -- `Parser` parses arguments into a `struct` (arguments) or `enum` (subcommands). -- `Args` allows defining a set of re-usable arguments that get merged into their parent container. -- `Subcommand` defines available subcommands. - - Subcommand arguments can be defined in a struct-variant or automatically flattened with a tuple-variant. -- `ValueEnum` allows parsing a value directly into an `enum`, erroring on unsupported values. - - The derive doesn't work on enums that contain non-unit variants, unless they are skipped - -See also the [tutorial](../tutorial_derive/README.md) and [examples](../README.md). - -## Attributes - -### Terminology - -**Raw attributes** are forwarded directly to the underlying `clap` builder. Any -`Command`, `Arg`, or `PossibleValue` method can be used as an attribute. - -Raw attributes come in two different syntaxes: -```rust -#[clap( - global = true, // name = arg form, neat for one-arg methods - required_if_eq("out", "file") // name(arg1, arg2, ...) form. -)] -``` - -- `method = arg` can only be used for methods which take only one argument. -- `method(arg1, arg2)` can be used with any method. - -As long as `method_name` is not one of the magical methods - it will be -translated into a mere method call. - -**Magic attributes** have post-processing done to them, whether that is -- Providing of defaults -- Special behavior is triggered off of it - -Magic attributes are more constrained in the syntax they support, usually just -`<attr> = <value>` though some use `<attr>(<value>)` instead. See the specific -magic attributes documentation for details. This allows users to access the -raw behavior of an attribute via `<attr>(<value>)` syntax. - -**NOTE:** Some attributes are inferred from [Arg Types](#arg-types) and [Doc -Comments](#doc-comments). Explicit attributes take precedence over inferred -attributes. - -### Command Attributes - -These correspond to a `clap::Command` which is used for both top-level parsers and -when defining subcommands. - -**Raw attributes:** Any [`Command` method](https://docs.rs/clap/latest/clap/type.Command.html) can also be used as an attribute, see [Terminology](#terminology) for syntax. -- e.g. `#[clap(arg_required_else_help(true))]` would translate to `cmd.arg_required_else_help(true)` - -**Magic attributes:** -- `name = <expr>`: `clap::Command::name` - - When not present: [crate `name`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-name-field) (`Parser` container), variant name (`Subcommand` variant) -- `version [= <expr>]`: `clap::Command::version` - - When not present: no version set - - Without `<expr>`: defaults to [crate `version`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-version-field) -- `author [= <expr>]`: `clap::Command::author` - - When not present: no author set - - Without `<expr>`: defaults to [crate `authors`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-authors-field) -- `about [= <expr>]`: `clap::Command::about` - - When not present: [Doc comment summary](#doc-comments) - - Without `<expr>`: [crate `description`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-description-field) (`Parser` container) - - **TIP:** When a doc comment is also present, you most likely want to add - `#[clap(long_about = None)]` to clear the doc comment so only `about` - gets shown with both `-h` and `--help`. -- `long_about = <expr>`: `clap::Command::long_about` - - When not present: [Doc comment](#doc-comments) if there is a blank line, else nothing -- `verbatim_doc_comment`: Minimizes pre-processing when converting doc comments to `about` / `long_about` -- `next_display_order`: `clap::Command::next_display_order` -- `next_help_heading`: `clap::Command::next_help_heading` - - When `flatten`ing `Args`, this is scoped to just the args in this struct and any struct `flatten`ed into it -- `rename_all = <expr>`: Override default field / variant name case conversion for `Command::name` / `Arg::name` - - When not present: `kebab-case` - - Available values: `camelCase`, `kebab-case`, `PascalCase`, `SCREAMING_SNAKE_CASE`, `snake_case`, `lower`, `UPPER`, `verbatim` -- `rename_all_env = <expr>`: Override default field name case conversion for env variables for `clap::Arg::env` - - When not present: `SCREAMING_SNAKE_CASE` - - Available values: `camelCase`, `kebab-case`, `PascalCase`, `SCREAMING_SNAKE_CASE`, `snake_case`, `lower`, `UPPER`, `verbatim` - -And for `Subcommand` variants: -- `skip`: Ignore this variant -- `flatten`: Delegates to the variant for more subcommands (must implement `Subcommand`) -- `subcommand`: Nest subcommands under the current set of subcommands (must implement `Subcommand`) -- `external_subcommand`: `clap::Command::allow_external_subcommand(true)` - - Variant must be either `Variant(Vec<String>)` or `Variant(Vec<OsString>)` - -### Arg Attributes - -These correspond to a `clap::Arg`. - -**Raw attributes:** Any [`Arg` method](https://docs.rs/clap/latest/clap/struct.Arg.html) can also be used as an attribute, see [Terminology](#terminology) for syntax. -- e.g. `#[clap(max_values(3))]` would translate to `arg.max_values(3)` - -**Magic attributes**: -- `name = <expr>`: `clap::Arg::new` - - When not present: case-converted field name is used -- `value_parser [= <expr>]`: `clap::Arg::value_parser` - - When not present: will auto-select an implementation based on the field type - - To register a custom type's `ValueParser`, implement `ValueParserFactory` - - When present, implies `#[clap(action)]` -- `action [= <expr>]`: `clap::Arg::action` - - When not present: will auto-select an action based on the field type - - When present, implies `#[clap(value_parser)]` -- `help = <expr>`: `clap::Arg::help` - - When not present: [Doc comment summary](#doc-comments) -- `long_help = <expr>`: `clap::Arg::long_help` - - When not present: [Doc comment](#doc-comments) if there is a blank line, else nothing -- `verbatim_doc_comment`: Minimizes pre-processing when converting doc comments to `help` / `long_help` -- `short [= <char>]`: `clap::Arg::short` - - When not present: no short set - - Without `<char>`: defaults to first character in the case-converted field name -- `long [= <str>]`: `clap::Arg::long` - - When not present: no long set - - Without `<str>`: defaults to the case-converted field name -- `env [= <str>]`: `clap::Arg::env` (needs `env` feature enabled) - - When not present: no env set - - Without `<str>`: defaults to the case-converted field name -- `flatten`: Delegates to the field for more arguments (must implement `Args`) - - Only `help_heading` can be used with `flatten`. See - [clap-rs/clap#3269](https://github.com/clap-rs/clap/issues/3269) for why - arg attributes are not generally supported. - - **Tip:** Though we do apply a flattened `Args`'s Parent Command Attributes, this - makes reuse harder. Generally prefer putting the cmd attributes on the `Parser` - or on the flattened field. -- `subcommand`: Delegates definition of subcommands to the field (must implement `Subcommand`) - - When `Option<T>`, the subcommand becomes optional -- `from_global`: Read a `clap::Arg::global` argument (raw attribute), regardless of what subcommand you are in -- `parse(<kind> [= <function>])`: `clap::Arg::validator` and `clap::ArgMatches::values_of_t` - - **Deprecated:** - - Use `value_parser(...)` for `from_str`, `try_from_str`, `from_os_str`, and `try_from_os_str` - - Use `action(ArgAction::Count` for `from_occurrences` - - Use `action(ArgAction::SetTrue` for `from_flag` - - Default: `try_from_str` - - Warning: for `Path` / `OsString`, be sure to use `try_from_os_str` - - See [Arg Types](#arg-types) for more details -- `value_enum`: Parse the value using the `ValueEnum` trait -- `skip [= <expr>]`: Ignore this field, filling in with `<expr>` - - Without `<expr>`: fills the field with `Default::default()` -- `default_value = <str>`: `clap::Arg::default_value` and `clap::Arg::required(false)` -- `default_value_t [= <expr>]`: `clap::Arg::default_value` and `clap::Arg::required(false)` - - Requires `std::fmt::Display` or `#[clap(value_enum)]` - - Without `<expr>`, relies on `Default::default()` -- `default_value_os_t [= <expr>]`: `clap::Arg::default_value_os` and `clap::Arg::required(false)` - - Requires `std::convert::Into<OsString>` or `#[clap(value_enum)]` - - Without `<expr>`, relies on `Default::default()` - -### Arg Enum Attributes - -- `rename_all = <expr>`: Override default field / variant name case conversion for `PossibleValue::new` - - When not present: `kebab-case` - - Available values: `camelCase`, `kebab-case`, `PascalCase`, `SCREAMING_SNAKE_CASE`, `snake_case`, `lower`, `UPPER`, `verbatim` - -### Possible Value Attributes - -These correspond to a `clap::PossibleValue`. - -**Raw attributes:** Any [`PossibleValue` method](https://docs.rs/clap/latest/clap/struct.PossibleValue.html) can also be used as an attribute, see [Terminology](#terminology) for syntax. -- e.g. `#[clap(alias("foo"))]` would translate to `pv.alias("foo")` - -**Magic attributes**: -- `name = <expr>`: `clap::PossibleValue::new` - - When not present: case-converted field name is used -- `help = <expr>`: `clap::PossibleValue::help` - - When not present: [Doc comment summary](#doc-comments) - -## Arg Types - -`clap` assumes some intent based on the type used: - -| Type | Effect | Implies | -|---------------------|--------------------------------------|------------------------------------------------------------------| -| `bool` | flag | `#[clap(parse(from_flag))]` | -| `Option<T>` | optional argument | `.takes_value(true).required(false)` | -| `Option<Option<T>>` | optional value for optional argument | `.takes_value(true).required(false).min_values(0).max_values(1)` | -| `T` | required argument | `.takes_value(true).required(!has_default)` | -| `Vec<T>` | `0..` occurrences of argument | `.takes_value(true).required(false).multiple_occurrences(true)` | -| `Option<Vec<T>>` | `0..` occurrences of argument | `.takes_value(true).required(false).multiple_occurrences(true)` | - -Notes: -- For custom type behavior, you can override the implied attributes/settings and/or set additional ones - - For example, see [custom-bool](./custom-bool.md) -- `Option<Vec<T>>` will be `None` instead of `vec![]` if no arguments are provided. - - This gives the user some flexibility in designing their argument, like with `min_values(0)` - -You can then support your custom type with `#[clap(parse(<kind> [= <function>]))]`: - -| `<kind>` | Signature | Default `<function>` | -|--------------------------|---------------------------------------|---------------------------------| -| `from_str` | `fn(&str) -> T` | `::std::convert::From::from` | -| `try_from_str` (default) | `fn(&str) -> Result<T, E>` | `::std::str::FromStr::from_str` | -| `from_os_str` | `fn(&OsStr) -> T` | `::std::convert::From::from` | -| `try_from_os_str` | `fn(&OsStr) -> Result<T, E>` | (no default function) | -| `from_occurrences` | `fn(u64) -> T` | `value as T` | -| `from_flag` | `fn(bool) -> T` | `::std::convert::From::from` | - -Notes: -- `from_os_str`: - - Implies `arg.takes_value(true).allow_invalid_utf8(true)` -- `try_from_os_str`: - - Implies `arg.takes_value(true).allow_invalid_utf8(true)` -- `from_occurrences`: - - Implies `arg.takes_value(false).multiple_occurrences(true)` - - Reads from `clap::ArgMatches::occurrences_of` rather than a `get_one` function - - Note: operations on values, like `default_value`, are unlikely to do what you want -- `from_flag` - - Implies `arg.takes_value(false)` - - Reads from `clap::ArgMatches::is_present` rather than a `get_one` function - - Note: operations on values, like `default_value`, are unlikely to do what you want - -**Warning:** -- To support non-UTF8 paths, you should use `#[clap(value_parser)]` otherwise - `clap` will parse it as a `String` which will fail on some paths. - -## Doc Comments - -In clap, help messages for the whole binary can be specified -via [`Command::about`] and [`Command::long_about`] while help messages -for individual arguments can be specified via [`Arg::help`] and [`Arg::long_help`]". - -`long_*` variants are used when user calls the program with -`--help` and "short" variants are used with `-h` flag. - -```rust -# use clap::Parser; - -#[derive(Parser)] -#[clap(about = "I am a program and I work, just pass `-h`", long_about = None)] -struct Foo { - #[clap(short, help = "Pass `-h` and you'll see me!")] - bar: String, -} -``` - -For convenience, doc comments can be used instead of raw methods -(this example works exactly like the one above): - -```rust -# use clap::Parser; - -#[derive(Parser)] -/// I am a program and I work, just pass `-h` -struct Foo { - /// Pass `-h` and you'll see me! - bar: String, -} -``` - -**NOTE:** Attributes have priority over doc comments! - -**Top level doc comments always generate `Command::about/long_about` calls!** -If you really want to use the `Command::about/long_about` methods (you likely don't), -use the `about` / `long_about` attributes to override the calls generated from -the doc comment. To clear `long_about`, you can use -`#[clap(long_about = None)]`. - -**TIP:** Set `#![deny(missing_docs)]` to catch missing `--help` documentation at compile time. - -### Pre-processing - -```rust -# use clap::Parser; -#[derive(Parser)] -/// Hi there, I'm Robo! -/// -/// I like beeping, stumbling, eating your electricity, -/// and making records of you singing in a shower. -/// Pay up, or I'll upload it to youtube! -struct Robo { - /// Call my brother SkyNet. - /// - /// I am artificial superintelligence. I won't rest - /// until I'll have destroyed humanity. Enjoy your - /// pathetic existence, you mere mortals. - #[clap(long, action)] - kill_all_humans: bool, -} -``` - -A doc comment consists of three parts: -- Short summary -- A blank line (whitespace only) -- Detailed description, all the rest - -The summary corresponds with `Command::about` / `Arg::help`. When a blank line is -present, the whole doc comment will be passed to `Command::long_about` / -`Arg::long_help`. Or in other words, a doc may result in just a `Command::about` / -`Arg::help` or `Command::about` / `Arg::help` and `Command::long_about` / -`Arg::long_help` - -In addition, when `verbatim_doc_comment` is not present, `clap` applies some preprocessing, including: - -- Strip leading and trailing whitespace from every line, if present. - -- Strip leading and trailing blank lines, if present. - -- Interpret each group of non-empty lines as a word-wrapped paragraph. - - We replace newlines within paragraphs with spaces to allow the output - to be re-wrapped to the terminal width. - -- Strip any excess blank lines so that there is exactly one per paragraph break. - -- If the first paragraph ends in exactly one period, - remove the trailing period (i.e. strip trailing periods but not trailing ellipses). - -Sometimes you don't want this preprocessing to apply, for example the comment contains -some ASCII art or markdown tables, you would need to preserve LFs along with -blank lines and the leading/trailing whitespace. When you pass use the -`verbatim_doc_comment` magic attribute, you preserve -them. - -**Note:** Keep in mind that `verbatim_doc_comment` will *still* -- Remove one leading space from each line, even if this attribute is present, - to allow for a space between `///` and the content. -- Remove leading and trailing blank lines - -## Tips - -- To get access to a `Command` call `CommandFactory::command` (implemented when deriving `Parser`) -- Proactively check for bad `Command` configurations by calling `Command::debug_assert` in a test ([example](../tutorial_derive/05_01_assert.rs)) - -## Mixing Builder and Derive APIs - -The builder and derive APIs do not live in isolation. They can work together, which is especially helpful if some arguments can be specified at compile-time while others must be specified at runtime. - -### Using derived arguments in a builder application - -*[Jump to source](augment_args.rs)* - -When using the derive API, you can `#[clap(flatten)]` a struct deriving `Args` into a struct deriving `Args` or `Parser`. This example shows how you can augment a `Command` instance created using the builder API with `Args` created using the derive API. - -It uses the `Args::augment_args` method to add the arguments to the `Command` instance. - -Crates such as [clap-verbosity-flag](https://github.com/rust-cli/clap-verbosity-flag) provide structs that implement `Args` or `Parser`. Without the technique shown in this example, it would not be possible to use such crates with the builder API. `augment_args` to the rescue! - -### Using derived subcommands in a builder application - -*[Jump to source](augment_subcommands.rs)* - -When using the derive API, you can use `#[clap(subcommand)]` inside the struct to add subcommands. The type of the field is usually an enum that derived `Parser`. However, you can also add the subcommands in that enum to a `Command` instance created with the builder API. - -It uses the `Subcommand::augment_subcommands` method to add the subcommands to the `Command` instance. - -### Adding hand-implemented subcommands to a derived application - -*[Jump to source](hand_subcommand.rs)* - -When using the derive API, you can use `#[clap(subcommand)]` inside the struct to add subcommands. The type of the field is usually an enum that derived `Parser`. However, you can also implement the `Subcommand` trait manually on this enum (or any other type) and it can still be used inside the struct created with the derive API. The implementation of the `Subcommand` trait will use the builder API to add the subcommands to the `Command` instance created behind the scenes for you by the derive API. - -Notice how in the previous example we used `augment_subcommands` on an enum that derived `Parser`, whereas now we implement `augment_subcommands` ourselves, but the derive API calls it automatically since we used the `#[clap(subcommand)]` attribute. - -### Flattening hand-implemented args into a derived application - -*[Jump to source](flatten_hand_args.rs)* - -When using the derive API, you can use `#[clap(flatten)]` inside the struct to add arguments as if they were added directly to the containing struct. The type of the field is usually an struct that derived `Args`. However, you can also implement the `Args` trait manually on this struct (or any other type) and it can still be used inside the struct created with the derive API. The implementation of the `Args` trait will use the builder API to add the arguments to the `Command` instance created behind the scenes for you by the derive API. - -Notice how in the example 1 we used `augment_args` on the struct that derived `Parser`, whereas now we implement `augment_args` ourselves, but the derive API calls it automatically since we used the `#[clap(flatten)]` attribute. diff --git a/vendor/clap/examples/derive_ref/augment_args.rs b/vendor/clap/examples/derive_ref/augment_args.rs deleted file mode 100644 index 390c72f4a..000000000 --- a/vendor/clap/examples/derive_ref/augment_args.rs +++ /dev/null @@ -1,30 +0,0 @@ -use clap::{arg, Args as _, Command, FromArgMatches as _, Parser}; - -#[derive(Parser, Debug)] -struct DerivedArgs { - #[clap(short, long, action)] - derived: bool, -} - -fn main() { - let cli = Command::new("CLI").arg(arg!(-b - -built).action(clap::ArgAction::SetTrue)); - // Augment built args with derived args - let cli = DerivedArgs::augment_args(cli); - - let matches = cli.get_matches(); - println!( - "Value of built: {:?}", - *matches.get_one::<bool>("built").unwrap() - ); - println!( - "Value of derived via ArgMatches: {:?}", - *matches.get_one::<bool>("derived").unwrap() - ); - - // Since DerivedArgs implements FromArgMatches, we can extract it from the unstructured ArgMatches. - // This is the main benefit of using derived arguments. - let derived_matches = DerivedArgs::from_arg_matches(&matches) - .map_err(|err| err.exit()) - .unwrap(); - println!("Value of derived: {:#?}", derived_matches); -} diff --git a/vendor/clap/examples/git.rs b/vendor/clap/examples/git.rs deleted file mode 100644 index 5536f1487..000000000 --- a/vendor/clap/examples/git.rs +++ /dev/null @@ -1,103 +0,0 @@ -// Note: this requires the `cargo` feature - -use std::ffi::OsString; -use std::path::PathBuf; - -use clap::{arg, Command}; - -fn cli() -> Command<'static> { - Command::new("git") - .about("A fictional versioning CLI") - .subcommand_required(true) - .arg_required_else_help(true) - .allow_external_subcommands(true) - .allow_invalid_utf8_for_external_subcommands(true) - .subcommand( - Command::new("clone") - .about("Clones repos") - .arg(arg!(<REMOTE> "The remote to clone")) - .arg_required_else_help(true), - ) - .subcommand( - Command::new("push") - .about("pushes things") - .arg(arg!(<REMOTE> "The remote to target")) - .arg_required_else_help(true), - ) - .subcommand( - Command::new("add") - .about("adds things") - .arg_required_else_help(true) - .arg(arg!(<PATH> ... "Stuff to add").value_parser(clap::value_parser!(PathBuf))), - ) - .subcommand( - Command::new("stash") - .args_conflicts_with_subcommands(true) - .args(push_args()) - .subcommand(Command::new("push").args(push_args())) - .subcommand(Command::new("pop").arg(arg!([STASH]))) - .subcommand(Command::new("apply").arg(arg!([STASH]))), - ) -} - -fn push_args() -> Vec<clap::Arg<'static>> { - vec![arg!(-m --message <MESSAGE>).required(false)] -} - -fn main() { - let matches = cli().get_matches(); - - match matches.subcommand() { - Some(("clone", sub_matches)) => { - println!( - "Cloning {}", - sub_matches.get_one::<String>("REMOTE").expect("required") - ); - } - Some(("push", sub_matches)) => { - println!( - "Pushing to {}", - sub_matches.get_one::<String>("REMOTE").expect("required") - ); - } - Some(("add", sub_matches)) => { - let paths = sub_matches - .get_many::<PathBuf>("PATH") - .into_iter() - .flatten() - .collect::<Vec<_>>(); - println!("Adding {:?}", paths); - } - Some(("stash", sub_matches)) => { - let stash_command = sub_matches.subcommand().unwrap_or(("push", sub_matches)); - match stash_command { - ("apply", sub_matches) => { - let stash = sub_matches.get_one::<String>("STASH"); - println!("Applying {:?}", stash); - } - ("pop", sub_matches) => { - let stash = sub_matches.get_one::<String>("STASH"); - println!("Popping {:?}", stash); - } - ("push", sub_matches) => { - let message = sub_matches.get_one::<String>("message"); - println!("Pushing {:?}", message); - } - (name, _) => { - unreachable!("Unsupported subcommand `{}`", name) - } - } - } - Some((ext, sub_matches)) => { - let args = sub_matches - .get_many::<OsString>("") - .into_iter() - .flatten() - .collect::<Vec<_>>(); - println!("Calling out to {:?} with {:?}", ext, args); - } - _ => unreachable!(), // If all subcommands are defined above, anything else is unreachabe!() - } - - // Continued program logic goes here... -} diff --git a/vendor/clap/examples/multicall-hostname.md b/vendor/clap/examples/multicall-hostname.md deleted file mode 100644 index 9e17ca16c..000000000 --- a/vendor/clap/examples/multicall-hostname.md +++ /dev/null @@ -1,14 +0,0 @@ -*Jump to [source](multicall-hostname.rs)* - -Example of a `hostname-style` multicall program - -See the documentation for `clap::Command::multicall` for rationale. - -This example omits the implementation of displaying address config - -```console -$ hostname -www - -``` -*Note: without the links setup, we can't demonstrate the multicall behavior* diff --git a/vendor/clap/examples/pacman.rs b/vendor/clap/examples/pacman.rs deleted file mode 100644 index 6a60a8bf5..000000000 --- a/vendor/clap/examples/pacman.rs +++ /dev/null @@ -1,114 +0,0 @@ -use clap::{Arg, ArgAction, Command}; - -fn main() { - let matches = Command::new("pacman") - .about("package manager utility") - .version("5.2.1") - .subcommand_required(true) - .arg_required_else_help(true) - .author("Pacman Development Team") - // Query subcommand - // - // Only a few of its arguments are implemented below. - .subcommand( - Command::new("query") - .short_flag('Q') - .long_flag("query") - .about("Query the package database.") - .arg( - Arg::new("search") - .short('s') - .long("search") - .help("search locally installed packages for matching strings") - .conflicts_with("info") - .takes_value(true) - .multiple_values(true), - ) - .arg( - Arg::new("info") - .long("info") - .short('i') - .conflicts_with("search") - .help("view package information") - .takes_value(true) - .multiple_values(true), - ), - ) - // Sync subcommand - // - // Only a few of its arguments are implemented below. - .subcommand( - Command::new("sync") - .short_flag('S') - .long_flag("sync") - .about("Synchronize packages.") - .arg( - Arg::new("search") - .short('s') - .long("search") - .conflicts_with("info") - .takes_value(true) - .multiple_values(true) - .help("search remote repositories for matching strings"), - ) - .arg( - Arg::new("info") - .long("info") - .conflicts_with("search") - .short('i') - .action(ArgAction::SetTrue) - .help("view package information"), - ) - .arg( - Arg::new("package") - .help("packages") - .required_unless_present("search") - .takes_value(true) - .multiple_values(true), - ), - ) - .get_matches(); - - match matches.subcommand() { - Some(("sync", sync_matches)) => { - if sync_matches.contains_id("search") { - let packages: Vec<_> = sync_matches - .get_many::<String>("search") - .expect("contains_id") - .map(|s| s.as_str()) - .collect(); - let values = packages.join(", "); - println!("Searching for {}...", values); - return; - } - - let packages: Vec<_> = sync_matches - .get_many::<String>("package") - .expect("is present") - .map(|s| s.as_str()) - .collect(); - let values = packages.join(", "); - - if *sync_matches - .get_one::<bool>("info") - .expect("defaulted by clap") - { - println!("Retrieving info for {}...", values); - } else { - println!("Installing {}...", values); - } - } - Some(("query", query_matches)) => { - if let Some(packages) = query_matches.get_many::<String>("info") { - let comma_sep = packages.map(|s| s.as_str()).collect::<Vec<_>>().join(", "); - println!("Retrieving info for {}...", comma_sep); - } else if let Some(queries) = query_matches.get_many::<String>("search") { - let comma_sep = queries.map(|s| s.as_str()).collect::<Vec<_>>().join(", "); - println!("Searching Locally for {}...", comma_sep); - } else { - println!("Displaying all locally installed packages..."); - } - } - _ => unreachable!(), // If all subcommands are defined above, anything else is unreachable - } -} diff --git a/vendor/clap/examples/tutorial_builder/02_crate.rs b/vendor/clap/examples/tutorial_builder/02_crate.rs deleted file mode 100644 index 16b7e7ee0..000000000 --- a/vendor/clap/examples/tutorial_builder/02_crate.rs +++ /dev/null @@ -1,19 +0,0 @@ -// Note: this requires the `cargo` feature - -use clap::{arg, command}; - -fn main() { - let matches = command!() - .arg(arg!(--two <VALUE>)) - .arg(arg!(--one <VALUE>)) - .get_matches(); - - println!( - "two: {:?}", - matches.get_one::<String>("two").expect("required") - ); - println!( - "one: {:?}", - matches.get_one::<String>("one").expect("required") - ); -} diff --git a/vendor/clap/examples/tutorial_builder/03_01_flag_bool.rs b/vendor/clap/examples/tutorial_builder/03_01_flag_bool.rs deleted file mode 100644 index 41ecbb1d7..000000000 --- a/vendor/clap/examples/tutorial_builder/03_01_flag_bool.rs +++ /dev/null @@ -1,21 +0,0 @@ -// Note: this requires the `cargo` feature - -use clap::{command, Arg, ArgAction}; - -fn main() { - let matches = command!() - .arg( - Arg::new("verbose") - .short('v') - .long("verbose") - .action(ArgAction::SetTrue), - ) - .get_matches(); - - println!( - "verbose: {:?}", - *matches - .get_one::<bool>("verbose") - .expect("defaulted by clap") - ); -} diff --git a/vendor/clap/examples/tutorial_builder/03_01_flag_count.rs b/vendor/clap/examples/tutorial_builder/03_01_flag_count.rs deleted file mode 100644 index 764affbd8..000000000 --- a/vendor/clap/examples/tutorial_builder/03_01_flag_count.rs +++ /dev/null @@ -1,16 +0,0 @@ -// Note: this requires the `cargo` feature - -use clap::{arg, command, ArgAction}; - -fn main() { - let matches = command!() - .arg(arg!(-v - -verbose).action(ArgAction::Count)) - .get_matches(); - - println!( - "verbose: {:?}", - matches - .get_one::<u8>("verbose") - .expect("Count always defaulted") - ); -} diff --git a/vendor/clap/examples/tutorial_builder/03_02_option.rs b/vendor/clap/examples/tutorial_builder/03_02_option.rs deleted file mode 100644 index 80e2b9159..000000000 --- a/vendor/clap/examples/tutorial_builder/03_02_option.rs +++ /dev/null @@ -1,11 +0,0 @@ -// Note: this requires the `cargo` feature - -use clap::{arg, command}; - -fn main() { - let matches = command!() - .arg(arg!(-n --name <NAME>).required(false)) - .get_matches(); - - println!("name: {:?}", matches.get_one::<String>("name")); -} diff --git a/vendor/clap/examples/tutorial_builder/03_03_positional.rs b/vendor/clap/examples/tutorial_builder/03_03_positional.rs deleted file mode 100644 index c6579409a..000000000 --- a/vendor/clap/examples/tutorial_builder/03_03_positional.rs +++ /dev/null @@ -1,9 +0,0 @@ -// Note: this requires the `cargo` feature - -use clap::{arg, command}; - -fn main() { - let matches = command!().arg(arg!([NAME])).get_matches(); - - println!("NAME: {:?}", matches.get_one::<String>("NAME")); -} diff --git a/vendor/clap/examples/tutorial_builder/04_01_enum.rs b/vendor/clap/examples/tutorial_builder/04_01_enum.rs deleted file mode 100644 index ad2177c23..000000000 --- a/vendor/clap/examples/tutorial_builder/04_01_enum.rs +++ /dev/null @@ -1,32 +0,0 @@ -// Note: this requires the `cargo` feature - -use clap::{arg, command, value_parser, ValueEnum}; - -#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum)] -enum Mode { - Fast, - Slow, -} - -fn main() { - let matches = command!() - .arg( - arg!(<MODE>) - .help("What mode to run the program in") - .value_parser(value_parser!(Mode)), - ) - .get_matches(); - - // Note, it's safe to call unwrap() because the arg is required - match matches - .get_one::<Mode>("MODE") - .expect("'MODE' is required and parsing will fail if its missing") - { - Mode::Fast => { - println!("Hare"); - } - Mode::Slow => { - println!("Tortoise"); - } - } -} diff --git a/vendor/clap/examples/tutorial_builder/04_03_relations.rs b/vendor/clap/examples/tutorial_builder/04_03_relations.rs deleted file mode 100644 index 605e5b48e..000000000 --- a/vendor/clap/examples/tutorial_builder/04_03_relations.rs +++ /dev/null @@ -1,82 +0,0 @@ -// Note: this requires the `cargo` feature - -use std::path::PathBuf; - -use clap::{arg, command, value_parser, ArgAction, ArgGroup}; - -fn main() { - // Create application like normal - let matches = command!() - // Add the version arguments - .arg(arg!(--"set-ver" <VER> "set version manually").required(false)) - .arg(arg!(--major "auto inc major").action(ArgAction::SetTrue)) - .arg(arg!(--minor "auto inc minor").action(ArgAction::SetTrue)) - .arg(arg!(--patch "auto inc patch").action(ArgAction::SetTrue)) - // Create a group, make it required, and add the above arguments - .group( - ArgGroup::new("vers") - .required(true) - .args(&["set-ver", "major", "minor", "patch"]), - ) - // Arguments can also be added to a group individually, these two arguments - // are part of the "input" group which is not required - .arg( - arg!([INPUT_FILE] "some regular input") - .value_parser(value_parser!(PathBuf)) - .group("input"), - ) - .arg( - arg!(--"spec-in" <SPEC_IN> "some special input argument") - .required(false) - .value_parser(value_parser!(PathBuf)) - .group("input"), - ) - // Now let's assume we have a -c [config] argument which requires one of - // (but **not** both) the "input" arguments - .arg( - arg!(config: -c <CONFIG>) - .required(false) - .value_parser(value_parser!(PathBuf)) - .requires("input"), - ) - .get_matches(); - - // Let's assume the old version 1.2.3 - let mut major = 1; - let mut minor = 2; - let mut patch = 3; - - // See if --set-ver was used to set the version manually - let version = if let Some(ver) = matches.get_one::<String>("set-ver") { - ver.to_owned() - } else { - // Increment the one requested (in a real program, we'd reset the lower numbers) - let (maj, min, pat) = ( - *matches.get_one::<bool>("major").expect("defaulted by clap"), - *matches.get_one::<bool>("minor").expect("defaulted by clap"), - *matches.get_one::<bool>("patch").expect("defaulted by clap"), - ); - match (maj, min, pat) { - (true, _, _) => major += 1, - (_, true, _) => minor += 1, - (_, _, true) => patch += 1, - _ => unreachable!(), - }; - format!("{}.{}.{}", major, minor, patch) - }; - - println!("Version: {}", version); - - // Check for usage of -c - if matches.contains_id("config") { - let input = matches - .get_one::<PathBuf>("INPUT_FILE") - .unwrap_or_else(|| matches.get_one::<PathBuf>("spec-in").unwrap()) - .display(); - println!( - "Doing work using input {} and config {}", - input, - matches.get_one::<PathBuf>("config").unwrap().display() - ); - } -} diff --git a/vendor/clap/examples/tutorial_builder/05_01_assert.rs b/vendor/clap/examples/tutorial_builder/05_01_assert.rs deleted file mode 100644 index d6f19ffe5..000000000 --- a/vendor/clap/examples/tutorial_builder/05_01_assert.rs +++ /dev/null @@ -1,26 +0,0 @@ -// Note: this requires the `cargo` feature - -use clap::{arg, command, value_parser}; - -fn main() { - let matches = cmd().get_matches(); - - // Note, it's safe to call unwrap() because the arg is required - let port: usize = *matches - .get_one::<usize>("PORT") - .expect("'PORT' is required and parsing will fail if its missing"); - println!("PORT = {}", port); -} - -fn cmd() -> clap::Command<'static> { - command!().arg( - arg!(<PORT>) - .help("Network port to use") - .value_parser(value_parser!(usize)), - ) -} - -#[test] -fn verify_app() { - cmd().debug_assert(); -} diff --git a/vendor/clap/examples/tutorial_builder/README.md b/vendor/clap/examples/tutorial_builder/README.md deleted file mode 100644 index 945b01e72..000000000 --- a/vendor/clap/examples/tutorial_builder/README.md +++ /dev/null @@ -1,658 +0,0 @@ -# Tutorial - -*Jump to [derive tutorial](../tutorial_derive/README.md)* - -1. [Quick Start](#quick-start) -2. [Configuring the Parser](#configuring-the-parser) -3. [Adding Arguments](#adding-arguments) - 1. [Positionals](#positionals) - 2. [Options](#options) - 3. [Flags](#flags) - 4. [Subcommands](#subcommands) - 5. [Defaults](#defaults) -4. Validation - 1. [Enumerated values](#enumerated-values) - 2. [Validated values](#validated-values) - 3. [Argument Relations](#argument-relations) - 4. [Custom Validation](#custom-validation) -5. [Tips](#tips) -6. [Contributing](#contributing) - -## Quick Start - -You can create an application with several arguments using usage strings. - -[Example:](01_quick.rs) -```console -$ 01_quick --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 01_quick[EXE] [OPTIONS] [name] [SUBCOMMAND] - -ARGS: - <name> Optional name to operate on - -OPTIONS: - -c, --config <FILE> Sets a custom config file - -d, --debug Turn debugging information on - -h, --help Print help information - -V, --version Print version information - -SUBCOMMANDS: - help Print this message or the help of the given subcommand(s) - test does testing things - -``` - -By default, the program does nothing: -```console -$ 01_quick -Debug mode is off - -``` - -But you can mix and match the various features -```console -$ 01_quick -dd test -Debug mode is on -Not printing testing lists... - -``` - -## Configuring the Parser - -You use the `Command` the start building a parser. - -[Example:](02_apps.rs) -```console -$ 02_apps --help -MyApp 1.0 -Kevin K. <kbknapp@gmail.com> -Does awesome things - -USAGE: - 02_apps[EXE] --two <VALUE> --one <VALUE> - -OPTIONS: - -h, --help Print help information - --one <VALUE> - --two <VALUE> - -V, --version Print version information - -$ 02_apps --version -MyApp 1.0 - -``` - -You can use `command!()` to fill these fields in from your `Cargo.toml` -file. **This requires the `cargo` feature flag.** - -[Example:](02_crate.rs) -```console -$ 02_crate --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 02_crate[EXE] --two <VALUE> --one <VALUE> - -OPTIONS: - -h, --help Print help information - --one <VALUE> - --two <VALUE> - -V, --version Print version information - -$ 02_crate --version -clap [..] - -``` - -You can use `Command` methods to change the application level behavior of clap. - -[Example:](02_app_settings.rs) -```console -$ 02_app_settings --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 02_app_settings[EXE] --two <VALUE> --one <VALUE> - -OPTIONS: - --two <VALUE> - --one <VALUE> - -h, --help Print help information - -V, --version Print version information - -$ 02_app_settings --one -1 --one -3 --two 10 -two: "10" -one: "-3" - -``` - -## Adding Arguments - -### Positionals - -You can have users specify values by their position on the command-line: - -[Example:](03_03_positional.rs) -```console -$ 03_03_positional --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 03_03_positional[EXE] [NAME] - -ARGS: - <NAME> - -OPTIONS: - -h, --help Print help information - -V, --version Print version information - -$ 03_03_positional -NAME: None - -$ 03_03_positional bob -NAME: Some("bob") - -``` - -### Options - -You can name your arguments with a flag: -- Order doesn't matter -- They can be optional -- Intent is clearer - -[Example:](03_02_option.rs) -```console -$ 03_02_option --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 03_02_option[EXE] [OPTIONS] - -OPTIONS: - -h, --help Print help information - -n, --name <NAME> - -V, --version Print version information - -$ 03_02_option -name: None - -$ 03_02_option --name bob -name: Some("bob") - -$ 03_02_option --name=bob -name: Some("bob") - -$ 03_02_option -n bob -name: Some("bob") - -$ 03_02_option -n=bob -name: Some("bob") - -$ 03_02_option -nbob -name: Some("bob") - -``` - -### Flags - -Flags can also be switches that can be on/off: - -[Example:](03_01_flag_bool.rs) -```console -$ 03_01_flag_bool --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 03_01_flag_bool[EXE] [OPTIONS] - -OPTIONS: - -h, --help Print help information - -v, --verbose - -V, --version Print version information - -$ 03_01_flag_bool -verbose: false - -$ 03_01_flag_bool --verbose -verbose: true - -$ 03_01_flag_bool --verbose --verbose -verbose: true - -``` - -Or counted. - -[Example:](03_01_flag_count.rs) -```console -$ 03_01_flag_count --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 03_01_flag_count[EXE] [OPTIONS] - -OPTIONS: - -h, --help Print help information - -v, --verbose - -V, --version Print version information - -$ 03_01_flag_count -verbose: 0 - -$ 03_01_flag_count --verbose -verbose: 1 - -$ 03_01_flag_count --verbose --verbose -verbose: 2 - -``` - -### Subcommands - -Subcommands are defined as `Command`s that get added via `Command::subcommand`. Each -instance of a Subcommand can have its own version, author(s), Args, and even its own -subcommands. - -[Example:](03_04_subcommands.rs) -```console -$ 03_04_subcommands help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 03_04_subcommands[EXE] <SUBCOMMAND> - -OPTIONS: - -h, --help Print help information - -V, --version Print version information - -SUBCOMMANDS: - add Adds files to myapp - help Print this message or the help of the given subcommand(s) - -$ 03_04_subcommands help add -03_04_subcommands[EXE]-add [..] -Adds files to myapp - -USAGE: - 03_04_subcommands[EXE] add [NAME] - -ARGS: - <NAME> - -OPTIONS: - -h, --help Print help information - -V, --version Print version information - -$ 03_04_subcommands add bob -'myapp add' was used, name is: Some("bob") - -``` - -Because we set `Command::arg_required_else_help`: -```console -$ 03_04_subcommands -? failed -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 03_04_subcommands[EXE] <SUBCOMMAND> - -OPTIONS: - -h, --help Print help information - -V, --version Print version information - -SUBCOMMANDS: - add Adds files to myapp - help Print this message or the help of the given subcommand(s) - -``` - -Because we set `Command::propagate_version`: -```console -$ 03_04_subcommands --version -clap [..] - -$ 03_04_subcommands add --version -03_04_subcommands[EXE]-add [..] - -``` - -### Defaults - -We've previously showed that arguments can be `required` or optional. When -optional, you work with a `Option` and can `unwrap_or`. Alternatively, you can -set `Arg::default_value`. - -[Example:](03_05_default_values.rs) -```console -$ 03_05_default_values --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 03_05_default_values[EXE] [NAME] - -ARGS: - <NAME> [default: alice] - -OPTIONS: - -h, --help Print help information - -V, --version Print version information - -$ 03_05_default_values -NAME: "alice" - -$ 03_05_default_values bob -NAME: "bob" - -``` - -## Validation - -### Enumerated values - -If you have arguments of specific values you want to test for, you can use the -`PossibleValuesParser` or `Arg::value_parser(["val1", ...])` for short. - -This allows you specify the valid values for that argument. If the user does not use one of -those specific values, they will receive a graceful exit with error message informing them -of the mistake, and what the possible valid values are - -[Example:](04_01_possible.rs) -```console -$ 04_01_possible --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 04_01_possible[EXE] <MODE> - -ARGS: - <MODE> What mode to run the program in [possible values: fast, slow] - -OPTIONS: - -h, --help Print help information - -V, --version Print version information - -$ 04_01_possible fast -Hare - -$ 04_01_possible slow -Tortoise - -$ 04_01_possible medium -? failed -error: "medium" isn't a valid value for '<MODE>' - [possible values: fast, slow] - -For more information try --help - -``` - -When enabling the `derive` feature, you can use `ValueEnum` to take care of the boiler plate for you, giving the same results. - -[Example:](04_01_enum.rs) -```console -$ 04_01_enum --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 04_01_enum[EXE] <MODE> - -ARGS: - <MODE> What mode to run the program in [possible values: fast, slow] - -OPTIONS: - -h, --help Print help information - -V, --version Print version information - -$ 04_01_enum fast -Hare - -$ 04_01_enum slow -Tortoise - -$ 04_01_enum medium -? failed -error: "medium" isn't a valid value for '<MODE>' - [possible values: fast, slow] - -For more information try --help - -``` - -### Validated values - -More generally, you can validate and parse into any data type. - -[Example:](04_02_parse.rs) -```console -$ 04_02_parse --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 04_02_parse[EXE] <PORT> - -ARGS: - <PORT> Network port to use - -OPTIONS: - -h, --help Print help information - -V, --version Print version information - -$ 04_02_parse 22 -PORT = 22 - -$ 04_02_parse foobar -? failed -error: Invalid value "foobar" for '<PORT>': invalid digit found in string - -For more information try --help - -$ 04_02_parse_derive 0 -? failed -error: Invalid value "0" for '<PORT>': 0 is not in 1..=65535 - -For more information try --help - -``` - -A custom parser can be used to improve the error messages or provide additional validation: - -[Example:](04_02_validate.rs) -```console -$ 04_02_validate --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 04_02_validate[EXE] <PORT> - -ARGS: - <PORT> Network port to use - -OPTIONS: - -h, --help Print help information - -V, --version Print version information - -$ 04_02_validate 22 -PORT = 22 - -$ 04_02_validate foobar -? failed -error: Invalid value "foobar" for '<PORT>': `foobar` isn't a port number - -For more information try --help - -$ 04_02_validate 0 -? failed -error: Invalid value "0" for '<PORT>': Port not in range 1-65535 - -For more information try --help - -``` - -### Argument Relations - -You can declare dependencies or conflicts between `Arg`s or even `ArgGroup`s. - -`ArgGroup`s make it easier to declare relations 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. - -[Example:](04_03_relations.rs) -```console -$ 04_03_relations --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 04_03_relations[EXE] [OPTIONS] <--set-ver <VER>|--major|--minor|--patch> [INPUT_FILE] - -ARGS: - <INPUT_FILE> some regular input - -OPTIONS: - -c <CONFIG> - -h, --help Print help information - --major auto inc major - --minor auto inc minor - --patch auto inc patch - --set-ver <VER> set version manually - --spec-in <SPEC_IN> some special input argument - -V, --version Print version information - -$ 04_03_relations -? failed -error: The following required arguments were not provided: - <--set-ver <VER>|--major|--minor|--patch> - -USAGE: - 04_03_relations[EXE] [OPTIONS] <--set-ver <VER>|--major|--minor|--patch> [INPUT_FILE] - -For more information try --help - -$ 04_03_relations --major -Version: 2.2.3 - -$ 04_03_relations --major --minor -? failed -error: The argument '--major' cannot be used with '--minor' - -USAGE: - 04_03_relations[EXE] <--set-ver <VER>|--major|--minor|--patch> - -For more information try --help - -$ 04_03_relations --major -c config.toml -? failed -error: The following required arguments were not provided: - <INPUT_FILE|--spec-in <SPEC_IN>> - -USAGE: - 04_03_relations[EXE] -c <CONFIG> <--set-ver <VER>|--major|--minor|--patch> <INPUT_FILE|--spec-in <SPEC_IN>> - -For more information try --help - -$ 04_03_relations --major -c config.toml --spec-in input.txt -Version: 2.2.3 -Doing work using input input.txt and config config.toml - -``` - -### Custom Validation - -As a last resort, you can create custom errors with the basics of clap's formatting. - -[Example:](04_04_custom.rs) -```console -$ 04_04_custom --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 04_04_custom[EXE] [OPTIONS] [INPUT_FILE] - -ARGS: - <INPUT_FILE> some regular input - -OPTIONS: - -c <CONFIG> - -h, --help Print help information - --major auto inc major - --minor auto inc minor - --patch auto inc patch - --set-ver <VER> set version manually - --spec-in <SPEC_IN> some special input argument - -V, --version Print version information - -$ 04_04_custom -? failed -error: Can only modify one version field - -USAGE: - 04_04_custom[EXE] [OPTIONS] [INPUT_FILE] - -For more information try --help - -$ 04_04_custom --major -Version: 2.2.3 - -$ 04_04_custom --major --minor -? failed -error: Can only modify one version field - -USAGE: - 04_04_custom[EXE] [OPTIONS] [INPUT_FILE] - -For more information try --help - -$ 04_04_custom --major -c config.toml -? failed -Version: 2.2.3 -error: INPUT_FILE or --spec-in is required when using --config - -USAGE: - 04_04_custom[EXE] [OPTIONS] [INPUT_FILE] - -For more information try --help - -$ 04_04_custom --major -c config.toml --spec-in input.txt -Version: 2.2.3 -Doing work using input input.txt and config config.toml - -``` - -## Tips - -- For more complex demonstration of features, see our [examples](../README.md). -- Proactively check for bad `Command` configurations by calling `Command::debug_assert` in a test ([example](05_01_assert.rs)) - -## Contributing - -New example code: -- Please update the corresponding section in the [derive tutorial](../tutorial_derive/README.md) -- Building: They must be added to [Cargo.toml](../../Cargo.toml) with the appropriate `required-features`. -- Testing: Ensure there is a markdown file with [trycmd](https://docs.rs/trycmd) syntax (generally they'll go in here). - -See also the general [CONTRIBUTING](../../CONTRIBUTING.md). diff --git a/vendor/clap/examples/tutorial_derive/02_crate.rs b/vendor/clap/examples/tutorial_derive/02_crate.rs deleted file mode 100644 index df16468d0..000000000 --- a/vendor/clap/examples/tutorial_derive/02_crate.rs +++ /dev/null @@ -1,17 +0,0 @@ -use clap::Parser; - -#[derive(Parser)] -#[clap(author, version, about, long_about = None)] -struct Cli { - #[clap(long, value_parser)] - two: String, - #[clap(long, value_parser)] - one: String, -} - -fn main() { - let cli = Cli::parse(); - - println!("two: {:?}", cli.two); - println!("one: {:?}", cli.one); -} diff --git a/vendor/clap/examples/tutorial_derive/04_01_enum.rs b/vendor/clap/examples/tutorial_derive/04_01_enum.rs deleted file mode 100644 index 84b4cace4..000000000 --- a/vendor/clap/examples/tutorial_derive/04_01_enum.rs +++ /dev/null @@ -1,28 +0,0 @@ -use clap::{ArgEnum, Parser}; - -#[derive(Parser)] -#[clap(author, version, about, long_about = None)] -struct Cli { - /// What mode to run the program in - #[clap(arg_enum, value_parser)] - mode: Mode, -} - -#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ArgEnum)] -enum Mode { - Fast, - Slow, -} - -fn main() { - let cli = Cli::parse(); - - match cli.mode { - Mode::Fast => { - println!("Hare"); - } - Mode::Slow => { - println!("Tortoise"); - } - } -} diff --git a/vendor/clap/examples/tutorial_derive/04_03_relations.rs b/vendor/clap/examples/tutorial_derive/04_03_relations.rs deleted file mode 100644 index f8523902d..000000000 --- a/vendor/clap/examples/tutorial_derive/04_03_relations.rs +++ /dev/null @@ -1,72 +0,0 @@ -use clap::{ArgGroup, Parser}; - -#[derive(Parser)] -#[clap(author, version, about, long_about = None)] -#[clap(group( - ArgGroup::new("vers") - .required(true) - .args(&["set-ver", "major", "minor", "patch"]), - ))] -struct Cli { - /// set version manually - #[clap(long, value_name = "VER", value_parser)] - set_ver: Option<String>, - - /// auto inc major - #[clap(long, action)] - major: bool, - - /// auto inc minor - #[clap(long, action)] - minor: bool, - - /// auto inc patch - #[clap(long, action)] - patch: bool, - - /// some regular input - #[clap(group = "input", value_parser)] - input_file: Option<String>, - - /// some special input argument - #[clap(long, group = "input", value_parser)] - spec_in: Option<String>, - - #[clap(short, requires = "input", value_parser)] - config: Option<String>, -} - -fn main() { - let cli = Cli::parse(); - - // Let's assume the old version 1.2.3 - let mut major = 1; - let mut minor = 2; - let mut patch = 3; - - // See if --set-ver was used to set the version manually - let version = if let Some(ver) = cli.set_ver.as_deref() { - ver.to_string() - } else { - // Increment the one requested (in a real program, we'd reset the lower numbers) - let (maj, min, pat) = (cli.major, cli.minor, cli.patch); - match (maj, min, pat) { - (true, _, _) => major += 1, - (_, true, _) => minor += 1, - (_, _, true) => patch += 1, - _ => unreachable!(), - }; - format!("{}.{}.{}", major, minor, patch) - }; - - println!("Version: {}", version); - - // Check for usage of -c - if let Some(config) = cli.config.as_deref() { - let input = cli - .input_file - .as_deref() - .unwrap_or_else(|| cli.spec_in.as_deref().unwrap()); - println!("Doing work using input {} and config {}", input, config); - } -} diff --git a/vendor/clap/examples/tutorial_derive/05_01_assert.rs b/vendor/clap/examples/tutorial_derive/05_01_assert.rs deleted file mode 100644 index f5fa3f6c5..000000000 --- a/vendor/clap/examples/tutorial_derive/05_01_assert.rs +++ /dev/null @@ -1,21 +0,0 @@ -use clap::Parser; - -#[derive(Parser)] -#[clap(author, version, about, long_about = None)] -struct Cli { - /// Network port to use - #[clap(value_parser)] - port: u16, -} - -fn main() { - let cli = Cli::parse(); - - println!("PORT = {}", cli.port); -} - -#[test] -fn verify_app() { - use clap::CommandFactory; - Cli::command().debug_assert() -} diff --git a/vendor/clap/examples/tutorial_derive/README.md b/vendor/clap/examples/tutorial_derive/README.md deleted file mode 100644 index 6127b6cd3..000000000 --- a/vendor/clap/examples/tutorial_derive/README.md +++ /dev/null @@ -1,639 +0,0 @@ -# Tutorial - -*Jump to [builder tutorial](../tutorial_builder/README.md)* - -1. [Quick Start](#quick-start) -2. [Configuring the Parser](#configuring-the-parser) -3. [Adding Arguments](#adding-arguments) - 1. [Positionals](#positionals) - 2. [Options](#options) - 3. [Flags](#flags) - 4. [Subcommands](#subcommands) - 5. [Defaults](#defaults) -4. Validation - 1. [Enumerated values](#enumerated-values) - 2. [Validated values](#validated-values) - 3. [Argument Relations](#argument-relations) - 4. [Custom Validation](#custom-validation) -5. [Tips](#tips) -6. [Contributing](#contributing) - -## Quick Start - -You can create an application declaratively with a `struct` and some -attributes. **This requires enabling the `derive` feature flag.** - -[Example:](01_quick.rs) -```console -$ 01_quick_derive --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 01_quick_derive[EXE] [OPTIONS] [NAME] [SUBCOMMAND] - -ARGS: - <NAME> Optional name to operate on - -OPTIONS: - -c, --config <FILE> Sets a custom config file - -d, --debug Turn debugging information on - -h, --help Print help information - -V, --version Print version information - -SUBCOMMANDS: - help Print this message or the help of the given subcommand(s) - test does testing things - -``` - -By default, the program does nothing: -```console -$ 01_quick_derive -Debug mode is off - -``` - -But you can mix and match the various features -```console -$ 01_quick_derive -dd test -Debug mode is on -Not printing testing lists... - -``` - -In addition to this tutorial, see the [derive reference](../derive_ref/README.md). - -## Configuring the Parser - -You use derive `Parser` the start building a parser. - -[Example:](02_apps.rs) -```console -$ 02_apps_derive --help -MyApp 1.0 -Kevin K. <kbknapp@gmail.com> -Does awesome things - -USAGE: - 02_apps_derive[EXE] --two <TWO> --one <ONE> - -OPTIONS: - -h, --help Print help information - --one <ONE> - --two <TWO> - -V, --version Print version information - -$ 02_apps_derive --version -MyApp 1.0 - -``` - -You can use `#[clap(author, version, about)]` attribute defaults to fill these fields in from your `Cargo.toml` file. - -[Example:](02_crate.rs) -```console -$ 02_crate_derive --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 02_crate_derive[EXE] --two <TWO> --one <ONE> - -OPTIONS: - -h, --help Print help information - --one <ONE> - --two <TWO> - -V, --version Print version information - -$ 02_crate_derive --version -clap [..] - -``` - -You can use attributes to change the application level behavior of clap. Any `Command` builder function can be used as an attribute. - -[Example:](02_app_settings.rs) -```console -$ 02_app_settings_derive --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 02_app_settings_derive[EXE] --two <TWO> --one <ONE> - -OPTIONS: - --two <TWO> - --one <ONE> - -h, --help Print help information - -V, --version Print version information - -$ 02_app_settings_derive --one -1 --one -3 --two 10 -two: "10" -one: "-3" - -``` - -## Adding Arguments - -### Positionals - -You can have users specify values by their position on the command-line: - -[Example:](03_03_positional.rs) -```console -$ 03_03_positional_derive --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 03_03_positional_derive[EXE] [NAME] - -ARGS: - <NAME> - -OPTIONS: - -h, --help Print help information - -V, --version Print version information - -$ 03_03_positional_derive -name: None - -$ 03_03_positional_derive bob -name: Some("bob") - -``` - -### Options - -You can name your arguments with a flag: -- Order doesn't matter -- They can be optional -- Intent is clearer - -The `#[clap(short = 'c')]` and `#[clap(long = "name")]` attributes that define -the flags are `Arg` methods that are derived from the field name when no value -is specified (`#[clap(short)]` and `#[clap(long)]`). - -[Example:](03_02_option.rs) -```console -$ 03_02_option_derive --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 03_02_option_derive[EXE] [OPTIONS] - -OPTIONS: - -h, --help Print help information - -n, --name <NAME> - -V, --version Print version information - -$ 03_02_option_derive -name: None - -$ 03_02_option_derive --name bob -name: Some("bob") - -$ 03_02_option_derive --name=bob -name: Some("bob") - -$ 03_02_option_derive -n bob -name: Some("bob") - -$ 03_02_option_derive -n=bob -name: Some("bob") - -$ 03_02_option_derive -nbob -name: Some("bob") - -``` - -### Flags - -Flags can also be switches that can be on/off. This is enabled via the -`#[clap(parse(from_flag)]` attribute though this is implied when the field is a -`bool`. - -[Example:](03_01_flag_bool.rs) -```console -$ 03_01_flag_bool_derive --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 03_01_flag_bool_derive[EXE] [OPTIONS] - -OPTIONS: - -h, --help Print help information - -v, --verbose - -V, --version Print version information - -$ 03_01_flag_bool_derive -verbose: false - -$ 03_01_flag_bool_derive --verbose -verbose: true - -$ 03_01_flag_bool_derive --verbose --verbose -verbose: true - -``` - -Or counted with `#[clap(action = clap::ArgAction::Count)]`: - -[Example:](03_01_flag_count.rs) -```console -$ 03_01_flag_count_derive --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 03_01_flag_count_derive[EXE] [OPTIONS] - -OPTIONS: - -h, --help Print help information - -v, --verbose - -V, --version Print version information - -$ 03_01_flag_count_derive -verbose: 0 - -$ 03_01_flag_count_derive --verbose -verbose: 1 - -$ 03_01_flag_count_derive --verbose --verbose -verbose: 2 - -``` - -### Subcommands - -Subcommands are derived with `#[derive(Subcommand)]` and be added via `#[clap(subcommand)]` attribute. Each -instance of a Subcommand can have its own version, author(s), Args, and even its own -subcommands. - -[Example:](03_04_subcommands.rs) -```console -$ 03_04_subcommands_derive help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 03_04_subcommands_derive[EXE] <SUBCOMMAND> - -OPTIONS: - -h, --help Print help information - -V, --version Print version information - -SUBCOMMANDS: - add Adds files to myapp - help Print this message or the help of the given subcommand(s) - -$ 03_04_subcommands_derive help add -03_04_subcommands_derive[EXE]-add [..] -Adds files to myapp - -USAGE: - 03_04_subcommands_derive[EXE] add [NAME] - -ARGS: - <NAME> - -OPTIONS: - -h, --help Print help information - -V, --version Print version information - -$ 03_04_subcommands_derive add bob -'myapp add' was used, name is: Some("bob") - -``` - -Above, we used a struct-variant to define the `add` subcommand. Alternatively, -you can -[use a struct for your subcommand's arguments](03_04_subcommands_alt.rs). - -Because we used `command: Commands` instead of `command: Option<Commands>`: -```console -$ 03_04_subcommands_derive -? failed -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 03_04_subcommands_derive[EXE] <SUBCOMMAND> - -OPTIONS: - -h, --help Print help information - -V, --version Print version information - -SUBCOMMANDS: - add Adds files to myapp - help Print this message or the help of the given subcommand(s) - -``` - -Because we added `#[clap(propagate_version = true)]`: -```console -$ 03_04_subcommands_derive --version -clap [..] - -$ 03_04_subcommands_derive add --version -03_04_subcommands_derive[EXE]-add [..] - -``` - -### Defaults - -We've previously showed that arguments can be `required` or optional. When -optional, you work with an `Option` and can `unwrap_or`. Alternatively, you can -set `#[clap(default_value_t)]`. - -[Example:](03_05_default_values.rs) -```console -$ 03_05_default_values_derive --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 03_05_default_values_derive[EXE] [NAME] - -ARGS: - <NAME> [default: alice] - -OPTIONS: - -h, --help Print help information - -V, --version Print version information - -$ 03_05_default_values_derive -name: "alice" - -$ 03_05_default_values_derive bob -name: "bob" - -``` - -## Validation - -### Enumerated values - -If you have arguments of specific values you want to test for, you can derive -`ValueEnum`. - -This allows you specify the valid values for that argument. If the user does not use one of -those specific values, they will receive a graceful exit with error message informing them -of the mistake, and what the possible valid values are - -[Example:](04_01_enum.rs) -```console -$ 04_01_enum_derive --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 04_01_enum_derive[EXE] <MODE> - -ARGS: - <MODE> What mode to run the program in [possible values: fast, slow] - -OPTIONS: - -h, --help Print help information - -V, --version Print version information - -$ 04_01_enum_derive fast -Hare - -$ 04_01_enum_derive slow -Tortoise - -$ 04_01_enum_derive medium -? failed -error: "medium" isn't a valid value for '<MODE>' - [possible values: fast, slow] - -For more information try --help - -``` - -### Validated values - -More generally, you can validate and parse into any data type. - -[Example:](04_02_parse.rs) -```console -$ 04_02_parse_derive --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 04_02_parse_derive[EXE] <PORT> - -ARGS: - <PORT> Network port to use - -OPTIONS: - -h, --help Print help information - -V, --version Print version information - -$ 04_02_parse_derive 22 -PORT = 22 - -$ 04_02_parse_derive foobar -? failed -error: Invalid value "foobar" for '<PORT>': invalid digit found in string - -For more information try --help - -$ 04_02_parse_derive 0 -? failed -error: Invalid value "0" for '<PORT>': 0 is not in 1..=65535 - -For more information try --help - -``` - -A custom parser can be used to improve the error messages or provide additional validation: - -[Example:](04_02_validate.rs) -```console -$ 04_02_validate_derive --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 04_02_validate_derive[EXE] <PORT> - -ARGS: - <PORT> Network port to use - -OPTIONS: - -h, --help Print help information - -V, --version Print version information - -$ 04_02_validate_derive 22 -PORT = 22 - -$ 04_02_validate_derive foobar -? failed -error: Invalid value "foobar" for '<PORT>': `foobar` isn't a port number - -For more information try --help - -$ 04_02_validate_derive 0 -? failed -error: Invalid value "0" for '<PORT>': Port not in range 1-65535 - -For more information try --help - -``` - -### Argument Relations - -You can declare dependencies or conflicts between `Arg`s or even `ArgGroup`s. - -`ArgGroup`s make it easier to declare relations 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. - -[Example:](04_03_relations.rs) -```console -$ 04_03_relations_derive --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 04_03_relations_derive[EXE] [OPTIONS] <--set-ver <VER>|--major|--minor|--patch> [INPUT_FILE] - -ARGS: - <INPUT_FILE> some regular input - -OPTIONS: - -c <CONFIG> - -h, --help Print help information - --major auto inc major - --minor auto inc minor - --patch auto inc patch - --set-ver <VER> set version manually - --spec-in <SPEC_IN> some special input argument - -V, --version Print version information - -$ 04_03_relations_derive -? failed -error: The following required arguments were not provided: - <--set-ver <VER>|--major|--minor|--patch> - -USAGE: - 04_03_relations_derive[EXE] [OPTIONS] <--set-ver <VER>|--major|--minor|--patch> [INPUT_FILE] - -For more information try --help - -$ 04_03_relations_derive --major -Version: 2.2.3 - -$ 04_03_relations_derive --major --minor -? failed -error: The argument '--major' cannot be used with '--minor' - -USAGE: - 04_03_relations_derive[EXE] <--set-ver <VER>|--major|--minor|--patch> - -For more information try --help - -$ 04_03_relations_derive --major -c config.toml -? failed -error: The following required arguments were not provided: - <INPUT_FILE|--spec-in <SPEC_IN>> - -USAGE: - 04_03_relations_derive[EXE] -c <CONFIG> <--set-ver <VER>|--major|--minor|--patch> <INPUT_FILE|--spec-in <SPEC_IN>> - -For more information try --help - -$ 04_03_relations_derive --major -c config.toml --spec-in input.txt -Version: 2.2.3 -Doing work using input input.txt and config config.toml - -``` - -### Custom Validation - -As a last resort, you can create custom errors with the basics of clap's formatting. - -[Example:](04_04_custom.rs) -```console -$ 04_04_custom_derive --help -clap [..] -A simple to use, efficient, and full-featured Command Line Argument Parser - -USAGE: - 04_04_custom_derive[EXE] [OPTIONS] [INPUT_FILE] - -ARGS: - <INPUT_FILE> some regular input - -OPTIONS: - -c <CONFIG> - -h, --help Print help information - --major auto inc major - --minor auto inc minor - --patch auto inc patch - --set-ver <VER> set version manually - --spec-in <SPEC_IN> some special input argument - -V, --version Print version information - -$ 04_04_custom_derive -? failed -error: Can only modify one version field - -USAGE: - clap [OPTIONS] [INPUT_FILE] - -For more information try --help - -$ 04_04_custom_derive --major -Version: 2.2.3 - -$ 04_04_custom_derive --major --minor -? failed -error: Can only modify one version field - -USAGE: - clap [OPTIONS] [INPUT_FILE] - -For more information try --help - -$ 04_04_custom_derive --major -c config.toml -? failed -Version: 2.2.3 -error: INPUT_FILE or --spec-in is required when using --config - -USAGE: - clap [OPTIONS] [INPUT_FILE] - -For more information try --help - -$ 04_04_custom_derive --major -c config.toml --spec-in input.txt -Version: 2.2.3 -Doing work using input input.txt and config config.toml - -``` - -## Tips - -- For more complex demonstration of features, see our [examples](../README.md). -- See the [derive reference](../derive_ref/README.md) to understand how to use - anything in the [builder API](https://docs.rs/clap/) in the derive API. -- Proactively check for bad `Command` configurations by calling `Command::debug_assert` in a test ([example](05_01_assert.rs)) - -## Contributing - -New example code: -- Please update the corresponding section in the [builder tutorial](../tutorial_builder/README.md) -- Building: They must be added to [Cargo.toml](../../Cargo.toml) with the appropriate `required-features`. -- Testing: Ensure there is a markdown file with [trycmd](https://docs.rs/trycmd) syntax (generally they'll go in here). - -See also the general [CONTRIBUTING](../../CONTRIBUTING.md). |