Macro `arg`

macro_rules! arg {
    ( $name:ident: $($tail:tt)+ ) => { ... };
    ( $($tail:tt)+ ) => { ... };
}

Create an Arg from a usage string.

Allows creation of basic settings for the Arg.

NOTE: Not all settings may be set using the usage string method. Some properties are only available via the builder pattern.

Syntax

Usage strings typically following the form:

[explicit name] [short] [long] [value names] [...] [help string]

Explicit Name

The name may be either a bare-word or a string, followed by a :, like name: or "name":.

Note: This is an optional field, if it's omitted the argument will use one of the additional fields as the name using the following priority order:

Explicit Name
Long
Value Name

See [Arg::id][crate::Arg::id].

Short

A short flag is a - followed by either a bare-character or quoted character, like -f or -'f'.

See [Arg::short][crate::Arg::short].

Long

A long flag is a -- followed by either a bare-word or a string, like --foo or --"foo".

NOTE: Dashes in the long name (e.g. --foo-bar) is not supported and quoting is required (e.g. --"foo-bar").

See [Arg::long][crate::Arg::long].

Values (Value Notation)

This is set by placing bare-word between:

[] like [FOO]
- Positional argument: optional
- Named argument: optional value
<> like <FOO>: required

See [Arg::value_name][crate::Arg::value_name].

`...`

... (three consecutive dots/periods) specifies that this argument may occur multiple times (not to be confused with multiple values per occurrence).

See [ArgAction::Count][crate::ArgAction::Count] and [ArgAction::Append][crate::ArgAction::Append].

Help String

The help string is denoted between a pair of double quotes "" and may contain any characters.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, arg};
let cmd = Command::new("prog")
    .args(&[
        arg!(--config <FILE> "a required file for the configuration and no short"),
        arg!(-d --debug ... "turns on debugging information and allows multiples"),
        arg!([input] "an optional input file to use")
    ]);

let m = cmd.try_get_matches_from(["prog", "--config", "file.toml"]).unwrap();
assert_eq!(m.get_one::<String>("config").unwrap(), "file.toml");
assert_eq!(*m.get_one::<u8>("debug").unwrap(), 0);
assert_eq!(m.get_one::<String>("input"), None);