mirror of
https://github.com/BurntSushi/ripgrep.git
synced 2025-04-19 09:02:15 +02:00
crates: remove hard-coded links
And use rustdoc's native intra-crate links. So much nicer.
This commit is contained in:
parent
82d3183a04
commit
3ad7a0d95e
@ -8,7 +8,7 @@ use bstr::{ByteSlice, ByteVec};
|
|||||||
/// converts the non-printable subset of ASCII in addition to invalid UTF-8
|
/// converts the non-printable subset of ASCII in addition to invalid UTF-8
|
||||||
/// bytes to hexadecimal escape sequences. Everything else is left as is.
|
/// 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
|
/// # Example
|
||||||
///
|
///
|
||||||
@ -29,7 +29,7 @@ pub fn escape(bytes: &[u8]) -> String {
|
|||||||
|
|
||||||
/// Escapes an OS string into a human readable 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 {
|
pub fn escape_os(string: &OsStr) -> String {
|
||||||
escape(Vec::from_os_str_lossy(string).as_bytes())
|
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
|
/// capable of specifying arbitrary bytes or otherwise make it easier to
|
||||||
/// specify non-printable characters.
|
/// specify non-printable characters.
|
||||||
///
|
///
|
||||||
/// The dual of this routine is [`escape`](fn.escape.html).
|
/// The dual of this routine is [`escape`].
|
||||||
///
|
///
|
||||||
/// # Example
|
/// # Example
|
||||||
///
|
///
|
||||||
@ -70,7 +70,7 @@ pub fn unescape(s: &str) -> Vec<u8> {
|
|||||||
|
|
||||||
/// Unescapes an OS string.
|
/// 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
|
/// 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.
|
/// is, an escaped string (the thing given) should be valid UTF-8.
|
||||||
|
@ -20,22 +20,17 @@ recursively search the current working directory for occurrences of `foo`, but
|
|||||||
|
|
||||||
# Coloring and buffering
|
# Coloring and buffering
|
||||||
|
|
||||||
The
|
The [`stdout`], [`stdout_buffered_block`] and [`stdout_buffered_line`] routines
|
||||||
[`stdout`](fn.stdout.html),
|
are alternative constructors for [`StandardStream`]. A `StandardStream`
|
||||||
[`stdout_buffered_block`](fn.stdout_buffered_block.html)
|
implements `termcolor::WriteColor`, which provides a way to emit colors to
|
||||||
and
|
terminals. Its key use is the encapsulation of buffering style. Namely,
|
||||||
[`stdout_buffered_line`](fn.stdout_buffered_line.html)
|
`stdout` will return a line buffered `StandardStream` if and only if
|
||||||
routines are alternative constructors for
|
stdout is connected to a tty, and will otherwise return a block buffered
|
||||||
[`StandardStream`](struct.StandardStream.html).
|
`StandardStream`. Line buffering is important for use with a tty because it
|
||||||
A `StandardStream` implements `termcolor::WriteColor`, which provides a way
|
typically decreases the latency at which the end user sees output. Block
|
||||||
to emit colors to terminals. Its key use is the encapsulation of buffering
|
buffering is used otherwise because it is faster, and redirecting stdout to a
|
||||||
style. Namely, `stdout` will return a line buffered `StandardStream` if and
|
file typically doesn't benefit from the decreased latency that line buffering
|
||||||
only if stdout is connected to a tty, and will otherwise return a block
|
provides.
|
||||||
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
|
The `stdout_buffered_block` and `stdout_buffered_line` can be used to
|
||||||
explicitly set the buffering strategy regardless of whether stdout is connected
|
explicitly set the buffering strategy regardless of whether stdout is connected
|
||||||
@ -44,17 +39,12 @@ to a tty or not.
|
|||||||
|
|
||||||
# Escaping
|
# Escaping
|
||||||
|
|
||||||
The
|
The [`escape`](crate::escape()), [`escape_os`], [`unescape`] and
|
||||||
[`escape`](fn.escape.html),
|
[`unescape_os`] routines provide a user friendly way of dealing with UTF-8
|
||||||
[`escape_os`](fn.escape_os.html),
|
encoded strings that can express arbitrary bytes. For example, you might want
|
||||||
[`unescape`](fn.unescape.html)
|
to accept a string containing arbitrary bytes as a command line argument, but
|
||||||
and
|
most interactive shells make such strings difficult to type. Instead, we can
|
||||||
[`unescape_os`](fn.unescape_os.html)
|
ask users to use escape sequences.
|
||||||
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
|
For example, `a\xFFz` is itself a valid UTF-8 string corresponding to the
|
||||||
following bytes:
|
following bytes:
|
||||||
@ -87,44 +77,36 @@ makes it easy to show user friendly error messages involving arbitrary bytes.
|
|||||||
# Building patterns
|
# Building patterns
|
||||||
|
|
||||||
Typically, regular expression patterns must be valid UTF-8. However, command
|
Typically, regular expression patterns must be valid UTF-8. However, command
|
||||||
line arguments aren't guaranteed to be valid UTF-8. Unfortunately, the
|
line arguments aren't guaranteed to be valid UTF-8. Unfortunately, the standard
|
||||||
standard library's UTF-8 conversion functions from `OsStr`s do not provide
|
library's UTF-8 conversion functions from `OsStr`s do not provide good error
|
||||||
good error messages. However, the
|
messages. However, the [`pattern_from_bytes`] and [`pattern_from_os`] do,
|
||||||
[`pattern_from_bytes`](fn.pattern_from_bytes.html)
|
including reporting exactly where the first invalid UTF-8 byte is seen.
|
||||||
and
|
|
||||||
[`pattern_from_os`](fn.pattern_from_os.html)
|
|
||||||
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
|
Additionally, it can be useful to read patterns from a file while reporting
|
||||||
good error messages that include line numbers. The
|
good error messages that include line numbers. The [`patterns_from_path`],
|
||||||
[`patterns_from_path`](fn.patterns_from_path.html),
|
[`patterns_from_reader`] and [`patterns_from_stdin`] routines do just that. If
|
||||||
[`patterns_from_reader`](fn.patterns_from_reader.html)
|
any pattern is found that is invalid UTF-8, then the error includes the file
|
||||||
and
|
path (if available) along with the line number and the byte offset at which the
|
||||||
[`patterns_from_stdin`](fn.patterns_from_stdin.html)
|
first invalid UTF-8 byte was observed.
|
||||||
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
|
# Read process output
|
||||||
|
|
||||||
Sometimes a command line application needs to execute other processes and read
|
Sometimes a command line application needs to execute other processes and
|
||||||
its stdout in a streaming fashion. The
|
read its stdout in a streaming fashion. The [`CommandReader`] provides this
|
||||||
[`CommandReader`](struct.CommandReader.html)
|
functionality with an explicit goal of improving failure modes. In particular,
|
||||||
provides this functionality with an explicit goal of improving failure modes.
|
if the process exits with an error code, then stderr is read and converted into
|
||||||
In particular, if the process exits with an error code, then stderr is read
|
a normal Rust error to show to end users. This makes the underlying failure
|
||||||
and converted into a normal Rust error to show to end users. This makes the
|
modes explicit and gives more information to end users for debugging the
|
||||||
underlying failure modes explicit and gives more information to end users for
|
problem.
|
||||||
debugging the problem.
|
|
||||||
|
|
||||||
As a special case,
|
As a special case, [`DecompressionReader`] provides a way to decompress
|
||||||
[`DecompressionReader`](struct.DecompressionReader.html)
|
arbitrary files by matching their file extensions up with corresponding
|
||||||
provides a way to decompress arbitrary files by matching their file extensions
|
decompression programs (such as `gzip` and `xz`). This is useful as a means of
|
||||||
up with corresponding decompression programs (such as `gzip` and `xz`). This
|
performing simplistic decompression in a portable manner without binding to
|
||||||
is useful as a means of performing simplistic decompression in a portable
|
specific compression libraries. This does come with some overhead though, so
|
||||||
manner without binding to specific compression libraries. This does come with
|
if you need to decompress lots of small files, this may not be an appropriate
|
||||||
some overhead though, so if you need to decompress lots of small files, this
|
convenience to use.
|
||||||
may not be an appropriate convenience to use.
|
|
||||||
|
|
||||||
Each reader has a corresponding builder for additional configuration, such as
|
Each reader has a corresponding builder for additional configuration, such as
|
||||||
whether to read stderr asynchronously in order to avoid deadlock (which is
|
whether to read stderr asynchronously in order to avoid deadlock (which is
|
||||||
@ -133,11 +115,10 @@ enabled by default).
|
|||||||
|
|
||||||
# Miscellaneous parsing
|
# Miscellaneous parsing
|
||||||
|
|
||||||
The
|
The [`parse_human_readable_size`] routine parses strings like `2M` and converts
|
||||||
[`parse_human_readable_size`](fn.parse_human_readable_size.html)
|
them to the corresponding number of bytes (`2 * 1<<20` in this case). If an
|
||||||
routine parses strings like `2M` and converts them to the corresponding number
|
invalid size is found, then a good error message is crafted that typically
|
||||||
of bytes (`2 * 1<<20` in this case). If an invalid size is found, then a good
|
tells the user how to fix the problem.
|
||||||
error message is crafted that typically tells the user how to fix the problem.
|
|
||||||
*/
|
*/
|
||||||
|
|
||||||
#![deny(missing_docs)]
|
#![deny(missing_docs)]
|
||||||
|
@ -191,8 +191,7 @@ impl CommandReader {
|
|||||||
/// returned.
|
/// returned.
|
||||||
///
|
///
|
||||||
/// If the caller requires additional configuration for the reader
|
/// If the caller requires additional configuration for the reader
|
||||||
/// returned, then use
|
/// returned, then use [`CommandReaderBuilder`].
|
||||||
/// [`CommandReaderBuilder`](struct.CommandReaderBuilder.html).
|
|
||||||
pub fn new(
|
pub fn new(
|
||||||
cmd: &mut process::Command,
|
cmd: &mut process::Command,
|
||||||
) -> Result<CommandReader, CommandError> {
|
) -> Result<CommandReader, CommandError> {
|
||||||
|
@ -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
|
/// 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.
|
/// is that it can be slower, especially when there is a lot of output.
|
||||||
///
|
///
|
||||||
/// You might consider using
|
/// You might consider using [`stdout`] instead, which chooses the buffering
|
||||||
/// [`stdout`](fn.stdout.html)
|
/// strategy automatically based on whether stdout is connected to a tty.
|
||||||
/// instead, which chooses the buffering strategy automatically based on
|
|
||||||
/// whether stdout is connected to a tty.
|
|
||||||
pub fn stdout_buffered_line(
|
pub fn stdout_buffered_line(
|
||||||
color_choice: termcolor::ColorChoice,
|
color_choice: termcolor::ColorChoice,
|
||||||
) -> StandardStream {
|
) -> StandardStream {
|
||||||
@ -50,10 +48,8 @@ pub fn stdout_buffered_line(
|
|||||||
/// the cost of writing data. The downside of this approach is that it can
|
/// 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.
|
/// increase the latency of display output when writing to a tty.
|
||||||
///
|
///
|
||||||
/// You might consider using
|
/// You might consider using [`stdout`] instead, which chooses the buffering
|
||||||
/// [`stdout`](fn.stdout.html)
|
/// strategy automatically based on whether stdout is connected to a tty.
|
||||||
/// instead, which chooses the buffering strategy automatically based on
|
|
||||||
/// whether stdout is connected to a tty.
|
|
||||||
pub fn stdout_buffered_block(
|
pub fn stdout_buffered_block(
|
||||||
color_choice: termcolor::ColorChoice,
|
color_choice: termcolor::ColorChoice,
|
||||||
) -> StandardStream {
|
) -> StandardStream {
|
||||||
|
@ -38,9 +38,7 @@ impl DirEntry {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/// The full path that this entry represents.
|
/// The full path that this entry represents.
|
||||||
/// Analogous to [`path`], but moves ownership of the path.
|
/// Analogous to [`DirEntry::path`], but moves ownership of the path.
|
||||||
///
|
|
||||||
/// [`path`]: struct.DirEntry.html#method.path
|
|
||||||
pub fn into_path(self) -> PathBuf {
|
pub fn into_path(self) -> PathBuf {
|
||||||
self.dent.into_path()
|
self.dent.into_path()
|
||||||
}
|
}
|
||||||
@ -1127,10 +1125,10 @@ impl WalkState {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// A builder for constructing a visitor when using
|
/// A builder for constructing a visitor when using [`WalkParallel::visit`].
|
||||||
/// [`WalkParallel::visit`](struct.WalkParallel.html#method.visit). The builder
|
/// The builder will be called for each thread started by `WalkParallel`. The
|
||||||
/// will be called for each thread started by `WalkParallel`. The visitor
|
/// visitor returned from each builder is then called for every directory
|
||||||
/// returned from each builder is then called for every directory entry.
|
/// entry.
|
||||||
pub trait ParallelVisitorBuilder<'s> {
|
pub trait ParallelVisitorBuilder<'s> {
|
||||||
/// Create per-thread `ParallelVisitor`s for `WalkParallel`.
|
/// Create per-thread `ParallelVisitor`s for `WalkParallel`.
|
||||||
fn build(&mut self) -> Box<dyn ParallelVisitor + 's>;
|
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.
|
/// Receives files and directories for the current thread.
|
||||||
///
|
///
|
||||||
/// Setup for the traversal can be implemented as part of
|
/// Setup for the traversal can be implemented as part of
|
||||||
/// [`ParallelVisitorBuilder::build`](trait.ParallelVisitorBuilder.html#tymethod.build).
|
/// [`ParallelVisitorBuilder::build`]. Teardown when traversal finishes can be
|
||||||
/// Teardown when traversal finishes can be implemented by implementing the
|
/// implemented by implementing the `Drop` trait on your traversal type.
|
||||||
/// `Drop` trait on your traversal type.
|
|
||||||
pub trait ParallelVisitor: Send {
|
pub trait ParallelVisitor: Send {
|
||||||
/// Receives files and directories for the current thread. This is called
|
/// Receives files and directories for the current thread. This is called
|
||||||
/// once for every directory entry visited by traversal.
|
/// once for every directory entry visited by traversal.
|
||||||
|
@ -6,12 +6,10 @@ the search routines provided by the
|
|||||||
[`grep-searcher`](https://docs.rs/grep-searcher)
|
[`grep-searcher`](https://docs.rs/grep-searcher)
|
||||||
crate.
|
crate.
|
||||||
|
|
||||||
The primary thing provided by this crate is the
|
The primary thing provided by this crate is the [`Matcher`] trait. The trait
|
||||||
[`Matcher`](trait.Matcher.html)
|
defines an abstract interface for text search. It is robust enough to support
|
||||||
trait. The trait defines an abstract interface for text search. It is robust
|
everything from basic substring search all the way to arbitrarily complex
|
||||||
enough to support everything from basic substring search all the way to
|
regular expression implementations without sacrificing performance.
|
||||||
arbitrarily complex regular expression implementations without sacrificing
|
|
||||||
performance.
|
|
||||||
|
|
||||||
A key design decision made in this crate is the use of *internal iteration*,
|
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,
|
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.
|
/// A matcher defines an interface for regular expression implementations.
|
||||||
///
|
///
|
||||||
/// While this trait is large, there are only two required methods that
|
/// While this trait is large, there are only two required methods that
|
||||||
/// implementors must provide: `find_at` and `new_captures`. If captures
|
/// implementors must provide: `find_at` and `new_captures`. If captures aren't
|
||||||
/// aren't supported by your implementation, then `new_captures` can be
|
/// supported by your implementation, then `new_captures` can be implemented
|
||||||
/// implemented with
|
/// with [`NoCaptures`]. If your implementation does support capture groups,
|
||||||
/// [`NoCaptures`](struct.NoCaptures.html). If your implementation does support
|
/// then you should also implement the other capture related methods, as
|
||||||
/// capture groups, then you should also implement the other capture related
|
/// dictated by the documentation. Crucially, this includes `captures_at`.
|
||||||
/// methods, as dictated by the documentation. Crucially, this includes
|
|
||||||
/// `captures_at`.
|
|
||||||
///
|
///
|
||||||
/// The rest of the methods on this trait provide default implementations on
|
/// 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
|
/// top of `find_at` and `new_captures`. It is not uncommon for implementations
|
||||||
|
@ -83,7 +83,7 @@ impl std::fmt::Display for ColorError {
|
|||||||
/// This set of color specifications represents the various color types that
|
/// This set of color specifications represents the various color types that
|
||||||
/// are supported by the printers in this crate. A set of color specifications
|
/// are supported by the printers in this crate. A set of color specifications
|
||||||
/// can be created from a sequence of
|
/// can be created from a sequence of
|
||||||
/// [`UserColorSpec`s](struct.UserColorSpec.html).
|
/// [`UserColorSpec`]s.
|
||||||
#[derive(Clone, Debug, Default, Eq, PartialEq)]
|
#[derive(Clone, Debug, Default, Eq, PartialEq)]
|
||||||
pub struct ColorSpecs {
|
pub struct ColorSpecs {
|
||||||
path: ColorSpec,
|
path: ColorSpec,
|
||||||
|
@ -550,9 +550,8 @@ impl<W> JSON<W> {
|
|||||||
///
|
///
|
||||||
/// * `'p` refers to the lifetime of the file path, if one is provided. When
|
/// * `'p` refers to the lifetime of the file path, if one is provided. When
|
||||||
/// no file path is given, then this is `'static`.
|
/// no file path is given, then this is `'static`.
|
||||||
/// * `'s` refers to the lifetime of the
|
/// * `'s` refers to the lifetime of the [`JSON`] printer that this type
|
||||||
/// [`JSON`](struct.JSON.html)
|
/// borrows.
|
||||||
/// printer that this type borrows.
|
|
||||||
/// * `M` refers to the type of matcher used by
|
/// * `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
|
/// * `W` refers to the underlying writer that this printer is writing its
|
||||||
|
@ -5,22 +5,20 @@ crate.
|
|||||||
|
|
||||||
# Brief overview
|
# Brief overview
|
||||||
|
|
||||||
The [`Standard`](struct.Standard.html) printer shows results in a human
|
The [`Standard`] printer shows results in a human readable format, and is
|
||||||
readable format, and is modeled after the formats used by standard grep-like
|
modeled after the formats used by standard grep-like tools. Features include,
|
||||||
tools. Features include, but are not limited to, cross platform terminal
|
but are not limited to, cross platform terminal coloring, search & replace,
|
||||||
coloring, search & replace, multi-line result handling and reporting summary
|
multi-line result handling and reporting summary statistics.
|
||||||
statistics.
|
|
||||||
|
|
||||||
The [`JSON`](struct.JSON.html) printer shows results in a machine readable
|
The [`JSON`] printer shows results in a machine readable format.
|
||||||
format. To facilitate a stream of search results, the format uses
|
To facilitate a stream of search results, the format uses [JSON
|
||||||
[JSON Lines](https://jsonlines.org/)
|
Lines](https://jsonlines.org/) by emitting a series of messages as search
|
||||||
by emitting a series of messages as search results are found.
|
results are found.
|
||||||
|
|
||||||
The [`Summary`](struct.Summary.html) printer shows *aggregate* results for a
|
The [`Summary`] printer shows *aggregate* results for a single search in a
|
||||||
single search in a human readable format, and is modeled after similar formats
|
human readable format, and is modeled after similar formats found in standard
|
||||||
found in standard grep-like tools. This printer is useful for showing the total
|
grep-like tools. This printer is useful for showing the total number of matches
|
||||||
number of matches and/or printing file paths that either contain or don't
|
and/or printing file paths that either contain or don't contain matches.
|
||||||
contain matches.
|
|
||||||
|
|
||||||
# Example
|
# Example
|
||||||
|
|
||||||
|
@ -149,11 +149,11 @@ impl StandardBuilder {
|
|||||||
|
|
||||||
/// Set the user color specifications to use for coloring in this printer.
|
/// Set the user color specifications to use for coloring in this printer.
|
||||||
///
|
///
|
||||||
/// A [`UserColorSpec`](struct.UserColorSpec.html) can be constructed from
|
/// A [`UserColorSpec`](crate::UserColorSpec) can be constructed from
|
||||||
/// a string in accordance with the color specification format. See the
|
/// a string in accordance with the color specification format. See
|
||||||
/// `UserColorSpec` type documentation for more details on the format.
|
/// the `UserColorSpec` type documentation for more details on the
|
||||||
/// A [`ColorSpecs`](struct.ColorSpecs.html) can then be generated from
|
/// format. A [`ColorSpecs`] can then be generated from zero or more
|
||||||
/// zero or more `UserColorSpec`s.
|
/// `UserColorSpec`s.
|
||||||
///
|
///
|
||||||
/// Regardless of the color specifications provided here, whether color
|
/// Regardless of the color specifications provided here, whether color
|
||||||
/// is actually used or not is determined by the implementation of
|
/// 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.
|
/// number of bytes searched and the total number of bytes printed.
|
||||||
///
|
///
|
||||||
/// Aggregate statistics can be accessed via the sink's
|
/// Aggregate statistics can be accessed via the sink's
|
||||||
/// [`StandardSink::stats`](struct.StandardSink.html#method.stats)
|
/// [`StandardSink::stats`] method.
|
||||||
/// method.
|
|
||||||
///
|
///
|
||||||
/// When this is enabled, this printer may need to do extra work in order
|
/// 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
|
/// to compute certain statistics, which could cause the search to take
|
||||||
/// longer.
|
/// longer.
|
||||||
///
|
///
|
||||||
/// For a complete description of available statistics, see
|
/// For a complete description of available statistics, see [`Stats`].
|
||||||
/// [`Stats`](struct.Stats.html).
|
|
||||||
pub fn stats(&mut self, yes: bool) -> &mut StandardBuilder {
|
pub fn stats(&mut self, yes: bool) -> &mut StandardBuilder {
|
||||||
self.config.stats = yes;
|
self.config.stats = yes;
|
||||||
self
|
self
|
||||||
@ -484,7 +482,7 @@ impl StandardBuilder {
|
|||||||
/// A default printer can be created with either of the `Standard::new` or
|
/// A default printer can be created with either of the `Standard::new` or
|
||||||
/// `Standard::new_no_color` constructors. However, there are a considerable
|
/// `Standard::new_no_color` constructors. However, there are a considerable
|
||||||
/// number of options that configure this printer's output. Those options can
|
/// 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
|
/// This type is generic over `W`, which represents any implementation
|
||||||
/// of the `termcolor::WriteColor` trait. If colors are not desired,
|
/// 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
|
/// An implementation of `Sink` associated with a matcher and an optional file
|
||||||
/// path for the standard printer.
|
/// path for the standard printer.
|
||||||
///
|
///
|
||||||
/// A `Sink` can be created via the
|
/// A `Sink` can be created via the [`Standard::sink`] or
|
||||||
/// [`Standard::sink`](struct.Standard.html#method.sink)
|
/// [`Standard::sink_with_path`] methods, depending on whether you want to
|
||||||
/// or
|
/// include a file path in the printer's output.
|
||||||
/// [`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.
|
|
||||||
///
|
///
|
||||||
/// Building a `StandardSink` is cheap, and callers should create a new one
|
/// 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
|
/// for each thing that is searched. After a search has completed, callers may
|
||||||
@ -649,9 +644,8 @@ impl<W> Standard<W> {
|
|||||||
///
|
///
|
||||||
/// * `'p` refers to the lifetime of the file path, if one is provided. When
|
/// * `'p` refers to the lifetime of the file path, if one is provided. When
|
||||||
/// no file path is given, then this is `'static`.
|
/// no file path is given, then this is `'static`.
|
||||||
/// * `'s` refers to the lifetime of the
|
/// * `'s` refers to the lifetime of the [`Standard`] printer that this type
|
||||||
/// [`Standard`](struct.Standard.html)
|
/// borrows.
|
||||||
/// printer that this type borrows.
|
|
||||||
/// * `M` refers to the type of matcher used by
|
/// * `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
|
/// * `W` refers to the underlying writer that this printer is writing its
|
||||||
@ -710,8 +704,7 @@ impl<'p, 's, M: Matcher, W: WriteColor> StandardSink<'p, 's, M, W> {
|
|||||||
/// searches executed on this sink.
|
/// searches executed on this sink.
|
||||||
///
|
///
|
||||||
/// This only returns stats if they were requested via the
|
/// This only returns stats if they were requested via the
|
||||||
/// [`StandardBuilder`](struct.StandardBuilder.html)
|
/// [`StandardBuilder`] configuration.
|
||||||
/// configuration.
|
|
||||||
pub fn stats(&self) -> Option<&Stats> {
|
pub fn stats(&self) -> Option<&Stats> {
|
||||||
self.stats.as_ref()
|
self.stats.as_ref()
|
||||||
}
|
}
|
||||||
|
@ -193,11 +193,11 @@ impl SummaryBuilder {
|
|||||||
|
|
||||||
/// Set the user color specifications to use for coloring in this printer.
|
/// Set the user color specifications to use for coloring in this printer.
|
||||||
///
|
///
|
||||||
/// A [`UserColorSpec`](struct.UserColorSpec.html) can be constructed from
|
/// A [`UserColorSpec`](crate::UserColorSpec) can be constructed from
|
||||||
/// a string in accordance with the color specification format. See the
|
/// a string in accordance with the color specification format. See
|
||||||
/// `UserColorSpec` type documentation for more details on the format.
|
/// the `UserColorSpec` type documentation for more details on the
|
||||||
/// A [`ColorSpecs`](struct.ColorSpecs.html) can then be generated from
|
/// format. A [`ColorSpecs`] can then be generated from zero or more
|
||||||
/// zero or more `UserColorSpec`s.
|
/// `UserColorSpec`s.
|
||||||
///
|
///
|
||||||
/// Regardless of the color specifications provided here, whether color
|
/// Regardless of the color specifications provided here, whether color
|
||||||
/// is actually used or not is determined by the implementation of
|
/// 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.
|
/// number of bytes searched and the total number of bytes printed.
|
||||||
///
|
///
|
||||||
/// Aggregate statistics can be accessed via the sink's
|
/// Aggregate statistics can be accessed via the sink's
|
||||||
/// [`SummarySink::stats`](struct.SummarySink.html#method.stats)
|
/// [`SummarySink::stats`] method.
|
||||||
/// method.
|
|
||||||
///
|
///
|
||||||
/// When this is enabled, this printer may need to do extra work in order
|
/// 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
|
/// 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
|
/// the first match, but if `stats` is enabled, then the search will
|
||||||
/// continue after the first match in order to compute statistics.
|
/// continue after the first match in order to compute statistics.
|
||||||
///
|
///
|
||||||
/// For a complete description of available statistics, see
|
/// For a complete description of available statistics, see [`Stats`].
|
||||||
/// [`Stats`](struct.Stats.html).
|
|
||||||
///
|
///
|
||||||
/// Note that some output modes, such as `CountMatches`, automatically
|
/// Note that some output modes, such as `CountMatches`, automatically
|
||||||
/// enable this option even if it has been explicitly disabled.
|
/// 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
|
/// A default printer can be created with either of the `Summary::new` or
|
||||||
/// `Summary::new_no_color` constructors. However, there are a number of
|
/// `Summary::new_no_color` constructors. However, there are a number of
|
||||||
/// options that configure this printer's output. Those options can be
|
/// 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
|
/// This type is generic over `W`, which represents any implementation of
|
||||||
/// the `termcolor::WriteColor` trait.
|
/// the `termcolor::WriteColor` trait.
|
||||||
@ -481,9 +479,8 @@ impl<W> Summary<W> {
|
|||||||
///
|
///
|
||||||
/// * `'p` refers to the lifetime of the file path, if one is provided. When
|
/// * `'p` refers to the lifetime of the file path, if one is provided. When
|
||||||
/// no file path is given, then this is `'static`.
|
/// no file path is given, then this is `'static`.
|
||||||
/// * `'s` refers to the lifetime of the
|
/// * `'s` refers to the lifetime of the [`Summary`] printer that this type
|
||||||
/// [`Summary`](struct.Summary.html)
|
/// borrows.
|
||||||
/// printer that this type borrows.
|
|
||||||
/// * `M` refers to the type of matcher used by
|
/// * `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
|
/// * `W` refers to the underlying writer that this printer is writing its
|
||||||
@ -531,8 +528,7 @@ impl<'p, 's, M: Matcher, W: WriteColor> SummarySink<'p, 's, M, W> {
|
|||||||
/// searches executed on this sink.
|
/// searches executed on this sink.
|
||||||
///
|
///
|
||||||
/// This only returns stats if they were requested via the
|
/// This only returns stats if they were requested via the
|
||||||
/// [`SummaryBuilder`](struct.SummaryBuilder.html)
|
/// [`SummaryBuilder`] configuration.
|
||||||
/// configuration.
|
|
||||||
pub fn stats(&self) -> Option<&Stats> {
|
pub fn stats(&self) -> Option<&Stats> {
|
||||||
self.stats.as_ref()
|
self.stats.as_ref()
|
||||||
}
|
}
|
||||||
|
@ -4,48 +4,38 @@ support for multi-line search.
|
|||||||
|
|
||||||
# Brief overview
|
# Brief overview
|
||||||
|
|
||||||
The principle type in this crate is a
|
The principle type in this crate is a [`Searcher`], which can be configured
|
||||||
[`Searcher`](struct.Searcher.html),
|
and built by a [`SearcherBuilder`]. A `Searcher` is responsible for reading
|
||||||
which can be configured and built by a
|
bytes from a source (e.g., a file), executing a search of those bytes using
|
||||||
[`SearcherBuilder`](struct.SearcherBuilder.html).
|
a `Matcher` (e.g., a regex) and then reporting the results of that search to
|
||||||
A `Searcher` is responsible for reading bytes from a source (e.g., a file),
|
a [`Sink`] (e.g., stdout). The `Searcher` itself is principally responsible
|
||||||
executing a search of those bytes using a `Matcher` (e.g., a regex) and then
|
for managing the consumption of bytes from a source and applying a `Matcher`
|
||||||
reporting the results of that search to a
|
over those bytes in an efficient way. The `Searcher` is also responsible for
|
||||||
[`Sink`](trait.Sink.html)
|
inverting a search, counting lines, reporting contextual lines, detecting
|
||||||
(e.g., stdout). The `Searcher` itself is principally responsible for managing
|
binary data and even deciding whether or not to use memory maps.
|
||||||
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
|
A `Matcher` (which is defined in the
|
||||||
[`grep-matcher`](https://crates.io/crates/grep-matcher)
|
[`grep-matcher`](https://crates.io/crates/grep-matcher) crate) is a trait
|
||||||
crate) is a trait for describing the lowest levels of pattern search in a
|
for describing the lowest levels of pattern search in a generic way. The
|
||||||
generic way. The interface itself is very similar to the interface of a regular
|
interface itself is very similar to the interface of a regular expression.
|
||||||
expression. For example, the
|
For example, the [`grep-regex`](https://crates.io/crates/grep-regex)
|
||||||
[`grep-regex`](https://crates.io/crates/grep-regex)
|
|
||||||
crate provides an implementation of the `Matcher` trait using Rust's
|
crate provides an implementation of the `Matcher` trait using Rust's
|
||||||
[`regex`](https://crates.io/crates/regex)
|
[`regex`](https://crates.io/crates/regex) crate.
|
||||||
crate.
|
|
||||||
|
|
||||||
Finally, a `Sink` describes how callers receive search results producer by a
|
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
|
`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
|
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
|
lines are found by the `Searcher`. Implementations of `Sink` can be trivially
|
||||||
simple, or extraordinarily complex, such as the
|
simple, or extraordinarily complex, such as the `Standard` printer found in
|
||||||
`Standard` printer found in the
|
the [`grep-printer`](https://crates.io/crates/grep-printer) crate, which
|
||||||
[`grep-printer`](https://crates.io/crates/grep-printer)
|
effectively implements grep-like output. This crate also provides convenience
|
||||||
crate, which effectively implements grep-like output.
|
`Sink` implementations in the [`sinks`] sub-module for easy searching with
|
||||||
This crate also provides convenience `Sink` implementations in the
|
closures.
|
||||||
[`sinks`](sinks/index.html)
|
|
||||||
sub-module for easy searching with closures.
|
|
||||||
|
|
||||||
# Example
|
# Example
|
||||||
|
|
||||||
This example shows how to execute the searcher and read the search results
|
This example shows how to execute the searcher and read the search results
|
||||||
using the
|
using the [`UTF8`](sinks::UTF8) implementation of `Sink`.
|
||||||
[`UTF8`](sinks/struct.UTF8.html)
|
|
||||||
implementation of `Sink`.
|
|
||||||
|
|
||||||
```
|
```
|
||||||
use std::error::Error;
|
use std::error::Error;
|
||||||
|
@ -114,9 +114,8 @@ impl BinaryDetection {
|
|||||||
|
|
||||||
/// An encoding to use when searching.
|
/// An encoding to use when searching.
|
||||||
///
|
///
|
||||||
/// An encoding can be used to configure a
|
/// An encoding can be used to configure a [`SearcherBuilder`] to transcode
|
||||||
/// [`SearcherBuilder`](struct.SearchBuilder.html)
|
/// source data from an encoding to UTF-8 before searching.
|
||||||
/// to transcode source data from an encoding to UTF-8 before searching.
|
|
||||||
///
|
///
|
||||||
/// An `Encoding` will always be cheap to clone.
|
/// An `Encoding` will always be cheap to clone.
|
||||||
#[derive(Clone, Debug)]
|
#[derive(Clone, Debug)]
|
||||||
@ -508,8 +507,7 @@ impl SearcherBuilder {
|
|||||||
///
|
///
|
||||||
/// The binary detection strategy determines not only how the searcher
|
/// The binary detection strategy determines not only how the searcher
|
||||||
/// detects binary data, but how it responds to the presence of binary
|
/// detects binary data, but how it responds to the presence of binary
|
||||||
/// data. See the [`BinaryDetection`](struct.BinaryDetection.html) type
|
/// data. See the [`BinaryDetection`] type for more information.
|
||||||
/// for more information.
|
|
||||||
///
|
///
|
||||||
/// By default, binary detection is disabled.
|
/// By default, binary detection is disabled.
|
||||||
pub fn binary_detection(
|
pub fn binary_detection(
|
||||||
@ -616,8 +614,7 @@ impl Searcher {
|
|||||||
/// Create a new searcher with a default configuration.
|
/// Create a new searcher with a default configuration.
|
||||||
///
|
///
|
||||||
/// To configure the searcher (e.g., invert matching, enable memory maps,
|
/// To configure the searcher (e.g., invert matching, enable memory maps,
|
||||||
/// enable contexts, etc.), use the
|
/// enable contexts, etc.), use the [`SearcherBuilder`].
|
||||||
/// [`SearcherBuilder`](struct.SearcherBuilder.html).
|
|
||||||
pub fn new() -> Searcher {
|
pub fn new() -> Searcher {
|
||||||
SearcherBuilder::new().build()
|
SearcherBuilder::new().build()
|
||||||
}
|
}
|
||||||
@ -817,9 +814,8 @@ impl Searcher {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/// The following methods permit querying the configuration of a searcher.
|
/// The following methods permit querying the configuration of a searcher.
|
||||||
/// These can be useful in generic implementations of
|
/// These can be useful in generic implementations of [`Sink`], where the
|
||||||
/// [`Sink`](trait.Sink.html),
|
/// output may be tailored based on how the searcher is configured.
|
||||||
/// where the output may be tailored based on how the searcher is configured.
|
|
||||||
impl Searcher {
|
impl Searcher {
|
||||||
/// Returns the line terminator used by this searcher.
|
/// Returns the line terminator used by this searcher.
|
||||||
#[inline]
|
#[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 a match is found. Callers must provide this.
|
||||||
/// * What to do when an error occurs. Callers must provide this via the
|
/// * What to do when an error occurs. Callers must provide this via the
|
||||||
/// [`SinkError`](trait.SinkError.html) trait. Generally, callers can just
|
/// [`SinkError`] trait. Generally, callers can just use `io::Error` for
|
||||||
/// use `io::Error` for this, which already implements `SinkError`.
|
/// this, which already implements `SinkError`.
|
||||||
/// * What to do when a contextual line is found. By default, these are
|
/// * What to do when a contextual line is found. By default, these are
|
||||||
/// ignored.
|
/// ignored.
|
||||||
/// * What to do when a gap between contextual lines has been found. By
|
/// * 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
|
/// For simpler uses of `Sink`, callers may elect to use one of
|
||||||
/// the more convenient but less flexible implementations in the
|
/// the more convenient but less flexible implementations in the
|
||||||
/// [`sinks`](sinks/index.html) module.
|
/// [`sinks`] module.
|
||||||
pub trait Sink {
|
pub trait Sink {
|
||||||
/// The type of an error that should be reported by a searcher.
|
/// The type of an error that should be reported by a searcher.
|
||||||
///
|
///
|
||||||
|
Loading…
x
Reference in New Issue
Block a user