# Enum clap::AppSettings [−] [src]

    pub enum AppSettings {
        SubcommandsNegateReqs,
        SubcommandRequired,
        ArgRequiredElseHelp,
        GlobalVersion,
        VersionlessSubcommands,
        UnifiedHelpMessage,
        WaitOnError,
        SubcommandRequiredElseHelp,
        Hidden,
        TrailingVarArg,
        NoBinaryName,
        AllowExternalSubcommands,
        StrictUtf8,
        AllowInvalidUtf8,
        AllowLeadingHyphen,
        HidePossibleValuesInHelp,
        NextLineHelp,
        DeriveDisplayOrder,
        ColoredHelp,
        // 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

`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 negative numbers `-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"));
`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. |
`NextLineHelp` | Places the help string for all arguments on the line after the argument NOTE: This setting is cosmetic only and does not affect any functionality. # Examples
    App::new("myprog")
        .setting(AppSettings::NextLineHelp)
        .get_matches();
`DeriveDisplayOrder` | Displays the arguments and subcommands in the help message in the order that they were declared in, vice alphabetically which is the default. # Examples
    App::new("myprog")
        .setting(AppSettings::DeriveDisplayOrder)
        .get_matches();
`ColoredHelp` | 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();

## Trait Implementations

### `impl FromStr for AppSettings`

#### `type Err = String`

#### `fn from_str(s: &str) -> Result<Self, Self::Err>`

### Derived Implementations

### `impl Clone for AppSettings`

#### `fn clone(&self) -> AppSettings`

#### `fn clone_from(&mut self, source: &Self)`1.0.0

### `impl Copy for AppSettings`

### `impl PartialEq for AppSettings`

#### `fn eq(&self, __arg_0: &AppSettings) -> bool`

#### `fn ne(&self, other: &Rhs) -> bool` 1.0.0

### `impl Debug for AppSettings`

#### `fn fmt(&self, __arg_0: &mut Formatter) -> Result`

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)