From e8218733c28ecdba1f8c20001a319ae763b45692 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 22 Feb 2022 08:23:58 -0600 Subject: [PATCH 1/8] docs(derive): Clarify subcommand arg syntax --- Cargo.toml | 5 +++ .../tutorial_derive/03_04_subcommands_alt.rs | 32 +++++++++++++++++++ examples/tutorial_derive/README.md | 4 +++ 3 files changed, 41 insertions(+) create mode 100644 examples/tutorial_derive/03_04_subcommands_alt.rs diff --git a/Cargo.toml b/Cargo.toml index 220ff739cc8..9faaee57035 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -309,6 +309,11 @@ name = "03_04_subcommands_derive" path = "examples/tutorial_derive/03_04_subcommands.rs" required-features = ["derive"] +[[example]] +name = "03_04_subcommands_alt_derive" +path = "examples/tutorial_derive/03_04_subcommands_alt.rs" +required-features = ["derive"] + [[example]] name = "03_05_default_values_derive" path = "examples/tutorial_derive/03_05_default_values.rs" diff --git a/examples/tutorial_derive/03_04_subcommands_alt.rs b/examples/tutorial_derive/03_04_subcommands_alt.rs new file mode 100644 index 00000000000..d152a2a6b7a --- /dev/null +++ b/examples/tutorial_derive/03_04_subcommands_alt.rs @@ -0,0 +1,32 @@ +use clap::{Parser, Subcommand, Args}; + +#[derive(Parser)] +#[clap(author, version, about, long_about = None)] +#[clap(propagate_version = true)] +struct Cli { + #[clap(subcommand)] + command: Commands, +} + +#[derive(Subcommand)] +enum Commands { + /// Adds files to myapp + Add(Add), +} + +#[derive(Args)] +struct Add { + name: Option +} + +fn main() { + let cli = Cli::parse(); + + // You can check for the existence of subcommands, and if found use their + // matches just as you would the top level cmd + match &cli.command { + Commands::Add { name } => { + println!("'myapp add' was used, name is: {:?}", name) + } + } +} diff --git a/examples/tutorial_derive/README.md b/examples/tutorial_derive/README.md index 662acc6cecf..99111d63d05 100644 --- a/examples/tutorial_derive/README.md +++ b/examples/tutorial_derive/README.md @@ -306,6 +306,10 @@ $ 03_04_subcommands_derive add bob ``` +Above, we used a struct-variant to define the `add` subcommand. Alternatively, +you can +[use a struct for your subcommand's arguments](03_04_subcommands_alt_derive.rs). + Because we used `command: Commands` instead of `command: Option`: ```console $ 03_04_subcommands_derive From 3eee9add96b85c97a98c1b8bc2eae1a31c852f4a Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 22 Feb 2022 08:27:35 -0600 Subject: [PATCH 2/8] docs(derive): Add tip about derive reference One of the concerns in #3490 was the finding of derive reference. Having it at the end for a "next step" seems appropriate. --- examples/tutorial_derive/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/examples/tutorial_derive/README.md b/examples/tutorial_derive/README.md index 99111d63d05..e4a0beb61de 100644 --- a/examples/tutorial_derive/README.md +++ b/examples/tutorial_derive/README.md @@ -615,6 +615,8 @@ Doing work using input input.txt and config config.toml ## Tips - Proactively check for bad `Command` configurations by calling `Command::debug_assert` ([example](05_01_assert.rs)) +- See the [derive reference](../derive_ref/README.md) to understand how to use + anything in the [builder API](https://docs.rs/clap/) in the derive API. ## Contributing From 9946579fc9a838100d18f43f6091d900af52fbca Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 22 Feb 2022 08:29:53 -0600 Subject: [PATCH 3/8] docs(tutorial): Clarify to debug_assert in tests --- examples/tutorial_builder/README.md | 2 +- examples/tutorial_derive/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/tutorial_builder/README.md b/examples/tutorial_builder/README.md index 990d6af120f..e0fcbb3202a 100644 --- a/examples/tutorial_builder/README.md +++ b/examples/tutorial_builder/README.md @@ -642,7 +642,7 @@ Doing work using input input.txt and config config.toml ## Tips -- Proactively check for bad `Command` configurations by calling `Command::debug_assert` ([example](05_01_assert.rs)) +- Proactively check for bad `Command` configurations by calling `Command::debug_assert` in a test ([example](05_01_assert.rs)) ## Contributing diff --git a/examples/tutorial_derive/README.md b/examples/tutorial_derive/README.md index e4a0beb61de..64e3a6a0401 100644 --- a/examples/tutorial_derive/README.md +++ b/examples/tutorial_derive/README.md @@ -614,7 +614,7 @@ Doing work using input input.txt and config config.toml ## Tips -- Proactively check for bad `Command` configurations by calling `Command::debug_assert` ([example](05_01_assert.rs)) +- Proactively check for bad `Command` configurations by calling `Command::debug_assert` in a test ([example](05_01_assert.rs)) - See the [derive reference](../derive_ref/README.md) to understand how to use anything in the [builder API](https://docs.rs/clap/) in the derive API. From 517b8e4233e03d9ba8bd508bfe0ebd2121ea0cff Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 22 Feb 2022 08:31:02 -0600 Subject: [PATCH 4/8] docs(derive): Clarify the break down --- examples/derive_ref/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/derive_ref/README.md b/examples/derive_ref/README.md index bdb8fdc9b6c..f55d52e7ea0 100644 --- a/examples/derive_ref/README.md +++ b/examples/derive_ref/README.md @@ -16,7 +16,7 @@ To derive `clap` types, you need to enable the `derive` feature flag. See [demo.rs](../demo.rs) and [demo.md](../demo.md) for a brief example. -Let's start by breaking down what can go where: +Let's start by breaking down the anatomy of the derive attributes: ```rust use clap::{Parser, Args, Subcommand, ArgEnum}; From 7e51f7c03da2ced4053dfaafb2835b8a3767404a Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 22 Feb 2022 08:32:18 -0600 Subject: [PATCH 5/8] docs(derive): Call out different subcommand arg syntaxes --- examples/derive_ref/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/examples/derive_ref/README.md b/examples/derive_ref/README.md index f55d52e7ea0..ddbb97fbb71 100644 --- a/examples/derive_ref/README.md +++ b/examples/derive_ref/README.md @@ -78,6 +78,7 @@ fn main() { - `Parser` parses arguments into a `struct` (arguments) or `enum` (subcommands). - `Args` allows defining a set of re-usable arguments that get merged into their parent container. - `Subcommand` defines available subcommands. + - Subcommand arguments can be defined in a struct-variant or automatically flattened with a tuple-variant. - `ArgEnum` allows parsing a value directly into an `enum`, erroring on unsupported values. See also the [tutorial](../tutorial_derive/README.md) and [examples](../README.md). From c55989459fc528306df87be539b75fcb2775dc84 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 22 Feb 2022 08:37:13 -0600 Subject: [PATCH 6/8] docs(tutorial): Examples as next step --- examples/tutorial_builder/README.md | 1 + examples/tutorial_derive/README.md | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/examples/tutorial_builder/README.md b/examples/tutorial_builder/README.md index e0fcbb3202a..9798a24278b 100644 --- a/examples/tutorial_builder/README.md +++ b/examples/tutorial_builder/README.md @@ -642,6 +642,7 @@ 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 diff --git a/examples/tutorial_derive/README.md b/examples/tutorial_derive/README.md index 64e3a6a0401..dc242bfc2e5 100644 --- a/examples/tutorial_derive/README.md +++ b/examples/tutorial_derive/README.md @@ -614,9 +614,10 @@ Doing work using input input.txt and config config.toml ## Tips -- Proactively check for bad `Command` configurations by calling `Command::debug_assert` in a test ([example](05_01_assert.rs)) +- For more complex demonstration of features, see our [examples](../README.md). - See the [derive reference](../derive_ref/README.md) to understand how to use anything in the [builder API](https://docs.rs/clap/) in the derive API. +- Proactively check for bad `Command` configurations by calling `Command::debug_assert` in a test ([example](05_01_assert.rs)) ## Contributing From f7419ec3d2057abc1cb425e226283333dcc37925 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 22 Feb 2022 08:43:33 -0600 Subject: [PATCH 7/8] docs(examples): Be explicit about example topics --- examples/README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/examples/README.md b/examples/README.md index 946822ddb08..690789d7bb1 100644 --- a/examples/README.md +++ b/examples/README.md @@ -2,13 +2,28 @@ - Basic demo: [derive](demo.md) - Key-value pair arguments: [derive](keyvalue-derive.md) + - Topics: + - Custom `parse()` - Custom cargo command: [builder](cargo-example.md), [derive](cargo-example-derive.md) + - Topics: + - Subcommands + - Cargo plugins - git-like interface: [builder](git.md), [derive](git-derive.md) + - Topics: + - Subcommands + - External subcommands - pacman-like interface: [builder](pacman.md) + - Topics: + - Flag subcommands + - Conflicting arguments - Escaped positionals with `--`: [builder](escaped-positional.md), [derive](escaped-positional-derive.md) - Multi-call - busybox: [builder](multicall-busybox.md) + - Topics: + - Subcommands - hostname: [builder](multicall-hostname.md) + - Topics: + - Subcommands ## Contributing From cb9cb251a9ac714a4e6d8724bfc5dc62275865e1 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 22 Feb 2022 17:40:28 -0600 Subject: [PATCH 8/8] style: Clean up --- examples/tutorial_derive/03_04_subcommands_alt.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/examples/tutorial_derive/03_04_subcommands_alt.rs b/examples/tutorial_derive/03_04_subcommands_alt.rs index d152a2a6b7a..0a5b60682d4 100644 --- a/examples/tutorial_derive/03_04_subcommands_alt.rs +++ b/examples/tutorial_derive/03_04_subcommands_alt.rs @@ -1,4 +1,4 @@ -use clap::{Parser, Subcommand, Args}; +use clap::{Args, Parser, Subcommand}; #[derive(Parser)] #[clap(author, version, about, long_about = None)] @@ -16,7 +16,7 @@ enum Commands { #[derive(Args)] struct Add { - name: Option + name: Option, } fn main() { @@ -25,8 +25,8 @@ fn main() { // You can check for the existence of subcommands, and if found use their // matches just as you would the top level cmd match &cli.command { - Commands::Add { name } => { - println!("'myapp add' was used, name is: {:?}", name) + Commands::Add(name) => { + println!("'myapp add' was used, name is: {:?}", name.name) } } }