Struct rg::args::ArgMatches

struct ArgMatches(ArgMatches<'static>);

ArgMatches wraps clap::ArgMatches and provides semantic meaning to the parsed arguments.

Tuple Fields

0: ArgMatches<'static>

Implementations

impl ArgMatches

fn new(clap_matches: ArgMatches<'static>) -> ArgMatches

Create an ArgMatches from clap’s parse result.

fn reconfigure(self) -> Result<ArgMatches, Box<dyn Error>>

Run clap and return the matches using a config file if present. If clap determines a problem with the user provided arguments (or if –help or –version are given), then an error/usage/version will be printed and the process will exit.

If there are no additional arguments from the environment (e.g., a config file), then the given matches are returned as is.

fn to_args(self) -> Result<Args, Box<dyn Error>>

Convert the result of parsing CLI arguments into ripgrep’s higher level configuration structure.

impl ArgMatches

High level routines for converting command line arguments into various data structures used by ripgrep.

Methods are sorted alphabetically.

fn matcher(&self, patterns: &[String]) -> Result<PatternMatcher, Box<dyn Error>>

Return the matcher that should be used for searching.

If there was a problem building the matcher (e.g., a syntax error), then this returns an error.

fn matcher_engine( &self, engine: &str, patterns: &[String] ) -> Result<PatternMatcher, Box<dyn Error>>

Return the matcher that should be used for searching using engine as the engine for the patterns.

If there was a problem building the matcher (e.g., a syntax error), then this returns an error.

fn matcher_rust( &self, patterns: &[String] ) -> Result<RustRegexMatcher, Box<dyn Error>>

Build a matcher using Rust’s regex engine.

If there was a problem building the matcher (such as a regex syntax error), then an error is returned.

fn printer_json<W: Write>(&self, wtr: W) -> Result<JSON<W>, Box<dyn Error>>

Build a JSON printer that writes results to the given writer.

fn printer_standard<W: WriteColor>( &self, paths: &[PathBuf], wtr: W, separator_search: bool ) -> Result<Standard<W>, Box<dyn Error>>

Build a Standard printer that writes results to the given writer.

The given paths are used to configure aspects of the printer.

If separator_search is true, then the returned printer will assume the responsibility of printing a separator between each set of search results, when appropriate (e.g., when contexts are enabled). When it’s set to false, the caller is responsible for handling separators.

In practice, we want the printer to handle it in the single threaded case but not in the multi-threaded case.

fn printer_summary<W: WriteColor>( &self, paths: &[PathBuf], wtr: W ) -> Result<Summary<W>, Box<dyn Error>>

Build a Summary printer that writes results to the given writer.

The given paths are used to configure aspects of the printer.

This panics if the output format is not OutputKind::Summary.

fn searcher(&self, paths: &[PathBuf]) -> Result<Searcher, Box<dyn Error>>

Build a searcher from the command line parameters.

fn walker_builder( &self, paths: &[PathBuf], threads: usize ) -> Result<WalkBuilder, Box<dyn Error>>

Return a builder for recursively traversing a directory while respecting ignore rules.

If there was a problem parsing the CLI arguments necessary for constructing the builder, then this returns an error.

impl ArgMatches

Mid level routines for converting command line arguments into various types of data structures.

Methods are sorted alphabetically.

fn binary_detection_implicit(&self) -> BinaryDetection

Returns the form of binary detection to perform on files that are implicitly searched via recursive directory traversal.

fn binary_detection_explicit(&self) -> BinaryDetection

Returns the form of binary detection to perform on files that are explicitly searched via the user invoking ripgrep on a particular file or files or stdin.

In general, this should never be BinaryDetection::quit, since that acts as a filter (but quitting immediately once a NUL byte is seen), and we should never filter out files that the user wants to explicitly search.

fn can_never_match(&self, patterns: &[String]) -> bool

Returns true if the command line configuration implies that a match can never be shown.

fn case_insensitive(&self) -> bool

Returns true if and only if case should be ignore.

If –case-sensitive is present, then case is never ignored, even if –ignore-case is present.

fn case_smart(&self) -> bool

Returns true if and only if smart case has been enabled.

If either –ignore-case of –case-sensitive are present, then smart case is disabled.

fn color_choice(&self) -> ColorChoice

Returns the user’s color choice based on command line parameters and environment.

fn color_specs(&self) -> Result<ColorSpecs, Box<dyn Error>>

Returns the color specifications given by the user on the CLI.

If the was a problem parsing any of the provided specs, then an error is returned.

fn column(&self) -> bool

Returns true if and only if column numbers should be shown.

fn contexts(&self) -> Result<(usize, usize), Box<dyn Error>>

Returns the before and after contexts from the command line.

If a context setting was absent, then 0 is returned.

If there was a problem parsing the values from the user as an integer, then an error is returned.

fn context_separator(&self) -> Option<Vec<u8>>

Returns the unescaped context separator in UTF-8 bytes.

If one was not provided, the default -- is returned. If –no-context-separator is passed, None is returned.

fn counts(&self) -> (bool, bool)

Returns whether the -c/–count or the –count-matches flags were passed from the command line.

If –count-matches and –invert-match were passed in, behave as if –count and –invert-match were passed in (i.e. rg will count inverted matches as per existing behavior).

fn dfa_size_limit(&self) -> Result<Option<usize>, Box<dyn Error>>

Parse the dfa-size-limit argument option into a byte count.

fn encoding(&self) -> Result<EncodingMode, Box<dyn Error>>

Returns the encoding mode to use.

This only returns an encoding if one is explicitly specified. Otherwise if set to automatic, the Searcher will do BOM sniffing for UTF-16 and transcode seamlessly. If disabled, no BOM sniffing nor transcoding will occur.

fn file_separator(&self) -> Result<Option<Vec<u8>>, Box<dyn Error>>

Return the file separator to use based on the CLI configuration.

fn heading(&self) -> bool

Returns true if and only if matches should be grouped with file name headings.

fn hidden(&self) -> bool

Returns true if and only if hidden files/directories should be searched.

fn hyperlink_config(&self) -> Result<HyperlinkConfig, Box<dyn Error>>

Returns the hyperlink pattern to use. A default pattern suitable for the current system is used if the value is not set.

If an invalid pattern is provided, then an error is returned.

fn ignore_file_case_insensitive(&self) -> bool

Returns true if ignore files should be processed case insensitively.

fn ignore_paths(&self) -> Vec<PathBuf>

Return all of the ignore file paths given on the command line.

fn is_one_search(&self, paths: &[PathBuf]) -> bool

Returns true if and only if ripgrep is invoked in a way where it knows it search exactly one thing.

fn is_only_stdin(&self, paths: &[PathBuf]) -> bool

Returns true if and only if we’re only searching a single thing and that thing is stdin.

fn line_number(&self, paths: &[PathBuf]) -> bool

Returns true if and only if we should show line numbers.

fn max_columns(&self) -> Result<Option<u64>, Box<dyn Error>>

The maximum number of columns allowed on each line.

If 0 is provided, then this returns None.

fn max_columns_preview(&self) -> bool

Returns true if and only if a preview should be shown for lines that exceed the maximum column limit.

fn max_count(&self) -> Result<Option<u64>, Box<dyn Error>>

The maximum number of matches permitted.

fn max_file_size(&self) -> Result<Option<u64>, Box<dyn Error>>

Parses the max-filesize argument option into a byte count.

fn mmap_choice(&self, paths: &[PathBuf]) -> MmapChoice

Returns whether we should attempt to use memory maps or not.

fn no_ignore(&self) -> bool

Returns true if ignore files should be ignored.

fn no_ignore_dot(&self) -> bool

Returns true if .ignore files should be ignored.

fn no_ignore_exclude(&self) -> bool

Returns true if local exclude (ignore) files should be ignored.

fn no_ignore_files(&self) -> bool

Returns true if explicitly given ignore files should be ignored.

fn no_ignore_global(&self) -> bool

Returns true if global ignore files should be ignored.

fn no_ignore_parent(&self) -> bool

Returns true if parent ignore files should be ignored.

fn no_ignore_vcs(&self) -> bool

Returns true if VCS ignore files should be ignored.

fn output_kind(&self) -> OutputKind

Determine the type of output we should produce.

fn overrides(&self) -> Result<Override, Box<dyn Error>>

Builds the set of glob overrides from the command line flags.

fn paths(&self) -> Vec<PathBuf>

Return all file paths that ripgrep should search.

If no paths were given, then this returns an empty list.

fn path_default(&self) -> PathBuf

Return the default path that ripgrep should search. This should only be used when ripgrep is not otherwise given at least one file path as a positional argument.

fn path_separator(&self) -> Result<Option<u8>, Box<dyn Error>>

Returns the unescaped path separator as a single byte, if one exists.

If the provided path separator is more than a single byte, then an error is returned.

fn path_terminator(&self) -> Option<u8>

Returns the byte that should be used to terminate paths.

Typically, this is only set to \x00 when the –null flag is provided, and None otherwise.

fn field_context_separator(&self) -> Vec<u8>

Returns the unescaped field context separator. If one wasn’t specified, then ‘-’ is used as the default.

fn field_match_separator(&self) -> Vec<u8>

Returns the unescaped field match separator. If one wasn’t specified, then ‘:’ is used as the default.

fn patterns(&self) -> Result<Vec<String>, Box<dyn Error>>

Get a sequence of all available patterns from the command line. This includes reading the -e/–regexp and -f/–file flags.

If any pattern is invalid UTF-8, then an error is returned.

fn pattern_from_os_str(&self, pat: &OsStr) -> Result<String, Box<dyn Error>>

Converts an OsStr pattern to a String pattern. The pattern is escaped if -F/–fixed-strings is set.

If the pattern is not valid UTF-8, then an error is returned.

fn pattern_from_str(&self, pat: &str) -> String

Converts a &str pattern to a String pattern. The pattern is escaped if -F/–fixed-strings is set.

fn pattern_from_string(&self, pat: String) -> String

Applies additional processing on the given pattern if necessary (such as escaping meta characters or turning it into a line regex).

fn preprocessor(&self) -> Option<PathBuf>

Returns the preprocessor command if one was specified.

fn preprocessor_globs(&self) -> Result<Override, Box<dyn Error>>

Builds the set of globs for filtering files to apply to the –pre flag. If no –pre-globs are available, then this always returns an empty set of globs.

fn regex_size_limit(&self) -> Result<Option<usize>, Box<dyn Error>>

Parse the regex-size-limit argument option into a byte count.

fn replacement(&self) -> Option<Vec<u8>>

Returns the replacement string as UTF-8 bytes if it exists.

fn sort_by(&self) -> Result<SortBy, Box<dyn Error>>

Returns the sorting criteria based on command line parameters.

fn stats(&self) -> bool

Returns true if and only if aggregate statistics for a search should be tracked.

Generally, this is only enabled when explicitly requested by in the command line arguments via the –stats flag, but this can also be enabled implicitly via the output format, e.g., for JSON Lines.

fn summary_kind(&self) -> Option<SummaryKind>

When the output format is Summary, this returns the type of summary output to show.

This returns None if the output format is not Summary.

fn threads(&self) -> Result<usize, Box<dyn Error>>

Return the number of threads that should be used for parallelism.

fn types(&self) -> Result<Types, Box<dyn Error>>

Builds a file type matcher from the command line flags.

fn unrestricted_count(&self) -> u64

Returns the number of times the unrestricted flag is provided.

fn unicode(&self) -> bool

Returns true if and only if Unicode mode should be enabled.

fn with_filename(&self, paths: &[PathBuf]) -> bool

Returns true if and only if file names containing each match should be emitted.

impl ArgMatches

Lower level generic helper methods for teasing values out of clap.

fn values_of_lossy_vec(&self, name: &str) -> Vec<String>

Like values_of_lossy, but returns an empty vec if the flag is not present.

fn usize_of_nonzero(&self, name: &str) -> Result<Option<usize>, Box<dyn Error>>

Safely reads an arg value with the given name, and if it’s present, tries to parse it as a usize value.

If the number is zero, then it is considered absent and None is returned.

fn usize_of(&self, name: &str) -> Result<Option<usize>, Box<dyn Error>>

Safely reads an arg value with the given name, and if it’s present, tries to parse it as a usize value.

fn parse_human_readable_size( &self, arg_name: &str ) -> Result<Option<u64>, Box<dyn Error>>

Parses an argument of the form [0-9]+(KMG)?.

If the aforementioned format is not recognized, then this returns an error.

impl ArgMatches

The following methods mostly dispatch to the underlying clap methods directly. Methods that would otherwise get a single value will fetch all values and return the last one. (Clap returns the first one.) We only define the ones we need.

fn is_present(&self, name: &str) -> bool

fn occurrences_of(&self, name: &str) -> u64

fn value_of_lossy(&self, name: &str) -> Option<String>

fn values_of_lossy(&self, name: &str) -> Option<Vec<String>>

fn value_of_os(&self, name: &str) -> Option<&OsStr>

fn values_of_os(&self, name: &str) -> Option<OsValues<'_>>

Trait Implementations

impl Clone for ArgMatches

fn clone(&self) -> ArgMatches

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ArgMatches

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.