Struct grep_printer::SummaryBuilder

pub struct SummaryBuilder { /* fields omitted */ }

A builder for summary printer.

The builder permits configuring how the printer behaves. The summary printer has fewer configuration options than the standard printer because it aims to produce aggregate output about a single search (typically just one line) instead of output for each match.

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

Methods

impl SummaryBuilder

pub fn new() -> SummaryBuilder

Return a new builder for configuring the summary printer.

pub fn build<W: WriteColor>(&self, wtr: W) -> Summary<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) -> Summary<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 SummaryBuilder::build(termcolor::NoColor::new(wtr)).

pub fn kind(&mut self, kind: SummaryKind) -> &mut SummaryBuilder

Set the output mode for this printer.

The output mode controls how aggregate results of a search are printed.

By default, this printer uses the Count mode.

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

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 SummaryBuilder

Enable the gathering of various aggregate statistics.

When this is enabled (it's disabled by default), statistics will be gathered for all uses of Summary 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 SummarySink::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 example, in Quiet mode, a search can quit after finding the first match, but if stats is enabled, then the search will continue after the first match in order to compute statistics.

For a complete description of available statistics, see Stats.

Note that some output modes, such as CountMatches, automatically enable this option even if it has been explicitly disabled.

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

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 setting has no effect in PathWithMatch and PathWithoutMatch modes.

This is enabled by default.

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

Set the maximum amount of matches 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 exclude_zero(&mut self, yes: bool) -> &mut SummaryBuilder

Exclude count-related summary results with no matches.

When enabled and the mode is either Count or CountMatches, then results are not printed if no matches were found. Otherwise, every search prints a result with a possibly 0 number of matches.

pub fn separator_field(&mut self, sep: Vec<u8>) -> &mut SummaryBuilder

Set the separator used between fields for the Count and CountMatches modes.

By default, this is set to :.

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

Set the path separator used when printing file paths.

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 SummaryBuilder

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 or the configured field separator.

Trait Implementations

impl Clone for SummaryBuilder

fn clone(&self) -> SummaryBuilder

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for SummaryBuilder

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

Formats the value using the given formatter.