Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-12-12 13:52:34 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #4045 from epage/enum

Browse source 
docs(tutorial): Switch to hand-implemented ValueEnum
This commit is contained in:
Ed Page 2022-08-09 11:30:23 -05:00 committed by GitHub
commit 6aa4f90609
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
18 changed files with 140 additions and 104 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
Cargo.toml
View file

@ -206,7 +206,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"

40
examples/tutorial_builder/04_01_enum.rs
View file

@ -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(

10
examples/tutorial_derive/01_quick.md
View file

@ -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...

14
examples/tutorial_derive/02_app_settings.md
View file

@ -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"

14
examples/tutorial_derive/02_apps.md
View file

@ -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:
--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_apps --version
$ 02_apps_derive --version
MyApp 1.0
```

14
examples/tutorial_derive/02_crate.md
View file

@ -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:
--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_crate --version
$ 02_crate_derive --version
clap [..]
```

10
examples/tutorial_derive/03_01_flag_bool.md
View file

@ -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:
-v, --verbose
-h, --help Print help information
-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
```

10
examples/tutorial_derive/03_01_flag_count.md
View file

@ -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:
-v, --verbose...
-h, --help Print help information
-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
```

16
examples/tutorial_derive/03_02_option.md
View file

@ -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:
-n, --name <NAME>
-h, --help Print help information
-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")
```

12
examples/tutorial_derive/03_03_positional.md
View file

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

18
examples/tutorial_derive/03_04_subcommands.md
View file

@ -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_derive help add
clap-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_derive add --version
clap-add [..]
```

12
examples/tutorial_derive/03_05_default_values.md
View file

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

10
examples/tutorial_derive/04_01_enum.md
View file

@ -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] <MODE>
04_01_enum_derive[EXE] <MODE>
ARGS:
<MODE> 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 '<MODE>'
[possible values: fast, slow]

8
examples/tutorial_derive/04_02_parse.md
View file

@ -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] <PORT>
04_02_parse_derive[EXE] <PORT>
ARGS:
<PORT> 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 '<PORT>': invalid digit found in string

10
examples/tutorial_derive/04_02_validate.md
View file

@ -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] <PORT>
04_02_validate_derive[EXE] <PORT>
ARGS:
<PORT> 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 '<PORT>': `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>': Port not in range 1-65535

20
examples/tutorial_derive/04_03_relations.md
View file

@ -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 <VER>|--major|--minor|--patch> [INPUT_FILE]
04_03_relations_derive[EXE] [OPTIONS] <--set-ver <VER>|--major|--minor|--patch> [INPUT_FILE]
ARGS:
<INPUT_FILE> some regular input
@ -19,39 +19,39 @@ OPTIONS:
-h, --help Print help information
-V, --version Print version information
$ 04_03_relations
$ 04_03_relations_derive
? 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]
04_03_relations_derive[EXE] [OPTIONS] <--set-ver <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 <VER>|--major|--minor|--patch>
04_03_relations_derive[EXE] <--set-ver <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:
<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>>
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 --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

4
examples/tutorial_derive/04_03_relations.rs
View file

@ -5,7 +5,7 @@ use clap::{ArgGroup, Parser};
#[clap(group(
ArgGroup::new("vers")
.required(true)
.args(&["set-ver", "major", "minor", "patch"]),
.args(&["set_ver", "major", "minor", "patch"]),
))]
struct Cli {
/// set version manually
@ -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 {

20
examples/tutorial_derive/04_04_custom.md
View file

@ -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:
<INPUT_FILE> some regular input
@ -19,38 +19,38 @@ OPTIONS:
-h, --help Print help information
-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