clap/args/
arg.rs

1#[cfg(feature = "yaml")]
2use std::collections::BTreeMap;
3use std::rc::Rc;
4use std::ffi::{OsStr, OsString};
5#[cfg(any(target_os = "windows", target_arch = "wasm32"))]
6use osstringext::OsStrExt3;
7#[cfg(not(any(target_os = "windows", target_arch = "wasm32")))]
8use std::os::unix::ffi::OsStrExt;
9use std::env;
10
11#[cfg(feature = "yaml")]
12use yaml_rust::Yaml;
13use map::VecMap;
14
15use usage_parser::UsageParser;
16use args::settings::ArgSettings;
17use args::arg_builder::{Base, Switched, Valued};
18
19/// The abstract representation of a command line argument. Used to set all the options and
20/// relationships that define a valid argument for the program.
21///
22/// There are two methods for constructing [`Arg`]s, using the builder pattern and setting options
23/// manually, or using a usage string which is far less verbose but has fewer options. You can also
24/// use a combination of the two methods to achieve the best of both worlds.
25///
26/// # Examples
27///
28/// ```rust
29/// # use clap::Arg;
30/// // Using the traditional builder pattern and setting each option manually
31/// let cfg = Arg::with_name("config")
32///       .short("c")
33///       .long("config")
34///       .takes_value(true)
35///       .value_name("FILE")
36///       .help("Provides a config file to myprog");
37/// // Using a usage string (setting a similar argument to the one above)
38/// let input = Arg::from_usage("-i, --input=[FILE] 'Provides an input file to the program'");
39/// ```
40/// [`Arg`]: ./struct.Arg.html
41#[allow(missing_debug_implementations)]
42#[derive(Default, Clone)]
43pub struct Arg<'a, 'b>
44where
45    'a: 'b,
46{
47    #[doc(hidden)] pub b: Base<'a, 'b>,
48    #[doc(hidden)] pub s: Switched<'b>,
49    #[doc(hidden)] pub v: Valued<'a, 'b>,
50    #[doc(hidden)] pub index: Option<u64>,
51    #[doc(hidden)] pub r_ifs: Option<Vec<(&'a str, &'b str)>>,
52}
53
54impl<'a, 'b> Arg<'a, 'b> {
55    /// Creates a new instance of [`Arg`] using a unique string name. The name will be used to get
56    /// information about whether or not the argument was used at runtime, get values, set
57    /// relationships with other args, etc..
58    ///
59    /// **NOTE:** In the case of arguments that take values (i.e. [`Arg::takes_value(true)`])
60    /// and positional arguments (i.e. those without a preceding `-` or `--`) the name will also
61    /// be displayed when the user prints the usage/help information of the program.
62    ///
63    /// # Examples
64    ///
65    /// ```rust
66    /// # use clap::{App, Arg};
67    /// Arg::with_name("config")
68    /// # ;
69    /// ```
70    /// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
71    /// [`Arg`]: ./struct.Arg.html
72    pub fn with_name(n: &'a str) -> Self {
73        Arg {
74            b: Base::new(n),
75            ..Default::default()
76        }
77    }
78
79    /// Creates a new instance of [`Arg`] from a .yml (YAML) file.
80    ///
81    /// # Examples
82    ///
83    /// ```ignore
84    /// # #[macro_use]
85    /// # extern crate clap;
86    /// # use clap::Arg;
87    /// # fn main() {
88    /// let yml = load_yaml!("arg.yml");
89    /// let arg = Arg::from_yaml(yml);
90    /// # }
91    /// ```
92    /// [`Arg`]: ./struct.Arg.html
93    #[cfg(feature = "yaml")]
94    pub fn from_yaml(y: &BTreeMap<Yaml, Yaml>) -> Arg {
95        // We WANT this to panic on error...so expect() is good.
96        let name_yml = y.keys().nth(0).unwrap();
97        let name_str = name_yml.as_str().unwrap();
98        let mut a = Arg::with_name(name_str);
99        let arg_settings = y.get(name_yml).unwrap().as_hash().unwrap();
100
101        for (k, v) in arg_settings.iter() {
102            a = match k.as_str().unwrap() {
103                "short" => yaml_to_str!(a, v, short),
104                "long" => yaml_to_str!(a, v, long),
105                "aliases" => yaml_vec_or_str!(v, a, alias),
106                "help" => yaml_to_str!(a, v, help),
107                "long_help" => yaml_to_str!(a, v, long_help),
108                "required" => yaml_to_bool!(a, v, required),
109                "required_if" => yaml_tuple2!(a, v, required_if),
110                "required_ifs" => yaml_tuple2!(a, v, required_if),
111                "takes_value" => yaml_to_bool!(a, v, takes_value),
112                "index" => yaml_to_u64!(a, v, index),
113                "global" => yaml_to_bool!(a, v, global),
114                "multiple" => yaml_to_bool!(a, v, multiple),
115                "hidden" => yaml_to_bool!(a, v, hidden),
116                "next_line_help" => yaml_to_bool!(a, v, next_line_help),
117                "empty_values" => yaml_to_bool!(a, v, empty_values),
118                "group" => yaml_to_str!(a, v, group),
119                "number_of_values" => yaml_to_u64!(a, v, number_of_values),
120                "max_values" => yaml_to_u64!(a, v, max_values),
121                "min_values" => yaml_to_u64!(a, v, min_values),
122                "value_name" => yaml_to_str!(a, v, value_name),
123                "use_delimiter" => yaml_to_bool!(a, v, use_delimiter),
124                "allow_hyphen_values" => yaml_to_bool!(a, v, allow_hyphen_values),
125                "last" => yaml_to_bool!(a, v, last),
126                "require_delimiter" => yaml_to_bool!(a, v, require_delimiter),
127                "value_delimiter" => yaml_to_str!(a, v, value_delimiter),
128                "required_unless" => yaml_to_str!(a, v, required_unless),
129                "display_order" => yaml_to_usize!(a, v, display_order),
130                "default_value" => yaml_to_str!(a, v, default_value),
131                "default_value_if" => yaml_tuple3!(a, v, default_value_if),
132                "default_value_ifs" => yaml_tuple3!(a, v, default_value_if),
133                "env" => yaml_to_str!(a, v, env),
134                "value_names" => yaml_vec_or_str!(v, a, value_name),
135                "groups" => yaml_vec_or_str!(v, a, group),
136                "requires" => yaml_vec_or_str!(v, a, requires),
137                "requires_if" => yaml_tuple2!(a, v, requires_if),
138                "requires_ifs" => yaml_tuple2!(a, v, requires_if),
139                "conflicts_with" => yaml_vec_or_str!(v, a, conflicts_with),
140                "overrides_with" => yaml_vec_or_str!(v, a, overrides_with),
141                "possible_values" => yaml_vec_or_str!(v, a, possible_value),
142                "case_insensitive" => yaml_to_bool!(a, v, case_insensitive),
143                "required_unless_one" => yaml_vec_or_str!(v, a, required_unless),
144                "required_unless_all" => {
145                    a = yaml_vec_or_str!(v, a, required_unless);
146                    a.setb(ArgSettings::RequiredUnlessAll);
147                    a
148                }
149                s => panic!(
150                    "Unknown Arg setting '{}' in YAML file for arg '{}'",
151                    s, name_str
152                ),
153            }
154        }
155
156        a
157    }
158
159    /// Creates a new instance of [`Arg`] from a usage string. Allows creation of basic settings
160    /// for the [`Arg`]. The syntax is flexible, but there are some rules to follow.
161    ///
162    /// **NOTE**: Not all settings may be set using the usage string method. Some properties are
163    /// only available via the builder pattern.
164    ///
165    /// **NOTE**: Only ASCII values are officially supported in [`Arg::from_usage`] strings. Some
166    /// UTF-8 codepoints may work just fine, but this is not guaranteed.
167    ///
168    /// # Syntax
169    ///
170    /// Usage strings typically following the form:
171    ///
172    /// ```notrust
173    /// [explicit name] [short] [long] [value names] [help string]
174    /// ```
175    ///
176    /// This is not a hard rule as the attributes can appear in other orders. There are also
177    /// several additional sigils which denote additional settings. Below are the details of each
178    /// portion of the string.
179    ///
180    /// ### Explicit Name
181    ///
182    /// This is an optional field, if it's omitted the argument will use one of the additional
183    /// fields as the name using the following priority order:
184    ///
185    ///  * Explicit Name (This always takes precedence when present)
186    ///  * Long
187    ///  * Short
188    ///  * Value Name
189    ///
190    /// `clap` determines explicit names as the first string of characters between either `[]` or
191    /// `<>` where `[]` has the dual notation of meaning the argument is optional, and `<>` meaning
192    /// the argument is required.
193    ///
194    /// Explicit names may be followed by:
195    ///  * The multiple denotation `...`
196    ///
197    /// Example explicit names as follows (`ename` for an optional argument, and `rname` for a
198    /// required argument):
199    ///
200    /// ```notrust
201    /// [ename] -s, --long 'some flag'
202    /// <rname> -r, --longer 'some other flag'
203    /// ```
204    ///
205    /// ### Short
206    ///
207    /// This is set by placing a single character after a leading `-`.
208    ///
209    /// Shorts may be followed by
210    ///  * The multiple denotation `...`
211    ///  * An optional comma `,` which is cosmetic only
212    ///  * Value notation
213    ///
214    /// Example shorts are as follows (`-s`, and `-r`):
215    ///
216    /// ```notrust
217    /// -s, --long 'some flag'
218    /// <rname> -r [val], --longer 'some option'
219    /// ```
220    ///
221    /// ### Long
222    ///
223    /// This is set by placing a word (no spaces) after a leading `--`.
224    ///
225    /// Shorts may be followed by
226    ///  * The multiple denotation `...`
227    ///  * Value notation
228    ///
229    /// Example longs are as follows (`--some`, and `--rapid`):
230    ///
231    /// ```notrust
232    /// -s, --some 'some flag'
233    /// --rapid=[FILE] 'some option'
234    /// ```
235    ///
236    /// ### Values (Value Notation)
237    ///
238    /// This is set by placing a word(s) between `[]` or `<>` optionally after `=` (although this
239    /// is cosmetic only and does not affect functionality). If an explicit name has **not** been
240    /// set, using `<>` will denote a required argument, and `[]` will denote an optional argument
241    ///
242    /// Values may be followed by
243    ///  * The multiple denotation `...`
244    ///  * More Value notation
245    ///
246    /// More than one value will also implicitly set the arguments number of values, i.e. having
247    /// two values, `--option [val1] [val2]` specifies that in order for option to be satisified it
248    /// must receive exactly two values
249    ///
250    /// Example values are as follows (`FILE`, and `SPEED`):
251    ///
252    /// ```notrust
253    /// -s, --some [FILE] 'some option'
254    /// --rapid=<SPEED>... 'some required multiple option'
255    /// ```
256    ///
257    /// ### Help String
258    ///
259    /// The help string is denoted between a pair of single quotes `''` and may contain any
260    /// characters.
261    ///
262    /// Example help strings are as follows:
263    ///
264    /// ```notrust
265    /// -s, --some [FILE] 'some option'
266    /// --rapid=<SPEED>... 'some required multiple option'
267    /// ```
268    ///
269    /// ### Additional Sigils
270    ///
271    /// Multiple notation `...` (three consecutive dots/periods) specifies that this argument may
272    /// be used multiple times. Do not confuse multiple occurrences (`...`) with multiple values.
273    /// `--option val1 val2` is a single occurrence with multiple values. `--flag --flag` is
274    /// multiple occurrences (and then you can obviously have instances of both as well)
275    ///
276    /// # Examples
277    ///
278    /// ```rust
279    /// # use clap::{App, Arg};
280    /// App::new("prog")
281    ///     .args(&[
282    ///         Arg::from_usage("--config <FILE> 'a required file for the configuration and no short'"),
283    ///         Arg::from_usage("-d, --debug... 'turns on debugging information and allows multiples'"),
284    ///         Arg::from_usage("[input] 'an optional input file to use'")
285    /// ])
286    /// # ;
287    /// ```
288    /// [`Arg`]: ./struct.Arg.html
289    /// [`Arg::from_usage`]: ./struct.Arg.html#method.from_usage
290    pub fn from_usage(u: &'a str) -> Self {
291        let parser = UsageParser::from_usage(u);
292        parser.parse()
293    }
294
295    /// Sets the short version of the argument without the preceding `-`.
296    ///
297    /// By default `clap` automatically assigns `V` and `h` to the auto-generated `version` and
298    /// `help` arguments respectively. You may use the uppercase `V` or lowercase `h` for your own
299    /// arguments, in which case `clap` simply will not assign those to the auto-generated
300    /// `version` or `help` arguments.
301    ///
302    /// **NOTE:** Any leading `-` characters will be stripped, and only the first
303    /// non `-` character will be used as the [`short`] version
304    ///
305    /// # Examples
306    ///
307    /// To set [`short`] use a single valid UTF-8 code point. If you supply a leading `-` such as
308    /// `-c`, the `-` will be stripped.
309    ///
310    /// ```rust
311    /// # use clap::{App, Arg};
312    /// Arg::with_name("config")
313    ///     .short("c")
314    /// # ;
315    /// ```
316    ///
317    /// Setting [`short`] allows using the argument via a single hyphen (`-`) such as `-c`
318    ///
319    /// ```rust
320    /// # use clap::{App, Arg};
321    /// let m = App::new("prog")
322    ///     .arg(Arg::with_name("config")
323    ///         .short("c"))
324    ///     .get_matches_from(vec![
325    ///         "prog", "-c"
326    ///     ]);
327    ///
328    /// assert!(m.is_present("config"));
329    /// ```
330    /// [`short`]: ./struct.Arg.html#method.short
331    pub fn short<S: AsRef<str>>(mut self, s: S) -> Self {
332        self.s.short = s.as_ref().trim_left_matches(|c| c == '-').chars().nth(0);
333        self
334    }
335
336    /// Sets the long version of the argument without the preceding `--`.
337    ///
338    /// By default `clap` automatically assigns `version` and `help` to the auto-generated
339    /// `version` and `help` arguments respectively. You may use the word `version` or `help` for
340    /// the long form of your own arguments, in which case `clap` simply will not assign those to
341    /// the auto-generated `version` or `help` arguments.
342    ///
343    /// **NOTE:** Any leading `-` characters will be stripped
344    ///
345    /// # Examples
346    ///
347    /// To set `long` use a word containing valid UTF-8 codepoints. If you supply a double leading
348    /// `--` such as `--config` they will be stripped. Hyphens in the middle of the word, however,
349    /// will *not* be stripped (i.e. `config-file` is allowed)
350    ///
351    /// ```rust
352    /// # use clap::{App, Arg};
353    /// Arg::with_name("cfg")
354    ///     .long("config")
355    /// # ;
356    /// ```
357    ///
358    /// Setting `long` allows using the argument via a double hyphen (`--`) such as `--config`
359    ///
360    /// ```rust
361    /// # use clap::{App, Arg};
362    /// let m = App::new("prog")
363    ///     .arg(Arg::with_name("cfg")
364    ///         .long("config"))
365    ///     .get_matches_from(vec![
366    ///         "prog", "--config"
367    ///     ]);
368    ///
369    /// assert!(m.is_present("cfg"));
370    /// ```
371    pub fn long(mut self, l: &'b str) -> Self {
372        self.s.long = Some(l.trim_left_matches(|c| c == '-'));
373        self
374    }
375
376    /// Allows adding a [`Arg`] alias, which function as "hidden" arguments that
377    /// automatically dispatch as if this argument was used. This is more efficient, and easier
378    /// than creating multiple hidden arguments as one only needs to check for the existence of
379    /// this command, and not all variants.
380    ///
381    /// # Examples
382    ///
383    /// ```rust
384    /// # use clap::{App, Arg};
385    /// let m = App::new("prog")
386    ///             .arg(Arg::with_name("test")
387    ///             .long("test")
388    ///             .alias("alias")
389    ///             .takes_value(true))
390    ///        .get_matches_from(vec![
391    ///             "prog", "--alias", "cool"
392    ///         ]);
393    /// assert!(m.is_present("test"));
394    /// assert_eq!(m.value_of("test"), Some("cool"));
395    /// ```
396    /// [`Arg`]: ./struct.Arg.html
397    pub fn alias<S: Into<&'b str>>(mut self, name: S) -> Self {
398        if let Some(ref mut als) = self.s.aliases {
399            als.push((name.into(), false));
400        } else {
401            self.s.aliases = Some(vec![(name.into(), false)]);
402        }
403        self
404    }
405
406    /// Allows adding [`Arg`] aliases, which function as "hidden" arguments that
407    /// automatically dispatch as if this argument was used. This is more efficient, and easier
408    /// than creating multiple hidden subcommands as one only needs to check for the existence of
409    /// this command, and not all variants.
410    ///
411    /// # Examples
412    ///
413    /// ```rust
414    /// # use clap::{App, Arg};
415    /// let m = App::new("prog")
416    ///             .arg(Arg::with_name("test")
417    ///                     .long("test")
418    ///                     .aliases(&["do-stuff", "do-tests", "tests"])
419    ///                     .help("the file to add")
420    ///                     .required(false))
421    ///             .get_matches_from(vec![
422    ///                 "prog", "--do-tests"
423    ///             ]);
424    /// assert!(m.is_present("test"));
425    /// ```
426    /// [`Arg`]: ./struct.Arg.html
427    pub fn aliases(mut self, names: &[&'b str]) -> Self {
428        if let Some(ref mut als) = self.s.aliases {
429            for n in names {
430                als.push((n, false));
431            }
432        } else {
433            self.s.aliases = Some(names.iter().map(|n| (*n, false)).collect::<Vec<_>>());
434        }
435        self
436    }
437
438    /// Allows adding a [`Arg`] alias that functions exactly like those defined with
439    /// [`Arg::alias`], except that they are visible inside the help message.
440    ///
441    /// # Examples
442    ///
443    /// ```rust
444    /// # use clap::{App, Arg};
445    /// let m = App::new("prog")
446    ///             .arg(Arg::with_name("test")
447    ///                 .visible_alias("something-awesome")
448    ///                 .long("test")
449    ///                 .takes_value(true))
450    ///        .get_matches_from(vec![
451    ///             "prog", "--something-awesome", "coffee"
452    ///         ]);
453    /// assert!(m.is_present("test"));
454    /// assert_eq!(m.value_of("test"), Some("coffee"));
455    /// ```
456    /// [`Arg`]: ./struct.Arg.html
457    /// [`App::alias`]: ./struct.Arg.html#method.alias
458    pub fn visible_alias<S: Into<&'b str>>(mut self, name: S) -> Self {
459        if let Some(ref mut als) = self.s.aliases {
460            als.push((name.into(), true));
461        } else {
462            self.s.aliases = Some(vec![(name.into(), true)]);
463        }
464        self
465    }
466
467    /// Allows adding multiple [`Arg`] aliases that functions exactly like those defined
468    /// with [`Arg::aliases`], except that they are visible inside the help message.
469    ///
470    /// # Examples
471    ///
472    /// ```rust
473    /// # use clap::{App, Arg};
474    /// let m = App::new("prog")
475    ///             .arg(Arg::with_name("test")
476    ///                 .long("test")
477    ///                 .visible_aliases(&["something", "awesome", "cool"]))
478    ///        .get_matches_from(vec![
479    ///             "prog", "--awesome"
480    ///         ]);
481    /// assert!(m.is_present("test"));
482    /// ```
483    /// [`Arg`]: ./struct.Arg.html
484    /// [`App::aliases`]: ./struct.Arg.html#method.aliases
485    pub fn visible_aliases(mut self, names: &[&'b str]) -> Self {
486        if let Some(ref mut als) = self.s.aliases {
487            for n in names {
488                als.push((n, true));
489            }
490        } else {
491            self.s.aliases = Some(names.iter().map(|n| (*n, true)).collect::<Vec<_>>());
492        }
493        self
494    }
495
496    /// Sets the short help text of the argument that will be displayed to the user when they print
497    /// the help information with `-h`. Typically, this is a short (one line) description of the
498    /// arg.
499    ///
500    /// **NOTE:** If only `Arg::help` is provided, and not [`Arg::long_help`] but the user requests
501    /// `--help` clap will still display the contents of `help` appropriately
502    ///
503    /// **NOTE:** Only `Arg::help` is used in completion script generation in order to be concise
504    ///
505    /// # Examples
506    ///
507    /// Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to
508    /// include a newline in the help text and have the following text be properly aligned with all
509    /// the other help text.
510    ///
511    /// ```rust
512    /// # use clap::{App, Arg};
513    /// Arg::with_name("config")
514    ///     .help("The config file used by the myprog")
515    /// # ;
516    /// ```
517    ///
518    /// Setting `help` displays a short message to the side of the argument when the user passes
519    /// `-h` or `--help` (by default).
520    ///
521    /// ```rust
522    /// # use clap::{App, Arg};
523    /// let m = App::new("prog")
524    ///     .arg(Arg::with_name("cfg")
525    ///         .long("config")
526    ///         .help("Some help text describing the --config arg"))
527    ///     .get_matches_from(vec![
528    ///         "prog", "--help"
529    ///     ]);
530    /// ```
531    ///
532    /// The above example displays
533    ///
534    /// ```notrust
535    /// helptest
536    ///
537    /// USAGE:
538    ///    helptest [FLAGS]
539    ///
540    /// FLAGS:
541    ///     --config     Some help text describing the --config arg
542    /// -h, --help       Prints help information
543    /// -V, --version    Prints version information
544    /// ```
545    /// [`Arg::long_help`]: ./struct.Arg.html#method.long_help
546    pub fn help(mut self, h: &'b str) -> Self {
547        self.b.help = Some(h);
548        self
549    }
550
551    /// Sets the long help text of the argument that will be displayed to the user when they print
552    /// the help information with `--help`. Typically this a more detailed (multi-line) message
553    /// that describes the arg.
554    ///
555    /// **NOTE:** If only `long_help` is provided, and not [`Arg::help`] but the user requests `-h`
556    /// clap will still display the contents of `long_help` appropriately
557    ///
558    /// **NOTE:** Only [`Arg::help`] is used in completion script generation in order to be concise
559    ///
560    /// # Examples
561    ///
562    /// Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to
563    /// include a newline in the help text and have the following text be properly aligned with all
564    /// the other help text.
565    ///
566    /// ```rust
567    /// # use clap::{App, Arg};
568    /// Arg::with_name("config")
569    ///     .long_help(
570    /// "The config file used by the myprog must be in JSON format
571    /// with only valid keys and may not contain other nonsense
572    /// that cannot be read by this program. Obviously I'm going on
573    /// and on, so I'll stop now.")
574    /// # ;
575    /// ```
576    ///
577    /// Setting `help` displays a short message to the side of the argument when the user passes
578    /// `-h` or `--help` (by default).
579    ///
580    /// ```rust
581    /// # use clap::{App, Arg};
582    /// let m = App::new("prog")
583    ///     .arg(Arg::with_name("cfg")
584    ///         .long("config")
585    ///         .long_help(
586    /// "The config file used by the myprog must be in JSON format
587    /// with only valid keys and may not contain other nonsense
588    /// that cannot be read by this program. Obviously I'm going on
589    /// and on, so I'll stop now."))
590    ///     .get_matches_from(vec![
591    ///         "prog", "--help"
592    ///     ]);
593    /// ```
594    ///
595    /// The above example displays
596    ///
597    /// ```notrust
598    /// helptest
599    ///
600    /// USAGE:
601    ///    helptest [FLAGS]
602    ///
603    /// FLAGS:
604    ///    --config
605    ///         The config file used by the myprog must be in JSON format
606    ///         with only valid keys and may not contain other nonsense
607    ///         that cannot be read by this program. Obviously I'm going on
608    ///         and on, so I'll stop now.
609    ///
610    /// -h, --help
611    ///         Prints help information
612    ///
613    /// -V, --version
614    ///         Prints version information
615    /// ```
616    /// [`Arg::help`]: ./struct.Arg.html#method.help
617    pub fn long_help(mut self, h: &'b str) -> Self {
618        self.b.long_help = Some(h);
619        self
620    }
621
622    /// Specifies that this arg is the last, or final, positional argument (i.e. has the highest
623    /// index) and is *only* able to be accessed via the `--` syntax (i.e. `$ prog args --
624    /// last_arg`). Even, if no other arguments are left to parse, if the user omits the `--` syntax
625    /// they will receive an [`UnknownArgument`] error. Setting an argument to `.last(true)` also
626    /// allows one to access this arg early using the `--` syntax. Accessing an arg early, even with
627    /// the `--` syntax is otherwise not possible.
628    ///
629    /// **NOTE:** This will change the usage string to look like `$ prog [FLAGS] [-- <ARG>]` if
630    /// `ARG` is marked as `.last(true)`.
631    ///
632    /// **NOTE:** This setting will imply [`AppSettings::DontCollapseArgsInUsage`] because failing
633    /// to set this can make the usage string very confusing.
634    ///
635    /// **NOTE**: This setting only applies to positional arguments, and has no affect on FLAGS /
636    /// OPTIONS
637    ///
638    /// **CAUTION:** Setting an argument to `.last(true)` *and* having child subcommands is not
639    /// recommended with the exception of *also* using [`AppSettings::ArgsNegateSubcommands`]
640    /// (or [`AppSettings::SubcommandsNegateReqs`] if the argument marked `.last(true)` is also
641    /// marked [`.required(true)`])
642    ///
643    /// # Examples
644    ///
645    /// ```rust
646    /// # use clap::Arg;
647    /// Arg::with_name("args")
648    ///     .last(true)
649    /// # ;
650    /// ```
651    ///
652    /// Setting [`Arg::last(true)`] ensures the arg has the highest [index] of all positional args
653    /// and requires that the `--` syntax be used to access it early.
654    ///
655    /// ```rust
656    /// # use clap::{App, Arg};
657    /// let res = App::new("prog")
658    ///     .arg(Arg::with_name("first"))
659    ///     .arg(Arg::with_name("second"))
660    ///     .arg(Arg::with_name("third").last(true))
661    ///     .get_matches_from_safe(vec![
662    ///         "prog", "one", "--", "three"
663    ///     ]);
664    ///
665    /// assert!(res.is_ok());
666    /// let m = res.unwrap();
667    /// assert_eq!(m.value_of("third"), Some("three"));
668    /// assert!(m.value_of("second").is_none());
669    /// ```
670    ///
671    /// Even if the positional argument marked `.last(true)` is the only argument left to parse,
672    /// failing to use the `--` syntax results in an error.
673    ///
674    /// ```rust
675    /// # use clap::{App, Arg, ErrorKind};
676    /// let res = App::new("prog")
677    ///     .arg(Arg::with_name("first"))
678    ///     .arg(Arg::with_name("second"))
679    ///     .arg(Arg::with_name("third").last(true))
680    ///     .get_matches_from_safe(vec![
681    ///         "prog", "one", "two", "three"
682    ///     ]);
683    ///
684    /// assert!(res.is_err());
685    /// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
686    /// ```
687    /// [`Arg::last(true)`]: ./struct.Arg.html#method.last
688    /// [index]: ./struct.Arg.html#method.index
689    /// [`AppSettings::DontCollapseArgsInUsage`]: ./enum.AppSettings.html#variant.DontCollapseArgsInUsage
690    /// [`AppSettings::ArgsNegateSubcommands`]: ./enum.AppSettings.html#variant.ArgsNegateSubcommands
691    /// [`AppSettings::SubcommandsNegateReqs`]: ./enum.AppSettings.html#variant.SubcommandsNegateReqs
692    /// [`.required(true)`]: ./struct.Arg.html#method.required
693    /// [`UnknownArgument`]: ./enum.ErrorKind.html#variant.UnknownArgument
694    pub fn last(self, l: bool) -> Self {
695        if l {
696            self.set(ArgSettings::Last)
697        } else {
698            self.unset(ArgSettings::Last)
699        }
700    }
701
702    /// Sets whether or not the argument is required by default. Required by default means it is
703    /// required, when no other conflicting rules have been evaluated. Conflicting rules take
704    /// precedence over being required. **Default:** `false`
705    ///
706    /// **NOTE:** Flags (i.e. not positional, or arguments that take values) cannot be required by
707    /// default. This is simply because if a flag should be required, it should simply be implied
708    /// as no additional information is required from user. Flags by their very nature are simply
709    /// yes/no, or true/false.
710    ///
711    /// # Examples
712    ///
713    /// ```rust
714    /// # use clap::Arg;
715    /// Arg::with_name("config")
716    ///     .required(true)
717    /// # ;
718    /// ```
719    ///
720    /// Setting [`Arg::required(true)`] requires that the argument be used at runtime.
721    ///
722    /// ```rust
723    /// # use clap::{App, Arg};
724    /// let res = App::new("prog")
725    ///     .arg(Arg::with_name("cfg")
726    ///         .required(true)
727    ///         .takes_value(true)
728    ///         .long("config"))
729    ///     .get_matches_from_safe(vec![
730    ///         "prog", "--config", "file.conf"
731    ///     ]);
732    ///
733    /// assert!(res.is_ok());
734    /// ```
735    ///
736    /// Setting [`Arg::required(true)`] and *not* supplying that argument is an error.
737    ///
738    /// ```rust
739    /// # use clap::{App, Arg, ErrorKind};
740    /// let res = App::new("prog")
741    ///     .arg(Arg::with_name("cfg")
742    ///         .required(true)
743    ///         .takes_value(true)
744    ///         .long("config"))
745    ///     .get_matches_from_safe(vec![
746    ///         "prog"
747    ///     ]);
748    ///
749    /// assert!(res.is_err());
750    /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
751    /// ```
752    /// [`Arg::required(true)`]: ./struct.Arg.html#method.required
753    pub fn required(self, r: bool) -> Self {
754        if r {
755            self.set(ArgSettings::Required)
756        } else {
757            self.unset(ArgSettings::Required)
758        }
759    }
760
761    /// Requires that options use the `--option=val` syntax (i.e. an equals between the option and
762    /// associated value) **Default:** `false`
763    ///
764    /// **NOTE:** This setting also removes the default of allowing empty values and implies
765    /// [`Arg::empty_values(false)`].
766    ///
767    /// # Examples
768    ///
769    /// ```rust
770    /// # use clap::Arg;
771    /// Arg::with_name("config")
772    ///     .long("config")
773    ///     .takes_value(true)
774    ///     .require_equals(true)
775    /// # ;
776    /// ```
777    ///
778    /// Setting [`Arg::require_equals(true)`] requires that the option have an equals sign between
779    /// it and the associated value.
780    ///
781    /// ```rust
782    /// # use clap::{App, Arg};
783    /// let res = App::new("prog")
784    ///     .arg(Arg::with_name("cfg")
785    ///         .require_equals(true)
786    ///         .takes_value(true)
787    ///         .long("config"))
788    ///     .get_matches_from_safe(vec![
789    ///         "prog", "--config=file.conf"
790    ///     ]);
791    ///
792    /// assert!(res.is_ok());
793    /// ```
794    ///
795    /// Setting [`Arg::require_equals(true)`] and *not* supplying the equals will cause an error
796    /// unless [`Arg::empty_values(true)`] is set.
797    ///
798    /// ```rust
799    /// # use clap::{App, Arg, ErrorKind};
800    /// let res = App::new("prog")
801    ///     .arg(Arg::with_name("cfg")
802    ///         .require_equals(true)
803    ///         .takes_value(true)
804    ///         .long("config"))
805    ///     .get_matches_from_safe(vec![
806    ///         "prog", "--config", "file.conf"
807    ///     ]);
808    ///
809    /// assert!(res.is_err());
810    /// assert_eq!(res.unwrap_err().kind, ErrorKind::EmptyValue);
811    /// ```
812    /// [`Arg::require_equals(true)`]: ./struct.Arg.html#method.require_equals
813    /// [`Arg::empty_values(true)`]: ./struct.Arg.html#method.empty_values
814    /// [`Arg::empty_values(false)`]: ./struct.Arg.html#method.empty_values
815    pub fn require_equals(mut self, r: bool) -> Self {
816        if r {
817            self.unsetb(ArgSettings::EmptyValues);
818            self.set(ArgSettings::RequireEquals)
819        } else {
820            self.unset(ArgSettings::RequireEquals)
821        }
822    }
823
824    /// Allows values which start with a leading hyphen (`-`)
825    ///
826    /// **WARNING**: Take caution when using this setting combined with [`Arg::multiple(true)`], as
827    /// this becomes ambiguous `$ prog --arg -- -- val`. All three `--, --, val` will be values
828    /// when the user may have thought the second `--` would constitute the normal, "Only
829    /// positional args follow" idiom. To fix this, consider using [`Arg::number_of_values(1)`]
830    ///
831    /// **WARNING**: When building your CLIs, consider the effects of allowing leading hyphens and
832    /// the user passing in a value that matches a valid short. For example `prog -opt -F` where
833    /// `-F` is supposed to be a value, yet `-F` is *also* a valid short for another arg. Care should
834    /// should be taken when designing these args. This is compounded by the ability to "stack"
835    /// short args. I.e. if `-val` is supposed to be a value, but `-v`, `-a`, and `-l` are all valid
836    /// shorts.
837    ///
838    /// # Examples
839    ///
840    /// ```rust
841    /// # use clap::Arg;
842    /// Arg::with_name("pattern")
843    ///     .allow_hyphen_values(true)
844    /// # ;
845    /// ```
846    ///
847    /// ```rust
848    /// # use clap::{App, Arg};
849    /// let m = App::new("prog")
850    ///     .arg(Arg::with_name("pat")
851    ///         .allow_hyphen_values(true)
852    ///         .takes_value(true)
853    ///         .long("pattern"))
854    ///     .get_matches_from(vec![
855    ///         "prog", "--pattern", "-file"
856    ///     ]);
857    ///
858    /// assert_eq!(m.value_of("pat"), Some("-file"));
859    /// ```
860    ///
861    /// Not setting [`Arg::allow_hyphen_values(true)`] and supplying a value which starts with a
862    /// hyphen is an error.
863    ///
864    /// ```rust
865    /// # use clap::{App, Arg, ErrorKind};
866    /// let res = App::new("prog")
867    ///     .arg(Arg::with_name("pat")
868    ///         .takes_value(true)
869    ///         .long("pattern"))
870    ///     .get_matches_from_safe(vec![
871    ///         "prog", "--pattern", "-file"
872    ///     ]);
873    ///
874    /// assert!(res.is_err());
875    /// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
876    /// ```
877    /// [`Arg::allow_hyphen_values(true)`]: ./struct.Arg.html#method.allow_hyphen_values
878    /// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
879    /// [`Arg::number_of_values(1)`]: ./struct.Arg.html#method.number_of_values
880    pub fn allow_hyphen_values(self, a: bool) -> Self {
881        if a {
882            self.set(ArgSettings::AllowLeadingHyphen)
883        } else {
884            self.unset(ArgSettings::AllowLeadingHyphen)
885        }
886    }
887    /// Sets an arg that override this arg's required setting. (i.e. this arg will be required
888    /// unless this other argument is present).
889    ///
890    /// **Pro Tip:** Using [`Arg::required_unless`] implies [`Arg::required`] and is therefore not
891    /// mandatory to also set.
892    ///
893    /// # Examples
894    ///
895    /// ```rust
896    /// # use clap::Arg;
897    /// Arg::with_name("config")
898    ///     .required_unless("debug")
899    /// # ;
900    /// ```
901    ///
902    /// Setting [`Arg::required_unless(name)`] requires that the argument be used at runtime
903    /// *unless* `name` is present. In the following example, the required argument is *not*
904    /// provided, but it's not an error because the `unless` arg has been supplied.
905    ///
906    /// ```rust
907    /// # use clap::{App, Arg};
908    /// let res = App::new("prog")
909    ///     .arg(Arg::with_name("cfg")
910    ///         .required_unless("dbg")
911    ///         .takes_value(true)
912    ///         .long("config"))
913    ///     .arg(Arg::with_name("dbg")
914    ///         .long("debug"))
915    ///     .get_matches_from_safe(vec![
916    ///         "prog", "--debug"
917    ///     ]);
918    ///
919    /// assert!(res.is_ok());
920    /// ```
921    ///
922    /// Setting [`Arg::required_unless(name)`] and *not* supplying `name` or this arg is an error.
923    ///
924    /// ```rust
925    /// # use clap::{App, Arg, ErrorKind};
926    /// let res = App::new("prog")
927    ///     .arg(Arg::with_name("cfg")
928    ///         .required_unless("dbg")
929    ///         .takes_value(true)
930    ///         .long("config"))
931    ///     .arg(Arg::with_name("dbg")
932    ///         .long("debug"))
933    ///     .get_matches_from_safe(vec![
934    ///         "prog"
935    ///     ]);
936    ///
937    /// assert!(res.is_err());
938    /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
939    /// ```
940    /// [`Arg::required_unless`]: ./struct.Arg.html#method.required_unless
941    /// [`Arg::required`]: ./struct.Arg.html#method.required
942    /// [`Arg::required_unless(name)`]: ./struct.Arg.html#method.required_unless
943    pub fn required_unless(mut self, name: &'a str) -> Self {
944        if let Some(ref mut vec) = self.b.r_unless {
945            vec.push(name);
946        } else {
947            self.b.r_unless = Some(vec![name]);
948        }
949        self.required(true)
950    }
951
952    /// Sets args that override this arg's required setting. (i.e. this arg will be required unless
953    /// all these other arguments are present).
954    ///
955    /// **NOTE:** If you wish for this argument to only be required if *one of* these args are
956    /// present see [`Arg::required_unless_one`]
957    ///
958    /// # Examples
959    ///
960    /// ```rust
961    /// # use clap::Arg;
962    /// Arg::with_name("config")
963    ///     .required_unless_all(&["cfg", "dbg"])
964    /// # ;
965    /// ```
966    ///
967    /// Setting [`Arg::required_unless_all(names)`] requires that the argument be used at runtime
968    /// *unless* *all* the args in `names` are present. In the following example, the required
969    /// argument is *not* provided, but it's not an error because all the `unless` args have been
970    /// supplied.
971    ///
972    /// ```rust
973    /// # use clap::{App, Arg};
974    /// let res = App::new("prog")
975    ///     .arg(Arg::with_name("cfg")
976    ///         .required_unless_all(&["dbg", "infile"])
977    ///         .takes_value(true)
978    ///         .long("config"))
979    ///     .arg(Arg::with_name("dbg")
980    ///         .long("debug"))
981    ///     .arg(Arg::with_name("infile")
982    ///         .short("i")
983    ///         .takes_value(true))
984    ///     .get_matches_from_safe(vec![
985    ///         "prog", "--debug", "-i", "file"
986    ///     ]);
987    ///
988    /// assert!(res.is_ok());
989    /// ```
990    ///
991    /// Setting [`Arg::required_unless_all(names)`] and *not* supplying *all* of `names` or this
992    /// arg is an error.
993    ///
994    /// ```rust
995    /// # use clap::{App, Arg, ErrorKind};
996    /// let res = App::new("prog")
997    ///     .arg(Arg::with_name("cfg")
998    ///         .required_unless_all(&["dbg", "infile"])
999    ///         .takes_value(true)
1000    ///         .long("config"))
1001    ///     .arg(Arg::with_name("dbg")
1002    ///         .long("debug"))
1003    ///     .arg(Arg::with_name("infile")
1004    ///         .short("i")
1005    ///         .takes_value(true))
1006    ///     .get_matches_from_safe(vec![
1007    ///         "prog"
1008    ///     ]);
1009    ///
1010    /// assert!(res.is_err());
1011    /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
1012    /// ```
1013    /// [`Arg::required_unless_one`]: ./struct.Arg.html#method.required_unless_one
1014    /// [`Arg::required_unless_all(names)`]: ./struct.Arg.html#method.required_unless_all
1015    pub fn required_unless_all(mut self, names: &[&'a str]) -> Self {
1016        if let Some(ref mut vec) = self.b.r_unless {
1017            for s in names {
1018                vec.push(s);
1019            }
1020        } else {
1021            self.b.r_unless = Some(names.iter().map(|s| *s).collect::<Vec<_>>());
1022        }
1023        self.setb(ArgSettings::RequiredUnlessAll);
1024        self.required(true)
1025    }
1026
1027    /// Sets args that override this arg's [required] setting. (i.e. this arg will be required
1028    /// unless *at least one of* these other arguments are present).
1029    ///
1030    /// **NOTE:** If you wish for this argument to only be required if *all of* these args are
1031    /// present see [`Arg::required_unless_all`]
1032    ///
1033    /// # Examples
1034    ///
1035    /// ```rust
1036    /// # use clap::Arg;
1037    /// Arg::with_name("config")
1038    ///     .required_unless_all(&["cfg", "dbg"])
1039    /// # ;
1040    /// ```
1041    ///
1042    /// Setting [`Arg::required_unless_one(names)`] requires that the argument be used at runtime
1043    /// *unless* *at least one of* the args in `names` are present. In the following example, the
1044    /// required argument is *not* provided, but it's not an error because one the `unless` args
1045    /// have been supplied.
1046    ///
1047    /// ```rust
1048    /// # use clap::{App, Arg};
1049    /// let res = App::new("prog")
1050    ///     .arg(Arg::with_name("cfg")
1051    ///         .required_unless_one(&["dbg", "infile"])
1052    ///         .takes_value(true)
1053    ///         .long("config"))
1054    ///     .arg(Arg::with_name("dbg")
1055    ///         .long("debug"))
1056    ///     .arg(Arg::with_name("infile")
1057    ///         .short("i")
1058    ///         .takes_value(true))
1059    ///     .get_matches_from_safe(vec![
1060    ///         "prog", "--debug"
1061    ///     ]);
1062    ///
1063    /// assert!(res.is_ok());
1064    /// ```
1065    ///
1066    /// Setting [`Arg::required_unless_one(names)`] and *not* supplying *at least one of* `names`
1067    /// or this arg is an error.
1068    ///
1069    /// ```rust
1070    /// # use clap::{App, Arg, ErrorKind};
1071    /// let res = App::new("prog")
1072    ///     .arg(Arg::with_name("cfg")
1073    ///         .required_unless_one(&["dbg", "infile"])
1074    ///         .takes_value(true)
1075    ///         .long("config"))
1076    ///     .arg(Arg::with_name("dbg")
1077    ///         .long("debug"))
1078    ///     .arg(Arg::with_name("infile")
1079    ///         .short("i")
1080    ///         .takes_value(true))
1081    ///     .get_matches_from_safe(vec![
1082    ///         "prog"
1083    ///     ]);
1084    ///
1085    /// assert!(res.is_err());
1086    /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
1087    /// ```
1088    /// [required]: ./struct.Arg.html#method.required
1089    /// [`Arg::required_unless_one(names)`]: ./struct.Arg.html#method.required_unless_one
1090    /// [`Arg::required_unless_all`]: ./struct.Arg.html#method.required_unless_all
1091    pub fn required_unless_one(mut self, names: &[&'a str]) -> Self {
1092        if let Some(ref mut vec) = self.b.r_unless {
1093            for s in names {
1094                vec.push(s);
1095            }
1096        } else {
1097            self.b.r_unless = Some(names.iter().map(|s| *s).collect::<Vec<_>>());
1098        }
1099        self.required(true)
1100    }
1101
1102    /// Sets a conflicting argument by name. I.e. when using this argument,
1103    /// the following argument can't be present and vice versa.
1104    ///
1105    /// **NOTE:** Conflicting rules take precedence over being required by default. Conflict rules
1106    /// only need to be set for one of the two arguments, they do not need to be set for each.
1107    ///
1108    /// **NOTE:** Defining a conflict is two-way, but does *not* need to defined for both arguments
1109    /// (i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not need
1110    /// need to also do B.conflicts_with(A))
1111    ///
1112    /// # Examples
1113    ///
1114    /// ```rust
1115    /// # use clap::Arg;
1116    /// Arg::with_name("config")
1117    ///     .conflicts_with("debug")
1118    /// # ;
1119    /// ```
1120    ///
1121    /// Setting conflicting argument, and having both arguments present at runtime is an error.
1122    ///
1123    /// ```rust
1124    /// # use clap::{App, Arg, ErrorKind};
1125    /// let res = App::new("prog")
1126    ///     .arg(Arg::with_name("cfg")
1127    ///         .takes_value(true)
1128    ///         .conflicts_with("debug")
1129    ///         .long("config"))
1130    ///     .arg(Arg::with_name("debug")
1131    ///         .long("debug"))
1132    ///     .get_matches_from_safe(vec![
1133    ///         "prog", "--debug", "--config", "file.conf"
1134    ///     ]);
1135    ///
1136    /// assert!(res.is_err());
1137    /// assert_eq!(res.unwrap_err().kind, ErrorKind::ArgumentConflict);
1138    /// ```
1139    pub fn conflicts_with(mut self, name: &'a str) -> Self {
1140        if let Some(ref mut vec) = self.b.blacklist {
1141            vec.push(name);
1142        } else {
1143            self.b.blacklist = Some(vec![name]);
1144        }
1145        self
1146    }
1147
1148    /// The same as [`Arg::conflicts_with`] but allows specifying multiple two-way conlicts per
1149    /// argument.
1150    ///
1151    /// **NOTE:** Conflicting rules take precedence over being required by default. Conflict rules
1152    /// only need to be set for one of the two arguments, they do not need to be set for each.
1153    ///
1154    /// **NOTE:** Defining a conflict is two-way, but does *not* need to defined for both arguments
1155    /// (i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not need
1156    /// need to also do B.conflicts_with(A))
1157    ///
1158    /// # Examples
1159    ///
1160    /// ```rust
1161    /// # use clap::Arg;
1162    /// Arg::with_name("config")
1163    ///     .conflicts_with_all(&["debug", "input"])
1164    /// # ;
1165    /// ```
1166    ///
1167    /// Setting conflicting argument, and having any of the arguments present at runtime with a
1168    /// conflicting argument is an error.
1169    ///
1170    /// ```rust
1171    /// # use clap::{App, Arg, ErrorKind};
1172    /// let res = App::new("prog")
1173    ///     .arg(Arg::with_name("cfg")
1174    ///         .takes_value(true)
1175    ///         .conflicts_with_all(&["debug", "input"])
1176    ///         .long("config"))
1177    ///     .arg(Arg::with_name("debug")
1178    ///         .long("debug"))
1179    ///     .arg(Arg::with_name("input")
1180    ///         .index(1))
1181    ///     .get_matches_from_safe(vec![
1182    ///         "prog", "--config", "file.conf", "file.txt"
1183    ///     ]);
1184    ///
1185    /// assert!(res.is_err());
1186    /// assert_eq!(res.unwrap_err().kind, ErrorKind::ArgumentConflict);
1187    /// ```
1188    /// [`Arg::conflicts_with`]: ./struct.Arg.html#method.conflicts_with
1189    pub fn conflicts_with_all(mut self, names: &[&'a str]) -> Self {
1190        if let Some(ref mut vec) = self.b.blacklist {
1191            for s in names {
1192                vec.push(s);
1193            }
1194        } else {
1195            self.b.blacklist = Some(names.iter().map(|s| *s).collect::<Vec<_>>());
1196        }
1197        self
1198    }
1199
1200    /// Sets a overridable argument by name. I.e. this argument and the following argument
1201    /// will override each other in POSIX style (whichever argument was specified at runtime
1202    /// **last** "wins")
1203    ///
1204    /// **NOTE:** When an argument is overridden it is essentially as if it never was used, any
1205    /// conflicts, requirements, etc. are evaluated **after** all "overrides" have been removed
1206    ///
1207    /// **WARNING:** Positional arguments cannot override themselves (or we would never be able
1208    /// to advance to the next positional). If a positional agument lists itself as an override,
1209    /// it is simply ignored.
1210    ///
1211    /// # Examples
1212    ///
1213    /// ```rust
1214    /// # use clap::{App, Arg};
1215    /// let m = App::new("prog")
1216    ///     .arg(Arg::from_usage("-f, --flag 'some flag'")
1217    ///         .conflicts_with("debug"))
1218    ///     .arg(Arg::from_usage("-d, --debug 'other flag'"))
1219    ///     .arg(Arg::from_usage("-c, --color 'third flag'")
1220    ///         .overrides_with("flag"))
1221    ///     .get_matches_from(vec![
1222    ///         "prog", "-f", "-d", "-c"]);
1223    ///             //    ^~~~~~~~~~~~^~~~~ flag is overridden by color
1224    ///
1225    /// assert!(m.is_present("color"));
1226    /// assert!(m.is_present("debug")); // even though flag conflicts with debug, it's as if flag
1227    ///                                 // was never used because it was overridden with color
1228    /// assert!(!m.is_present("flag"));
1229    /// ```
1230    /// Care must be taken when using this setting, and having an arg override with itself. This
1231    /// is common practice when supporting things like shell aliases, config files, etc.
1232    /// However, when combined with multiple values, it can get dicy.
1233    /// Here is how clap handles such situations:
1234    ///
1235    /// When a flag overrides itself, it's as if the flag was only ever used once (essentially
1236    /// preventing a "Unexpected multiple usage" error):
1237    ///
1238    /// ```rust
1239    /// # use clap::{App, Arg};
1240    /// let m = App::new("posix")
1241    ///             .arg(Arg::from_usage("--flag  'some flag'").overrides_with("flag"))
1242    ///             .get_matches_from(vec!["posix", "--flag", "--flag"]);
1243    /// assert!(m.is_present("flag"));
1244    /// assert_eq!(m.occurrences_of("flag"), 1);
1245    /// ```
1246    /// Making a arg `multiple(true)` and override itself is essentially meaningless. Therefore
1247    /// clap ignores an override of self if it's a flag and it already accepts multiple occurrences.
1248    ///
1249    /// ```
1250    /// # use clap::{App, Arg};
1251    /// let m = App::new("posix")
1252    ///             .arg(Arg::from_usage("--flag...  'some flag'").overrides_with("flag"))
1253    ///             .get_matches_from(vec!["", "--flag", "--flag", "--flag", "--flag"]);
1254    /// assert!(m.is_present("flag"));
1255    /// assert_eq!(m.occurrences_of("flag"), 4);
1256    /// ```
1257    /// Now notice with options (which *do not* set `multiple(true)`), it's as if only the last
1258    /// occurrence happened.
1259    ///
1260    /// ```
1261    /// # use clap::{App, Arg};
1262    /// let m = App::new("posix")
1263    ///             .arg(Arg::from_usage("--opt [val] 'some option'").overrides_with("opt"))
1264    ///             .get_matches_from(vec!["", "--opt=some", "--opt=other"]);
1265    /// assert!(m.is_present("opt"));
1266    /// assert_eq!(m.occurrences_of("opt"), 1);
1267    /// assert_eq!(m.value_of("opt"), Some("other"));
1268    /// ```
1269    ///
1270    /// Just like flags, options with `multiple(true)` set, will ignore the "override self" setting.
1271    ///
1272    /// ```
1273    /// # use clap::{App, Arg};
1274    /// let m = App::new("posix")
1275    ///             .arg(Arg::from_usage("--opt [val]... 'some option'")
1276    ///                 .overrides_with("opt"))
1277    ///             .get_matches_from(vec!["", "--opt", "first", "over", "--opt", "other", "val"]);
1278    /// assert!(m.is_present("opt"));
1279    /// assert_eq!(m.occurrences_of("opt"), 2);
1280    /// assert_eq!(m.values_of("opt").unwrap().collect::<Vec<_>>(), &["first", "over", "other", "val"]);
1281    /// ```
1282    ///
1283    /// A safe thing to do if you'd like to support an option which supports multiple values, but
1284    /// also is "overridable" by itself, is to use `use_delimiter(false)` and *not* use
1285    /// `multiple(true)` while telling users to seperate values with a comma (i.e. `val1,val2`)
1286    ///
1287    /// ```
1288    /// # use clap::{App, Arg};
1289    /// let m = App::new("posix")
1290    ///             .arg(Arg::from_usage("--opt [val] 'some option'")
1291    ///                 .overrides_with("opt")
1292    ///                 .use_delimiter(false))
1293    ///             .get_matches_from(vec!["", "--opt=some,other", "--opt=one,two"]);
1294    /// assert!(m.is_present("opt"));
1295    /// assert_eq!(m.occurrences_of("opt"), 1);
1296    /// assert_eq!(m.values_of("opt").unwrap().collect::<Vec<_>>(), &["one,two"]);
1297    /// ```
1298    pub fn overrides_with(mut self, name: &'a str) -> Self {
1299        if let Some(ref mut vec) = self.b.overrides {
1300            vec.push(name);
1301        } else {
1302            self.b.overrides = Some(vec![name]);
1303        }
1304        self
1305    }
1306
1307    /// Sets multiple mutually overridable arguments by name. I.e. this argument and the following
1308    /// argument will override each other in POSIX style (whichever argument was specified at
1309    /// runtime **last** "wins")
1310    ///
1311    /// **NOTE:** When an argument is overridden it is essentially as if it never was used, any
1312    /// conflicts, requirements, etc. are evaluated **after** all "overrides" have been removed
1313    ///
1314    /// # Examples
1315    ///
1316    /// ```rust
1317    /// # use clap::{App, Arg};
1318    /// let m = App::new("prog")
1319    ///     .arg(Arg::from_usage("-f, --flag 'some flag'")
1320    ///         .conflicts_with("color"))
1321    ///     .arg(Arg::from_usage("-d, --debug 'other flag'"))
1322    ///     .arg(Arg::from_usage("-c, --color 'third flag'")
1323    ///         .overrides_with_all(&["flag", "debug"]))
1324    ///     .get_matches_from(vec![
1325    ///         "prog", "-f", "-d", "-c"]);
1326    ///             //    ^~~~~~^~~~~~~~~ flag and debug are overridden by color
1327    ///
1328    /// assert!(m.is_present("color")); // even though flag conflicts with color, it's as if flag
1329    ///                                 // and debug were never used because they were overridden
1330    ///                                 // with color
1331    /// assert!(!m.is_present("debug"));
1332    /// assert!(!m.is_present("flag"));
1333    /// ```
1334    pub fn overrides_with_all(mut self, names: &[&'a str]) -> Self {
1335        if let Some(ref mut vec) = self.b.overrides {
1336            for s in names {
1337                vec.push(s);
1338            }
1339        } else {
1340            self.b.overrides = Some(names.iter().map(|s| *s).collect::<Vec<_>>());
1341        }
1342        self
1343    }
1344
1345    /// Sets an argument by name that is required when this one is present I.e. when
1346    /// using this argument, the following argument *must* be present.
1347    ///
1348    /// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required
1349    ///
1350    /// # Examples
1351    ///
1352    /// ```rust
1353    /// # use clap::Arg;
1354    /// Arg::with_name("config")
1355    ///     .requires("input")
1356    /// # ;
1357    /// ```
1358    ///
1359    /// Setting [`Arg::requires(name)`] requires that the argument be used at runtime if the
1360    /// defining argument is used. If the defining argument isn't used, the other argument isn't
1361    /// required
1362    ///
1363    /// ```rust
1364    /// # use clap::{App, Arg};
1365    /// let res = App::new("prog")
1366    ///     .arg(Arg::with_name("cfg")
1367    ///         .takes_value(true)
1368    ///         .requires("input")
1369    ///         .long("config"))
1370    ///     .arg(Arg::with_name("input")
1371    ///         .index(1))
1372    ///     .get_matches_from_safe(vec![
1373    ///         "prog"
1374    ///     ]);
1375    ///
1376    /// assert!(res.is_ok()); // We didn't use cfg, so input wasn't required
1377    /// ```
1378    ///
1379    /// Setting [`Arg::requires(name)`] and *not* supplying that argument is an error.
1380    ///
1381    /// ```rust
1382    /// # use clap::{App, Arg, ErrorKind};
1383    /// let res = App::new("prog")
1384    ///     .arg(Arg::with_name("cfg")
1385    ///         .takes_value(true)
1386    ///         .requires("input")
1387    ///         .long("config"))
1388    ///     .arg(Arg::with_name("input")
1389    ///         .index(1))
1390    ///     .get_matches_from_safe(vec![
1391    ///         "prog", "--config", "file.conf"
1392    ///     ]);
1393    ///
1394    /// assert!(res.is_err());
1395    /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
1396    /// ```
1397    /// [`Arg::requires(name)`]: ./struct.Arg.html#method.requires
1398    /// [Conflicting]: ./struct.Arg.html#method.conflicts_with
1399    /// [override]: ./struct.Arg.html#method.overrides_with
1400    pub fn requires(mut self, name: &'a str) -> Self {
1401        if let Some(ref mut vec) = self.b.requires {
1402            vec.push((None, name));
1403        } else {
1404            let mut vec = vec![];
1405            vec.push((None, name));
1406            self.b.requires = Some(vec);
1407        }
1408        self
1409    }
1410
1411    /// Allows a conditional requirement. The requirement will only become valid if this arg's value
1412    /// equals `val`.
1413    ///
1414    /// **NOTE:** If using YAML the values should be laid out as follows
1415    ///
1416    /// ```yaml
1417    /// requires_if:
1418    ///     - [val, arg]
1419    /// ```
1420    ///
1421    /// # Examples
1422    ///
1423    /// ```rust
1424    /// # use clap::Arg;
1425    /// Arg::with_name("config")
1426    ///     .requires_if("val", "arg")
1427    /// # ;
1428    /// ```
1429    ///
1430    /// Setting [`Arg::requires_if(val, arg)`] requires that the `arg` be used at runtime if the
1431    /// defining argument's value is equal to `val`. If the defining argument is anything other than
1432    /// `val`, the other argument isn't required.
1433    ///
1434    /// ```rust
1435    /// # use clap::{App, Arg};
1436    /// let res = App::new("prog")
1437    ///     .arg(Arg::with_name("cfg")
1438    ///         .takes_value(true)
1439    ///         .requires_if("my.cfg", "other")
1440    ///         .long("config"))
1441    ///     .arg(Arg::with_name("other"))
1442    ///     .get_matches_from_safe(vec![
1443    ///         "prog", "--config", "some.cfg"
1444    ///     ]);
1445    ///
1446    /// assert!(res.is_ok()); // We didn't use --config=my.cfg, so other wasn't required
1447    /// ```
1448    ///
1449    /// Setting [`Arg::requires_if(val, arg)`] and setting the value to `val` but *not* supplying
1450    /// `arg` is an error.
1451    ///
1452    /// ```rust
1453    /// # use clap::{App, Arg, ErrorKind};
1454    /// let res = App::new("prog")
1455    ///     .arg(Arg::with_name("cfg")
1456    ///         .takes_value(true)
1457    ///         .requires_if("my.cfg", "input")
1458    ///         .long("config"))
1459    ///     .arg(Arg::with_name("input"))
1460    ///     .get_matches_from_safe(vec![
1461    ///         "prog", "--config", "my.cfg"
1462    ///     ]);
1463    ///
1464    /// assert!(res.is_err());
1465    /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
1466    /// ```
1467    /// [`Arg::requires(name)`]: ./struct.Arg.html#method.requires
1468    /// [Conflicting]: ./struct.Arg.html#method.conflicts_with
1469    /// [override]: ./struct.Arg.html#method.overrides_with
1470    pub fn requires_if(mut self, val: &'b str, arg: &'a str) -> Self {
1471        if let Some(ref mut vec) = self.b.requires {
1472            vec.push((Some(val), arg));
1473        } else {
1474            self.b.requires = Some(vec![(Some(val), arg)]);
1475        }
1476        self
1477    }
1478
1479    /// Allows multiple conditional requirements. The requirement will only become valid if this arg's value
1480    /// equals `val`.
1481    ///
1482    /// **NOTE:** If using YAML the values should be laid out as follows
1483    ///
1484    /// ```yaml
1485    /// requires_if:
1486    ///     - [val, arg]
1487    ///     - [val2, arg2]
1488    /// ```
1489    ///
1490    /// # Examples
1491    ///
1492    /// ```rust
1493    /// # use clap::Arg;
1494    /// Arg::with_name("config")
1495    ///     .requires_ifs(&[
1496    ///         ("val", "arg"),
1497    ///         ("other_val", "arg2"),
1498    ///     ])
1499    /// # ;
1500    /// ```
1501    ///
1502    /// Setting [`Arg::requires_ifs(&["val", "arg"])`] requires that the `arg` be used at runtime if the
1503    /// defining argument's value is equal to `val`. If the defining argument's value is anything other
1504    /// than `val`, `arg` isn't required.
1505    ///
1506    /// ```rust
1507    /// # use clap::{App, Arg, ErrorKind};
1508    /// let res = App::new("prog")
1509    ///     .arg(Arg::with_name("cfg")
1510    ///         .takes_value(true)
1511    ///         .requires_ifs(&[
1512    ///             ("special.conf", "opt"),
1513    ///             ("other.conf", "other"),
1514    ///         ])
1515    ///         .long("config"))
1516    ///     .arg(Arg::with_name("opt")
1517    ///         .long("option")
1518    ///         .takes_value(true))
1519    ///     .arg(Arg::with_name("other"))
1520    ///     .get_matches_from_safe(vec![
1521    ///         "prog", "--config", "special.conf"
1522    ///     ]);
1523    ///
1524    /// assert!(res.is_err()); // We  used --config=special.conf so --option <val> is required
1525    /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
1526    /// ```
1527    /// [`Arg::requires(name)`]: ./struct.Arg.html#method.requires
1528    /// [Conflicting]: ./struct.Arg.html#method.conflicts_with
1529    /// [override]: ./struct.Arg.html#method.overrides_with
1530    pub fn requires_ifs(mut self, ifs: &[(&'b str, &'a str)]) -> Self {
1531        if let Some(ref mut vec) = self.b.requires {
1532            for &(val, arg) in ifs {
1533                vec.push((Some(val), arg));
1534            }
1535        } else {
1536            let mut vec = vec![];
1537            for &(val, arg) in ifs {
1538                vec.push((Some(val), arg));
1539            }
1540            self.b.requires = Some(vec);
1541        }
1542        self
1543    }
1544
1545    /// Allows specifying that an argument is [required] conditionally. The requirement will only
1546    /// become valid if the specified `arg`'s value equals `val`.
1547    ///
1548    /// **NOTE:** If using YAML the values should be laid out as follows
1549    ///
1550    /// ```yaml
1551    /// required_if:
1552    ///     - [arg, val]
1553    /// ```
1554    ///
1555    /// # Examples
1556    ///
1557    /// ```rust
1558    /// # use clap::Arg;
1559    /// Arg::with_name("config")
1560    ///     .required_if("other_arg", "value")
1561    /// # ;
1562    /// ```
1563    ///
1564    /// Setting [`Arg::required_if(arg, val)`] makes this arg required if the `arg` is used at
1565    /// runtime and it's value is equal to `val`. If the `arg`'s value is anything other than `val`,
1566    /// this argument isn't required.
1567    ///
1568    /// ```rust
1569    /// # use clap::{App, Arg};
1570    /// let res = App::new("prog")
1571    ///     .arg(Arg::with_name("cfg")
1572    ///         .takes_value(true)
1573    ///         .required_if("other", "special")
1574    ///         .long("config"))
1575    ///     .arg(Arg::with_name("other")
1576    ///         .long("other")
1577    ///         .takes_value(true))
1578    ///     .get_matches_from_safe(vec![
1579    ///         "prog", "--other", "not-special"
1580    ///     ]);
1581    ///
1582    /// assert!(res.is_ok()); // We didn't use --other=special, so "cfg" wasn't required
1583    /// ```
1584    ///
1585    /// Setting [`Arg::required_if(arg, val)`] and having `arg` used with a value of `val` but *not*
1586    /// using this arg is an error.
1587    ///
1588    /// ```rust
1589    /// # use clap::{App, Arg, ErrorKind};
1590    /// let res = App::new("prog")
1591    ///     .arg(Arg::with_name("cfg")
1592    ///         .takes_value(true)
1593    ///         .required_if("other", "special")
1594    ///         .long("config"))
1595    ///     .arg(Arg::with_name("other")
1596    ///         .long("other")
1597    ///         .takes_value(true))
1598    ///     .get_matches_from_safe(vec![
1599    ///         "prog", "--other", "special"
1600    ///     ]);
1601    ///
1602    /// assert!(res.is_err());
1603    /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
1604    /// ```
1605    /// [`Arg::requires(name)`]: ./struct.Arg.html#method.requires
1606    /// [Conflicting]: ./struct.Arg.html#method.conflicts_with
1607    /// [required]: ./struct.Arg.html#method.required
1608    pub fn required_if(mut self, arg: &'a str, val: &'b str) -> Self {
1609        if let Some(ref mut vec) = self.r_ifs {
1610            vec.push((arg, val));
1611        } else {
1612            self.r_ifs = Some(vec![(arg, val)]);
1613        }
1614        self
1615    }
1616
1617    /// Allows specifying that an argument is [required] based on multiple conditions. The
1618    /// conditions are set up in a `(arg, val)` style tuple. The requirement will only become valid
1619    /// if one of the specified `arg`'s value equals it's corresponding `val`.
1620    ///
1621    /// **NOTE:** If using YAML the values should be laid out as follows
1622    ///
1623    /// ```yaml
1624    /// required_if:
1625    ///     - [arg, val]
1626    ///     - [arg2, val2]
1627    /// ```
1628    ///
1629    /// # Examples
1630    ///
1631    /// ```rust
1632    /// # use clap::Arg;
1633    /// Arg::with_name("config")
1634    ///     .required_ifs(&[
1635    ///         ("extra", "val"),
1636    ///         ("option", "spec")
1637    ///     ])
1638    /// # ;
1639    /// ```
1640    ///
1641    /// Setting [`Arg::required_ifs(&[(arg, val)])`] makes this arg required if any of the `arg`s
1642    /// are used at runtime and it's corresponding value is equal to `val`. If the `arg`'s value is
1643    /// anything other than `val`, this argument isn't required.
1644    ///
1645    /// ```rust
1646    /// # use clap::{App, Arg};
1647    /// let res = App::new("prog")
1648    ///     .arg(Arg::with_name("cfg")
1649    ///         .required_ifs(&[
1650    ///             ("extra", "val"),
1651    ///             ("option", "spec")
1652    ///         ])
1653    ///         .takes_value(true)
1654    ///         .long("config"))
1655    ///     .arg(Arg::with_name("extra")
1656    ///         .takes_value(true)
1657    ///         .long("extra"))
1658    ///     .arg(Arg::with_name("option")
1659    ///         .takes_value(true)
1660    ///         .long("option"))
1661    ///     .get_matches_from_safe(vec![
1662    ///         "prog", "--option", "other"
1663    ///     ]);
1664    ///
1665    /// assert!(res.is_ok()); // We didn't use --option=spec, or --extra=val so "cfg" isn't required
1666    /// ```
1667    ///
1668    /// Setting [`Arg::required_ifs(&[(arg, val)])`] and having any of the `arg`s used with it's
1669    /// value of `val` but *not* using this arg is an error.
1670    ///
1671    /// ```rust
1672    /// # use clap::{App, Arg, ErrorKind};
1673    /// let res = App::new("prog")
1674    ///     .arg(Arg::with_name("cfg")
1675    ///         .required_ifs(&[
1676    ///             ("extra", "val"),
1677    ///             ("option", "spec")
1678    ///         ])
1679    ///         .takes_value(true)
1680    ///         .long("config"))
1681    ///     .arg(Arg::with_name("extra")
1682    ///         .takes_value(true)
1683    ///         .long("extra"))
1684    ///     .arg(Arg::with_name("option")
1685    ///         .takes_value(true)
1686    ///         .long("option"))
1687    ///     .get_matches_from_safe(vec![
1688    ///         "prog", "--option", "spec"
1689    ///     ]);
1690    ///
1691    /// assert!(res.is_err());
1692    /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
1693    /// ```
1694    /// [`Arg::requires(name)`]: ./struct.Arg.html#method.requires
1695    /// [Conflicting]: ./struct.Arg.html#method.conflicts_with
1696    /// [required]: ./struct.Arg.html#method.required
1697    pub fn required_ifs(mut self, ifs: &[(&'a str, &'b str)]) -> Self {
1698        if let Some(ref mut vec) = self.r_ifs {
1699            for r_if in ifs {
1700                vec.push((r_if.0, r_if.1));
1701            }
1702        } else {
1703            let mut vec = vec![];
1704            for r_if in ifs {
1705                vec.push((r_if.0, r_if.1));
1706            }
1707            self.r_ifs = Some(vec);
1708        }
1709        self
1710    }
1711
1712    /// Sets multiple arguments by names that are required when this one is present I.e. when
1713    /// using this argument, the following arguments *must* be present.
1714    ///
1715    /// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required
1716    /// by default.
1717    ///
1718    /// # Examples
1719    ///
1720    /// ```rust
1721    /// # use clap::Arg;
1722    /// Arg::with_name("config")
1723    ///     .requires_all(&["input", "output"])
1724    /// # ;
1725    /// ```
1726    ///
1727    /// Setting [`Arg::requires_all(&[arg, arg2])`] requires that all the arguments be used at
1728    /// runtime if the defining argument is used. If the defining argument isn't used, the other
1729    /// argument isn't required
1730    ///
1731    /// ```rust
1732    /// # use clap::{App, Arg};
1733    /// let res = App::new("prog")
1734    ///     .arg(Arg::with_name("cfg")
1735    ///         .takes_value(true)
1736    ///         .requires("input")
1737    ///         .long("config"))
1738    ///     .arg(Arg::with_name("input")
1739    ///         .index(1))
1740    ///     .arg(Arg::with_name("output")
1741    ///         .index(2))
1742    ///     .get_matches_from_safe(vec![
1743    ///         "prog"
1744    ///     ]);
1745    ///
1746    /// assert!(res.is_ok()); // We didn't use cfg, so input and output weren't required
1747    /// ```
1748    ///
1749    /// Setting [`Arg::requires_all(&[arg, arg2])`] and *not* supplying all the arguments is an
1750    /// error.
1751    ///
1752    /// ```rust
1753    /// # use clap::{App, Arg, ErrorKind};
1754    /// let res = App::new("prog")
1755    ///     .arg(Arg::with_name("cfg")
1756    ///         .takes_value(true)
1757    ///         .requires_all(&["input", "output"])
1758    ///         .long("config"))
1759    ///     .arg(Arg::with_name("input")
1760    ///         .index(1))
1761    ///     .arg(Arg::with_name("output")
1762    ///         .index(2))
1763    ///     .get_matches_from_safe(vec![
1764    ///         "prog", "--config", "file.conf", "in.txt"
1765    ///     ]);
1766    ///
1767    /// assert!(res.is_err());
1768    /// // We didn't use output
1769    /// assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
1770    /// ```
1771    /// [Conflicting]: ./struct.Arg.html#method.conflicts_with
1772    /// [override]: ./struct.Arg.html#method.overrides_with
1773    /// [`Arg::requires_all(&[arg, arg2])`]: ./struct.Arg.html#method.requires_all
1774    pub fn requires_all(mut self, names: &[&'a str]) -> Self {
1775        if let Some(ref mut vec) = self.b.requires {
1776            for s in names {
1777                vec.push((None, s));
1778            }
1779        } else {
1780            let mut vec = vec![];
1781            for s in names {
1782                vec.push((None, *s));
1783            }
1784            self.b.requires = Some(vec);
1785        }
1786        self
1787    }
1788
1789    /// Specifies that the argument takes a value at run time.
1790    ///
1791    /// **NOTE:** values for arguments may be specified in any of the following methods
1792    ///
1793    /// * Using a space such as `-o value` or `--option value`
1794    /// * Using an equals and no space such as `-o=value` or `--option=value`
1795    /// * Use a short and no space such as `-ovalue`
1796    ///
1797    /// **NOTE:** By default, args which allow [multiple values] are delimited by commas, meaning
1798    /// `--option=val1,val2,val3` is three values for the `--option` argument. If you wish to
1799    /// change the delimiter to another character you can use [`Arg::value_delimiter(char)`],
1800    /// alternatively you can turn delimiting values **OFF** by using [`Arg::use_delimiter(false)`]
1801    ///
1802    /// # Examples
1803    ///
1804    /// ```rust
1805    /// # use clap::{App, Arg};
1806    /// Arg::with_name("config")
1807    ///     .takes_value(true)
1808    /// # ;
1809    /// ```
1810    ///
1811    /// ```rust
1812    /// # use clap::{App, Arg};
1813    /// let m = App::new("prog")
1814    ///     .arg(Arg::with_name("mode")
1815    ///         .long("mode")
1816    ///         .takes_value(true))
1817    ///     .get_matches_from(vec![
1818    ///         "prog", "--mode", "fast"
1819    ///     ]);
1820    ///
1821    /// assert!(m.is_present("mode"));
1822    /// assert_eq!(m.value_of("mode"), Some("fast"));
1823    /// ```
1824    /// [`Arg::value_delimiter(char)`]: ./struct.Arg.html#method.value_delimiter
1825    /// [`Arg::use_delimiter(false)`]: ./struct.Arg.html#method.use_delimiter
1826    /// [multiple values]: ./struct.Arg.html#method.multiple
1827    pub fn takes_value(self, tv: bool) -> Self {
1828        if tv {
1829            self.set(ArgSettings::TakesValue)
1830        } else {
1831            self.unset(ArgSettings::TakesValue)
1832        }
1833    }
1834
1835    /// Specifies if the possible values of an argument should be displayed in the help text or
1836    /// not. Defaults to `false` (i.e. show possible values)
1837    ///
1838    /// This is useful for args with many values, or ones which are explained elsewhere in the
1839    /// help text.
1840    ///
1841    /// # Examples
1842    ///
1843    /// ```rust
1844    /// # use clap::{App, Arg};
1845    /// Arg::with_name("config")
1846    ///     .hide_possible_values(true)
1847    /// # ;
1848    /// ```
1849    ///
1850    /// ```rust
1851    /// # use clap::{App, Arg};
1852    /// let m = App::new("prog")
1853    ///     .arg(Arg::with_name("mode")
1854    ///         .long("mode")
1855    ///         .possible_values(&["fast", "slow"])
1856    ///         .takes_value(true)
1857    ///         .hide_possible_values(true));
1858    ///
1859    /// ```
1860    ///
1861    /// If we were to run the above program with `--help` the `[values: fast, slow]` portion of
1862    /// the help text would be omitted.
1863    pub fn hide_possible_values(self, hide: bool) -> Self {
1864        if hide {
1865            self.set(ArgSettings::HidePossibleValues)
1866        } else {
1867            self.unset(ArgSettings::HidePossibleValues)
1868        }
1869    }
1870
1871    /// Specifies if the default value of an argument should be displayed in the help text or
1872    /// not. Defaults to `false` (i.e. show default value)
1873    ///
1874    /// This is useful when default behavior of an arg is explained elsewhere in the help text.
1875    ///
1876    /// # Examples
1877    ///
1878    /// ```rust
1879    /// # use clap::{App, Arg};
1880    /// Arg::with_name("config")
1881    ///     .hide_default_value(true)
1882    /// # ;
1883    /// ```
1884    ///
1885    /// ```rust
1886    /// # use clap::{App, Arg};
1887    /// let m = App::new("connect")
1888    ///     .arg(Arg::with_name("host")
1889    ///         .long("host")
1890    ///         .default_value("localhost")
1891    ///         .hide_default_value(true));
1892    ///
1893    /// ```
1894    ///
1895    /// If we were to run the above program with `--help` the `[default: localhost]` portion of
1896    /// the help text would be omitted.
1897    pub fn hide_default_value(self, hide: bool) -> Self {
1898        if hide {
1899            self.set(ArgSettings::HideDefaultValue)
1900        } else {
1901            self.unset(ArgSettings::HideDefaultValue)
1902        }
1903    }
1904
1905    /// Specifies the index of a positional argument **starting at** 1.
1906    ///
1907    /// **NOTE:** The index refers to position according to **other positional argument**. It does
1908    /// not define position in the argument list as a whole.
1909    ///
1910    /// **NOTE:** If no [`Arg::short`], or [`Arg::long`] have been defined, you can optionally
1911    /// leave off the `index` method, and the index will be assigned in order of evaluation.
1912    /// Utilizing the `index` method allows for setting indexes out of order
1913    ///
1914    /// **NOTE:** When utilized with [`Arg::multiple(true)`], only the **last** positional argument
1915    /// may be defined as multiple (i.e. with the highest index)
1916    ///
1917    /// # Panics
1918    ///
1919    /// Although not in this method directly, [`App`] will [`panic!`] if indexes are skipped (such
1920    /// as defining `index(1)` and `index(3)` but not `index(2)`, or a positional argument is
1921    /// defined as multiple and is not the highest index
1922    ///
1923    /// # Examples
1924    ///
1925    /// ```rust
1926    /// # use clap::{App, Arg};
1927    /// Arg::with_name("config")
1928    ///     .index(1)
1929    /// # ;
1930    /// ```
1931    ///
1932    /// ```rust
1933    /// # use clap::{App, Arg};
1934    /// let m = App::new("prog")
1935    ///     .arg(Arg::with_name("mode")
1936    ///         .index(1))
1937    ///     .arg(Arg::with_name("debug")
1938    ///         .long("debug"))
1939    ///     .get_matches_from(vec![
1940    ///         "prog", "--debug", "fast"
1941    ///     ]);
1942    ///
1943    /// assert!(m.is_present("mode"));
1944    /// assert_eq!(m.value_of("mode"), Some("fast")); // notice index(1) means "first positional"
1945    ///                                               // *not* first argument
1946    /// ```
1947    /// [`Arg::short`]: ./struct.Arg.html#method.short
1948    /// [`Arg::long`]: ./struct.Arg.html#method.long
1949    /// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
1950    /// [`App`]: ./struct.App.html
1951    /// [`panic!`]: https://doc.rust-lang.org/std/macro.panic!.html
1952    pub fn index(mut self, idx: u64) -> Self {
1953        self.index = Some(idx);
1954        self
1955    }
1956
1957    /// Specifies that the argument may appear more than once. For flags, this results
1958    /// in the number of occurrences of the flag being recorded. For example `-ddd` or `-d -d -d`
1959    /// would count as three occurrences. For options there is a distinct difference in multiple
1960    /// occurrences vs multiple values.
1961    ///
1962    /// For example, `--opt val1 val2` is one occurrence, but two values. Whereas
1963    /// `--opt val1 --opt val2` is two occurrences.
1964    ///
1965    /// **WARNING:**
1966    ///
1967    /// Setting `multiple(true)` for an [option] with no other details, allows multiple values
1968    /// **and** multiple occurrences because it isn't possible to have more occurrences than values
1969    /// for options. Because multiple values are allowed, `--option val1 val2 val3` is perfectly
1970    /// valid, be careful when designing a CLI where positional arguments are expected after a
1971    /// option which accepts multiple values, as `clap` will continue parsing *values* until it
1972    /// reaches the max or specific number of values defined, or another flag or option.
1973    ///
1974    /// **Pro Tip**:
1975    ///
1976    /// It's possible to define an option which allows multiple occurrences, but only one value per
1977    /// occurrence. To do this use [`Arg::number_of_values(1)`] in coordination with
1978    /// [`Arg::multiple(true)`].
1979    ///
1980    /// **WARNING:**
1981    ///
1982    /// When using args with `multiple(true)` on [options] or [positionals] (i.e. those args that
1983    /// accept values) and [subcommands], one needs to consider the possibility of an argument value
1984    /// being the same as a valid subcommand. By default `clap` will parse the argument in question
1985    /// as a value *only if* a value is possible at that moment. Otherwise it will be parsed as a
1986    /// subcommand. In effect, this means using `multiple(true)` with no additional parameters and
1987    /// a possible value that coincides with a subcommand name, the subcommand cannot be called
1988    /// unless another argument is passed first.
1989    ///
1990    /// As an example, consider a CLI with an option `--ui-paths=<paths>...` and subcommand `signer`
1991    ///
1992    /// The following would be parsed as values to `--ui-paths`.
1993    ///
1994    /// ```notrust
1995    /// $ program --ui-paths path1 path2 signer
1996    /// ```
1997    ///
1998    /// This is because `--ui-paths` accepts multiple values. `clap` will continue parsing values
1999    /// until another argument is reached and it knows `--ui-paths` is done.
2000    ///
2001    /// By adding additional parameters to `--ui-paths` we can solve this issue. Consider adding
2002    /// [`Arg::number_of_values(1)`] as discussed above. The following are all valid, and `signer`
2003    /// is parsed as both a subcommand and a value in the second case.
2004    ///
2005    /// ```notrust
2006    /// $ program --ui-paths path1 signer
2007    /// $ program --ui-paths path1 --ui-paths signer signer
2008    /// ```
2009    ///
2010    /// # Examples
2011    ///
2012    /// ```rust
2013    /// # use clap::{App, Arg};
2014    /// Arg::with_name("debug")
2015    ///     .short("d")
2016    ///     .multiple(true)
2017    /// # ;
2018    /// ```
2019    /// An example with flags
2020    ///
2021    /// ```rust
2022    /// # use clap::{App, Arg};
2023    /// let m = App::new("prog")
2024    ///     .arg(Arg::with_name("verbose")
2025    ///         .multiple(true)
2026    ///         .short("v"))
2027    ///     .get_matches_from(vec![
2028    ///         "prog", "-v", "-v", "-v"    // note, -vvv would have same result
2029    ///     ]);
2030    ///
2031    /// assert!(m.is_present("verbose"));
2032    /// assert_eq!(m.occurrences_of("verbose"), 3);
2033    /// ```
2034    ///
2035    /// An example with options
2036    ///
2037    /// ```rust
2038    /// # use clap::{App, Arg};
2039    /// let m = App::new("prog")
2040    ///     .arg(Arg::with_name("file")
2041    ///         .multiple(true)
2042    ///         .takes_value(true)
2043    ///         .short("F"))
2044    ///     .get_matches_from(vec![
2045    ///         "prog", "-F", "file1", "file2", "file3"
2046    ///     ]);
2047    ///
2048    /// assert!(m.is_present("file"));
2049    /// assert_eq!(m.occurrences_of("file"), 1); // notice only one occurrence
2050    /// let files: Vec<_> = m.values_of("file").unwrap().collect();
2051    /// assert_eq!(files, ["file1", "file2", "file3"]);
2052    /// ```
2053    /// This is functionally equivalent to the example above
2054    ///
2055    /// ```rust
2056    /// # use clap::{App, Arg};
2057    /// let m = App::new("prog")
2058    ///     .arg(Arg::with_name("file")
2059    ///         .multiple(true)
2060    ///         .takes_value(true)
2061    ///         .short("F"))
2062    ///     .get_matches_from(vec![
2063    ///         "prog", "-F", "file1", "-F", "file2", "-F", "file3"
2064    ///     ]);
2065    /// let files: Vec<_> = m.values_of("file").unwrap().collect();
2066    /// assert_eq!(files, ["file1", "file2", "file3"]);
2067    ///
2068    /// assert!(m.is_present("file"));
2069    /// assert_eq!(m.occurrences_of("file"), 3); // Notice 3 occurrences
2070    /// let files: Vec<_> = m.values_of("file").unwrap().collect();
2071    /// assert_eq!(files, ["file1", "file2", "file3"]);
2072    /// ```
2073    ///
2074    /// A common mistake is to define an option which allows multiples, and a positional argument
2075    ///
2076    /// ```rust
2077    /// # use clap::{App, Arg};
2078    /// let m = App::new("prog")
2079    ///     .arg(Arg::with_name("file")
2080    ///         .multiple(true)
2081    ///         .takes_value(true)
2082    ///         .short("F"))
2083    ///     .arg(Arg::with_name("word")
2084    ///         .index(1))
2085    ///     .get_matches_from(vec![
2086    ///         "prog", "-F", "file1", "file2", "file3", "word"
2087    ///     ]);
2088    ///
2089    /// assert!(m.is_present("file"));
2090    /// let files: Vec<_> = m.values_of("file").unwrap().collect();
2091    /// assert_eq!(files, ["file1", "file2", "file3", "word"]); // wait...what?!
2092    /// assert!(!m.is_present("word")); // but we clearly used word!
2093    /// ```
2094    /// The problem is clap doesn't know when to stop parsing values for "files". This is further
2095    /// compounded by if we'd said `word -F file1 file2` it would have worked fine, so it would
2096    /// appear to only fail sometimes...not good!
2097    ///
2098    /// A solution for the example above is to specify that `-F` only accepts one value, but is
2099    /// allowed to appear multiple times
2100    ///
2101    /// ```rust
2102    /// # use clap::{App, Arg};
2103    /// let m = App::new("prog")
2104    ///     .arg(Arg::with_name("file")
2105    ///         .multiple(true)
2106    ///         .takes_value(true)
2107    ///         .number_of_values(1)
2108    ///         .short("F"))
2109    ///     .arg(Arg::with_name("word")
2110    ///         .index(1))
2111    ///     .get_matches_from(vec![
2112    ///         "prog", "-F", "file1", "-F", "file2", "-F", "file3", "word"
2113    ///     ]);
2114    ///
2115    /// assert!(m.is_present("file"));
2116    /// let files: Vec<_> = m.values_of("file").unwrap().collect();
2117    /// assert_eq!(files, ["file1", "file2", "file3"]);
2118    /// assert!(m.is_present("word"));
2119    /// assert_eq!(m.value_of("word"), Some("word"));
2120    /// ```
2121    /// As a final example, notice if we define [`Arg::number_of_values(1)`] and try to run the
2122    /// problem example above, it would have been a runtime error with a pretty message to the
2123    /// user :)
2124    ///
2125    /// ```rust
2126    /// # use clap::{App, Arg, ErrorKind};
2127    /// let res = App::new("prog")
2128    ///     .arg(Arg::with_name("file")
2129    ///         .multiple(true)
2130    ///         .takes_value(true)
2131    ///         .number_of_values(1)
2132    ///         .short("F"))
2133    ///     .arg(Arg::with_name("word")
2134    ///         .index(1))
2135    ///     .get_matches_from_safe(vec![
2136    ///         "prog", "-F", "file1", "file2", "file3", "word"
2137    ///     ]);
2138    ///
2139    /// assert!(res.is_err());
2140    /// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
2141    /// ```
2142    /// [option]: ./struct.Arg.html#method.takes_value
2143    /// [options]: ./struct.Arg.html#method.takes_value
2144    /// [subcommands]: ./struct.SubCommand.html
2145    /// [positionals]: ./struct.Arg.html#method.index
2146    /// [`Arg::number_of_values(1)`]: ./struct.Arg.html#method.number_of_values
2147    /// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
2148    pub fn multiple(self, multi: bool) -> Self {
2149        if multi {
2150            self.set(ArgSettings::Multiple)
2151        } else {
2152            self.unset(ArgSettings::Multiple)
2153        }
2154    }
2155
2156    /// Specifies a value that *stops* parsing multiple values of a give argument. By default when
2157    /// one sets [`multiple(true)`] on an argument, clap will continue parsing values for that
2158    /// argument until it reaches another valid argument, or one of the other more specific settings
2159    /// for multiple values is used (such as [`min_values`], [`max_values`] or
2160    /// [`number_of_values`]).
2161    ///
2162    /// **NOTE:** This setting only applies to [options] and [positional arguments]
2163    ///
2164    /// **NOTE:** When the terminator is passed in on the command line, it is **not** stored as one
2165    /// of the values
2166    ///
2167    /// # Examples
2168    ///
2169    /// ```rust
2170    /// # use clap::{App, Arg};
2171    /// Arg::with_name("vals")
2172    ///     .takes_value(true)
2173    ///     .multiple(true)
2174    ///     .value_terminator(";")
2175    /// # ;
2176    /// ```
2177    /// The following example uses two arguments, a sequence of commands, and the location in which
2178    /// to perform them
2179    ///
2180    /// ```rust
2181    /// # use clap::{App, Arg};
2182    /// let m = App::new("prog")
2183    ///     .arg(Arg::with_name("cmds")
2184    ///         .multiple(true)
2185    ///         .allow_hyphen_values(true)
2186    ///         .value_terminator(";"))
2187    ///     .arg(Arg::with_name("location"))
2188    ///     .get_matches_from(vec![
2189    ///         "prog", "find", "-type", "f", "-name", "special", ";", "/home/clap"
2190    ///     ]);
2191    /// let cmds: Vec<_> = m.values_of("cmds").unwrap().collect();
2192    /// assert_eq!(&cmds, &["find", "-type", "f", "-name", "special"]);
2193    /// assert_eq!(m.value_of("location"), Some("/home/clap"));
2194    /// ```
2195    /// [options]: ./struct.Arg.html#method.takes_value
2196    /// [positional arguments]: ./struct.Arg.html#method.index
2197    /// [`multiple(true)`]: ./struct.Arg.html#method.multiple
2198    /// [`min_values`]: ./struct.Arg.html#method.min_values
2199    /// [`number_of_values`]: ./struct.Arg.html#method.number_of_values
2200    /// [`max_values`]: ./struct.Arg.html#method.max_values
2201    pub fn value_terminator(mut self, term: &'b str) -> Self {
2202        self.setb(ArgSettings::TakesValue);
2203        self.v.terminator = Some(term);
2204        self
2205    }
2206
2207    /// Specifies that an argument can be matched to all child [`SubCommand`]s.
2208    ///
2209    /// **NOTE:** Global arguments *only* propagate down, **not** up (to parent commands), however
2210    /// their values once a user uses them will be propagated back up to parents. In effect, this
2211    /// means one should *define* all global arguments at the top level, however it doesn't matter
2212    /// where the user *uses* the global argument.
2213    ///
2214    /// # Examples
2215    ///
2216    /// ```rust
2217    /// # use clap::{App, Arg};
2218    /// Arg::with_name("debug")
2219    ///     .short("d")
2220    ///     .global(true)
2221    /// # ;
2222    /// ```
2223    ///
2224    /// For example, assume an application with two subcommands, and you'd like to define a
2225    /// `--verbose` flag that can be called on any of the subcommands and parent, but you don't
2226    /// want to clutter the source with three duplicate [`Arg`] definitions.
2227    ///
2228    /// ```rust
2229    /// # use clap::{App, Arg, SubCommand};
2230    /// let m = App::new("prog")
2231    ///     .arg(Arg::with_name("verb")
2232    ///         .long("verbose")
2233    ///         .short("v")
2234    ///         .global(true))
2235    ///     .subcommand(SubCommand::with_name("test"))
2236    ///     .subcommand(SubCommand::with_name("do-stuff"))
2237    ///     .get_matches_from(vec![
2238    ///         "prog", "do-stuff", "--verbose"
2239    ///     ]);
2240    ///
2241    /// assert_eq!(m.subcommand_name(), Some("do-stuff"));
2242    /// let sub_m = m.subcommand_matches("do-stuff").unwrap();
2243    /// assert!(sub_m.is_present("verb"));
2244    /// ```
2245    /// [`SubCommand`]: ./struct.SubCommand.html
2246    /// [required]: ./struct.Arg.html#method.required
2247    /// [`ArgMatches`]: ./struct.ArgMatches.html
2248    /// [`ArgMatches::is_present("flag")`]: ./struct.ArgMatches.html#method.is_present
2249    /// [`Arg`]: ./struct.Arg.html
2250    pub fn global(self, g: bool) -> Self {
2251        if g {
2252            self.set(ArgSettings::Global)
2253        } else {
2254            self.unset(ArgSettings::Global)
2255        }
2256    }
2257
2258    /// Allows an argument to accept explicitly empty values. An empty value must be specified at
2259    /// the command line with an explicit `""`, or `''`
2260    ///
2261    /// **NOTE:** Defaults to `true` (Explicitly empty values are allowed)
2262    ///
2263    /// **NOTE:** Implicitly sets [`Arg::takes_value(true)`] when set to `false`
2264    ///
2265    /// # Examples
2266    ///
2267    /// ```rust
2268    /// # use clap::{App, Arg};
2269    /// Arg::with_name("file")
2270    ///     .long("file")
2271    ///     .empty_values(false)
2272    /// # ;
2273    /// ```
2274    /// The default is to allow empty values, such as `--option ""` would be an empty value. But
2275    /// we can change to make empty values become an error.
2276    ///
2277    /// ```rust
2278    /// # use clap::{App, Arg, ErrorKind};
2279    /// let res = App::new("prog")
2280    ///     .arg(Arg::with_name("cfg")
2281    ///         .long("config")
2282    ///         .short("v")
2283    ///         .empty_values(false))
2284    ///     .get_matches_from_safe(vec![
2285    ///         "prog", "--config="
2286    ///     ]);
2287    ///
2288    /// assert!(res.is_err());
2289    /// assert_eq!(res.unwrap_err().kind, ErrorKind::EmptyValue);
2290    /// ```
2291    /// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
2292    pub fn empty_values(mut self, ev: bool) -> Self {
2293        if ev {
2294            self.set(ArgSettings::EmptyValues)
2295        } else {
2296            self = self.set(ArgSettings::TakesValue);
2297            self.unset(ArgSettings::EmptyValues)
2298        }
2299    }
2300
2301    /// Hides an argument from help message output.
2302    ///
2303    /// **NOTE:** Implicitly sets [`Arg::hidden_short_help(true)`] and [`Arg::hidden_long_help(true)`]
2304    /// when set to true
2305    ///
2306    /// **NOTE:** This does **not** hide the argument from usage strings on error
2307    ///
2308    /// # Examples
2309    ///
2310    /// ```rust
2311    /// # use clap::{App, Arg};
2312    /// Arg::with_name("debug")
2313    ///     .hidden(true)
2314    /// # ;
2315    /// ```
2316    /// Setting `hidden(true)` will hide the argument when displaying help text
2317    ///
2318    /// ```rust
2319    /// # use clap::{App, Arg};
2320    /// let m = App::new("prog")
2321    ///     .arg(Arg::with_name("cfg")
2322    ///         .long("config")
2323    ///         .hidden(true)
2324    ///         .help("Some help text describing the --config arg"))
2325    ///     .get_matches_from(vec![
2326    ///         "prog", "--help"
2327    ///     ]);
2328    /// ```
2329    ///
2330    /// The above example displays
2331    ///
2332    /// ```notrust
2333    /// helptest
2334    ///
2335    /// USAGE:
2336    ///    helptest [FLAGS]
2337    ///
2338    /// FLAGS:
2339    /// -h, --help       Prints help information
2340    /// -V, --version    Prints version information
2341    /// ```
2342    /// [`Arg::hidden_short_help(true)`]: ./struct.Arg.html#method.hidden_short_help
2343    /// [`Arg::hidden_long_help(true)`]: ./struct.Arg.html#method.hidden_long_help
2344    pub fn hidden(self, h: bool) -> Self {
2345        if h {
2346            self.set(ArgSettings::Hidden)
2347        } else {
2348            self.unset(ArgSettings::Hidden)
2349        }
2350    }
2351
2352    /// Specifies a list of possible values for this argument. At runtime, `clap` verifies that
2353    /// only one of the specified values was used, or fails with an error message.
2354    ///
2355    /// **NOTE:** This setting only applies to [options] and [positional arguments]
2356    ///
2357    /// # Examples
2358    ///
2359    /// ```rust
2360    /// # use clap::{App, Arg};
2361    /// Arg::with_name("mode")
2362    ///     .takes_value(true)
2363    ///     .possible_values(&["fast", "slow", "medium"])
2364    /// # ;
2365    /// ```
2366    ///
2367    /// ```rust
2368    /// # use clap::{App, Arg};
2369    /// let m = App::new("prog")
2370    ///     .arg(Arg::with_name("mode")
2371    ///         .long("mode")
2372    ///         .takes_value(true)
2373    ///         .possible_values(&["fast", "slow", "medium"]))
2374    ///     .get_matches_from(vec![
2375    ///         "prog", "--mode", "fast"
2376    ///     ]);
2377    /// assert!(m.is_present("mode"));
2378    /// assert_eq!(m.value_of("mode"), Some("fast"));
2379    /// ```
2380    ///
2381    /// The next example shows a failed parse from using a value which wasn't defined as one of the
2382    /// possible values.
2383    ///
2384    /// ```rust
2385    /// # use clap::{App, Arg, ErrorKind};
2386    /// let res = App::new("prog")
2387    ///     .arg(Arg::with_name("mode")
2388    ///         .long("mode")
2389    ///         .takes_value(true)
2390    ///         .possible_values(&["fast", "slow", "medium"]))
2391    ///     .get_matches_from_safe(vec![
2392    ///         "prog", "--mode", "wrong"
2393    ///     ]);
2394    /// assert!(res.is_err());
2395    /// assert_eq!(res.unwrap_err().kind, ErrorKind::InvalidValue);
2396    /// ```
2397    /// [options]: ./struct.Arg.html#method.takes_value
2398    /// [positional arguments]: ./struct.Arg.html#method.index
2399    pub fn possible_values(mut self, names: &[&'b str]) -> Self {
2400        if let Some(ref mut vec) = self.v.possible_vals {
2401            for s in names {
2402                vec.push(s);
2403            }
2404        } else {
2405            self.v.possible_vals = Some(names.iter().map(|s| *s).collect::<Vec<_>>());
2406        }
2407        self
2408    }
2409
2410    /// Specifies a possible value for this argument, one at a time. At runtime, `clap` verifies
2411    /// that only one of the specified values was used, or fails with error message.
2412    ///
2413    /// **NOTE:** This setting only applies to [options] and [positional arguments]
2414    ///
2415    /// # Examples
2416    ///
2417    /// ```rust
2418    /// # use clap::{App, Arg};
2419    /// Arg::with_name("mode")
2420    ///     .takes_value(true)
2421    ///     .possible_value("fast")
2422    ///     .possible_value("slow")
2423    ///     .possible_value("medium")
2424    /// # ;
2425    /// ```
2426    ///
2427    /// ```rust
2428    /// # use clap::{App, Arg};
2429    /// let m = App::new("prog")
2430    ///     .arg(Arg::with_name("mode")
2431    ///         .long("mode")
2432    ///         .takes_value(true)
2433    ///         .possible_value("fast")
2434    ///         .possible_value("slow")
2435    ///         .possible_value("medium"))
2436    ///     .get_matches_from(vec![
2437    ///         "prog", "--mode", "fast"
2438    ///     ]);
2439    /// assert!(m.is_present("mode"));
2440    /// assert_eq!(m.value_of("mode"), Some("fast"));
2441    /// ```
2442    ///
2443    /// The next example shows a failed parse from using a value which wasn't defined as one of the
2444    /// possible values.
2445    ///
2446    /// ```rust
2447    /// # use clap::{App, Arg, ErrorKind};
2448    /// let res = App::new("prog")
2449    ///     .arg(Arg::with_name("mode")
2450    ///         .long("mode")
2451    ///         .takes_value(true)
2452    ///         .possible_value("fast")
2453    ///         .possible_value("slow")
2454    ///         .possible_value("medium"))
2455    ///     .get_matches_from_safe(vec![
2456    ///         "prog", "--mode", "wrong"
2457    ///     ]);
2458    /// assert!(res.is_err());
2459    /// assert_eq!(res.unwrap_err().kind, ErrorKind::InvalidValue);
2460    /// ```
2461    /// [options]: ./struct.Arg.html#method.takes_value
2462    /// [positional arguments]: ./struct.Arg.html#method.index
2463    pub fn possible_value(mut self, name: &'b str) -> Self {
2464        if let Some(ref mut vec) = self.v.possible_vals {
2465            vec.push(name);
2466        } else {
2467            self.v.possible_vals = Some(vec![name]);
2468        }
2469        self
2470    }
2471
2472    /// When used with [`Arg::possible_values`] it allows the argument value to pass validation even if
2473    /// the case differs from that of the specified `possible_value`.
2474    ///
2475    /// **Pro Tip:** Use this setting with [`arg_enum!`]
2476    ///
2477    /// # Examples
2478    ///
2479    /// ```rust
2480    /// # use clap::{App, Arg};
2481    /// # use std::ascii::AsciiExt;
2482    /// let m = App::new("pv")
2483    ///     .arg(Arg::with_name("option")
2484    ///         .long("--option")
2485    ///         .takes_value(true)
2486    ///         .possible_value("test123")
2487    ///         .case_insensitive(true))
2488    ///     .get_matches_from(vec![
2489    ///         "pv", "--option", "TeSt123",
2490    ///     ]);
2491    ///
2492    /// assert!(m.value_of("option").unwrap().eq_ignore_ascii_case("test123"));
2493    /// ```
2494    ///
2495    /// This setting also works when multiple values can be defined:
2496    ///
2497    /// ```rust
2498    /// # use clap::{App, Arg};
2499    /// let m = App::new("pv")
2500    ///     .arg(Arg::with_name("option")
2501    ///         .short("-o")
2502    ///         .long("--option")
2503    ///         .takes_value(true)
2504    ///         .possible_value("test123")
2505    ///         .possible_value("test321")
2506    ///         .multiple(true)
2507    ///         .case_insensitive(true))
2508    ///     .get_matches_from(vec![
2509    ///         "pv", "--option", "TeSt123", "teST123", "tESt321"
2510    ///     ]);
2511    ///
2512    /// let matched_vals = m.values_of("option").unwrap().collect::<Vec<_>>();
2513    /// assert_eq!(&*matched_vals, &["TeSt123", "teST123", "tESt321"]);
2514    /// ```
2515    /// [`Arg::case_insensitive(true)`]: ./struct.Arg.html#method.possible_values
2516    /// [`arg_enum!`]: ./macro.arg_enum.html
2517    pub fn case_insensitive(self, ci: bool) -> Self {
2518        if ci {
2519            self.set(ArgSettings::CaseInsensitive)
2520        } else {
2521            self.unset(ArgSettings::CaseInsensitive)
2522        }
2523    }
2524
2525    /// Specifies the name of the [`ArgGroup`] the argument belongs to.
2526    ///
2527    /// # Examples
2528    ///
2529    /// ```rust
2530    /// # use clap::{App, Arg};
2531    /// Arg::with_name("debug")
2532    ///     .long("debug")
2533    ///     .group("mode")
2534    /// # ;
2535    /// ```
2536    ///
2537    /// Multiple arguments can be a member of a single group and then the group checked as if it
2538    /// was one of said arguments.
2539    ///
2540    /// ```rust
2541    /// # use clap::{App, Arg};
2542    /// let m = App::new("prog")
2543    ///     .arg(Arg::with_name("debug")
2544    ///         .long("debug")
2545    ///         .group("mode"))
2546    ///     .arg(Arg::with_name("verbose")
2547    ///         .long("verbose")
2548    ///         .group("mode"))
2549    ///     .get_matches_from(vec![
2550    ///         "prog", "--debug"
2551    ///     ]);
2552    /// assert!(m.is_present("mode"));
2553    /// ```
2554    /// [`ArgGroup`]: ./struct.ArgGroup.html
2555    pub fn group(mut self, name: &'a str) -> Self {
2556        if let Some(ref mut vec) = self.b.groups {
2557            vec.push(name);
2558        } else {
2559            self.b.groups = Some(vec![name]);
2560        }
2561        self
2562    }
2563
2564    /// Specifies the names of multiple [`ArgGroup`]'s the argument belongs to.
2565    ///
2566    /// # Examples
2567    ///
2568    /// ```rust
2569    /// # use clap::{App, Arg};
2570    /// Arg::with_name("debug")
2571    ///     .long("debug")
2572    ///     .groups(&["mode", "verbosity"])
2573    /// # ;
2574    /// ```
2575    ///
2576    /// Arguments can be members of multiple groups and then the group checked as if it
2577    /// was one of said arguments.
2578    ///
2579    /// ```rust
2580    /// # use clap::{App, Arg};
2581    /// let m = App::new("prog")
2582    ///     .arg(Arg::with_name("debug")
2583    ///         .long("debug")
2584    ///         .groups(&["mode", "verbosity"]))
2585    ///     .arg(Arg::with_name("verbose")
2586    ///         .long("verbose")
2587    ///         .groups(&["mode", "verbosity"]))
2588    ///     .get_matches_from(vec![
2589    ///         "prog", "--debug"
2590    ///     ]);
2591    /// assert!(m.is_present("mode"));
2592    /// assert!(m.is_present("verbosity"));
2593    /// ```
2594    /// [`ArgGroup`]: ./struct.ArgGroup.html
2595    pub fn groups(mut self, names: &[&'a str]) -> Self {
2596        if let Some(ref mut vec) = self.b.groups {
2597            for s in names {
2598                vec.push(s);
2599            }
2600        } else {
2601            self.b.groups = Some(names.into_iter().map(|s| *s).collect::<Vec<_>>());
2602        }
2603        self
2604    }
2605
2606    /// Specifies how many values are required to satisfy this argument. For example, if you had a
2607    /// `-f <file>` argument where you wanted exactly 3 'files' you would set
2608    /// `.number_of_values(3)`, and this argument wouldn't be satisfied unless the user provided
2609    /// 3 and only 3 values.
2610    ///
2611    /// **NOTE:** Does *not* require [`Arg::multiple(true)`] to be set. Setting
2612    /// [`Arg::multiple(true)`] would allow `-f <file> <file> <file> -f <file> <file> <file>` where
2613    /// as *not* setting [`Arg::multiple(true)`] would only allow one occurrence of this argument.
2614    ///
2615    /// # Examples
2616    ///
2617    /// ```rust
2618    /// # use clap::{App, Arg};
2619    /// Arg::with_name("file")
2620    ///     .short("f")
2621    ///     .number_of_values(3)
2622    /// # ;
2623    /// ```
2624    ///
2625    /// Not supplying the correct number of values is an error
2626    ///
2627    /// ```rust
2628    /// # use clap::{App, Arg, ErrorKind};
2629    /// let res = App::new("prog")
2630    ///     .arg(Arg::with_name("file")
2631    ///         .takes_value(true)
2632    ///         .number_of_values(2)
2633    ///         .short("F"))
2634    ///     .get_matches_from_safe(vec![
2635    ///         "prog", "-F", "file1"
2636    ///     ]);
2637    ///
2638    /// assert!(res.is_err());
2639    /// assert_eq!(res.unwrap_err().kind, ErrorKind::WrongNumberOfValues);
2640    /// ```
2641    /// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
2642    pub fn number_of_values(mut self, qty: u64) -> Self {
2643        self.setb(ArgSettings::TakesValue);
2644        self.v.num_vals = Some(qty);
2645        self
2646    }
2647
2648    /// Allows one to perform a custom validation on the argument value. You provide a closure
2649    /// which accepts a [`String`] value, and return a [`Result`] where the [`Err(String)`] is a
2650    /// message displayed to the user.
2651    ///
2652    /// **NOTE:** The error message does *not* need to contain the `error:` portion, only the
2653    /// message as all errors will appear as
2654    /// `error: Invalid value for '<arg>': <YOUR MESSAGE>` where `<arg>` is replaced by the actual
2655    /// arg, and `<YOUR MESSAGE>` is the `String` you return as the error.
2656    ///
2657    /// **NOTE:** There is a small performance hit for using validators, as they are implemented
2658    /// with [`Rc`] pointers. And the value to be checked will be allocated an extra time in order
2659    /// to to be passed to the closure. This performance hit is extremely minimal in the grand
2660    /// scheme of things.
2661    ///
2662    /// # Examples
2663    ///
2664    /// ```rust
2665    /// # use clap::{App, Arg};
2666    /// fn has_at(v: String) -> Result<(), String> {
2667    ///     if v.contains("@") { return Ok(()); }
2668    ///     Err(String::from("The value did not contain the required @ sigil"))
2669    /// }
2670    /// let res = App::new("prog")
2671    ///     .arg(Arg::with_name("file")
2672    ///         .index(1)
2673    ///         .validator(has_at))
2674    ///     .get_matches_from_safe(vec![
2675    ///         "prog", "some@file"
2676    ///     ]);
2677    /// assert!(res.is_ok());
2678    /// assert_eq!(res.unwrap().value_of("file"), Some("some@file"));
2679    /// ```
2680    /// [`String`]: https://doc.rust-lang.org/std/string/struct.String.html
2681    /// [`Result`]: https://doc.rust-lang.org/std/result/enum.Result.html
2682    /// [`Err(String)`]: https://doc.rust-lang.org/std/result/enum.Result.html#variant.Err
2683    /// [`Rc`]: https://doc.rust-lang.org/std/rc/struct.Rc.html
2684    pub fn validator<F>(mut self, f: F) -> Self
2685    where
2686        F: Fn(String) -> Result<(), String> + 'static,
2687    {
2688        self.v.validator = Some(Rc::new(f));
2689        self
2690    }
2691
2692    /// Works identically to Validator but is intended to be used with values that could
2693    /// contain non UTF-8 formatted strings.
2694    ///
2695    /// # Examples
2696    ///
2697    #[cfg_attr(not(unix), doc = " ```ignore")]
2698    #[cfg_attr(unix, doc = " ```rust")]
2699    /// # use clap::{App, Arg};
2700    /// # use std::ffi::{OsStr, OsString};
2701    /// # use std::os::unix::ffi::OsStrExt;
2702    /// fn has_ampersand(v: &OsStr) -> Result<(), OsString> {
2703    ///     if v.as_bytes().iter().any(|b| *b == b'&') { return Ok(()); }
2704    ///     Err(OsString::from("The value did not contain the required & sigil"))
2705    /// }
2706    /// let res = App::new("prog")
2707    ///     .arg(Arg::with_name("file")
2708    ///         .index(1)
2709    ///         .validator_os(has_ampersand))
2710    ///     .get_matches_from_safe(vec![
2711    ///         "prog", "Fish & chips"
2712    ///     ]);
2713    /// assert!(res.is_ok());
2714    /// assert_eq!(res.unwrap().value_of("file"), Some("Fish & chips"));
2715    /// ```
2716    /// [`String`]: https://doc.rust-lang.org/std/string/struct.String.html
2717    /// [`OsStr`]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html
2718    /// [`OsString`]: https://doc.rust-lang.org/std/ffi/struct.OsString.html
2719    /// [`Result`]: https://doc.rust-lang.org/std/result/enum.Result.html
2720    /// [`Err(String)`]: https://doc.rust-lang.org/std/result/enum.Result.html#variant.Err
2721    /// [`Rc`]: https://doc.rust-lang.org/std/rc/struct.Rc.html
2722    pub fn validator_os<F>(mut self, f: F) -> Self
2723    where
2724        F: Fn(&OsStr) -> Result<(), OsString> + 'static,
2725    {
2726        self.v.validator_os = Some(Rc::new(f));
2727        self
2728    }
2729
2730    /// Specifies the *maximum* number of values are for this argument. For example, if you had a
2731    /// `-f <file>` argument where you wanted up to 3 'files' you would set `.max_values(3)`, and
2732    /// this argument would be satisfied if the user provided, 1, 2, or 3 values.
2733    ///
2734    /// **NOTE:** This does *not* implicitly set [`Arg::multiple(true)`]. This is because
2735    /// `-o val -o val` is multiple occurrences but a single value and `-o val1 val2` is a single
2736    /// occurrence with multiple values. For positional arguments this **does** set
2737    /// [`Arg::multiple(true)`] because there is no way to determine the difference between multiple
2738    /// occurrences and multiple values.
2739    ///
2740    /// # Examples
2741    ///
2742    /// ```rust
2743    /// # use clap::{App, Arg};
2744    /// Arg::with_name("file")
2745    ///     .short("f")
2746    ///     .max_values(3)
2747    /// # ;
2748    /// ```
2749    ///
2750    /// Supplying less than the maximum number of values is allowed
2751    ///
2752    /// ```rust
2753    /// # use clap::{App, Arg};
2754    /// let res = App::new("prog")
2755    ///     .arg(Arg::with_name("file")
2756    ///         .takes_value(true)
2757    ///         .max_values(3)
2758    ///         .short("F"))
2759    ///     .get_matches_from_safe(vec![
2760    ///         "prog", "-F", "file1", "file2"
2761    ///     ]);
2762    ///
2763    /// assert!(res.is_ok());
2764    /// let m = res.unwrap();
2765    /// let files: Vec<_> = m.values_of("file").unwrap().collect();
2766    /// assert_eq!(files, ["file1", "file2"]);
2767    /// ```
2768    ///
2769    /// Supplying more than the maximum number of values is an error
2770    ///
2771    /// ```rust
2772    /// # use clap::{App, Arg, ErrorKind};
2773    /// let res = App::new("prog")
2774    ///     .arg(Arg::with_name("file")
2775    ///         .takes_value(true)
2776    ///         .max_values(2)
2777    ///         .short("F"))
2778    ///     .get_matches_from_safe(vec![
2779    ///         "prog", "-F", "file1", "file2", "file3"
2780    ///     ]);
2781    ///
2782    /// assert!(res.is_err());
2783    /// assert_eq!(res.unwrap_err().kind, ErrorKind::TooManyValues);
2784    /// ```
2785    /// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
2786    pub fn max_values(mut self, qty: u64) -> Self {
2787        self.setb(ArgSettings::TakesValue);
2788        self.v.max_vals = Some(qty);
2789        self
2790    }
2791
2792    /// Specifies the *minimum* number of values for this argument. For example, if you had a
2793    /// `-f <file>` argument where you wanted at least 2 'files' you would set
2794    /// `.min_values(2)`, and this argument would be satisfied if the user provided, 2 or more
2795    /// values.
2796    ///
2797    /// **NOTE:** This does not implicitly set [`Arg::multiple(true)`]. This is because
2798    /// `-o val -o val` is multiple occurrences but a single value and `-o val1 val2` is a single
2799    /// occurrence with multiple values. For positional arguments this **does** set
2800    /// [`Arg::multiple(true)`] because there is no way to determine the difference between multiple
2801    /// occurrences and multiple values.
2802    ///
2803    /// # Examples
2804    ///
2805    /// ```rust
2806    /// # use clap::{App, Arg};
2807    /// Arg::with_name("file")
2808    ///     .short("f")
2809    ///     .min_values(3)
2810    /// # ;
2811    /// ```
2812    ///
2813    /// Supplying more than the minimum number of values is allowed
2814    ///
2815    /// ```rust
2816    /// # use clap::{App, Arg};
2817    /// let res = App::new("prog")
2818    ///     .arg(Arg::with_name("file")
2819    ///         .takes_value(true)
2820    ///         .min_values(2)
2821    ///         .short("F"))
2822    ///     .get_matches_from_safe(vec![
2823    ///         "prog", "-F", "file1", "file2", "file3"
2824    ///     ]);
2825    ///
2826    /// assert!(res.is_ok());
2827    /// let m = res.unwrap();
2828    /// let files: Vec<_> = m.values_of("file").unwrap().collect();
2829    /// assert_eq!(files, ["file1", "file2", "file3"]);
2830    /// ```
2831    ///
2832    /// Supplying less than the minimum number of values is an error
2833    ///
2834    /// ```rust
2835    /// # use clap::{App, Arg, ErrorKind};
2836    /// let res = App::new("prog")
2837    ///     .arg(Arg::with_name("file")
2838    ///         .takes_value(true)
2839    ///         .min_values(2)
2840    ///         .short("F"))
2841    ///     .get_matches_from_safe(vec![
2842    ///         "prog", "-F", "file1"
2843    ///     ]);
2844    ///
2845    /// assert!(res.is_err());
2846    /// assert_eq!(res.unwrap_err().kind, ErrorKind::TooFewValues);
2847    /// ```
2848    /// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
2849    pub fn min_values(mut self, qty: u64) -> Self {
2850        self.v.min_vals = Some(qty);
2851        self.set(ArgSettings::TakesValue)
2852    }
2853
2854    /// Specifies whether or not an argument should allow grouping of multiple values via a
2855    /// delimiter. I.e. should `--option=val1,val2,val3` be parsed as three values (`val1`, `val2`,
2856    /// and `val3`) or as a single value (`val1,val2,val3`). Defaults to using `,` (comma) as the
2857    /// value delimiter for all arguments that accept values (options and positional arguments)
2858    ///
2859    /// **NOTE:** The default is `false`. When set to `true` the default [`Arg::value_delimiter`]
2860    /// is the comma `,`.
2861    ///
2862    /// # Examples
2863    ///
2864    /// The following example shows the default behavior.
2865    ///
2866    /// ```rust
2867    /// # use clap::{App, Arg};
2868    /// let delims = App::new("prog")
2869    ///     .arg(Arg::with_name("option")
2870    ///         .long("option")
2871    ///         .use_delimiter(true)
2872    ///         .takes_value(true))
2873    ///     .get_matches_from(vec![
2874    ///         "prog", "--option=val1,val2,val3",
2875    ///     ]);
2876    ///
2877    /// assert!(delims.is_present("option"));
2878    /// assert_eq!(delims.occurrences_of("option"), 1);
2879    /// assert_eq!(delims.values_of("option").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"]);
2880    /// ```
2881    /// The next example shows the difference when turning delimiters off. This is the default
2882    /// behavior
2883    ///
2884    /// ```rust
2885    /// # use clap::{App, Arg};
2886    /// let nodelims = App::new("prog")
2887    ///     .arg(Arg::with_name("option")
2888    ///         .long("option")
2889    ///         .use_delimiter(false)
2890    ///         .takes_value(true))
2891    ///     .get_matches_from(vec![
2892    ///         "prog", "--option=val1,val2,val3",
2893    ///     ]);
2894    ///
2895    /// assert!(nodelims.is_present("option"));
2896    /// assert_eq!(nodelims.occurrences_of("option"), 1);
2897    /// assert_eq!(nodelims.value_of("option").unwrap(), "val1,val2,val3");
2898    /// ```
2899    /// [`Arg::value_delimiter`]: ./struct.Arg.html#method.value_delimiter
2900    pub fn use_delimiter(mut self, d: bool) -> Self {
2901        if d {
2902            if self.v.val_delim.is_none() {
2903                self.v.val_delim = Some(',');
2904            }
2905            self.setb(ArgSettings::TakesValue);
2906            self.setb(ArgSettings::UseValueDelimiter);
2907            self.unset(ArgSettings::ValueDelimiterNotSet)
2908        } else {
2909            self.v.val_delim = None;
2910            self.unsetb(ArgSettings::UseValueDelimiter);
2911            self.unset(ArgSettings::ValueDelimiterNotSet)
2912        }
2913    }
2914
2915    /// Specifies that *multiple values* may only be set using the delimiter. This means if an
2916    /// if an option is encountered, and no delimiter is found, it automatically assumed that no
2917    /// additional values for that option follow. This is unlike the default, where it is generally
2918    /// assumed that more values will follow regardless of whether or not a delimiter is used.
2919    ///
2920    /// **NOTE:** The default is `false`.
2921    ///
2922    /// **NOTE:** Setting this to true implies [`Arg::use_delimiter(true)`]
2923    ///
2924    /// **NOTE:** It's a good idea to inform the user that use of a delimiter is required, either
2925    /// through help text or other means.
2926    ///
2927    /// # Examples
2928    ///
2929    /// These examples demonstrate what happens when `require_delimiter(true)` is used. Notice
2930    /// everything works in this first example, as we use a delimiter, as expected.
2931    ///
2932    /// ```rust
2933    /// # use clap::{App, Arg};
2934    /// let delims = App::new("prog")
2935    ///     .arg(Arg::with_name("opt")
2936    ///         .short("o")
2937    ///         .takes_value(true)
2938    ///         .multiple(true)
2939    ///         .require_delimiter(true))
2940    ///     .get_matches_from(vec![
2941    ///         "prog", "-o", "val1,val2,val3",
2942    ///     ]);
2943    ///
2944    /// assert!(delims.is_present("opt"));
2945    /// assert_eq!(delims.values_of("opt").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"]);
2946    /// ```
2947    /// In this next example, we will *not* use a delimiter. Notice it's now an error.
2948    ///
2949    /// ```rust
2950    /// # use clap::{App, Arg, ErrorKind};
2951    /// let res = App::new("prog")
2952    ///     .arg(Arg::with_name("opt")
2953    ///         .short("o")
2954    ///         .takes_value(true)
2955    ///         .multiple(true)
2956    ///         .require_delimiter(true))
2957    ///     .get_matches_from_safe(vec![
2958    ///         "prog", "-o", "val1", "val2", "val3",
2959    ///     ]);
2960    ///
2961    /// assert!(res.is_err());
2962    /// let err = res.unwrap_err();
2963    /// assert_eq!(err.kind, ErrorKind::UnknownArgument);
2964    /// ```
2965    /// What's happening is `-o` is getting `val1`, and because delimiters are required yet none
2966    /// were present, it stops parsing `-o`. At this point it reaches `val2` and because no
2967    /// positional arguments have been defined, it's an error of an unexpected argument.
2968    ///
2969    /// In this final example, we contrast the above with `clap`'s default behavior where the above
2970    /// is *not* an error.
2971    ///
2972    /// ```rust
2973    /// # use clap::{App, Arg};
2974    /// let delims = App::new("prog")
2975    ///     .arg(Arg::with_name("opt")
2976    ///         .short("o")
2977    ///         .takes_value(true)
2978    ///         .multiple(true))
2979    ///     .get_matches_from(vec![
2980    ///         "prog", "-o", "val1", "val2", "val3",
2981    ///     ]);
2982    ///
2983    /// assert!(delims.is_present("opt"));
2984    /// assert_eq!(delims.values_of("opt").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"]);
2985    /// ```
2986    /// [`Arg::use_delimiter(true)`]: ./struct.Arg.html#method.use_delimiter
2987    pub fn require_delimiter(mut self, d: bool) -> Self {
2988        if d {
2989            self = self.use_delimiter(true);
2990            self.unsetb(ArgSettings::ValueDelimiterNotSet);
2991            self.setb(ArgSettings::UseValueDelimiter);
2992            self.set(ArgSettings::RequireDelimiter)
2993        } else {
2994            self = self.use_delimiter(false);
2995            self.unsetb(ArgSettings::UseValueDelimiter);
2996            self.unset(ArgSettings::RequireDelimiter)
2997        }
2998    }
2999
3000    /// Specifies the separator to use when values are clumped together, defaults to `,` (comma).
3001    ///
3002    /// **NOTE:** implicitly sets [`Arg::use_delimiter(true)`]
3003    ///
3004    /// **NOTE:** implicitly sets [`Arg::takes_value(true)`]
3005    ///
3006    /// # Examples
3007    ///
3008    /// ```rust
3009    /// # use clap::{App, Arg};
3010    /// let m = App::new("prog")
3011    ///     .arg(Arg::with_name("config")
3012    ///         .short("c")
3013    ///         .long("config")
3014    ///         .value_delimiter(";"))
3015    ///     .get_matches_from(vec![
3016    ///         "prog", "--config=val1;val2;val3"
3017    ///     ]);
3018    ///
3019    /// assert_eq!(m.values_of("config").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"])
3020    /// ```
3021    /// [`Arg::use_delimiter(true)`]: ./struct.Arg.html#method.use_delimiter
3022    /// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
3023    pub fn value_delimiter(mut self, d: &str) -> Self {
3024        self.unsetb(ArgSettings::ValueDelimiterNotSet);
3025        self.setb(ArgSettings::TakesValue);
3026        self.setb(ArgSettings::UseValueDelimiter);
3027        self.v.val_delim = Some(
3028            d.chars()
3029                .nth(0)
3030                .expect("Failed to get value_delimiter from arg"),
3031        );
3032        self
3033    }
3034
3035    /// Specify multiple names for values of option arguments. These names are cosmetic only, used
3036    /// for help and usage strings only. The names are **not** used to access arguments. The values
3037    /// of the arguments are accessed in numeric order (i.e. if you specify two names `one` and
3038    /// `two` `one` will be the first matched value, `two` will be the second).
3039    ///
3040    /// This setting can be very helpful when describing the type of input the user should be
3041    /// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to
3042    /// use all capital letters for the value name.
3043    ///
3044    /// **Pro Tip:** It may help to use [`Arg::next_line_help(true)`] if there are long, or
3045    /// multiple value names in order to not throw off the help text alignment of all options.
3046    ///
3047    /// **NOTE:** This implicitly sets [`Arg::number_of_values`] if the number of value names is
3048    /// greater than one. I.e. be aware that the number of "names" you set for the values, will be
3049    /// the *exact* number of values required to satisfy this argument
3050    ///
3051    /// **NOTE:** implicitly sets [`Arg::takes_value(true)`]
3052    ///
3053    /// **NOTE:** Does *not* require or imply [`Arg::multiple(true)`].
3054    ///
3055    /// # Examples
3056    ///
3057    /// ```rust
3058    /// # use clap::{App, Arg};
3059    /// Arg::with_name("speed")
3060    ///     .short("s")
3061    ///     .value_names(&["fast", "slow"])
3062    /// # ;
3063    /// ```
3064    ///
3065    /// ```rust
3066    /// # use clap::{App, Arg};
3067    /// let m = App::new("prog")
3068    ///     .arg(Arg::with_name("io")
3069    ///         .long("io-files")
3070    ///         .value_names(&["INFILE", "OUTFILE"]))
3071    ///     .get_matches_from(vec![
3072    ///         "prog", "--help"
3073    ///     ]);
3074    /// ```
3075    /// Running the above program produces the following output
3076    ///
3077    /// ```notrust
3078    /// valnames
3079    ///
3080    /// USAGE:
3081    ///    valnames [FLAGS] [OPTIONS]
3082    ///
3083    /// FLAGS:
3084    ///     -h, --help       Prints help information
3085    ///     -V, --version    Prints version information
3086    ///
3087    /// OPTIONS:
3088    ///     --io-files <INFILE> <OUTFILE>    Some help text
3089    /// ```
3090    /// [`Arg::next_line_help(true)`]: ./struct.Arg.html#method.next_line_help
3091    /// [`Arg::number_of_values`]: ./struct.Arg.html#method.number_of_values
3092    /// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
3093    /// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
3094    pub fn value_names(mut self, names: &[&'b str]) -> Self {
3095        self.setb(ArgSettings::TakesValue);
3096        if self.is_set(ArgSettings::ValueDelimiterNotSet) {
3097            self.unsetb(ArgSettings::ValueDelimiterNotSet);
3098            self.setb(ArgSettings::UseValueDelimiter);
3099        }
3100        if let Some(ref mut vals) = self.v.val_names {
3101            let mut l = vals.len();
3102            for s in names {
3103                vals.insert(l, s);
3104                l += 1;
3105            }
3106        } else {
3107            let mut vm = VecMap::new();
3108            for (i, n) in names.iter().enumerate() {
3109                vm.insert(i, *n);
3110            }
3111            self.v.val_names = Some(vm);
3112        }
3113        self
3114    }
3115
3116    /// Specifies the name for value of [option] or [positional] arguments inside of help
3117    /// documentation. This name is cosmetic only, the name is **not** used to access arguments.
3118    /// This setting can be very helpful when describing the type of input the user should be
3119    /// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to
3120    /// use all capital letters for the value name.
3121    ///
3122    /// **NOTE:** implicitly sets [`Arg::takes_value(true)`]
3123    ///
3124    /// # Examples
3125    ///
3126    /// ```rust
3127    /// # use clap::{App, Arg};
3128    /// Arg::with_name("cfg")
3129    ///     .long("config")
3130    ///     .value_name("FILE")
3131    /// # ;
3132    /// ```
3133    ///
3134    /// ```rust
3135    /// # use clap::{App, Arg};
3136    /// let m = App::new("prog")
3137    ///     .arg(Arg::with_name("config")
3138    ///         .long("config")
3139    ///         .value_name("FILE"))
3140    ///     .get_matches_from(vec![
3141    ///         "prog", "--help"
3142    ///     ]);
3143    /// ```
3144    /// Running the above program produces the following output
3145    ///
3146    /// ```notrust
3147    /// valnames
3148    ///
3149    /// USAGE:
3150    ///    valnames [FLAGS] [OPTIONS]
3151    ///
3152    /// FLAGS:
3153    ///     -h, --help       Prints help information
3154    ///     -V, --version    Prints version information
3155    ///
3156    /// OPTIONS:
3157    ///     --config <FILE>     Some help text
3158    /// ```
3159    /// [option]: ./struct.Arg.html#method.takes_value
3160    /// [positional]: ./struct.Arg.html#method.index
3161    /// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
3162    pub fn value_name(mut self, name: &'b str) -> Self {
3163        self.setb(ArgSettings::TakesValue);
3164        if let Some(ref mut vals) = self.v.val_names {
3165            let l = vals.len();
3166            vals.insert(l, name);
3167        } else {
3168            let mut vm = VecMap::new();
3169            vm.insert(0, name);
3170            self.v.val_names = Some(vm);
3171        }
3172        self
3173    }
3174
3175    /// Specifies the value of the argument when *not* specified at runtime.
3176    ///
3177    /// **NOTE:** If the user *does not* use this argument at runtime, [`ArgMatches::occurrences_of`]
3178    /// will return `0` even though the [`ArgMatches::value_of`] will return the default specified.
3179    ///
3180    /// **NOTE:** If the user *does not* use this argument at runtime [`ArgMatches::is_present`] will
3181    /// still return `true`. If you wish to determine whether the argument was used at runtime or
3182    /// not, consider [`ArgMatches::occurrences_of`] which will return `0` if the argument was *not*
3183    /// used at runtime.
3184    ///
3185    /// **NOTE:** This setting is perfectly compatible with [`Arg::default_value_if`] but slightly
3186    /// different. `Arg::default_value` *only* takes affect when the user has not provided this arg
3187    /// at runtime. `Arg::default_value_if` however only takes affect when the user has not provided
3188    /// a value at runtime **and** these other conditions are met as well. If you have set
3189    /// `Arg::default_value` and `Arg::default_value_if`, and the user **did not** provide a this
3190    /// arg at runtime, nor did were the conditions met for `Arg::default_value_if`, the
3191    /// `Arg::default_value` will be applied.
3192    ///
3193    /// **NOTE:** This implicitly sets [`Arg::takes_value(true)`].
3194    ///
3195    /// **NOTE:** This setting effectively disables `AppSettings::ArgRequiredElseHelp` if used in
3196    /// conjunction as it ensures that some argument will always be present.
3197    ///
3198    /// # Examples
3199    ///
3200    /// First we use the default value without providing any value at runtime.
3201    ///
3202    /// ```rust
3203    /// # use clap::{App, Arg};
3204    /// let m = App::new("prog")
3205    ///     .arg(Arg::with_name("opt")
3206    ///         .long("myopt")
3207    ///         .default_value("myval"))
3208    ///     .get_matches_from(vec![
3209    ///         "prog"
3210    ///     ]);
3211    ///
3212    /// assert_eq!(m.value_of("opt"), Some("myval"));
3213    /// assert!(m.is_present("opt"));
3214    /// assert_eq!(m.occurrences_of("opt"), 0);
3215    /// ```
3216    ///
3217    /// Next we provide a value at runtime to override the default.
3218    ///
3219    /// ```rust
3220    /// # use clap::{App, Arg};
3221    /// let m = App::new("prog")
3222    ///     .arg(Arg::with_name("opt")
3223    ///         .long("myopt")
3224    ///         .default_value("myval"))
3225    ///     .get_matches_from(vec![
3226    ///         "prog", "--myopt=non_default"
3227    ///     ]);
3228    ///
3229    /// assert_eq!(m.value_of("opt"), Some("non_default"));
3230    /// assert!(m.is_present("opt"));
3231    /// assert_eq!(m.occurrences_of("opt"), 1);
3232    /// ```
3233    /// [`ArgMatches::occurrences_of`]: ./struct.ArgMatches.html#method.occurrences_of
3234    /// [`ArgMatches::value_of`]: ./struct.ArgMatches.html#method.value_of
3235    /// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
3236    /// [`ArgMatches::is_present`]: ./struct.ArgMatches.html#method.is_present
3237    /// [`Arg::default_value_if`]: ./struct.Arg.html#method.default_value_if
3238    pub fn default_value(self, val: &'a str) -> Self {
3239        self.default_value_os(OsStr::from_bytes(val.as_bytes()))
3240    }
3241
3242    /// Provides a default value in the exact same manner as [`Arg::default_value`]
3243    /// only using [`OsStr`]s instead.
3244    /// [`Arg::default_value`]: ./struct.Arg.html#method.default_value
3245    /// [`OsStr`]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html
3246    pub fn default_value_os(mut self, val: &'a OsStr) -> Self {
3247        self.setb(ArgSettings::TakesValue);
3248        self.v.default_val = Some(val);
3249        self
3250    }
3251
3252    /// Specifies the value of the argument if `arg` has been used at runtime. If `val` is set to
3253    /// `None`, `arg` only needs to be present. If `val` is set to `"some-val"` then `arg` must be
3254    /// present at runtime **and** have the value `val`.
3255    ///
3256    /// **NOTE:** This setting is perfectly compatible with [`Arg::default_value`] but slightly
3257    /// different. `Arg::default_value` *only* takes affect when the user has not provided this arg
3258    /// at runtime. This setting however only takes affect when the user has not provided a value at
3259    /// runtime **and** these other conditions are met as well. If you have set `Arg::default_value`
3260    /// and `Arg::default_value_if`, and the user **did not** provide a this arg at runtime, nor did
3261    /// were the conditions met for `Arg::default_value_if`, the `Arg::default_value` will be
3262    /// applied.
3263    ///
3264    /// **NOTE:** This implicitly sets [`Arg::takes_value(true)`].
3265    ///
3266    /// **NOTE:** If using YAML the values should be laid out as follows (`None` can be represented
3267    /// as `null` in YAML)
3268    ///
3269    /// ```yaml
3270    /// default_value_if:
3271    ///     - [arg, val, default]
3272    /// ```
3273    ///
3274    /// # Examples
3275    ///
3276    /// First we use the default value only if another arg is present at runtime.
3277    ///
3278    /// ```rust
3279    /// # use clap::{App, Arg};
3280    /// let m = App::new("prog")
3281    ///     .arg(Arg::with_name("flag")
3282    ///         .long("flag"))
3283    ///     .arg(Arg::with_name("other")
3284    ///         .long("other")
3285    ///         .default_value_if("flag", None, "default"))
3286    ///     .get_matches_from(vec![
3287    ///         "prog", "--flag"
3288    ///     ]);
3289    ///
3290    /// assert_eq!(m.value_of("other"), Some("default"));
3291    /// ```
3292    ///
3293    /// Next we run the same test, but without providing `--flag`.
3294    ///
3295    /// ```rust
3296    /// # use clap::{App, Arg};
3297    /// let m = App::new("prog")
3298    ///     .arg(Arg::with_name("flag")
3299    ///         .long("flag"))
3300    ///     .arg(Arg::with_name("other")
3301    ///         .long("other")
3302    ///         .default_value_if("flag", None, "default"))
3303    ///     .get_matches_from(vec![
3304    ///         "prog"
3305    ///     ]);
3306    ///
3307    /// assert_eq!(m.value_of("other"), None);
3308    /// ```
3309    ///
3310    /// Now lets only use the default value if `--opt` contains the value `special`.
3311    ///
3312    /// ```rust
3313    /// # use clap::{App, Arg};
3314    /// let m = App::new("prog")
3315    ///     .arg(Arg::with_name("opt")
3316    ///         .takes_value(true)
3317    ///         .long("opt"))
3318    ///     .arg(Arg::with_name("other")
3319    ///         .long("other")
3320    ///         .default_value_if("opt", Some("special"), "default"))
3321    ///     .get_matches_from(vec![
3322    ///         "prog", "--opt", "special"
3323    ///     ]);
3324    ///
3325    /// assert_eq!(m.value_of("other"), Some("default"));
3326    /// ```
3327    ///
3328    /// We can run the same test and provide any value *other than* `special` and we won't get a
3329    /// default value.
3330    ///
3331    /// ```rust
3332    /// # use clap::{App, Arg};
3333    /// let m = App::new("prog")
3334    ///     .arg(Arg::with_name("opt")
3335    ///         .takes_value(true)
3336    ///         .long("opt"))
3337    ///     .arg(Arg::with_name("other")
3338    ///         .long("other")
3339    ///         .default_value_if("opt", Some("special"), "default"))
3340    ///     .get_matches_from(vec![
3341    ///         "prog", "--opt", "hahaha"
3342    ///     ]);
3343    ///
3344    /// assert_eq!(m.value_of("other"), None);
3345    /// ```
3346    /// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
3347    /// [`Arg::default_value`]: ./struct.Arg.html#method.default_value
3348    pub fn default_value_if(self, arg: &'a str, val: Option<&'b str>, default: &'b str) -> Self {
3349        self.default_value_if_os(
3350            arg,
3351            val.map(str::as_bytes).map(OsStr::from_bytes),
3352            OsStr::from_bytes(default.as_bytes()),
3353        )
3354    }
3355
3356    /// Provides a conditional default value in the exact same manner as [`Arg::default_value_if`]
3357    /// only using [`OsStr`]s instead.
3358    /// [`Arg::default_value_if`]: ./struct.Arg.html#method.default_value_if
3359    /// [`OsStr`]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html
3360    pub fn default_value_if_os(
3361        mut self,
3362        arg: &'a str,
3363        val: Option<&'b OsStr>,
3364        default: &'b OsStr,
3365    ) -> Self {
3366        self.setb(ArgSettings::TakesValue);
3367        if let Some(ref mut vm) = self.v.default_vals_ifs {
3368            let l = vm.len();
3369            vm.insert(l, (arg, val, default));
3370        } else {
3371            let mut vm = VecMap::new();
3372            vm.insert(0, (arg, val, default));
3373            self.v.default_vals_ifs = Some(vm);
3374        }
3375        self
3376    }
3377
3378    /// Specifies multiple values and conditions in the same manner as [`Arg::default_value_if`].
3379    /// The method takes a slice of tuples in the `(arg, Option<val>, default)` format.
3380    ///
3381    /// **NOTE**: The conditions are stored in order and evaluated in the same order. I.e. the first
3382    /// if multiple conditions are true, the first one found will be applied and the ultimate value.
3383    ///
3384    /// **NOTE:** If using YAML the values should be laid out as follows
3385    ///
3386    /// ```yaml
3387    /// default_value_if:
3388    ///     - [arg, val, default]
3389    ///     - [arg2, null, default2]
3390    /// ```
3391    ///
3392    /// # Examples
3393    ///
3394    /// First we use the default value only if another arg is present at runtime.
3395    ///
3396    /// ```rust
3397    /// # use clap::{App, Arg};
3398    /// let m = App::new("prog")
3399    ///     .arg(Arg::with_name("flag")
3400    ///         .long("flag"))
3401    ///     .arg(Arg::with_name("opt")
3402    ///         .long("opt")
3403    ///         .takes_value(true))
3404    ///     .arg(Arg::with_name("other")
3405    ///         .long("other")
3406    ///         .default_value_ifs(&[
3407    ///             ("flag", None, "default"),
3408    ///             ("opt", Some("channal"), "chan"),
3409    ///         ]))
3410    ///     .get_matches_from(vec![
3411    ///         "prog", "--opt", "channal"
3412    ///     ]);
3413    ///
3414    /// assert_eq!(m.value_of("other"), Some("chan"));
3415    /// ```
3416    ///
3417    /// Next we run the same test, but without providing `--flag`.
3418    ///
3419    /// ```rust
3420    /// # use clap::{App, Arg};
3421    /// let m = App::new("prog")
3422    ///     .arg(Arg::with_name("flag")
3423    ///         .long("flag"))
3424    ///     .arg(Arg::with_name("other")
3425    ///         .long("other")
3426    ///         .default_value_ifs(&[
3427    ///             ("flag", None, "default"),
3428    ///             ("opt", Some("channal"), "chan"),
3429    ///         ]))
3430    ///     .get_matches_from(vec![
3431    ///         "prog"
3432    ///     ]);
3433    ///
3434    /// assert_eq!(m.value_of("other"), None);
3435    /// ```
3436    ///
3437    /// We can also see that these values are applied in order, and if more than one condition is
3438    /// true, only the first evaluated "wins"
3439    ///
3440    /// ```rust
3441    /// # use clap::{App, Arg};
3442    /// let m = App::new("prog")
3443    ///     .arg(Arg::with_name("flag")
3444    ///         .long("flag"))
3445    ///     .arg(Arg::with_name("opt")
3446    ///         .long("opt")
3447    ///         .takes_value(true))
3448    ///     .arg(Arg::with_name("other")
3449    ///         .long("other")
3450    ///         .default_value_ifs(&[
3451    ///             ("flag", None, "default"),
3452    ///             ("opt", Some("channal"), "chan"),
3453    ///         ]))
3454    ///     .get_matches_from(vec![
3455    ///         "prog", "--opt", "channal", "--flag"
3456    ///     ]);
3457    ///
3458    /// assert_eq!(m.value_of("other"), Some("default"));
3459    /// ```
3460    /// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
3461    /// [`Arg::default_value`]: ./struct.Arg.html#method.default_value
3462    pub fn default_value_ifs(mut self, ifs: &[(&'a str, Option<&'b str>, &'b str)]) -> Self {
3463        for &(arg, val, default) in ifs {
3464            self = self.default_value_if_os(
3465                arg,
3466                val.map(str::as_bytes).map(OsStr::from_bytes),
3467                OsStr::from_bytes(default.as_bytes()),
3468            );
3469        }
3470        self
3471    }
3472
3473    /// Provides multiple conditional default values in the exact same manner as
3474    /// [`Arg::default_value_ifs`] only using [`OsStr`]s instead.
3475    /// [`Arg::default_value_ifs`]: ./struct.Arg.html#method.default_value_ifs
3476    /// [`OsStr`]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html
3477    #[cfg_attr(feature = "lints", allow(explicit_counter_loop))]
3478    pub fn default_value_ifs_os(mut self, ifs: &[(&'a str, Option<&'b OsStr>, &'b OsStr)]) -> Self {
3479        for &(arg, val, default) in ifs {
3480            self = self.default_value_if_os(arg, val, default);
3481        }
3482        self
3483    }
3484
3485    /// Specifies that if the value is not passed in as an argument, that it should be retrieved
3486    /// from the environment, if available. If it is not present in the environment, then default
3487    /// rules will apply.
3488    ///
3489    /// **NOTE:** If the user *does not* use this argument at runtime, [`ArgMatches::occurrences_of`]
3490    /// will return `0` even though the [`ArgMatches::value_of`] will return the default specified.
3491    ///
3492    /// **NOTE:** If the user *does not* use this argument at runtime [`ArgMatches::is_present`] will
3493    /// return `true` if the variable is present in the environment . If you wish to determine whether
3494    /// the argument was used at runtime or not, consider [`ArgMatches::occurrences_of`] which will
3495    /// return `0` if the argument was *not* used at runtime.
3496    ///
3497    /// **NOTE:** This implicitly sets [`Arg::takes_value(true)`].
3498    ///
3499    /// **NOTE:** If [`Arg::multiple(true)`] is set then [`Arg::use_delimiter(true)`] should also be
3500    /// set. Otherwise, only a single argument will be returned from the environment variable. The
3501    /// default delimiter is `,` and follows all the other delimiter rules.
3502    ///
3503    /// # Examples
3504    ///
3505    /// In this example, we show the variable coming from the environment:
3506    ///
3507    /// ```rust
3508    /// # use std::env;
3509    /// # use clap::{App, Arg};
3510    ///
3511    /// env::set_var("MY_FLAG", "env");
3512    ///
3513    /// let m = App::new("prog")
3514    ///     .arg(Arg::with_name("flag")
3515    ///         .long("flag")
3516    ///         .env("MY_FLAG"))
3517    ///     .get_matches_from(vec![
3518    ///         "prog"
3519    ///     ]);
3520    ///
3521    /// assert_eq!(m.value_of("flag"), Some("env"));
3522    /// ```
3523    ///
3524    /// In this example, we show the variable coming from an option on the CLI:
3525    ///
3526    /// ```rust
3527    /// # use std::env;
3528    /// # use clap::{App, Arg};
3529    ///
3530    /// env::set_var("MY_FLAG", "env");
3531    ///
3532    /// let m = App::new("prog")
3533    ///     .arg(Arg::with_name("flag")
3534    ///         .long("flag")
3535    ///         .env("MY_FLAG"))
3536    ///     .get_matches_from(vec![
3537    ///         "prog", "--flag", "opt"
3538    ///     ]);
3539    ///
3540    /// assert_eq!(m.value_of("flag"), Some("opt"));
3541    /// ```
3542    ///
3543    /// In this example, we show the variable coming from the environment even with the
3544    /// presence of a default:
3545    ///
3546    /// ```rust
3547    /// # use std::env;
3548    /// # use clap::{App, Arg};
3549    ///
3550    /// env::set_var("MY_FLAG", "env");
3551    ///
3552    /// let m = App::new("prog")
3553    ///     .arg(Arg::with_name("flag")
3554    ///         .long("flag")
3555    ///         .env("MY_FLAG")
3556    ///         .default_value("default"))
3557    ///     .get_matches_from(vec![
3558    ///         "prog"
3559    ///     ]);
3560    ///
3561    /// assert_eq!(m.value_of("flag"), Some("env"));
3562    /// ```
3563    ///
3564    /// In this example, we show the use of multiple values in a single environment variable:
3565    ///
3566    /// ```rust
3567    /// # use std::env;
3568    /// # use clap::{App, Arg};
3569    ///
3570    /// env::set_var("MY_FLAG_MULTI", "env1,env2");
3571    ///
3572    /// let m = App::new("prog")
3573    ///     .arg(Arg::with_name("flag")
3574    ///         .long("flag")
3575    ///         .env("MY_FLAG_MULTI")
3576    ///         .multiple(true)
3577    ///         .use_delimiter(true))
3578    ///     .get_matches_from(vec![
3579    ///         "prog"
3580    ///     ]);
3581    ///
3582    /// assert_eq!(m.values_of("flag").unwrap().collect::<Vec<_>>(), vec!["env1", "env2"]);
3583    /// ```
3584    /// [`ArgMatches::occurrences_of`]: ./struct.ArgMatches.html#method.occurrences_of
3585    /// [`ArgMatches::value_of`]: ./struct.ArgMatches.html#method.value_of
3586    /// [`ArgMatches::is_present`]: ./struct.ArgMatches.html#method.is_present
3587    /// [`Arg::takes_value(true)`]: ./struct.Arg.html#method.takes_value
3588    /// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
3589    /// [`Arg::use_delimiter(true)`]: ./struct.Arg.html#method.use_delimiter
3590    pub fn env(self, name: &'a str) -> Self {
3591        self.env_os(OsStr::new(name))
3592    }
3593
3594    /// Specifies that if the value is not passed in as an argument, that it should be retrieved
3595    /// from the environment if available in the exact same manner as [`Arg::env`] only using
3596    /// [`OsStr`]s instead.
3597    pub fn env_os(mut self, name: &'a OsStr) -> Self {
3598        self.setb(ArgSettings::TakesValue);
3599
3600        self.v.env = Some((name, env::var_os(name)));
3601        self
3602    }
3603
3604    /// @TODO @p2 @docs @release: write docs
3605    pub fn hide_env_values(self, hide: bool) -> Self {
3606        if hide {
3607            self.set(ArgSettings::HideEnvValues)
3608        } else {
3609            self.unset(ArgSettings::HideEnvValues)
3610        }
3611    }
3612
3613    /// When set to `true` the help string will be displayed on the line after the argument and
3614    /// indented once. This can be helpful for arguments with very long or complex help messages.
3615    /// This can also be helpful for arguments with very long flag names, or many/long value names.
3616    ///
3617    /// **NOTE:** To apply this setting to all arguments consider using
3618    /// [`AppSettings::NextLineHelp`]
3619    ///
3620    /// # Examples
3621    ///
3622    /// ```rust
3623    /// # use clap::{App, Arg};
3624    /// let m = App::new("prog")
3625    ///     .arg(Arg::with_name("opt")
3626    ///         .long("long-option-flag")
3627    ///         .short("o")
3628    ///         .takes_value(true)
3629    ///         .value_names(&["value1", "value2"])
3630    ///         .help("Some really long help and complex\n\
3631    ///                help that makes more sense to be\n\
3632    ///                on a line after the option")
3633    ///         .next_line_help(true))
3634    ///     .get_matches_from(vec![
3635    ///         "prog", "--help"
3636    ///     ]);
3637    /// ```
3638    ///
3639    /// The above example displays the following help message
3640    ///
3641    /// ```notrust
3642    /// nlh
3643    ///
3644    /// USAGE:
3645    ///     nlh [FLAGS] [OPTIONS]
3646    ///
3647    /// FLAGS:
3648    ///     -h, --help       Prints help information
3649    ///     -V, --version    Prints version information
3650    ///
3651    /// OPTIONS:
3652    ///     -o, --long-option-flag <value1> <value2>
3653    ///         Some really long help and complex
3654    ///         help that makes more sense to be
3655    ///         on a line after the option
3656    /// ```
3657    /// [`AppSettings::NextLineHelp`]: ./enum.AppSettings.html#variant.NextLineHelp
3658    pub fn next_line_help(mut self, nlh: bool) -> Self {
3659        if nlh {
3660            self.setb(ArgSettings::NextLineHelp);
3661        } else {
3662            self.unsetb(ArgSettings::NextLineHelp);
3663        }
3664        self
3665    }
3666
3667    /// Allows custom ordering of args within the help message. Args with a lower value will be
3668    /// displayed first in the help message. This is helpful when one would like to emphasise
3669    /// frequently used args, or prioritize those towards the top of the list. Duplicate values
3670    /// **are** allowed. Args with duplicate display orders will be displayed in alphabetical
3671    /// order.
3672    ///
3673    /// **NOTE:** The default is 999 for all arguments.
3674    ///
3675    /// **NOTE:** This setting is ignored for [positional arguments] which are always displayed in
3676    /// [index] order.
3677    ///
3678    /// # Examples
3679    ///
3680    /// ```rust
3681    /// # use clap::{App, Arg};
3682    /// let m = App::new("prog")
3683    ///     .arg(Arg::with_name("a") // Typically args are grouped alphabetically by name.
3684    ///                              // Args without a display_order have a value of 999 and are
3685    ///                              // displayed alphabetically with all other 999 valued args.
3686    ///         .long("long-option")
3687    ///         .short("o")
3688    ///         .takes_value(true)
3689    ///         .help("Some help and text"))
3690    ///     .arg(Arg::with_name("b")
3691    ///         .long("other-option")
3692    ///         .short("O")
3693    ///         .takes_value(true)
3694    ///         .display_order(1)   // In order to force this arg to appear *first*
3695    ///                             // all we have to do is give it a value lower than 999.
3696    ///                             // Any other args with a value of 1 will be displayed
3697    ///                             // alphabetically with this one...then 2 values, then 3, etc.
3698    ///         .help("I should be first!"))
3699    ///     .get_matches_from(vec![
3700    ///         "prog", "--help"
3701    ///     ]);
3702    /// ```
3703    ///
3704    /// The above example displays the following help message
3705    ///
3706    /// ```notrust
3707    /// cust-ord
3708    ///
3709    /// USAGE:
3710    ///     cust-ord [FLAGS] [OPTIONS]
3711    ///
3712    /// FLAGS:
3713    ///     -h, --help       Prints help information
3714    ///     -V, --version    Prints version information
3715    ///
3716    /// OPTIONS:
3717    ///     -O, --other-option <b>    I should be first!
3718    ///     -o, --long-option <a>     Some help and text
3719    /// ```
3720    /// [positional arguments]: ./struct.Arg.html#method.index
3721    /// [index]: ./struct.Arg.html#method.index
3722    pub fn display_order(mut self, ord: usize) -> Self {
3723        self.s.disp_ord = ord;
3724        self
3725    }
3726
3727    /// Indicates that all parameters passed after this should not be parsed
3728    /// individually, but rather passed in their entirety. It is worth noting
3729    /// that setting this requires all values to come after a `--` to indicate they
3730    /// should all be captured. For example:
3731    ///
3732    /// ```notrust
3733    /// --foo something -- -v -v -v -b -b -b --baz -q -u -x
3734    /// ```
3735    /// Will result in everything after `--` to be considered one raw argument. This behavior
3736    /// may not be exactly what you are expecting and using [`AppSettings::TrailingVarArg`]
3737    /// may be more appropriate.
3738    ///
3739    /// **NOTE:** Implicitly sets [`Arg::multiple(true)`], [`Arg::allow_hyphen_values(true)`], and
3740    /// [`Arg::last(true)`] when set to `true`
3741    ///
3742    /// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple
3743    /// [`Arg::allow_hyphen_values(true)`]: ./struct.Arg.html#method.allow_hyphen_values
3744    /// [`Arg::last(true)`]: ./struct.Arg.html#method.last
3745    /// [`AppSettings::TrailingVarArg`]: ./enum.AppSettings.html#variant.TrailingVarArg
3746    pub fn raw(self, raw: bool) -> Self {
3747        self.multiple(raw).allow_hyphen_values(raw).last(raw)
3748    }
3749
3750    /// Hides an argument from short help message output.
3751    ///
3752    /// **NOTE:** This does **not** hide the argument from usage strings on error
3753    ///
3754    /// **NOTE:** Setting this option will cause next-line-help output style to be used
3755    /// when long help (`--help`) is called.
3756    ///
3757    /// # Examples
3758    ///
3759    /// ```rust
3760    /// # use clap::{App, Arg};
3761    /// Arg::with_name("debug")
3762    ///     .hidden_short_help(true)
3763    /// # ;
3764    /// ```
3765    /// Setting `hidden_short_help(true)` will hide the argument when displaying short help text
3766    ///
3767    /// ```rust
3768    /// # use clap::{App, Arg};
3769    /// let m = App::new("prog")
3770    ///     .arg(Arg::with_name("cfg")
3771    ///         .long("config")
3772    ///         .hidden_short_help(true)
3773    ///         .help("Some help text describing the --config arg"))
3774    ///     .get_matches_from(vec![
3775    ///         "prog", "-h"
3776    ///     ]);
3777    /// ```
3778    ///
3779    /// The above example displays
3780    ///
3781    /// ```notrust
3782    /// helptest
3783    ///
3784    /// USAGE:
3785    ///    helptest [FLAGS]
3786    ///
3787    /// FLAGS:
3788    /// -h, --help       Prints help information
3789    /// -V, --version    Prints version information
3790    /// ```
3791    ///
3792    /// However, when --help is called
3793    ///
3794    /// ```rust
3795    /// # use clap::{App, Arg};
3796    /// let m = App::new("prog")
3797    ///     .arg(Arg::with_name("cfg")
3798    ///         .long("config")
3799    ///         .hidden_short_help(true)
3800    ///         .help("Some help text describing the --config arg"))
3801    ///     .get_matches_from(vec![
3802    ///         "prog", "--help"
3803    ///     ]);
3804    /// ```
3805    ///
3806    /// Then the following would be displayed
3807    ///
3808    /// ```notrust
3809    /// helptest
3810    ///
3811    /// USAGE:
3812    ///    helptest [FLAGS]
3813    ///
3814    /// FLAGS:
3815    ///     --config     Some help text describing the --config arg
3816    /// -h, --help       Prints help information
3817    /// -V, --version    Prints version information
3818    /// ```
3819    pub fn hidden_short_help(self, hide: bool) -> Self {
3820        if hide {
3821            self.set(ArgSettings::HiddenShortHelp)
3822        } else {
3823            self.unset(ArgSettings::HiddenShortHelp)
3824        }
3825    }
3826
3827    /// Hides an argument from long help message output.
3828    ///
3829    /// **NOTE:** This does **not** hide the argument from usage strings on error
3830    ///
3831    /// **NOTE:** Setting this option will cause next-line-help output style to be used
3832    /// when long help (`--help`) is called.
3833    ///
3834    /// # Examples
3835    ///
3836    /// ```rust
3837    /// # use clap::{App, Arg};
3838    /// Arg::with_name("debug")
3839    ///     .hidden_long_help(true)
3840    /// # ;
3841    /// ```
3842    /// Setting `hidden_long_help(true)` will hide the argument when displaying long help text
3843    ///
3844    /// ```rust
3845    /// # use clap::{App, Arg};
3846    /// let m = App::new("prog")
3847    ///     .arg(Arg::with_name("cfg")
3848    ///         .long("config")
3849    ///         .hidden_long_help(true)
3850    ///         .help("Some help text describing the --config arg"))
3851    ///     .get_matches_from(vec![
3852    ///         "prog", "--help"
3853    ///     ]);
3854    /// ```
3855    ///
3856    /// The above example displays
3857    ///
3858    /// ```notrust
3859    /// helptest
3860    ///
3861    /// USAGE:
3862    ///    helptest [FLAGS]
3863    ///
3864    /// FLAGS:
3865    /// -h, --help       Prints help information
3866    /// -V, --version    Prints version information
3867    /// ```
3868    ///
3869    /// However, when -h is called
3870    ///
3871    /// ```rust
3872    /// # use clap::{App, Arg};
3873    /// let m = App::new("prog")
3874    ///     .arg(Arg::with_name("cfg")
3875    ///         .long("config")
3876    ///         .hidden_long_help(true)
3877    ///         .help("Some help text describing the --config arg"))
3878    ///     .get_matches_from(vec![
3879    ///         "prog", "-h"
3880    ///     ]);
3881    /// ```
3882    ///
3883    /// Then the following would be displayed
3884    ///
3885    /// ```notrust
3886    /// helptest
3887    ///
3888    /// USAGE:
3889    ///    helptest [FLAGS]
3890    ///
3891    /// FLAGS:
3892    ///     --config     Some help text describing the --config arg
3893    /// -h, --help       Prints help information
3894    /// -V, --version    Prints version information
3895    /// ```
3896    pub fn hidden_long_help(self, hide: bool) -> Self {
3897        if hide {
3898            self.set(ArgSettings::HiddenLongHelp)
3899        } else {
3900            self.unset(ArgSettings::HiddenLongHelp)
3901        }
3902    }
3903
3904    /// Checks if one of the [`ArgSettings`] settings is set for the argument.
3905    ///
3906    /// [`ArgSettings`]: ./enum.ArgSettings.html
3907    pub fn is_set(&self, s: ArgSettings) -> bool {
3908        self.b.is_set(s)
3909    }
3910
3911    /// Sets one of the [`ArgSettings`] settings for the argument.
3912    ///
3913    /// [`ArgSettings`]: ./enum.ArgSettings.html
3914    pub fn set(mut self, s: ArgSettings) -> Self {
3915        self.setb(s);
3916        self
3917    }
3918
3919    /// Unsets one of the [`ArgSettings`] settings for the argument.
3920    ///
3921    /// [`ArgSettings`]: ./enum.ArgSettings.html
3922    pub fn unset(mut self, s: ArgSettings) -> Self {
3923        self.unsetb(s);
3924        self
3925    }
3926
3927    #[doc(hidden)]
3928    pub fn setb(&mut self, s: ArgSettings) {
3929        self.b.set(s);
3930    }
3931
3932    #[doc(hidden)]
3933    pub fn unsetb(&mut self, s: ArgSettings) {
3934        self.b.unset(s);
3935    }
3936}
3937
3938impl<'a, 'b, 'z> From<&'z Arg<'a, 'b>> for Arg<'a, 'b> {
3939    fn from(a: &'z Arg<'a, 'b>) -> Self {
3940        Arg {
3941            b: a.b.clone(),
3942            v: a.v.clone(),
3943            s: a.s.clone(),
3944            index: a.index,
3945            r_ifs: a.r_ifs.clone(),
3946        }
3947    }
3948}
3949
3950impl<'n, 'e> PartialEq for Arg<'n, 'e> {
3951    fn eq(&self, other: &Arg<'n, 'e>) -> bool {
3952        self.b == other.b
3953    }
3954}