Trait grep_searcher::Sink

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> { ... }
}

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 SinkError trait. Generally, callers can just use std::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 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

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

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

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.

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.

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.

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.

fn finish( &mut self, _searcher: &Searcher, _: &SinkFinish, ) -> Result<(), Self::Error>

This method is called when a search has completed. By default, this does nothing.

If this returns an error, the error is bubbled back up to the caller of the searcher.

Implementations on Foreign Types

impl<'a, S: Sink> Sink for &'a mut S

type Error = <S as Sink>::Error

fn matched( &mut self, searcher: &Searcher, mat: &SinkMatch<'_>, ) -> Result<bool, S::Error>

fn context( &mut self, searcher: &Searcher, context: &SinkContext<'_>, ) -> Result<bool, S::Error>

fn context_break(&mut self, searcher: &Searcher) -> Result<bool, S::Error>

fn binary_data( &mut self, searcher: &Searcher, binary_byte_offset: u64, ) -> Result<bool, S::Error>

fn begin(&mut self, searcher: &Searcher) -> Result<bool, S::Error>

fn finish( &mut self, searcher: &Searcher, sink_finish: &SinkFinish, ) -> Result<(), S::Error>

impl<S: Sink + ?Sized> Sink for Box<S>

type Error = <S as Sink>::Error

fn matched( &mut self, searcher: &Searcher, mat: &SinkMatch<'_>, ) -> Result<bool, S::Error>

fn context( &mut self, searcher: &Searcher, context: &SinkContext<'_>, ) -> Result<bool, S::Error>

fn context_break(&mut self, searcher: &Searcher) -> Result<bool, S::Error>

fn binary_data( &mut self, searcher: &Searcher, binary_byte_offset: u64, ) -> Result<bool, S::Error>

fn begin(&mut self, searcher: &Searcher) -> Result<bool, S::Error>

fn finish( &mut self, searcher: &Searcher, sink_finish: &SinkFinish, ) -> Result<(), S::Error>

Implementors

impl<F> Sink for Bytes<F>

where F: FnMut(u64, &[u8]) -> Result<bool, Error>,

type Error = Error

impl<F> Sink for Lossy<F>

where F: FnMut(u64, &str) -> Result<bool, Error>,

type Error = Error

impl<F> Sink for UTF8<F>

where F: FnMut(u64, &str) -> Result<bool, Error>,

type Error = Error