1 // Contributing 2 // 3 // New example code: 4 // - Please update the corresponding section in the derive tutorial 5 // - Building: They must be added to `Cargo.toml` with the appropriate `required-features`. 6 // - Testing: Ensure there is a markdown file with [trycmd](https://docs.rs/trycmd) syntax 7 // 8 // See also the general CONTRIBUTING 9 10 //! # Documentation: Derive Tutorial 11 //! 12 //! 1. [Quick Start](#quick-start) 13 //! 2. [Configuring the Parser](#configuring-the-parser) 14 //! 3. [Adding Arguments](#adding-arguments) 15 //! 1. [Positionals](#positionals) 16 //! 2. [Options](#options) 17 //! 3. [Flags](#flags) 18 //! 4. [Subcommands](#subcommands) 19 //! 5. [Defaults](#defaults) 20 //! 4. Validation 21 //! 1. [Enumerated values](#enumerated-values) 22 //! 2. [Validated values](#validated-values) 23 //! 3. [Argument Relations](#argument-relations) 24 //! 4. [Custom Validation](#custom-validation) 25 //! 5. [Testing](#testing) 26 //! 27 //! See also 28 //! - [FAQ: When should I use the builder vs derive APIs?][crate::_faq#when-should-i-use-the-builder-vs-derive-apis] 29 //! - The [cookbook][crate::_cookbook] for more application-focused examples 30 //! 31 //! ## Quick Start 32 //! 33 //! You can create an application declaratively with a `struct` and some 34 //! attributes. **This requires enabling the [`derive` feature flag][crate::_features].** 35 //! 36 //! ```rust 37 #![doc = include_str!("../../examples/tutorial_derive/01_quick.rs")] 38 //! ``` 39 //! 40 #![doc = include_str!("../../examples/tutorial_derive/01_quick.md")] 41 //! 42 //! ## Configuring the Parser 43 //! 44 //! You use derive [`Parser`][crate::Parser] to start building a parser. 45 //! 46 //! ```rust 47 #![doc = include_str!("../../examples/tutorial_derive/02_apps.rs")] 48 //! ``` 49 //! 50 #![doc = include_str!("../../examples/tutorial_derive/02_apps.md")] 51 //! 52 //! You can use `#[clap(author, version, about)]` attribute defaults to fill these fields in from your `Cargo.toml` file. 53 //! 54 //! ```rust 55 #![doc = include_str!("../../examples/tutorial_derive/02_crate.rs")] 56 //! ``` 57 #![doc = include_str!("../../examples/tutorial_derive/02_crate.md")] 58 //! 59 //! You can use attributes to change the application level behavior of clap. Any [`Command`][crate::Command]] builder function can be used as an attribute. 60 //! 61 //! ```rust 62 #![doc = include_str!("../../examples/tutorial_derive/02_app_settings.rs")] 63 //! ``` 64 #![doc = include_str!("../../examples/tutorial_derive/02_app_settings.md")] 65 //! 66 //! ## Adding Arguments 67 //! 68 //! ### Positionals 69 //! 70 //! You can have users specify values by their position on the command-line: 71 //! 72 //! ```rust 73 #![doc = include_str!("../../examples/tutorial_derive/03_03_positional.rs")] 74 //! ``` 75 #![doc = include_str!("../../examples/tutorial_derive/03_03_positional.md")] 76 //! 77 //! ### Options 78 //! 79 //! You can name your arguments with a flag: 80 //! - Order doesn't matter 81 //! - They can be optional 82 //! - Intent is clearer 83 //! 84 //! The `#[clap(short = 'n')]` and `#[clap(long = "name")]` attributes that define 85 //! the flags are [`Arg`][crate::Args] methods that are derived from the field name when no value 86 //! is specified (`#[clap(short)]` and `#[clap(long)]`). 87 //! 88 //! ```rust 89 #![doc = include_str!("../../examples/tutorial_derive/03_02_option.rs")] 90 //! ``` 91 #![doc = include_str!("../../examples/tutorial_derive/03_02_option.md")] 92 //! 93 //! ### Flags 94 //! 95 //! Flags can also be switches that can be on/off. This is enabled via the 96 //! `#[clap(action = ArgAction::SetTrue)]` attribute though this is implied when the field is a 97 //! `bool`. 98 //! 99 //! ```rust 100 #![doc = include_str!("../../examples/tutorial_derive/03_01_flag_bool.rs")] 101 //! ``` 102 #![doc = include_str!("../../examples/tutorial_derive/03_01_flag_bool.md")] 103 //! 104 //! Or counted with `#[clap(action = clap::ArgAction::Count)]`: 105 //! 106 //! ```rust 107 #![doc = include_str!("../../examples/tutorial_derive/03_01_flag_count.rs")] 108 //! ``` 109 #![doc = include_str!("../../examples/tutorial_derive/03_01_flag_count.md")] 110 //! 111 //! ### Subcommands 112 //! 113 //! Subcommands are derived with `#[derive(Subcommand)]` and be added via `#[clap(subcommand)]` attribute. Each 114 //! instance of a [Subcommand][crate::Subcommand] can have its own version, author(s), Args, and even its own 115 //! subcommands. 116 //! 117 //! ```rust 118 #![doc = include_str!("../../examples/tutorial_derive/03_04_subcommands.rs")] 119 //! ``` 120 //! We used a struct-variant to define the `add` subcommand. 121 //! Alternatively, you can use a struct for your subcommand's arguments: 122 //! ```rust 123 #![doc = include_str!("../../examples/tutorial_derive/03_04_subcommands_alt.rs")] 124 //! ``` 125 //! 126 #![doc = include_str!("../../examples/tutorial_derive/03_04_subcommands.md")] 127 //! 128 //! ### Defaults 129 //! 130 //! We've previously showed that arguments can be [`required`][crate::Arg::required] or optional. 131 //! When optional, you work with a `Option` and can `unwrap_or`. Alternatively, you can 132 //! set `#[clap(default_value_t)]`. 133 //! 134 //! ```rust 135 #![doc = include_str!("../../examples/tutorial_derive/03_05_default_values.rs")] 136 //! ``` 137 #![doc = include_str!("../../examples/tutorial_derive/03_05_default_values.md")] 138 //! 139 //! ## Validation 140 //! 141 //! ### Enumerated values 142 //! 143 //! If you have arguments of specific values you want to test for, you can derive 144 //! [`ValueEnum`][crate::ValueEnum]. 145 //! 146 //! This allows you specify the valid values for that argument. If the user does not use one of 147 //! those specific values, they will receive a graceful exit with error message informing them 148 //! of the mistake, and what the possible valid values are 149 //! 150 //! ```rust 151 #![doc = include_str!("../../examples/tutorial_derive/04_01_enum.rs")] 152 //! ``` 153 #![doc = include_str!("../../examples/tutorial_derive/04_01_enum.md")] 154 //! 155 //! ### Validated values 156 //! 157 //! More generally, you can validate and parse into any data type. 158 //! 159 //! ```rust 160 #![doc = include_str!("../../examples/tutorial_derive/04_02_parse.rs")] 161 //! ``` 162 #![doc = include_str!("../../examples/tutorial_derive/04_02_parse.md")] 163 //! 164 //! A custom parser can be used to improve the error messages or provide additional validation: 165 //! 166 //! ```rust 167 #![doc = include_str!("../../examples/tutorial_derive/04_02_validate.rs")] 168 //! ``` 169 #![doc = include_str!("../../examples/tutorial_derive/04_02_validate.md")] 170 //! 171 //! ### Argument Relations 172 //! 173 //! You can declare dependencies or conflicts between [`Arg`][crate::Arg]s or even 174 //! [`ArgGroup`][crate::ArgGroup]s. 175 //! 176 //! [`ArgGroup`][crate::ArgGroup]s make it easier to declare relations instead of having to list 177 //! each individually, or when you want a rule to apply "any but not all" arguments. 178 //! 179 //! Perhaps the most common use of [`ArgGroup`][crate::ArgGroup]s is to require one and *only* one 180 //! argument to be present out of a given set. Imagine that you had multiple arguments, and you 181 //! want one of them to be required, but making all of them required isn't feasible because perhaps 182 //! they conflict with each other. 183 //! 184 //! ```rust 185 #![doc = include_str!("../../examples/tutorial_derive/04_03_relations.rs")] 186 //! ``` 187 #![doc = include_str!("../../examples/tutorial_derive/04_03_relations.md")] 188 //! 189 //! ### Custom Validation 190 //! 191 //! As a last resort, you can create custom errors with the basics of clap's formatting. 192 //! 193 //! ```rust 194 #![doc = include_str!("../../examples/tutorial_derive/04_04_custom.rs")] 195 //! ``` 196 #![doc = include_str!("../../examples/tutorial_derive/04_04_custom.md")] 197 //! 198 //! ## Testing 199 //! 200 //! clap reports most development errors as `debug_assert!`s. Rather than checking every 201 //! subcommand, you should have a test that calls 202 //! [`Command::debug_assert`][crate::App::debug_assert]: 203 //! ```rust,no_run 204 #![doc = include_str!("../../examples/tutorial_derive/05_01_assert.rs")] 205 //! ``` 206