Skip to content

Commit 565c5ea

Browse files
epageepage
authored
Merge pull request #4048 from epage/backport
docs(tutorial): Switch to hand-implemented ValueEnum
2 parents a61f874 + 3af94ec commit 565c5ea

18 files changed

+141
-105
lines changed

‎Cargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -210,7 +210,7 @@ required-features = ["cargo"]
210210
[[example]]
211211
name = "04_01_enum"
212212
path = "examples/tutorial_builder/04_01_enum.rs"
213-
required-features = ["cargo", "derive"]
213+
required-features = ["cargo"]
214214

215215
[[example]]
216216
name = "04_02_parse"

‎examples/tutorial_builder/04_01_enum.rs‎

Lines changed: 38 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,47 @@
1-
use clap::{arg, command, value_parser, ValueEnum};
1+
use clap::{arg, builder::PossibleValue, command, value_parser, ValueEnum};
22

3-
#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum)] // requires `derive` feature
3+
#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
44
enum Mode {
55
Fast,
66
Slow,
77
}
88

9+
// Can also be derived] with feature flag `derive`
10+
impl ValueEnum for Mode {
11+
fn value_variants<'a>() -> &'a [Self] {
12+
&[Mode::Fast, Mode::Slow]
13+
}
14+
15+
fn to_possible_value<'a>(&self) -> Option<PossibleValue<'a>> {
16+
Some(match self {
17+
Mode::Fast => PossibleValue::new("fast"),
18+
Mode::Slow => PossibleValue::new("slow"),
19+
})
20+
}
21+
}
22+
23+
impl std::fmt::Display for Mode {
24+
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
25+
self.to_possible_value()
26+
.expect("no values are skipped")
27+
.get_name()
28+
.fmt(f)
29+
}
30+
}
31+
32+
impl std::str::FromStr for Mode {
33+
type Err = String;
34+
35+
fn from_str(s: &str) -> Result<Self, Self::Err> {
36+
for variant in Self::value_variants() {
37+
if variant.to_possible_value().unwrap().matches(s, false) {
38+
return Ok(*variant);
39+
}
40+
}
41+
Err(format!("Invalid variant: {}", s))
42+
}
43+
}
44+
945
fn main() {
1046
let matches = command!() // requires `cargo` feature
1147
.arg(

‎examples/tutorial_derive/01_quick.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
```console
2-
$ 01_quick --help
2+
$ 01_quick_derive --help
33
clap [..]
44
A simple to use, efficient, and full-featured Command Line Argument Parser
55

66
USAGE:
7-
01_quick[EXE] [OPTIONS] [name] [SUBCOMMAND]
7+
01_quick_derive[EXE] [OPTIONS] [NAME] [SUBCOMMAND]
88

99
ARGS:
10-
<name> Optional name to operate on
10+
<NAME> Optional name to operate on
1111

1212
OPTIONS:
1313
-c, --config <FILE> Sets a custom config file
@@ -23,14 +23,14 @@ SUBCOMMANDS:
2323

2424
By default, the program does nothing:
2525
```console
26-
$ 01_quick
26+
$ 01_quick_derive
2727
Debug mode is off
2828

2929
```
3030

3131
But you can mix and match the various features
3232
```console
33-
$ 01_quick -dd test
33+
$ 01_quick_derive -dd test
3434
Debug mode is on
3535
Not printing testing lists...
3636

‎examples/tutorial_derive/02_app_settings.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
11
```console
2-
$ 02_app_settings --help
2+
$ 02_app_settings_derive --help
33
clap [..]
44
A simple to use, efficient, and full-featured Command Line Argument Parser
55

66
USAGE:
7-
02_app_settings[EXE] --two <VALUE> --one <VALUE>
7+
02_app_settings_derive[EXE] --two <TWO> --one <ONE>
88

99
OPTIONS:
10-
--two <VALUE>
11-
--one <VALUE>
12-
-h, --help Print help information
13-
-V, --version Print version information
10+
--two <TWO>
11+
--one <ONE>
12+
-h, --help Print help information
13+
-V, --version Print version information
1414

15-
$ 02_app_settings --one -1 --one -3 --two 10
15+
$ 02_app_settings_derive --one -1 --one -3 --two 10
1616
two: "10"
1717
one: "-3"
1818

‎examples/tutorial_derive/02_apps.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
11
```console
2-
$ 02_apps --help
2+
$ 02_apps_derive --help
33
MyApp 1.0
44
Kevin K. <kbknapp@gmail.com>
55
Does awesome things
66

77
USAGE:
8-
02_apps[EXE] --two <VALUE> --one <VALUE>
8+
02_apps_derive[EXE] --two <TWO> --one <ONE>
99

1010
OPTIONS:
11-
-h, --help Print help information
12-
--one <VALUE>
13-
--two <VALUE>
14-
-V, --version Print version information
11+
-h, --help Print help information
12+
--one <ONE>
13+
--two <TWO>
14+
-V, --version Print version information
1515

16-
$ 02_apps --version
16+
$ 02_apps_derive --version
1717
MyApp 1.0
1818

1919
```

‎examples/tutorial_derive/02_crate.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
11
```console
2-
$ 02_crate --help
2+
$ 02_crate_derive --help
33
clap [..]
44
A simple to use, efficient, and full-featured Command Line Argument Parser
55

66
USAGE:
7-
02_crate[EXE] --two <VALUE> --one <VALUE>
7+
02_crate_derive[EXE] --two <TWO> --one <ONE>
88

99
OPTIONS:
10-
-h, --help Print help information
11-
--one <VALUE>
12-
--two <VALUE>
13-
-V, --version Print version information
10+
-h, --help Print help information
11+
--one <ONE>
12+
--two <TWO>
13+
-V, --version Print version information
1414

15-
$ 02_crate --version
15+
$ 02_crate_derive --version
1616
clap [..]
1717

1818
```

‎examples/tutorial_derive/03_01_flag_bool.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,23 @@
11
```console
2-
$ 03_01_flag_bool --help
2+
$ 03_01_flag_bool_derive --help
33
clap [..]
44
A simple to use, efficient, and full-featured Command Line Argument Parser
55

66
USAGE:
7-
03_01_flag_bool[EXE] [OPTIONS]
7+
03_01_flag_bool_derive[EXE] [OPTIONS]
88

99
OPTIONS:
1010
-h, --help Print help information
1111
-v, --verbose
1212
-V, --version Print version information
1313

14-
$ 03_01_flag_bool
14+
$ 03_01_flag_bool_derive
1515
verbose: false
1616

17-
$ 03_01_flag_bool --verbose
17+
$ 03_01_flag_bool_derive --verbose
1818
verbose: true
1919

20-
$ 03_01_flag_bool --verbose --verbose
20+
$ 03_01_flag_bool_derive --verbose --verbose
2121
verbose: true
2222

2323
```

‎examples/tutorial_derive/03_01_flag_count.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,23 @@
11
```console
2-
$ 03_01_flag_count --help
2+
$ 03_01_flag_count_derive --help
33
clap [..]
44
A simple to use, efficient, and full-featured Command Line Argument Parser
55

66
USAGE:
7-
03_01_flag_count[EXE] [OPTIONS]
7+
03_01_flag_count_derive[EXE] [OPTIONS]
88

99
OPTIONS:
1010
-h, --help Print help information
1111
-v, --verbose
1212
-V, --version Print version information
1313

14-
$ 03_01_flag_count
14+
$ 03_01_flag_count_derive
1515
verbose: 0
1616

17-
$ 03_01_flag_count --verbose
17+
$ 03_01_flag_count_derive --verbose
1818
verbose: 1
1919

20-
$ 03_01_flag_count --verbose --verbose
20+
$ 03_01_flag_count_derive --verbose --verbose
2121
verbose: 2
2222

2323
```

‎examples/tutorial_derive/03_02_option.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,32 @@
11
```console
2-
$ 03_02_option --help
2+
$ 03_02_option_derive --help
33
clap [..]
44
A simple to use, efficient, and full-featured Command Line Argument Parser
55

66
USAGE:
7-
03_02_option[EXE] [OPTIONS]
7+
03_02_option_derive[EXE] [OPTIONS]
88

99
OPTIONS:
1010
-h, --help Print help information
1111
-n, --name <NAME>
1212
-V, --version Print version information
1313

14-
$ 03_02_option
14+
$ 03_02_option_derive
1515
name: None
1616

17-
$ 03_02_option --name bob
17+
$ 03_02_option_derive --name bob
1818
name: Some("bob")
1919

20-
$ 03_02_option --name=bob
20+
$ 03_02_option_derive --name=bob
2121
name: Some("bob")
2222

23-
$ 03_02_option -n bob
23+
$ 03_02_option_derive -n bob
2424
name: Some("bob")
2525

26-
$ 03_02_option -n=bob
26+
$ 03_02_option_derive -n=bob
2727
name: Some("bob")
2828

29-
$ 03_02_option -nbob
29+
$ 03_02_option_derive -nbob
3030
name: Some("bob")
3131

3232
```

‎examples/tutorial_derive/03_03_positional.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
```console
2-
$ 03_03_positional --help
2+
$ 03_03_positional_derive --help
33
clap [..]
44
A simple to use, efficient, and full-featured Command Line Argument Parser
55

66
USAGE:
7-
03_03_positional[EXE] [NAME]
7+
03_03_positional_derive[EXE] [NAME]
88

99
ARGS:
1010
<NAME>
@@ -13,10 +13,10 @@ OPTIONS:
1313
-h, --help Print help information
1414
-V, --version Print version information
1515

16-
$ 03_03_positional
17-
NAME: None
16+
$ 03_03_positional_derive
17+
name: None
1818

19-
$ 03_03_positional bob
20-
NAME: Some("bob")
19+
$ 03_03_positional_derive bob
20+
name: Some("bob")
2121

2222
```

0 commit comments

Comments
 (0)