pub struct StandardBuilder { /* private fields */ }
Expand description

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§

source§

impl StandardBuilder

source

pub fn new() -> StandardBuilder

Return a new builder for configuring the standard printer.

source

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.

source

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

source

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.

Set the configuration to use for hyperlinks output by this printer.

Regardless of the hyperlink format provided here, whether hyperlinks are 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 hyperlinks will ever be printed regardless of the format provided here.

This completely overrides any previous hyperlink format.

The default configuration results in not emitting any hyperlinks.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

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.

source

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

source

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

source

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

source

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

source

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§

source§

impl Clone for StandardBuilder

source§

fn clone(&self) -> StandardBuilder

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for StandardBuilder

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.