[−][src]Crate grep_searcher
This crate provides an implementation of line oriented search, with optional support for multi-line search.
Brief overview
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
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
crate provides an implementation of the Matcher
trait using Rust's
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
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
implementation of Sink
.
extern crate grep_matcher; extern crate grep_regex; extern crate grep_searcher; use std::error::Error; use grep_matcher::Matcher; use grep_regex::RegexMatcher; use grep_searcher::Searcher; use grep_searcher::sinks::UTF8; const SHERLOCK: &'static [u8] = b"\ For the Doctor Watsons of this world, as opposed to the Sherlock Holmeses, success in the province of detective work must always be, to a very large extent, the result of luck. Sherlock Holmes can extract a clew from a wisp of straw or a flake of cigar ash; but Doctor Watson has to have it taken out for him and dusted, and exhibited clearly, with a label attached. "; fn example() -> Result<(), Box<Error>> { let matcher = RegexMatcher::new(r"Doctor \w+")?; let mut matches: Vec<(u64, String)> = vec![]; Searcher::new().search_slice(&matcher, SHERLOCK, UTF8(|lnum, line| { // We are guaranteed to find a match, so the unwrap is OK. let mymatch = matcher.find(line.as_bytes())?.unwrap(); matches.push((lnum, line[mymatch].to_string())); Ok(true) }))?; assert_eq!(matches.len(), 2); assert_eq!( matches[0], (1, "Doctor Watsons".to_string()) ); assert_eq!( matches[1], (5, "Doctor Watson".to_string()) ); Ok(()) }
See also examples/search-stdin.rs
from the root of this crate's directory
to see a similar example that accepts a pattern on the command line and
searches stdin.
Modules
sinks | A collection of convenience implementations of |
Structs
BinaryDetection | The behavior of binary detection while searching. |
Encoding | An encoding to use when searching. |
LineIter | An iterator over lines in a particular slice of bytes. |
LineStep | An explicit iterator over lines in a particular slice of bytes. |
MmapChoice | Controls the strategy used for determining when to use memory maps. |
Searcher | A searcher executes searches over a haystack and writes results to a caller provided sink. |
SearcherBuilder | A builder for configuring a searcher. |
SinkContext | A type that describes a contextual line reported by a searcher. |
SinkFinish | Summary data reported at the end of a search. |
SinkMatch | A type that describes a match reported by a searcher. |
Enums
ConfigError | An error that can occur when building a searcher. |
SinkContextKind | The type of context reported by a searcher. |
Traits
Sink | A trait that defines how results from searchers are handled. |
SinkError | A trait that describes errors that can be reported by searchers and
implementations of |