Enum clap::AppSettings [−] [src]

pub enum AppSettings {
    SubcommandsNegateReqs,
    SubcommandRequired,
    ArgRequiredElseHelp,
    GlobalVersion,
    VersionlessSubcommands,
    UnifiedHelpMessage,
    WaitOnError,
    SubcommandRequiredElseHelp,
    Hidden,
    TrailingVarArg,
    NoBinaryName,
    // some variants omitted
}

Application level settings, which affect how App operates

Variants

SubcommandsNegateReqs

Allows subcommands to override all requirements of the parent (this command). For example if you had a subcommand or even top level application which had a required arguments that are only required as long as there is no subcommand present.

NOTE: This defaults to false (using subcommand does not negate requirements)

Examples

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

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

Uses version of the current command for all subcommands. (Defaults to false; subcommands have independant version strings)

NOTE: The version for the current command and this setting must be set prior to adding any 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

NOTE: Do not set this value to false, it will have undesired results!

Examples

App::new("myprog")
    .version("v1.1")
    .setting(AppSettings::VersionlessSubcommands)
    .subcommand(SubCommand::with_name("test"))
    .get_matches();
// running `myprog test --version` will display unknown argument error
UnifiedHelpMessage

By default the auto-generated help message groups flags, options, and positional arguments separately. This setting disable that and groups flags and options together presenting a more unified help message (a la getopts or docopt style).

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 (i.e. set .arg_required_else_help(true) and .wait_on_error(true) to display the help in such a case).

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 one prints the help text, and one 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 .arg_required_else_help()

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 usage token equivalent.

Examples

let m = App::new("myprog")
    .setting(AppSettings::TrailingVarArg)
    .arg(Arg::from_usage("<cmd>... 'commands to run'"))
    .get_matches_from(vec!["myprog", "some_command", "-r", "set"]);

assert_eq!(m.values_of("cmd").unwrap(), &["some_command", "-r", "set"]);
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.

NOTE: This should only be used when you absolutely know it's what you need. 99% of the cases out there don't need this setting.

Examples

let m = App::new("myprog")
    .setting(AppSettings::NoBinaryName)
    .arg(Arg::from_usage("<cmd>... 'commands to run'"))
    .get_matches_from(vec!["some_command", "-r", "set"]);

assert_eq!(m.values_of("cmd").unwrap(), &["some_command", "-r", "set"]);

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)

impl Copy for AppSettings

impl PartialEq for AppSettings

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

fn ne(&self, __arg_0: &AppSettings) -> bool

impl Debug for AppSettings

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