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
use std::str::FromStr;
use std::ascii::AsciiExt;
/// Application level settings, which affect how `App` operates
#[derive(PartialEq, Debug)]
pub enum AppSettings {
/// Allows subcommands to override all requirements of the parent (this command). For example
/// if you had a subcommand or even top level application which had a required arguments that
/// are only required as long as there is no subcommand present.
///
/// **NOTE:** This defaults to false (using subcommand does *not* negate requirements)
///
/// # Example
///
/// ```no_run
/// # use clap::{App, AppSettings};
/// App::new("myprog")
/// .setting(AppSettings::SubcommandsNegateReqs)
/// # ;
/// ```
SubcommandsNegateReqs,
/// Allows specifying that if no subcommand is present at runtime, error and exit gracefully
///
/// **NOTE:** This defaults to false (subcommands do *not* need to be present)
///
/// # Example
///
/// ```no_run
/// # use clap::{App, AppSettings};
/// App::new("myprog")
/// .setting(AppSettings::SubcommandRequired)
/// # ;
/// ```
SubcommandRequired,
/// Specifies that the help text sould be displayed (and then exit gracefully), if no
/// arguments are present at runtime (i.e. an empty run such as, `$ myprog`.
///
/// **NOTE:** Subcommands count as arguments
///
/// # Example
///
/// ```no_run
/// # use clap::{App, AppSettings};
/// App::new("myprog")
/// .setting(AppSettings::ArgRequiredElseHelp)
/// # ;
/// ```
ArgRequiredElseHelp,
/// Uses version of the current command for all subcommands. (Defaults to false; subcommands
/// have independant version strings)
///
/// **NOTE:** The version for the current command and this setting must be set **prior** to
/// adding any subcommands
///
/// # Example
///
/// ```no_run
/// # use clap::{App, Arg, SubCommand, AppSettings};
/// App::new("myprog")
/// .version("v1.1")
/// .setting(AppSettings::GlobalVersion)
/// .subcommand(SubCommand::with_name("test"))
/// .get_matches();
/// // running `myprog test --version` will display
/// // "myprog-test v1.1"
/// ```
GlobalVersion,
/// Disables `-V` and `--version` for all subcommands (Defaults to false; subcommands have
/// version flags)
///
/// **NOTE:** This setting must be set **prior** adding any subcommands
///
/// **NOTE:** Do not set this value to false, it will have undesired results!
///
/// # Example
///
/// ```no_run
/// # use clap::{App, Arg, SubCommand, AppSettings};
/// App::new("myprog")
/// .version("v1.1")
/// .setting(AppSettings::VersionlessSubcommands)
/// .subcommand(SubCommand::with_name("test"))
/// .get_matches();
/// // running `myprog test --version` will display unknown argument error
/// ```
VersionlessSubcommands,
/// By default the auto-generated help message groups flags, options, and positional arguments
/// separately. This setting disable that and groups flags and options together presenting a
/// more unified help message (a la getopts or docopt style).
///
/// **NOTE:** This setting is cosmetic only and does not affect any functionality.
///
/// # Example
///
/// ```no_run
/// # use clap::{App, Arg, SubCommand, AppSettings};
/// App::new("myprog")
/// .setting(AppSettings::UnifiedHelpMessage)
/// .get_matches();
/// // running `myprog --help` will display a unified "docopt" or "getopts" style help message
/// ```
UnifiedHelpMessage,
/// Will display a message "Press [ENTER]/[RETURN] to continue..." and wait user before
/// exiting
///
/// This is most useful when writing an application which is run from a GUI shortcut, or on
/// Windows where a user tries to open the binary by double-clicking instead of using the
/// command line (i.e. set `.arg_required_else_help(true)` and `.wait_on_error(true)` to
/// display the help in such a case).
///
/// **NOTE:** This setting is **not** recursive with subcommands, meaning if you wish this
/// behavior for all subcommands, you must set this on each command (needing this is extremely
/// rare)
///
/// # Example
///
/// ```no_run
/// # use clap::{App, Arg, AppSettings};
/// App::new("myprog")
/// .setting(AppSettings::WaitOnError)
/// # ;
/// ```
WaitOnError,
/// Specifies that the help text sould be displayed (and then exit gracefully), if no
/// subcommands are present at runtime (i.e. an empty run such as, `$ myprog`.
///
/// **NOTE:** This should *not* be used with `.subcommand_required()` as they do the same
/// thing, except one prints the help text, and one prints an error.
///
/// **NOTE:** If the user specifies arguments at runtime, but no subcommand the help text will
/// still be displayed and exit. If this is *not* the desired result, consider using
/// `.arg_required_else_help()`
///
/// # Example
///
/// ```no_run
/// # use clap::{App, Arg, AppSettings};
/// App::new("myprog")
/// .setting(AppSettings::SubcommandRequiredElseHelp)
/// # ;
/// ```
SubcommandRequiredElseHelp,
}
impl FromStr for AppSettings {
type Err = String;
fn from_str(s: &str) -> Result<Self, <Self as FromStr>::Err> {
match &*s.to_ascii_lowercase() {
"subcommandsnegatereqs" => Ok(AppSettings::SubcommandsNegateReqs),
"subcommandsrequired" => Ok(AppSettings::SubcommandRequired),
"argrequiredelsehelp" => Ok(AppSettings::ArgRequiredElseHelp),
"globalversion" => Ok(AppSettings::GlobalVersion),
"versionlesssubcommands" => Ok(AppSettings::VersionlessSubcommands),
"unifiedhelpmessage" => Ok(AppSettings::UnifiedHelpMessage),
"waitonerror" => Ok(AppSettings::WaitOnError),
"subcommandrequiredelsehelp" => Ok(AppSettings::SubcommandRequiredElseHelp),
_ => Err("unknown AppSetting, cannot convert from str".to_owned())
}
}
}