Struct grep_printer::StandardBuilder

pub struct StandardBuilder { /* fields omitted */ }

A builder for the “standard” grep-like printer.

The builder permits configuring how the printer behaves. Configurable behavior includes, but is not limited to, limiting the number of matches, tweaking separators, executing pattern replacements, recording statistics and setting colors.

Some configuration options, such as the display of line numbers or contextual lines, are drawn directly from the grep_searcher::Searcher’s configuration.

Once a Standard printer is built, its configuration cannot be changed.

Implementations

impl StandardBuilder

pub fn new() -> StandardBuilder

Return a new builder for configuring the standard printer.

pub fn build<W: WriteColor>(&self, wtr: W) -> Standard<W>

Build a printer using any implementation of termcolor::WriteColor.

The implementation of WriteColor used here controls whether colors are used or not when colors have been configured using the color_specs method.

For maximum portability, callers should generally use either termcolor::StandardStream or termcolor::BufferedStandardStream where appropriate, which will automatically enable colors on Windows when possible.

However, callers may also provide an arbitrary writer using the termcolor::Ansi or termcolor::NoColor wrappers, which always enable colors via ANSI escapes or always disable colors, respectively.

As a convenience, callers may use build_no_color to automatically select the termcolor::NoColor wrapper to avoid needing to import from termcolor explicitly.

pub fn build_no_color<W: Write>(&self, wtr: W) -> Standard<NoColor<W>>

Build a printer from any implementation of io::Write and never emit any colors, regardless of the user color specification settings.

This is a convenience routine for StandardBuilder::build(termcolor::NoColor::new(wtr)).

pub fn color_specs(&mut self, specs: ColorSpecs) -> &mut StandardBuilder

Set the user color specifications to use for coloring in this printer.

A UserColorSpec can be constructed from a string in accordance with the color specification format. See the UserColorSpec type documentation for more details on the format. A ColorSpecs can then be generated from zero or more UserColorSpecs.

Regardless of the color specifications provided here, whether color is actually used or not is determined by the implementation of WriteColor provided to build. For example, if termcolor::NoColor is provided to build, then no color will ever be printed regardless of the color specifications provided here.

This completely overrides any previous color specifications. This does not add to any previously provided color specifications on this builder.

pub fn stats(&mut self, yes: bool) -> &mut StandardBuilder

Enable the gathering of various aggregate statistics.

When this is enabled (it’s disabled by default), statistics will be gathered for all uses of Standard printer returned by build, including but not limited to, the total number of matches, the total number of bytes searched and the total number of bytes printed.

Aggregate statistics can be accessed via the sink’s StandardSink::stats method.

When this is enabled, this printer may need to do extra work in order to compute certain statistics, which could cause the search to take longer.

For a complete description of available statistics, see Stats.

pub fn heading(&mut self, yes: bool) -> &mut StandardBuilder

Enable the use of “headings” in the printer.

When this is enabled, and if a file path has been given to the printer, then the file path will be printed once on its own line before showing any matches. If the heading is not the first thing emitted by the printer, then a line terminator is printed before the heading.

By default, this option is disabled. When disabled, the printer will not show any heading and will instead print the file path (if one is given) on the same line as each matching (or context) line.

pub fn path(&mut self, yes: bool) -> &mut StandardBuilder

When enabled, if a path was given to the printer, then it is shown in the output (either as a heading or as a prefix to each matching line). When disabled, then no paths are ever included in the output even when a path is provided to the printer.

This is enabled by default.

pub fn only_matching(&mut self, yes: bool) -> &mut StandardBuilder

Only print the specific matches instead of the entire line containing each match. Each match is printed on its own line. When multi line search is enabled, then matches spanning multiple lines are printed such that only the matching portions of each line are shown.

pub fn per_match(&mut self, yes: bool) -> &mut StandardBuilder

Print at least one line for every match.

This is similar to the only_matching option, except the entire line is printed for each match. This is typically useful in conjunction with the column option, which will show the starting column number for every match on every line.

When multi-line mode is enabled, each match is printed, including every line in the match. As with single line matches, if a line contains multiple matches (even if only partially), then that line is printed once for each match it participates in, assuming it’s the first line in that match. In multi-line mode, column numbers only indicate the start of a match. Subsequent lines in a multi-line match always have a column number of 1.

When a match contains multiple lines, enabling per_match_one_line will cause only the first line each in match to be printed.

pub fn per_match_one_line(&mut self, yes: bool) -> &mut StandardBuilder

Print at most one line per match when per_match is enabled.

By default, every line in each match found is printed when per_match is enabled. However, this is sometimes undesirable, e.g., when you only ever want one line per match.

