Enum clap::AppSettings
[−]
[src]
pub enum AppSettings { SubcommandsNegateReqs, SubcommandRequired, ArgRequiredElseHelp, GlobalVersion, VersionlessSubcommands, UnifiedHelpMessage, WaitOnError, SubcommandRequiredElseHelp, Hidden, TrailingVarArg, NoBinaryName, AllowExternalSubcommands, StrictUtf8, AllowInvalidUtf8, AllowLeadingHyphen, // some variants omitted }
Application level settings, which affect how App
operates
Variants
SubcommandsNegateReqs
Allows subcommands to override all requirements of the parent command. For example
if you had a subcommand or top level application which had a required argument that
are only required as long as there is no subcommand present, using this setting would allow
you set those arguments to required(true)
and yet receive no error so long as the user
uses a valid subcommand instead.
NOTE: This defaults to false (using subcommand does not negate requirements)
Examples
This first example shows that it is an error to not use a required argument
let err = App::new("myprog") .setting(AppSettings::SubcommandsNegateReqs) .arg(Arg::with_name("opt").required(true)) .subcommand(SubCommand::with_name("test")) .get_matches_from_safe(vec![ "myprog" ]); assert!(err.is_err()); assert_eq!(err.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
This next example shows that it is no longer error to not use a required argument if a valid subcommand is used.
let noerr = App::new("myprog") .setting(AppSettings::SubcommandsNegateReqs) .arg(Arg::with_name("opt").required(true)) .subcommand(SubCommand::with_name("test")) .get_matches_from_safe(vec![ "myprog", "test" ]); assert!(noerr.is_ok());
SubcommandRequired
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)
Examples
let err = App::new("myprog") .setting(AppSettings::SubcommandRequired) .subcommand(SubCommand::with_name("test")) .get_matches_from_safe(vec![ "myprog", ]); assert!(err.is_err()); assert_eq!(err.unwrap_err().kind, ErrorKind::MissingSubcommand);
ArgRequiredElseHelp
Specifies that the help text should 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
Examples
App::new("myprog") .setting(AppSettings::ArgRequiredElseHelp)
GlobalVersion
Specifies to version of the current command for all child subcommands. (Defaults to false; subcommands have independant version strings from their parents)
NOTE: The version for the current command and this setting must be set prior to adding any child subcommands
Examples
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"
VersionlessSubcommands
Disables -V
and --version
for all subcommands (Defaults to false; subcommands have
version flags)
NOTE: This setting must be set prior adding any subcommands
Examples
let res = App::new("myprog") .version("v1.1") .setting(AppSettings::VersionlessSubcommands) .subcommand(SubCommand::with_name("test")) .get_matches_from_safe(vec![ "myprog", "test", "-V" ]); assert!(res.is_err()); assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
UnifiedHelpMessage
Groups flags and options together presenting a more unified help message (a la getopts
or
docopt
style). The default is the auto-generated help message groups flags, options
separately.
NOTE: This setting is cosmetic only and does not affect any functionality.
Examples
App::new("myprog") .setting(AppSettings::UnifiedHelpMessage) .get_matches(); // running `myprog --help` will display a unified "docopt" or "getopts" style help message
WaitOnError
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.
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)
Examples
App::new("myprog") .setting(AppSettings::WaitOnError)
SubcommandRequiredElseHelp
Specifies that the help text should 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 this prints the help text, and the other 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
ArgRequiredElseHelp
instead.
Examples
App::new("myprog") .setting(AppSettings::SubcommandRequiredElseHelp)
Hidden
Specifies that this subcommand should be hidden from help messages
Examples
App::new("myprog") .subcommand(SubCommand::with_name("test") .setting(AppSettings::Hidden))
TrailingVarArg
Specifies that the final positional argument is a "VarArg" and that clap
should not
attempt to parse any further args.
The values of the trailing positional argument will contain all args from itself on.
NOTE: The final positional argument must have .multiple(true)
or the usage string
equivalent.
Examples
let m = App::new("myprog") .setting(AppSettings::TrailingVarArg) .arg(Arg::from_usage("<cmd>... 'commands to run'")) .get_matches_from(vec!["myprog", "arg1", "-r", "val1"]); let trail: Vec<&str> = m.values_of("cmd").unwrap().collect(); assert_eq!(trail, ["arg1", "-r", "val1"]);
NoBinaryName
Specifies that the parser should not assume the first argument passed is the binary name. This is normally the case when using a "daemon" style mode, or an interactive CLI where one one would not normally type the binary or program name for each command.
Examples
let m = App::new("myprog") .setting(AppSettings::NoBinaryName) .arg(Arg::from_usage("<cmd>... 'commands to run'")) .get_matches_from(vec!["command", "set"]); let cmds: Vec<&str> = m.values_of("cmd").unwrap().collect(); assert_eq!(cmds, ["command", "set"]);
AllowExternalSubcommands
Specifies that an unexpected argument positional arguments which would otherwise cause a
ErrorKind::UnknownArgument
error, should instead be treated as a subcommand in the
ArgMatches
struct.
NOTE: Use this setting with caution, as a truly unexpected argument (i.e. one that is NOT an external subcommand) will not cause an error and instead be treatd as a potential subcommand. You shoud inform the user appropriatly.
Examples
// Assume there is an external subcommand named "subcmd" let m = App::new("myprog") .setting(AppSettings::AllowExternalSubcommands) .get_matches_from(vec![ "myprog", "subcmd", "--option", "value", "-fff", "--flag" ]); // All trailing arguments will be stored under the subcommand's sub-matches using a value // of the runtime subcommand name (in this case "subcmd") match m.subcommand() { (external, Some(ext_m)) => { let ext_args: Vec<&str> = ext_m.values_of(external).unwrap().collect(); assert_eq!(ext_args, ["--option", "value", "-fff", "--flag"]); }, _ => {}, }
StrictUtf8
Specifies that any invalid UTF-8 code points should be treated as an error and fail
with a ErrorKind::InvalidUtf8
error.
NOTE: This rule only applies to argument values, as flags, options, and subcommands themselves only allow valid UTF-8 code points.
Platform Specific
Non Windows systems only
Examples
use std::ffi::OsString; let m = App::new("myprog") .setting(AppSettings::StrictUtf8) .arg_from_usage("<arg> 'some positional arg'") .get_matches_from_safe( vec![ OsString::from("myprog"), OsString::from_vec(vec![0xe9])]); assert!(m.is_err()); assert_eq!(m.unwrap_err().kind, ErrorKind::InvalidUtf8); }
AllowInvalidUtf8
Specifies that any invalid UTF-8 code points should not be treated as an error. This is
the default behavior of clap
NOTE: Using argument values with invalid UTF-8 code points requires using Either
ArgMatches::os_value(s)_of
or ArgMatches::lossy_value(s)_of
for those particular
arguments which may contain invalid UTF-8 values
NOTE: This rule only applies to argument values, as flags, options, and subcommands themselves only allow valid UTF-8 code points.
Platform Specific
Non Windows systems only
Examples
use std::ffi::OsString; use std::os::unix::ffi::OsStrExt; let r = App::new("myprog") .setting(AppSettings::StrictUtf8) .arg_from_usage("<arg> 'some positional arg'") .get_matches_from_safe( vec![ OsString::from("myprog"), OsString::from_vec(vec![0xe9])]); assert!(r.is_ok()); let m = r.unwrap(); assert_eq!(m.value_of_os("arg").unwrap().as_bytes(), &[0xe9]);
AllowLeadingHyphen
Specifies that leading hyphens are allowed in argument values, such as -10
NOTE: This can only be set application wide and not on a per argument basis.
NOTE: Use this setting with caution as it silences certain circumstances which would otherwise be an error (such as accidentally forgetting to specify a value for leading option)
Examples
// Imagine you needed to represent negative numbers as well, such as -10 let m = App::new("nums") .setting(AppSettings::AllowLeadingHyphen) .arg(Arg::with_name("neg").index(1)) .get_matches_from(vec![ "nums", "-20" ]); assert_eq!(m.value_of("neg"), Some("-20"));
Trait Implementations
impl Clone for AppSettings
[src]
fn clone(&self) -> AppSettings
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0
Performs copy-assignment from source
. Read more
impl Copy for AppSettings
[src]
impl PartialEq for AppSettings
[src]
fn eq(&self, __arg_0: &AppSettings) -> bool
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, other: &Rhs) -> bool
1.0.0
This method tests for !=
.