Trait grep_searcher::Sink
source · pub trait Sink {
type Error: SinkError;
// Required method
fn matched(
&mut self,
_searcher: &Searcher,
_mat: &SinkMatch<'_>
) -> Result<bool, Self::Error>;
// Provided methods
fn context(
&mut self,
_searcher: &Searcher,
_context: &SinkContext<'_>
) -> Result<bool, Self::Error> { ... }
fn context_break(
&mut self,
_searcher: &Searcher
) -> Result<bool, Self::Error> { ... }
fn binary_data(
&mut self,
_searcher: &Searcher,
_binary_byte_offset: u64
) -> Result<bool, Self::Error> { ... }
fn begin(&mut self, _searcher: &Searcher) -> Result<bool, Self::Error> { ... }
fn finish(
&mut self,
_searcher: &Searcher,
_: &SinkFinish
) -> Result<(), Self::Error> { ... }
}Expand description
A trait that defines how results from searchers are handled.
In this crate, a searcher follows the “push” model. What that means is that the searcher drives execution, and pushes results back to the caller. This is in contrast to a “pull” model where the caller drives execution and takes results as they need them. These are also known as “internal” and “external” iteration strategies, respectively.
For a variety of reasons, including the complexity of the searcher implementation, this crate chooses the “push” or “internal” model of execution. Thus, in order to act on search results, callers must provide an implementation of this trait to a searcher, and the searcher is then responsible for calling the methods on this trait.
This trait defines several behaviors:
- 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
SinkErrortrait. Generally, callers can just usestd::io::Errorfor this, which already implementsSinkError. - 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 default, this is ignored.
- What to do when a search has started. By default, this does nothing.
- What to do when a search has finished successfully. By default, this does nothing.
Callers must, at minimum, specify the behavior when an error occurs and
the behavior when a match occurs. The rest is optional. For each behavior,
callers may report an error (say, if writing the result to another
location failed) or simply return false if they want the search to stop
(e.g., when implementing a cap on the number of search results to show).
When errors are reported (whether in the searcher or in the implementation
of Sink), then searchers quit immediately without calling finish.
For simpler uses of Sink, callers may elect to use one of
the more convenient but less flexible implementations in the
sinks module.
Required Associated Types§
sourcetype Error: SinkError
type Error: SinkError
The type of an error that should be reported by a searcher.
Errors of this type are not only returned by the methods on this
trait, but the constructors defined in SinkError are also used in
the searcher implementation itself. e.g., When a I/O error occurs when
reading data from a file.
Required Methods§
sourcefn matched(
&mut self,
_searcher: &Searcher,
_mat: &SinkMatch<'_>
) -> Result<bool, Self::Error>
fn matched( &mut self, _searcher: &Searcher, _mat: &SinkMatch<'_> ) -> Result<bool, Self::Error>
This method is called whenever a match is found.
If multi line is enabled on the searcher, then the match reported here may span multiple lines and it may include multiple matches. When multi line is disabled, then the match is guaranteed to span exactly one non-empty line (where a single line is, at minimum, a line terminator).
If this returns true, then searching continues. If this returns
false, then searching is stopped immediately and finish is called.
If this returns an error, then searching is stopped immediately,
finish is not called and the error is bubbled back up to the caller
of the searcher.
Provided Methods§
sourcefn context(
&mut self,
_searcher: &Searcher,
_context: &SinkContext<'_>
) -> Result<bool, Self::Error>
fn context( &mut self, _searcher: &Searcher, _context: &SinkContext<'_> ) -> Result<bool, Self::Error>
This method is called whenever a context line is found, and is optional
to implement. By default, it does nothing and returns true.
In all cases, the context given is guaranteed to span exactly one non-empty line (where a single line is, at minimum, a line terminator).
If this returns true, then searching continues. If this returns
false, then searching is stopped immediately and finish is called.
If this returns an error, then searching is stopped immediately,
finish is not called and the error is bubbled back up to the caller
of the searcher.
sourcefn context_break(&mut self, _searcher: &Searcher) -> Result<bool, Self::Error>
fn context_break(&mut self, _searcher: &Searcher) -> Result<bool, Self::Error>
This method is called whenever a break in contextual lines is found,
and is optional to implement. By default, it does nothing and returns
true.
A break can only occur when context reporting is enabled (that is,
either or both of before_context or after_context are greater than
0). More precisely, a break occurs between non-contiguous groups of
lines.
If this returns true, then searching continues. If this returns
false, then searching is stopped immediately and finish is called.
If this returns an error, then searching is stopped immediately,
finish is not called and the error is bubbled back up to the caller
of the searcher.
sourcefn binary_data(
&mut self,
_searcher: &Searcher,
_binary_byte_offset: u64
) -> Result<bool, Self::Error>
fn binary_data( &mut self, _searcher: &Searcher, _binary_byte_offset: u64 ) -> Result<bool, Self::Error>
This method is called whenever binary detection is enabled and binary data is found. If binary data is found, then this is called at least once for the first occurrence with the absolute byte offset at which the binary data begins.
If this returns true, then searching continues. If this returns
false, then searching is stopped immediately and finish is called.
If this returns an error, then searching is stopped immediately,
finish is not called and the error is bubbled back up to the caller
of the searcher.
By default, it does nothing and returns true.
sourcefn begin(&mut self, _searcher: &Searcher) -> Result<bool, Self::Error>
fn begin(&mut self, _searcher: &Searcher) -> Result<bool, Self::Error>
This method is called when a search has begun, before any search is executed. By default, this does nothing.
If this returns true, then searching continues. If this returns
false, then searching is stopped immediately and finish is called.
If this returns an error, then searching is stopped immediately,
finish is not called and the error is bubbled back up to the caller
of the searcher.