Struct rg::app::RGArg

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,
}

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.

hidden: bool

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

impl 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.

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.

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.

fn short(self, name: &'static str) -> RGArg

Set the short flag name.

This panics if this arg isn’t a switch or a flag.

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.

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.

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.

fn hidden(self) -> RGArg

Hide this flag from all documentation.

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.

fn alias(self, name: &'static str) -> RGArg

Add an alias to this argument.

Aliases are not show in the output of -h/–help.

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.

fn required_unless(self, names: &[&'static str]) -> RGArg

Sets this argument to a required argument, unless one of the given arguments is provided.

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.

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.

fn default_value(self, value: &'static str) -> RGArg

Sets the default value of this argument when not specified at runtime.

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.

fn number(self) -> RGArg

Indicate that any value given to this argument should be a number. If it’s not a number, then clap will report an error to the end user.

Trait Implementations

impl Clone for RGArg

fn clone(&self) -> RGArg

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.