Struct grep_regex::RegexMatcherBuilder

pub struct RegexMatcherBuilder { /* private fields */ }

A builder for constructing a Matcher using regular expressions.

This builder re-exports many of the same options found on the regex crate’s builder, in addition to a few other options such as smart case, word matching and the ability to set a line terminator which may enable certain types of optimizations.

The syntax supported is documented as part of the regex crate: https://docs.rs/regex/#syntax.

Implementations

impl RegexMatcherBuilder

pub fn new() -> RegexMatcherBuilder

Create a new builder for configuring a regex matcher.

pub fn build(&self, pattern: &str) -> Result<RegexMatcher, Error>

Build a new matcher using the current configuration for the provided pattern.

The syntax supported is documented as part of the regex crate: https://docs.rs/regex/#syntax.

pub fn build_many<P: AsRef<str>>( &self, patterns: &[P] ) -> Result<RegexMatcher, Error>

Build a new matcher using the current configuration for the provided patterns. The resulting matcher behaves as if all of the patterns given are joined together into a single alternation. That is, it reports matches where at least one of the given patterns matches.

pub fn build_literals<B: AsRef<str>>( &self, literals: &[B] ) -> Result<RegexMatcher, Error>

Build a new matcher from a plain alternation of literals.

Depending on the configuration set by the builder, this may be able to build a matcher substantially faster than by joining the patterns with a | and calling build.

pub fn case_insensitive(&mut self, yes: bool) -> &mut RegexMatcherBuilder

Set the value for the case insensitive (i) flag.

When enabled, letters in the pattern will match both upper case and lower case variants.

pub fn case_smart(&mut self, yes: bool) -> &mut RegexMatcherBuilder

Whether to enable “smart case” or not.

When smart case is enabled, the builder will automatically enable case insensitive matching based on how the pattern is written. Namely, case insensitive mode is enabled when both of the following things are true:

1. The pattern contains at least one literal character. For example, a\w contains a literal (a) but \w does not.
2. Of the literals in the pattern, none of them are considered to be uppercase according to Unicode. For example, foo\pL has no uppercase literals but Foo\pL does.

pub fn multi_line(&mut self, yes: bool) -> &mut RegexMatcherBuilder

Set the value for the multi-line matching (m) flag.

When enabled, ^ matches the beginning of lines and $ matches the end of lines.

By default, they match beginning/end of the input.

pub fn dot_matches_new_line(&mut self, yes: bool) -> &mut RegexMatcherBuilder

Set the value for the any character (s) flag, where in . matches anything when s is set and matches anything except for new line when it is not set (the default).

N.B. “matches anything” means “any byte” when Unicode is disabled and means “any valid UTF-8 encoding of any Unicode scalar value” when Unicode is enabled.

pub fn swap_greed(&mut self, yes: bool) -> &mut RegexMatcherBuilder

Set the value for the greedy swap (U) flag.

When enabled, a pattern like a* is lazy (tries to find shortest match) and a*? is greedy (tries to find longest match).

By default, a* is greedy and a*? is lazy.

pub fn ignore_whitespace(&mut self, yes: bool) -> &mut RegexMatcherBuilder

Set the value for the ignore whitespace (x) flag.

When enabled, whitespace such as new lines and spaces will be ignored between expressions of the pattern, and # can be used to start a comment until the next new line.

pub fn unicode(&mut self, yes: bool) -> &mut RegexMatcherBuilder

Set the value for the Unicode (u) flag.

Enabled by default. When disabled, character classes such as \w only match ASCII word characters instead of all Unicode word characters.

pub fn octal(&mut self, yes: bool) -> &mut RegexMatcherBuilder

Whether to support octal syntax or not.

Octal syntax is a little-known way of uttering Unicode codepoints in a regular expression. For example, a, \x61, \u0061 and \141 are all equivalent regular expressions, where the last example shows octal syntax.

While supporting octal syntax isn’t in and of itself a problem, it does make good error messages harder. That is, in PCRE based regex engines, syntax like \0 invokes a backreference, which is explicitly unsupported in Rust’s regex engine. However, many users expect it to be supported. Therefore, when octal support is disabled, the error message will explicitly mention that backreferences aren’t supported.

Octal syntax is disabled by default.

pub fn size_limit(&mut self, bytes: usize) -> &mut RegexMatcherBuilder

Set the approximate size limit of the compiled regular expression.

This roughly corresponds to the number of bytes occupied by a single compiled program. If the program exceeds this number, then a compilation error is returned.

pub fn dfa_size_limit(&mut self, bytes: usize) -> &mut RegexMatcherBuilder

Set the approximate size of the cache used by the DFA.

