Enum clap::AppSettings [−][src]
pub enum AppSettings {
Show 33 variants
AllowInvalidUtf8,
AllArgsOverrideSelf,
AllowLeadingHyphen,
AllowNegativeNumbers,
AllowMissingPositional,
AllowExternalSubcommands,
ArgsNegateSubcommands,
ArgRequiredElseHelp,
ColoredHelp,
ColorAuto,
ColorAlways,
ColorNever,
DontCollapseArgsInUsage,
DontDelimitTrailingValues,
DisableHelpFlags,
DisableHelpSubcommand,
DisableVersion,
DeriveDisplayOrder,
GlobalVersion,
Hidden,
HidePossibleValuesInHelp,
InferSubcommands,
NoBinaryName,
NextLineHelp,
PropagateGlobalValuesDown,
SubcommandsNegateReqs,
SubcommandRequiredElseHelp,
StrictUtf8,
SubcommandRequired,
TrailingVarArg,
UnifiedHelpMessage,
VersionlessSubcommands,
WaitOnError,
// some variants omitted
}
Expand description
Application level settings, which affect how App
operates
NOTE: When these settings are used, they apply only to current command, and are not propagated down or up through child or parent subcommands
Variants
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
ArgMatches::os_value_of
, ArgMatches::os_values_of
, ArgMatches::lossy_value_of
,
or ArgMatches::lossy_values_of
for those particular arguments which may contain invalid
UTF-8 values
NOTE: This rule only applies to argument values, as flags, options, and
SubCommand
s 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,OsStringExt};
let r = App::new("myprog")
//.setting(AppSettings::AllowInvalidUtf8)
.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]);
AllArgsOverrideSelf
Essentially sets [Arg::overrides_with("itself")
] for all arguments.
WARNING: Positional arguments cannot override themselves (or we would never be able
to advance to the next positional). This setting ignores positional arguments.
[Arg::overrides_with("itself")
]: ./struct.Arg.html#method.overrides_with
AllowLeadingHyphen
Specifies that leading hyphens are allowed in argument values, such as negative numbers
like -10
. (which would otherwise be parsed as another flag or option)
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). It is preferred to set this on a per argument basis, via Arg::allow_hyphen_values
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"));
AllowNegativeNumbers
Allows negative numbers to pass as values. This is similar to
AllowLeadingHyphen
except that it only allows numbers, all
other undefined leading hyphens will fail to parse.
Examples
let res = App::new("myprog")
.version("v1.1")
.setting(AppSettings::AllowNegativeNumbers)
.arg(Arg::with_name("num"))
.get_matches_from_safe(vec![
"myprog", "-20"
]);
assert!(res.is_ok());
let m = res.unwrap();
assert_eq!(m.value_of("num").unwrap(), "-20");
AllowMissingPositional
Allows one to implement two styles of CLIs where positionals can be used out of order.
The first example is a CLI where the second to last positional argument is optional, but
the final positional argument is required. Such as $ prog [optional] <required>
where one
of the two following usages is allowed:
$ prog [optional] <required>
$ prog <required>
This would otherwise not be allowed. This is useful when [optional]
has a default value.
Note: when using this style of “missing positionals” the final positional must be
required if --
will not be used to skip to the final positional argument.
Note: This style also only allows a single positional argument to be “skipped” without
the use of --
. To skip more than one, see the second example.
The second example is when one wants to skip multiple optional positional arguments, and use
of the --
operator is OK (but not required if all arguments will be specified anyways).
For example, imagine a CLI which has three positional arguments [foo] [bar] [baz]...
where
baz
accepts multiple values (similar to man ARGS...
style training arguments).
With this setting the following invocations are possible:
$ prog foo bar baz1 baz2 baz3
$ prog foo -- baz1 baz2 baz3
$ prog -- baz1 baz2 baz3
Examples
Style number one from above:
// Assume there is an external subcommand named "subcmd"
let m = App::new("myprog")
.setting(AppSettings::AllowMissingPositional)
.arg(Arg::with_name("arg1"))
.arg(Arg::with_name("arg2")
.required(true))
.get_matches_from(vec![
"prog", "other"
]);
assert_eq!(m.value_of("arg1"), None);
assert_eq!(m.value_of("arg2"), Some("other"));
Now the same example, but using a default value for the first optional positional argument
// Assume there is an external subcommand named "subcmd"
let m = App::new("myprog")
.setting(AppSettings::AllowMissingPositional)
.arg(Arg::with_name("arg1")
.default_value("something"))
.arg(Arg::with_name("arg2")
.required(true))
.get_matches_from(vec![
"prog", "other"
]);
assert_eq!(m.value_of("arg1"), Some("something"));
assert_eq!(m.value_of("arg2"), Some("other"));
Style number two from above:
// Assume there is an external subcommand named "subcmd"
let m = App::new("myprog")
.setting(AppSettings::AllowMissingPositional)
.arg(Arg::with_name("foo"))
.arg(Arg::with_name("bar"))
.arg(Arg::with_name("baz").multiple(true))
.get_matches_from(vec![
"prog", "foo", "bar", "baz1", "baz2", "baz3"
]);
assert_eq!(m.value_of("foo"), Some("foo"));
assert_eq!(m.value_of("bar"), Some("bar"));
assert_eq!(m.values_of("baz").unwrap().collect::<Vec<_>>(), &["baz1", "baz2", "baz3"]);
Now notice if we don’t specify foo
or baz
but use the --
operator.
// Assume there is an external subcommand named "subcmd"
let m = App::new("myprog")
.setting(AppSettings::AllowMissingPositional)
.arg(Arg::with_name("foo"))
.arg(Arg::with_name("bar"))
.arg(Arg::with_name("baz").multiple(true))
.get_matches_from(vec![
"prog", "--", "baz1", "baz2", "baz3"
]);
assert_eq!(m.value_of("foo"), None);
assert_eq!(m.value_of("bar"), None);
assert_eq!(m.values_of("baz").unwrap().collect::<Vec<_>>(), &["baz1", "baz2", "baz3"]);
AllowExternalSubcommands
Specifies that an unexpected positional argument,
which would otherwise cause a ErrorKind::UnknownArgument
error,
should instead be treated as a SubCommand
within 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 treated as a potential subcommand. One should check for such cases manually and inform the user appropriately.
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 an empty
// string argument name
match m.subcommand() {
(external, Some(ext_m)) => {
let ext_args: Vec<&str> = ext_m.values_of("").unwrap().collect();
assert_eq!(external, "subcmd");
assert_eq!(ext_args, ["--option", "value", "-fff", "--flag"]);
},
_ => {},
}
ArgsNegateSubcommands
Specifies that use of a valid argument negates subcommands being used after. By default
clap
allows arguments between subcommands such as
<cmd> [cmd_args] <cmd2> [cmd2_args] <cmd3> [cmd3_args]
. This setting disables that
functionality and says that arguments can only follow the final subcommand. For instance
using this setting makes only the following invocations possible:
<cmd> <cmd2> <cmd3> [cmd3_args]
<cmd> <cmd2> [cmd2_args]
<cmd> [cmd_args]
Examples
App::new("myprog")
.setting(AppSettings::ArgsNegateSubcommands)
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: SubCommand
s count as arguments
NOTE: Setting Arg::default_value
effectively disables this option as it will
ensure that some argument is always present.
Examples
App::new("myprog")
.setting(AppSettings::ArgRequiredElseHelp)
ColoredHelp
Uses colorized help messages.
NOTE: Must be compiled with the color
cargo feature
Platform Specific
This setting only applies to Unix, Linux, and macOS (i.e. non-Windows platforms)
Examples
App::new("myprog")
.setting(AppSettings::ColoredHelp)
.get_matches();
ColorAuto
Enables colored output only when the output is going to a terminal or TTY.
NOTE: This is the default behavior of clap
.
NOTE: Must be compiled with the color
cargo feature.
Platform Specific
This setting only applies to Unix, Linux, and macOS (i.e. non-Windows platforms).
Examples
App::new("myprog")
.setting(AppSettings::ColorAuto)
.get_matches();
ColorAlways
Enables colored output regardless of whether or not the output is going to a terminal/TTY.
NOTE: Must be compiled with the color
cargo feature.
Platform Specific
This setting only applies to Unix, Linux, and macOS (i.e. non-Windows platforms).
Examples
App::new("myprog")
.setting(AppSettings::ColorAlways)
.get_matches();
ColorNever
Disables colored output no matter if the output is going to a terminal/TTY, or not.
NOTE: Must be compiled with the color
cargo feature
Platform Specific
This setting only applies to Unix, Linux, and macOS (i.e. non-Windows platforms)
Examples
App::new("myprog")
.setting(AppSettings::ColorNever)
.get_matches();
DontCollapseArgsInUsage
Disables the automatic collapsing of positional args into [ARGS]
inside the usage string
Examples
App::new("myprog")
.setting(AppSettings::DontCollapseArgsInUsage)
.get_matches();
DontDelimitTrailingValues
Disables the automatic delimiting of values when --
or AppSettings::TrailingVarArg
was used.
NOTE: The same thing can be done manually by setting the final positional argument to
Arg::use_delimiter(false)
. Using this setting is safer, because it’s easier to locate
when making changes.
Examples
App::new("myprog")
.setting(AppSettings::DontDelimitTrailingValues)
.get_matches();
DisableHelpFlags
Disables -h
and --help
App
without affecting any of the SubCommand
s
(Defaults to false
; application does have help flags)
Examples
let res = App::new("myprog")
.setting(AppSettings::DisableHelpFlags)
.get_matches_from_safe(vec![
"myprog", "-h"
]);
assert!(res.is_err());
assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
let res = App::new("myprog")
.setting(AppSettings::DisableHelpFlags)
.subcommand(SubCommand::with_name("test"))
.get_matches_from_safe(vec![
"myprog", "test", "-h"
]);
assert!(res.is_err());
assert_eq!(res.unwrap_err().kind, ErrorKind::HelpDisplayed);
DisableHelpSubcommand
Disables the help
subcommand
Examples
let res = App::new("myprog")
.version("v1.1")
.setting(AppSettings::DisableHelpSubcommand)
// Normally, creating a subcommand causes a `help` subcommand to automatically
// be generated as well
.subcommand(SubCommand::with_name("test"))
.get_matches_from_safe(vec![
"myprog", "help"
]);
assert!(res.is_err());
assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
DisableVersion
Disables -V
and --version
App
without affecting any of the SubCommand
s
(Defaults to false
; application does have a version flag)
Examples
let res = App::new("myprog")
.version("v1.1")
.setting(AppSettings::DisableVersion)
.get_matches_from_safe(vec![
"myprog", "-V"
]);
assert!(res.is_err());
assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
let res = App::new("myprog")
.version("v1.1")
.setting(AppSettings::DisableVersion)
.subcommand(SubCommand::with_name("test"))
.get_matches_from_safe(vec![
"myprog", "test", "-V"
]);
assert!(res.is_err());
assert_eq!(res.unwrap_err().kind, ErrorKind::VersionDisplayed);
DeriveDisplayOrder
Displays the arguments and SubCommand
s in the help message in the order that they were
declared in, and not alphabetically which is the default.
Examples
App::new("myprog")
.setting(AppSettings::DeriveDisplayOrder)
.get_matches();
GlobalVersion
Specifies to use the version of the current command for all child SubCommand
s.
(Defaults to false
; subcommands have independent 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"
Hidden
Specifies that this SubCommand
should be hidden from help messages
Examples
App::new("myprog")
.subcommand(SubCommand::with_name("test")
.setting(AppSettings::Hidden))
HidePossibleValuesInHelp
Tells clap
not to print possible values when displaying help information.
This can be useful if there are many values, or they are explained elsewhere.
InferSubcommands
Tries to match unknown args to partial subcommands
or their aliases. For example to
match a subcommand named test
, one could use t
, te
, tes
, and test
.
NOTE: The match must not be ambiguous at all in order to succeed. i.e. to match te
to test
there could not also be a subcommand or alias temp
because both start with te
CAUTION: This setting can interfere with positional/free arguments, take care when
designing CLIs which allow inferred subcommands and have potential positional/free
arguments whose values could start with the same characters as subcommands. If this is the
case, it’s recommended to use settings such as AppSeettings::ArgsNegateSubcommands
in
conjunction with this setting.
Examples
let m = App::new("prog")
.setting(AppSettings::InferSubcommands)
.subcommand(SubCommand::with_name("test"))
.get_matches_from(vec![
"prog", "te"
]);
assert_eq!(m.subcommand_name(), Some("test"));
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"]);
NextLineHelp
Places the help string for all arguments on the line after the argument.
Examples
App::new("myprog")
.setting(AppSettings::NextLineHelp)
.get_matches();
PropagateGlobalValuesDown
No longer required to propagate values
DEPRECATED: This setting is no longer required in order to propagate values up or down
Specifies that the parser should propagate global arg’s values down or up through any used child subcommands. Meaning, if a subcommand wasn’t used, the values won’t be propagated to said subcommand.
Examples
let m = App::new("myprog")
.arg(Arg::from_usage("[cmd] 'command to run'")
.global(true))
.subcommand(SubCommand::with_name("foo"))
.get_matches_from(vec!["myprog", "set", "foo"]);
assert_eq!(m.value_of("cmd"), Some("set"));
let sub_m = m.subcommand_matches("foo").unwrap();
assert_eq!(sub_m.value_of("cmd"), Some("set"));
Now doing the same thing, but not using any subcommands will result in the value not being propagated down.
let m = App::new("myprog")
.arg(Arg::from_usage("[cmd] 'command to run'")
.global(true))
.subcommand(SubCommand::with_name("foo"))
.get_matches_from(vec!["myprog", "set"]);
assert_eq!(m.value_of("cmd"), Some("set"));
assert!(m.subcommand_matches("foo").is_none());
SubcommandsNegateReqs
Allows SubCommand
s to override all requirements of the parent command.
For example if you had a subcommand or top level application with a required argument
that is only required as long as there is no subcommand present,
using this setting would allow you to set those arguments to Arg::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());
SubcommandRequiredElseHelp
Specifies that the help text should be displayed (before exiting gracefully) if no
SubCommand
s are present at runtime (i.e. an empty run such as $ myprog
).
NOTE: This should not be used with AppSettings::SubcommandRequired
as they do
nearly same thing; 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
AppSettings::ArgRequiredElseHelp
instead.
Examples
App::new("myprog")
.setting(AppSettings::SubcommandRequiredElseHelp)
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; Things such as flags, options, and
SubCommand
s themselves only allow valid UTF-8 code points.
Platform Specific
Non Windows systems only
Examples
use std::ffi::OsString;
use std::os::unix::ffi::OsStringExt;
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);
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);
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 Arg::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"]);
UnifiedHelpMessage
Groups flags and options together, presenting a more unified help message
(a la getopts
or docopt
style).
The default is that the auto-generated help message will group flags, and 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
VersionlessSubcommands
Disables -V
and --version
for all SubCommand
s
(Defaults to false
; subcommands do have version flags.)
NOTE: This setting must be set prior to 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);
WaitOnError
Will display a message “Press [ENTER]/[RETURN] to continue…” and wait for 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 SubCommand
s, 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)
Trait Implementations
Auto Trait Implementations
impl RefUnwindSafe for AppSettings
impl Send for AppSettings
impl Sync for AppSettings
impl Unpin for AppSettings
impl UnwindSafe for AppSettings
Blanket Implementations
Mutably borrows from an owned value. Read more