rust/ripgrep
1
0
Fork 0
mirror of https://github.com/BurntSushi/ripgrep.git synced 2025-01-03 05:10:12 +02:00
Code Issues Releases Activity

crates: remove hard-coded links

Browse Source 
And use rustdoc's native intra-crate links. So much nicer.
This commit is contained in:
Andrew Gallant 2023-09-25 18:24:08 -04:00
parent 82d3183a04
commit 3ad7a0d95e
14 changed files with 147 additions and 206 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
crates/cli/src/escape.rs
View File

@ -8,7 +8,7 @@ use bstr::{ByteSlice, ByteVec};
/// converts the non-printable subset of ASCII in addition to invalid UTF-8
/// bytes to hexadecimal escape sequences. Everything else is left as is.
///
/// The dual of this routine is [`unescape`](fn.unescape.html).
/// The dual of this routine is [`unescape`].
///
/// # Example
///
@ -29,7 +29,7 @@ pub fn escape(bytes: &[u8]) -> String {
/// Escapes an OS string into a human readable string.
///
/// This is like [`escape`](fn.escape.html), but accepts an OS string.
/// This is like [`escape`], but accepts an OS string.
pub fn escape_os(string: &OsStr) -> String {
escape(Vec::from_os_str_lossy(string).as_bytes())
}
@ -48,7 +48,7 @@ pub fn escape_os(string: &OsStr) -> String {
/// capable of specifying arbitrary bytes or otherwise make it easier to
/// specify non-printable characters.
///
/// The dual of this routine is [`escape`](fn.escape.html).
/// The dual of this routine is [`escape`].
///
/// # Example
///
@ -70,7 +70,7 @@ pub fn unescape(s: &str) -> Vec<u8> {
/// Unescapes an OS string.
///
/// This is like [`unescape`](fn.unescape.html), but accepts an OS string.
/// This is like [`unescape`], but accepts an OS string.
///
/// Note that this first lossily decodes the given OS string as UTF-8. That
/// is, an escaped string (the thing given) should be valid UTF-8.

107
crates/cli/src/lib.rs
View File

@ -20,22 +20,17 @@ recursively search the current working directory for occurrences of `foo`, but
# Coloring and buffering
The
[`stdout`](fn.stdout.html),
[`stdout_buffered_block`](fn.stdout_buffered_block.html)
and
[`stdout_buffered_line`](fn.stdout_buffered_line.html)
routines are alternative constructors for
[`StandardStream`](struct.StandardStream.html).
A `StandardStream` implements `termcolor::WriteColor`, which provides a way
to emit colors to terminals. Its key use is the encapsulation of buffering
style. Namely, `stdout` will return a line buffered `StandardStream` if and
only if stdout is connected to a tty, and will otherwise return a block
buffered `StandardStream`. Line buffering is important for use with a tty
because it typically decreases the latency at which the end user sees output.
Block buffering is used otherwise because it is faster, and redirecting stdout
to a file typically doesn't benefit from the decreased latency that line
buffering provides.
The [`stdout`], [`stdout_buffered_block`] and [`stdout_buffered_line`] routines
are alternative constructors for [`StandardStream`]. A `StandardStream`
implements `termcolor::WriteColor`, which provides a way to emit colors to
terminals. Its key use is the encapsulation of buffering style. Namely,
`stdout` will return a line buffered `StandardStream` if and only if
stdout is connected to a tty, and will otherwise return a block buffered
`StandardStream`. Line buffering is important for use with a tty because it
typically decreases the latency at which the end user sees output. Block
buffering is used otherwise because it is faster, and redirecting stdout to a
file typically doesn't benefit from the decreased latency that line buffering
provides.
The `stdout_buffered_block` and `stdout_buffered_line` can be used to
explicitly set the buffering strategy regardless of whether stdout is connected
@ -44,17 +39,12 @@ to a tty or not.
# Escaping
The
[`escape`](fn.escape.html),
[`escape_os`](fn.escape_os.html),
[`unescape`](fn.unescape.html)
and
[`unescape_os`](fn.unescape_os.html)
routines provide a user friendly way of dealing with UTF-8 encoded strings that
can express arbitrary bytes. For example, you might want to accept a string
containing arbitrary bytes as a command line argument, but most interactive
shells make such strings difficult to type. Instead, we can ask users to use
escape sequences.
The [`escape`](crate::escape()), [`escape_os`], [`unescape`] and
[`unescape_os`] routines provide a user friendly way of dealing with UTF-8
encoded strings that can express arbitrary bytes. For example, you might want
to accept a string containing arbitrary bytes as a command line argument, but
most interactive shells make such strings difficult to type. Instead, we can
ask users to use escape sequences.
For example, `a\xFFz` is itself a valid UTF-8 string corresponding to the
following bytes:
@ -87,44 +77,36 @@ makes it easy to show user friendly error messages involving arbitrary bytes.
# Building patterns
Typically, regular expression patterns must be valid UTF-8. However, command
line arguments aren't guaranteed to be valid UTF-8. Unfortunately, the
standard library's UTF-8 conversion functions from `OsStr`s do not provide
good error messages. However, the
[`pattern_from_bytes`](fn.pattern_from_bytes.html)
and
[`pattern_from_os`](fn.pattern_from_os.html)
do, including reporting exactly where the first invalid UTF-8 byte is seen.
line arguments aren't guaranteed to be valid UTF-8. Unfortunately, the standard
library's UTF-8 conversion functions from `OsStr`s do not provide good error
messages. However, the [`pattern_from_bytes`] and [`pattern_from_os`] do,
including reporting exactly where the first invalid UTF-8 byte is seen.
Additionally, it can be useful to read patterns from a file while reporting
good error messages that include line numbers. The
[`patterns_from_path`](fn.patterns_from_path.html),
[`patterns_from_reader`](fn.patterns_from_reader.html)
and
[`patterns_from_stdin`](fn.patterns_from_stdin.html)
routines do just that. If any pattern is found that is invalid UTF-8, then the
error includes the file path (if available) along with the line number and the
byte offset at which the first invalid UTF-8 byte was observed.
good error messages that include line numbers. The [`patterns_from_path`],
[`patterns_from_reader`] and [`patterns_from_stdin`] routines do just that. If
any pattern is found that is invalid UTF-8, then the error includes the file
path (if available) along with the line number and the byte offset at which the
first invalid UTF-8 byte was observed.
# Read process output
Sometimes a command line application needs to execute other processes and read
its stdout in a streaming fashion. The
[`CommandReader`](struct.CommandReader.html)
provides this functionality with an explicit goal of improving failure modes.
In particular, if the process exits with an error code, then stderr is read
and converted into a normal Rust error to show to end users. This makes the
underlying failure modes explicit and gives more information to end users for
debugging the problem.
Sometimes a command line application needs to execute other processes and
read its stdout in a streaming fashion. The [`CommandReader`] provides this
functionality with an explicit goal of improving failure modes. In particular,
if the process exits with an error code, then stderr is read and converted into
a normal Rust error to show to end users. This makes the underlying failure
modes explicit and gives more information to end users for debugging the
problem.
As a special case,
[`DecompressionReader`](struct.DecompressionReader.html)
provides a way to decompress arbitrary files by matching their file extensions
up with corresponding decompression programs (such as `gzip` and `xz`). This
is useful as a means of performing simplistic decompression in a portable
manner without binding to specific compression libraries. This does come with
some overhead though, so if you need to decompress lots of small files, this
may not be an appropriate convenience to use.
As a special case, [`DecompressionReader`] provides a way to decompress
arbitrary files by matching their file extensions up with corresponding
decompression programs (such as `gzip` and `xz`). This is useful as a means of
performing simplistic decompression in a portable manner without binding to
specific compression libraries. This does come with some overhead though, so
if you need to decompress lots of small files, this may not be an appropriate
convenience to use.
Each reader has a corresponding builder for additional configuration, such as
whether to read stderr asynchronously in order to avoid deadlock (which is
@ -133,11 +115,10 @@ enabled by default).
# Miscellaneous parsing
The
[`parse_human_readable_size`](fn.parse_human_readable_size.html)
routine parses strings like `2M` and converts them to the corresponding number
of bytes (`2 * 1<<20` in this case). If an invalid size is found, then a good
error message is crafted that typically tells the user how to fix the problem.
The [`parse_human_readable_size`] routine parses strings like `2M` and converts
them to the corresponding number of bytes (`2 * 1<<20` in this case). If an
invalid size is found, then a good error message is crafted that typically
tells the user how to fix the problem.
*/
#![deny(missing_docs)]

3
crates/cli/src/process.rs
View File

@ -191,8 +191,7 @@ impl CommandReader {
/// returned.
///
/// If the caller requires additional configuration for the reader
/// returned, then use
/// [`CommandReaderBuilder`](struct.CommandReaderBuilder.html).
/// returned, then use [`CommandReaderBuilder`].
pub fn new(
cmd: &mut process::Command,
) -> Result<CommandReader, CommandError> {

12
crates/cli/src/wtr.rs
View File

@ -33,10 +33,8 @@ pub fn stdout(color_choice: termcolor::ColorChoice) -> StandardStream {
/// users see output as soon as it's written. The downside of this approach
/// is that it can be slower, especially when there is a lot of output.
///
/// You might consider using
/// [`stdout`](fn.stdout.html)
/// instead, which chooses the buffering strategy automatically based on
/// whether stdout is connected to a tty.
/// You might consider using [`stdout`] instead, which chooses the buffering
/// strategy automatically based on whether stdout is connected to a tty.
pub fn stdout_buffered_line(
color_choice: termcolor::ColorChoice,
) -> StandardStream {
@ -50,10 +48,8 @@ pub fn stdout_buffered_line(
/// the cost of writing data. The downside of this approach is that it can
/// increase the latency of display output when writing to a tty.
///
/// You might consider using
/// [`stdout`](fn.stdout.html)
/// instead, which chooses the buffering strategy automatically based on
/// whether stdout is connected to a tty.
/// You might consider using [`stdout`] instead, which chooses the buffering
/// strategy automatically based on whether stdout is connected to a tty.
pub fn stdout_buffered_block(
color_choice: termcolor::ColorChoice,
) -> StandardStream {

17
crates/ignore/src/walk.rs
View File

@ -38,9 +38,7 @@ impl DirEntry {
}
/// The full path that this entry represents.
/// Analogous to [`path`], but moves ownership of the path.
///
/// [`path`]: struct.DirEntry.html#method.path
/// Analogous to [`DirEntry::path`], but moves ownership of the path.
pub fn into_path(self) -> PathBuf {
self.dent.into_path()
}
@ -1127,10 +1125,10 @@ impl WalkState {
}
}
/// A builder for constructing a visitor when using
/// [`WalkParallel::visit`](struct.WalkParallel.html#method.visit). The builder
/// will be called for each thread started by `WalkParallel`. The visitor
/// returned from each builder is then called for every directory entry.
/// A builder for constructing a visitor when using [`WalkParallel::visit`].
/// The builder will be called for each thread started by `WalkParallel`. The
/// visitor returned from each builder is then called for every directory
/// entry.
pub trait ParallelVisitorBuilder<'s> {
/// Create per-thread `ParallelVisitor`s for `WalkParallel`.
fn build(&mut self) -> Box<dyn ParallelVisitor + 's>;
@ -1147,9 +1145,8 @@ impl<'a, 's, P: ParallelVisitorBuilder<'s>> ParallelVisitorBuilder<'s>
/// Receives files and directories for the current thread.
///
/// Setup for the traversal can be implemented as part of
/// [`ParallelVisitorBuilder::build`](trait.ParallelVisitorBuilder.html#tymethod.build).
/// Teardown when traversal finishes can be implemented by implementing the
/// `Drop` trait on your traversal type.
/// [`ParallelVisitorBuilder::build`]. Teardown when traversal finishes can be
/// implemented by implementing the `Drop` trait on your traversal type.
pub trait ParallelVisitor: Send {
/// Receives files and directories for the current thread. This is called
/// once for every directory entry visited by traversal.

22
crates/matcher/src/lib.rs
View File

@ -6,12 +6,10 @@ the search routines provided by the
[`grep-searcher`](https://docs.rs/grep-searcher)
crate.
The primary thing provided by this crate is the
[`Matcher`](trait.Matcher.html)
trait. The trait defines an abstract interface for text search. It is robust
enough to support everything from basic substring search all the way to
arbitrarily complex regular expression implementations without sacrificing
performance.
The primary thing provided by this crate is the [`Matcher`] trait. The trait
defines an abstract interface for text search. It is robust enough to support
everything from basic substring search all the way to arbitrarily complex
regular expression implementations without sacrificing performance.
A key design decision made in this crate is the use of *internal iteration*,
or otherwise known as the "push" model of searching. In this paradigm,
@ -513,13 +511,11 @@ pub enum LineMatchKind {
/// A matcher defines an interface for regular expression implementations.
///
/// While this trait is large, there are only two required methods that
/// implementors must provide: `find_at` and `new_captures`. If captures
/// aren't supported by your implementation, then `new_captures` can be
/// implemented with
/// [`NoCaptures`](struct.NoCaptures.html). If your implementation does support
/// capture groups, then you should also implement the other capture related
/// methods, as dictated by the documentation. Crucially, this includes
/// `captures_at`.
/// implementors must provide: `find_at` and `new_captures`. If captures aren't
/// supported by your implementation, then `new_captures` can be implemented
/// with [`NoCaptures`]. If your implementation does support capture groups,
/// then you should also implement the other capture related methods, as
/// dictated by the documentation. Crucially, this includes `captures_at`.
///
/// The rest of the methods on this trait provide default implementations on
/// top of `find_at` and `new_captures`. It is not uncommon for implementations

2
crates/printer/src/color.rs
View File

@ -83,7 +83,7 @@ impl std::fmt::Display for ColorError {
/// This set of color specifications represents the various color types that
/// are supported by the printers in this crate. A set of color specifications
/// can be created from a sequence of
/// [`UserColorSpec`s](struct.UserColorSpec.html).
/// [`UserColorSpec`]s.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct ColorSpecs {
path: ColorSpec,

11
crates/printer/src/json.rs
View File

@ -549,14 +549,13 @@ impl<W> JSON<W> {
/// This type is generic over a few type parameters:
///
/// * `'p` refers to the lifetime of the file path, if one is provided. When
/// no file path is given, then this is `'static`.
/// * `'s` refers to the lifetime of the
/// [`JSON`](struct.JSON.html)
/// printer that this type borrows.
/// no file path is given, then this is `'static`.
/// * `'s` refers to the lifetime of the [`JSON`] printer that this type
/// borrows.
/// * `M` refers to the type of matcher used by
/// `grep_searcher::Searcher` that is reporting results to this sink.
/// `grep_searcher::Searcher` that is reporting results to this sink.
/// * `W` refers to the underlying writer that this printer is writing its
/// output to.
/// output to.
#[derive(Debug)]
pub struct JSONSink<'p, 's, M: Matcher, W> {
matcher: M,

26
crates/printer/src/lib.rs
View File

@ -5,22 +5,20 @@ crate.
# Brief overview
The [`Standard`](struct.Standard.html) printer shows results in a human
readable format, and is modeled after the formats used by standard grep-like
tools. Features include, but are not limited to, cross platform terminal
coloring, search & replace, multi-line result handling and reporting summary
statistics.
The [`Standard`] printer shows results in a human readable format, and is
modeled after the formats used by standard grep-like tools. Features include,
but are not limited to, cross platform terminal coloring, search & replace,
multi-line result handling and reporting summary statistics.
The [`JSON`](struct.JSON.html) printer shows results in a machine readable
format. To facilitate a stream of search results, the format uses
[JSON Lines](https://jsonlines.org/)
by emitting a series of messages as search results are found.
The [`JSON`] printer shows results in a machine readable format.
To facilitate a stream of search results, the format uses [JSON
Lines](https://jsonlines.org/) by emitting a series of messages as search
results are found.
The [`Summary`](struct.Summary.html) printer shows *aggregate* results for a
single search in a human readable format, and is modeled after similar formats
found in standard grep-like tools. This printer is useful for showing the total
number of matches and/or printing file paths that either contain or don't
contain matches.
The [`Summary`] printer shows *aggregate* results for a single search in a
human readable format, and is modeled after similar formats found in standard
grep-like tools. This printer is useful for showing the total number of matches
and/or printing file paths that either contain or don't contain matches.
# Example

41
crates/printer/src/standard.rs
View File

@ -149,11 +149,11 @@ impl StandardBuilder {
/// Set the user color specifications to use for coloring in this printer.
///
/// A [`UserColorSpec`](struct.UserColorSpec.html) 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`](struct.ColorSpecs.html) can then be generated from
/// zero or more `UserColorSpec`s.
/// A [`UserColorSpec`](crate::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
/// `UserColorSpec`s.
///
/// Regardless of the color specifications provided here, whether color
/// is actually used or not is determined by the implementation of
@ -196,15 +196,13 @@ impl StandardBuilder {
/// number of bytes searched and the total number of bytes printed.
///
/// Aggregate statistics can be accessed via the sink's
/// [`StandardSink::stats`](struct.StandardSink.html#method.stats)
/// method.
/// [`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`](struct.Stats.html).
/// For a complete description of available statistics, see [`Stats`].
pub fn stats(&mut self, yes: bool) -> &mut StandardBuilder {
self.config.stats = yes;
self
@ -484,7 +482,7 @@ impl StandardBuilder {
/// A default printer can be created with either of the `Standard::new` or
/// `Standard::new_no_color` constructors. However, there are a considerable
/// number of options that configure this printer's output. Those options can
/// be configured using [`StandardBuilder`](struct.StandardBuilder.html).
/// be configured using [`StandardBuilder`].
///
/// This type is generic over `W`, which represents any implementation
/// of the `termcolor::WriteColor` trait. If colors are not desired,
@ -633,12 +631,9 @@ impl<W> Standard<W> {
/// An implementation of `Sink` associated with a matcher and an optional file
/// path for the standard printer.
///
/// A `Sink` can be created via the
/// [`Standard::sink`](struct.Standard.html#method.sink)
/// or
/// [`Standard::sink_with_path`](struct.Standard.html#method.sink_with_path)
/// methods, depending on whether you want to include a file path in the
/// printer's output.
/// A `Sink` can be created via the [`Standard::sink`] or
/// [`Standard::sink_with_path`] methods, depending on whether you want to
/// include a file path in the printer's output.
///
/// Building a `StandardSink` is cheap, and callers should create a new one
/// for each thing that is searched. After a search has completed, callers may
@ -648,14 +643,13 @@ impl<W> Standard<W> {
/// This type is generic over a few type parameters:
///
/// * `'p` refers to the lifetime of the file path, if one is provided. When
/// no file path is given, then this is `'static`.
/// * `'s` refers to the lifetime of the
/// [`Standard`](struct.Standard.html)
/// printer that this type borrows.
/// no file path is given, then this is `'static`.
/// * `'s` refers to the lifetime of the [`Standard`] printer that this type
/// borrows.
/// * `M` refers to the type of matcher used by
/// `grep_searcher::Searcher` that is reporting results to this sink.
/// `grep_searcher::Searcher` that is reporting results to this sink.
/// * `W` refers to the underlying writer that this printer is writing its
/// output to.
/// output to.
#[derive(Debug)]
pub struct StandardSink<'p, 's, M: Matcher, W> {
matcher: M,
@ -710,8 +704,7 @@ impl<'p, 's, M: Matcher, W: WriteColor> StandardSink<'p, 's, M, W> {
/// searches executed on this sink.
///
/// This only returns stats if they were requested via the
/// [`StandardBuilder`](struct.StandardBuilder.html)
/// configuration.
/// [`StandardBuilder`] configuration.
pub fn stats(&self) -> Option<&Stats> {
self.stats.as_ref()
}

32
crates/printer/src/summary.rs
View File

@ -193,11 +193,11 @@ impl SummaryBuilder {
/// Set the user color specifications to use for coloring in this printer.
///
/// A [`UserColorSpec`](struct.UserColorSpec.html) 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`](struct.ColorSpecs.html) can then be generated from
/// zero or more `UserColorSpec`s.
/// A [`UserColorSpec`](crate::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
/// `UserColorSpec`s.
///
/// Regardless of the color specifications provided here, whether color
/// is actually used or not is determined by the implementation of
@ -242,8 +242,7 @@ impl SummaryBuilder {
/// number of bytes searched and the total number of bytes printed.
///
/// Aggregate statistics can be accessed via the sink's
/// [`SummarySink::stats`](struct.SummarySink.html#method.stats)
/// method.
/// [`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
@ -251,8 +250,7 @@ impl SummaryBuilder {
/// 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`](struct.Stats.html).
/// 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.
@ -348,7 +346,7 @@ impl SummaryBuilder {
/// A default printer can be created with either of the `Summary::new` or
/// `Summary::new_no_color` constructors. However, there are a number of
/// options that configure this printer's output. Those options can be
/// configured using [`SummaryBuilder`](struct.SummaryBuilder.html).
/// configured using [`SummaryBuilder`].
///
/// This type is generic over `W`, which represents any implementation of
/// the `termcolor::WriteColor` trait.
@ -480,14 +478,13 @@ impl<W> Summary<W> {
/// This type is generic over a few type parameters:
///
/// * `'p` refers to the lifetime of the file path, if one is provided. When
/// no file path is given, then this is `'static`.
/// * `'s` refers to the lifetime of the
/// [`Summary`](struct.Summary.html)
/// printer that this type borrows.
/// no file path is given, then this is `'static`.
/// * `'s` refers to the lifetime of the [`Summary`] printer that this type
/// borrows.
/// * `M` refers to the type of matcher used by
/// `grep_searcher::Searcher` that is reporting results to this sink.
/// `grep_searcher::Searcher` that is reporting results to this sink.
/// * `W` refers to the underlying writer that this printer is writing its
/// output to.
/// output to.
#[derive(Debug)]
pub struct SummarySink<'p, 's, M: Matcher, W> {
matcher: M,
@ -531,8 +528,7 @@ impl<'p, 's, M: Matcher, W: WriteColor> SummarySink<'p, 's, M, W> {
/// searches executed on this sink.
///
/// This only returns stats if they were requested via the
/// [`SummaryBuilder`](struct.SummaryBuilder.html)
/// configuration.
/// [`SummaryBuilder`] configuration.
pub fn stats(&self) -> Option<&Stats> {
self.stats.as_ref()
}

50
crates/searcher/src/lib.rs
View File

@ -4,48 +4,38 @@ support for multi-line search.
# Brief overview
The principle type in this crate is a
[`Searcher`](struct.Searcher.html),
which can be configured and built by a
[`SearcherBuilder`](struct.SearcherBuilder.html).
A `Searcher` is responsible for reading bytes from a source (e.g., a file),
executing a search of those bytes using a `Matcher` (e.g., a regex) and then
reporting the results of that search to a
[`Sink`](trait.Sink.html)
(e.g., stdout). The `Searcher` itself is principally responsible for managing
the consumption of bytes from a source and applying a `Matcher` over those
bytes in an efficient way. The `Searcher` is also responsible for inverting
a search, counting lines, reporting contextual lines, detecting binary data
and even deciding whether or not to use memory maps.
The principle type in this crate is a [`Searcher`], which can be configured
and built by a [`SearcherBuilder`]. A `Searcher` is responsible for reading
bytes from a source (e.g., a file), executing a search of those bytes using
a `Matcher` (e.g., a regex) and then reporting the results of that search to
a [`Sink`] (e.g., stdout). The `Searcher` itself is principally responsible
for managing the consumption of bytes from a source and applying a `Matcher`
over those bytes in an efficient way. The `Searcher` is also responsible for
inverting a search, counting lines, reporting contextual lines, detecting
binary data and even deciding whether or not to use memory maps.
A `Matcher` (which is defined in the
[`grep-matcher`](https://crates.io/crates/grep-matcher)
crate) is a trait for describing the lowest levels of pattern search in a
generic way. The interface itself is very similar to the interface of a regular
expression. For example, the
[`grep-regex`](https://crates.io/crates/grep-regex)
[`grep-matcher`](https://crates.io/crates/grep-matcher) crate) is a trait
for describing the lowest levels of pattern search in a generic way. The
interface itself is very similar to the interface of a regular expression.
For example, the [`grep-regex`](https://crates.io/crates/grep-regex)
crate provides an implementation of the `Matcher` trait using Rust's
[`regex`](https://crates.io/crates/regex)
crate.
[`regex`](https://crates.io/crates/regex) crate.
Finally, a `Sink` describes how callers receive search results producer by a
`Searcher`. This includes routines that are called at the beginning and end of
a search, in addition to routines that are called when matching or contextual
lines are found by the `Searcher`. Implementations of `Sink` can be trivially
simple, or extraordinarily complex, such as the
`Standard` printer found in the
[`grep-printer`](https://crates.io/crates/grep-printer)
crate, which effectively implements grep-like output.
This crate also provides convenience `Sink` implementations in the
[`sinks`](sinks/index.html)
sub-module for easy searching with closures.
simple, or extraordinarily complex, such as the `Standard` printer found in
the [`grep-printer`](https://crates.io/crates/grep-printer) crate, which
effectively implements grep-like output. This crate also provides convenience
`Sink` implementations in the [`sinks`] sub-module for easy searching with
closures.
# Example
This example shows how to execute the searcher and read the search results
using the
[`UTF8`](sinks/struct.UTF8.html)
implementation of `Sink`.
using the [`UTF8`](sinks::UTF8) implementation of `Sink`.
```
use std::error::Error;

16
crates/searcher/src/searcher/mod.rs
View File

@ -114,9 +114,8 @@ impl BinaryDetection {
/// An encoding to use when searching.
///
/// An encoding can be used to configure a
/// [`SearcherBuilder`](struct.SearchBuilder.html)
/// to transcode source data from an encoding to UTF-8 before searching.
/// An encoding can be used to configure a [`SearcherBuilder`] to transcode
/// source data from an encoding to UTF-8 before searching.
///
/// An `Encoding` will always be cheap to clone.
#[derive(Clone, Debug)]
@ -508,8 +507,7 @@ impl SearcherBuilder {
///
/// The binary detection strategy determines not only how the searcher
/// detects binary data, but how it responds to the presence of binary
/// data. See the [`BinaryDetection`](struct.BinaryDetection.html) type
/// for more information.
/// data. See the [`BinaryDetection`] type for more information.
///
/// By default, binary detection is disabled.
pub fn binary_detection(
@ -616,8 +614,7 @@ impl Searcher {
/// Create a new searcher with a default configuration.
///
/// To configure the searcher (e.g., invert matching, enable memory maps,
/// enable contexts, etc.), use the
/// [`SearcherBuilder`](struct.SearcherBuilder.html).
/// enable contexts, etc.), use the [`SearcherBuilder`].
pub fn new() -> Searcher {
SearcherBuilder::new().build()
}
@ -817,9 +814,8 @@ impl Searcher {
}
/// The following methods permit querying the configuration of a searcher.
/// These can be useful in generic implementations of
/// [`Sink`](trait.Sink.html),
/// where the output may be tailored based on how the searcher is configured.
/// These can be useful in generic implementations of [`Sink`], where the
/// output may be tailored based on how the searcher is configured.
impl Searcher {
/// Returns the line terminator used by this searcher.
#[inline]

6
crates/searcher/src/sink.rs
View File

@ -74,8 +74,8 @@ impl SinkError for Box<dyn error::Error> {
///
/// * What to do when a match is found. Callers must provide this.
/// * What to do when an error occurs. Callers must provide this via the
/// [`SinkError`](trait.SinkError.html) trait. Generally, callers can just
/// use `io::Error` for this, which already implements `SinkError`.
/// [`SinkError`] trait. Generally, callers can just use `io::Error` for
/// this, which already implements `SinkError`.
/// * What to do when a contextual line is found. By default, these are
/// ignored.
/// * What to do when a gap between contextual lines has been found. By
@ -95,7 +95,7 @@ impl SinkError for Box<dyn error::Error> {
///
/// For simpler uses of `Sink`, callers may elect to use one of
/// the more convenient but less flexible implementations in the
/// [`sinks`](sinks/index.html) module.
/// [`sinks`] module.
pub trait Sink {
/// The type of an error that should be reported by a searcher.
///