Enum clap::AppSettings [−] [src]

pub enum AppSettings {
    AllowInvalidUtf8,
    AllowLeadingHyphen,
    AllowNegativeNumbers,
    AllowMissingPositional,
    AllowExternalSubcommands,
    ArgsNegateSubcommands,
    ArgRequiredElseHelp,
    ColoredHelp,
    ColorAuto,
    ColorAlways,
    ColorNever,
    DontCollapseArgsInUsage,
    DontDelimitTrailingValues,
    DisableHelpSubcommand,
    DisableVersion,
    DeriveDisplayOrder,
    GlobalVersion,
    Hidden,
    HidePossibleValuesInHelp,
    InferSubcommands,
    NoBinaryName,
    NextLineHelp,
    PropagateGlobalValuesDown,
    SubcommandsNegateReqs,
    SubcommandRequiredElseHelp,
    StrictUtf8,
    SubcommandRequired,
    TrailingVarArg,
    UnifiedHelpMessage,
    VersionlessSubcommands,
    WaitOnError,
    // some variants omitted
}

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

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]);

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"));

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");

Allows one to implement 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:

This would otherwise not be allowed. This is useful when [optional] has a default value.

Note: In addition to using this setting, the second positional argument must be required

Examples

// 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![
        "myprog", "other"
    ]);

assert_eq!(m.value_of("arg1"), Some("something"));
assert_eq!(m.value_of("arg2"), Some("other"));

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"]);
    },
    _ => {},
}

Specifies that use of a valid argument negates [subcomands] 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:

Examples

App::new("myprog")
    .setting(AppSettings::ArgsNegateSubcommands)

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

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)

Uses colorized help messages.

NOTE: Must be compiled with the color cargo feature

Platform Specific

This setting only applies to Unix, Linux, and OSX (i.e. non-Windows platforms)

Examples

App::new("myprog")
    .setting(AppSettings::ColoredHelp)
    .get_matches();

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 OSX (i.e. non-Windows platforms).

Examples

App::new("myprog")
    .setting(AppSettings::ColorAuto)
    .get_matches();

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 OSX (i.e. non-Windows platforms).

Examples

App::new("myprog")
    .setting(AppSettings::ColorAlways)
    .get_matches();

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 OSX (i.e. non-Windows platforms)

Examples

App::new("myprog")
    .setting(AppSettings::ColorNever)
    .get_matches();

Disables the automatic collapsing of positional args into [ARGS] inside the usage string

Examples

App::new("myprog")
    .setting(AppSettings::DontCollapseArgsInUsage)
    .get_matches();

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();

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 automaticaly
    // 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);

Disables -V and --version [App] without affecting any of the SubCommands (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);

Displays the arguments and SubCommands 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();

Specifies to use the 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"

Specifies that this SubCommand should be hidden from help messages

Examples

App::new("myprog")
    .subcommand(SubCommand::with_name("test")
    .setting(AppSettings::Hidden))

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.

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 conjuction 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"));

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"]);

Places the help string for all arguments on the line after the argument.

Examples

App::new("myprog")
    .setting(AppSettings::NextLineHelp)
    .get_matches();

Specifies that the parser should propagate global arg's values down through any used child subcommands. Meaning, if a subcommand wasn't used, the values won't be propagated down to said subcommand.

NOTE: Values are only propagated down through futher child commands, not up

Examples

let m = App::new("myprog")
    .setting(AppSettings::PropagateGlobalValuesDown)
    .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")
    .setting(AppSettings::PropagateGlobalValuesDown)
    .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());

Allows SubCommands 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());

Specifies that the help text should be displayed (before exiting gracefully) if no SubCommands 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)

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 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::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);

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);

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"]);

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

Disables -V and --version for all SubCommands (Defaults to false; subcommands do 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);

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 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)

Trait Implementations

impl Debug for AppSettings
[src]

Formats the value using the given formatter.

impl PartialEq for AppSettings
[src]

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

impl Copy for AppSettings
[src]

impl Clone for AppSettings
[src]

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

impl FromStr for AppSettings
[src]

The associated error which can be returned from parsing.

Parses a string s to return a value of this type. Read more