      1
      2
      3
      4
      5
      6
      7
      8
      9
     10
     11
     12
     13
     14
     15
     16
     17
     18
     19
     20
     21
     22
     23
     24
     25
     26
     27
     28
     29
     30
     31
     32
     33
     34
     35
     36
     37
     38
     39
     40
     41
     42
     43
     44
     45
     46
     47
     48
     49
     50
     51
     52
     53
     54
     55
     56
     57
     58
     59
     60
     61
     62
     63
     64
     65
     66
     67
     68
     69
     70
     71
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214
    215
    216
    217
    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232
    233
    234
    235
    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247
    248
    249
    250
    251
    252
    253
    254
    255
    256
    257
    258
    259
    260
    261
    262
    263
    264
    265
    266
    267
    268
    269
    270
    271
    272
    273
    274
    275
    276
    277
    278
    279
    280
    281
    282

    use std::collections::HashMap;

    use args::SubCommand;
    use args::MatchedArg;

    /// Used to get information about the arguments that where supplied to the program at runtime by
    /// the user. To get a new instance of this struct you use `.get_matches()` of the `App` struct.
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # use clap::{App, Arg};
    /// let matches = App::new("MyApp")
    /// // adding of arguments and configuration goes here...
    /// #                    .arg(Arg::with_name("config")
    /// #                               .long("config")
    /// #                               .required(true)
    /// #                               .takes_value(true))
    /// #                    .arg(Arg::with_name("debug")
    /// #                                   .short("d")
    /// #                                   .multiple(true))
    ///                     .get_matches();
    /// // if you had an argument named "output" that takes a value
    /// if let Some(o) = matches.value_of("output") {
    ///     println!("Value for output: {}", o);
    /// }
    ///
    /// // If you have a required argument you can call .unwrap() because the program will exit long
    /// // before this point if the user didn't specify it at runtime.
    /// println!("Config file: {}", matches.value_of("config").unwrap());
    ///
    /// // You can check the presence of an argument
    /// if matches.is_present("debug") {
    ///     // Another way to check if an argument was present, or if it occurred multiple times is to
    ///     // use occurrences_of() which returns 0 if an argument isn't found at runtime, or the
    ///     // number of times that it occurred, if it was. To allow an argument to appear more than
    ///     // once, you must use the .multiple(true) method, otherwise it will only return 1 or 0.
    ///     if matches.occurrences_of("debug") > 2 {
    ///         println!("Debug mode is REALLY on");
    ///     } else {
    ///         println!("Debug mode kind of on");
    ///     }
    /// }
    ///
    /// // You can get the sub-matches of a particular subcommand (in this case "test")
    /// // If "test" had it's own "-l" flag you could check for it's presence accordingly
    /// if let Some(ref matches) = matches.subcommand_matches("test") {
    ///     if matches.is_present("list") {
    ///         println!("Printing testing lists...");
    ///     } else {
    ///         println!("Not printing testing lists...");
    ///     }
    /// }
    #[derive(Debug)]
    pub struct ArgMatches<'n, 'a> {
        #[doc(hidden)]
        pub args: HashMap<&'a str, MatchedArg>,
        #[doc(hidden)]
        pub subcommand: Option<Box<SubCommand<'n, 'a>>>,
        #[doc(hidden)]
        pub usage: Option<String>,
    }

    impl<'n, 'a> ArgMatches<'n, 'a> {
        /// Creates a new instance of `ArgMatches`. This ins't called directly, but
        /// through the `.get_matches()` method of `App`
        ///
        /// # Examples
        ///
        /// ```no_run
        /// # use clap::{App, Arg};
        /// let matches = App::new("myprog").get_matches();
        /// ```
        #[doc(hidden)]
        pub fn new() -> ArgMatches<'n, 'a> {
            ArgMatches {
                args: HashMap::new(),
                subcommand: None,
                usage: None,
            }
        }

        /// Gets the value of a specific option or positional argument (i.e. an argument that takes
        /// an additional value at runtime). If the option wasn't present at runtime
        /// it returns `None`.
        ///
        /// *NOTE:* If getting a value for an option or positional argument that allows multiples,
        /// prefer `values_of()` as `value_of()` will only return the _*first*_ value.
        ///
        /// # Examples
        ///
        /// ```no_run
        /// # use clap::{App, Arg};
        /// # let matches = App::new("myapp")
        /// #     .arg(Arg::with_name("output")
        /// #         .takes_value(true))
        /// #     .get_matches();
        /// if let Some(o) = matches.value_of("output") {
        ///        println!("Value for output: {}", o);
        /// }
        /// ```
        pub fn value_of(&self, name: &str) -> Option<&str> {
            if let Some(ref arg) = self.args.get(name) {
                if let Some(ref vals) = arg.values {
                    if let Some(ref val) = vals.values().nth(0) {
                        return Some(&val[..]);
                    }
                }
            }
            None
        }

        /// Gets the values of a specific option or positional argument in a vector (i.e. an argument
        /// that takes multiple values at runtime). If the option wasn't present at runtime it
        /// returns `None`
        ///
        /// # Examples
        ///
        /// ```no_run
        /// # use clap::{App, Arg};
        /// # let matches = App::new("myapp")
        /// #     .arg(Arg::with_name("output").takes_value(true)).get_matches();
        /// // If the program had option "-c" that took a value and was run
        /// // via "myapp -o some -o other -o file"
        /// // values_of() would return a [&str; 3] ("some", "other", "file")
        /// if let Some(os) = matches.values_of("output") {
        ///        for o in os {
        ///            println!("A value for output: {}", o);
        ///        }
        /// }
        /// ```
        pub fn values_of(&'a self, name: &str) -> Option<Vec<&'a str>> {
            if let Some(ref arg) = self.args.get(name) {
                if let Some(ref vals) = arg.values {
                    return Some(vals.values().map(|s| &s[..]).collect::<Vec<_>>());
                }
            }
            None
        }

        /// Returns if an argument was present at runtime.
        ///
        ///
        /// # Examples
        ///
        /// ```no_run
        /// # use clap::{App, Arg};
        /// # let matches = App::new("myapp")
        /// #     .arg(Arg::with_name("output").takes_value(true)).get_matches();
        /// if matches.is_present("output") {
        ///        println!("The output argument was used!");
        /// }
        /// ```
        pub fn is_present(&self, name: &str) -> bool {
            if let Some(ref sc) = self.subcommand {
                if sc.name == name {
                    return true;
                }
            }
            if self.args.contains_key(name) {
                return true;
            }
            false
        }

        /// Returns the number of occurrences of an option, flag, or positional argument at runtime.
        /// If an argument isn't present it will return `0`. Can be used on arguments which *don't*
        /// allow multiple occurrences, but will obviously only return `0` or `1`.
        ///
        ///
        /// # Examples
        ///
        /// ```no_run
        /// # use clap::{App, Arg};
        /// # let matches = App::new("myapp")
        /// #     .arg(Arg::with_name("output").takes_value(true)).get_matches();
        /// if matches.occurrences_of("debug") > 1 {
        ///     println!("Debug mode is REALLY on");
        /// } else {
        ///     println!("Debug mode kind of on");
        /// }
        /// ```
        pub fn occurrences_of(&self, name: &str) -> u8 {
            if let Some(ref arg) = self.args.get(name) {
                return arg.occurrences;
            }
            0
        }

        /// Returns the `ArgMatches` for a particular subcommand or None if the subcommand wasn't
        /// present at runtime.
        ///
        ///
        /// # Examples
        ///
        /// ```no_run
        /// # use clap::{App, Arg, SubCommand};
        /// # let app_matches = App::new("myapp")
        /// #     .subcommand(SubCommand::with_name("test")).get_matches();
        /// if let Some(matches) = app_matches.subcommand_matches("test") {
        ///     // Use matches as normal
        /// }
        /// ```
        pub fn subcommand_matches<'na>(&self, name: &'na str) -> Option<&ArgMatches> {
            if let Some(ref sc) = self.subcommand {
                if sc.name != name {
                    return None;
                }
                return Some(&sc.matches);
            }
            None
        }

        /// Returns the name of the subcommand used of the parent `App`, or `None` if one wasn't found
        ///
        /// *NOTE*: Only a single subcommand may be present per `App` at runtime, does *NOT* check for
        /// the name of sub-subcommand's names
        ///
        ///
        /// # Examples
        ///
        /// ```no_run
        /// # use clap::{App, Arg, SubCommand};
        /// # let app_matches = App::new("myapp")
        /// #     .subcommand(SubCommand::with_name("test")).get_matches();
        /// match app_matches.subcommand_name() {
        ///     Some("test")   => {}, // test was used
        ///     Some("config") => {}, // config was used
        ///     _              => {}, // Either no subcommand or one not tested for...
        /// }
        /// ```
        pub fn subcommand_name(&self) -> Option<&str> {
            if let Some(ref sc) = self.subcommand {
                return Some(&sc.name[..]);
            }
            None
        }

        /// Returns the name and `ArgMatches` of the subcommand used at runtime or ("", None) if one
        /// wasn't found.
        ///
        ///
        /// # Examples
        ///
        /// ```no_run
        /// # use clap::{App, Arg, SubCommand};
        /// # let app_matches = App::new("myapp")
        /// #     .subcommand(SubCommand::with_name("test")).get_matches();
        /// match app_matches.subcommand() {
        ///     ("test", Some(matches))   => {}, // test was used
        ///     ("config", Some(matches)) => {}, // config was used
        ///     _                         => {}, // Either no subcommand or one not tested for...
        /// }
        /// ```
        pub fn subcommand(&self) -> (&str, Option<&ArgMatches>) {
            if let Some(ref sc) = self.subcommand {
                return (&sc.name[..], Some(&sc.matches));
            }
            ("", None)
        }

        /// Returns a string slice of the usage statement for the `App` (or `SubCommand`)
        ///
        ///
        /// # Examples
        ///
        /// ```no_run
        /// # use clap::{App, Arg, SubCommand};
        /// # let app_matches = App::new("myapp")
        /// #     .subcommand(SubCommand::with_name("test")).get_matches();
        /// println!("{}",app_matches.usage());
        /// ```
        pub fn usage(&self) -> &str {
            if let Some(ref u) = self.usage {
                return &u[..];
            }

            // Should be un-reachable
            ""
        }
    }

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)