diff --git a/crates/cli/src/escape.rs b/crates/cli/src/escape.rs index 9b442343..d14b81d1 100644 --- a/crates/cli/src/escape.rs +++ b/crates/cli/src/escape.rs @@ -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 { /// 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. diff --git a/crates/cli/src/lib.rs b/crates/cli/src/lib.rs index b335a3f5..643d796c 100644 --- a/crates/cli/src/lib.rs +++ b/crates/cli/src/lib.rs @@ -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)] diff --git a/crates/cli/src/process.rs b/crates/cli/src/process.rs index 11e02566..bc166d69 100644 --- a/crates/cli/src/process.rs +++ b/crates/cli/src/process.rs @@ -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 { diff --git a/crates/cli/src/wtr.rs b/crates/cli/src/wtr.rs index 18c1175a..f6c7306b 100644 --- a/crates/cli/src/wtr.rs +++ b/crates/cli/src/wtr.rs @@ -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 { diff --git a/crates/ignore/src/walk.rs b/crates/ignore/src/walk.rs index fdeea93c..eead9ffa 100644 --- a/crates/ignore/src/walk.rs +++ b/crates/ignore/src/walk.rs @@ -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; @@ -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. diff --git a/crates/matcher/src/lib.rs b/crates/matcher/src/lib.rs index b9c1b8a8..306fed53 100644 --- a/crates/matcher/src/lib.rs +++ b/crates/matcher/src/lib.rs @@ -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 diff --git a/crates/printer/src/color.rs b/crates/printer/src/color.rs index d17674e9..164cac75 100644 --- a/crates/printer/src/color.rs +++ b/crates/printer/src/color.rs @@ -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, diff --git a/crates/printer/src/json.rs b/crates/printer/src/json.rs index 3f5bd48a..1a0b6183 100644 --- a/crates/printer/src/json.rs +++ b/crates/printer/src/json.rs @@ -549,14 +549,13 @@ impl JSON { /// 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, diff --git a/crates/printer/src/lib.rs b/crates/printer/src/lib.rs index 6c4a3735..5748862c 100644 --- a/crates/printer/src/lib.rs +++ b/crates/printer/src/lib.rs @@ -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 diff --git a/crates/printer/src/standard.rs b/crates/printer/src/standard.rs index cd6a4e54..c33bf14e 100644 --- a/crates/printer/src/standard.rs +++ b/crates/printer/src/standard.rs @@ -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 Standard { /// 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 Standard { /// 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() } diff --git a/crates/printer/src/summary.rs b/crates/printer/src/summary.rs index 431b3a92..7c16223c 100644 --- a/crates/printer/src/summary.rs +++ b/crates/printer/src/summary.rs @@ -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 Summary { /// 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() } diff --git a/crates/searcher/src/lib.rs b/crates/searcher/src/lib.rs index f6a96a21..20d38ffe 100644 --- a/crates/searcher/src/lib.rs +++ b/crates/searcher/src/lib.rs @@ -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; diff --git a/crates/searcher/src/searcher/mod.rs b/crates/searcher/src/searcher/mod.rs index 9b6c9bd4..b6b8f38f 100644 --- a/crates/searcher/src/searcher/mod.rs +++ b/crates/searcher/src/searcher/mod.rs @@ -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] diff --git a/crates/searcher/src/sink.rs b/crates/searcher/src/sink.rs index e82634cd..8621e73a 100644 --- a/crates/searcher/src/sink.rs +++ b/crates/searcher/src/sink.rs @@ -74,8 +74,8 @@ impl SinkError for Box { /// /// * 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 { /// /// 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. ///