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