diff --git a/Cargo.toml b/Cargo.toml index f113b351029..4f3c2b83b6c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -210,7 +210,7 @@ required-features = ["cargo"] [[example]] name = "04_01_enum" path = "examples/tutorial_builder/04_01_enum.rs" -required-features = ["cargo", "derive"] +required-features = ["cargo"] [[example]] name = "04_02_parse" diff --git a/examples/tutorial_builder/04_01_enum.rs b/examples/tutorial_builder/04_01_enum.rs index e76c9512e1e..e8cf70f5c59 100644 --- a/examples/tutorial_builder/04_01_enum.rs +++ b/examples/tutorial_builder/04_01_enum.rs @@ -1,11 +1,47 @@ -use clap::{arg, command, value_parser, ValueEnum}; +use clap::{arg, builder::PossibleValue, command, value_parser, ValueEnum}; -#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum)] // requires `derive` feature +#[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> { + 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 { + 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!() // requires `cargo` feature .arg( diff --git a/examples/tutorial_derive/01_quick.md b/examples/tutorial_derive/01_quick.md index 4a9e3fca17a..6f70d2ccea9 100644 --- a/examples/tutorial_derive/01_quick.md +++ b/examples/tutorial_derive/01_quick.md @@ -1,13 +1,13 @@ ```console -$ 01_quick --help +$ 01_quick_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser USAGE: - 01_quick[EXE] [OPTIONS] [name] [SUBCOMMAND] + 01_quick_derive[EXE] [OPTIONS] [NAME] [SUBCOMMAND] ARGS: - Optional name to operate on + Optional name to operate on OPTIONS: -c, --config Sets a custom config file @@ -23,14 +23,14 @@ SUBCOMMANDS: By default, the program does nothing: ```console -$ 01_quick +$ 01_quick_derive Debug mode is off ``` But you can mix and match the various features ```console -$ 01_quick -dd test +$ 01_quick_derive -dd test Debug mode is on Not printing testing lists... diff --git a/examples/tutorial_derive/02_app_settings.md b/examples/tutorial_derive/02_app_settings.md index 247843bcfdc..ee16c66df7c 100644 --- a/examples/tutorial_derive/02_app_settings.md +++ b/examples/tutorial_derive/02_app_settings.md @@ -1,18 +1,18 @@ ```console -$ 02_app_settings --help +$ 02_app_settings_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser USAGE: - 02_app_settings[EXE] --two --one + 02_app_settings_derive[EXE] --two --one OPTIONS: - --two - --one - -h, --help Print help information - -V, --version Print version information + --two + --one + -h, --help Print help information + -V, --version Print version information -$ 02_app_settings --one -1 --one -3 --two 10 +$ 02_app_settings_derive --one -1 --one -3 --two 10 two: "10" one: "-3" diff --git a/examples/tutorial_derive/02_apps.md b/examples/tutorial_derive/02_apps.md index 8504b5f5220..0141581c4ef 100644 --- a/examples/tutorial_derive/02_apps.md +++ b/examples/tutorial_derive/02_apps.md @@ -1,19 +1,19 @@ ```console -$ 02_apps --help +$ 02_apps_derive --help MyApp 1.0 Kevin K. Does awesome things USAGE: - 02_apps[EXE] --two --one + 02_apps_derive[EXE] --two --one OPTIONS: - -h, --help Print help information - --one - --two - -V, --version Print version information + -h, --help Print help information + --one + --two + -V, --version Print version information -$ 02_apps --version +$ 02_apps_derive --version MyApp 1.0 ``` diff --git a/examples/tutorial_derive/02_crate.md b/examples/tutorial_derive/02_crate.md index f76e0d608b5..92c82075816 100644 --- a/examples/tutorial_derive/02_crate.md +++ b/examples/tutorial_derive/02_crate.md @@ -1,18 +1,18 @@ ```console -$ 02_crate --help +$ 02_crate_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser USAGE: - 02_crate[EXE] --two --one + 02_crate_derive[EXE] --two --one OPTIONS: - -h, --help Print help information - --one - --two - -V, --version Print version information + -h, --help Print help information + --one + --two + -V, --version Print version information -$ 02_crate --version +$ 02_crate_derive --version clap [..] ``` diff --git a/examples/tutorial_derive/03_01_flag_bool.md b/examples/tutorial_derive/03_01_flag_bool.md index b0ee2a12635..0baaa10cad6 100644 --- a/examples/tutorial_derive/03_01_flag_bool.md +++ b/examples/tutorial_derive/03_01_flag_bool.md @@ -1,23 +1,23 @@ ```console -$ 03_01_flag_bool --help +$ 03_01_flag_bool_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser USAGE: - 03_01_flag_bool[EXE] [OPTIONS] + 03_01_flag_bool_derive[EXE] [OPTIONS] OPTIONS: -h, --help Print help information -v, --verbose -V, --version Print version information -$ 03_01_flag_bool +$ 03_01_flag_bool_derive verbose: false -$ 03_01_flag_bool --verbose +$ 03_01_flag_bool_derive --verbose verbose: true -$ 03_01_flag_bool --verbose --verbose +$ 03_01_flag_bool_derive --verbose --verbose verbose: true ``` diff --git a/examples/tutorial_derive/03_01_flag_count.md b/examples/tutorial_derive/03_01_flag_count.md index ca4bcd6eb89..3d5a53084de 100644 --- a/examples/tutorial_derive/03_01_flag_count.md +++ b/examples/tutorial_derive/03_01_flag_count.md @@ -1,23 +1,23 @@ ```console -$ 03_01_flag_count --help +$ 03_01_flag_count_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser USAGE: - 03_01_flag_count[EXE] [OPTIONS] + 03_01_flag_count_derive[EXE] [OPTIONS] OPTIONS: -h, --help Print help information -v, --verbose -V, --version Print version information -$ 03_01_flag_count +$ 03_01_flag_count_derive verbose: 0 -$ 03_01_flag_count --verbose +$ 03_01_flag_count_derive --verbose verbose: 1 -$ 03_01_flag_count --verbose --verbose +$ 03_01_flag_count_derive --verbose --verbose verbose: 2 ``` diff --git a/examples/tutorial_derive/03_02_option.md b/examples/tutorial_derive/03_02_option.md index 6198bcc7372..84ff7fa7498 100644 --- a/examples/tutorial_derive/03_02_option.md +++ b/examples/tutorial_derive/03_02_option.md @@ -1,32 +1,32 @@ ```console -$ 03_02_option --help +$ 03_02_option_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser USAGE: - 03_02_option[EXE] [OPTIONS] + 03_02_option_derive[EXE] [OPTIONS] OPTIONS: -h, --help Print help information -n, --name -V, --version Print version information -$ 03_02_option +$ 03_02_option_derive name: None -$ 03_02_option --name bob +$ 03_02_option_derive --name bob name: Some("bob") -$ 03_02_option --name=bob +$ 03_02_option_derive --name=bob name: Some("bob") -$ 03_02_option -n bob +$ 03_02_option_derive -n bob name: Some("bob") -$ 03_02_option -n=bob +$ 03_02_option_derive -n=bob name: Some("bob") -$ 03_02_option -nbob +$ 03_02_option_derive -nbob name: Some("bob") ``` diff --git a/examples/tutorial_derive/03_03_positional.md b/examples/tutorial_derive/03_03_positional.md index a3d7b8cf347..7281fe3ffe8 100644 --- a/examples/tutorial_derive/03_03_positional.md +++ b/examples/tutorial_derive/03_03_positional.md @@ -1,10 +1,10 @@ ```console -$ 03_03_positional --help +$ 03_03_positional_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser USAGE: - 03_03_positional[EXE] [NAME] + 03_03_positional_derive[EXE] [NAME] ARGS: @@ -13,10 +13,10 @@ OPTIONS: -h, --help Print help information -V, --version Print version information -$ 03_03_positional -NAME: None +$ 03_03_positional_derive +name: None -$ 03_03_positional bob -NAME: Some("bob") +$ 03_03_positional_derive bob +name: Some("bob") ``` diff --git a/examples/tutorial_derive/03_04_subcommands.md b/examples/tutorial_derive/03_04_subcommands.md index 8f3e7a8943c..02f96e3d378 100644 --- a/examples/tutorial_derive/03_04_subcommands.md +++ b/examples/tutorial_derive/03_04_subcommands.md @@ -1,10 +1,10 @@ ```console -$ 03_04_subcommands help +$ 03_04_subcommands_derive help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser USAGE: - 03_04_subcommands[EXE] + 03_04_subcommands_derive[EXE] OPTIONS: -h, --help Print help information @@ -14,12 +14,12 @@ 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 [..] +$ 03_04_subcommands_derive help add +03_04_subcommands_derive[EXE]-add [..] Adds files to myapp USAGE: - 03_04_subcommands[EXE] add [NAME] + 03_04_subcommands_derive[EXE] add [NAME] ARGS: @@ -28,20 +28,20 @@ OPTIONS: -h, --help Print help information -V, --version Print version information -$ 03_04_subcommands add bob +$ 03_04_subcommands_derive add bob 'myapp add' was used, name is: Some("bob") ``` Because we used `command: Commands` instead of `command: Option`: ```console -$ 03_04_subcommands +$ 03_04_subcommands_derive ? failed clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser USAGE: - 03_04_subcommands[EXE] + 03_04_subcommands_derive[EXE] OPTIONS: -h, --help Print help information @@ -55,10 +55,10 @@ SUBCOMMANDS: Because we added `#[clap(propagate_version = true)]`: ```console -$ 03_04_subcommands --version +$ 03_04_subcommands_derive --version clap [..] -$ 03_04_subcommands add --version -03_04_subcommands[EXE]-add [..] +$ 03_04_subcommands_derive add --version +03_04_subcommands_derive[EXE]-add [..] ``` diff --git a/examples/tutorial_derive/03_05_default_values.md b/examples/tutorial_derive/03_05_default_values.md index 7b6c0307d34..f7315e7362d 100644 --- a/examples/tutorial_derive/03_05_default_values.md +++ b/examples/tutorial_derive/03_05_default_values.md @@ -1,10 +1,10 @@ ```console -$ 03_05_default_values --help +$ 03_05_default_values_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser USAGE: - 03_05_default_values[EXE] [NAME] + 03_05_default_values_derive[EXE] [NAME] ARGS: [default: alice] @@ -13,10 +13,10 @@ OPTIONS: -h, --help Print help information -V, --version Print version information -$ 03_05_default_values -NAME: "alice" +$ 03_05_default_values_derive +name: "alice" -$ 03_05_default_values bob -NAME: "bob" +$ 03_05_default_values_derive bob +name: "bob" ``` diff --git a/examples/tutorial_derive/04_01_enum.md b/examples/tutorial_derive/04_01_enum.md index 282b1e61344..2523af924a6 100644 --- a/examples/tutorial_derive/04_01_enum.md +++ b/examples/tutorial_derive/04_01_enum.md @@ -1,10 +1,10 @@ ```console -$ 04_01_enum --help +$ 04_01_enum_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser USAGE: - 04_01_enum[EXE] + 04_01_enum_derive[EXE] ARGS: What mode to run the program in [possible values: fast, slow] @@ -13,13 +13,13 @@ OPTIONS: -h, --help Print help information -V, --version Print version information -$ 04_01_enum fast +$ 04_01_enum_derive fast Hare -$ 04_01_enum slow +$ 04_01_enum_derive slow Tortoise -$ 04_01_enum medium +$ 04_01_enum_derive medium ? failed error: "medium" isn't a valid value for '' [possible values: fast, slow] diff --git a/examples/tutorial_derive/04_02_parse.md b/examples/tutorial_derive/04_02_parse.md index 605bf4b5920..6079ef19372 100644 --- a/examples/tutorial_derive/04_02_parse.md +++ b/examples/tutorial_derive/04_02_parse.md @@ -1,10 +1,10 @@ ```console -$ 04_02_parse --help +$ 04_02_parse_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser USAGE: - 04_02_parse[EXE] + 04_02_parse_derive[EXE] ARGS: Network port to use @@ -13,10 +13,10 @@ OPTIONS: -h, --help Print help information -V, --version Print version information -$ 04_02_parse 22 +$ 04_02_parse_derive 22 PORT = 22 -$ 04_02_parse foobar +$ 04_02_parse_derive foobar ? failed error: Invalid value "foobar" for '': invalid digit found in string diff --git a/examples/tutorial_derive/04_02_validate.md b/examples/tutorial_derive/04_02_validate.md index a317a8eb76c..cc43440efa3 100644 --- a/examples/tutorial_derive/04_02_validate.md +++ b/examples/tutorial_derive/04_02_validate.md @@ -1,10 +1,10 @@ ```console -$ 04_02_validate --help +$ 04_02_validate_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser USAGE: - 04_02_validate[EXE] + 04_02_validate_derive[EXE] ARGS: Network port to use @@ -13,16 +13,16 @@ OPTIONS: -h, --help Print help information -V, --version Print version information -$ 04_02_validate 22 +$ 04_02_validate_derive 22 PORT = 22 -$ 04_02_validate foobar +$ 04_02_validate_derive foobar ? failed error: Invalid value "foobar" for '': `foobar` isn't a port number For more information try --help -$ 04_02_validate 0 +$ 04_02_validate_derive 0 ? failed error: Invalid value "0" for '': Port not in range 1-65535 diff --git a/examples/tutorial_derive/04_03_relations.md b/examples/tutorial_derive/04_03_relations.md index 3ea33636310..4f5703d8233 100644 --- a/examples/tutorial_derive/04_03_relations.md +++ b/examples/tutorial_derive/04_03_relations.md @@ -1,10 +1,10 @@ ```console -$ 04_03_relations --help +$ 04_03_relations_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser USAGE: - 04_03_relations[EXE] [OPTIONS] <--set-ver |--major|--minor|--patch> [INPUT_FILE] + 04_03_relations_derive[EXE] [OPTIONS] <--set-ver |--major|--minor|--patch> [INPUT_FILE] ARGS: some regular input @@ -19,39 +19,39 @@ OPTIONS: --spec-in some special input argument -V, --version Print version information -$ 04_03_relations +$ 04_03_relations_derive ? failed error: The following required arguments were not provided: <--set-ver |--major|--minor|--patch> USAGE: - 04_03_relations[EXE] [OPTIONS] <--set-ver |--major|--minor|--patch> [INPUT_FILE] + 04_03_relations_derive[EXE] [OPTIONS] <--set-ver |--major|--minor|--patch> [INPUT_FILE] For more information try --help -$ 04_03_relations --major +$ 04_03_relations_derive --major Version: 2.2.3 -$ 04_03_relations --major --minor +$ 04_03_relations_derive --major --minor ? failed error: The argument '--major' cannot be used with '--minor' USAGE: - 04_03_relations[EXE] <--set-ver |--major|--minor|--patch> + 04_03_relations_derive[EXE] <--set-ver |--major|--minor|--patch> For more information try --help -$ 04_03_relations --major -c config.toml +$ 04_03_relations_derive --major -c config.toml ? failed error: The following required arguments were not provided: > USAGE: - 04_03_relations[EXE] -c <--set-ver |--major|--minor|--patch> > + 04_03_relations_derive[EXE] -c <--set-ver |--major|--minor|--patch> > For more information try --help -$ 04_03_relations --major -c config.toml --spec-in input.txt +$ 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 diff --git a/examples/tutorial_derive/04_03_relations.rs b/examples/tutorial_derive/04_03_relations.rs index f8523902d6b..37efe95e343 100644 --- a/examples/tutorial_derive/04_03_relations.rs +++ b/examples/tutorial_derive/04_03_relations.rs @@ -44,7 +44,7 @@ fn main() { let mut minor = 2; let mut patch = 3; - // See if --set-ver was used to set the version manually + // 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 { diff --git a/examples/tutorial_derive/04_04_custom.md b/examples/tutorial_derive/04_04_custom.md index 26a3df1ab6b..0f19bfe3189 100644 --- a/examples/tutorial_derive/04_04_custom.md +++ b/examples/tutorial_derive/04_04_custom.md @@ -1,10 +1,10 @@ ```console -$ 04_04_custom --help +$ 04_04_custom_derive --help clap [..] A simple to use, efficient, and full-featured Command Line Argument Parser USAGE: - 04_04_custom[EXE] [OPTIONS] [INPUT_FILE] + 04_04_custom_derive[EXE] [OPTIONS] [INPUT_FILE] ARGS: some regular input @@ -19,38 +19,38 @@ OPTIONS: --spec-in some special input argument -V, --version Print version information -$ 04_04_custom +$ 04_04_custom_derive ? failed error: Can only modify one version field USAGE: - 04_04_custom[EXE] [OPTIONS] [INPUT_FILE] + clap [OPTIONS] [INPUT_FILE] For more information try --help -$ 04_04_custom --major +$ 04_04_custom_derive --major Version: 2.2.3 -$ 04_04_custom --major --minor +$ 04_04_custom_derive --major --minor ? failed error: Can only modify one version field USAGE: - 04_04_custom[EXE] [OPTIONS] [INPUT_FILE] + clap [OPTIONS] [INPUT_FILE] For more information try --help -$ 04_04_custom --major -c config.toml +$ 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: - 04_04_custom[EXE] [OPTIONS] [INPUT_FILE] + clap [OPTIONS] [INPUT_FILE] For more information try --help -$ 04_04_custom --major -c config.toml --spec-in input.txt +$ 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