Enum clap::builder::ArgAction

source · [−]

#[non_exhaustive]
pub enum ArgAction {
    Set,
    Append,
    StoreValue,
    IncOccurrence,
    SetTrue,
    SetFalse,
    Count,
    Help,
    Version,
}

Expand description

Behavior of arguments when they are encountered while parsing

Examples

let cmd = Command::new("mycmd")
    .arg(
        Arg::new("special-help")
            .short('?')
            .action(clap::ArgAction::Help)
    );

// Existing help still exists
let err = cmd.clone().try_get_matches_from(["mycmd", "-h"]).unwrap_err();
assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp);

// New help available
let err = cmd.try_get_matches_from(["mycmd", "-?"]).unwrap_err();
assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp);

Variants (Non-exhaustive)

This enum is marked as non-exhaustive

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

`Set`

When encountered, store the associated value(s) in ArgMatches

Examples

let cmd = Command::new("mycmd")
    .arg(
        Arg::new("flag")
            .long("flag")
            .action(clap::ArgAction::Set)
    );

let matches = cmd.try_get_matches_from(["mycmd", "--flag", "value"]).unwrap();
assert!(matches.contains_id("flag"));
assert_eq!(matches.occurrences_of("flag"), 0);
assert_eq!(
    matches.get_many::<String>("flag").unwrap_or_default().map(|v| v.as_str()).collect::<Vec<_>>(),
    vec!["value"]
);

`Append`

When encountered, store the associated value(s) in ArgMatches

Examples

let cmd = Command::new("mycmd")
    .arg(
        Arg::new("flag")
            .long("flag")
            .action(clap::ArgAction::Append)
    );

let matches = cmd.try_get_matches_from(["mycmd", "--flag", "value1", "--flag", "value2"]).unwrap();
assert!(matches.contains_id("flag"));
assert_eq!(matches.occurrences_of("flag"), 0);
assert_eq!(
    matches.get_many::<String>("flag").unwrap_or_default().map(|v| v.as_str()).collect::<Vec<_>>(),
    vec!["value1", "value2"]
);

`StoreValue`

Deprecated, replaced with ArgAction::Set or ArgAction::Append

Builder: Instead of arg.action(ArgAction::StoreValue),

Use arg.action(ArgAction::Set) for single-occurrence arguments
Use arg.action(ArgAction::Append) for multiple-occurrence arguments

Derive: opt-in to the new behavior with #[clap(action)]

`IncOccurrence`

Deprecated, replaced with ArgAction::SetTrue or ArgAction::Count

`SetTrue`

When encountered, act as if "true" was encountered on the command-line

If no default_value is set, it will be false.

No value is allowed. To optionally accept a value, see Arg::default_missing_value

Examples

let cmd = Command::new("mycmd")
    .arg(
        Arg::new("flag")
            .long("flag")
            .action(clap::ArgAction::SetTrue)
    );

let matches = cmd.clone().try_get_matches_from(["mycmd", "--flag", "--flag"]).unwrap();
assert!(matches.contains_id("flag"));
assert_eq!(matches.occurrences_of("flag"), 0);
assert_eq!(
    matches.get_one::<bool>("flag").copied(),
    Some(true)
);

let matches = cmd.try_get_matches_from(["mycmd"]).unwrap();
assert!(matches.contains_id("flag"));
assert_eq!(matches.occurrences_of("flag"), 0);
assert_eq!(
    matches.get_one::<bool>("flag").copied(),
    Some(false)
);

`SetFalse`

When encountered, act as if "false" was encountered on the command-line

If no default_value is set, it will be true.

No value is allowed. To optionally accept a value, see Arg::default_missing_value

Examples

let cmd = Command::new("mycmd")
    .arg(
        Arg::new("flag")
            .long("flag")
            .action(clap::ArgAction::SetFalse)
    );

let matches = cmd.clone().try_get_matches_from(["mycmd", "--flag", "--flag"]).unwrap();
assert!(matches.contains_id("flag"));
assert_eq!(matches.occurrences_of("flag"), 0);
assert_eq!(
    matches.get_one::<bool>("flag").copied(),
    Some(false)
);

let matches = cmd.try_get_matches_from(["mycmd"]).unwrap();
assert!(matches.contains_id("flag"));
assert_eq!(matches.occurrences_of("flag"), 0);
assert_eq!(
    matches.get_one::<bool>("flag").copied(),
    Some(true)
);

`Count`

When encountered, increment a u8 counter

If no default_value is set, it will be 0.

No value is allowed. To optionally accept a value, see Arg::default_missing_value

Examples

let cmd = Command::new("mycmd")
    .arg(
        Arg::new("flag")
            .long("flag")
            .action(clap::ArgAction::Count)
    );

let matches = cmd.clone().try_get_matches_from(["mycmd", "--flag", "--flag"]).unwrap();
assert!(matches.contains_id("flag"));
assert_eq!(matches.occurrences_of("flag"), 0);
assert_eq!(
    matches.get_count("flag"),
    2
);

let matches = cmd.try_get_matches_from(["mycmd"]).unwrap();
assert!(matches.contains_id("flag"));
assert_eq!(matches.occurrences_of("flag"), 0);
assert_eq!(
    matches.get_count("flag"),
    0
);

`Help`

When encountered, display Command::print_help

Depending on the flag, Command::print_long_help may be shown

Examples

let cmd = Command::new("mycmd")
    .arg(
        Arg::new("special-help")
            .short('?')
            .action(clap::ArgAction::Help)
    );

// Existing help still exists
let err = cmd.clone().try_get_matches_from(["mycmd", "-h"]).unwrap_err();
assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp);

// New help available
let err = cmd.try_get_matches_from(["mycmd", "-?"]).unwrap_err();
assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp);

`Version`

When encountered, display Command::version

Depending on the flag, Command::long_version may be shown

Examples

let cmd = Command::new("mycmd")
    .version("1.0.0")
    .arg(
        Arg::new("special-version")
            .long("special-version")
            .action(clap::ArgAction::Version)
    );

// Existing help still exists
let err = cmd.clone().try_get_matches_from(["mycmd", "--version"]).unwrap_err();
assert_eq!(err.kind(), clap::error::ErrorKind::DisplayVersion);

// New help available
let err = cmd.try_get_matches_from(["mycmd", "--special-version"]).unwrap_err();
assert_eq!(err.kind(), clap::error::ErrorKind::DisplayVersion);