clap/args/subcommand.rs
1// Third Party
2#[cfg(feature = "yaml")]
3use yaml_rust::Yaml;
4
5// Internal
6use App;
7use ArgMatches;
8
9/// The abstract representation of a command line subcommand.
10///
11/// This struct describes all the valid options of the subcommand for the program. Subcommands are
12/// essentially "sub-[`App`]s" and contain all the same possibilities (such as their own
13/// [arguments], subcommands, and settings).
14///
15/// # Examples
16///
17/// ```rust
18/// # use clap::{App, Arg, SubCommand};
19/// App::new("myprog")
20/// .subcommand(
21/// SubCommand::with_name("config")
22/// .about("Used for configuration")
23/// .arg(Arg::with_name("config_file")
24/// .help("The configuration file to use")
25/// .index(1)))
26/// # ;
27/// ```
28/// [`App`]: ./struct.App.html
29/// [arguments]: ./struct.Arg.html
30#[derive(Debug, Clone)]
31pub struct SubCommand<'a> {
32 #[doc(hidden)] pub name: String,
33 #[doc(hidden)] pub matches: ArgMatches<'a>,
34}
35
36impl<'a> SubCommand<'a> {
37 /// Creates a new instance of a subcommand requiring a name. The name will be displayed
38 /// to the user when they print version or help and usage information.
39 ///
40 /// # Examples
41 ///
42 /// ```rust
43 /// # use clap::{App, Arg, SubCommand};
44 /// App::new("myprog")
45 /// .subcommand(
46 /// SubCommand::with_name("config"))
47 /// # ;
48 /// ```
49 pub fn with_name<'b>(name: &str) -> App<'a, 'b> { App::new(name) }
50
51 /// Creates a new instance of a subcommand from a YAML (.yml) document
52 ///
53 /// # Examples
54 ///
55 /// ```ignore
56 /// # #[macro_use]
57 /// # extern crate clap;
58 /// # use clap::Subcommand;
59 /// # fn main() {
60 /// let sc_yaml = load_yaml!("test_subcommand.yml");
61 /// let sc = SubCommand::from_yaml(sc_yaml);
62 /// # }
63 /// ```
64 #[cfg(feature = "yaml")]
65 pub fn from_yaml(yaml: &Yaml) -> App { App::from_yaml(yaml) }
66}