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