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/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 diff --git a/examples/derive_ref/README.md b/examples/derive_ref/README.md index bdb8fdc9b6c..ddbb97fbb71 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}; @@ -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). diff --git a/examples/tutorial_builder/README.md b/examples/tutorial_builder/README.md index 990d6af120f..9798a24278b 100644 --- a/examples/tutorial_builder/README.md +++ b/examples/tutorial_builder/README.md @@ -642,7 +642,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)) +- 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/03_04_subcommands_alt.rs b/examples/tutorial_derive/03_04_subcommands_alt.rs new file mode 100644 index 00000000000..0a5b60682d4 --- /dev/null +++ b/examples/tutorial_derive/03_04_subcommands_alt.rs @@ -0,0 +1,32 @@ +use clap::{Args, Parser, Subcommand}; + +#[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.name) + } + } +} diff --git a/examples/tutorial_derive/README.md b/examples/tutorial_derive/README.md index 662acc6cecf..dc242bfc2e5 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 @@ -610,7 +614,10 @@ 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)) +- 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