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: Builder 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 with several arguments using usage strings. 34 //! 35 //! ```rust 36 #![doc = include_str!("../examples/tutorial_builder/01_quick.rs")] 37 //! ``` 38 //! 39 #![doc = include_str!("../examples/tutorial_builder/01_quick.md")] 40 //! 41 //! ## Configuring the Parser 42 //! 43 //! You use [`Command`][crate::Command] to start building a parser. 44 //! 45 //! ```rust 46 #![doc = include_str!("../examples/tutorial_builder/02_apps.rs")] 47 //! ``` 48 //! 49 #![doc = include_str!("../examples/tutorial_builder/02_apps.md")] 50 //! 51 //! You can use [`command!()`][crate::command!] to fill these fields in from your `Cargo.toml` 52 //! file. **This requires the [`cargo` feature flag][crate::_features].** 53 //! 54 //! ```rust 55 #![doc = include_str!("../examples/tutorial_builder/02_crate.rs")] 56 //! ``` 57 #![doc = include_str!("../examples/tutorial_builder/02_crate.md")] 58 //! 59 //! You can use [`Command`][crate::Command] methods to change the application level behavior of 60 //! clap. 61 //! 62 //! ```rust 63 #![doc = include_str!("../examples/tutorial_builder/02_app_settings.rs")] 64 //! ``` 65 #![doc = include_str!("../examples/tutorial_builder/02_app_settings.md")] 66 //! 67 //! ## Adding Arguments 68 //! 69 //! ### Positionals 70 //! 71 //! You can have users specify values by their position on the command-line: 72 //! 73 //! ```rust 74 #![doc = include_str!("../examples/tutorial_builder/03_03_positional.rs")] 75 //! ``` 76 #![doc = include_str!("../examples/tutorial_builder/03_03_positional.md")] 77 //! 78 //! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set]. To 79 //! accept multiple values, use [`Append`][crate::ArgAction::Append]: 80 //! ```rust 81 #![doc = include_str!("../examples/tutorial_builder/03_03_positional_mult.rs")] 82 //! ``` 83 #![doc = include_str!("../examples/tutorial_builder/03_03_positional_mult.md")] 84 //! 85 //! ### Options 86 //! 87 //! You can name your arguments with a flag: 88 //! - Order doesn't matter 89 //! - They can be optional 90 //! - Intent is clearer 91 //! 92 //! ```rust 93 #![doc = include_str!("../examples/tutorial_builder/03_02_option.rs")] 94 //! ``` 95 #![doc = include_str!("../examples/tutorial_builder/03_02_option.md")] 96 //! 97 //! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set]. To 98 //! accept multiple occurrences, use [`Append`][crate::ArgAction::Append]: 99 //! ```rust 100 #![doc = include_str!("../examples/tutorial_builder/03_02_option_mult.rs")] 101 //! ``` 102 #![doc = include_str!("../examples/tutorial_builder/03_02_option_mult.md")] 103 //! 104 //! ### Flags 105 //! 106 //! Flags can also be switches that can be on/off: 107 //! 108 //! ```rust 109 #![doc = include_str!("../examples/tutorial_builder/03_01_flag_bool.rs")] 110 //! ``` 111 #![doc = include_str!("../examples/tutorial_builder/03_01_flag_bool.md")] 112 //! 113 //! To accept multiple flags, use [`Count`][crate::ArgAction::Count]: 114 //! 115 //! ```rust 116 #![doc = include_str!("../examples/tutorial_builder/03_01_flag_count.rs")] 117 //! ``` 118 #![doc = include_str!("../examples/tutorial_builder/03_01_flag_count.md")] 119 //! 120 //! ### Subcommands 121 //! 122 //! Subcommands are defined as [`Command`][crate::Command]s that get added via 123 //! [`Command::subcommand`][crate::Command::subcommand]. Each instance of a Subcommand can have its 124 //! own version, author(s), Args, and even its own subcommands. 125 //! 126 //! ```rust 127 #![doc = include_str!("../examples/tutorial_builder/03_04_subcommands.rs")] 128 //! ``` 129 #![doc = include_str!("../examples/tutorial_builder/03_04_subcommands.md")] 130 //! 131 //! ### Defaults 132 //! 133 //! We've previously showed that arguments can be [`required`][crate::Arg::required] or optional. 134 //! When optional, you work with a `Option` and can `unwrap_or`. Alternatively, you can set 135 //! [`Arg::default_value`][crate::Arg::default_value]. 136 //! 137 //! ```rust 138 #![doc = include_str!("../examples/tutorial_builder/03_05_default_values.rs")] 139 //! ``` 140 #![doc = include_str!("../examples/tutorial_builder/03_05_default_values.md")] 141 //! 142 //! ## Validation 143 //! 144 //! By default, arguments are assumed to be `String`s and only UTF-8 validation is performed. 145 //! 146 //! ### Enumerated values 147 //! 148 //! If you have arguments of specific values you want to test for, you can use the 149 //! [`PossibleValuesParser`][crate::builder::PossibleValuesParser] or [`Arg::value_parser(["val1", 150 //! ...])`][crate::Arg::value_parser] for short. 151 //! 152 //! This allows you specify the valid values for that argument. If the user does not use one of 153 //! those specific values, they will receive a graceful exit with error message informing them 154 //! of the mistake, and what the possible valid values are 155 //! 156 //! ```rust 157 #![doc = include_str!("../examples/tutorial_builder/04_01_possible.rs")] 158 //! ``` 159 #![doc = include_str!("../examples/tutorial_builder/04_01_possible.md")] 160 //! 161 //! When enabling the [`derive` feature][crate::_features], you can use 162 //! [`ValueEnum`][crate::ValueEnum] to take care of the boiler plate for you, giving the same 163 //! results. 164 //! 165 //! ```rust 166 #![doc = include_str!("../examples/tutorial_builder/04_01_enum.rs")] 167 //! ``` 168 #![doc = include_str!("../examples/tutorial_builder/04_01_enum.md")] 169 //! 170 //! ### Validated values 171 //! 172 //! More generally, you can validate and parse into any data type. 173 //! 174 //! ```rust 175 #![doc = include_str!("../examples/tutorial_builder/04_02_parse.rs")] 176 //! ``` 177 #![doc = include_str!("../examples/tutorial_builder/04_02_parse.md")] 178 //! 179 //! A custom parser can be used to improve the error messages or provide additional validation: 180 //! 181 //! ```rust 182 #![doc = include_str!("../examples/tutorial_builder/04_02_validate.rs")] 183 //! ``` 184 #![doc = include_str!("../examples/tutorial_builder/04_02_validate.md")] 185 //! 186 //! See [`Arg::value_parser`][crate::Arg::value_parser] for more details. 187 //! 188 //! ### Argument Relations 189 //! 190 //! You can declare dependencies or conflicts between [`Arg`][crate::Arg]s or even 191 //! [`ArgGroup`][crate::ArgGroup]s. 192 //! 193 //! [`ArgGroup`][crate::ArgGroup]s make it easier to declare relations instead of having to list 194 //! each individually, or when you want a rule to apply "any but not all" arguments. 195 //! 196 //! Perhaps the most common use of [`ArgGroup`][crate::ArgGroup]s is to require one and *only* one 197 //! argument to be present out of a given set. Imagine that you had multiple arguments, and you 198 //! want one of them to be required, but making all of them required isn't feasible because perhaps 199 //! they conflict with each other. 200 //! 201 //! ```rust 202 #![doc = include_str!("../examples/tutorial_builder/04_03_relations.rs")] 203 //! ``` 204 #![doc = include_str!("../examples/tutorial_builder/04_03_relations.md")] 205 //! 206 //! ### Custom Validation 207 //! 208 //! As a last resort, you can create custom errors with the basics of clap's formatting. 209 //! 210 //! ```rust 211 #![doc = include_str!("../examples/tutorial_builder/04_04_custom.rs")] 212 //! ``` 213 #![doc = include_str!("../examples/tutorial_builder/04_04_custom.md")] 214 //! 215 //! ## Testing 216 //! 217 //! clap reports most development errors as `debug_assert!`s. Rather than checking every 218 //! subcommand, you should have a test that calls 219 //! [`Command::debug_assert`][crate::Command::debug_assert]: 220 //! ```rust,no_run 221 #![doc = include_str!("../examples/tutorial_builder/05_01_assert.rs")] 222 //! ``` 223