Merge pull request #4048 from epage/backport

docs(tutorial): Switch to hand-implemented ValueEnum

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"

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<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!() // requires `cargo` feature
         .arg(

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:
-    <name>    Optional name to operate on
+    <NAME>    Optional name to operate on
 
 OPTIONS:
     -c, --config <FILE>    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...
 

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 <VALUE> --one <VALUE>
+    02_app_settings_derive[EXE] --two <TWO> --one <ONE>
 
 OPTIONS:
-        --two <VALUE>    
-        --one <VALUE>    
-    -h, --help           Print help information
-    -V, --version        Print version information
+        --two <TWO>    
+        --one <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"
 

examples/tutorial_derive/02_apps.md

@@ -1,19 +1,19 @@
 ```console
-$ 02_apps --help
+$ 02_apps_derive --help
 MyApp 1.0
 Kevin K. <kbknapp@gmail.com>
 Does awesome things
 
 USAGE:
-    02_apps[EXE] --two <VALUE> --one <VALUE>
+    02_apps_derive[EXE] --two <TWO> --one <ONE>
 
 OPTIONS:
-    -h, --help           Print help information
-        --one <VALUE>    
-        --two <VALUE>    
-    -V, --version        Print version information
+    -h, --help         Print help information
+        --one <ONE>    
+        --two <TWO>    
+    -V, --version      Print version information
 
-$ 02_apps --version
+$ 02_apps_derive --version
 MyApp 1.0
 
 ```

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 <VALUE> --one <VALUE>
+    02_crate_derive[EXE] --two <TWO> --one <ONE>
 
 OPTIONS:
-    -h, --help           Print help information
-        --one <VALUE>    
-        --two <VALUE>    
-    -V, --version        Print version information
+    -h, --help         Print help information
+        --one <ONE>    
+        --two <TWO>    
+    -V, --version      Print version information
 
-$ 02_crate --version
+$ 02_crate_derive --version
 clap [..]
 
 ```

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
 
 ```

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
 
 ```

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 <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")
 
 ```

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:
     <NAME>    
@@ -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")
 
 ```

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] <SUBCOMMAND>
+    03_04_subcommands_derive[EXE] <SUBCOMMAND>
 
 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:
     <NAME>    
@@ -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<Commands>`:
 ```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] <SUBCOMMAND>
+    03_04_subcommands_derive[EXE] <SUBCOMMAND>
 
 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 [..]
 
 ```

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:
     <NAME>    [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"
 
 ```