diff options
Diffstat (limited to 'vendor/clap/examples/tutorial_builder')
33 files changed, 585 insertions, 734 deletions
diff --git a/vendor/clap/examples/tutorial_builder/01_quick.md b/vendor/clap/examples/tutorial_builder/01_quick.md new file mode 100644 index 000000000..4a9e3fca1 --- /dev/null +++ b/vendor/clap/examples/tutorial_builder/01_quick.md @@ -0,0 +1,37 @@ +```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... + +``` diff --git a/vendor/clap/examples/tutorial_builder/01_quick.rs b/vendor/clap/examples/tutorial_builder/01_quick.rs index 61cc3432d..393d6aeae 100644 --- a/vendor/clap/examples/tutorial_builder/01_quick.rs +++ b/vendor/clap/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.md b/vendor/clap/examples/tutorial_builder/02_app_settings.md new file mode 100644 index 000000000..247843bcf --- /dev/null +++ b/vendor/clap/examples/tutorial_builder/02_app_settings.md @@ -0,0 +1,19 @@ +```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" + +``` diff --git a/vendor/clap/examples/tutorial_builder/02_app_settings.rs b/vendor/clap/examples/tutorial_builder/02_app_settings.rs index 7bbedd3eb..5f374d7f0 100644 --- a/vendor/clap/examples/tutorial_builder/02_app_settings.rs +++ b/vendor/clap/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.md b/vendor/clap/examples/tutorial_builder/02_apps.md new file mode 100644 index 000000000..8504b5f52 --- /dev/null +++ b/vendor/clap/examples/tutorial_builder/02_apps.md @@ -0,0 +1,19 @@ +```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 + +``` diff --git a/vendor/clap/examples/tutorial_builder/02_crate.md b/vendor/clap/examples/tutorial_builder/02_crate.md new file mode 100644 index 000000000..f76e0d608 --- /dev/null +++ b/vendor/clap/examples/tutorial_builder/02_crate.md @@ -0,0 +1,18 @@ +```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 [..] + +``` diff --git a/vendor/clap/examples/tutorial_builder/02_crate.rs b/vendor/clap/examples/tutorial_builder/02_crate.rs index 16b7e7ee0..8a1722fd3 100644 --- a/vendor/clap/examples/tutorial_builder/02_crate.rs +++ b/vendor/clap/examples/tutorial_builder/02_crate.rs @@ -1,8 +1,7 @@ -// Note: this requires the `cargo` feature - use clap::{arg, command}; fn main() { + // requires `cargo` feature, reading name, version, author, and description from `Cargo.toml` let matches = command!() .arg(arg!(--two <VALUE>)) .arg(arg!(--one <VALUE>)) diff --git a/vendor/clap/examples/tutorial_builder/03_01_flag_bool.md b/vendor/clap/examples/tutorial_builder/03_01_flag_bool.md new file mode 100644 index 000000000..b0ee2a126 --- /dev/null +++ b/vendor/clap/examples/tutorial_builder/03_01_flag_bool.md @@ -0,0 +1,23 @@ +```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 + +``` diff --git a/vendor/clap/examples/tutorial_builder/03_01_flag_bool.rs b/vendor/clap/examples/tutorial_builder/03_01_flag_bool.rs index 41ecbb1d7..03f2f1756 100644 --- a/vendor/clap/examples/tutorial_builder/03_01_flag_bool.rs +++ b/vendor/clap/examples/tutorial_builder/03_01_flag_bool.rs @@ -1,9 +1,7 @@ -// Note: this requires the `cargo` feature - use clap::{command, Arg, ArgAction}; fn main() { - let matches = command!() + let matches = command!() // requires `cargo` feature .arg( Arg::new("verbose") .short('v') @@ -12,10 +10,5 @@ fn main() { ) .get_matches(); - println!( - "verbose: {:?}", - *matches - .get_one::<bool>("verbose") - .expect("defaulted by clap") - ); + println!("verbose: {:?}", matches.get_flag("verbose")); } diff --git a/vendor/clap/examples/tutorial_builder/03_01_flag_count.md b/vendor/clap/examples/tutorial_builder/03_01_flag_count.md new file mode 100644 index 000000000..ca4bcd6eb --- /dev/null +++ b/vendor/clap/examples/tutorial_builder/03_01_flag_count.md @@ -0,0 +1,23 @@ +```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 + +``` diff --git a/vendor/clap/examples/tutorial_builder/03_01_flag_count.rs b/vendor/clap/examples/tutorial_builder/03_01_flag_count.rs index 764affbd8..7f23649d6 100644 --- a/vendor/clap/examples/tutorial_builder/03_01_flag_count.rs +++ b/vendor/clap/examples/tutorial_builder/03_01_flag_count.rs @@ -1,16 +1,9 @@ -// Note: this requires the `cargo` feature - use clap::{arg, command, ArgAction}; fn main() { - let matches = command!() + let matches = command!() // requires `cargo` feature .arg(arg!(-v - -verbose).action(ArgAction::Count)) .get_matches(); - println!( - "verbose: {:?}", - matches - .get_one::<u8>("verbose") - .expect("Count always defaulted") - ); + println!("verbose: {:?}", matches.get_count("verbose")); } diff --git a/vendor/clap/examples/tutorial_builder/03_02_option.md b/vendor/clap/examples/tutorial_builder/03_02_option.md new file mode 100644 index 000000000..6198bcc73 --- /dev/null +++ b/vendor/clap/examples/tutorial_builder/03_02_option.md @@ -0,0 +1,32 @@ +```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") + +``` diff --git a/vendor/clap/examples/tutorial_builder/03_02_option.rs b/vendor/clap/examples/tutorial_builder/03_02_option.rs index 80e2b9159..188244566 100644 --- a/vendor/clap/examples/tutorial_builder/03_02_option.rs +++ b/vendor/clap/examples/tutorial_builder/03_02_option.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!(-n --name <NAME>).required(false)) .get_matches(); diff --git a/vendor/clap/examples/tutorial_builder/03_03_positional.md b/vendor/clap/examples/tutorial_builder/03_03_positional.md new file mode 100644 index 000000000..a3d7b8cf3 --- /dev/null +++ b/vendor/clap/examples/tutorial_builder/03_03_positional.md @@ -0,0 +1,22 @@ +```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") + +``` diff --git a/vendor/clap/examples/tutorial_builder/03_03_positional.rs b/vendor/clap/examples/tutorial_builder/03_03_positional.rs index c6579409a..0c3a5f037 100644 --- a/vendor/clap/examples/tutorial_builder/03_03_positional.rs +++ b/vendor/clap/examples/tutorial_builder/03_03_positional.rs @@ -1,9 +1,9 @@ -// Note: this requires the `cargo` feature - use clap::{arg, command}; fn main() { - let matches = command!().arg(arg!([NAME])).get_matches(); + let matches = command!() // requires `cargo` feature + .arg(arg!([NAME])) + .get_matches(); println!("NAME: {:?}", matches.get_one::<String>("NAME")); } diff --git a/vendor/clap/examples/tutorial_builder/03_04_subcommands.md b/vendor/clap/examples/tutorial_builder/03_04_subcommands.md new file mode 100644 index 000000000..8f9efa911 --- /dev/null +++ b/vendor/clap/examples/tutorial_builder/03_04_subcommands.md @@ -0,0 +1,64 @@ +```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`][crate::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`][crate::Command::propagate_version]: +```console +$ 03_04_subcommands --version +clap [..] + +$ 03_04_subcommands add --version +03_04_subcommands[EXE]-add [..] + +``` diff --git a/vendor/clap/examples/tutorial_builder/03_04_subcommands.rs b/vendor/clap/examples/tutorial_builder/03_04_subcommands.rs index 1dd1cbf09..fbe23809e 100644 --- a/vendor/clap/examples/tutorial_builder/03_04_subcommands.rs +++ b/vendor/clap/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.md b/vendor/clap/examples/tutorial_builder/03_05_default_values.md new file mode 100644 index 000000000..7b6c0307d --- /dev/null +++ b/vendor/clap/examples/tutorial_builder/03_05_default_values.md @@ -0,0 +1,22 @@ +```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" + +``` diff --git a/vendor/clap/examples/tutorial_builder/03_05_default_values.rs b/vendor/clap/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/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_enum.md b/vendor/clap/examples/tutorial_builder/04_01_enum.md new file mode 100644 index 000000000..282b1e613 --- /dev/null +++ b/vendor/clap/examples/tutorial_builder/04_01_enum.md @@ -0,0 +1,29 @@ +```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 + +``` diff --git a/vendor/clap/examples/tutorial_builder/04_01_enum.rs b/vendor/clap/examples/tutorial_builder/04_01_enum.rs index ad2177c23..e8cf70f5c 100644 --- a/vendor/clap/examples/tutorial_builder/04_01_enum.rs +++ b/vendor/clap/examples/tutorial_builder/04_01_enum.rs @@ -1,15 +1,49 @@ -// Note: this requires the `cargo` feature +use clap::{arg, builder::PossibleValue, command, value_parser, ValueEnum}; -use clap::{arg, command, value_parser, ValueEnum}; - -#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum)] +#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord)] enum Mode { Fast, Slow, } +// Can also be derived] with feature flag `derive` +impl ValueEnum for Mode { + fn value_variants<'a>() -> &'a [Self] { + &[Mode::Fast, Mode::Slow] + } + + fn to_possible_value<'a>(&self) -> Option<PossibleValue<'a>> { + Some(match self { + Mode::Fast => PossibleValue::new("fast"), + Mode::Slow => PossibleValue::new("slow"), + }) + } +} + +impl std::fmt::Display for Mode { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + self.to_possible_value() + .expect("no values are skipped") + .get_name() + .fmt(f) + } +} + +impl std::str::FromStr for Mode { + type Err = String; + + fn from_str(s: &str) -> Result<Self, Self::Err> { + for variant in Self::value_variants() { + if variant.to_possible_value().unwrap().matches(s, false) { + return Ok(*variant); + } + } + Err(format!("Invalid variant: {}", s)) + } +} + 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_01_possible.md b/vendor/clap/examples/tutorial_builder/04_01_possible.md new file mode 100644 index 000000000..2909bfb17 --- /dev/null +++ b/vendor/clap/examples/tutorial_builder/04_01_possible.md @@ -0,0 +1,29 @@ +```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 + +``` diff --git a/vendor/clap/examples/tutorial_builder/04_01_possible.rs b/vendor/clap/examples/tutorial_builder/04_01_possible.rs index f7b0cfb34..3da7aca74 100644 --- a/vendor/clap/examples/tutorial_builder/04_01_possible.rs +++ b/vendor/clap/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.md b/vendor/clap/examples/tutorial_builder/04_02_parse.md new file mode 100644 index 000000000..605bf4b59 --- /dev/null +++ b/vendor/clap/examples/tutorial_builder/04_02_parse.md @@ -0,0 +1,31 @@ +```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 + +``` diff --git a/vendor/clap/examples/tutorial_builder/04_02_parse.rs b/vendor/clap/examples/tutorial_builder/04_02_parse.rs index c2f3cc533..13f41a18e 100644 --- a/vendor/clap/examples/tutorial_builder/04_02_parse.rs +++ b/vendor/clap/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.md b/vendor/clap/examples/tutorial_builder/04_02_validate.md new file mode 100644 index 000000000..a317a8eb7 --- /dev/null +++ b/vendor/clap/examples/tutorial_builder/04_02_validate.md @@ -0,0 +1,31 @@ +```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 + +``` diff --git a/vendor/clap/examples/tutorial_builder/04_02_validate.rs b/vendor/clap/examples/tutorial_builder/04_02_validate.rs index e60018a46..ea2f32e67 100644 --- a/vendor/clap/examples/tutorial_builder/04_02_validate.rs +++ b/vendor/clap/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_03_relations.md b/vendor/clap/examples/tutorial_builder/04_03_relations.md new file mode 100644 index 000000000..3ea336363 --- /dev/null +++ b/vendor/clap/examples/tutorial_builder/04_03_relations.md @@ -0,0 +1,58 @@ +```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 + +``` diff --git a/vendor/clap/examples/tutorial_builder/04_03_relations.rs b/vendor/clap/examples/tutorial_builder/04_03_relations.rs index 605e5b48e..8e26d3ea9 100644 --- a/vendor/clap/examples/tutorial_builder/04_03_relations.rs +++ b/vendor/clap/examples/tutorial_builder/04_03_relations.rs @@ -1,12 +1,10 @@ -// 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!() + let matches = 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)) @@ -52,9 +50,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, _, _) => major += 1, diff --git a/vendor/clap/examples/tutorial_builder/04_04_custom.md b/vendor/clap/examples/tutorial_builder/04_04_custom.md new file mode 100644 index 000000000..26a3df1ab --- /dev/null +++ b/vendor/clap/examples/tutorial_builder/04_04_custom.md @@ -0,0 +1,57 @@ +```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 + +``` diff --git a/vendor/clap/examples/tutorial_builder/04_04_custom.rs b/vendor/clap/examples/tutorial_builder/04_04_custom.rs index 3dc080505..fb40b2fc4 100644 --- a/vendor/clap/examples/tutorial_builder/04_04_custom.rs +++ b/vendor/clap/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_builder/05_01_assert.rs b/vendor/clap/examples/tutorial_builder/05_01_assert.rs index d6f19ffe5..4b9254230 100644 --- a/vendor/clap/examples/tutorial_builder/05_01_assert.rs +++ b/vendor/clap/examples/tutorial_builder/05_01_assert.rs @@ -1,5 +1,3 @@ -// Note: this requires the `cargo` feature - use clap::{arg, command, value_parser}; fn main() { @@ -13,14 +11,15 @@ fn main() { } fn cmd() -> clap::Command<'static> { - command!().arg( - arg!(<PORT>) - .help("Network port to use") - .value_parser(value_parser!(usize)), - ) + command!() // requires `cargo` feature + .arg( + arg!(<PORT>) + .help("Network port to use") + .value_parser(value_parser!(usize)), + ) } #[test] -fn verify_app() { +fn verify_cmd() { 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). |