Struct clap::Arg
[−]
[src]
pub struct Arg<'a, 'b> where 'a: 'b {
// some fields omitted
}
The abstract representation of a command line argument. Used to set all the options and relationships that define a valid argument for the program.
There are two methods for constructing Arg
s, using the builder pattern and setting options
manually, or using a usage string which is far less verbose but has fewer options. You can also
use a combination of the two methods to achieve the best of both worlds.
Examples
// Using the traditional builder pattern and setting each option manually let cfg = Arg::with_name("config") .short("c") .long("config") .takes_value(true) .value_name("FILE") .help("Provides a config file to myprog"); // Using a usage string (setting a similar argument to the one above) let input = Arg::from_usage("-i, --input=[FILE] 'Provides an input file to the program'");
Methods
impl<'a, 'b> Arg<'a, 'b>
[src]
fn with_name(n: &'a str) -> Self
Creates a new instance of Arg
using a unique string name. The name will be used to get
information about whether or not the argument was used at runtime, get values, set
relationships with other args, etc..
NOTE: In the case of arguments that take values (i.e. takes_value(true)
)
and positional arguments (i.e. those without a preceding -
or --
) the name will also
be displayed when the user prints the usage/help information of the program.
Examples
Arg::with_name("config")
fn from_usage(u: &'a str) -> Self
Creates a new instance of Arg
from a usage string. Allows creation of basic settings for
the Arg
. The syntax is flexible, but there are some rules to follow.
NOTE: Not all settings may be set using the usage string method. Some properties are only available via the builder pattern.
NOTE: Only ASCII values in from_usage
strings are officially supported. Some UTF-8
codepoints may work just fine, but this is not guaranteed.
Syntax
Usage strings typically following the form:
[explicit name] [short] [long] [value names] [help string]
This is not a hard rule as the attributes can appear in other orders. There are also several additional sigils which denote additional settings. Below are the details of each portion of the string.
Explicit Name
This is an optional field, if it's omitted the argumenet will use one of the additioinal fields as the name using the following priority order:
- Explicit Name (This always takes precedence when present)
- Long
- Short
- Value Name
clap
determines explicit names as the first string of characters between either []
or
<>
where []
has the dual notation of meaning the argument is optional, and <>
meaning
the argument is required.
Explicit names may be followed by:
* The multiple denotation ...
Example explicit names as follows (ename
for an optional argument, and rname
for a
required argument):
[ename] -s, --long 'some flag'
<rname> -r, --longer 'some other flag'
Short
This is set by placing a single character after a leading -
.
Shorts may be followed by
* The multiple denotation ...
* An optional comma ,
which is cosmetic only
* Value notation
Example shorts are as follows (-s
, and -r
):
-s, --long 'some flag'
<rname> -r [val], --longer 'some option'
Long
This is set by placing a word (no spaces) after a leading --
.
Shorts may be followed by
* The multiple denotation ...
* Value notation
Example longs are as follows (--some
, and --rapid
):
-s, --some 'some flag'
--rapid=[FILE] 'some option'
Values (Value Notation)
This is set by placing a word(s) between []
or <>
optionally after =
(although this
is cosmetic only and does not affect functionality). If an explicit name has not been
set, using <>
will denote a required argument, and []
will denote an optional argument
Values may be followed by
* The multiple denotation ...
* More Value notation
More than one value will also implicitly set the arguments number of values, i.e. having
two values, --option [val1] [val2]
specifies that in order for option to be satisified it
must receive exactly two values
Example values are as follows (FILE
, and SPEED
):
-s, --some [FILE] 'some option'
--rapid=<SPEED>... 'some required multiple option'
Help String
The help string is denoted between a pair of single quotes ''
and may contain any characters.
Example help strings are as follows:
-s, --some [FILE] 'some option'
--rapid=<SPEED>... 'some required multiple option'
Additional Sigils
Multiple notation ...
(three consecutive dots/periods) specifies that this argument may
be used multiple times. Do not confuse multiple occurrences (...
) with multiple values.
--option val1 val2
is a single occurrence with multiple values. --flag --flag
is
multiple occurrences (and then you can obviously have instances of both as well)
Examples
App::new("myprog") .args(&[ Arg::from_usage("--config <FILE> 'a required file for the configuration and no short'"), Arg::from_usage("-d, --debug... 'turns on debugging information and allows multiples'"), Arg::from_usage("[input] 'an optional input file to use'") ])
fn short<S: AsRef<str>>(self, s: S) -> Self
Sets the short version of the argument without the preceding -
.
By default clap
automatically assigns V
and h
to display version and help information
respectively. You may use V
or h
for your own purposes, in which case clap
simply
will not assign those to the displaying of version or help.
NOTE: Any leading -
characters will be stripped, and only the first
non -
character will be used as the short
version
Examples
To set short
use a single valid UTF-8 codepoint. If you supply a leading -
such as -c
it will be stripped.
Arg::with_name("config") .short("c")
Setting short
allows using the argument via a single hyphen (-
) such as -c
let m = App::new("shorttest") .arg(Arg::with_name("config") .short("c")) .get_matches_from(vec![ "shorttest", "-c" ]); assert!(m.is_present("config"));
fn long(self, l: &'b str) -> Self
Sets the long version of the argument without the preceding --
.
By default clap
automatically assigns version
and help
to display version and help
information respectively. You may use version
or help
for your own purposes, in which
case clap
simply will not assign those to the displaying of version or help automatically,
and you will have to do so manually.
NOTE: Any leading -
characters will be stripped
Examples
To set long
use a word containing valid UTF-8 codepoints. If you supply a dobule leading
--
such as --config
they will be stripped. Hyphens in the middle of the word, however,
will not be stripped (i.e. config-file
is allowed)
Arg::with_name("cfg") .long("config")
Setting long
allows using the argument via a double hyphen (--
) such as --config
let m = App::new("longtest") .arg(Arg::with_name("cfg") .long("config")) .get_matches_from(vec![ "shorttest", "--config" ]); assert!(m.is_present("cfg"));
fn help(self, h: &'b str) -> Self
Sets the help text of the argument that will be displayed to the user when they print the usage/help information.
Examples
Any valid String
slice is allowed as help (i.e. only valid UTF-8). The one exception is
one wishes to include a newline in the help text. To include a newline and be properly
aligned with all other arguments help text, it must be specified via {n}
instead of \n
.
Arg::with_name("config") .help("The config file used by the myprog")
Setting help
displays a short message to the side of the argument when the user passes
-h
or --help
(by default).
let m = App::new("helptest") .arg(Arg::with_name("cfg") .long("config") .help("Some help text describing the --config arg")) .get_matches_from(vec![ "shorttest", "--help" ]); // ...
The above example displays
helptest
USAGE:
helptest [FLAGS]
FLAGS:
--config Some help text describing the --config arg
-h, --help Prints help information
-V, --version Prints version information
fn required(self, r: bool) -> Self
Sets whether or not the argument is required by default. Required by default means it is
required, when no other conflicting rules have been evaluated. Conflicting rules take
precedence over being required. Default: false
NOTE: Flags (i.e. not positional, or arguments that take values) cannot be required.
Examples
Arg::with_name("config") .required(true)
Setting required(true)
requires that the argument be used at runtime.
let res = App::new("longtest") .arg(Arg::with_name("cfg") .required(true) .takes_value(true) .long("config")) .get_matches_from_safe(vec![ "shorttest", "--config", "file.conf" ]); assert!(res.is_ok());
Setting required(true)
and not supplying that argument is an error.
let res = App::new("longtest") .arg(Arg::with_name("cfg") .required(true) .takes_value(true) .long("config")) .get_matches_from_safe(vec![ "shorttest" ]); assert!(res.is_err()); assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
fn conflicts_with(self, name: &'a str) -> Self
Sets a conflicting argument by name. I.e. when using this argument, the following argument can't be present and vice versa.
NOTE: Conflicting rules take precedence over being required by default. Conflict rules only need to be set for one of the two arguments, they do not need to be set for each.
NOTE: Defining a conflict is two-way, but does not need to defined for both arguments (i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not need need to also do B.conflicts_with(A))
Examples
Arg::with_name("config") .conflicts_with("debug")
Setting conflicting argument, and having both arguments present at runtime is an error.
let res = App::new("conflictions") .arg(Arg::with_name("cfg") .takes_value(true) .conflicts_with("debug") .long("config")) .arg(Arg::with_name("debug") .long("debug")) .get_matches_from_safe(vec![ "conflictions", "--debug", "--config", "file.conf" ]); assert!(res.is_err()); assert_eq!(res.unwrap_err().kind, ErrorKind::ArgumentConflict);
fn conflicts_with_all(self, names: &[&'a str]) -> Self
The same as Arg::conflicts_with
but allows specifying multiple two-way conlicts per
argument.
NOTE: Conflicting rules take precedence over being required by default. Conflict rules only need to be set for one of the two arguments, they do not need to be set for each.
NOTE: Defining a conflict is two-way, but does not need to defined for both arguments (i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not need need to also do B.conflicts_with(A))
Examples
Arg::with_name("config") .conflicts_with_all(&["debug", "input"])
Setting conflicting argument, and having any of the arguments present at runtime with a conflicting argument is an error.
let res = App::new("conflictions") .arg(Arg::with_name("cfg") .takes_value(true) .conflicts_with_all(&["debug", "input"]) .long("config")) .arg(Arg::with_name("debug") .long("debug")) .arg(Arg::with_name("input") .index(1)) .get_matches_from_safe(vec![ "conflictions", "--config", "file.conf", "file.txt" ]); assert!(res.is_err()); assert_eq!(res.unwrap_err().kind, ErrorKind::ArgumentConflict);
fn overrides_with(self, name: &'a str) -> Self
Sets a overridable argument by name. I.e. this argument and the following argument will override each other in POSIX style (whichever argument was specified at runtime last "wins")
NOTE: When an argument is overriden it is essentially as if it never was used, any conflicts, requirements, etc. are evaluated after all "overrides" have been removed
Examples
let m = App::new("posix") .arg(Arg::from_usage("-f, --flag 'some flag'") .conflicts_with("debug")) .arg(Arg::from_usage("-d, --debug 'other flag'")) .arg(Arg::from_usage("-c, --color 'third flag'") .overrides_with("flag")) .get_matches_from(vec!["posix", "-f", "-d", "-c"]); // ^~~~~~~~~~~~^~~~~ flag is overriden by color assert!(m.is_present("color")); assert!(m.is_present("debug")); // even though flag conflicts with debug, it's as if flag // was never used because it was overriden with color assert!(!m.is_present("flag"));
fn overrides_with_all(self, names: &[&'a str]) -> Self
Sets multiple mutually overridable arguments by name. I.e. this argument and the following argument will override each other in POSIX style (whichever argument was specified at runtime last "wins")
NOTE: When an argument is overriden it is essentially as if it never was used, any conflicts, requirements, etc. are evaluated after all "overrides" have been removed
Examples
let m = App::new("posix") .arg(Arg::from_usage("-f, --flag 'some flag'") .conflicts_with("color")) .arg(Arg::from_usage("-d, --debug 'other flag'")) .arg(Arg::from_usage("-c, --color 'third flag'") .overrides_with_all(&["flag", "debug"])) .get_matches_from(vec!["posix", "-f", "-d", "-c"]); // ^~~~~~^~~~~~~~~ flag and debug are overriden by color assert!(m.is_present("color")); // even though flag conflicts with color, it's as if flag // and debug were never used because they were overriden // with color assert!(!m.is_present("debug")); assert!(!m.is_present("flag"));
fn requires(self, name: &'a str) -> Self
Sets an argument by name that is required when this one is present I.e. when using this argument, the following argument must be present.
NOTE: Conflicting rules and override rules take precedence over being required
Examples
Arg::with_name("config") .requires("input")
Setting requires("arg")
requires that the argument be used at runtime if the defining
argument is used. If the defining argument isn't used, the other arguemnt isn't required
let res = App::new("reqtest") .arg(Arg::with_name("cfg") .takes_value(true) .requires("input") .long("config")) .arg(Arg::with_name("input") .index(1)) .get_matches_from_safe(vec![ "reqtest" ]); assert!(res.is_ok()); // We didn't use cfg, so input wasn't required
Setting requires("arg")
and not supplying that argument is an error.
let res = App::new("reqtest") .arg(Arg::with_name("cfg") .takes_value(true) .requires("input") .long("config")) .arg(Arg::with_name("input") .index(1)) .get_matches_from_safe(vec![ "reqtest", "--config", "file.conf" ]); assert!(res.is_err()); assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
fn requires_all(self, names: &[&'a str]) -> Self
Sets multiple arguments by names that are required when this one is present I.e. when using this argument, the following arguments must be present.
NOTE: Mutually exclusive and override rules take precedence over being required by default.
Examples
Arg::with_name("config") .requires_all(&["input", "output"])
Setting requires_all(&["arg", "arg2"])
requires that all the arguments be used at runtime
if the defining argument is used. If the defining argument isn't used, the other arguemnt
isn't required
let res = App::new("reqtest") .arg(Arg::with_name("cfg") .takes_value(true) .requires("input") .long("config")) .arg(Arg::with_name("input") .index(1)) .arg(Arg::with_name("output") .index(2)) .get_matches_from_safe(vec![ "reqtest" ]); assert!(res.is_ok()); // We didn't use cfg, so input and output weren't required
Setting requires_all(&["arg", "arg2"])
and not supplying all the arguments is an error.
let res = App::new("reqtest") .arg(Arg::with_name("cfg") .takes_value(true) .requires_all(&["input", "output"]) .long("config")) .arg(Arg::with_name("input") .index(1)) .arg(Arg::with_name("output") .index(2)) .get_matches_from_safe(vec![ "reqtest", "--config", "file.conf", "in.txt" ]); assert!(res.is_err()); // We didn't use output assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
fn takes_value(self, tv: bool) -> Self
Specifies that the argument takes a value at run time.
NOTE: values for arguments may be specified in any of the following methods
- Using a space such as
-o value
or--option value
- Using an equals and no space such as
-o=value
or--option=value
- Use a short and no space such as
-ovalue
NOTE: By default, values are delimted by commas, meaning --option=val1,val2,val3
is
is three values for the --option
argument. If you wish to change the delimiter to another
character you can use Arg::value_delimiter(char)
, alternatively you can delimiting values
OFF by using Arg::use_delimiter(false)
Examples
Arg::with_name("config") .takes_value(true)
let m = App::new("posvals") .arg(Arg::with_name("mode") .long("mode") .takes_value(true)) .get_matches_from(vec!["posvals", "--mode", "fast"]); assert!(m.is_present("mode")); assert_eq!(m.value_of("mode"), Some("fast"));
fn index(self, idx: u64) -> Self
Specifies the index of a positional argument starting at 1.
NOTE: The index refers to position according to other positional argument. It does not define position in the argument list as a whole.
NOTE: If no short
, or long
have been defined, you can optionally leave off the
index
method, and the index will be assigned in order of evaluation. Utilizing the
index
method allows for setting indexes out of order
NOTE: When utilized with multiple(true)
, only the last psoitional argument may
be defined as multiple (i.e. with the highest index)
Panics
Although not in this method directly, App
will panic!
if indexes are skipped (such as
defining index(1)
and index(3)
but not index(2)
, or a positional argument is defined
as multiple and is not the highest index
Examples
Arg::with_name("config") .index(1)
let m = App::new("posvals") .arg(Arg::with_name("mode") .index(1)) .arg(Arg::with_name("debug") .long("debug")) .get_matches_from(vec!["posvals", "--debug", "fast"]); assert!(m.is_present("mode")); assert_eq!(m.value_of("mode"), Some("fast")); // notice index(1) means "first positional" // *not* first argument
fn multiple(self, multi: bool) -> Self
Specifies that the argument may appear more than once. For flags, this results
in the number of occurrences of the flag being recorded. For example -ddd
or -d -d -d
would count as three occurrences. For options there is a distinct difference in multiple
occurrences vs multiple values.
For example, --opt val1 val2
is one occurrence, but two values. Whereas
--opt val1 --opt val2
is two occurrences.
WARNING:
Setting multipe(true)
for an option allows multiple values and multiple occurrences
because it isn't possible to more occurrences than values for options. Because multiple
values are allowed, --option val1 val2 val3
is perfectly valid, be careful when designing
a CLI where positional arguments are expectd after a option which accepts multiple values,
as clap
will continue parsing values until it reaches the max or specific number of values defined, or another flag
or option.
Pro Tip:
It's possible to define an option which allows multiple occurrences, but only one value per
occurrence. To do this use Arg::number_of_values(1)
in coordination with
Arg::multiple(true)
.
Examples
Arg::with_name("debug") .short("d") .multiple(true)
An example with flags
let m = App::new("mults") .arg(Arg::with_name("verbose") .multiple(true) .short("v")) .get_matches_from(vec!["mults", "-v", "-v", "-v"]); // note, -vvv would have same result assert!(m.is_present("verbose")); assert_eq!(m.occurrences_of("verbose"), 3);
An example with options
let m = App::new("mults") .arg(Arg::with_name("file") .multiple(true) .takes_value(true) .short("F")) .get_matches_from(vec!["mults", "-F", "file1", "file2", "file3"]); assert!(m.is_present("file")); assert_eq!(m.occurrences_of("file"), 1); // notice only one occurrence let files: Vec<_> = m.values_of("file").unwrap().collect(); assert_eq!(files, ["file1", "file2", "file3"]);
This is functionally equivilant to the example above
let m = App::new("mults") .arg(Arg::with_name("file") .multiple(true) .takes_value(true) .short("F")) .get_matches_from(vec!["mults", "-F", "file1", "-F", "file2", "-F", "file3"]); let files: Vec<_> = m.values_of("file").unwrap().collect(); assert_eq!(files, ["file1", "file2", "file3"]); assert!(m.is_present("file")); assert_eq!(m.occurrences_of("file"), 3); // Notice 3 occurrences let files: Vec<_> = m.values_of("file").unwrap().collect(); assert_eq!(files, ["file1", "file2", "file3"]);
A common mistake is to define an option which allows multiples, and a positional argument
let m = App::new("mults") .arg(Arg::with_name("file") .multiple(true) .takes_value(true) .short("F")) .arg(Arg::with_name("word") .index(1)) .get_matches_from(vec!["mults", "-F", "file1", "file2", "file3", "word"]); assert!(m.is_present("file")); let files: Vec<_> = m.values_of("file").unwrap().collect(); assert_eq!(files, ["file1", "file2", "file3", "word"]); // wait...what?! assert!(!m.is_present("word")); // but we clearly used word!
The problem is clap doesn't know when to stop parsing values for "files". This is further
compounded by if we'd said word -F file1 file2
it would have worked fine, so it would
appear to only fail sometimes...not good!
A solution for the example above is to specify that -F
only accepts one value, but is
allowed to appear multiple times
let m = App::new("mults") .arg(Arg::with_name("file") .multiple(true) .takes_value(true) .number_of_values(1) .short("F")) .arg(Arg::with_name("word") .index(1)) .get_matches_from(vec!["mults", "-F", "file1", "-F", "file2", "-F", "file3", "word"]); assert!(m.is_present("file")); let files: Vec<_> = m.values_of("file").unwrap().collect(); assert_eq!(files, ["file1", "file2", "file3"]); assert!(m.is_present("word")); assert_eq!(m.value_of("word"), Some("word"));
As a final example, notice if we define number_of_values(1)
and try to run the problem
example above, it would have been a runtime error with a pretty message to the user :)
let res = App::new("mults") .arg(Arg::with_name("file") .multiple(true) .takes_value(true) .number_of_values(1) .short("F")) .arg(Arg::with_name("word") .index(1)) .get_matches_from_safe(vec!["mults", "-F", "file1", "file2", "file3", "word"]); assert!(res.is_err()); assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
fn global(self, g: bool) -> Self
Specifies that an argument can be matched to all child subcommands.
NOTE: Global arguments only propagate down, not up (to parent commands)
NOTE: Global arguments cannot be required.
NOTE: Global arguments, when matched, only exist in the command's matches that they
were matched to. For example, if you defined a --flag
global argument in the top most
parent command, but the user supplied the arguments top cmd1 cmd2 --flag
only cmd2
's
ArgMatches
would return true
if tested for .is_present("flag")
.
Examples
Arg::with_name("debug") .short("d") .global(true)
For example, assume an appliction with two subcommands, and you'd like to define a
--verbose
flag that can be called on any of the subcommands and parent, but you don't
want to clutter the source with three duplicate Arg
definitions.
let m = App::new("mults") .arg(Arg::with_name("verb") .long("verbose") .short("v") .global(true)) .subcommand(SubCommand::with_name("test")) .subcommand(SubCommand::with_name("do-stuff")) .get_matches_from(vec!["mults", "do-stuff", "--verbose"]); assert_eq!(m.subcommand_name(), Some("do-stuff")); let sub_m = m.subcommand_matches("do-stuff").unwrap(); assert!(sub_m.is_present("verb"));
fn empty_values(self, ev: bool) -> Self
Allows an argument to accept explicitly empty values. An empty value must be specified at
the command line with an explicit ""
, or ''
NOTE: Defaults to true
(Explicitly empty values are allowed)
NOTE: Implicitly sets takes_value(true)
when set to false
Examples
Arg::with_name("file") .long("file") .empty_values(false)
The default is to allow empty values, such as --option ""
would be an empty value. But
we can change to make empty values become an error.
let res = App::new("evals") .arg(Arg::with_name("cfg") .long("config") .short("v") .empty_values(false)) .get_matches_from_safe(vec!["evals", "--config="]); assert!(res.is_err()); assert_eq!(res.unwrap_err().kind, ErrorKind::EmptyValue);
fn hidden(self, h: bool) -> Self
Hides an argument from help message output.
NOTE: This does not hide the argument from usage strings on error
Examples
Arg::with_name("debug") .hidden(true)
Setting hidden(true)
will hide the argument when displaying help text
let m = App::new("helptest") .arg(Arg::with_name("cfg") .long("config") .hidden(true) .help("Some help text describing the --config arg")) .get_matches_from(vec![ "shorttest", "--help" ]); // ...
The above example displays
helptest
USAGE:
helptest [FLAGS]
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
fn possible_values(self, names: &[&'b str]) -> Self
Specifies a list of possible values for this argument. At runtime, clap
verifies that only
one of the specified values was used, or fails with an error message.
NOTE: This setting only applies to options and positional arguments
Examples
Arg::with_name("mode") .takes_value(true) .possible_values(&["fast", "slow", "medium"])
let m = App::new("posvals") .arg(Arg::with_name("mode") .long("mode") .takes_value(true) .possible_values(&["fast", "slow", "medium"])) .get_matches_from(vec!["posvals", "--mode", "fast"]); assert!(m.is_present("mode")); assert_eq!(m.value_of("mode"), Some("fast"));
The next example shows a failed parse from using a value which wasn't defined as one of the possible values.
let res = App::new("posvals") .arg(Arg::with_name("mode") .long("mode") .takes_value(true) .possible_values(&["fast", "slow", "medium"])) .get_matches_from_safe(vec!["myprog", "--mode", "wrong"]); assert!(res.is_err()); assert_eq!(res.unwrap_err().kind, ErrorKind::InvalidValue);
fn possible_value(self, name: &'b str) -> Self
Specifies a possible value for this argument, one at a time. At runtime, clap
verifies
that only one of the specified values was used, or fails with error message.
Examples
Arg::with_name("mode") .takes_value(true) .possible_value("fast") .possible_value("slow") .possible_value("medium")
let m = App::new("posvals") .arg(Arg::with_name("mode") .long("mode") .takes_value(true) .possible_value("fast") .possible_value("slow") .possible_value("medium")) .get_matches_from(vec!["posvals", "--mode", "fast"]); assert!(m.is_present("mode")); assert_eq!(m.value_of("mode"), Some("fast"));
The next example shows a failed parse from using a value which wasn't defined as one of the possible values.
let res = App::new("posvals") .arg(Arg::with_name("mode") .long("mode") .takes_value(true) .possible_value("fast") .possible_value("slow") .possible_value("medium")) .get_matches_from_safe(vec!["myprog", "--mode", "wrong"]); assert!(res.is_err()); assert_eq!(res.unwrap_err().kind, ErrorKind::InvalidValue);
fn group(self, name: &'a str) -> Self
Specifies the name of the group the argument belongs to.
Examples
Arg::with_name("debug") .long("debug") .group("mode")
Multiple arguments can be a member of a single group and then the group checked as if it was one of said arguments.
let m = App::new("groups") .arg(Arg::with_name("debug") .long("debug") .group("mode")) .arg(Arg::with_name("verbose") .long("verbose") .group("mode")) .get_matches_from(vec!["posvals", "--debug"]); assert!(m.is_present("mode"));
fn number_of_values(self, qty: u64) -> Self
Specifies how many values are required to satisfy this argument. For example, if you had a
-f <file>
argument where you wanted exactly 3 'files' you would set
.number_of_values(3)
, and this argument wouldn't be satisfied unless the user provided
3 and only 3 values.
NOTE: Does not require .multiple(true)
to be set. Setting .multiple(true)
would
allow -f <file> <file> <file> -f <file> <file> <file>
where as not setting
.multiple(true)
would only allow one occurrence of this argument.
Examples
Arg::with_name("file") .short("f") .number_of_values(3)
Not supplying the correct number of values is an error
let res = App::new("numvals") .arg(Arg::with_name("file") .takes_value(true) .number_of_values(2) .short("F")) .get_matches_from_safe(vec!["mults", "-F", "file1"]); assert!(res.is_err()); assert_eq!(res.unwrap_err().kind, ErrorKind::WrongNumberOfValues);
fn validator<F>(self, f: F) -> Self where F: Fn(String) -> Result<(), String> + 'static
Allows one to perform a custom validation on the argument value. You provide a closure which
accepts a String
value, a Result
where the Err(String)
is a message displayed to the
user.
NOTE: The error message does not need to contain the error:
portion, only the
message.
NOTE: There is a small performance hit for using validators, as they are implemented
with Rc
pointers. And the value to be checked will be allocated an extra time in order to
to be passed to the closure. This performance hit is extremely minimal in the grand scheme
of things.
Examples
fn has_at(v: String) -> Result<(), String> { if v.contains("@") { return Ok(()); } Err(String::from("The value did not contain the required @ sigil")) } let res = App::new("validators") .arg(Arg::with_name("file") .index(1) .validator(has_at)) .get_matches_from_safe(vec![ "validators", "some@file" ]); assert!(res.is_ok()); assert_eq!(res.unwrap().value_of("file"), Some("some@file"));
fn max_values(self, qty: u64) -> Self
Specifies the maximum number of values are for this argument. For example, if you had a
-f <file>
argument where you wanted up to 3 'files' you would set
.max_values(3)
, and this argument would be satisfied if the user provided, 1, 2, or 3
values.
NOTE: This does not implicitly set mulitple(true)
. This is because -o val -o val
is
multiples occurrences but a single value and -o val1 val2
is a single occurence with
multple values. For positional arguments this does set multiple(true)
because there
is no way to determine the diffrence between multiple occureces and multiple values.
Examples
Arg::with_name("file") .short("f") .max_values(3)
Supplying less than the maximum number of values is allowed
let res = App::new("numvals") .arg(Arg::with_name("file") .takes_value(true) .max_values(3) .short("F")) .get_matches_from_safe(vec!["mults", "-F", "file1", "file2"]); assert!(res.is_ok()); let m = res.unwrap(); let files: Vec<_> = m.values_of("file").unwrap().collect(); assert_eq!(files, ["file1", "file2"]);
Supplying more than the maximum number of values is an error
let res = App::new("numvals") .arg(Arg::with_name("file") .takes_value(true) .max_values(2) .short("F")) .get_matches_from_safe(vec!["mults", "-F", "file1", "file2", "file3"]); assert!(res.is_err()); assert_eq!(res.unwrap_err().kind, ErrorKind::TooManyValues);
fn min_values(self, qty: u64) -> Self
Specifies the minimum number of values are for this argument. For example, if you had a
-f <file>
argument where you wanted at least 2 'files' you would set
.min_values(2)
, and this argument would be satisfied if the user provided, 2 or more
values.
NOTE: This does not implicitly set mulitple(true)
. This is because -o val -o val
is
multiples occurrences but a single value and -o val1 val2
is a single occurence with
multple values. For positional arguments this does set multiple(true)
because there
is no way to determine the diffrence between multiple occureces and multiple values.
Examples
Arg::with_name("file") .short("f") .min_values(3)
Supplying more than the minimum number of values is allowed
let res = App::new("numvals") .arg(Arg::with_name("file") .takes_value(true) .min_values(2) .short("F")) .get_matches_from_safe(vec!["mults", "-F", "file1", "file2", "file3"]); assert!(res.is_ok()); let m = res.unwrap(); let files: Vec<_> = m.values_of("file").unwrap().collect(); assert_eq!(files, ["file1", "file2", "file3"]);
Supplying less than the mainimum number of values is an error
let res = App::new("numvals") .arg(Arg::with_name("file") .takes_value(true) .min_values(2) .short("F")) .get_matches_from_safe(vec!["mults", "-F", "file1"]); assert!(res.is_err()); assert_eq!(res.unwrap_err().kind, ErrorKind::TooFewValues);
fn use_delimiter(self, d: bool) -> Self
Specifies whether or not an arugment should allow grouping of multiple values via a
delimter. I.e. shoulde --option=val1,val2,val3
be parsed as three values (val1
, val2
,
and val3
) or as a single value (val1,val2,val3
). Defaults to using ,
(comma) as the
value delimiter for all arguments that accept values (options and positional arguments)
NOTE: The defalt is true
. Setting the value to true
will reset any previous use of
Arg::value_delimiter
back to the default of ,
(comma).
Examples
The following example shows the default behavior.
let delims = App::new("delims") .arg(Arg::with_name("option") .long("option") .takes_value(true)) .get_matches_from(vec![ "delims", "--option=val1,val2,val3", ]); assert!(delims.is_present("option")); assert_eq!(delims.occurrences_of("option"), 1); assert_eq!(delims.values_of("option").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"]);
The next example shows the difference when turning delimiters off.
let nodelims = App::new("nodelims") .arg(Arg::with_name("option") .long("option") .use_delimiter(false) .takes_value(true)) .get_matches_from(vec![ "nodelims", "--option=val1,val2,val3", ]); assert!(nodelims.is_present("option")); assert_eq!(nodelims.occurrences_of("option"), 1); assert_eq!(nodelims.value_of("option").unwrap(), "val1,val2,val3");
fn value_delimiter(self, d: &str) -> Self
Specifies the separator to use when values are clumped together, defaults to ,
(comma).
NOTE: implicitly sets Arg::use_delimiter(true)
NOTE: implicitly sets Arg::takes_value(true)
Examples
let app = App::new("fake") .arg(Arg::with_name("config") .short("c") .long("config") .value_delimiter(";")); let m = app.get_matches_from(vec![ "fake", "--config=val1;val2;val3" ]); assert_eq!(m.values_of("config").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"])
fn value_names(self, names: &[&'b str]) -> Self
Specify multiple names for values of option arguments. These names are cosmetic only, used
for help and usage strings only. The names are not used to access arguments. The values
of the arguments are accessed in numeric order (i.e. if you specify two names one
and
two
one
will be the first matched value, two
will be the second).
This setting can be very helpful when describing the type of input the user should be
using, such as FILE
, INTERFACE
, etc. Although not required, it's somewhat convention to
use all capital letters for the value name.
Pro Tip: It may help to use Arg::next_line_help(true)
if there are long, or multiple
value names in order to not throw off the help text alignment of all options.
NOTE: This implicitly sets .number_of_values()
if the number of value names is
greater than one. I.e. be aware that the number of "names" you set for the values, will be
the exact number of values required to satisfy this argument
NOTE: implicitly sets Arg::takes_value(true)
NOTE: Does not require or imply .multiple(true)
.
Examples
Arg::with_name("speed") .short("s") .value_names(&["fast", "slow"])
let app = App::new("valnames") .arg(Arg::with_name("io") .long("io-files") .value_names(&["INFILE", "OUTFILE"])) .get_matches_from(vec![ "valnames", "--help" ]);
Running the above program produces the following output
valnames
USAGE:
valnames [FLAGS] [OPTIONS]
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
--io-files <INFILE> <OUTFILE> Some help text
fn value_name(self, name: &'b str) -> Self
Specifies the name for value of option or positional arguments inside of help documenation.
This name is cosmetic only, the name is not used to access arguments. This setting can
be very helpful when describing the type of input the user should be using, such as FILE
,
INTERFACE
, etc. Although not required, it's somewhat convention to use all capital
letters for the value name.
NOTE: implicitly sets Arg::takes_value(true)
Examples
Arg::with_name("cfg") .long("config") .value_name("FILE")
let app = App::new("valnames") .arg(Arg::with_name("config") .long("config") .value_name("FILE")) .get_matches_from(vec![ "valnames", "--help" ]);
Running the above program produces the following output
valnames
USAGE:
valnames [FLAGS] [OPTIONS]
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
--config <FILE> Some help text
fn default_value(self, val: &'a str) -> Self
Specifies the value of the argument when not specified at runtime.
NOTE: If the user does not use this argument at runtime, ArgMatches::occurrences_of
will return 0
even though the value_of
will return the default specified.
NOTE: If the user does not use this argument at runtime ArgMatches::is_present
will
still return true
. If you wish to determine whether the argument was used at runtime or
not, consider ArgMatches::occurrences_of
which will return 0
if the argument was not
used at runtmie.
NOTE: This implicitly sets Arg::takes_value(true)
.
Examples
let m = App::new("defvals") .arg(Arg::with_name("opt") .long("myopt") .default_value("myval")) .get_matches_from(vec![ "defvals" ]); assert_eq!(m.value_of("opt"), Some("myval")); assert!(m.is_present("opt")); assert_eq!(m.occurrences_of("opt"), 0);
fn next_line_help(self, nlh: bool) -> Self
When set to true
the help string will be displayed on the line after the argument and
indented once. This can be helpful for arguments with very long or complex help messages.
This can also be helpful for arguments with very long flag names, or many/long value names.
NOTE: To apply this setting to all arguments consider using AppSettings::NextLineHelp
Examples
let m = App::new("nlh") .arg(Arg::with_name("opt") .long("long-option-flag") .short("o") .takes_value(true) .value_names(&["value1", "value2"]) .help("Some really long help and complex{n}\ help that makes more sense to be{n}\ on a line after the option") .next_line_help(true)) .get_matches_from(vec![ "nlh", "--help" ]);
The above example displays the following help message
nlh USAGE: nlh [FLAGS] [OPTIONS] FLAGS: -h, --help Prints help information -V, --version Prints version information OPTIONS: -o, --long-option-flag <value1> <value2> Some really long help and complex help that makes more sense to be on a line after the option
fn is_set(&self, s: ArgSettings) -> bool
Checks if one of the ArgSettings
settings is set for the argument
fn set(self, s: ArgSettings) -> Self
Sets one of the ArgSettings
settings for the argument
fn unset(self, s: ArgSettings) -> Self
Unsets one of the ArgSettings
settings for the argument