pub struct ArgGroup<'n, 'ar> { /* private fields */ }Expand description
ArgGroups are a family of related arguments and way for you to say, “Any of these arguments”.
By placing arguments in a logical group, you can make easier requirement and exclusion rules
intead of having to list each individually, or when you want a rule to apply “any but not all”
arguments.
For instance, you can make an entire ArgGroup required, this means that one (and only one) argument. from that group must be present. Using more than one argument from an ArgGroup causes a failure (graceful exit).
You can also do things such as name an ArgGroup as a confliction or requirement, 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 ArgGroups 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.
§Example
let _ = 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")
.arg_group(ArgGroup::with_name("vers")
.add_all(vec!["ver", "major", "minor","patch"])
.required(true))Implementations§
source§impl<'n, 'ar> ArgGroup<'n, 'ar>
impl<'n, 'ar> ArgGroup<'n, 'ar>
sourcepub fn with_name(n: &'n str) -> ArgGroup<'n, 'ar>
pub fn with_name(n: &'n str) -> ArgGroup<'n, 'ar>
Creates a new instace of ArgGroup using a unique string name.
The name will only be used by the library consumer and not displayed to the use.
§Example
ArgGroup::with_name("conifg")sourcepub fn add_all(self, ns: Vec<&'ar str>) -> ArgGroup<'n, 'ar>
pub fn add_all(self, ns: Vec<&'ar str>) -> ArgGroup<'n, 'ar>
Adds multiple arguments to this group by name using a Vec
§Example
.add_all(vec!["config", "input", "output"])sourcepub fn required(self, r: bool) -> ArgGroup<'n, 'ar>
pub fn required(self, r: bool) -> ArgGroup<'n, 'ar>
Sets the requirement of this group. 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, and only one argument from this group must be present at runtime (unless
conflicting with another argument).
§Example
.required(true)sourcepub fn requires(self, n: &'ar str) -> ArgGroup<'n, 'ar>
pub fn requires(self, n: &'ar str) -> ArgGroup<'n, 'ar>
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 name provided may be an argument, or group name
§Example
.requires("config")sourcepub fn requires_all(self, ns: Vec<&'ar str>) -> ArgGroup<'n, 'ar>
pub fn requires_all(self, ns: Vec<&'ar str>) -> ArgGroup<'n, 'ar>
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
§Example
.requires_all(vec!["config", "input"])sourcepub fn conflicts_with(self, n: &'ar str) -> ArgGroup<'n, 'ar>
pub fn conflicts_with(self, n: &'ar str) -> ArgGroup<'n, 'ar>
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 name provided may be an argument, or group name
§Example
.conflicts_with("config")sourcepub fn conflicts_with_all(self, ns: Vec<&'ar str>) -> ArgGroup<'n, 'ar>
pub fn conflicts_with_all(self, ns: Vec<&'ar str>) -> ArgGroup<'n, 'ar>
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
§Example
.conflicts_with_all(vec!["config", "input"])