Bodu.Text.Filtering Namespace

Package: Bodu.Text.Filtering 1.0.0

Bodu.Text.Filtering

Purpose

Bodu.Text.Filtering filters lists of text values through include/exclude pattern sets - glob (wildcard) and regular-expression patterns compiled once into an immutable TextFilter that classifies every pattern by evaluation cost and runs the cheapest strategies first. The design deliberately adopts the models users already know: Ant / MSBuild-style unordered include/exclude sets, gitignore-style ordered last-match-wins rules with ! negation, and globset-style strategy extraction. Built-in telemetry reports what matched, what was vetoed, and by which pattern.

Sibling text libraries cover adjacent jobs: Bodu.Text.Encoding for binary-to-text codecs and Bodu.Text.Configuration for configuration documents.

Static documentation

Bodu.Text.Filtering introduction - the mental model, evaluation modes, and type map.
Bodu.Text.Filtering core concepts - vocabulary: actions, pattern kinds, modes, cost tiers, deciding patterns.
Bodu.Text.Filtering getting started - install and minimal samples.
Bodu.Text.Filtering guides - pattern grammar, evaluation modes, and telemetry deep dives.

Key types

TextFilter - the compiled engine: Build / Parse factories, IsMatch, Evaluate, Filter, statistics, and the observer hook.
TextFilterBuilder - fluent assembly (AddInclude / AddExclude / AddParsed) in the Microsoft.Extensions.FileSystemGlobbing style.
TextFilterPattern - one immutable rule: pattern text, include/exclude action, wildcard/regex kind, optional case override.
TextFilterOptions - evaluation mode, case default, regex match timeout, opt-in timing capture.
TextFilterEvaluationMode - AnyMatch sets (Ant / MSBuild) or LastMatchWins ordered rules (gitignore).
TextFilterResult / TextFilterDecision - the outcome of one evaluation and the pattern that decided it.
TextFilterStatistics / TextFilterPatternStatistics - the counters snapshot: decision buckets, per-pattern hit counts, regex timeouts, optional timing.
ITextFilterObserver - the per-decision callback hook; a single null check when unattached.

Example

using Bodu.Text.Filtering;

var filter = TextFilter.Parse(new[]
{
    "error*",        // include everything starting with "error"
    "warn*",         // ... or "warn"
    "!*debug*",      // but exclude anything containing "debug"
});

foreach (var line in filter.Filter(lines))
    Console.WriteLine(line);

var stats = filter.GetStatistics();   // evaluated / accepted / excluded, hits per pattern

Notes

Whole-string matching. Globs match the entire value; use *abc* for contains-style matching. Comparison is ordinal, case-insensitive by default, and overridable per filter and per pattern.
Cost-tiered evaluation. At build time each glob is classified - literal, prefix, suffix, contains, general wildcard - and regexes compile preferring the linear-time NonBacktracking engine; groups evaluate cheapest-first, which cannot change the outcome because set matching is an order-independent OR.
Fail-safe regex timeouts. A timed-out include does not admit the value; a timed-out exclude still vetoes it - and the event is visible in the statistics and to the observer.
See also: the introduction and the guides.

Classes

TextFilter: 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.

TextFilterBuilder: Provides a fluent builder for assembling the patterns of a TextFilter, in the style of Microsoft.Extensions.FileSystemGlobbing's Matcher.

TextFilterOptions: Provides configuration for building a TextFilter.

TextFilterPattern: Represents one immutable filtering rule: a pattern, the action taken when it matches, the syntax the pattern is written in, and an optional case-sensitivity override.

TextFilterPatternStatistics: Represents the accumulated statistics of one pattern within a TextFilterStatistics snapshot.

TextFilterStatistics: Represents an immutable snapshot of a TextFilter's accumulated evaluation statistics, obtained via GetStatistics().

Structs

TextFilterResult: Represents the outcome of evaluating a single value against a TextFilter: the decision reached and the pattern that decided it, if any.

Interfaces

ITextFilterObserver: Receives a callback for every value a TextFilter evaluates, carrying the decision reached and the pattern that decided it.

Enums

TextFilterAction: Specifies whether a TextFilterPattern admits or rejects the values it matches.

TextFilterDecision: Identifies the outcome of evaluating a value against a TextFilter.

TextFilterEvaluationMode: Specifies how a TextFilter combines its patterns when deciding whether a value is accepted.

TextFilterPatternKind: Specifies the syntax used to interpret the text of a TextFilterPattern.

Table of Contents