This roughly corresponds to the number of bytes that the DFA will use while searching.

Note that this is a per thread limit. There is no way to set a global limit. In particular, if a regex is used from multiple threads simultaneously, then each thread may use up to the number of bytes specified here.

pub fn nest_limit(&mut self, limit: u32) -> &mut RegexMatcherBuilder

Set the nesting limit for this parser.

The nesting limit controls how deep the abstract syntax tree is allowed to be. If the AST exceeds the given limit (e.g., with too many nested groups), then an error is returned by the parser.

The purpose of this limit is to act as a heuristic to prevent stack overflow for consumers that do structural induction on an Ast using explicit recursion. While this crate never does this (instead using constant stack space and moving the call stack to the heap), other crates may.

This limit is not checked until the entire Ast is parsed. Therefore, if callers want to put a limit on the amount of heap space used, then they should impose a limit on the length, in bytes, of the concrete pattern string. In particular, this is viable since this parser implementation will limit itself to heap space proportional to the length of the pattern string.

Note that a nest limit of 0 will return a nest limit error for most patterns but not all. For example, a nest limit of 0 permits a but not ab, since ab requires a concatenation, which results in a nest depth of 1. In general, a nest limit is not something that manifests in an obvious way in the concrete syntax, therefore, it should not be used in a granular way.

pub fn line_terminator( &mut self, line_term: Option<u8> ) -> &mut RegexMatcherBuilder

Set an ASCII line terminator for the matcher.

The purpose of setting a line terminator is to enable a certain class of optimizations that can make line oriented searching faster. Namely, when a line terminator is enabled, then the builder will guarantee that the resulting matcher will never be capable of producing a match that contains the line terminator. Because of this guarantee, users of the resulting matcher do not need to slowly execute a search line by line for line oriented search.

If the aforementioned guarantee about not matching a line terminator cannot be made because of how the pattern was written, then the builder will return an error when attempting to construct the matcher. For example, the pattern a\sb will be transformed such that it can never match a\nb (when \n is the line terminator), but the pattern a\nb will result in an error since the \n cannot be easily removed without changing the fundamental intent of the pattern.

If the given line terminator isn’t an ASCII byte (<=127), then the builder will return an error when constructing the matcher.

pub fn ban_byte(&mut self, byte: Option<u8>) -> &mut RegexMatcherBuilder

Ban a byte from occurring in a regular expression pattern.

If this byte is found in the regex pattern, then an error will be returned at construction time.

This is useful when binary detection is enabled. Callers will likely want to ban the same byte that is used to detect binary data, i.e., the NUL byte. The reason for this is that when binary detection is enabled, it’s impossible to match a NUL byte because binary detection will either quit when one is found, or will convert NUL bytes to line terminators to avoid exorbitant heap usage.

pub fn crlf(&mut self, yes: bool) -> &mut RegexMatcherBuilder

Set the line terminator to \r\n and enable CRLF matching for $ in regex patterns.

This method sets two distinct settings:

1. It causes the line terminator for the matcher to be \r\n. Namely, this prevents the matcher from ever producing a match that contains a \r or \n.
2. It enables CRLF mode for ^ and $. This means that line anchors will treat both \r and \n as line terminators, but will never match between a \r and \n.

Note that if you do not wish to set the line terminator but would still like $ to match \r\n line terminators, then it is valid to call crlf(true) followed by line_terminator(None). Ordering is important, since crlf sets the line terminator, but line_terminator does not touch the crlf setting.

pub fn word(&mut self, yes: bool) -> &mut RegexMatcherBuilder

Require that all matches occur on word boundaries.

Enabling this option is subtly different than putting \b assertions on both sides of your pattern. In particular, a \b assertion requires that one side of it match a word character while the other match a non-word character. This option, in contrast, merely requires that one side match a non-word character.

For example, \b-2\b will not match foo -2 bar since - is not a word character. However, -2 with this word option enabled will match the -2 in foo -2 bar.

pub fn fixed_strings(&mut self, yes: bool) -> &mut RegexMatcherBuilder

Whether the patterns should be treated as literal strings or not. When this is active, all characters, including ones that would normally be special regex meta characters, are matched literally.

pub fn whole_line(&mut self, yes: bool) -> &mut RegexMatcherBuilder

Whether each pattern should match the entire line or not. This is equivalent to surrounding the pattern with (?m:^) and (?m:$).

Trait Implementations

impl Clone for RegexMatcherBuilder

fn clone(&self) -> RegexMatcherBuilder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RegexMatcherBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for RegexMatcherBuilder

fn default() -> RegexMatcherBuilder

Returns the “default value” for a type.