TextFilter Class

Definition

Namespace

Bodu.Text.Filtering

Assembly

Bodu.Text.Filtering.dll

Package

Bodu.Text.Filtering 1.0.0

Source

TextFilter.CompiledPattern.cs

Represents an immutable, compiled include/exclude text filter that evaluates values against a set of wildcard and regular-expression patterns, running the cheapest pattern strategies first.

public sealed class TextFilter

Inheritance

object

TextFilter

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Remarks

A filter is built once from its patterns via Build(IEnumerable<TextFilterPattern>) (or parsed from raw lines via Parse(IEnumerable<string>)) and then evaluated many times. At build time every wildcard pattern is classified into the cheapest strategy its shape permits - whole-string equality for literals, prefix/suffix comparison for abc* / *abc / abc*def, substring search for *abc*, the general wildcard matcher otherwise - and regular expressions compile preferring the linear-time NonBacktracking engine. In AnyMatch mode the include and exclude groups are additionally evaluated cheapest-strategy-first, which cannot change the outcome because group matching is an order-independent OR.

Semantics. In AnyMatch (the default), a value is accepted when the include set is empty or at least one include matches, and no exclude matches - the Ant / MSBuild model. In LastMatchWins, the last matching rule decides and unmatched values are included - the gitignore model.

Thread safety. The compiled matching state is immutable, so IsMatch(string), Evaluate(ReadOnlySpan<char>), and the filtering members are safe for concurrent use and always produce exact results. The statistics counters are deliberately not interlocked and may undercount under concurrent evaluation; see TextFilterStatistics.

Properties

IgnoreCase

Gets a value indicating whether patterns without a per-pattern override match case-insensitively.

public bool IgnoreCase { get; }

Property Value

bool

Mode

Gets the evaluation mode this filter was built with.

public TextFilterEvaluationMode Mode { get; }

Property Value

TextFilterEvaluationMode

Observer

Gets or sets the observer notified of every evaluation decision, or null for none.

public ITextFilterObserver? Observer { get; set; }

Property Value

ITextFilterObserver

Remarks

When unset the evaluation path pays only a single null check. The observer is invoked synchronously on the evaluating thread; exceptions it throws propagate to the caller of the evaluating member.

Patterns

Gets the declared patterns in declaration order.

public IReadOnlyList<TextFilterPattern> Patterns { get; }

Property Value

IReadOnlyList<TextFilterPattern>

Methods

Build(IEnumerable<TextFilterPattern>)

Builds a filter from the specified patterns with default options.

public static TextFilter Build(IEnumerable<TextFilterPattern> patterns)

Parameters

patterns IEnumerable<TextFilterPattern>

The patterns to compile. Must not be null or contain null entries.

Returns

TextFilter

The compiled filter.

Remarks

An empty pattern set is legal and yields a filter that accepts every value.

Exceptions

ArgumentNullException

patterns is null.

ArgumentException

patterns contains a null entry, a wildcard pattern is malformed, or a regular-expression pattern is not valid (the original parse failure is preserved as the inner exception).

Build(IEnumerable<TextFilterPattern>, TextFilterOptions?)

Builds a filter from the specified patterns and options.

public static TextFilter Build(IEnumerable<TextFilterPattern> patterns, TextFilterOptions? options)

Parameters

patterns IEnumerable<TextFilterPattern>

The patterns to compile. Must not be null or contain null entries.

options TextFilterOptions

The build options, or null for defaults.

Returns

TextFilter

The compiled filter.

Remarks

An empty pattern set is legal and yields a filter that accepts every value.

Exceptions

ArgumentNullException

patterns is null.

ArgumentException

patterns contains a null entry, a wildcard pattern is malformed, or a regular-expression pattern is not valid (the original parse failure is preserved as the inner exception).

ArgumentOutOfRangeException

The options carry an undefined Mode or a RegexMatchTimeout that is neither positive nor InfiniteMatchTimeout.

Evaluate(ReadOnlySpan<char>)

Evaluates the specified value and reports the decision together with the pattern that decided it.

public TextFilterResult Evaluate(ReadOnlySpan<char> value)

Parameters

value ReadOnlySpan<char>

The value to evaluate.

Returns

TextFilterResult

The decision and, when a pattern decided the outcome, that pattern.

Filter(IEnumerable<string>)

