mirror of
https://github.com/BurntSushi/ripgrep.git
synced 2025-08-10 00:52:04 -07:00
crates: remove hard-coded links
And use rustdoc's native intra-crate links. So much nicer.
This commit is contained in:
@@ -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;
|
||||
|
@@ -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]
|
||||
|
@@ -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.
|
||||
///
|
||||
|
Reference in New Issue
Block a user