pub struct ArgGroup<'a> { /* private fields */ }
Expand description
ArgGroup
s are a family of related arguments and way for you to express, “Any of these
arguments”. By placing arguments in a logical group, you can create easier requirement and
exclusion rules instead of having to list each argument individually, or when you want a rule
to apply “any but not all” arguments.
For instance, you can make an entire ArgGroup
required. If ArgGroup::multiple(true)
is
set, this means that at least one argument from that group must be present. If
[ArgGroup::multiple(false)
] is set (the default), one and only one must be present.
You can also do things such as name an entire ArgGroup
as a conflict or requirement for
another argument, meaning any of the arguments that belong to that group will cause a failure
if present, or must present respectively.
Perhaps the most common use of ArgGroup
s is to require one and only one argument to be
present out of a given set. Imagine that you had multiple arguments, and you want one of them
to be required, but making all of them required isn’t feasible because perhaps they conflict
with each other. For example, lets say that you were building an application where one could
set a given version number by supplying a string with an option argument, i.e.
--set-ver v1.2.3
, you also wanted to support automatically using a previous version number
and simply incrementing one of the three numbers. So you create three flags --major
,
--minor
, and --patch
. All of these arguments shouldn’t be used at one time but you want to
specify that at least one of them is used. For this, you can create a group.
Finally, you may use ArgGroup
s to pull a value from a group of arguments when you don’t care
exactly which argument was actually used at runtime.
Examples
The following example demonstrates using an ArgGroup
to ensure that one, and only one, of
the arguments from the specified group is present at runtime.
let result = App::new("app")
.args_from_usage(
"--set-ver [ver] 'set the version manually'
--major 'auto increase major'
--minor 'auto increase minor'
--patch 'auto increase patch'")
.group(ArgGroup::with_name("vers")
.args(&["set-ver", "major", "minor", "patch"])
.required(true))
.get_matches_from_safe(vec!["app", "--major", "--patch"]);
// Because we used two args in the group it's an error
assert!(result.is_err());
let err = result.unwrap_err();
assert_eq!(err.kind, ErrorKind::ArgumentConflict);
This next example shows a passing parse of the same scenario
let result = App::new("app")
.args_from_usage(
"--set-ver [ver] 'set the version manually'
--major 'auto increase major'
--minor 'auto increase minor'
--patch 'auto increase patch'")
.group(ArgGroup::with_name("vers")
.args(&["set-ver", "major", "minor","patch"])
.required(true))
.get_matches_from_safe(vec!["app", "--major"]);
assert!(result.is_ok());
let matches = result.unwrap();
// We may not know which of the args was used, so we can test for the group...
assert!(matches.is_present("vers"));
// we could also alternatively check each arg individually (not shown here)
Implementations
sourceimpl<'a> ArgGroup<'a>
impl<'a> ArgGroup<'a>
sourcepub fn with_name(n: &'a str) -> Self
pub fn with_name(n: &'a str) -> Self
Creates a new instance of ArgGroup
using a unique string name. The name will be used to
get values from the group or refer to the group inside of conflict and requirement rules.
Examples
ArgGroup::with_name("config")
sourcepub fn arg(self, n: &'a str) -> Self
pub fn arg(self, n: &'a str) -> Self
Adds an argument to this group by name
Examples
let m = App::new("myprog")
.arg(Arg::with_name("flag")
.short("f"))
.arg(Arg::with_name("color")
.short("c"))
.group(ArgGroup::with_name("req_flags")
.arg("flag")
.arg("color"))
.get_matches_from(vec!["myprog", "-f"]);
// maybe we don't know which of the two flags was used...
assert!(m.is_present("req_flags"));
// but we can also check individually if needed
assert!(m.is_present("flag"));
sourcepub fn args(self, ns: &[&'a str]) -> Self
pub fn args(self, ns: &[&'a str]) -> Self
Adds multiple arguments to this group by name
Examples
let m = App::new("myprog")
.arg(Arg::with_name("flag")
.short("f"))
.arg(Arg::with_name("color")
.short("c"))
.group(ArgGroup::with_name("req_flags")
.args(&["flag", "color"]))
.get_matches_from(vec!["myprog", "-f"]);
// maybe we don't know which of the two flags was used...
assert!(m.is_present("req_flags"));
// but we can also check individually if needed
assert!(m.is_present("flag"));
sourcepub fn multiple(self, m: bool) -> Self
pub fn multiple(self, m: bool) -> Self
Allows more than one of the ‘Arg’s in this group to be used. (Default: false
)
Examples
Notice in this example we use both the -f
and -c
flags which are both part of the
group
let m = App::new("myprog")
.arg(Arg::with_name("flag")
.short("f"))
.arg(Arg::with_name("color")
.short("c"))
.group(ArgGroup::with_name("req_flags")
.args(&["flag", "color"])
.multiple(true))
.get_matches_from(vec!["myprog", "-f", "-c"]);
// maybe we don't know which of the two flags was used...
assert!(m.is_present("req_flags"));
In this next example, we show the default behavior (i.e. `multiple(false)) which will throw an error if more than one of the args in the group was used.
let result = App::new("myprog")
.arg(Arg::with_name("flag")
.short("f"))
.arg(Arg::with_name("color")
.short("c"))
.group(ArgGroup::with_name("req_flags")
.args(&["flag", "color"]))
.get_matches_from_safe(vec!["myprog", "-f", "-c"]);
// Because we used both args in the group it's an error
assert!(result.is_err());
let err = result.unwrap_err();
assert_eq!(err.kind, ErrorKind::ArgumentConflict);
sourcepub fn required(self, r: bool) -> Self
pub fn required(self, r: bool) -> Self
Sets the group as required or not. A required group will be displayed in the usage string
of the application in the format <arg|arg2|arg3>
. A required ArgGroup
simply states
that one argument from this group must be present at runtime (unless
conflicting with another argument).
NOTE: This setting only applies to the current App
/ SubCommand
, and not
globally.
NOTE: By default, ArgGroup::multiple
is set to false
which when combined with
ArgGroup::required(true)
states, “One and only one arg must be used from this group.
Use of more than one arg is an error.” Vice setting ArgGroup::multiple(true)
which
states, ’At least one arg from this group must be used. Using multiple is OK.“
Examples
let result = App::new("myprog")
.arg(Arg::with_name("flag")
.short("f"))
.arg(Arg::with_name("color")
.short("c"))
.group(ArgGroup::with_name("req_flags")
.args(&["flag", "color"])
.required(true))
.get_matches_from_safe(vec!["myprog"]);
// Because we didn't use any of the args in the group, it's an error
assert!(result.is_err());
let err = result.unwrap_err();
assert_eq!(err.kind, ErrorKind::MissingRequiredArgument);
sourcepub fn requires(self, n: &'a str) -> Self
pub fn requires(self, n: &'a str) -> Self
Sets the requirement rules of this group. This is not to be confused with a required group. Requirement rules function just like argument requirement rules, you can name other arguments or groups that must be present when any one of the arguments from this group is used.
NOTE: The name provided may be an argument, or group name
Examples
let result = App::new("myprog")
.arg(Arg::with_name("flag")
.short("f"))
.arg(Arg::with_name("color")
.short("c"))
.arg(Arg::with_name("debug")
.short("d"))
.group(ArgGroup::with_name("req_flags")
.args(&["flag", "color"])
.requires("debug"))
.get_matches_from_safe(vec!["myprog", "-c"]);
// because we used an arg from the group, and the group requires "-d" to be used, it's an
// error
assert!(result.is_err());
let err = result.unwrap_err();
assert_eq!(err.kind, ErrorKind::MissingRequiredArgument);
sourcepub fn requires_all(self, ns: &[&'a str]) -> Self
pub fn requires_all(self, ns: &[&'a str]) -> Self
Sets the requirement rules of this group. This is not to be confused with a required group. Requirement rules function just like argument requirement rules, you can name other arguments or groups that must be present when one of the arguments from this group is used.
NOTE: The names provided may be an argument, or group name
Examples
let result = App::new("myprog")
.arg(Arg::with_name("flag")
.short("f"))
.arg(Arg::with_name("color")
.short("c"))
.arg(Arg::with_name("debug")
.short("d"))
.arg(Arg::with_name("verb")
.short("v"))
.group(ArgGroup::with_name("req_flags")
.args(&["flag", "color"])
.requires_all(&["debug", "verb"]))
.get_matches_from_safe(vec!["myprog", "-c", "-d"]);
// because we used an arg from the group, and the group requires "-d" and "-v" to be used,
// yet we only used "-d" it's an error
assert!(result.is_err());
let err = result.unwrap_err();
assert_eq!(err.kind, ErrorKind::MissingRequiredArgument);
sourcepub fn conflicts_with(self, n: &'a str) -> Self
pub fn conflicts_with(self, n: &'a str) -> Self
Sets the exclusion rules of this group. Exclusion (aka conflict) rules function just like argument exclusion rules, you can name other arguments or groups that must not be present when one of the arguments from this group are used.
NOTE: The name provided may be an argument, or group name
Examples
let result = App::new("myprog")
.arg(Arg::with_name("flag")
.short("f"))
.arg(Arg::with_name("color")
.short("c"))
.arg(Arg::with_name("debug")
.short("d"))
.group(ArgGroup::with_name("req_flags")
.args(&["flag", "color"])
.conflicts_with("debug"))
.get_matches_from_safe(vec!["myprog", "-c", "-d"]);
// because we used an arg from the group, and the group conflicts with "-d", it's an error
assert!(result.is_err());
let err = result.unwrap_err();
assert_eq!(err.kind, ErrorKind::ArgumentConflict);
sourcepub fn conflicts_with_all(self, ns: &[&'a str]) -> Self
pub fn conflicts_with_all(self, ns: &[&'a str]) -> Self
Sets the exclusion rules of this group. Exclusion rules function just like argument exclusion rules, you can name other arguments or groups that must not be present when one of the arguments from this group are used.
NOTE: The names provided may be an argument, or group name
Examples
let result = App::new("myprog")
.arg(Arg::with_name("flag")
.short("f"))
.arg(Arg::with_name("color")
.short("c"))
.arg(Arg::with_name("debug")
.short("d"))
.arg(Arg::with_name("verb")
.short("v"))
.group(ArgGroup::with_name("req_flags")
.args(&["flag", "color"])
.conflicts_with_all(&["debug", "verb"]))
.get_matches_from_safe(vec!["myprog", "-c", "-v"]);
// because we used an arg from the group, and the group conflicts with either "-v" or "-d"
// it's an error
assert!(result.is_err());
let err = result.unwrap_err();
assert_eq!(err.kind, ErrorKind::ArgumentConflict);
Trait Implementations
Auto Trait Implementations
impl<'a> RefUnwindSafe for ArgGroup<'a>
impl<'a> Send for ArgGroup<'a>
impl<'a> Sync for ArgGroup<'a>
impl<'a> Unpin for ArgGroup<'a>
impl<'a> UnwindSafe for ArgGroup<'a>
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcepub fn borrow_mut(&mut self) -> &mut T
pub fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcepub fn to_owned(&self) -> T
pub fn to_owned(&self) -> T
Creates owned data from borrowed data, usually by cloning. Read more
sourcepub fn clone_into(&self, target: &mut T)
pub fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more