1// Std
2#[cfg(feature = "env")]
3use std::env;
4#[cfg(feature = "env")]
5use std::ffi::OsString;
6use std::{
7 cmp::{Ord, Ordering},
8 fmt::{self, Display, Formatter},
9 str,
10};
11
12// Internal
13use super::{ArgFlags, ArgSettings};
14use crate::builder::ArgPredicate;
15use crate::builder::IntoResettable;
16use crate::builder::OsStr;
17use crate::builder::PossibleValue;
18use crate::builder::Str;
19use crate::builder::StyledStr;
20use crate::builder::Styles;
21use crate::builder::ValueRange;
22use crate::util::AnyValueId;
23use crate::ArgAction;
24use crate::Id;
25use crate::ValueHint;
26use crate::INTERNAL_ERROR_MSG;
27
28/// The abstract representation of a command line argument. Used to set all the options and
29/// relationships that define a valid argument for the program.
30///
31/// There are two methods for constructing [`Arg`]s, using the builder pattern and setting options
32/// manually, or using a usage string which is far less verbose but has fewer options. You can also
33/// use a combination of the two methods to achieve the best of both worlds.
34///
35/// - [Basic API][crate::Arg#basic-api]
36/// - [Value Handling][crate::Arg#value-handling]
37/// - [Help][crate::Arg#help-1]
38/// - [Advanced Argument Relations][crate::Arg#advanced-argument-relations]
39/// - [Reflection][crate::Arg#reflection]
40///
41/// # Examples
42///
43/// ```rust
44/// # use clap_builder as clap;
45/// # use clap::{Arg, arg, ArgAction};
46/// // Using the traditional builder pattern and setting each option manually
47/// let cfg = Arg::new("config")
48/// .short('c')
49/// .long("config")
50/// .action(ArgAction::Set)
51/// .value_name("FILE")
52/// .help("Provides a config file to myprog");
53/// // Using a usage string (setting a similar argument to the one above)
54/// let input = arg!(-i --input <FILE> "Provides an input file to the program");
55/// ```
56#[derive(Default, Clone)]
57pub struct Arg {
58 pub(crate) id: Id,
59 pub(crate) help: Option<StyledStr>,
60 pub(crate) long_help: Option<StyledStr>,
61 pub(crate) action: Option<ArgAction>,
62 pub(crate) value_parser: Option<super::ValueParser>,
63 pub(crate) blacklist: Vec<Id>,
64 pub(crate) settings: ArgFlags,
65 pub(crate) overrides: Vec<Id>,
66 pub(crate) groups: Vec<Id>,
67 pub(crate) requires: Vec<(ArgPredicate, Id)>,
68 pub(crate) r_ifs: Vec<(Id, OsStr)>,
69 pub(crate) r_ifs_all: Vec<(Id, OsStr)>,
70 pub(crate) r_unless: Vec<Id>,
71 pub(crate) r_unless_all: Vec<Id>,
72 pub(crate) short: Option<char>,
73 pub(crate) long: Option<Str>,
74 pub(crate) aliases: Vec<(Str, bool)>, // (name, visible)
75 pub(crate) short_aliases: Vec<(char, bool)>, // (name, visible)
76 pub(crate) disp_ord: Option<usize>,
77 pub(crate) val_names: Vec<Str>,
78 pub(crate) num_vals: Option<ValueRange>,
79 pub(crate) val_delim: Option<char>,
80 pub(crate) default_vals: Vec<OsStr>,
81 pub(crate) default_vals_ifs: Vec<(Id, ArgPredicate, Option<OsStr>)>,
82 pub(crate) default_missing_vals: Vec<OsStr>,
83 #[cfg(feature = "env")]
84 pub(crate) env: Option<(OsStr, Option<OsString>)>,
85 pub(crate) terminator: Option<Str>,
86 pub(crate) index: Option<usize>,
87 pub(crate) help_heading: Option<Option<Str>>,
88 pub(crate) value_hint: Option<ValueHint>,
89}
90
91/// # Basic API
92impl Arg {
93 /// Create a new [`Arg`] with a unique name.
94 ///
95 /// The name is used to check whether or not the argument was used at
96 /// runtime, get values, set relationships with other args, etc..
97 ///
98 /// **NOTE:** In the case of arguments that take values (i.e. [`Arg::action(ArgAction::Set)`])
99 /// and positional arguments (i.e. those without a preceding `-` or `--`) the name will also
100 /// be displayed when the user prints the usage/help information of the program.
101 ///
102 /// # Examples
103 ///
104 /// ```rust
105 /// # use clap_builder as clap;
106 /// # use clap::{Command, Arg};
107 /// Arg::new("config")
108 /// # ;
109 /// ```
110 /// [`Arg::action(ArgAction::Set)`]: Arg::action()
111 pub fn new(id: impl Into<Id>) -> Self {
112 Arg::default().id(id)
113 }
114
115 /// Set the identifier used for referencing this argument in the clap API.
116 ///
117 /// See [`Arg::new`] for more details.
118 #[must_use]
119 pub fn id(mut self, id: impl Into<Id>) -> Self {
120 self.id = id.into();
121 self
122 }
123
124 /// Sets the short version of the argument without the preceding `-`.
125 ///
126 /// By default `V` and `h` are used by the auto-generated `version` and `help` arguments,
127 /// respectively. You will need to disable the auto-generated flags
128 /// ([`disable_help_flag`][crate::Command::disable_help_flag],
129 /// [`disable_version_flag`][crate::Command::disable_version_flag]) and define your own.
130 ///
131 /// # Examples
132 ///
133 /// When calling `short`, use a single valid UTF-8 character which will allow using the
134 /// argument via a single hyphen (`-`) such as `-c`:
135 ///
136 /// ```rust
137 /// # use clap_builder as clap;
138 /// # use clap::{Command, Arg, ArgAction};
139 /// let m = Command::new("prog")
140 /// .arg(Arg::new("config")
141 /// .short('c')
142 /// .action(ArgAction::Set))
143 /// .get_matches_from(vec![
144 /// "prog", "-c", "file.toml"
145 /// ]);
146 ///
147 /// assert_eq!(m.get_one::<String>("config").map(String::as_str), Some("file.toml"));
148 /// ```
149 ///
150 /// To use `-h` for your own flag and still have help:
151 /// ```rust
152 /// # use clap_builder as clap;
153 /// # use clap::{Command, Arg, ArgAction};
154 /// let m = Command::new("prog")
155 /// .disable_help_flag(true)
156 /// .arg(Arg::new("host")
157 /// .short('h')
158 /// .long("host"))
159 /// .arg(Arg::new("help")
160 /// .long("help")
161 /// .global(true)
162 /// .action(ArgAction::Help))
163 /// .get_matches_from(vec![
164 /// "prog", "-h", "wikipedia.org"
165 /// ]);
166 ///
167 /// assert_eq!(m.get_one::<String>("host").map(String::as_str), Some("wikipedia.org"));
168 /// ```
169 #[inline]
170 #[must_use]
171 pub fn short(mut self, s: impl IntoResettable<char>) -> Self {
172 if let Some(s) = s.into_resettable().into_option() {
173 debug_assert!(s != '-', "short option name cannot be `-`");
174 self.short = Some(s);
175 } else {
176 self.short = None;
177 }
178 self
179 }
180
181 /// Sets the long version of the argument without the preceding `--`.
182 ///
183 /// By default `version` and `help` are used by the auto-generated `version` and `help`
184 /// arguments, respectively. You may use the word `version` or `help` for the long form of your
185 /// own arguments, in which case `clap` simply will not assign those to the auto-generated
186 /// `version` or `help` arguments.
187 ///
188 /// **NOTE:** Any leading `-` characters will be stripped
189 ///
190 /// # Examples
191 ///
192 /// To set `long` use a word containing valid UTF-8. If you supply a double leading
193 /// `--` such as `--config` they will be stripped. Hyphens in the middle of the word, however,
194 /// will *not* be stripped (i.e. `config-file` is allowed).
195 ///
196 /// Setting `long` allows using the argument via a double hyphen (`--`) such as `--config`
197 ///
198 /// ```rust
199 /// # use clap_builder as clap;
200 /// # use clap::{Command, Arg, ArgAction};
201 /// let m = Command::new("prog")
202 /// .arg(Arg::new("cfg")
203 /// .long("config")
204 /// .action(ArgAction::Set))
205 /// .get_matches_from(vec![
206 /// "prog", "--config", "file.toml"
207 /// ]);
208 ///
209 /// assert_eq!(m.get_one::<String>("cfg").map(String::as_str), Some("file.toml"));
210 /// ```
211 #[inline]
212 #[must_use]
213 pub fn long(mut self, l: impl IntoResettable<Str>) -> Self {
214 self.long = l.into_resettable().into_option();
215 self
216 }
217
218 /// Add an alias, which functions as a hidden long flag.
219 ///
220 /// This is more efficient, and easier than creating multiple hidden arguments as one only
221 /// needs to check for the existence of this command, and not all variants.
222 ///
223 /// # Examples
224 ///
225 /// ```rust
226 /// # use clap_builder as clap;
227 /// # use clap::{Command, Arg, ArgAction};
228 /// let m = Command::new("prog")
229 /// .arg(Arg::new("test")
230 /// .long("test")
231 /// .alias("alias")
232 /// .action(ArgAction::Set))
233 /// .get_matches_from(vec![
234 /// "prog", "--alias", "cool"
235 /// ]);
236 /// assert_eq!(m.get_one::<String>("test").unwrap(), "cool");
237 /// ```
238 #[must_use]
239 pub fn alias(mut self, name: impl IntoResettable<Str>) -> Self {
240 if let Some(name) = name.into_resettable().into_option() {
241 self.aliases.push((name, false));
242 } else {
243 self.aliases.clear();
244 }
245 self
246 }
247
248 /// Add an alias, which functions as a hidden short flag.
249 ///
250 /// This is more efficient, and easier than creating multiple hidden arguments as one only
251 /// needs to check for the existence of this command, and not all variants.
252 ///
253 /// # Examples
254 ///
255 /// ```rust
256 /// # use clap_builder as clap;
257 /// # use clap::{Command, Arg, ArgAction};
258 /// let m = Command::new("prog")
259 /// .arg(Arg::new("test")
260 /// .short('t')
261 /// .short_alias('e')
262 /// .action(ArgAction::Set))
263 /// .get_matches_from(vec![
264 /// "prog", "-e", "cool"
265 /// ]);
266 /// assert_eq!(m.get_one::<String>("test").unwrap(), "cool");
267 /// ```
268 #[must_use]
269 pub fn short_alias(mut self, name: impl IntoResettable<char>) -> Self {
270 if let Some(name) = name.into_resettable().into_option() {
271 debug_assert!(name != '-', "short alias name cannot be `-`");
272 self.short_aliases.push((name, false));
273 } else {
274 self.short_aliases.clear();
275 }
276 self
277 }
278
279 /// Add aliases, which function as hidden long flags.
280 ///
281 /// This is more efficient, and easier than creating multiple hidden subcommands as one only
282 /// needs to check for the existence of this command, and not all variants.
283 ///
284 /// # Examples
285 ///
286 /// ```rust
287 /// # use clap_builder as clap;
288 /// # use clap::{Command, Arg, ArgAction};
289 /// let m = Command::new("prog")
290 /// .arg(Arg::new("test")
291 /// .long("test")
292 /// .aliases(["do-stuff", "do-tests", "tests"])
293 /// .action(ArgAction::SetTrue)
294 /// .help("the file to add")
295 /// .required(false))
296 /// .get_matches_from(vec![
297 /// "prog", "--do-tests"
298 /// ]);
299 /// assert_eq!(m.get_flag("test"), true);
300 /// ```
301 #[must_use]
302 pub fn aliases(mut self, names: impl IntoIterator<Item = impl Into<Str>>) -> Self {
303 self.aliases
304 .extend(names.into_iter().map(|x| (x.into(), false)));
305 self
306 }
307
308 /// Add aliases, which functions as a hidden short flag.
309 ///
310 /// This is more efficient, and easier than creating multiple hidden subcommands as one only
311 /// needs to check for the existence of this command, and not all variants.
312 ///
313 /// # Examples
314 ///
315 /// ```rust
316 /// # use clap_builder as clap;
317 /// # use clap::{Command, Arg, ArgAction};
318 /// let m = Command::new("prog")
319 /// .arg(Arg::new("test")
320 /// .short('t')
321 /// .short_aliases(['e', 's'])
322 /// .action(ArgAction::SetTrue)
323 /// .help("the file to add")
324 /// .required(false))
325 /// .get_matches_from(vec![
326 /// "prog", "-s"
327 /// ]);
328 /// assert_eq!(m.get_flag("test"), true);
329 /// ```
330 #[must_use]
331 pub fn short_aliases(mut self, names: impl IntoIterator<Item = char>) -> Self {
332 for s in names {
333 debug_assert!(s != '-', "short alias name cannot be `-`");
334 self.short_aliases.push((s, false));
335 }
336 self
337 }
338
339 /// Add an alias, which functions as a visible long flag.
340 ///
341 /// Like [`Arg::alias`], except that they are visible inside the help message.
342 ///
343 /// # Examples
344 ///
345 /// ```rust
346 /// # use clap_builder as clap;
347 /// # use clap::{Command, Arg, ArgAction};
348 /// let m = Command::new("prog")
349 /// .arg(Arg::new("test")
350 /// .visible_alias("something-awesome")
351 /// .long("test")
352 /// .action(ArgAction::Set))
353 /// .get_matches_from(vec![
354 /// "prog", "--something-awesome", "coffee"
355 /// ]);
356 /// assert_eq!(m.get_one::<String>("test").unwrap(), "coffee");
357 /// ```
358 /// [`Command::alias`]: Arg::alias()
359 #[must_use]
360 pub fn visible_alias(mut self, name: impl IntoResettable<Str>) -> Self {
361 if let Some(name) = name.into_resettable().into_option() {
362 self.aliases.push((name, true));
363 } else {
364 self.aliases.clear();
365 }
366 self
367 }
368
369 /// Add an alias, which functions as a visible short flag.
370 ///
371 /// Like [`Arg::short_alias`], except that they are visible inside the help message.
372 ///
373 /// # Examples
374 ///
375 /// ```rust
376 /// # use clap_builder as clap;
377 /// # use clap::{Command, Arg, ArgAction};
378 /// let m = Command::new("prog")
379 /// .arg(Arg::new("test")
380 /// .long("test")
381 /// .visible_short_alias('t')
382 /// .action(ArgAction::Set))
383 /// .get_matches_from(vec![
384 /// "prog", "-t", "coffee"
385 /// ]);
386 /// assert_eq!(m.get_one::<String>("test").unwrap(), "coffee");
387 /// ```
388 #[must_use]
389 pub fn visible_short_alias(mut self, name: impl IntoResettable<char>) -> Self {
390 if let Some(name) = name.into_resettable().into_option() {
391 debug_assert!(name != '-', "short alias name cannot be `-`");
392 self.short_aliases.push((name, true));
393 } else {
394 self.short_aliases.clear();
395 }
396 self
397 }
398
399 /// Add aliases, which function as visible long flags.
400 ///
401 /// Like [`Arg::aliases`], except that they are visible inside the help message.
402 ///
403 /// # Examples
404 ///
405 /// ```rust
406 /// # use clap_builder as clap;
407 /// # use clap::{Command, Arg, ArgAction};
408 /// let m = Command::new("prog")
409 /// .arg(Arg::new("test")
410 /// .long("test")
411 /// .action(ArgAction::SetTrue)
412 /// .visible_aliases(["something", "awesome", "cool"]))
413 /// .get_matches_from(vec![
414 /// "prog", "--awesome"
415 /// ]);
416 /// assert_eq!(m.get_flag("test"), true);
417 /// ```
418 /// [`Command::aliases`]: Arg::aliases()
419 #[must_use]
420 pub fn visible_aliases(mut self, names: impl IntoIterator<Item = impl Into<Str>>) -> Self {
421 self.aliases
422 .extend(names.into_iter().map(|n| (n.into(), true)));
423 self
424 }
425
426 /// Add aliases, which function as visible short flags.
427 ///
428 /// Like [`Arg::short_aliases`], except that they are visible inside the help message.
429 ///
430 /// # Examples
431 ///
432 /// ```rust
433 /// # use clap_builder as clap;
434 /// # use clap::{Command, Arg, ArgAction};
435 /// let m = Command::new("prog")
436 /// .arg(Arg::new("test")
437 /// .long("test")
438 /// .action(ArgAction::SetTrue)
439 /// .visible_short_aliases(['t', 'e']))
440 /// .get_matches_from(vec![
441 /// "prog", "-t"
442 /// ]);
443 /// assert_eq!(m.get_flag("test"), true);
444 /// ```
445 #[must_use]
446 pub fn visible_short_aliases(mut self, names: impl IntoIterator<Item = char>) -> Self {
447 for n in names {
448 debug_assert!(n != '-', "short alias name cannot be `-`");
449 self.short_aliases.push((n, true));
450 }
451 self
452 }
453
454 /// Specifies the index of a positional argument **starting at** 1.
455 ///
456 /// **NOTE:** The index refers to position according to **other positional argument**. It does
457 /// not define position in the argument list as a whole.
458 ///
459 /// **NOTE:** You can optionally leave off the `index` method, and the index will be
460 /// assigned in order of evaluation. Utilizing the `index` method allows for setting
461 /// indexes out of order
462 ///
463 /// **NOTE:** This is only meant to be used for positional arguments and shouldn't to be used
464 /// with [`Arg::short`] or [`Arg::long`].
465 ///
466 /// **NOTE:** When utilized with [`Arg::num_args(1..)`], only the **last** positional argument
467 /// may be defined as having a variable number of arguments (i.e. with the highest index)
468 ///
469 /// # Panics
470 ///
471 /// [`Command`] will [`panic!`] if indexes are skipped (such as defining `index(1)` and `index(3)`
472 /// but not `index(2)`, or a positional argument is defined as multiple and is not the highest
473 /// index (debug builds)
474 ///
475 /// # Examples
476 ///
477 /// ```rust
478 /// # use clap_builder as clap;
479 /// # use clap::{Command, Arg};
480 /// Arg::new("config")
481 /// .index(1)
482 /// # ;
483 /// ```
484 ///
485 /// ```rust
486 /// # use clap_builder as clap;
487 /// # use clap::{Command, Arg, ArgAction};
488 /// let m = Command::new("prog")
489 /// .arg(Arg::new("mode")
490 /// .index(1))
491 /// .arg(Arg::new("debug")
492 /// .long("debug")
493 /// .action(ArgAction::SetTrue))
494 /// .get_matches_from(vec![
495 /// "prog", "--debug", "fast"
496 /// ]);
497 ///
498 /// assert!(m.contains_id("mode"));
499 /// assert_eq!(m.get_one::<String>("mode").unwrap(), "fast"); // notice index(1) means "first positional"
500 /// // *not* first argument
501 /// ```
502 /// [`Arg::short`]: Arg::short()
503 /// [`Arg::long`]: Arg::long()
504 /// [`Arg::num_args(true)`]: Arg::num_args()
505 /// [`Command`]: crate::Command
506 #[inline]
507 #[must_use]
508 pub fn index(mut self, idx: impl IntoResettable<usize>) -> Self {
509 self.index = idx.into_resettable().into_option();
510 self
511 }
512
513 /// This is a "VarArg" and everything that follows should be captured by it, as if the user had
514 /// used a `--`.
515 ///
516 /// **NOTE:** To start the trailing "VarArg" on unknown flags (and not just a positional
517 /// value), set [`allow_hyphen_values`][Arg::allow_hyphen_values]. Either way, users still
518 /// have the option to explicitly escape ambiguous arguments with `--`.
519 ///
520 /// **NOTE:** [`Arg::value_delimiter`] still applies if set.
521 ///
522 /// **NOTE:** Setting this requires [`Arg::num_args(..)`].
523 ///
524 /// # Examples
525 ///
526 /// ```rust
527 /// # use clap_builder as clap;
528 /// # use clap::{Command, arg};
529 /// let m = Command::new("myprog")
530 /// .arg(arg!(<cmd> ... "commands to run").trailing_var_arg(true))
531 /// .get_matches_from(vec!["myprog", "arg1", "-r", "val1"]);
532 ///
533 /// let trail: Vec<_> = m.get_many::<String>("cmd").unwrap().collect();
534 /// assert_eq!(trail, ["arg1", "-r", "val1"]);
535 /// ```
536 /// [`Arg::num_args(..)`]: crate::Arg::num_args()
537 pub fn trailing_var_arg(self, yes: bool) -> Self {
538 if yes {
539 self.setting(ArgSettings::TrailingVarArg)
540 } else {
541 self.unset_setting(ArgSettings::TrailingVarArg)
542 }
543 }
544
545 /// This arg is the last, or final, positional argument (i.e. has the highest
546 /// index) and is *only* able to be accessed via the `--` syntax (i.e. `$ prog args --
547 /// last_arg`).
548 ///
549 /// Even, if no other arguments are left to parse, if the user omits the `--` syntax
550 /// they will receive an [`UnknownArgument`] error. Setting an argument to `.last(true)` also
551 /// allows one to access this arg early using the `--` syntax. Accessing an arg early, even with
552 /// the `--` syntax is otherwise not possible.
553 ///
554 /// **NOTE:** This will change the usage string to look like `$ prog [OPTIONS] [-- <ARG>]` if
555 /// `ARG` is marked as `.last(true)`.
556 ///
557 /// **NOTE:** This setting will imply [`crate::Command::dont_collapse_args_in_usage`] because failing
558 /// to set this can make the usage string very confusing.
559 ///
560 /// **NOTE**: This setting only applies to positional arguments, and has no effect on OPTIONS
561 ///
562 /// **NOTE:** Setting this requires [taking values][Arg::num_args]
563 ///
564 /// **CAUTION:** Using this setting *and* having child subcommands is not
565 /// recommended with the exception of *also* using
566 /// [`crate::Command::args_conflicts_with_subcommands`]
567 /// (or [`crate::Command::subcommand_negates_reqs`] if the argument marked `Last` is also
568 /// marked [`Arg::required`])
569 ///
570 /// # Examples
571 ///
572 /// ```rust
573 /// # use clap_builder as clap;
574 /// # use clap::{Arg, ArgAction};
575 /// Arg::new("args")
576 /// .action(ArgAction::Set)
577 /// .last(true)
578 /// # ;
579 /// ```
580 ///
581 /// Setting `last` ensures the arg has the highest [index] of all positional args
582 /// and requires that the `--` syntax be used to access it early.
583 ///
584 /// ```rust
585 /// # use clap_builder as clap;
586 /// # use clap::{Command, Arg, ArgAction};
587 /// let res = Command::new("prog")
588 /// .arg(Arg::new("first"))
589 /// .arg(Arg::new("second"))
590 /// .arg(Arg::new("third")
591 /// .action(ArgAction::Set)
592 /// .last(true))
593 /// .try_get_matches_from(vec![
594 /// "prog", "one", "--", "three"
595 /// ]);
596 ///
597 /// assert!(res.is_ok());
598 /// let m = res.unwrap();
599 /// assert_eq!(m.get_one::<String>("third").unwrap(), "three");
600 /// assert_eq!(m.get_one::<String>("second"), None);
601 /// ```
602 ///
603 /// Even if the positional argument marked `Last` is the only argument left to parse,
604 /// failing to use the `--` syntax results in an error.
605 ///
606 /// ```rust
607 /// # use clap_builder as clap;
608 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction};
609 /// let res = Command::new("prog")
610 /// .arg(Arg::new("first"))
611 /// .arg(Arg::new("second"))
612 /// .arg(Arg::new("third")
613 /// .action(ArgAction::Set)
614 /// .last(true))
615 /// .try_get_matches_from(vec![
616 /// "prog", "one", "two", "three"
617 /// ]);
618 ///
619 /// assert!(res.is_err());
620 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::UnknownArgument);
621 /// ```
622 /// [index]: Arg::index()
623 /// [`UnknownArgument`]: crate::error::ErrorKind::UnknownArgument
624 #[inline]
625 #[must_use]
626 pub fn last(self, yes: bool) -> Self {
627 if yes {
628 self.setting(ArgSettings::Last)
629 } else {
630 self.unset_setting(ArgSettings::Last)
631 }
632 }
633
634 /// Specifies that the argument must be present.
635 ///
636 /// Required by default means it is required, when no other conflicting rules or overrides have
637 /// been evaluated. Conflicting rules take precedence over being required.
638 ///
639 /// **Pro tip:** Flags (i.e. not positional, or arguments that take values) shouldn't be
640 /// required by default. This is because if a flag were to be required, it should simply be
641 /// implied. No additional information is required from user. Flags by their very nature are
642 /// simply boolean on/off switches. The only time a user *should* be required to use a flag
643 /// is if the operation is destructive in nature, and the user is essentially proving to you,
644 /// "Yes, I know what I'm doing."
645 ///
646 /// # Examples
647 ///
648 /// ```rust
649 /// # use clap_builder as clap;
650 /// # use clap::Arg;
651 /// Arg::new("config")
652 /// .required(true)
653 /// # ;
654 /// ```
655 ///
656 /// Setting required requires that the argument be used at runtime.
657 ///
658 /// ```rust
659 /// # use clap_builder as clap;
660 /// # use clap::{Command, Arg, ArgAction};
661 /// let res = Command::new("prog")
662 /// .arg(Arg::new("cfg")
663 /// .required(true)
664 /// .action(ArgAction::Set)
665 /// .long("config"))
666 /// .try_get_matches_from(vec![
667 /// "prog", "--config", "file.conf",
668 /// ]);
669 ///
670 /// assert!(res.is_ok());
671 /// ```
672 ///
673 /// Setting required and then *not* supplying that argument at runtime is an error.
674 ///
675 /// ```rust
676 /// # use clap_builder as clap;
677 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction};
678 /// let res = Command::new("prog")
679 /// .arg(Arg::new("cfg")
680 /// .required(true)
681 /// .action(ArgAction::Set)
682 /// .long("config"))
683 /// .try_get_matches_from(vec![
684 /// "prog"
685 /// ]);
686 ///
687 /// assert!(res.is_err());
688 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
689 /// ```
690 #[inline]
691 #[must_use]
692 pub fn required(self, yes: bool) -> Self {
693 if yes {
694 self.setting(ArgSettings::Required)
695 } else {
696 self.unset_setting(ArgSettings::Required)
697 }
698 }
699
700 /// Sets an argument that is required when this one is present
701 ///
702 /// i.e. when using this argument, the following argument *must* be present.
703 ///
704 /// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required
705 ///
706 /// # Examples
707 ///
708 /// ```rust
709 /// # use clap_builder as clap;
710 /// # use clap::Arg;
711 /// Arg::new("config")
712 /// .requires("input")
713 /// # ;
714 /// ```
715 ///
716 /// Setting [`Arg::requires(name)`] requires that the argument be used at runtime if the
717 /// defining argument is used. If the defining argument isn't used, the other argument isn't
718 /// required
719 ///
720 /// ```rust
721 /// # use clap_builder as clap;
722 /// # use clap::{Command, Arg, ArgAction};
723 /// let res = Command::new("prog")
724 /// .arg(Arg::new("cfg")
725 /// .action(ArgAction::Set)
726 /// .requires("input")
727 /// .long("config"))
728 /// .arg(Arg::new("input"))
729 /// .try_get_matches_from(vec![
730 /// "prog"
731 /// ]);
732 ///
733 /// assert!(res.is_ok()); // We didn't use cfg, so input wasn't required
734 /// ```
735 ///
736 /// Setting [`Arg::requires(name)`] and *not* supplying that argument is an error.
737 ///
738 /// ```rust
739 /// # use clap_builder as clap;
740 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction};
741 /// let res = Command::new("prog")
742 /// .arg(Arg::new("cfg")
743 /// .action(ArgAction::Set)
744 /// .requires("input")
745 /// .long("config"))
746 /// .arg(Arg::new("input"))
747 /// .try_get_matches_from(vec![
748 /// "prog", "--config", "file.conf"
749 /// ]);
750 ///
751 /// assert!(res.is_err());
752 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
753 /// ```
754 /// [`Arg::requires(name)`]: Arg::requires()
755 /// [Conflicting]: Arg::conflicts_with()
756 /// [override]: Arg::overrides_with()
757 #[must_use]
758 pub fn requires(mut self, arg_id: impl IntoResettable<Id>) -> Self {
759 if let Some(arg_id) = arg_id.into_resettable().into_option() {
760 self.requires.push((ArgPredicate::IsPresent, arg_id));
761 } else {
762 self.requires.clear();
763 }
764 self
765 }
766
767 /// This argument must be passed alone; it conflicts with all other arguments.
768 ///
769 /// # Examples
770 ///
771 /// ```rust
772 /// # use clap_builder as clap;
773 /// # use clap::Arg;
774 /// Arg::new("config")
775 /// .exclusive(true)
776 /// # ;
777 /// ```
778 ///
779 /// Setting an exclusive argument and having any other arguments present at runtime
780 /// is an error.
781 ///
782 /// ```rust
783 /// # use clap_builder as clap;
784 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction};
785 /// let res = Command::new("prog")
786 /// .arg(Arg::new("exclusive")
787 /// .action(ArgAction::Set)
788 /// .exclusive(true)
789 /// .long("exclusive"))
790 /// .arg(Arg::new("debug")
791 /// .long("debug"))
792 /// .arg(Arg::new("input"))
793 /// .try_get_matches_from(vec![
794 /// "prog", "--exclusive", "file.conf", "file.txt"
795 /// ]);
796 ///
797 /// assert!(res.is_err());
798 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::ArgumentConflict);
799 /// ```
800 #[inline]
801 #[must_use]
802 pub fn exclusive(self, yes: bool) -> Self {
803 if yes {
804 self.setting(ArgSettings::Exclusive)
805 } else {
806 self.unset_setting(ArgSettings::Exclusive)
807 }
808 }
809
810 /// Specifies that an argument can be matched to all child [`Subcommand`]s.
811 ///
812 /// **NOTE:** Global arguments *only* propagate down, **not** up (to parent commands), however
813 /// their values once a user uses them will be propagated back up to parents. In effect, this
814 /// means one should *define* all global arguments at the top level, however it doesn't matter
815 /// where the user *uses* the global argument.
816 ///
817 /// # Examples
818 ///
819 /// Assume an application with two subcommands, and you'd like to define a
820 /// `--verbose` flag that can be called on any of the subcommands and parent, but you don't
821 /// want to clutter the source with three duplicate [`Arg`] definitions.
822 ///
823 /// ```rust
824 /// # use clap_builder as clap;
825 /// # use clap::{Command, Arg, ArgAction};
826 /// let m = Command::new("prog")
827 /// .arg(Arg::new("verb")
828 /// .long("verbose")
829 /// .short('v')
830 /// .action(ArgAction::SetTrue)
831 /// .global(true))
832 /// .subcommand(Command::new("test"))
833 /// .subcommand(Command::new("do-stuff"))
834 /// .get_matches_from(vec![
835 /// "prog", "do-stuff", "--verbose"
836 /// ]);
837 ///
838 /// assert_eq!(m.subcommand_name(), Some("do-stuff"));
839 /// let sub_m = m.subcommand_matches("do-stuff").unwrap();
840 /// assert_eq!(sub_m.get_flag("verb"), true);
841 /// ```
842 ///
843 /// [`Subcommand`]: crate::Subcommand
844 #[inline]
845 #[must_use]
846 pub fn global(self, yes: bool) -> Self {
847 if yes {
848 self.setting(ArgSettings::Global)
849 } else {
850 self.unset_setting(ArgSettings::Global)
851 }
852 }
853
854 #[inline]
855 pub(crate) fn is_set(&self, s: ArgSettings) -> bool {
856 self.settings.is_set(s)
857 }
858
859 #[inline]
860 #[must_use]
861 pub(crate) fn setting(mut self, setting: ArgSettings) -> Self {
862 self.settings.set(setting);
863 self
864 }
865
866 #[inline]
867 #[must_use]
868 pub(crate) fn unset_setting(mut self, setting: ArgSettings) -> Self {
869 self.settings.unset(setting);
870 self
871 }
872}
873
874/// # Value Handling
875impl Arg {
876 /// Specify how to react to an argument when parsing it.
877 ///
878 /// [ArgAction] controls things like
879 /// - Overwriting previous values with new ones
880 /// - Appending new values to all previous ones
881 /// - Counting how many times a flag occurs
882 ///
883 /// The default action is `ArgAction::Set`
884 ///
885 /// # Examples
886 ///
887 /// ```rust
888 /// # use clap_builder as clap;
889 /// # use clap::Command;
890 /// # use clap::Arg;
891 /// let cmd = Command::new("mycmd")
892 /// .arg(
893 /// Arg::new("flag")
894 /// .long("flag")
895 /// .action(clap::ArgAction::Append)
896 /// );
897 ///
898 /// let matches = cmd.try_get_matches_from(["mycmd", "--flag", "value"]).unwrap();
899 /// assert!(matches.contains_id("flag"));
900 /// assert_eq!(
901 /// matches.get_many::<String>("flag").unwrap_or_default().map(|v| v.as_str()).collect::<Vec<_>>(),
902 /// vec!["value"]
903 /// );
904 /// ```
905 #[inline]
906 #[must_use]
907 pub fn action(mut self, action: impl IntoResettable<ArgAction>) -> Self {
908 self.action = action.into_resettable().into_option();
909 self
910 }
911
912 /// Specify the typed behavior of the argument.
913 ///
914 /// This allows parsing and validating a value before storing it into
915 /// [`ArgMatches`][crate::ArgMatches] as the given type.
916 ///
917 /// Possible value parsers include:
918 /// - [`value_parser!(T)`][crate::value_parser!] for auto-selecting a value parser for a given type
919 /// - Or [range expressions like `0..=1`][std::ops::RangeBounds] as a shorthand for [`RangedI64ValueParser`][crate::builder::RangedI64ValueParser]
920 /// - `Fn(&str) -> Result<T, E>`
921 /// - `[&str]` and [`PossibleValuesParser`][crate::builder::PossibleValuesParser] for static enumerated values
922 /// - [`BoolishValueParser`][crate::builder::BoolishValueParser], and [`FalseyValueParser`][crate::builder::FalseyValueParser] for alternative `bool` implementations
923 /// - [`NonEmptyStringValueParser`][crate::builder::NonEmptyStringValueParser] for basic validation for strings
924 /// - or any other [`TypedValueParser`][crate::builder::TypedValueParser] implementation
925 ///
926 /// The default value is [`ValueParser::string`][crate::builder::ValueParser::string].
927 ///
928 /// ```rust
929 /// # use clap_builder as clap;
930 /// # use clap::ArgAction;
931 /// let mut cmd = clap::Command::new("raw")
932 /// .arg(
933 /// clap::Arg::new("color")
934 /// .long("color")
935 /// .value_parser(["always", "auto", "never"])
936 /// .default_value("auto")
937 /// )
938 /// .arg(
939 /// clap::Arg::new("hostname")
940 /// .long("hostname")
941 /// .value_parser(clap::builder::NonEmptyStringValueParser::new())
942 /// .action(ArgAction::Set)
943 /// .required(true)
944 /// )
945 /// .arg(
946 /// clap::Arg::new("port")
947 /// .long("port")
948 /// .value_parser(clap::value_parser!(u16).range(3000..))
949 /// .action(ArgAction::Set)
950 /// .required(true)
951 /// );
952 ///
953 /// let m = cmd.try_get_matches_from_mut(
954 /// ["cmd", "--hostname", "rust-lang.org", "--port", "3001"]
955 /// ).unwrap();
956 ///
957 /// let color: &String = m.get_one("color")
958 /// .expect("default");
959 /// assert_eq!(color, "auto");
960 ///
961 /// let hostname: &String = m.get_one("hostname")
962 /// .expect("required");
963 /// assert_eq!(hostname, "rust-lang.org");
964 ///
965 /// let port: u16 = *m.get_one("port")
966 /// .expect("required");
967 /// assert_eq!(port, 3001);
968 /// ```
969 pub fn value_parser(mut self, parser: impl IntoResettable<super::ValueParser>) -> Self {
970 self.value_parser = parser.into_resettable().into_option();
971 self
972 }
973
974 /// Specifies the number of arguments parsed per occurrence
975 ///
976 /// For example, if you had a `-f <file>` argument where you wanted exactly 3 'files' you would
977 /// set `.num_args(3)`, and this argument wouldn't be satisfied unless the user
978 /// provided 3 and only 3 values.
979 ///
980 /// Users may specify values for arguments in any of the following methods
981 ///
982 /// - Using a space such as `-o value` or `--option value`
983 /// - Using an equals and no space such as `-o=value` or `--option=value`
984 /// - Use a short and no space such as `-ovalue`
985 ///
986 /// **WARNING:**
987 ///
988 /// Setting a variable number of values (e.g. `1..=10`) for an argument without
989 /// other details can be dangerous in some circumstances. Because multiple values are
990 /// allowed, `--option val1 val2 val3` is perfectly valid. Be careful when designing a CLI
991 /// where **positional arguments** or **subcommands** are *also* expected as `clap` will continue
992 /// parsing *values* until one of the following happens:
993 ///
994 /// - It reaches the maximum number of values
995 /// - It reaches a specific number of values
996 /// - It finds another flag or option (i.e. something that starts with a `-`)
997 /// - It reaches the [`Arg::value_terminator`] if set
998 ///
999 /// Alternatively,
1000 /// - Use a delimiter between values with [Arg::value_delimiter]
1001 /// - Require a flag occurrence per value with [`ArgAction::Append`]
1002 /// - Require positional arguments to appear after `--` with [`Arg::last`]
1003 ///
1004 /// # Examples
1005 ///
1006 /// Option:
1007 /// ```rust
1008 /// # use clap_builder as clap;
1009 /// # use clap::{Command, Arg};
1010 /// let m = Command::new("prog")
1011 /// .arg(Arg::new("mode")
1012 /// .long("mode")
1013 /// .num_args(1))
1014 /// .get_matches_from(vec![
1015 /// "prog", "--mode", "fast"
1016 /// ]);
1017 ///
1018 /// assert_eq!(m.get_one::<String>("mode").unwrap(), "fast");
1019 /// ```
1020 ///
1021 /// Flag/option hybrid (see also [default_missing_value][Arg::default_missing_value])
1022 /// ```rust
1023 /// # use clap_builder as clap;
1024 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction};
1025 /// let cmd = Command::new("prog")
1026 /// .arg(Arg::new("mode")
1027 /// .long("mode")
1028 /// .default_missing_value("slow")
1029 /// .default_value("plaid")
1030 /// .num_args(0..=1));
1031 ///
1032 /// let m = cmd.clone()
1033 /// .get_matches_from(vec![
1034 /// "prog", "--mode", "fast"
1035 /// ]);
1036 /// assert_eq!(m.get_one::<String>("mode").unwrap(), "fast");
1037 ///
1038 /// let m = cmd.clone()
1039 /// .get_matches_from(vec![
1040 /// "prog", "--mode",
1041 /// ]);
1042 /// assert_eq!(m.get_one::<String>("mode").unwrap(), "slow");
1043 ///
1044 /// let m = cmd.clone()
1045 /// .get_matches_from(vec![
1046 /// "prog",
1047 /// ]);
1048 /// assert_eq!(m.get_one::<String>("mode").unwrap(), "plaid");
1049 /// ```
1050 ///
1051 /// Tuples
1052 /// ```rust
1053 /// # use clap_builder as clap;
1054 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction};
1055 /// let cmd = Command::new("prog")
1056 /// .arg(Arg::new("file")
1057 /// .action(ArgAction::Set)
1058 /// .num_args(2)
1059 /// .short('F'));
1060 ///
1061 /// let m = cmd.clone()
1062 /// .get_matches_from(vec![
1063 /// "prog", "-F", "in-file", "out-file"
1064 /// ]);
1065 /// assert_eq!(
1066 /// m.get_many::<String>("file").unwrap_or_default().map(|v| v.as_str()).collect::<Vec<_>>(),
1067 /// vec!["in-file", "out-file"]
1068 /// );
1069 ///
1070 /// let res = cmd.clone()
1071 /// .try_get_matches_from(vec![
1072 /// "prog", "-F", "file1"
1073 /// ]);
1074 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::WrongNumberOfValues);
1075 /// ```
1076 ///
1077 /// A common mistake is to define an option which allows multiple values and a positional
1078 /// argument.
1079 /// ```rust
1080 /// # use clap_builder as clap;
1081 /// # use clap::{Command, Arg, ArgAction};
1082 /// let cmd = Command::new("prog")
1083 /// .arg(Arg::new("file")
1084 /// .action(ArgAction::Set)
1085 /// .num_args(0..)
1086 /// .short('F'))
1087 /// .arg(Arg::new("word"));
1088 ///
1089 /// let m = cmd.clone().get_matches_from(vec![
1090 /// "prog", "-F", "file1", "file2", "file3", "word"
1091 /// ]);
1092 /// let files: Vec<_> = m.get_many::<String>("file").unwrap().collect();
1093 /// assert_eq!(files, ["file1", "file2", "file3", "word"]); // wait...what?!
1094 /// assert!(!m.contains_id("word")); // but we clearly used word!
1095 ///
1096 /// // but this works
1097 /// let m = cmd.clone().get_matches_from(vec![
1098 /// "prog", "word", "-F", "file1", "file2", "file3",
1099 /// ]);
1100 /// let files: Vec<_> = m.get_many::<String>("file").unwrap().collect();
1101 /// assert_eq!(files, ["file1", "file2", "file3"]);
1102 /// assert_eq!(m.get_one::<String>("word").unwrap(), "word");
1103 /// ```
1104 /// The problem is `clap` doesn't know when to stop parsing values for "file".
1105 ///
1106 /// A solution for the example above is to limit how many values with a maximum, or specific
1107 /// number, or to say [`ArgAction::Append`] is ok, but multiple values are not.
1108 /// ```rust
1109 /// # use clap_builder as clap;
1110 /// # use clap::{Command, Arg, ArgAction};
1111 /// let m = Command::new("prog")
1112 /// .arg(Arg::new("file")
1113 /// .action(ArgAction::Append)
1114 /// .short('F'))
1115 /// .arg(Arg::new("word"))
1116 /// .get_matches_from(vec![
1117 /// "prog", "-F", "file1", "-F", "file2", "-F", "file3", "word"
1118 /// ]);
1119 ///
1120 /// let files: Vec<_> = m.get_many::<String>("file").unwrap().collect();
1121 /// assert_eq!(files, ["file1", "file2", "file3"]);
1122 /// assert_eq!(m.get_one::<String>("word").unwrap(), "word");
1123 /// ```
1124 #[inline]
1125 #[must_use]
1126 pub fn num_args(mut self, qty: impl IntoResettable<ValueRange>) -> Self {
1127 self.num_vals = qty.into_resettable().into_option();
1128 self
1129 }
1130
1131 #[doc(hidden)]
1132 #[cfg_attr(
1133 feature = "deprecated",
1134 deprecated(since = "4.0.0", note = "Replaced with `Arg::num_args`")
1135 )]
1136 pub fn number_of_values(self, qty: usize) -> Self {
1137 self.num_args(qty)
1138 }
1139
1140 /// Placeholder for the argument's value in the help message / usage.
1141 ///
1142 /// This name is cosmetic only; the name is **not** used to access arguments.
1143 /// This setting can be very helpful when describing the type of input the user should be
1144 /// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to
1145 /// use all capital letters for the value name.
1146 ///
1147 /// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`]
1148 ///
1149 /// # Examples
1150 ///
1151 /// ```rust
1152 /// # use clap_builder as clap;
1153 /// # use clap::{Command, Arg};
1154 /// Arg::new("cfg")
1155 /// .long("config")
1156 /// .value_name("FILE")
1157 /// # ;
1158 /// ```
1159 ///
1160 /// ```rust
1161 /// # use clap_builder as clap;
1162 /// # #[cfg(feature = "help")] {
1163 /// # use clap::{Command, Arg};
1164 /// let m = Command::new("prog")
1165 /// .arg(Arg::new("config")
1166 /// .long("config")
1167 /// .value_name("FILE")
1168 /// .help("Some help text"))
1169 /// .get_matches_from(vec![
1170 /// "prog", "--help"
1171 /// ]);
1172 /// # }
1173 /// ```
1174 /// Running the above program produces the following output
1175 ///
1176 /// ```text
1177 /// valnames
1178 ///
1179 /// Usage: valnames [OPTIONS]
1180 ///
1181 /// Options:
1182 /// --config <FILE> Some help text
1183 /// -h, --help Print help information
1184 /// -V, --version Print version information
1185 /// ```
1186 /// [positional]: Arg::index()
1187 /// [`Arg::action(ArgAction::Set)`]: Arg::action()
1188 #[inline]
1189 #[must_use]
1190 pub fn value_name(mut self, name: impl IntoResettable<Str>) -> Self {
1191 if let Some(name) = name.into_resettable().into_option() {
1192 self.value_names([name])
1193 } else {
1194 self.val_names.clear();
1195 self
1196 }
1197 }
1198
1199 /// Placeholders for the argument's values in the help message / usage.
1200 ///
1201 /// These names are cosmetic only, used for help and usage strings only. The names are **not**
1202 /// used to access arguments. The values of the arguments are accessed in numeric order (i.e.
1203 /// if you specify two names `one` and `two` `one` will be the first matched value, `two` will
1204 /// be the second).
1205 ///
1206 /// This setting can be very helpful when describing the type of input the user should be
1207 /// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to
1208 /// use all capital letters for the value name.
1209 ///
1210 /// **Pro Tip:** It may help to use [`Arg::next_line_help(true)`] if there are long, or
1211 /// multiple value names in order to not throw off the help text alignment of all options.
1212 ///
1213 /// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`] and [`Arg::num_args(1..)`].
1214 ///
1215 /// # Examples
1216 ///
1217 /// ```rust
1218 /// # use clap_builder as clap;
1219 /// # use clap::{Command, Arg};
1220 /// Arg::new("speed")
1221 /// .short('s')
1222 /// .value_names(["fast", "slow"]);
1223 /// ```
1224 ///
1225 /// ```rust
1226 /// # use clap_builder as clap;
1227 /// # #[cfg(feature = "help")] {
1228 /// # use clap::{Command, Arg};
1229 /// let m = Command::new("prog")
1230 /// .arg(Arg::new("io")
1231 /// .long("io-files")
1232 /// .value_names(["INFILE", "OUTFILE"]))
1233 /// .get_matches_from(vec![
1234 /// "prog", "--help"
1235 /// ]);
1236 /// # }
1237 /// ```
1238 ///
1239 /// Running the above program produces the following output
1240 ///
1241 /// ```text
1242 /// valnames
1243 ///
1244 /// Usage: valnames [OPTIONS]
1245 ///
1246 /// Options:
1247 /// -h, --help Print help information
1248 /// --io-files <INFILE> <OUTFILE> Some help text
1249 /// -V, --version Print version information
1250 /// ```
1251 /// [`Arg::next_line_help(true)`]: Arg::next_line_help()
1252 /// [`Arg::num_args`]: Arg::num_args()
1253 /// [`Arg::action(ArgAction::Set)`]: Arg::action()
1254 /// [`Arg::num_args(1..)`]: Arg::num_args()
1255 #[must_use]
1256 pub fn value_names(mut self, names: impl IntoIterator<Item = impl Into<Str>>) -> Self {
1257 self.val_names = names.into_iter().map(|s| s.into()).collect();
1258 self
1259 }
1260
1261 /// Provide the shell a hint about how to complete this argument.
1262 ///
1263 /// See [`ValueHint`] for more information.
1264 ///
1265 /// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`].
1266 ///
1267 /// For example, to take a username as argument:
1268 ///
1269 /// ```rust
1270 /// # use clap_builder as clap;
1271 /// # use clap::{Arg, ValueHint};
1272 /// Arg::new("user")
1273 /// .short('u')
1274 /// .long("user")
1275 /// .value_hint(ValueHint::Username);
1276 /// ```
1277 ///
1278 /// To take a full command line and its arguments (for example, when writing a command wrapper):
1279 ///
1280 /// ```rust
1281 /// # use clap_builder as clap;
1282 /// # use clap::{Command, Arg, ValueHint, ArgAction};
1283 /// Command::new("prog")
1284 /// .trailing_var_arg(true)
1285 /// .arg(
1286 /// Arg::new("command")
1287 /// .action(ArgAction::Set)
1288 /// .num_args(1..)
1289 /// .value_hint(ValueHint::CommandWithArguments)
1290 /// );
1291 /// ```
1292 #[must_use]
1293 pub fn value_hint(mut self, value_hint: impl IntoResettable<ValueHint>) -> Self {
1294 self.value_hint = value_hint.into_resettable().into_option();
1295 self
1296 }
1297
1298 /// Match values against [`PossibleValuesParser`][crate::builder::PossibleValuesParser] without matching case.
1299 ///
1300 /// When other arguments are conditionally required based on the
1301 /// value of a case-insensitive argument, the equality check done
1302 /// by [`Arg::required_if_eq`], [`Arg::required_if_eq_any`], or
1303 /// [`Arg::required_if_eq_all`] is case-insensitive.
1304 ///
1305 ///
1306 /// **NOTE:** Setting this requires [taking values][Arg::num_args]
1307 ///
1308 /// **NOTE:** To do unicode case folding, enable the `unicode` feature flag.
1309 ///
1310 /// # Examples
1311 ///
1312 /// ```rust
1313 /// # use clap_builder as clap;
1314 /// # use clap::{Command, Arg, ArgAction};
1315 /// let m = Command::new("pv")
1316 /// .arg(Arg::new("option")
1317 /// .long("option")
1318 /// .action(ArgAction::Set)
1319 /// .ignore_case(true)
1320 /// .value_parser(["test123"]))
1321 /// .get_matches_from(vec![
1322 /// "pv", "--option", "TeSt123",
1323 /// ]);
1324 ///
1325 /// assert!(m.get_one::<String>("option").unwrap().eq_ignore_ascii_case("test123"));
1326 /// ```
1327 ///
1328 /// This setting also works when multiple values can be defined:
1329 ///
1330 /// ```rust
1331 /// # use clap_builder as clap;
1332 /// # use clap::{Command, Arg, ArgAction};
1333 /// let m = Command::new("pv")
1334 /// .arg(Arg::new("option")
1335 /// .short('o')
1336 /// .long("option")
1337 /// .action(ArgAction::Set)
1338 /// .ignore_case(true)
1339 /// .num_args(1..)
1340 /// .value_parser(["test123", "test321"]))
1341 /// .get_matches_from(vec![
1342 /// "pv", "--option", "TeSt123", "teST123", "tESt321"
1343 /// ]);
1344 ///
1345 /// let matched_vals = m.get_many::<String>("option").unwrap().collect::<Vec<_>>();
1346 /// assert_eq!(&*matched_vals, &["TeSt123", "teST123", "tESt321"]);
1347 /// ```
1348 #[inline]
1349 #[must_use]
1350 pub fn ignore_case(self, yes: bool) -> Self {
1351 if yes {
1352 self.setting(ArgSettings::IgnoreCase)
1353 } else {
1354 self.unset_setting(ArgSettings::IgnoreCase)
1355 }
1356 }
1357
1358 /// Allows values which start with a leading hyphen (`-`)
1359 ///
1360 /// To limit values to just numbers, see
1361 /// [`allow_negative_numbers`][Arg::allow_negative_numbers].
1362 ///
1363 /// See also [`trailing_var_arg`][Arg::trailing_var_arg].
1364 ///
1365 /// **NOTE:** Setting this requires [taking values][Arg::num_args]
1366 ///
1367 /// **WARNING:** Prior arguments with `allow_hyphen_values(true)` get precedence over known
1368 /// flags but known flags get precedence over the next possible positional argument with
1369 /// `allow_hyphen_values(true)`. When combined with [`Arg::num_args(..)`],
1370 /// [`Arg::value_terminator`] is one way to ensure processing stops.
1371 ///
1372 /// **WARNING**: Take caution when using this setting combined with another argument using
1373 /// [`Arg::num_args`], as this becomes ambiguous `$ prog --arg -- -- val`. All
1374 /// three `--, --, val` will be values when the user may have thought the second `--` would
1375 /// constitute the normal, "Only positional args follow" idiom.
1376 ///
1377 /// # Examples
1378 ///
1379 /// ```rust
1380 /// # use clap_builder as clap;
1381 /// # use clap::{Command, Arg, ArgAction};
1382 /// let m = Command::new("prog")
1383 /// .arg(Arg::new("pat")
1384 /// .action(ArgAction::Set)
1385 /// .allow_hyphen_values(true)
1386 /// .long("pattern"))
1387 /// .get_matches_from(vec![
1388 /// "prog", "--pattern", "-file"
1389 /// ]);
1390 ///
1391 /// assert_eq!(m.get_one::<String>("pat").unwrap(), "-file");
1392 /// ```
1393 ///
1394 /// Not setting `Arg::allow_hyphen_values(true)` and supplying a value which starts with a
1395 /// hyphen is an error.
1396 ///
1397 /// ```rust
1398 /// # use clap_builder as clap;
1399 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction};
1400 /// let res = Command::new("prog")
1401 /// .arg(Arg::new("pat")
1402 /// .action(ArgAction::Set)
1403 /// .long("pattern"))
1404 /// .try_get_matches_from(vec![
1405 /// "prog", "--pattern", "-file"
1406 /// ]);
1407 ///
1408 /// assert!(res.is_err());
1409 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::UnknownArgument);
1410 /// ```
1411 /// [`Arg::num_args(1)`]: Arg::num_args()
1412 #[inline]
1413 #[must_use]
1414 pub fn allow_hyphen_values(self, yes: bool) -> Self {
1415 if yes {
1416 self.setting(ArgSettings::AllowHyphenValues)
1417 } else {
1418 self.unset_setting(ArgSettings::AllowHyphenValues)
1419 }
1420 }
1421
1422 /// Allows negative numbers to pass as values.
1423 ///
1424 /// This is similar to [`Arg::allow_hyphen_values`] except that it only allows numbers,
1425 /// all other undefined leading hyphens will fail to parse.
1426 ///
1427 /// **NOTE:** Setting this requires [taking values][Arg::num_args]
1428 ///
1429 /// # Examples
1430 ///
1431 /// ```rust
1432 /// # use clap_builder as clap;
1433 /// # use clap::{Command, Arg};
1434 /// let res = Command::new("myprog")
1435 /// .arg(Arg::new("num").allow_negative_numbers(true))
1436 /// .try_get_matches_from(vec![
1437 /// "myprog", "-20"
1438 /// ]);
1439 /// assert!(res.is_ok());
1440 /// let m = res.unwrap();
1441 /// assert_eq!(m.get_one::<String>("num").unwrap(), "-20");
1442 /// ```
1443 #[inline]
1444 pub fn allow_negative_numbers(self, yes: bool) -> Self {
1445 if yes {
1446 self.setting(ArgSettings::AllowNegativeNumbers)
1447 } else {
1448 self.unset_setting(ArgSettings::AllowNegativeNumbers)
1449 }
1450 }
1451
1452 /// Requires that options use the `--option=val` syntax
1453 ///
1454 /// i.e. an equals between the option and associated value.
1455 ///
1456 /// **NOTE:** Setting this requires [taking values][Arg::num_args]
1457 ///
1458 /// # Examples
1459 ///
1460 /// Setting `require_equals` requires that the option have an equals sign between
1461 /// it and the associated value.
1462 ///
1463 /// ```rust
1464 /// # use clap_builder as clap;
1465 /// # use clap::{Command, Arg, ArgAction};
1466 /// let res = Command::new("prog")
1467 /// .arg(Arg::new("cfg")
1468 /// .action(ArgAction::Set)
1469 /// .require_equals(true)
1470 /// .long("config"))
1471 /// .try_get_matches_from(vec![
1472 /// "prog", "--config=file.conf"
1473 /// ]);
1474 ///
1475 /// assert!(res.is_ok());
1476 /// ```
1477 ///
1478 /// Setting `require_equals` and *not* supplying the equals will cause an
1479 /// error.
1480 ///
1481 /// ```rust
1482 /// # use clap_builder as clap;
1483 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction};
1484 /// let res = Command::new("prog")
1485 /// .arg(Arg::new("cfg")
1486 /// .action(ArgAction::Set)
1487 /// .require_equals(true)
1488 /// .long("config"))
1489 /// .try_get_matches_from(vec![
1490 /// "prog", "--config", "file.conf"
1491 /// ]);
1492 ///
1493 /// assert!(res.is_err());
1494 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::NoEquals);
1495 /// ```
1496 #[inline]
1497 #[must_use]
1498 pub fn require_equals(self, yes: bool) -> Self {
1499 if yes {
1500 self.setting(ArgSettings::RequireEquals)
1501 } else {
1502 self.unset_setting(ArgSettings::RequireEquals)
1503 }
1504 }
1505
1506 #[doc(hidden)]
1507 #[cfg_attr(
1508 feature = "deprecated",
1509 deprecated(since = "4.0.0", note = "Replaced with `Arg::value_delimiter`")
1510 )]
1511 pub fn use_value_delimiter(mut self, yes: bool) -> Self {
1512 if yes {
1513 self.val_delim.get_or_insert(',');
1514 } else {
1515 self.val_delim = None;
1516 }
1517 self
1518 }
1519
1520 /// Allow grouping of multiple values via a delimiter.
1521 ///
1522 /// i.e. should `--option=val1,val2,val3` be parsed as three values (`val1`, `val2`,
1523 /// and `val3`) or as a single value (`val1,val2,val3`). Defaults to using `,` (comma) as the
1524 /// value delimiter for all arguments that accept values (options and positional arguments)
1525 ///
1526 /// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`]
1527 ///
1528 /// # Examples
1529 ///
1530 /// ```rust
1531 /// # use clap_builder as clap;
1532 /// # use clap::{Command, Arg};
1533 /// let m = Command::new("prog")
1534 /// .arg(Arg::new("config")
1535 /// .short('c')
1536 /// .long("config")
1537 /// .value_delimiter(','))
1538 /// .get_matches_from(vec![
1539 /// "prog", "--config=val1,val2,val3"
1540 /// ]);
1541 ///
1542 /// assert_eq!(m.get_many::<String>("config").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"])
1543 /// ```
1544 /// [`Arg::value_delimiter(',')`]: Arg::value_delimiter()
1545 /// [`Arg::action(ArgAction::Set)`]: Arg::action()
1546 #[inline]
1547 #[must_use]
1548 pub fn value_delimiter(mut self, d: impl IntoResettable<char>) -> Self {
1549 self.val_delim = d.into_resettable().into_option();
1550 self
1551 }
1552
1553 /// Sentinel to **stop** parsing multiple values of a given argument.
1554 ///
1555 /// By default when
1556 /// one sets [`num_args(1..)`] on an argument, clap will continue parsing values for that
1557 /// argument until it reaches another valid argument, or one of the other more specific settings
1558 /// for multiple values is used (such as [`num_args`]).
1559 ///
1560 /// **NOTE:** This setting only applies to [options] and [positional arguments]
1561 ///
1562 /// **NOTE:** When the terminator is passed in on the command line, it is **not** stored as one
1563 /// of the values
1564 ///
1565 /// # Examples
1566 ///
1567 /// ```rust
1568 /// # use clap_builder as clap;
1569 /// # use clap::{Command, Arg, ArgAction};
1570 /// Arg::new("vals")
1571 /// .action(ArgAction::Set)
1572 /// .num_args(1..)
1573 /// .value_terminator(";")
1574 /// # ;
1575 /// ```
1576 ///
1577 /// The following example uses two arguments, a sequence of commands, and the location in which
1578 /// to perform them
1579 ///
1580 /// ```rust
1581 /// # use clap_builder as clap;
1582 /// # use clap::{Command, Arg, ArgAction};
1583 /// let m = Command::new("prog")
1584 /// .arg(Arg::new("cmds")
1585 /// .action(ArgAction::Set)
1586 /// .num_args(1..)
1587 /// .allow_hyphen_values(true)
1588 /// .value_terminator(";"))
1589 /// .arg(Arg::new("location"))
1590 /// .get_matches_from(vec![
1591 /// "prog", "find", "-type", "f", "-name", "special", ";", "/home/clap"
1592 /// ]);
1593 /// let cmds: Vec<_> = m.get_many::<String>("cmds").unwrap().collect();
1594 /// assert_eq!(&cmds, &["find", "-type", "f", "-name", "special"]);
1595 /// assert_eq!(m.get_one::<String>("location").unwrap(), "/home/clap");
1596 /// ```
1597 /// [options]: Arg::action
1598 /// [positional arguments]: Arg::index()
1599 /// [`num_args(1..)`]: Arg::num_args()
1600 /// [`num_args`]: Arg::num_args()
1601 #[inline]
1602 #[must_use]
1603 pub fn value_terminator(mut self, term: impl IntoResettable<Str>) -> Self {
1604 self.terminator = term.into_resettable().into_option();
1605 self
1606 }
1607
1608 /// Consume all following arguments.
1609 ///
1610 /// Do not be parse them individually, but rather pass them in entirety.
1611 ///
1612 /// It is worth noting that setting this requires all values to come after a `--` to indicate
1613 /// they should all be captured. For example:
1614 ///
1615 /// ```text
1616 /// --foo something -- -v -v -v -b -b -b --baz -q -u -x
1617 /// ```
1618 ///
1619 /// Will result in everything after `--` to be considered one raw argument. This behavior
1620 /// may not be exactly what you are expecting and using [`Arg::trailing_var_arg`]
1621 /// may be more appropriate.
1622 ///
1623 /// **NOTE:** Implicitly sets [`Arg::action(ArgAction::Set)`] [`Arg::num_args(1..)`],
1624 /// [`Arg::allow_hyphen_values(true)`], and [`Arg::last(true)`] when set to `true`.
1625 ///
1626 /// [`Arg::action(ArgAction::Set)`]: Arg::action()
1627 /// [`Arg::num_args(1..)`]: Arg::num_args()
1628 /// [`Arg::allow_hyphen_values(true)`]: Arg::allow_hyphen_values()
1629 /// [`Arg::last(true)`]: Arg::last()
1630 #[inline]
1631 #[must_use]
1632 pub fn raw(mut self, yes: bool) -> Self {
1633 if yes {
1634 self.num_vals.get_or_insert_with(|| (1..).into());
1635 }
1636 self.allow_hyphen_values(yes).last(yes)
1637 }
1638
1639 /// Value for the argument when not present.
1640 ///
1641 /// **NOTE:** If the user *does not* use this argument at runtime [`ArgMatches::contains_id`] will
1642 /// still return `true`. If you wish to determine whether the argument was used at runtime or
1643 /// not, consider [`ArgMatches::value_source`][crate::ArgMatches::value_source].
1644 ///
1645 /// **NOTE:** This setting is perfectly compatible with [`Arg::default_value_if`] but slightly
1646 /// different. `Arg::default_value` *only* takes effect when the user has not provided this arg
1647 /// at runtime. `Arg::default_value_if` however only takes effect when the user has not provided
1648 /// a value at runtime **and** these other conditions are met as well. If you have set
1649 /// `Arg::default_value` and `Arg::default_value_if`, and the user **did not** provide this arg
1650 /// at runtime, nor were the conditions met for `Arg::default_value_if`, the `Arg::default_value`
1651 /// will be applied.
1652 ///
1653 /// Like with command-line values, this will be split by [`Arg::value_delimiter`].
1654 ///
1655 /// # Examples
1656 ///
1657 /// First we use the default value without providing any value at runtime.
1658 ///
1659 /// ```rust
1660 /// # use clap_builder as clap;
1661 /// # use clap::{Command, Arg, parser::ValueSource};
1662 /// let m = Command::new("prog")
1663 /// .arg(Arg::new("opt")
1664 /// .long("myopt")
1665 /// .default_value("myval"))
1666 /// .get_matches_from(vec![
1667 /// "prog"
1668 /// ]);
1669 ///
1670 /// assert_eq!(m.get_one::<String>("opt").unwrap(), "myval");
1671 /// assert!(m.contains_id("opt"));
1672 /// assert_eq!(m.value_source("opt"), Some(ValueSource::DefaultValue));
1673 /// ```
1674 ///
1675 /// Next we provide a value at runtime to override the default.
1676 ///
1677 /// ```rust
1678 /// # use clap_builder as clap;
1679 /// # use clap::{Command, Arg, parser::ValueSource};
1680 /// let m = Command::new("prog")
1681 /// .arg(Arg::new("opt")
1682 /// .long("myopt")
1683 /// .default_value("myval"))
1684 /// .get_matches_from(vec![
1685 /// "prog", "--myopt=non_default"
1686 /// ]);
1687 ///
1688 /// assert_eq!(m.get_one::<String>("opt").unwrap(), "non_default");
1689 /// assert!(m.contains_id("opt"));
1690 /// assert_eq!(m.value_source("opt"), Some(ValueSource::CommandLine));
1691 /// ```
1692 /// [`Arg::action(ArgAction::Set)`]: Arg::action()
1693 /// [`ArgMatches::contains_id`]: crate::ArgMatches::contains_id()
1694 /// [`Arg::default_value_if`]: Arg::default_value_if()
1695 #[inline]
1696 #[must_use]
1697 pub fn default_value(mut self, val: impl IntoResettable<OsStr>) -> Self {
1698 if let Some(val) = val.into_resettable().into_option() {
1699 self.default_values([val])
1700 } else {
1701 self.default_vals.clear();
1702 self
1703 }
1704 }
1705
1706 #[inline]
1707 #[must_use]
1708 #[doc(hidden)]
1709 #[cfg_attr(
1710 feature = "deprecated",
1711 deprecated(since = "4.0.0", note = "Replaced with `Arg::default_value`")
1712 )]
1713 pub fn default_value_os(self, val: impl Into<OsStr>) -> Self {
1714 self.default_values([val])
1715 }
1716
1717 /// Value for the argument when not present.
1718 ///
1719 /// See [`Arg::default_value`].
1720 ///
1721 /// [`Arg::default_value`]: Arg::default_value()
1722 #[inline]
1723 #[must_use]
1724 pub fn default_values(mut self, vals: impl IntoIterator<Item = impl Into<OsStr>>) -> Self {
1725 self.default_vals = vals.into_iter().map(|s| s.into()).collect();
1726 self
1727 }
1728
1729 #[inline]
1730 #[must_use]
1731 #[doc(hidden)]
1732 #[cfg_attr(
1733 feature = "deprecated",
1734 deprecated(since = "4.0.0", note = "Replaced with `Arg::default_values`")
1735 )]
1736 pub fn default_values_os(self, vals: impl IntoIterator<Item = impl Into<OsStr>>) -> Self {
1737 self.default_values(vals)
1738 }
1739
1740 /// Value for the argument when the flag is present but no value is specified.
1741 ///
1742 /// This configuration option is often used to give the user a shortcut and allow them to
1743 /// efficiently specify an option argument without requiring an explicitly value. The `--color`
1744 /// argument is a common example. By, supplying an default, such as `default_missing_value("always")`,
1745 /// the user can quickly just add `--color` to the command line to produce the desired color output.
1746 ///
1747 /// **NOTE:** using this configuration option requires the use of the
1748 /// [`.num_args(0..N)`][Arg::num_args] and the
1749 /// [`.require_equals(true)`][Arg::require_equals] configuration option. These are required in
1750 /// order to unambiguously determine what, if any, value was supplied for the argument.
1751 ///
1752 /// Like with command-line values, this will be split by [`Arg::value_delimiter`].
1753 ///
1754 /// # Examples
1755 ///
1756 /// For POSIX style `--color`:
1757 /// ```rust
1758 /// # use clap_builder as clap;
1759 /// # use clap::{Command, Arg, parser::ValueSource};
1760 /// fn cli() -> Command {
1761 /// Command::new("prog")
1762 /// .arg(Arg::new("color").long("color")
1763 /// .value_name("WHEN")
1764 /// .value_parser(["always", "auto", "never"])
1765 /// .default_value("auto")
1766 /// .num_args(0..=1)
1767 /// .require_equals(true)
1768 /// .default_missing_value("always")
1769 /// .help("Specify WHEN to colorize output.")
1770 /// )
1771 /// }
1772 ///
1773 /// // first, we'll provide no arguments
1774 /// let m = cli().get_matches_from(vec![
1775 /// "prog"
1776 /// ]);
1777 /// assert_eq!(m.get_one::<String>("color").unwrap(), "auto");
1778 /// assert_eq!(m.value_source("color"), Some(ValueSource::DefaultValue));
1779 ///
1780 /// // next, we'll provide a runtime value to override the default (as usually done).
1781 /// let m = cli().get_matches_from(vec![
1782 /// "prog", "--color=never"
1783 /// ]);
1784 /// assert_eq!(m.get_one::<String>("color").unwrap(), "never");
1785 /// assert_eq!(m.value_source("color"), Some(ValueSource::CommandLine));
1786 ///
1787 /// // finally, we will use the shortcut and only provide the argument without a value.
1788 /// let m = cli().get_matches_from(vec![
1789 /// "prog", "--color"
1790 /// ]);
1791 /// assert_eq!(m.get_one::<String>("color").unwrap(), "always");
1792 /// assert_eq!(m.value_source("color"), Some(ValueSource::CommandLine));
1793 /// ```
1794 ///
1795 /// For bool literals:
1796 /// ```rust
1797 /// # use clap_builder as clap;
1798 /// # use clap::{Command, Arg, parser::ValueSource, value_parser};
1799 /// fn cli() -> Command {
1800 /// Command::new("prog")
1801 /// .arg(Arg::new("create").long("create")
1802 /// .value_name("BOOL")
1803 /// .value_parser(value_parser!(bool))
1804 /// .num_args(0..=1)
1805 /// .require_equals(true)
1806 /// .default_missing_value("true")
1807 /// )
1808 /// }
1809 ///
1810 /// // first, we'll provide no arguments
1811 /// let m = cli().get_matches_from(vec![
1812 /// "prog"
1813 /// ]);
1814 /// assert_eq!(m.get_one::<bool>("create").copied(), None);
1815 ///
1816 /// // next, we'll provide a runtime value to override the default (as usually done).
1817 /// let m = cli().get_matches_from(vec![
1818 /// "prog", "--create=false"
1819 /// ]);
1820 /// assert_eq!(m.get_one::<bool>("create").copied(), Some(false));
1821 /// assert_eq!(m.value_source("create"), Some(ValueSource::CommandLine));
1822 ///
1823 /// // finally, we will use the shortcut and only provide the argument without a value.
1824 /// let m = cli().get_matches_from(vec![
1825 /// "prog", "--create"
1826 /// ]);
1827 /// assert_eq!(m.get_one::<bool>("create").copied(), Some(true));
1828 /// assert_eq!(m.value_source("create"), Some(ValueSource::CommandLine));
1829 /// ```
1830 ///
1831 /// [`Arg::action(ArgAction::Set)`]: Arg::action()
1832 /// [`Arg::default_value`]: Arg::default_value()
1833 #[inline]
1834 #[must_use]
1835 pub fn default_missing_value(mut self, val: impl IntoResettable<OsStr>) -> Self {
1836 if let Some(val) = val.into_resettable().into_option() {
1837 self.default_missing_values_os([val])
1838 } else {
1839 self.default_missing_vals.clear();
1840 self
1841 }
1842 }
1843
1844 /// Value for the argument when the flag is present but no value is specified.
1845 ///
1846 /// See [`Arg::default_missing_value`].
1847 ///
1848 /// [`Arg::default_missing_value`]: Arg::default_missing_value()
1849 /// [`OsStr`]: std::ffi::OsStr
1850 #[inline]
1851 #[must_use]
1852 pub fn default_missing_value_os(self, val: impl Into<OsStr>) -> Self {
1853 self.default_missing_values_os([val])
1854 }
1855
1856 /// Value for the argument when the flag is present but no value is specified.
1857 ///
1858 /// See [`Arg::default_missing_value`].
1859 ///
1860 /// [`Arg::default_missing_value`]: Arg::default_missing_value()
1861 #[inline]
1862 #[must_use]
1863 pub fn default_missing_values(self, vals: impl IntoIterator<Item = impl Into<OsStr>>) -> Self {
1864 self.default_missing_values_os(vals)
1865 }
1866
1867 /// Value for the argument when the flag is present but no value is specified.
1868 ///
1869 /// See [`Arg::default_missing_values`].
1870 ///
1871 /// [`Arg::default_missing_values`]: Arg::default_missing_values()
1872 /// [`OsStr`]: std::ffi::OsStr
1873 #[inline]
1874 #[must_use]
1875 pub fn default_missing_values_os(
1876 mut self,
1877 vals: impl IntoIterator<Item = impl Into<OsStr>>,
1878 ) -> Self {
1879 self.default_missing_vals = vals.into_iter().map(|s| s.into()).collect();
1880 self
1881 }
1882
1883 /// Read from `name` environment variable when argument is not present.
1884 ///
1885 /// If it is not present in the environment, then default
1886 /// rules will apply.
1887 ///
1888 /// If user sets the argument in the environment:
1889 /// - When [`Arg::action(ArgAction::Set)`] is not set, the flag is considered raised.
1890 /// - When [`Arg::action(ArgAction::Set)`] is set,
1891 /// [`ArgMatches::get_one`][crate::ArgMatches::get_one] will
1892 /// return value of the environment variable.
1893 ///
1894 /// If user doesn't set the argument in the environment:
1895 /// - When [`Arg::action(ArgAction::Set)`] is not set, the flag is considered off.
1896 /// - When [`Arg::action(ArgAction::Set)`] is set,
1897 /// [`ArgMatches::get_one`][crate::ArgMatches::get_one] will
1898 /// return the default specified.
1899 ///
1900 /// Like with command-line values, this will be split by [`Arg::value_delimiter`].
1901 ///
1902 /// # Examples
1903 ///
1904 /// In this example, we show the variable coming from the environment:
1905 ///
1906 /// ```rust
1907 /// # use clap_builder as clap;
1908 /// # use std::env;
1909 /// # use clap::{Command, Arg, ArgAction};
1910 ///
1911 /// env::set_var("MY_FLAG", "env");
1912 ///
1913 /// let m = Command::new("prog")
1914 /// .arg(Arg::new("flag")
1915 /// .long("flag")
1916 /// .env("MY_FLAG")
1917 /// .action(ArgAction::Set))
1918 /// .get_matches_from(vec![
1919 /// "prog"
1920 /// ]);
1921 ///
1922 /// assert_eq!(m.get_one::<String>("flag").unwrap(), "env");
1923 /// ```
1924 ///
1925 /// In this example, because `prog` is a flag that accepts an optional, case-insensitive
1926 /// boolean literal.
1927 ///
1928 /// Note that the value parser controls how flags are parsed. In this case we've selected
1929 /// [`FalseyValueParser`][crate::builder::FalseyValueParser]. A `false` literal is `n`, `no`,
1930 /// `f`, `false`, `off` or `0`. An absent environment variable will also be considered as
1931 /// `false`. Anything else will considered as `true`.
1932 ///
1933 /// ```rust
1934 /// # use clap_builder as clap;
1935 /// # use std::env;
1936 /// # use clap::{Command, Arg, ArgAction};
1937 /// # use clap::builder::FalseyValueParser;
1938 ///
1939 /// env::set_var("TRUE_FLAG", "true");
1940 /// env::set_var("FALSE_FLAG", "0");
1941 ///
1942 /// let m = Command::new("prog")
1943 /// .arg(Arg::new("true_flag")
1944 /// .long("true_flag")
1945 /// .action(ArgAction::SetTrue)
1946 /// .value_parser(FalseyValueParser::new())
1947 /// .env("TRUE_FLAG"))
1948 /// .arg(Arg::new("false_flag")
1949 /// .long("false_flag")
1950 /// .action(ArgAction::SetTrue)
1951 /// .value_parser(FalseyValueParser::new())
1952 /// .env("FALSE_FLAG"))
1953 /// .arg(Arg::new("absent_flag")
1954 /// .long("absent_flag")
1955 /// .action(ArgAction::SetTrue)
1956 /// .value_parser(FalseyValueParser::new())
1957 /// .env("ABSENT_FLAG"))
1958 /// .get_matches_from(vec![
1959 /// "prog"
1960 /// ]);
1961 ///
1962 /// assert!(m.get_flag("true_flag"));
1963 /// assert!(!m.get_flag("false_flag"));
1964 /// assert!(!m.get_flag("absent_flag"));
1965 /// ```
1966 ///
1967 /// In this example, we show the variable coming from an option on the CLI:
1968 ///
1969 /// ```rust
1970 /// # use clap_builder as clap;
1971 /// # use std::env;
1972 /// # use clap::{Command, Arg, ArgAction};
1973 ///
1974 /// env::set_var("MY_FLAG", "env");
1975 ///
1976 /// let m = Command::new("prog")
1977 /// .arg(Arg::new("flag")
1978 /// .long("flag")
1979 /// .env("MY_FLAG")
1980 /// .action(ArgAction::Set))
1981 /// .get_matches_from(vec![
1982 /// "prog", "--flag", "opt"
1983 /// ]);
1984 ///
1985 /// assert_eq!(m.get_one::<String>("flag").unwrap(), "opt");
1986 /// ```
1987 ///
1988 /// In this example, we show the variable coming from the environment even with the
1989 /// presence of a default:
1990 ///
1991 /// ```rust
1992 /// # use clap_builder as clap;
1993 /// # use std::env;
1994 /// # use clap::{Command, Arg, ArgAction};
1995 ///
1996 /// env::set_var("MY_FLAG", "env");
1997 ///
1998 /// let m = Command::new("prog")
1999 /// .arg(Arg::new("flag")
2000 /// .long("flag")
2001 /// .env("MY_FLAG")
2002 /// .action(ArgAction::Set)
2003 /// .default_value("default"))
2004 /// .get_matches_from(vec![
2005 /// "prog"
2006 /// ]);
2007 ///
2008 /// assert_eq!(m.get_one::<String>("flag").unwrap(), "env");
2009 /// ```
2010 ///
2011 /// In this example, we show the use of multiple values in a single environment variable:
2012 ///
2013 /// ```rust
2014 /// # use clap_builder as clap;
2015 /// # use std::env;
2016 /// # use clap::{Command, Arg, ArgAction};
2017 ///
2018 /// env::set_var("MY_FLAG_MULTI", "env1,env2");
2019 ///
2020 /// let m = Command::new("prog")
2021 /// .arg(Arg::new("flag")
2022 /// .long("flag")
2023 /// .env("MY_FLAG_MULTI")
2024 /// .action(ArgAction::Set)
2025 /// .num_args(1..)
2026 /// .value_delimiter(','))
2027 /// .get_matches_from(vec![
2028 /// "prog"
2029 /// ]);
2030 ///
2031 /// assert_eq!(m.get_many::<String>("flag").unwrap().collect::<Vec<_>>(), vec!["env1", "env2"]);
2032 /// ```
2033 /// [`Arg::action(ArgAction::Set)`]: Arg::action()
2034 /// [`Arg::value_delimiter(',')`]: Arg::value_delimiter()
2035 #[cfg(feature = "env")]
2036 #[inline]
2037 #[must_use]
2038 pub fn env(mut self, name: impl IntoResettable<OsStr>) -> Self {
2039 if let Some(name) = name.into_resettable().into_option() {
2040 let value = env::var_os(&name);
2041 self.env = Some((name, value));
2042 } else {
2043 self.env = None;
2044 }
2045 self
2046 }
2047
2048 #[cfg(feature = "env")]
2049 #[doc(hidden)]
2050 #[cfg_attr(
2051 feature = "deprecated",
2052 deprecated(since = "4.0.0", note = "Replaced with `Arg::env`")
2053 )]
2054 pub fn env_os(self, name: impl Into<OsStr>) -> Self {
2055 self.env(name)
2056 }
2057}
2058
2059/// # Help
2060impl Arg {
2061 /// Sets the description of the argument for short help (`-h`).
2062 ///
2063 /// Typically, this is a short (one line) description of the arg.
2064 ///
2065 /// If [`Arg::long_help`] is not specified, this message will be displayed for `--help`.
2066 ///
2067 /// **NOTE:** Only `Arg::help` is used in completion script generation in order to be concise
2068 ///
2069 /// # Examples
2070 ///
2071 /// Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to
2072 /// include a newline in the help text and have the following text be properly aligned with all
2073 /// the other help text.
2074 ///
2075 /// Setting `help` displays a short message to the side of the argument when the user passes
2076 /// `-h` or `--help` (by default).
2077 ///
2078 /// ```rust
2079 /// # #[cfg(feature = "help")] {
2080 /// # use clap_builder as clap;
2081 /// # use clap::{Command, Arg};
2082 /// let m = Command::new("prog")
2083 /// .arg(Arg::new("cfg")
2084 /// .long("config")
2085 /// .help("Some help text describing the --config arg"))
2086 /// .get_matches_from(vec![
2087 /// "prog", "--help"
2088 /// ]);
2089 /// # }
2090 /// ```
2091 ///
2092 /// The above example displays
2093 ///
2094 /// ```notrust
2095 /// helptest
2096 ///
2097 /// Usage: helptest [OPTIONS]
2098 ///
2099 /// Options:
2100 /// --config Some help text describing the --config arg
2101 /// -h, --help Print help information
2102 /// -V, --version Print version information
2103 /// ```
2104 /// [`Arg::long_help`]: Arg::long_help()
2105 #[inline]
2106 #[must_use]
2107 pub fn help(mut self, h: impl IntoResettable<StyledStr>) -> Self {
2108 self.help = h.into_resettable().into_option();
2109 self
2110 }
2111
2112 /// Sets the description of the argument for long help (`--help`).
2113 ///
2114 /// Typically this a more detailed (multi-line) message
2115 /// that describes the arg.
2116 ///
2117 /// If [`Arg::help`] is not specified, this message will be displayed for `-h`.
2118 ///
2119 /// **NOTE:** Only [`Arg::help`] is used in completion script generation in order to be concise
2120 ///
2121 /// # Examples
2122 ///
2123 /// Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to
2124 /// include a newline in the help text and have the following text be properly aligned with all
2125 /// the other help text.
2126 ///
2127 /// Setting `help` displays a short message to the side of the argument when the user passes
2128 /// `-h` or `--help` (by default).
2129 ///
2130 /// ```rust
2131 /// # #[cfg(feature = "help")] {
2132 /// # use clap_builder as clap;
2133 /// # use clap::{Command, Arg};
2134 /// let m = Command::new("prog")
2135 /// .arg(Arg::new("cfg")
2136 /// .long("config")
2137 /// .long_help(
2138 /// "The config file used by the myprog must be in JSON format
2139 /// with only valid keys and may not contain other nonsense
2140 /// that cannot be read by this program. Obviously I'm going on
2141 /// and on, so I'll stop now."))
2142 /// .get_matches_from(vec![
2143 /// "prog", "--help"
2144 /// ]);
2145 /// # }
2146 /// ```
2147 ///
2148 /// The above example displays
2149 ///
2150 /// ```text
2151 /// prog
2152 ///
2153 /// Usage: prog [OPTIONS]
2154 ///
2155 /// Options:
2156 /// --config
2157 /// The config file used by the myprog must be in JSON format
2158 /// with only valid keys and may not contain other nonsense
2159 /// that cannot be read by this program. Obviously I'm going on
2160 /// and on, so I'll stop now.
2161 ///
2162 /// -h, --help
2163 /// Print help information
2164 ///
2165 /// -V, --version
2166 /// Print version information
2167 /// ```
2168 /// [`Arg::help`]: Arg::help()
2169 #[inline]
2170 #[must_use]
2171 pub fn long_help(mut self, h: impl IntoResettable<StyledStr>) -> Self {
2172 self.long_help = h.into_resettable().into_option();
2173 self
2174 }
2175
2176 /// Allows custom ordering of args within the help message.
2177 ///
2178 /// `Arg`s with a lower value will be displayed first in the help message.
2179 /// Those with the same display order will be sorted.
2180 ///
2181 /// `Arg`s are automatically assigned a display order based on the order they are added to the
2182 /// [`Command`][crate::Command].
2183 /// Overriding this is helpful when the order arguments are added in isn't the same as the
2184 /// display order, whether in one-off cases or to automatically sort arguments.
2185 ///
2186 /// To change, see [`Command::next_display_order`][crate::Command::next_display_order].
2187 ///
2188 /// **NOTE:** This setting is ignored for [positional arguments] which are always displayed in
2189 /// [index] order.
2190 ///
2191 /// # Examples
2192 ///
2193 /// ```rust
2194 /// # #[cfg(feature = "help")] {
2195 /// # use clap_builder as clap;
2196 /// # use clap::{Command, Arg, ArgAction};
2197 /// let m = Command::new("prog")
2198 /// .arg(Arg::new("boat")
2199 /// .short('b')
2200 /// .long("boat")
2201 /// .action(ArgAction::Set)
2202 /// .display_order(0) // Sort
2203 /// .help("Some help and text"))
2204 /// .arg(Arg::new("airplane")
2205 /// .short('a')
2206 /// .long("airplane")
2207 /// .action(ArgAction::Set)
2208 /// .display_order(0) // Sort
2209 /// .help("I should be first!"))
2210 /// .arg(Arg::new("custom-help")
2211 /// .short('?')
2212 /// .action(ArgAction::Help)
2213 /// .display_order(100) // Don't sort
2214 /// .help("Alt help"))
2215 /// .get_matches_from(vec![
2216 /// "prog", "--help"
2217 /// ]);
2218 /// # }
2219 /// ```
2220 ///
2221 /// The above example displays the following help message
2222 ///
2223 /// ```text
2224 /// cust-ord
2225 ///
2226 /// Usage: cust-ord [OPTIONS]
2227 ///
2228 /// Options:
2229 /// -a, --airplane <airplane> I should be first!
2230 /// -b, --boat <boar> Some help and text
2231 /// -h, --help Print help information
2232 /// -? Alt help
2233 /// ```
2234 /// [positional arguments]: Arg::index()
2235 /// [index]: Arg::index()
2236 #[inline]
2237 #[must_use]
2238 pub fn display_order(mut self, ord: impl IntoResettable<usize>) -> Self {
2239 self.disp_ord = ord.into_resettable().into_option();
2240 self
2241 }
2242
2243 /// Override the [current] help section.
2244 ///
2245 /// [current]: crate::Command::next_help_heading
2246 #[inline]
2247 #[must_use]
2248 pub fn help_heading(mut self, heading: impl IntoResettable<Str>) -> Self {
2249 self.help_heading = Some(heading.into_resettable().into_option());
2250 self
2251 }
2252
2253 /// Render the [help][Arg::help] on the line after the argument.
2254 ///
2255 /// This can be helpful for arguments with very long or complex help messages.
2256 /// This can also be helpful for arguments with very long flag names, or many/long value names.
2257 ///
2258 /// **NOTE:** To apply this setting to all arguments and subcommands, consider using
2259 /// [`crate::Command::next_line_help`]
2260 ///
2261 /// # Examples
2262 ///
2263 /// ```rust
2264 /// # #[cfg(feature = "help")] {
2265 /// # use clap_builder as clap;
2266 /// # use clap::{Command, Arg, ArgAction};
2267 /// let m = Command::new("prog")
2268 /// .arg(Arg::new("opt")
2269 /// .long("long-option-flag")
2270 /// .short('o')
2271 /// .action(ArgAction::Set)
2272 /// .next_line_help(true)
2273 /// .value_names(["value1", "value2"])
2274 /// .help("Some really long help and complex\n\
2275 /// help that makes more sense to be\n\
2276 /// on a line after the option"))
2277 /// .get_matches_from(vec![
2278 /// "prog", "--help"
2279 /// ]);
2280 /// # }
2281 /// ```
2282 ///
2283 /// The above example displays the following help message
2284 ///
2285 /// ```text
2286 /// nlh
2287 ///
2288 /// Usage: nlh [OPTIONS]
2289 ///
2290 /// Options:
2291 /// -h, --help Print help information
2292 /// -V, --version Print version information
2293 /// -o, --long-option-flag <value1> <value2>
2294 /// Some really long help and complex
2295 /// help that makes more sense to be
2296 /// on a line after the option
2297 /// ```
2298 #[inline]
2299 #[must_use]
2300 pub fn next_line_help(self, yes: bool) -> Self {
2301 if yes {
2302 self.setting(ArgSettings::NextLineHelp)
2303 } else {
2304 self.unset_setting(ArgSettings::NextLineHelp)
2305 }
2306 }
2307
2308 /// Do not display the argument in help message.
2309 ///
2310 /// **NOTE:** This does **not** hide the argument from usage strings on error
2311 ///
2312 /// # Examples
2313 ///
2314 /// Setting `Hidden` will hide the argument when displaying help text
2315 ///
2316 /// ```rust
2317 /// # #[cfg(feature = "help")] {
2318 /// # use clap_builder as clap;
2319 /// # use clap::{Command, Arg};
2320 /// let m = Command::new("prog")
2321 /// .arg(Arg::new("cfg")
2322 /// .long("config")
2323 /// .hide(true)
2324 /// .help("Some help text describing the --config arg"))
2325 /// .get_matches_from(vec![
2326 /// "prog", "--help"
2327 /// ]);
2328 /// # }
2329 /// ```
2330 ///
2331 /// The above example displays
2332 ///
2333 /// ```text
2334 /// helptest
2335 ///
2336 /// Usage: helptest [OPTIONS]
2337 ///
2338 /// Options:
2339 /// -h, --help Print help information
2340 /// -V, --version Print version information
2341 /// ```
2342 #[inline]
2343 #[must_use]
2344 pub fn hide(self, yes: bool) -> Self {
2345 if yes {
2346 self.setting(ArgSettings::Hidden)
2347 } else {
2348 self.unset_setting(ArgSettings::Hidden)
2349 }
2350 }
2351
2352 /// Do not display the [possible values][crate::builder::ValueParser::possible_values] in the help message.
2353 ///
2354 /// This is useful for args with many values, or ones which are explained elsewhere in the
2355 /// help text.
2356 ///
2357 /// **NOTE:** Setting this requires [taking values][Arg::num_args]
2358 ///
2359 /// To set this for all arguments, see
2360 /// [`Command::hide_possible_values`][crate::Command::hide_possible_values].
2361 ///
2362 /// # Examples
2363 ///
2364 /// ```rust
2365 /// # use clap_builder as clap;
2366 /// # use clap::{Command, Arg, ArgAction};
2367 /// let m = Command::new("prog")
2368 /// .arg(Arg::new("mode")
2369 /// .long("mode")
2370 /// .value_parser(["fast", "slow"])
2371 /// .action(ArgAction::Set)
2372 /// .hide_possible_values(true));
2373 /// ```
2374 /// If we were to run the above program with `--help` the `[values: fast, slow]` portion of
2375 /// the help text would be omitted.
2376 #[inline]
2377 #[must_use]
2378 pub fn hide_possible_values(self, yes: bool) -> Self {
2379 if yes {
2380 self.setting(ArgSettings::HidePossibleValues)
2381 } else {
2382 self.unset_setting(ArgSettings::HidePossibleValues)
2383 }
2384 }
2385
2386 /// Do not display the default value of the argument in the help message.
2387 ///
2388 /// This is useful when default behavior of an arg is explained elsewhere in the help text.
2389 ///
2390 /// **NOTE:** Setting this requires [taking values][Arg::num_args]
2391 ///
2392 /// # Examples
2393 ///
2394 /// ```rust
2395 /// # use clap_builder as clap;
2396 /// # use clap::{Command, Arg, ArgAction};
2397 /// let m = Command::new("connect")
2398 /// .arg(Arg::new("host")
2399 /// .long("host")
2400 /// .default_value("localhost")
2401 /// .action(ArgAction::Set)
2402 /// .hide_default_value(true));
2403 ///
2404 /// ```
2405 ///
2406 /// If we were to run the above program with `--help` the `[default: localhost]` portion of
2407 /// the help text would be omitted.
2408 #[inline]
2409 #[must_use]
2410 pub fn hide_default_value(self, yes: bool) -> Self {
2411 if yes {
2412 self.setting(ArgSettings::HideDefaultValue)
2413 } else {
2414 self.unset_setting(ArgSettings::HideDefaultValue)
2415 }
2416 }
2417
2418 /// Do not display in help the environment variable name.
2419 ///
2420 /// This is useful when the variable option is explained elsewhere in the help text.
2421 ///
2422 /// # Examples
2423 ///
2424 /// ```rust
2425 /// # use clap_builder as clap;
2426 /// # use clap::{Command, Arg, ArgAction};
2427 /// let m = Command::new("prog")
2428 /// .arg(Arg::new("mode")
2429 /// .long("mode")
2430 /// .env("MODE")
2431 /// .action(ArgAction::Set)
2432 /// .hide_env(true));
2433 /// ```
2434 ///
2435 /// If we were to run the above program with `--help` the `[env: MODE]` portion of the help
2436 /// text would be omitted.
2437 #[cfg(feature = "env")]
2438 #[inline]
2439 #[must_use]
2440 pub fn hide_env(self, yes: bool) -> Self {
2441 if yes {
2442 self.setting(ArgSettings::HideEnv)
2443 } else {
2444 self.unset_setting(ArgSettings::HideEnv)
2445 }
2446 }
2447
2448 /// Do not display in help any values inside the associated ENV variables for the argument.
2449 ///
2450 /// This is useful when ENV vars contain sensitive values.
2451 ///
2452 /// # Examples
2453 ///
2454 /// ```rust
2455 /// # use clap_builder as clap;
2456 /// # use clap::{Command, Arg, ArgAction};
2457 /// let m = Command::new("connect")
2458 /// .arg(Arg::new("host")
2459 /// .long("host")
2460 /// .env("CONNECT")
2461 /// .action(ArgAction::Set)
2462 /// .hide_env_values(true));
2463 ///
2464 /// ```
2465 ///
2466 /// If we were to run the above program with `$ CONNECT=super_secret connect --help` the
2467 /// `[default: CONNECT=super_secret]` portion of the help text would be omitted.
2468 #[cfg(feature = "env")]
2469 #[inline]
2470 #[must_use]
2471 pub fn hide_env_values(self, yes: bool) -> Self {
2472 if yes {
2473 self.setting(ArgSettings::HideEnvValues)
2474 } else {
2475 self.unset_setting(ArgSettings::HideEnvValues)
2476 }
2477 }
2478
2479 /// Hides an argument from short help (`-h`).
2480 ///
2481 /// **NOTE:** This does **not** hide the argument from usage strings on error
2482 ///
2483 /// **NOTE:** Setting this option will cause next-line-help output style to be used
2484 /// when long help (`--help`) is called.
2485 ///
2486 /// # Examples
2487 ///
2488 /// ```rust
2489 /// # use clap_builder as clap;
2490 /// # use clap::{Command, Arg};
2491 /// Arg::new("debug")
2492 /// .hide_short_help(true);
2493 /// ```
2494 ///
2495 /// Setting `hide_short_help(true)` will hide the argument when displaying short help text
2496 ///
2497 /// ```rust
2498 /// # #[cfg(feature = "help")] {
2499 /// # use clap_builder as clap;
2500 /// # use clap::{Command, Arg};
2501 /// let m = Command::new("prog")
2502 /// .arg(Arg::new("cfg")
2503 /// .long("config")
2504 /// .hide_short_help(true)
2505 /// .help("Some help text describing the --config arg"))
2506 /// .get_matches_from(vec![
2507 /// "prog", "-h"
2508 /// ]);
2509 /// # }
2510 /// ```
2511 ///
2512 /// The above example displays
2513 ///
2514 /// ```text
2515 /// helptest
2516 ///
2517 /// Usage: helptest [OPTIONS]
2518 ///
2519 /// Options:
2520 /// -h, --help Print help information
2521 /// -V, --version Print version information
2522 /// ```
2523 ///
2524 /// However, when --help is called
2525 ///
2526 /// ```rust
2527 /// # #[cfg(feature = "help")] {
2528 /// # use clap_builder as clap;
2529 /// # use clap::{Command, Arg};
2530 /// let m = Command::new("prog")
2531 /// .arg(Arg::new("cfg")
2532 /// .long("config")
2533 /// .hide_short_help(true)
2534 /// .help("Some help text describing the --config arg"))
2535 /// .get_matches_from(vec![
2536 /// "prog", "--help"
2537 /// ]);
2538 /// # }
2539 /// ```
2540 ///
2541 /// Then the following would be displayed
2542 ///
2543 /// ```text
2544 /// helptest
2545 ///
2546 /// Usage: helptest [OPTIONS]
2547 ///
2548 /// Options:
2549 /// --config Some help text describing the --config arg
2550 /// -h, --help Print help information
2551 /// -V, --version Print version information
2552 /// ```
2553 #[inline]
2554 #[must_use]
2555 pub fn hide_short_help(self, yes: bool) -> Self {
2556 if yes {
2557 self.setting(ArgSettings::HiddenShortHelp)
2558 } else {
2559 self.unset_setting(ArgSettings::HiddenShortHelp)
2560 }
2561 }
2562
2563 /// Hides an argument from long help (`--help`).
2564 ///
2565 /// **NOTE:** This does **not** hide the argument from usage strings on error
2566 ///
2567 /// **NOTE:** Setting this option will cause next-line-help output style to be used
2568 /// when long help (`--help`) is called.
2569 ///
2570 /// # Examples
2571 ///
2572 /// Setting `hide_long_help(true)` will hide the argument when displaying long help text
2573 ///
2574 /// ```rust
2575 /// # #[cfg(feature = "help")] {
2576 /// # use clap_builder as clap;
2577 /// # use clap::{Command, Arg};
2578 /// let m = Command::new("prog")
2579 /// .arg(Arg::new("cfg")
2580 /// .long("config")
2581 /// .hide_long_help(true)
2582 /// .help("Some help text describing the --config arg"))
2583 /// .get_matches_from(vec![
2584 /// "prog", "--help"
2585 /// ]);
2586 /// # }
2587 /// ```
2588 ///
2589 /// The above example displays
2590 ///
2591 /// ```text
2592 /// helptest
2593 ///
2594 /// Usage: helptest [OPTIONS]
2595 ///
2596 /// Options:
2597 /// -h, --help Print help information
2598 /// -V, --version Print version information
2599 /// ```
2600 ///
2601 /// However, when -h is called
2602 ///
2603 /// ```rust
2604 /// # #[cfg(feature = "help")] {
2605 /// # use clap_builder as clap;
2606 /// # use clap::{Command, Arg};
2607 /// let m = Command::new("prog")
2608 /// .arg(Arg::new("cfg")
2609 /// .long("config")
2610 /// .hide_long_help(true)
2611 /// .help("Some help text describing the --config arg"))
2612 /// .get_matches_from(vec![
2613 /// "prog", "-h"
2614 /// ]);
2615 /// # }
2616 /// ```
2617 ///
2618 /// Then the following would be displayed
2619 ///
2620 /// ```text
2621 /// helptest
2622 ///
2623 /// Usage: helptest [OPTIONS]
2624 ///
2625 /// OPTIONS:
2626 /// --config Some help text describing the --config arg
2627 /// -h, --help Print help information
2628 /// -V, --version Print version information
2629 /// ```
2630 #[inline]
2631 #[must_use]
2632 pub fn hide_long_help(self, yes: bool) -> Self {
2633 if yes {
2634 self.setting(ArgSettings::HiddenLongHelp)
2635 } else {
2636 self.unset_setting(ArgSettings::HiddenLongHelp)
2637 }
2638 }
2639}
2640
2641/// # Advanced Argument Relations
2642impl Arg {
2643 /// The name of the [`ArgGroup`] the argument belongs to.
2644 ///
2645 /// # Examples
2646 ///
2647 /// ```rust
2648 /// # use clap_builder as clap;
2649 /// # use clap::{Command, Arg, ArgAction};
2650 /// Arg::new("debug")
2651 /// .long("debug")
2652 /// .action(ArgAction::SetTrue)
2653 /// .group("mode")
2654 /// # ;
2655 /// ```
2656 ///
2657 /// Multiple arguments can be a member of a single group and then the group checked as if it
2658 /// was one of said arguments.
2659 ///
2660 /// ```rust
2661 /// # use clap_builder as clap;
2662 /// # use clap::{Command, Arg, ArgAction};
2663 /// let m = Command::new("prog")
2664 /// .arg(Arg::new("debug")
2665 /// .long("debug")
2666 /// .action(ArgAction::SetTrue)
2667 /// .group("mode"))
2668 /// .arg(Arg::new("verbose")
2669 /// .long("verbose")
2670 /// .action(ArgAction::SetTrue)
2671 /// .group("mode"))
2672 /// .get_matches_from(vec![
2673 /// "prog", "--debug"
2674 /// ]);
2675 /// assert!(m.contains_id("mode"));
2676 /// ```
2677 ///
2678 /// [`ArgGroup`]: crate::ArgGroup
2679 #[must_use]
2680 pub fn group(mut self, group_id: impl IntoResettable<Id>) -> Self {
2681 if let Some(group_id) = group_id.into_resettable().into_option() {
2682 self.groups.push(group_id);
2683 } else {
2684 self.groups.clear();
2685 }
2686 self
2687 }
2688
2689 /// The names of [`ArgGroup`]'s the argument belongs to.
2690 ///
2691 /// # Examples
2692 ///
2693 /// ```rust
2694 /// # use clap_builder as clap;
2695 /// # use clap::{Command, Arg, ArgAction};
2696 /// Arg::new("debug")
2697 /// .long("debug")
2698 /// .action(ArgAction::SetTrue)
2699 /// .groups(["mode", "verbosity"])
2700 /// # ;
2701 /// ```
2702 ///
2703 /// Arguments can be members of multiple groups and then the group checked as if it
2704 /// was one of said arguments.
2705 ///
2706 /// ```rust
2707 /// # use clap_builder as clap;
2708 /// # use clap::{Command, Arg, ArgAction};
2709 /// let m = Command::new("prog")
2710 /// .arg(Arg::new("debug")
2711 /// .long("debug")
2712 /// .action(ArgAction::SetTrue)
2713 /// .groups(["mode", "verbosity"]))
2714 /// .arg(Arg::new("verbose")
2715 /// .long("verbose")
2716 /// .action(ArgAction::SetTrue)
2717 /// .groups(["mode", "verbosity"]))
2718 /// .get_matches_from(vec![
2719 /// "prog", "--debug"
2720 /// ]);
2721 /// assert!(m.contains_id("mode"));
2722 /// assert!(m.contains_id("verbosity"));
2723 /// ```
2724 ///
2725 /// [`ArgGroup`]: crate::ArgGroup
2726 #[must_use]
2727 pub fn groups(mut self, group_ids: impl IntoIterator<Item = impl Into<Id>>) -> Self {
2728 self.groups.extend(group_ids.into_iter().map(Into::into));
2729 self
2730 }
2731
2732 /// Specifies the value of the argument if `arg` has been used at runtime.
2733 ///
2734 /// If `default` is set to `None`, `default_value` will be removed.
2735 ///
2736 /// **NOTE:** This setting is perfectly compatible with [`Arg::default_value`] but slightly
2737 /// different. `Arg::default_value` *only* takes effect when the user has not provided this arg
2738 /// at runtime. This setting however only takes effect when the user has not provided a value at
2739 /// runtime **and** these other conditions are met as well. If you have set `Arg::default_value`
2740 /// and `Arg::default_value_if`, and the user **did not** provide this arg at runtime, nor were
2741 /// the conditions met for `Arg::default_value_if`, the `Arg::default_value` will be applied.
2742 ///
2743 /// Like with command-line values, this will be split by [`Arg::value_delimiter`].
2744 ///
2745 /// # Examples
2746 ///
2747 /// First we use the default value only if another arg is present at runtime.
2748 ///
2749 /// ```rust
2750 /// # use clap_builder as clap;
2751 /// # use clap::{Command, Arg, ArgAction};
2752 /// # use clap::builder::{ArgPredicate};
2753 /// let m = Command::new("prog")
2754 /// .arg(Arg::new("flag")
2755 /// .long("flag")
2756 /// .action(ArgAction::SetTrue))
2757 /// .arg(Arg::new("other")
2758 /// .long("other")
2759 /// .default_value_if("flag", ArgPredicate::IsPresent, Some("default")))
2760 /// .get_matches_from(vec![
2761 /// "prog", "--flag"
2762 /// ]);
2763 ///
2764 /// assert_eq!(m.get_one::<String>("other").unwrap(), "default");
2765 /// ```
2766 ///
2767 /// Next we run the same test, but without providing `--flag`.
2768 ///
2769 /// ```rust
2770 /// # use clap_builder as clap;
2771 /// # use clap::{Command, Arg, ArgAction};
2772 /// let m = Command::new("prog")
2773 /// .arg(Arg::new("flag")
2774 /// .long("flag")
2775 /// .action(ArgAction::SetTrue))
2776 /// .arg(Arg::new("other")
2777 /// .long("other")
2778 /// .default_value_if("flag", "true", Some("default")))
2779 /// .get_matches_from(vec![
2780 /// "prog"
2781 /// ]);
2782 ///
2783 /// assert_eq!(m.get_one::<String>("other"), None);
2784 /// ```
2785 ///
2786 /// Now lets only use the default value if `--opt` contains the value `special`.
2787 ///
2788 /// ```rust
2789 /// # use clap_builder as clap;
2790 /// # use clap::{Command, Arg, ArgAction};
2791 /// let m = Command::new("prog")
2792 /// .arg(Arg::new("opt")
2793 /// .action(ArgAction::Set)
2794 /// .long("opt"))
2795 /// .arg(Arg::new("other")
2796 /// .long("other")
2797 /// .default_value_if("opt", "special", Some("default")))
2798 /// .get_matches_from(vec![
2799 /// "prog", "--opt", "special"
2800 /// ]);
2801 ///
2802 /// assert_eq!(m.get_one::<String>("other").unwrap(), "default");
2803 /// ```
2804 ///
2805 /// We can run the same test and provide any value *other than* `special` and we won't get a
2806 /// default value.
2807 ///
2808 /// ```rust
2809 /// # use clap_builder as clap;
2810 /// # use clap::{Command, Arg, ArgAction};
2811 /// let m = Command::new("prog")
2812 /// .arg(Arg::new("opt")
2813 /// .action(ArgAction::Set)
2814 /// .long("opt"))
2815 /// .arg(Arg::new("other")
2816 /// .long("other")
2817 /// .default_value_if("opt", "special", Some("default")))
2818 /// .get_matches_from(vec![
2819 /// "prog", "--opt", "hahaha"
2820 /// ]);
2821 ///
2822 /// assert_eq!(m.get_one::<String>("other"), None);
2823 /// ```
2824 ///
2825 /// If we want to unset the default value for an Arg based on the presence or
2826 /// value of some other Arg.
2827 ///
2828 /// ```rust
2829 /// # use clap_builder as clap;
2830 /// # use clap::{Command, Arg, ArgAction};
2831 /// let m = Command::new("prog")
2832 /// .arg(Arg::new("flag")
2833 /// .long("flag")
2834 /// .action(ArgAction::SetTrue))
2835 /// .arg(Arg::new("other")
2836 /// .long("other")
2837 /// .default_value("default")
2838 /// .default_value_if("flag", "true", None))
2839 /// .get_matches_from(vec![
2840 /// "prog", "--flag"
2841 /// ]);
2842 ///
2843 /// assert_eq!(m.get_one::<String>("other"), None);
2844 /// ```
2845 /// [`Arg::action(ArgAction::Set)`]: Arg::action()
2846 /// [`Arg::default_value`]: Arg::default_value()
2847 #[must_use]
2848 pub fn default_value_if(
2849 mut self,
2850 arg_id: impl Into<Id>,
2851 predicate: impl Into<ArgPredicate>,
2852 default: impl IntoResettable<OsStr>,
2853 ) -> Self {
2854 self.default_vals_ifs.push((
2855 arg_id.into(),
2856 predicate.into(),
2857 default.into_resettable().into_option(),
2858 ));
2859 self
2860 }
2861
2862 #[must_use]
2863 #[doc(hidden)]
2864 #[cfg_attr(
2865 feature = "deprecated",
2866 deprecated(since = "4.0.0", note = "Replaced with `Arg::default_value_if`")
2867 )]
2868 pub fn default_value_if_os(
2869 self,
2870 arg_id: impl Into<Id>,
2871 predicate: impl Into<ArgPredicate>,
2872 default: impl IntoResettable<OsStr>,
2873 ) -> Self {
2874 self.default_value_if(arg_id, predicate, default)
2875 }
2876
2877 /// Specifies multiple values and conditions in the same manner as [`Arg::default_value_if`].
2878 ///
2879 /// The method takes a slice of tuples in the `(arg, predicate, default)` format.
2880 ///
2881 /// **NOTE**: The conditions are stored in order and evaluated in the same order. I.e. the first
2882 /// if multiple conditions are true, the first one found will be applied and the ultimate value.
2883 ///
2884 /// Like with command-line values, this will be split by [`Arg::value_delimiter`].
2885 ///
2886 /// # Examples
2887 ///
2888 /// First we use the default value only if another arg is present at runtime.
2889 ///
2890 /// ```rust
2891 /// # use clap_builder as clap;
2892 /// # use clap::{Command, Arg, ArgAction};
2893 /// let m = Command::new("prog")
2894 /// .arg(Arg::new("flag")
2895 /// .long("flag")
2896 /// .action(ArgAction::SetTrue))
2897 /// .arg(Arg::new("opt")
2898 /// .long("opt")
2899 /// .action(ArgAction::Set))
2900 /// .arg(Arg::new("other")
2901 /// .long("other")
2902 /// .default_value_ifs([
2903 /// ("flag", "true", Some("default")),
2904 /// ("opt", "channal", Some("chan")),
2905 /// ]))
2906 /// .get_matches_from(vec![
2907 /// "prog", "--opt", "channal"
2908 /// ]);
2909 ///
2910 /// assert_eq!(m.get_one::<String>("other").unwrap(), "chan");
2911 /// ```
2912 ///
2913 /// Next we run the same test, but without providing `--flag`.
2914 ///
2915 /// ```rust
2916 /// # use clap_builder as clap;
2917 /// # use clap::{Command, Arg, ArgAction};
2918 /// let m = Command::new("prog")
2919 /// .arg(Arg::new("flag")
2920 /// .long("flag")
2921 /// .action(ArgAction::SetTrue))
2922 /// .arg(Arg::new("other")
2923 /// .long("other")
2924 /// .default_value_ifs([
2925 /// ("flag", "true", Some("default")),
2926 /// ("opt", "channal", Some("chan")),
2927 /// ]))
2928 /// .get_matches_from(vec![
2929 /// "prog"
2930 /// ]);
2931 ///
2932 /// assert_eq!(m.get_one::<String>("other"), None);
2933 /// ```
2934 ///
2935 /// We can also see that these values are applied in order, and if more than one condition is
2936 /// true, only the first evaluated "wins"
2937 ///
2938 /// ```rust
2939 /// # use clap_builder as clap;
2940 /// # use clap::{Command, Arg, ArgAction};
2941 /// # use clap::builder::ArgPredicate;
2942 /// let m = Command::new("prog")
2943 /// .arg(Arg::new("flag")
2944 /// .long("flag")
2945 /// .action(ArgAction::SetTrue))
2946 /// .arg(Arg::new("opt")
2947 /// .long("opt")
2948 /// .action(ArgAction::Set))
2949 /// .arg(Arg::new("other")
2950 /// .long("other")
2951 /// .default_value_ifs([
2952 /// ("flag", ArgPredicate::IsPresent, Some("default")),
2953 /// ("opt", ArgPredicate::Equals("channal".into()), Some("chan")),
2954 /// ]))
2955 /// .get_matches_from(vec![
2956 /// "prog", "--opt", "channal", "--flag"
2957 /// ]);
2958 ///
2959 /// assert_eq!(m.get_one::<String>("other").unwrap(), "default");
2960 /// ```
2961 /// [`Arg::action(ArgAction::Set)`]: Arg::action()
2962 /// [`Arg::default_value_if`]: Arg::default_value_if()
2963 #[must_use]
2964 pub fn default_value_ifs(
2965 mut self,
2966 ifs: impl IntoIterator<
2967 Item = (
2968 impl Into<Id>,
2969 impl Into<ArgPredicate>,
2970 impl IntoResettable<OsStr>,
2971 ),
2972 >,
2973 ) -> Self {
2974 for (arg, predicate, default) in ifs {
2975 self = self.default_value_if(arg, predicate, default);
2976 }
2977 self
2978 }
2979
2980 #[must_use]
2981 #[doc(hidden)]
2982 #[cfg_attr(
2983 feature = "deprecated",
2984 deprecated(since = "4.0.0", note = "Replaced with `Arg::default_value_ifs`")
2985 )]
2986 pub fn default_value_ifs_os(
2987 self,
2988 ifs: impl IntoIterator<
2989 Item = (
2990 impl Into<Id>,
2991 impl Into<ArgPredicate>,
2992 impl IntoResettable<OsStr>,
2993 ),
2994 >,
2995 ) -> Self {
2996 self.default_value_ifs(ifs)
2997 }
2998
2999 /// Set this arg as [required] as long as the specified argument is not present at runtime.
3000 ///
3001 /// **Pro Tip:** Using `Arg::required_unless_present` implies [`Arg::required`] and is therefore not
3002 /// mandatory to also set.
3003 ///
3004 /// # Examples
3005 ///
3006 /// ```rust
3007 /// # use clap_builder as clap;
3008 /// # use clap::Arg;
3009 /// Arg::new("config")
3010 /// .required_unless_present("debug")
3011 /// # ;
3012 /// ```
3013 ///
3014 /// In the following example, the required argument is *not* provided,
3015 /// but it's not an error because the `unless` arg has been supplied.
3016 ///
3017 /// ```rust
3018 /// # use clap_builder as clap;
3019 /// # use clap::{Command, Arg, ArgAction};
3020 /// let res = Command::new("prog")
3021 /// .arg(Arg::new("cfg")
3022 /// .required_unless_present("dbg")
3023 /// .action(ArgAction::Set)
3024 /// .long("config"))
3025 /// .arg(Arg::new("dbg")
3026 /// .long("debug")
3027 /// .action(ArgAction::SetTrue))
3028 /// .try_get_matches_from(vec![
3029 /// "prog", "--debug"
3030 /// ]);
3031 ///
3032 /// assert!(res.is_ok());
3033 /// ```
3034 ///
3035 /// Setting `Arg::required_unless_present(name)` and *not* supplying `name` or this arg is an error.
3036 ///
3037 /// ```rust
3038 /// # use clap_builder as clap;
3039 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction};
3040 /// let res = Command::new("prog")
3041 /// .arg(Arg::new("cfg")
3042 /// .required_unless_present("dbg")
3043 /// .action(ArgAction::Set)
3044 /// .long("config"))
3045 /// .arg(Arg::new("dbg")
3046 /// .long("debug"))
3047 /// .try_get_matches_from(vec![
3048 /// "prog"
3049 /// ]);
3050 ///
3051 /// assert!(res.is_err());
3052 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
3053 /// ```
3054 /// [required]: Arg::required()
3055 #[must_use]
3056 pub fn required_unless_present(mut self, arg_id: impl IntoResettable<Id>) -> Self {
3057 if let Some(arg_id) = arg_id.into_resettable().into_option() {
3058 self.r_unless.push(arg_id);
3059 } else {
3060 self.r_unless.clear();
3061 }
3062 self
3063 }
3064
3065 /// Sets this arg as [required] unless *all* of the specified arguments are present at runtime.
3066 ///
3067 /// In other words, parsing will succeed only if user either
3068 /// * supplies the `self` arg.
3069 /// * supplies *all* of the `names` arguments.
3070 ///
3071 /// **NOTE:** If you wish for this argument to only be required unless *any of* these args are
3072 /// present see [`Arg::required_unless_present_any`]
3073 ///
3074 /// # Examples
3075 ///
3076 /// ```rust
3077 /// # use clap_builder as clap;
3078 /// # use clap::Arg;
3079 /// Arg::new("config")
3080 /// .required_unless_present_all(["cfg", "dbg"])
3081 /// # ;
3082 /// ```
3083 ///
3084 /// In the following example, the required argument is *not* provided, but it's not an error
3085 /// because *all* of the `names` args have been supplied.
3086 ///
3087 /// ```rust
3088 /// # use clap_builder as clap;
3089 /// # use clap::{Command, Arg, ArgAction};
3090 /// let res = Command::new("prog")
3091 /// .arg(Arg::new("cfg")
3092 /// .required_unless_present_all(["dbg", "infile"])
3093 /// .action(ArgAction::Set)
3094 /// .long("config"))
3095 /// .arg(Arg::new("dbg")
3096 /// .long("debug")
3097 /// .action(ArgAction::SetTrue))
3098 /// .arg(Arg::new("infile")
3099 /// .short('i')
3100 /// .action(ArgAction::Set))
3101 /// .try_get_matches_from(vec![
3102 /// "prog", "--debug", "-i", "file"
3103 /// ]);
3104 ///
3105 /// assert!(res.is_ok());
3106 /// ```
3107 ///
3108 /// Setting [`Arg::required_unless_present_all(names)`] and *not* supplying
3109 /// either *all* of `unless` args or the `self` arg is an error.
3110 ///
3111 /// ```rust
3112 /// # use clap_builder as clap;
3113 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction};
3114 /// let res = Command::new("prog")
3115 /// .arg(Arg::new("cfg")
3116 /// .required_unless_present_all(["dbg", "infile"])
3117 /// .action(ArgAction::Set)
3118 /// .long("config"))
3119 /// .arg(Arg::new("dbg")
3120 /// .long("debug")
3121 /// .action(ArgAction::SetTrue))
3122 /// .arg(Arg::new("infile")
3123 /// .short('i')
3124 /// .action(ArgAction::Set))
3125 /// .try_get_matches_from(vec![
3126 /// "prog"
3127 /// ]);
3128 ///
3129 /// assert!(res.is_err());
3130 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
3131 /// ```
3132 /// [required]: Arg::required()
3133 /// [`Arg::required_unless_present_any`]: Arg::required_unless_present_any()
3134 /// [`Arg::required_unless_present_all(names)`]: Arg::required_unless_present_all()
3135 #[must_use]
3136 pub fn required_unless_present_all(
3137 mut self,
3138 names: impl IntoIterator<Item = impl Into<Id>>,
3139 ) -> Self {
3140 self.r_unless_all.extend(names.into_iter().map(Into::into));
3141 self
3142 }
3143
3144 /// Sets this arg as [required] unless *any* of the specified arguments are present at runtime.
3145 ///
3146 /// In other words, parsing will succeed only if user either
3147 /// * supplies the `self` arg.
3148 /// * supplies *one or more* of the `unless` arguments.
3149 ///
3150 /// **NOTE:** If you wish for this argument to be required unless *all of* these args are
3151 /// present see [`Arg::required_unless_present_all`]
3152 ///
3153 /// # Examples
3154 ///
3155 /// ```rust
3156 /// # use clap_builder as clap;
3157 /// # use clap::Arg;
3158 /// Arg::new("config")
3159 /// .required_unless_present_any(["cfg", "dbg"])
3160 /// # ;
3161 /// ```
3162 ///
3163 /// Setting [`Arg::required_unless_present_any(names)`] requires that the argument be used at runtime
3164 /// *unless* *at least one of* the args in `names` are present. In the following example, the
3165 /// required argument is *not* provided, but it's not an error because one the `unless` args
3166 /// have been supplied.
3167 ///
3168 /// ```rust
3169 /// # use clap_builder as clap;
3170 /// # use clap::{Command, Arg, ArgAction};
3171 /// let res = Command::new("prog")
3172 /// .arg(Arg::new("cfg")
3173 /// .required_unless_present_any(["dbg", "infile"])
3174 /// .action(ArgAction::Set)
3175 /// .long("config"))
3176 /// .arg(Arg::new("dbg")
3177 /// .long("debug")
3178 /// .action(ArgAction::SetTrue))
3179 /// .arg(Arg::new("infile")
3180 /// .short('i')
3181 /// .action(ArgAction::Set))
3182 /// .try_get_matches_from(vec![
3183 /// "prog", "--debug"
3184 /// ]);
3185 ///
3186 /// assert!(res.is_ok());
3187 /// ```
3188 ///
3189 /// Setting [`Arg::required_unless_present_any(names)`] and *not* supplying *at least one of* `names`
3190 /// or this arg is an error.
3191 ///
3192 /// ```rust
3193 /// # use clap_builder as clap;
3194 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction};
3195 /// let res = Command::new("prog")
3196 /// .arg(Arg::new("cfg")
3197 /// .required_unless_present_any(["dbg", "infile"])
3198 /// .action(ArgAction::Set)
3199 /// .long("config"))
3200 /// .arg(Arg::new("dbg")
3201 /// .long("debug")
3202 /// .action(ArgAction::SetTrue))
3203 /// .arg(Arg::new("infile")
3204 /// .short('i')
3205 /// .action(ArgAction::Set))
3206 /// .try_get_matches_from(vec![
3207 /// "prog"
3208 /// ]);
3209 ///
3210 /// assert!(res.is_err());
3211 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
3212 /// ```
3213 /// [required]: Arg::required()
3214 /// [`Arg::required_unless_present_any(names)`]: Arg::required_unless_present_any()
3215 /// [`Arg::required_unless_present_all`]: Arg::required_unless_present_all()
3216 #[must_use]
3217 pub fn required_unless_present_any(
3218 mut self,
3219 names: impl IntoIterator<Item = impl Into<Id>>,
3220 ) -> Self {
3221 self.r_unless.extend(names.into_iter().map(Into::into));
3222 self
3223 }
3224
3225 /// This argument is [required] only if the specified `arg` is present at runtime and its value
3226 /// equals `val`.
3227 ///
3228 /// # Examples
3229 ///
3230 /// ```rust
3231 /// # use clap_builder as clap;
3232 /// # use clap::Arg;
3233 /// Arg::new("config")
3234 /// .required_if_eq("other_arg", "value")
3235 /// # ;
3236 /// ```
3237 ///
3238 /// ```rust
3239 /// # use clap_builder as clap;
3240 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction};
3241 /// let res = Command::new("prog")
3242 /// .arg(Arg::new("cfg")
3243 /// .action(ArgAction::Set)
3244 /// .required_if_eq("other", "special")
3245 /// .long("config"))
3246 /// .arg(Arg::new("other")
3247 /// .long("other")
3248 /// .action(ArgAction::Set))
3249 /// .try_get_matches_from(vec![
3250 /// "prog", "--other", "not-special"
3251 /// ]);
3252 ///
3253 /// assert!(res.is_ok()); // We didn't use --other=special, so "cfg" wasn't required
3254 ///
3255 /// let res = Command::new("prog")
3256 /// .arg(Arg::new("cfg")
3257 /// .action(ArgAction::Set)
3258 /// .required_if_eq("other", "special")
3259 /// .long("config"))
3260 /// .arg(Arg::new("other")
3261 /// .long("other")
3262 /// .action(ArgAction::Set))
3263 /// .try_get_matches_from(vec![
3264 /// "prog", "--other", "special"
3265 /// ]);
3266 ///
3267 /// // We did use --other=special so "cfg" had become required but was missing.
3268 /// assert!(res.is_err());
3269 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
3270 ///
3271 /// let res = Command::new("prog")
3272 /// .arg(Arg::new("cfg")
3273 /// .action(ArgAction::Set)
3274 /// .required_if_eq("other", "special")
3275 /// .long("config"))
3276 /// .arg(Arg::new("other")
3277 /// .long("other")
3278 /// .action(ArgAction::Set))
3279 /// .try_get_matches_from(vec![
3280 /// "prog", "--other", "SPECIAL"
3281 /// ]);
3282 ///
3283 /// // By default, the comparison is case-sensitive, so "cfg" wasn't required
3284 /// assert!(res.is_ok());
3285 ///
3286 /// let res = Command::new("prog")
3287 /// .arg(Arg::new("cfg")
3288 /// .action(ArgAction::Set)
3289 /// .required_if_eq("other", "special")
3290 /// .long("config"))
3291 /// .arg(Arg::new("other")
3292 /// .long("other")
3293 /// .ignore_case(true)
3294 /// .action(ArgAction::Set))
3295 /// .try_get_matches_from(vec![
3296 /// "prog", "--other", "SPECIAL"
3297 /// ]);
3298 ///
3299 /// // However, case-insensitive comparisons can be enabled. This typically occurs when using Arg::possible_values().
3300 /// assert!(res.is_err());
3301 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
3302 /// ```
3303 /// [`Arg::requires(name)`]: Arg::requires()
3304 /// [Conflicting]: Arg::conflicts_with()
3305 /// [required]: Arg::required()
3306 #[must_use]
3307 pub fn required_if_eq(mut self, arg_id: impl Into<Id>, val: impl Into<OsStr>) -> Self {
3308 self.r_ifs.push((arg_id.into(), val.into()));
3309 self
3310 }
3311
3312 /// Specify this argument is [required] based on multiple conditions.
3313 ///
3314 /// The conditions are set up in a `(arg, val)` style tuple. The requirement will only become
3315 /// valid if one of the specified `arg`'s value equals its corresponding `val`.
3316 ///
3317 /// # Examples
3318 ///
3319 /// ```rust
3320 /// # use clap_builder as clap;
3321 /// # use clap::Arg;
3322 /// Arg::new("config")
3323 /// .required_if_eq_any([
3324 /// ("extra", "val"),
3325 /// ("option", "spec")
3326 /// ])
3327 /// # ;
3328 /// ```
3329 ///
3330 /// Setting `Arg::required_if_eq_any([(arg, val)])` makes this arg required if any of the `arg`s
3331 /// are used at runtime and it's corresponding value is equal to `val`. If the `arg`'s value is
3332 /// anything other than `val`, this argument isn't required.
3333 ///
3334 /// ```rust
3335 /// # use clap_builder as clap;
3336 /// # use clap::{Command, Arg, ArgAction};
3337 /// let res = Command::new("prog")
3338 /// .arg(Arg::new("cfg")
3339 /// .required_if_eq_any([
3340 /// ("extra", "val"),
3341 /// ("option", "spec")
3342 /// ])
3343 /// .action(ArgAction::Set)
3344 /// .long("config"))
3345 /// .arg(Arg::new("extra")
3346 /// .action(ArgAction::Set)
3347 /// .long("extra"))
3348 /// .arg(Arg::new("option")
3349 /// .action(ArgAction::Set)
3350 /// .long("option"))
3351 /// .try_get_matches_from(vec![
3352 /// "prog", "--option", "other"
3353 /// ]);
3354 ///
3355 /// assert!(res.is_ok()); // We didn't use --option=spec, or --extra=val so "cfg" isn't required
3356 /// ```
3357 ///
3358 /// Setting `Arg::required_if_eq_any([(arg, val)])` and having any of the `arg`s used with its
3359 /// value of `val` but *not* using this arg is an error.
3360 ///
3361 /// ```rust
3362 /// # use clap_builder as clap;
3363 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction};
3364 /// let res = Command::new("prog")
3365 /// .arg(Arg::new("cfg")
3366 /// .required_if_eq_any([
3367 /// ("extra", "val"),
3368 /// ("option", "spec")
3369 /// ])
3370 /// .action(ArgAction::Set)
3371 /// .long("config"))
3372 /// .arg(Arg::new("extra")
3373 /// .action(ArgAction::Set)
3374 /// .long("extra"))
3375 /// .arg(Arg::new("option")
3376 /// .action(ArgAction::Set)
3377 /// .long("option"))
3378 /// .try_get_matches_from(vec![
3379 /// "prog", "--option", "spec"
3380 /// ]);
3381 ///
3382 /// assert!(res.is_err());
3383 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
3384 /// ```
3385 /// [`Arg::requires(name)`]: Arg::requires()
3386 /// [Conflicting]: Arg::conflicts_with()
3387 /// [required]: Arg::required()
3388 #[must_use]
3389 pub fn required_if_eq_any(
3390 mut self,
3391 ifs: impl IntoIterator<Item = (impl Into<Id>, impl Into<OsStr>)>,
3392 ) -> Self {
3393 self.r_ifs
3394 .extend(ifs.into_iter().map(|(id, val)| (id.into(), val.into())));
3395 self
3396 }
3397
3398 /// Specify this argument is [required] based on multiple conditions.
3399 ///
3400 /// The conditions are set up in a `(arg, val)` style tuple. The requirement will only become
3401 /// valid if every one of the specified `arg`'s value equals its corresponding `val`.
3402 ///
3403 /// # Examples
3404 ///
3405 /// ```rust
3406 /// # use clap_builder as clap;
3407 /// # use clap::Arg;
3408 /// Arg::new("config")
3409 /// .required_if_eq_all([
3410 /// ("extra", "val"),
3411 /// ("option", "spec")
3412 /// ])
3413 /// # ;
3414 /// ```
3415 ///
3416 /// Setting `Arg::required_if_eq_all([(arg, val)])` makes this arg required if all of the `arg`s
3417 /// are used at runtime and every value is equal to its corresponding `val`. If the `arg`'s value is
3418 /// anything other than `val`, this argument isn't required.
3419 ///
3420 /// ```rust
3421 /// # use clap_builder as clap;
3422 /// # use clap::{Command, Arg, ArgAction};
3423 /// let res = Command::new("prog")
3424 /// .arg(Arg::new("cfg")
3425 /// .required_if_eq_all([
3426 /// ("extra", "val"),
3427 /// ("option", "spec")
3428 /// ])
3429 /// .action(ArgAction::Set)
3430 /// .long("config"))
3431 /// .arg(Arg::new("extra")
3432 /// .action(ArgAction::Set)
3433 /// .long("extra"))
3434 /// .arg(Arg::new("option")
3435 /// .action(ArgAction::Set)
3436 /// .long("option"))
3437 /// .try_get_matches_from(vec![
3438 /// "prog", "--option", "spec"
3439 /// ]);
3440 ///
3441 /// assert!(res.is_ok()); // We didn't use --option=spec --extra=val so "cfg" isn't required
3442 /// ```
3443 ///
3444 /// Setting `Arg::required_if_eq_all([(arg, val)])` and having all of the `arg`s used with its
3445 /// value of `val` but *not* using this arg is an error.
3446 ///
3447 /// ```rust
3448 /// # use clap_builder as clap;
3449 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction};
3450 /// let res = Command::new("prog")
3451 /// .arg(Arg::new("cfg")
3452 /// .required_if_eq_all([
3453 /// ("extra", "val"),
3454 /// ("option", "spec")
3455 /// ])
3456 /// .action(ArgAction::Set)
3457 /// .long("config"))
3458 /// .arg(Arg::new("extra")
3459 /// .action(ArgAction::Set)
3460 /// .long("extra"))
3461 /// .arg(Arg::new("option")
3462 /// .action(ArgAction::Set)
3463 /// .long("option"))
3464 /// .try_get_matches_from(vec![
3465 /// "prog", "--extra", "val", "--option", "spec"
3466 /// ]);
3467 ///
3468 /// assert!(res.is_err());
3469 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
3470 /// ```
3471 /// [required]: Arg::required()
3472 #[must_use]
3473 pub fn required_if_eq_all(
3474 mut self,
3475 ifs: impl IntoIterator<Item = (impl Into<Id>, impl Into<OsStr>)>,
3476 ) -> Self {
3477 self.r_ifs_all
3478 .extend(ifs.into_iter().map(|(id, val)| (id.into(), val.into())));
3479 self
3480 }
3481
3482 /// Require another argument if this arg matches the [`ArgPredicate`]
3483 ///
3484 /// This method takes `value, another_arg` pair. At runtime, clap will check
3485 /// if this arg (`self`) matches the [`ArgPredicate`].
3486 /// If it does, `another_arg` will be marked as required.
3487 ///
3488 /// # Examples
3489 ///
3490 /// ```rust
3491 /// # use clap_builder as clap;
3492 /// # use clap::Arg;
3493 /// Arg::new("config")
3494 /// .requires_if("val", "arg")
3495 /// # ;
3496 /// ```
3497 ///
3498 /// Setting `Arg::requires_if(val, arg)` requires that the `arg` be used at runtime if the
3499 /// defining argument's value is equal to `val`. If the defining argument is anything other than
3500 /// `val`, the other argument isn't required.
3501 ///
3502 /// ```rust
3503 /// # use clap_builder as clap;
3504 /// # use clap::{Command, Arg, ArgAction};
3505 /// let res = Command::new("prog")
3506 /// .arg(Arg::new("cfg")
3507 /// .action(ArgAction::Set)
3508 /// .requires_if("my.cfg", "other")
3509 /// .long("config"))
3510 /// .arg(Arg::new("other"))
3511 /// .try_get_matches_from(vec![
3512 /// "prog", "--config", "some.cfg"
3513 /// ]);
3514 ///
3515 /// assert!(res.is_ok()); // We didn't use --config=my.cfg, so other wasn't required
3516 /// ```
3517 ///
3518 /// Setting `Arg::requires_if(val, arg)` and setting the value to `val` but *not* supplying
3519 /// `arg` is an error.
3520 ///
3521 /// ```rust
3522 /// # use clap_builder as clap;
3523 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction};
3524 /// let res = Command::new("prog")
3525 /// .arg(Arg::new("cfg")
3526 /// .action(ArgAction::Set)
3527 /// .requires_if("my.cfg", "input")
3528 /// .long("config"))
3529 /// .arg(Arg::new("input"))
3530 /// .try_get_matches_from(vec![
3531 /// "prog", "--config", "my.cfg"
3532 /// ]);
3533 ///
3534 /// assert!(res.is_err());
3535 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
3536 /// ```
3537 /// [`Arg::requires(name)`]: Arg::requires()
3538 /// [Conflicting]: Arg::conflicts_with()
3539 /// [override]: Arg::overrides_with()
3540 #[must_use]
3541 pub fn requires_if(mut self, val: impl Into<ArgPredicate>, arg_id: impl Into<Id>) -> Self {
3542 self.requires.push((val.into(), arg_id.into()));
3543 self
3544 }
3545
3546 /// Allows multiple conditional requirements.
3547 ///
3548 /// The requirement will only become valid if this arg's value matches the
3549 /// [`ArgPredicate`].
3550 ///
3551 /// # Examples
3552 ///
3553 /// ```rust
3554 /// # use clap_builder as clap;
3555 /// # use clap::Arg;
3556 /// Arg::new("config")
3557 /// .requires_ifs([
3558 /// ("val", "arg"),
3559 /// ("other_val", "arg2"),
3560 /// ])
3561 /// # ;
3562 /// ```
3563 ///
3564 /// Setting `Arg::requires_ifs(["val", "arg"])` requires that the `arg` be used at runtime if the
3565 /// defining argument's value is equal to `val`. If the defining argument's value is anything other
3566 /// than `val`, `arg` isn't required.
3567 ///
3568 /// ```rust
3569 /// # use clap_builder as clap;
3570 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction};
3571 /// let res = Command::new("prog")
3572 /// .arg(Arg::new("cfg")
3573 /// .action(ArgAction::Set)
3574 /// .requires_ifs([
3575 /// ("special.conf", "opt"),
3576 /// ("other.conf", "other"),
3577 /// ])
3578 /// .long("config"))
3579 /// .arg(Arg::new("opt")
3580 /// .long("option")
3581 /// .action(ArgAction::Set))
3582 /// .arg(Arg::new("other"))
3583 /// .try_get_matches_from(vec![
3584 /// "prog", "--config", "special.conf"
3585 /// ]);
3586 ///
3587 /// assert!(res.is_err()); // We used --config=special.conf so --option <val> is required
3588 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
3589 /// ```
3590 ///
3591 /// Setting `Arg::requires_ifs` with [`ArgPredicate::IsPresent`] and *not* supplying all the
3592 /// arguments is an error.
3593 ///
3594 /// ```rust
3595 /// # use clap_builder as clap;
3596 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction, builder::ArgPredicate};
3597 /// let res = Command::new("prog")
3598 /// .arg(Arg::new("cfg")
3599 /// .action(ArgAction::Set)
3600 /// .requires_ifs([
3601 /// (ArgPredicate::IsPresent, "input"),
3602 /// (ArgPredicate::IsPresent, "output"),
3603 /// ])
3604 /// .long("config"))
3605 /// .arg(Arg::new("input"))
3606 /// .arg(Arg::new("output"))
3607 /// .try_get_matches_from(vec![
3608 /// "prog", "--config", "file.conf", "in.txt"
3609 /// ]);
3610 ///
3611 /// assert!(res.is_err());
3612 /// // We didn't use output
3613 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
3614 /// ```
3615 ///
3616 /// [`Arg::requires(name)`]: Arg::requires()
3617 /// [Conflicting]: Arg::conflicts_with()
3618 /// [override]: Arg::overrides_with()
3619 #[must_use]
3620 pub fn requires_ifs(
3621 mut self,
3622 ifs: impl IntoIterator<Item = (impl Into<ArgPredicate>, impl Into<Id>)>,
3623 ) -> Self {
3624 self.requires
3625 .extend(ifs.into_iter().map(|(val, arg)| (val.into(), arg.into())));
3626 self
3627 }
3628
3629 #[doc(hidden)]
3630 #[cfg_attr(
3631 feature = "deprecated",
3632 deprecated(since = "4.0.0", note = "Replaced with `Arg::requires_ifs`")
3633 )]
3634 pub fn requires_all(self, ids: impl IntoIterator<Item = impl Into<Id>>) -> Self {
3635 self.requires_ifs(ids.into_iter().map(|id| (ArgPredicate::IsPresent, id)))
3636 }
3637
3638 /// This argument is mutually exclusive with the specified argument.
3639 ///
3640 /// **NOTE:** Conflicting rules take precedence over being required by default. Conflict rules
3641 /// only need to be set for one of the two arguments, they do not need to be set for each.
3642 ///
3643 /// **NOTE:** Defining a conflict is two-way, but does *not* need to defined for both arguments
3644 /// (i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not
3645 /// need to also do B.conflicts_with(A))
3646 ///
3647 /// **NOTE:** [`Arg::conflicts_with_all(names)`] allows specifying an argument which conflicts with more than one argument.
3648 ///
3649 /// **NOTE** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument.
3650 ///
3651 /// **NOTE:** All arguments implicitly conflict with themselves.
3652 ///
3653 /// # Examples
3654 ///
3655 /// ```rust
3656 /// # use clap_builder as clap;
3657 /// # use clap::Arg;
3658 /// Arg::new("config")
3659 /// .conflicts_with("debug")
3660 /// # ;
3661 /// ```
3662 ///
3663 /// Setting conflicting argument, and having both arguments present at runtime is an error.
3664 ///
3665 /// ```rust
3666 /// # use clap_builder as clap;
3667 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction};
3668 /// let res = Command::new("prog")
3669 /// .arg(Arg::new("cfg")
3670 /// .action(ArgAction::Set)
3671 /// .conflicts_with("debug")
3672 /// .long("config"))
3673 /// .arg(Arg::new("debug")
3674 /// .long("debug")
3675 /// .action(ArgAction::SetTrue))
3676 /// .try_get_matches_from(vec![
3677 /// "prog", "--debug", "--config", "file.conf"
3678 /// ]);
3679 ///
3680 /// assert!(res.is_err());
3681 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::ArgumentConflict);
3682 /// ```
3683 ///
3684 /// [`Arg::conflicts_with_all(names)`]: Arg::conflicts_with_all()
3685 /// [`Arg::exclusive(true)`]: Arg::exclusive()
3686 #[must_use]
3687 pub fn conflicts_with(mut self, arg_id: impl IntoResettable<Id>) -> Self {
3688 if let Some(arg_id) = arg_id.into_resettable().into_option() {
3689 self.blacklist.push(arg_id);
3690 } else {
3691 self.blacklist.clear();
3692 }
3693 self
3694 }
3695
3696 /// This argument is mutually exclusive with the specified arguments.
3697 ///
3698 /// See [`Arg::conflicts_with`].
3699 ///
3700 /// **NOTE:** Conflicting rules take precedence over being required by default. Conflict rules
3701 /// only need to be set for one of the two arguments, they do not need to be set for each.
3702 ///
3703 /// **NOTE:** Defining a conflict is two-way, but does *not* need to defined for both arguments
3704 /// (i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not need
3705 /// need to also do B.conflicts_with(A))
3706 ///
3707 /// **NOTE:** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument.
3708 ///
3709 /// # Examples
3710 ///
3711 /// ```rust
3712 /// # use clap_builder as clap;
3713 /// # use clap::Arg;
3714 /// Arg::new("config")
3715 /// .conflicts_with_all(["debug", "input"])
3716 /// # ;
3717 /// ```
3718 ///
3719 /// Setting conflicting argument, and having any of the arguments present at runtime with a
3720 /// conflicting argument is an error.
3721 ///
3722 /// ```rust
3723 /// # use clap_builder as clap;
3724 /// # use clap::{Command, Arg, error::ErrorKind, ArgAction};
3725 /// let res = Command::new("prog")
3726 /// .arg(Arg::new("cfg")
3727 /// .action(ArgAction::Set)
3728 /// .conflicts_with_all(["debug", "input"])
3729 /// .long("config"))
3730 /// .arg(Arg::new("debug")
3731 /// .long("debug"))
3732 /// .arg(Arg::new("input"))
3733 /// .try_get_matches_from(vec![
3734 /// "prog", "--config", "file.conf", "file.txt"
3735 /// ]);
3736 ///
3737 /// assert!(res.is_err());
3738 /// assert_eq!(res.unwrap_err().kind(), ErrorKind::ArgumentConflict);
3739 /// ```
3740 /// [`Arg::conflicts_with`]: Arg::conflicts_with()
3741 /// [`Arg::exclusive(true)`]: Arg::exclusive()
3742 #[must_use]
3743 pub fn conflicts_with_all(mut self, names: impl IntoIterator<Item = impl Into<Id>>) -> Self {
3744 self.blacklist.extend(names.into_iter().map(Into::into));
3745 self
3746 }
3747
3748 /// Sets an overridable argument.
3749 ///
3750 /// i.e. this argument and the following argument
3751 /// will override each other in POSIX style (whichever argument was specified at runtime
3752 /// **last** "wins")
3753 ///
3754 /// **NOTE:** When an argument is overridden it is essentially as if it never was used, any
3755 /// conflicts, requirements, etc. are evaluated **after** all "overrides" have been removed
3756 ///
3757 /// **NOTE:** Overriding an argument implies they [conflict][Arg::conflicts_with`].
3758 ///
3759 /// # Examples
3760 ///
3761 /// ```rust
3762 /// # use clap_builder as clap;
3763 /// # use clap::{Command, arg};
3764 /// let m = Command::new("prog")
3765 /// .arg(arg!(-f --flag "some flag")
3766 /// .conflicts_with("debug"))
3767 /// .arg(arg!(-d --debug "other flag"))
3768 /// .arg(arg!(-c --color "third flag")
3769 /// .overrides_with("flag"))
3770 /// .get_matches_from(vec![
3771 /// "prog", "-f", "-d", "-c"]);
3772 /// // ^~~~~~~~~~~~^~~~~ flag is overridden by color
3773 ///
3774 /// assert!(m.get_flag("color"));
3775 /// assert!(m.get_flag("debug")); // even though flag conflicts with debug, it's as if flag
3776 /// // was never used because it was overridden with color
3777 /// assert!(!m.get_flag("flag"));
3778 /// ```
3779 #[must_use]
3780 pub fn overrides_with(mut self, arg_id: impl IntoResettable<Id>) -> Self {
3781 if let Some(arg_id) = arg_id.into_resettable().into_option() {
3782 self.overrides.push(arg_id);
3783 } else {
3784 self.overrides.clear();
3785 }
3786 self
3787 }
3788
3789 /// Sets multiple mutually overridable arguments by name.
3790 ///
3791 /// i.e. this argument and the following argument will override each other in POSIX style
3792 /// (whichever argument was specified at runtime **last** "wins")
3793 ///
3794 /// **NOTE:** When an argument is overridden it is essentially as if it never was used, any
3795 /// conflicts, requirements, etc. are evaluated **after** all "overrides" have been removed
3796 ///
3797 /// **NOTE:** Overriding an argument implies they [conflict][Arg::conflicts_with_all`].
3798 ///
3799 /// # Examples
3800 ///
3801 /// ```rust
3802 /// # use clap_builder as clap;
3803 /// # use clap::{Command, arg};
3804 /// let m = Command::new("prog")
3805 /// .arg(arg!(-f --flag "some flag")
3806 /// .conflicts_with("color"))
3807 /// .arg(arg!(-d --debug "other flag"))
3808 /// .arg(arg!(-c --color "third flag")
3809 /// .overrides_with_all(["flag", "debug"]))
3810 /// .get_matches_from(vec![
3811 /// "prog", "-f", "-d", "-c"]);
3812 /// // ^~~~~~^~~~~~~~~ flag and debug are overridden by color
3813 ///
3814 /// assert!(m.get_flag("color")); // even though flag conflicts with color, it's as if flag
3815 /// // and debug were never used because they were overridden
3816 /// // with color
3817 /// assert!(!m.get_flag("debug"));
3818 /// assert!(!m.get_flag("flag"));
3819 /// ```
3820 #[must_use]
3821 pub fn overrides_with_all(mut self, names: impl IntoIterator<Item = impl Into<Id>>) -> Self {
3822 self.overrides.extend(names.into_iter().map(Into::into));
3823 self
3824 }
3825}
3826
3827/// # Reflection
3828impl Arg {
3829 /// Get the name of the argument
3830 #[inline]
3831 pub fn get_id(&self) -> &Id {
3832 &self.id
3833 }
3834
3835 /// Get the help specified for this argument, if any
3836 #[inline]
3837 pub fn get_help(&self) -> Option<&StyledStr> {
3838 self.help.as_ref()
3839 }
3840
3841 /// Get the long help specified for this argument, if any
3842 ///
3843 /// # Examples
3844 ///
3845 /// ```rust
3846 /// # use clap_builder as clap;
3847 /// # use clap::Arg;
3848 /// let arg = Arg::new("foo").long_help("long help");
3849 /// assert_eq!(Some("long help".to_owned()), arg.get_long_help().map(|s| s.to_string()));
3850 /// ```
3851 ///
3852 #[inline]
3853 pub fn get_long_help(&self) -> Option<&StyledStr> {
3854 self.long_help.as_ref()
3855 }
3856
3857 /// Get the help heading specified for this argument, if any
3858 #[inline]
3859 pub fn get_help_heading(&self) -> Option<&str> {
3860 self.help_heading
3861 .as_ref()
3862 .map(|s| s.as_deref())
3863 .unwrap_or_default()
3864 }
3865
3866 /// Get the short option name for this argument, if any
3867 #[inline]
3868 pub fn get_short(&self) -> Option<char> {
3869 self.short
3870 }
3871
3872 /// Get visible short aliases for this argument, if any
3873 #[inline]
3874 pub fn get_visible_short_aliases(&self) -> Option<Vec<char>> {
3875 if self.short_aliases.is_empty() {
3876 None
3877 } else {
3878 Some(
3879 self.short_aliases
3880 .iter()
3881 .filter_map(|(c, v)| if *v { Some(c) } else { None })
3882 .copied()
3883 .collect(),
3884 )
3885 }
3886 }
3887
3888 /// Get *all* short aliases for this argument, if any, both visible and hidden.
3889 #[inline]
3890 pub fn get_all_short_aliases(&self) -> Option<Vec<char>> {
3891 if self.short_aliases.is_empty() {
3892 None
3893 } else {
3894 Some(self.short_aliases.iter().map(|(s, _)| s).copied().collect())
3895 }
3896 }
3897
3898 /// Get the short option name and its visible aliases, if any
3899 #[inline]
3900 pub fn get_short_and_visible_aliases(&self) -> Option<Vec<char>> {
3901 let mut shorts = match self.short {
3902 Some(short) => vec![short],
3903 None => return None,
3904 };
3905 if let Some(aliases) = self.get_visible_short_aliases() {
3906 shorts.extend(aliases);
3907 }
3908 Some(shorts)
3909 }
3910
3911 /// Get the long option name for this argument, if any
3912 #[inline]
3913 pub fn get_long(&self) -> Option<&str> {
3914 self.long.as_deref()
3915 }
3916
3917 /// Get visible aliases for this argument, if any
3918 #[inline]
3919 pub fn get_visible_aliases(&self) -> Option<Vec<&str>> {
3920 if self.aliases.is_empty() {
3921 None
3922 } else {
3923 Some(
3924 self.aliases
3925 .iter()
3926 .filter_map(|(s, v)| if *v { Some(s.as_str()) } else { None })
3927 .collect(),
3928 )
3929 }
3930 }
3931
3932 /// Get *all* aliases for this argument, if any, both visible and hidden.
3933 #[inline]
3934 pub fn get_all_aliases(&self) -> Option<Vec<&str>> {
3935 if self.aliases.is_empty() {
3936 None
3937 } else {
3938 Some(self.aliases.iter().map(|(s, _)| s.as_str()).collect())
3939 }
3940 }
3941
3942 /// Get the long option name and its visible aliases, if any
3943 #[inline]
3944 pub fn get_long_and_visible_aliases(&self) -> Option<Vec<&str>> {
3945 let mut longs = match self.get_long() {
3946 Some(long) => vec![long],
3947 None => return None,
3948 };
3949 if let Some(aliases) = self.get_visible_aliases() {
3950 longs.extend(aliases);
3951 }
3952 Some(longs)
3953 }
3954
3955 /// Get the names of possible values for this argument. Only useful for user
3956 /// facing applications, such as building help messages or man files
3957 pub fn get_possible_values(&self) -> Vec<PossibleValue> {
3958 if !self.is_takes_value_set() {
3959 vec![]
3960 } else {
3961 self.get_value_parser()
3962 .possible_values()
3963 .map(|pvs| pvs.collect())
3964 .unwrap_or_default()
3965 }
3966 }
3967
3968 /// Get the names of values for this argument.
3969 #[inline]
3970 pub fn get_value_names(&self) -> Option<&[Str]> {
3971 if self.val_names.is_empty() {
3972 None
3973 } else {
3974 Some(&self.val_names)
3975 }
3976 }
3977
3978 /// Get the number of values for this argument.
3979 #[inline]
3980 pub fn get_num_args(&self) -> Option<ValueRange> {
3981 self.num_vals
3982 }
3983
3984 #[inline]
3985 pub(crate) fn get_min_vals(&self) -> usize {
3986 self.get_num_args().expect(INTERNAL_ERROR_MSG).min_values()
3987 }
3988
3989 /// Get the delimiter between multiple values
3990 #[inline]
3991 pub fn get_value_delimiter(&self) -> Option<char> {
3992 self.val_delim
3993 }
3994
3995 /// Get the value terminator for this argument. The value_terminator is a value
3996 /// that terminates parsing of multi-valued arguments.
3997 #[inline]
3998 pub fn get_value_terminator(&self) -> Option<&Str> {
3999 self.terminator.as_ref()
4000 }
4001
4002 /// Get the index of this argument, if any
4003 #[inline]
4004 pub fn get_index(&self) -> Option<usize> {
4005 self.index
4006 }
4007
4008 /// Get the value hint of this argument
4009 pub fn get_value_hint(&self) -> ValueHint {
4010 self.value_hint.unwrap_or_else(|| {
4011 if self.is_takes_value_set() {
4012 let type_id = self.get_value_parser().type_id();
4013 if type_id == AnyValueId::of::<std::path::PathBuf>() {
4014 ValueHint::AnyPath
4015 } else {
4016 ValueHint::default()
4017 }
4018 } else {
4019 ValueHint::default()
4020 }
4021 })
4022 }
4023
4024 /// Get the environment variable name specified for this argument, if any
4025 ///
4026 /// # Examples
4027 ///
4028 /// ```rust
4029 /// # use clap_builder as clap;
4030 /// # use std::ffi::OsStr;
4031 /// # use clap::Arg;
4032 /// let arg = Arg::new("foo").env("ENVIRONMENT");
4033 /// assert_eq!(arg.get_env(), Some(OsStr::new("ENVIRONMENT")));
4034 /// ```
4035 #[cfg(feature = "env")]
4036 pub fn get_env(&self) -> Option<&std::ffi::OsStr> {
4037 self.env.as_ref().map(|x| x.0.as_os_str())
4038 }
4039
4040 /// Get the default values specified for this argument, if any
4041 ///
4042 /// # Examples
4043 ///
4044 /// ```rust
4045 /// # use clap_builder as clap;
4046 /// # use clap::Arg;
4047 /// let arg = Arg::new("foo").default_value("default value");
4048 /// assert_eq!(arg.get_default_values(), &["default value"]);
4049 /// ```
4050 pub fn get_default_values(&self) -> &[OsStr] {
4051 &self.default_vals
4052 }
4053
4054 /// Checks whether this argument is a positional or not.
4055 ///
4056 /// # Examples
4057 ///
4058 /// ```rust
4059 /// # use clap_builder as clap;
4060 /// # use clap::Arg;
4061 /// let arg = Arg::new("foo");
4062 /// assert_eq!(arg.is_positional(), true);
4063 ///
4064 /// let arg = Arg::new("foo").long("foo");
4065 /// assert_eq!(arg.is_positional(), false);
4066 /// ```
4067 pub fn is_positional(&self) -> bool {
4068 self.get_long().is_none() && self.get_short().is_none()
4069 }
4070
4071 /// Reports whether [`Arg::required`] is set
4072 pub fn is_required_set(&self) -> bool {
4073 self.is_set(ArgSettings::Required)
4074 }
4075
4076 pub(crate) fn is_multiple_values_set(&self) -> bool {
4077 self.get_num_args().unwrap_or_default().is_multiple()
4078 }
4079
4080 pub(crate) fn is_takes_value_set(&self) -> bool {
4081 self.get_action().takes_values()
4082 }
4083
4084 /// Report whether [`Arg::allow_hyphen_values`] is set
4085 pub fn is_allow_hyphen_values_set(&self) -> bool {
4086 self.is_set(ArgSettings::AllowHyphenValues)
4087 }
4088
4089 /// Report whether [`Arg::allow_negative_numbers`] is set
4090 pub fn is_allow_negative_numbers_set(&self) -> bool {
4091 self.is_set(ArgSettings::AllowNegativeNumbers)
4092 }
4093
4094 /// Behavior when parsing the argument
4095 pub fn get_action(&self) -> &super::ArgAction {
4096 const DEFAULT: super::ArgAction = super::ArgAction::Set;
4097 self.action.as_ref().unwrap_or(&DEFAULT)
4098 }
4099
4100 /// Configured parser for argument values
4101 ///
4102 /// # Example
4103 ///
4104 /// ```rust
4105 /// # use clap_builder as clap;
4106 /// let cmd = clap::Command::new("raw")
4107 /// .arg(
4108 /// clap::Arg::new("port")
4109 /// .value_parser(clap::value_parser!(usize))
4110 /// );
4111 /// let value_parser = cmd.get_arguments()
4112 /// .find(|a| a.get_id() == "port").unwrap()
4113 /// .get_value_parser();
4114 /// println!("{value_parser:?}");
4115 /// ```
4116 pub fn get_value_parser(&self) -> &super::ValueParser {
4117 if let Some(value_parser) = self.value_parser.as_ref() {
4118 value_parser
4119 } else {
4120 static DEFAULT: super::ValueParser = super::ValueParser::string();
4121 &DEFAULT
4122 }
4123 }
4124
4125 /// Report whether [`Arg::global`] is set
4126 pub fn is_global_set(&self) -> bool {
4127 self.is_set(ArgSettings::Global)
4128 }
4129
4130 /// Report whether [`Arg::next_line_help`] is set
4131 pub fn is_next_line_help_set(&self) -> bool {
4132 self.is_set(ArgSettings::NextLineHelp)
4133 }
4134
4135 /// Report whether [`Arg::hide`] is set
4136 pub fn is_hide_set(&self) -> bool {
4137 self.is_set(ArgSettings::Hidden)
4138 }
4139
4140 /// Report whether [`Arg::hide_default_value`] is set
4141 pub fn is_hide_default_value_set(&self) -> bool {
4142 self.is_set(ArgSettings::HideDefaultValue)
4143 }
4144
4145 /// Report whether [`Arg::hide_possible_values`] is set
4146 pub fn is_hide_possible_values_set(&self) -> bool {
4147 self.is_set(ArgSettings::HidePossibleValues)
4148 }
4149
4150 /// Report whether [`Arg::hide_env`] is set
4151 #[cfg(feature = "env")]
4152 pub fn is_hide_env_set(&self) -> bool {
4153 self.is_set(ArgSettings::HideEnv)
4154 }
4155
4156 /// Report whether [`Arg::hide_env_values`] is set
4157 #[cfg(feature = "env")]
4158 pub fn is_hide_env_values_set(&self) -> bool {
4159 self.is_set(ArgSettings::HideEnvValues)
4160 }
4161
4162 /// Report whether [`Arg::hide_short_help`] is set
4163 pub fn is_hide_short_help_set(&self) -> bool {
4164 self.is_set(ArgSettings::HiddenShortHelp)
4165 }
4166
4167 /// Report whether [`Arg::hide_long_help`] is set
4168 pub fn is_hide_long_help_set(&self) -> bool {
4169 self.is_set(ArgSettings::HiddenLongHelp)
4170 }
4171
4172 /// Report whether [`Arg::require_equals`] is set
4173 pub fn is_require_equals_set(&self) -> bool {
4174 self.is_set(ArgSettings::RequireEquals)
4175 }
4176
4177 /// Reports whether [`Arg::exclusive`] is set
4178 pub fn is_exclusive_set(&self) -> bool {
4179 self.is_set(ArgSettings::Exclusive)
4180 }
4181
4182 /// Report whether [`Arg::trailing_var_arg`] is set
4183 pub fn is_trailing_var_arg_set(&self) -> bool {
4184 self.is_set(ArgSettings::TrailingVarArg)
4185 }
4186
4187 /// Reports whether [`Arg::last`] is set
4188 pub fn is_last_set(&self) -> bool {
4189 self.is_set(ArgSettings::Last)
4190 }
4191
4192 /// Reports whether [`Arg::ignore_case`] is set
4193 pub fn is_ignore_case_set(&self) -> bool {
4194 self.is_set(ArgSettings::IgnoreCase)
4195 }
4196}
4197
4198/// # Internally used only
4199impl Arg {
4200 pub(crate) fn _build(&mut self) {
4201 if self.action.is_none() {
4202 if self.num_vals == Some(ValueRange::EMPTY) {
4203 let action = super::ArgAction::SetTrue;
4204 self.action = Some(action);
4205 } else {
4206 let action =
4207 if self.is_positional() && self.num_vals.unwrap_or_default().is_unbounded() {
4208 // Allow collecting arguments interleaved with flags
4209 //
4210 // Bounded values are probably a group and the user should explicitly opt-in to
4211 // Append
4212 super::ArgAction::Append
4213 } else {
4214 super::ArgAction::Set
4215 };
4216 self.action = Some(action);
4217 }
4218 }
4219 if let Some(action) = self.action.as_ref() {
4220 if let Some(default_value) = action.default_value() {
4221 if self.default_vals.is_empty() {
4222 self.default_vals = vec![default_value.into()];
4223 }
4224 }
4225 if let Some(default_value) = action.default_missing_value() {
4226 if self.default_missing_vals.is_empty() {
4227 self.default_missing_vals = vec![default_value.into()];
4228 }
4229 }
4230 }
4231
4232 if self.value_parser.is_none() {
4233 if let Some(default) = self.action.as_ref().and_then(|a| a.default_value_parser()) {
4234 self.value_parser = Some(default);
4235 } else {
4236 self.value_parser = Some(super::ValueParser::string());
4237 }
4238 }
4239
4240 let val_names_len = self.val_names.len();
4241 if val_names_len > 1 {
4242 self.num_vals.get_or_insert(val_names_len.into());
4243 } else {
4244 let nargs = if self.get_action().takes_values() {
4245 ValueRange::SINGLE
4246 } else {
4247 ValueRange::EMPTY
4248 };
4249 self.num_vals.get_or_insert(nargs);
4250 }
4251 }
4252
4253 // Used for positionals when printing
4254 pub(crate) fn name_no_brackets(&self) -> String {
4255 debug!("Arg::name_no_brackets:{}", self.get_id());
4256 let delim = " ";
4257 if !self.val_names.is_empty() {
4258 debug!("Arg::name_no_brackets: val_names={:#?}", self.val_names);
4259
4260 if self.val_names.len() > 1 {
4261 self.val_names
4262 .iter()
4263 .map(|n| format!("<{n}>"))
4264 .collect::<Vec<_>>()
4265 .join(delim)
4266 } else {
4267 self.val_names
4268 .first()
4269 .expect(INTERNAL_ERROR_MSG)
4270 .as_str()
4271 .to_owned()
4272 }
4273 } else {
4274 debug!("Arg::name_no_brackets: just name");
4275 self.get_id().as_str().to_owned()
4276 }
4277 }
4278
4279 pub(crate) fn stylized(&self, styles: &Styles, required: Option<bool>) -> StyledStr {
4280 use std::fmt::Write as _;
4281 let literal = styles.get_literal();
4282
4283 let mut styled = StyledStr::new();
4284 // Write the name such --long or -l
4285 if let Some(l) = self.get_long() {
4286 let _ = write!(
4287 styled,
4288 "{}--{l}{}",
4289 literal.render(),
4290 literal.render_reset()
4291 );
4292 } else if let Some(s) = self.get_short() {
4293 let _ = write!(styled, "{}-{s}{}", literal.render(), literal.render_reset());
4294 }
4295 styled.push_styled(&self.stylize_arg_suffix(styles, required));
4296 styled
4297 }
4298
4299 pub(crate) fn stylize_arg_suffix(&self, styles: &Styles, required: Option<bool>) -> StyledStr {
4300 use std::fmt::Write as _;
4301 let literal = styles.get_literal();
4302 let placeholder = styles.get_placeholder();
4303 let mut styled = StyledStr::new();
4304
4305 let mut need_closing_bracket = false;
4306 if self.is_takes_value_set() && !self.is_positional() {
4307 let is_optional_val = self.get_min_vals() == 0;
4308 let (style, start) = if self.is_require_equals_set() {
4309 if is_optional_val {
4310 need_closing_bracket = true;
4311 (placeholder, "[=")
4312 } else {
4313 (literal, "=")
4314 }
4315 } else if is_optional_val {
4316 need_closing_bracket = true;
4317 (placeholder, " [")
4318 } else {
4319 (placeholder, " ")
4320 };
4321 let _ = write!(styled, "{}{start}{}", style.render(), style.render_reset());
4322 }
4323 if self.is_takes_value_set() || self.is_positional() {
4324 let required = required.unwrap_or_else(|| self.is_required_set());
4325 let arg_val = self.render_arg_val(required);
4326 let _ = write!(
4327 styled,
4328 "{}{arg_val}{}",
4329 placeholder.render(),
4330 placeholder.render_reset()
4331 );
4332 } else if matches!(*self.get_action(), ArgAction::Count) {
4333 let _ = write!(
4334 styled,
4335 "{}...{}",
4336 placeholder.render(),
4337 placeholder.render_reset()
4338 );
4339 }
4340 if need_closing_bracket {
4341 let _ = write!(
4342 styled,
4343 "{}]{}",
4344 placeholder.render(),
4345 placeholder.render_reset()
4346 );
4347 }
4348
4349 styled
4350 }
4351
4352 /// Write the values such as `<name1> <name2>`
4353 fn render_arg_val(&self, required: bool) -> String {
4354 let mut rendered = String::new();
4355
4356 let num_vals = self.get_num_args().unwrap_or_else(|| 1.into());
4357
4358 let mut val_names = if self.val_names.is_empty() {
4359 vec![self.id.as_internal_str().to_owned()]
4360 } else {
4361 self.val_names.clone()
4362 };
4363 if val_names.len() == 1 {
4364 let min = num_vals.min_values().max(1);
4365 let val_name = val_names.pop().unwrap();
4366 val_names = vec![val_name; min];
4367 }
4368
4369 debug_assert!(self.is_takes_value_set());
4370 for (n, val_name) in val_names.iter().enumerate() {
4371 let arg_name = if self.is_positional() && (num_vals.min_values() == 0 || !required) {
4372 format!("[{val_name}]")
4373 } else {
4374 format!("<{val_name}>")
4375 };
4376
4377 if n != 0 {
4378 rendered.push(' ');
4379 }
4380 rendered.push_str(&arg_name);
4381 }
4382
4383 let mut extra_values = false;
4384 extra_values |= val_names.len() < num_vals.max_values();
4385 if self.is_positional() && matches!(*self.get_action(), ArgAction::Append) {
4386 extra_values = true;
4387 }
4388 if extra_values {
4389 rendered.push_str("...");
4390 }
4391
4392 rendered
4393 }
4394
4395 /// Either multiple values or occurrences
4396 pub(crate) fn is_multiple(&self) -> bool {
4397 self.is_multiple_values_set() || matches!(*self.get_action(), ArgAction::Append)
4398 }
4399
4400 #[cfg(feature = "help")]
4401 pub(crate) fn get_display_order(&self) -> usize {
4402 self.disp_ord.unwrap_or(999)
4403 }
4404}
4405
4406impl From<&'_ Arg> for Arg {
4407 fn from(a: &Arg) -> Self {
4408 a.clone()
4409 }
4410}
4411
4412impl PartialEq for Arg {
4413 fn eq(&self, other: &Arg) -> bool {
4414 self.get_id() == other.get_id()
4415 }
4416}
4417
4418impl PartialOrd for Arg {
4419 fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
4420 Some(self.cmp(other))
4421 }
4422}
4423
4424impl Ord for Arg {
4425 fn cmp(&self, other: &Arg) -> Ordering {
4426 self.get_id().cmp(other.get_id())
4427 }
4428}
4429
4430impl Eq for Arg {}
4431
4432impl Display for Arg {
4433 fn fmt(&self, f: &mut Formatter) -> fmt::Result {
4434 let plain = Styles::plain();
4435 self.stylized(&plain, None).fmt(f)
4436 }
4437}
4438
4439impl fmt::Debug for Arg {
4440 fn fmt(&self, f: &mut Formatter) -> Result<(), fmt::Error> {
4441 let mut ds = f.debug_struct("Arg");
4442
4443 #[allow(unused_mut)]
4444 let mut ds = ds
4445 .field("id", &self.id)
4446 .field("help", &self.help)
4447 .field("long_help", &self.long_help)
4448 .field("action", &self.action)
4449 .field("value_parser", &self.value_parser)
4450 .field("blacklist", &self.blacklist)
4451 .field("settings", &self.settings)
4452 .field("overrides", &self.overrides)
4453 .field("groups", &self.groups)
4454 .field("requires", &self.requires)
4455 .field("r_ifs", &self.r_ifs)
4456 .field("r_unless", &self.r_unless)
4457 .field("short", &self.short)
4458 .field("long", &self.long)
4459 .field("aliases", &self.aliases)
4460 .field("short_aliases", &self.short_aliases)
4461 .field("disp_ord", &self.disp_ord)
4462 .field("val_names", &self.val_names)
4463 .field("num_vals", &self.num_vals)
4464 .field("val_delim", &self.val_delim)
4465 .field("default_vals", &self.default_vals)
4466 .field("default_vals_ifs", &self.default_vals_ifs)
4467 .field("terminator", &self.terminator)
4468 .field("index", &self.index)
4469 .field("help_heading", &self.help_heading)
4470 .field("value_hint", &self.value_hint)
4471 .field("default_missing_vals", &self.default_missing_vals);
4472
4473 #[cfg(feature = "env")]
4474 {
4475 ds = ds.field("env", &self.env);
4476 }
4477
4478 ds.finish()
4479 }
4480}
4481
4482// Flags
4483#[cfg(test)]
4484mod test {
4485 use super::Arg;
4486 use super::ArgAction;
4487
4488 #[test]
4489 fn flag_display_long() {
4490 let mut f = Arg::new("flg").long("flag").action(ArgAction::SetTrue);
4491 f._build();
4492
4493 assert_eq!(f.to_string(), "--flag");
4494 }
4495
4496 #[test]
4497 fn flag_display_short() {
4498 let mut f2 = Arg::new("flg").short('f').action(ArgAction::SetTrue);
4499 f2._build();
4500
4501 assert_eq!(f2.to_string(), "-f");
4502 }
4503
4504 #[test]
4505 fn flag_display_count() {
4506 let mut f2 = Arg::new("flg").long("flag").action(ArgAction::Count);
4507 f2._build();
4508
4509 assert_eq!(f2.to_string(), "--flag...");
4510 }
4511
4512 #[test]
4513 fn flag_display_single_alias() {
4514 let mut f = Arg::new("flg")
4515 .long("flag")
4516 .visible_alias("als")
4517 .action(ArgAction::SetTrue);
4518 f._build();
4519
4520 assert_eq!(f.to_string(), "--flag")
4521 }
4522
4523 #[test]
4524 fn flag_display_multiple_aliases() {
4525 let mut f = Arg::new("flg").short('f').action(ArgAction::SetTrue);
4526 f.aliases = vec![
4527 ("alias_not_visible".into(), false),
4528 ("f2".into(), true),
4529 ("f3".into(), true),
4530 ("f4".into(), true),
4531 ];
4532 f._build();
4533
4534 assert_eq!(f.to_string(), "-f");
4535 }
4536
4537 #[test]
4538 fn flag_display_single_short_alias() {
4539 let mut f = Arg::new("flg").short('a').action(ArgAction::SetTrue);
4540 f.short_aliases = vec![('b', true)];
4541 f._build();
4542
4543 assert_eq!(f.to_string(), "-a")
4544 }
4545
4546 #[test]
4547 fn flag_display_multiple_short_aliases() {
4548 let mut f = Arg::new("flg").short('a').action(ArgAction::SetTrue);
4549 f.short_aliases = vec![('b', false), ('c', true), ('d', true), ('e', true)];
4550 f._build();
4551
4552 assert_eq!(f.to_string(), "-a");
4553 }
4554
4555 // Options
4556
4557 #[test]
4558 fn option_display_multiple_occurrences() {
4559 let mut o = Arg::new("opt").long("option").action(ArgAction::Append);
4560 o._build();
4561
4562 assert_eq!(o.to_string(), "--option <opt>");
4563 }
4564
4565 #[test]
4566 fn option_display_multiple_values() {
4567 let mut o = Arg::new("opt")
4568 .long("option")
4569 .action(ArgAction::Set)
4570 .num_args(1..);
4571 o._build();
4572
4573 assert_eq!(o.to_string(), "--option <opt>...");
4574 }
4575
4576 #[test]
4577 fn option_display_zero_or_more_values() {
4578 let mut o = Arg::new("opt")
4579 .long("option")
4580 .action(ArgAction::Set)
4581 .num_args(0..);
4582 o._build();
4583
4584 assert_eq!(o.to_string(), "--option [<opt>...]");
4585 }
4586
4587 #[test]
4588 fn option_display_one_or_more_values() {
4589 let mut o = Arg::new("opt")
4590 .long("option")
4591 .action(ArgAction::Set)
4592 .num_args(1..);
4593 o._build();
4594
4595 assert_eq!(o.to_string(), "--option <opt>...");
4596 }
4597
4598 #[test]
4599 fn option_display_zero_or_more_values_with_value_name() {
4600 let mut o = Arg::new("opt")
4601 .short('o')
4602 .action(ArgAction::Set)
4603 .num_args(0..)
4604 .value_names(["file"]);
4605 o._build();
4606
4607 assert_eq!(o.to_string(), "-o [<file>...]");
4608 }
4609
4610 #[test]
4611 fn option_display_one_or_more_values_with_value_name() {
4612 let mut o = Arg::new("opt")
4613 .short('o')
4614 .action(ArgAction::Set)
4615 .num_args(1..)
4616 .value_names(["file"]);
4617 o._build();
4618
4619 assert_eq!(o.to_string(), "-o <file>...");
4620 }
4621
4622 #[test]
4623 fn option_display_optional_value() {
4624 let mut o = Arg::new("opt")
4625 .long("option")
4626 .action(ArgAction::Set)
4627 .num_args(0..=1);
4628 o._build();
4629
4630 assert_eq!(o.to_string(), "--option [<opt>]");
4631 }
4632
4633 #[test]
4634 fn option_display_value_names() {
4635 let mut o = Arg::new("opt")
4636 .short('o')
4637 .action(ArgAction::Set)
4638 .value_names(["file", "name"]);
4639 o._build();
4640
4641 assert_eq!(o.to_string(), "-o <file> <name>");
4642 }
4643
4644 #[test]
4645 fn option_display3() {
4646 let mut o = Arg::new("opt")
4647 .short('o')
4648 .num_args(1..)
4649 .action(ArgAction::Set)
4650 .value_names(["file", "name"]);
4651 o._build();
4652
4653 assert_eq!(o.to_string(), "-o <file> <name>...");
4654 }
4655
4656 #[test]
4657 fn option_display_single_alias() {
4658 let mut o = Arg::new("opt")
4659 .long("option")
4660 .action(ArgAction::Set)
4661 .visible_alias("als");
4662 o._build();
4663
4664 assert_eq!(o.to_string(), "--option <opt>");
4665 }
4666
4667 #[test]
4668 fn option_display_multiple_aliases() {
4669 let mut o = Arg::new("opt")
4670 .long("option")
4671 .action(ArgAction::Set)
4672 .visible_aliases(["als2", "als3", "als4"])
4673 .alias("als_not_visible");
4674 o._build();
4675
4676 assert_eq!(o.to_string(), "--option <opt>");
4677 }
4678
4679 #[test]
4680 fn option_display_single_short_alias() {
4681 let mut o = Arg::new("opt")
4682 .short('a')
4683 .action(ArgAction::Set)
4684 .visible_short_alias('b');
4685 o._build();
4686
4687 assert_eq!(o.to_string(), "-a <opt>");
4688 }
4689
4690 #[test]
4691 fn option_display_multiple_short_aliases() {
4692 let mut o = Arg::new("opt")
4693 .short('a')
4694 .action(ArgAction::Set)
4695 .visible_short_aliases(['b', 'c', 'd'])
4696 .short_alias('e');
4697 o._build();
4698
4699 assert_eq!(o.to_string(), "-a <opt>");
4700 }
4701
4702 // Positionals
4703
4704 #[test]
4705 fn positional_display_multiple_values() {
4706 let mut p = Arg::new("pos").index(1).num_args(1..);
4707 p._build();
4708
4709 assert_eq!(p.to_string(), "[pos]...");
4710 }
4711
4712 #[test]
4713 fn positional_display_multiple_values_required() {
4714 let mut p = Arg::new("pos").index(1).num_args(1..).required(true);
4715 p._build();
4716
4717 assert_eq!(p.to_string(), "<pos>...");
4718 }
4719
4720 #[test]
4721 fn positional_display_zero_or_more_values() {
4722 let mut p = Arg::new("pos").index(1).num_args(0..);
4723 p._build();
4724
4725 assert_eq!(p.to_string(), "[pos]...");
4726 }
4727
4728 #[test]
4729 fn positional_display_one_or_more_values() {
4730 let mut p = Arg::new("pos").index(1).num_args(1..);
4731 p._build();
4732
4733 assert_eq!(p.to_string(), "[pos]...");
4734 }
4735
4736 #[test]
4737 fn positional_display_one_or_more_values_required() {
4738 let mut p = Arg::new("pos").index(1).num_args(1..).required(true);
4739 p._build();
4740
4741 assert_eq!(p.to_string(), "<pos>...");
4742 }
4743
4744 #[test]
4745 fn positional_display_optional_value() {
4746 let mut p = Arg::new("pos")
4747 .index(1)
4748 .num_args(0..=1)
4749 .action(ArgAction::Set);
4750 p._build();
4751
4752 assert_eq!(p.to_string(), "[pos]");
4753 }
4754
4755 #[test]
4756 fn positional_display_multiple_occurrences() {
4757 let mut p = Arg::new("pos").index(1).action(ArgAction::Append);
4758 p._build();
4759
4760 assert_eq!(p.to_string(), "[pos]...");
4761 }
4762
4763 #[test]
4764 fn positional_display_multiple_occurrences_required() {
4765 let mut p = Arg::new("pos")
4766 .index(1)
4767 .action(ArgAction::Append)
4768 .required(true);
4769 p._build();
4770
4771 assert_eq!(p.to_string(), "<pos>...");
4772 }
4773
4774 #[test]
4775 fn positional_display_required() {
4776 let mut p = Arg::new("pos").index(1).required(true);
4777 p._build();
4778
4779 assert_eq!(p.to_string(), "<pos>");
4780 }
4781
4782 #[test]
4783 fn positional_display_val_names() {
4784 let mut p = Arg::new("pos").index(1).value_names(["file1", "file2"]);
4785 p._build();
4786
4787 assert_eq!(p.to_string(), "[file1] [file2]");
4788 }
4789
4790 #[test]
4791 fn positional_display_val_names_required() {
4792 let mut p = Arg::new("pos")
4793 .index(1)
4794 .value_names(["file1", "file2"])
4795 .required(true);
4796 p._build();
4797
4798 assert_eq!(p.to_string(), "<file1> <file2>");
4799 }
4800}
4801