Filters a sequence, yielding the values the filter accepts in their source order.

public IEnumerable<string> Filter(IEnumerable<string> source)

Parameters

source IEnumerable<string>

The sequence to filter. Must not be null.

Returns

IEnumerable<string>

A deferred sequence of the accepted values.

Remarks

Evaluation is deferred: values are evaluated - and statistics updated - as the result is enumerated. null elements are dropped without being evaluated, since no pattern can match them.

Exceptions

ArgumentNullException

source is null.

FilterToList(IReadOnlyList<string>)

Filters an indexed list eagerly, returning the accepted values in their source order.

public List<string> FilterToList(IReadOnlyList<string> source)

Parameters

source IReadOnlyList<string>

The list to filter. Must not be null.

Returns

List<string>

A new list containing the accepted values.

Remarks

This is the bulk-throughput surface: a tight indexed loop with the result list pre-sized to the source count. null elements are dropped without being evaluated.

Exceptions

ArgumentNullException

source is null.

GetMatchingPatterns(ReadOnlySpan<char>)

Returns every declared pattern that matches the specified value, in declaration order.

public IReadOnlyList<TextFilterPattern> GetMatchingPatterns(ReadOnlySpan<char> value)

Parameters

value ReadOnlySpan<char>

The value to test.

Returns

IReadOnlyList<TextFilterPattern>

The matching patterns; empty when none match.

Remarks

This diagnostic surface tests all patterns without short-circuiting - unlike Evaluate(ReadOnlySpan<char>), which stops at the deciding pattern - and does not update the filter's statistics or invoke the observer. A pattern whose brace alternation expanded into several matchers is reported once. Regular-expression timeouts follow the same fail-safe rule as evaluation (a timed-out exclude reports as matching).

GetStatistics()

Returns an immutable snapshot of the filter's accumulated statistics.

public TextFilterStatistics GetStatistics()

Returns

TextFilterStatistics

The snapshot.

IsMatch(ReadOnlySpan<char>)

Determines whether the filter accepts the specified value.

public bool IsMatch(ReadOnlySpan<char> value)

Parameters

value ReadOnlySpan<char>

The value to evaluate.

Returns

bool

true when the value is accepted; otherwise false.

IsMatch(string)

Determines whether the filter accepts the specified value.

public bool IsMatch(string value)

Parameters

value string

The value to evaluate. Must not be null.

Returns

bool

true when the value is accepted; otherwise false.

Exceptions

ArgumentNullException

value is null.

Parse(IEnumerable<string>)

Builds a filter from raw pattern lines using the gitignore file conventions, with default options.

public static TextFilter Parse(IEnumerable<string> lines)

Parameters

lines IEnumerable<string>

The lines to parse. Must not be null or contain null entries.

Returns

TextFilter

The compiled filter.

Remarks

Each line is trimmed and parsed as a wildcard pattern: blank lines and lines starting with # are skipped, a leading ! makes the pattern an exclude, and ! / # escape a literal leading ! or #. Regular-expression patterns cannot be expressed in line form - declare them via TextFilterPattern or TextFilterBuilder.

Exceptions

ArgumentNullException

lines is null.

ArgumentException

lines contains a null entry, or a parsed pattern is empty or malformed.

Parse(IEnumerable<string>, TextFilterOptions?)

Builds a filter from raw pattern lines using the gitignore file conventions.

public static TextFilter Parse(IEnumerable<string> lines, TextFilterOptions? options)

Parameters

lines IEnumerable<string>

The lines to parse. Must not be null or contain null entries.

options TextFilterOptions

The build options, or null for defaults.

Returns

TextFilter

The compiled filter.

Remarks

Each line is trimmed and parsed as a wildcard pattern: blank lines and lines starting with # are skipped, a leading ! makes the pattern an exclude, and ! / # escape a literal leading ! or #. Combine with LastMatchWins for gitignore-faithful ordered-rule semantics.

Exceptions

ArgumentNullException

lines is null.

ArgumentException

lines contains a null entry, or a parsed pattern is empty or malformed.

ArgumentOutOfRangeException

The options carry an invalid value; see Build(IEnumerable<TextFilterPattern>, TextFilterOptions?).

ResetStatistics()

Resets every statistics counter to zero.

public void ResetStatistics()

Applies to

Product	Versions
.NET	8, 10