pub struct RGArg {
claparg: Arg<'static, 'static>,
pub name: &'static str,
pub doc_short: &'static str,
pub doc_long: &'static str,
pub hidden: bool,
pub kind: RGArgKind,
}
Expand description
RGArg is a light wrapper around a clap::Arg and also contains some metadata about the underlying Arg so that it can be inspected for other purposes (e.g., hopefully generating a man page).
Note that this type is purposely overly constrained to ripgrep’s particular use of clap.
Fields§
§claparg: Arg<'static, 'static>
The underlying clap argument.
name: &'static str
The name of this argument. This is always present and is the name used in the code to find the value of an argument at runtime.
doc_short: &'static str
A short documentation string describing this argument. This string should fit on a single line and be a complete sentence.
This is shown in the -h
output.
doc_long: &'static str
A longer documentation string describing this argument. This usually
starts with the contents of doc_short
. This is also usually many
lines, potentially paragraphs, and may contain examples and additional
prose.
This is shown in the --help
output.
Whether this flag is hidden or not.
This is typically used for uncommon flags that only serve to override other flags. For example, –no-ignore is a prominent flag that disables ripgrep’s gitignore functionality, but –ignore re-enables it. Since gitignore support is enabled by default, use of the –ignore flag is somewhat niche and relegated to special cases when users make use of configuration files to set defaults.
Generally, these flags should be documented in the documentation for the flag they override.
kind: RGArgKind
The type of this argument.
Implementations§
source§impl RGArg
impl RGArg
sourcefn positional(name: &'static str, value_name: &'static str) -> RGArg
fn positional(name: &'static str, value_name: &'static str) -> RGArg
Create a positional argument.
The long_name
parameter is the name of the argument, e.g., pattern
.
The value_name
parameter is a name that describes the type of
argument this flag accepts. It should be in uppercase, e.g., PATH or
PATTERN.
sourcefn switch(long_name: &'static str) -> RGArg
fn switch(long_name: &'static str) -> RGArg
Create a boolean switch.
The long_name
parameter is the name of the flag, e.g., --long-name
.
All switches may be repeated an arbitrary number of times. If a switch is truly boolean, that consumers of clap’s configuration should only check whether the flag is present or not. Otherwise, consumers may inspect the number of times the switch is used.
sourcefn flag(long_name: &'static str, value_name: &'static str) -> RGArg
fn flag(long_name: &'static str, value_name: &'static str) -> RGArg
Create a flag. A flag always accepts exactly one argument.
The long_name
parameter is the name of the flag, e.g., --long-name
.
The value_name
parameter is a name that describes the type of
argument this flag accepts. It should be in uppercase, e.g., PATH or
PATTERN.
All flags may be repeated an arbitrary number of times. If a flag has only one logical value, that consumers of clap’s configuration should only use the last value.
sourcefn short(self, name: &'static str) -> RGArg
fn short(self, name: &'static str) -> RGArg
Set the short flag name.
This panics if this arg isn’t a switch or a flag.
sourcefn help(self, text: &'static str) -> RGArg
fn help(self, text: &'static str) -> RGArg
Set the “short” help text.
This should be a single line. It is shown in the -h
output.
sourcefn long_help(self, text: &'static str) -> RGArg
fn long_help(self, text: &'static str) -> RGArg
Set the “long” help text.
This should be at least a single line, usually longer. It is shown in
the --help
output.
sourcefn multiple(self) -> RGArg
fn multiple(self) -> RGArg
Enable this argument to accept multiple values.
Note that while switches and flags can always be repeated an arbitrary number of times, this particular method enables the flag to be logically repeated where each occurrence of the flag may have significance. That is, when this is disabled, then a switch is either present or not and a flag has exactly one value (the last one given). When this is enabled, then a switch has a count corresponding to the number of times it is used and a flag’s value is a list of all values given.
For the most part, this distinction is resolved by consumers of clap’s configuration.
Hide this flag from all documentation.
sourcefn possible_values(self, values: &[&'static str]) -> RGArg
fn possible_values(self, values: &[&'static str]) -> RGArg
Set the possible values for this argument. If this argument is not a flag, then this panics.
If the end user provides any value other than what is given here, then clap will report an error to the user.
Note that this will suppress clap’s automatic output of possible values when using -h/–help, so users of this method should provide appropriate documentation for the choices in the “long” help text.
sourcefn alias(self, name: &'static str) -> RGArg
fn alias(self, name: &'static str) -> RGArg
Add an alias to this argument.
Aliases are not show in the output of -h/–help.
sourcefn allow_leading_hyphen(self) -> RGArg
fn allow_leading_hyphen(self) -> RGArg
Permit this flag to have values that begin with a hyphen.
This panics if this arg is not a flag.
sourcefn required_unless(self, names: &[&'static str]) -> RGArg
fn required_unless(self, names: &[&'static str]) -> RGArg
Sets this argument to a required argument, unless one of the given arguments is provided.
sourcefn conflicts(self, names: &[&'static str]) -> RGArg
fn conflicts(self, names: &[&'static str]) -> RGArg
Sets conflicting arguments. That is, if this argument is used whenever any of the other arguments given here are used, then clap will report an error.
sourcefn overrides(self, name: &'static str) -> RGArg
fn overrides(self, name: &'static str) -> RGArg
Sets an overriding argument. That is, if this argument and the given argument are both provided by an end user, then the “last” one will win. ripgrep will behave as if any previous instantiations did not happen.
sourcefn default_value(self, value: &'static str) -> RGArg
fn default_value(self, value: &'static str) -> RGArg
Sets the default value of this argument when not specified at runtime.
sourcefn default_value_if(self, value: &'static str, arg_name: &'static str) -> RGArg
fn default_value_if(self, value: &'static str, arg_name: &'static str) -> RGArg
Sets the default value of this argument if and only if the argument given is present.