This is only applicable when multi-line matching is enabled, since otherwise, matches are guaranteed to span one line.

This is disabled by default.

pub fn replacement(
    &mut self,
    replacement: Option<Vec<u8>>
) -> &mut StandardBuilder

Set the bytes that will be used to replace each occurrence of a match found.

The replacement bytes given may include references to capturing groups, which may either be in index form (e.g., $2) or can reference named capturing groups if present in the original pattern (e.g., $foo).

For documentation on the full format, please see the Capture trait’s interpolate method in the grep-printer crate.

pub fn max_columns(&mut self, limit: Option<u64>) -> &mut StandardBuilder

Set the maximum number of columns allowed for each line printed. A single column is heuristically defined as a single byte.

If a line is found which exceeds this maximum, then it is replaced with a message indicating that the line has been omitted.

The default is to not specify a limit, in which each matching or contextual line is printed regardless of how long it is.

pub fn max_columns_preview(&mut self, yes: bool) -> &mut StandardBuilder

When enabled, if a line is found to be over the configured maximum column limit (measured in terms of bytes), then a preview of the long line will be printed instead.

The preview will correspond to the first N grapheme clusters of the line, where N is the limit configured by max_columns.

If no limit is set, then enabling this has no effect.

This is disabled by default.

pub fn max_matches(&mut self, limit: Option<u64>) -> &mut StandardBuilder

Set the maximum amount of matching lines that are printed.

If multi line search is enabled and a match spans multiple lines, then that match is counted exactly once for the purposes of enforcing this limit, regardless of how many lines it spans.

pub fn column(&mut self, yes: bool) -> &mut StandardBuilder

Print the column number of the first match in a line.

This option is convenient for use with per_match which will print a line for every match along with the starting offset for that match.

Column numbers are computed in terms of bytes from the start of the line being printed.

This is disabled by default.

pub fn byte_offset(&mut self, yes: bool) -> &mut StandardBuilder

Print the absolute byte offset of the beginning of each line printed.

The absolute byte offset starts from the beginning of each search and is zero based.

If the only_matching option is set, then this will print the absolute byte offset of the beginning of each match.

pub fn trim_ascii(&mut self, yes: bool) -> &mut StandardBuilder

When enabled, all lines will have prefix ASCII whitespace trimmed before being written.

This is disabled by default.

pub fn separator_search(&mut self, sep: Option<Vec<u8>>) -> &mut StandardBuilder

Set the separator used between sets of search results.

When this is set, then it will be printed on its own line immediately before the results for a single search if and only if a previous search had already printed results. In effect, this permits showing a divider between sets of search results that does not appear at the beginning or end of all search results.

To reproduce the classic grep format, this is typically set to -- (the same as the context separator) if and only if contextual lines have been requested, but disabled otherwise.

By default, this is disabled.

pub fn separator_context(
    &mut self,
    sep: Option<Vec<u8>>
) -> &mut StandardBuilder

Set the separator used between discontiguous runs of search context, but only when the searcher is configured to report contextual lines.

The separator is always printed on its own line, even if it’s empty.

If no separator is set, then nothing is printed when a context break occurs.

By default, this is set to --.

pub fn separator_field_match(&mut self, sep: Vec<u8>) -> &mut StandardBuilder

Set the separator used between fields emitted for matching lines.

For example, when the searcher has line numbers enabled, this printer will print the line number before each matching line. The bytes given here will be written after the line number but before the matching line.

By default, this is set to :.

pub fn separator_field_context(&mut self, sep: Vec<u8>) -> &mut StandardBuilder

Set the separator used between fields emitted for context lines.

For example, when the searcher has line numbers enabled, this printer will print the line number before each context line. The bytes given here will be written after the line number but before the context line.

By default, this is set to -.

pub fn separator_path(&mut self, sep: Option<u8>) -> &mut StandardBuilder

Set the path separator used when printing file paths.

When a printer is configured with a file path, and when a match is found, that file path will be printed (either as a heading or as a prefix to each matching or contextual line, depending on other configuration settings). Typically, printing is done by emitting the file path as is. However, this setting provides the ability to use a different path separator from what the current environment has configured.

A typical use for this option is to permit cygwin users on Windows to set the path separator to / instead of using the system default of \.

pub fn path_terminator(
    &mut self,
    terminator: Option<u8>
) -> &mut StandardBuilder

Set the path terminator used.

The path terminator is a byte that is printed after every file path emitted by this printer.

If no path terminator is set (the default), then paths are terminated by either new lines (for when heading is enabled) or the match or context field separators (e.g., : or -).

Trait Implementations

impl Clone for StandardBuilder

fn clone(&self) -> StandardBuilder

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for StandardBuilder

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

Formats the value using the given formatter.