[][src]Enum clap::AppSettings

[]
pub enum AppSettings {
    AllowInvalidUtf8,
    AllowLeadingHyphen,
    AllArgsOverrideSelf,
    AllowNegativeNumbers,
    AllowMissingPositional,
    AllowExternalSubcommands,
    ArgsNegateSubcommands,
    ArgRequiredElseHelp,
    SubcommandPrecedenceOverArg,
    ColoredHelp,
    ColorAuto,
    ColorAlways,
    ColorNever,
    DontCollapseArgsInUsage,
    DontDelimitTrailingValues,
    DisableHelpFlags,
    DisableHelpSubcommand,
    DisableVersion,
    DeriveDisplayOrder,
    GlobalVersion,
    Hidden,
    HidePossibleValuesInHelp,
    HelpRequired,
    InferSubcommands,
    NoBinaryName,
    NextLineHelp,
    SubcommandsNegateReqs,
    SubcommandRequiredElseHelp,
    StrictUtf8,
    SubcommandRequired,
    TrailingVarArg,
    UnifiedHelpMessage,
    VersionlessSubcommands,
    WaitOnError,
    NoAutoHelp,
    NoAutoVersion,
    // 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

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 ``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("<arg> 'some positional arg'")
   .try_get_matches_from(
       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 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::new("neg").index(1))
    .get_matches_from(vec![
        "nums", "-20"
    ]);

assert_eq!(m.value_of("neg"), Some("-20"));
AllArgsOverrideSelf
[]

Specifies that all arguments override themselves. This is the equivolent to saying the foo arg using [Arg::overrides_with("foo")] for all defined arguments. [Arg::overrides_with("foo")]: ./struct.Arg.html#method.overrides_with

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::new("num"))
    .try_get_matches_from(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:

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 posisble:

Examples

Style number one from above:

// Assume there is an external subcommand named "subcmd"
let m = App::new("myprog")
    .setting(AppSettings::AllowMissingPositional)
    .arg(Arg::new("arg1"))
    .arg(Arg::new("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::new("arg1")
        .default_value("something"))
    .arg(Arg::new("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::new("foo"))
    .arg(Arg::new("bar"))
    .arg(Arg::new("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 nofice 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::new("foo"))
    .arg(Arg::new("bar"))
    .arg(Arg::new("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 `` 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() {
    Some((external, 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 [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)
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: ``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)
SubcommandPrecedenceOverArg
[]

Instructs the parser to stop when encountering a subcommand instead of greedily consuming args.

By default, if an option taking multiple values is followed by a subcommand, the subcommand will be parsed as another value.

app --foo val1 val2 subcommand
          --------- ----------
            values   another value

This setting instructs the parser to stop when encountering a subcommand instead of greedily consuming arguments.

app --foo val1 val2 subcommand
          --------- ----------
            values   subcommand

Note: Make sure you apply it as global_setting if you want it to be propagated to sub-sub commands!

Examples

let app = App::new("app").subcommand(App::new("sub")).arg(
    Arg::new("arg")
        .long("arg")
        .multiple(true)
        .takes_value(true),
);

let matches = app
    .clone()
    .try_get_matches_from(&["app", "--arg", "1", "2", "3", "sub"])
    .unwrap();
assert_eq!(
    matches.values_of("arg").unwrap().collect::<Vec<_>>(),
    &["1", "2", "3", "sub"]
);
assert!(matches.subcommand_matches("sub").is_none());

let app = app.setting(AppSettings::SubcommandPrecedenceOverArg);
let matches = app
    .try_get_matches_from(&["app", "--arg", "1", "2", "3", "sub"])
    .unwrap();
assert_eq!(
    matches.values_of("arg").unwrap().collect::<Vec<_>>(),
    &["1", "2", "3"]
);
assert!(matches.subcommand_matches("sub").is_some());
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();
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 OSX (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 OSX (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 OSX (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 SubCommands (Defaults to false; application does have help flags)

Examples

let res = App::new("myprog")
    .setting(AppSettings::DisableHelpFlags)
    .try_get_matches_from(vec![
        "myprog", "-h"
    ]);
assert!(res.is_err());
assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
let res = App::new("myprog")
    .setting(AppSettings::DisableHelpFlags)
    .subcommand(App::new("test"))
    .try_get_matches_from(vec![
        "myprog", "test", "-h"
    ]);
assert!(res.is_err());
assert_eq!(res.unwrap_err().kind, ErrorKind::DisplayHelp);
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(App::new("test"))
    .try_get_matches_from(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 ``s (Defaults to false; application does have a version flag)

Examples

let res = App::new("myprog")
    .version("v1.1")
    .setting(AppSettings::DisableVersion)
    .try_get_matches_from(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(App::new("test"))
    .try_get_matches_from(vec![
        "myprog", "test", "-V"
    ]);
assert!(res.is_err());
assert_eq!(res.unwrap_err().kind, ErrorKind::DisplayVersion);
DeriveDisplayOrder
[]

Displays the arguments and ``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 ``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(App::new("test"))
    .get_matches();
// running `$ myprog test --version` will display
// "myprog-test v1.1"
Hidden
[]

Specifies that this `` should be hidden from help messages

Examples

App::new("myprog")
    .subcommand(App::new("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.

HelpRequired
[]

Tells clap to panic if help strings are omitted

Examples

App::new("myprog")
    .setting(AppSettings::HelpRequired)
    .arg(
        Arg::new("foo").about("It does foo stuff")
        // As required via AppSettings::HelpRequired, a help message was supplied
     )

Panics

App::new("myapp")
    .setting(AppSettings::HelpRequired)
    .arg(
        Arg::new("foo")
        // Someone forgot to put .about("...") here
        // Since the setting AppSettings::HelpRequired is activated, this will lead to
        // a panic (if you are in debug mode)
    )
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 AppSettings::ArgsNegateSubcommands in conjunction with this setting.

Examples

let m = App::new("prog")
    .setting(AppSettings::InferSubcommands)
    .subcommand(App::new("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("<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();
SubcommandsNegateReqs
[]

Allows ``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::new("opt").required(true))
    .subcommand(App::new("test"))
    .try_get_matches_from(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::new("opt").required(true))
    .subcommand(App::new("test"))
    .try_get_matches_from(vec![
        "myprog", "test"
    ]);
assert!(noerr.is_ok());
SubcommandRequiredElseHelp
[]

Specifies that the help text should be displayed (before exiting gracefully) if no ``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 ``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("<arg> 'some positional arg'")
   .try_get_matches_from(
       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 `` 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(App::new("test"))
    .try_get_matches_from(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("<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 ``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(App::new("test"))
    .try_get_matches_from(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 ``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)
NoAutoHelp
[]

@TODO-v3: @docs write them...maybe rename

NoAutoVersion
[]

@TODO-v3: @docs write them...maybe rename

Trait Implementations

impl Clone for AppSettings[src][+]

impl Copy for AppSettings[src]

impl Debug for AppSettings[src][+]

impl FromStr for AppSettings[src][+]

type Err = String

The associated error which can be returned from parsing.

impl PartialEq<AppSettings> for AppSettings[src][+]

impl StructuralPartialEq for AppSettings[src]

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

impl<T> Any for T where
    T: 'static + ?Sized
[src][+]

impl<T> Borrow<T> for T where
    T: ?Sized
[src][+]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src][+]

impl<T> From<T> for T[src][+]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src][+]

impl<T> ToOwned for T where
    T: Clone
[src][+]

type Owned = T

The resulting type after obtaining ownership.

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src][+]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src][+]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.