Wildcard 2.7.0

Wildcard

A high-performance .NET 10 library for wildcard pattern matching. Provides a lightweight alternative to the full Regex engine, optimized for speed and zero allocations on the hot path.

Requirements

• .NET 10.0 or later

Supported Syntax

Glob-only Syntax

Usage

// One-shot match
bool matches = WildcardPattern.IsMatch("*.cs", "program.cs"); // true

// Pre-compiled pattern (reuse across many inputs)
var pattern = WildcardPattern.Compile("file?.log");
pattern.IsMatch("file1.log"); // true
pattern.IsMatch("fileAB.log"); // false

// Case-insensitive matching
WildcardPattern.IsMatch("HELLO", "hello", ignoreCase: true); // true

// Brace alternation — match any of the comma-separated alternatives
WildcardPattern.IsMatch("*.{cs,fs,vb}", "program.cs");       // true
WildcardPattern.IsMatch("{error,warn}*", "error: timeout");   // true
WildcardPattern.IsMatch("{get,set}_{name,value}", "get_name");// true

// TryMatch — extract what each * captured
var p = WildcardPattern.Compile("\\[*\\] * - *");
if (p.TryMatch("[2024-03-15] ERROR - timeout", out var captures))
{
    // captures: ["2024-03-15", "ERROR", "timeout"]
}

// LINQ extensions
string[] files = ["app.cs", "readme.md", "test.cs", "data.csv"];
var csFiles = files.WhereMatch("*.cs").ToList();       // ["app.cs", "test.cs"]
bool hasCsv = files.AnyMatch(WildcardPattern.Compile("*.csv")); // true
string? first = files.FirstMatch(WildcardPattern.Compile("*.md")); // "readme.md"

// Convert to Regex for interop
Regex regex = WildcardPattern.Compile("*.csv").ToRegex();
// regex.ToString() == "^.*\\.csv$"

// Bulk filtering
var pattern = WildcardPattern.Compile("*.cs");
List<string> csharpFiles = WildcardSearch.FilterLines(pattern, files);

// Parallel bulk filtering for large datasets
string[] results = WildcardSearch.FilterBulk(pattern, largeArray, parallel: true);

File Content Scanning

FilePathMatcher scans files on disk for lines matching wildcard patterns using memory-mapped I/O.

// Single include pattern
var matcher = FilePathMatcher.Create("*ERROR*");
List<FilePathMatcher.LineMatch> matches = matcher.Scan("app.log", "server.log");

foreach (var match in matches)
    Console.WriteLine($"{match.FilePath}:{match.LineNumber}: {match.Line}");

// Multiple include patterns — OR logic (match lines containing ERROR or WARN)
var matcher = FilePathMatcher.Create(
    include: ["*ERROR*", "*WARN*"]
);
var matches = matcher.Scan("app.log");

// Include/exclude patterns — match lines containing ERROR but not DEBUG
var matcher = FilePathMatcher.Create(
    include: ["*ERROR*"],
    exclude: ["*DEBUG*"]
);
var matches = matcher.Scan("app.log");

// Async streaming — results arrive as they are found
var matcher = FilePathMatcher.Create("*timeout*");
await foreach (var match in matcher.ScanAsync(filePaths))
    Console.WriteLine(match.Line);

// Context lines — like grep -C 3 (3 lines before and after each match)
var matcher = FilePathMatcher.Create("*ERROR*");
List<FilePathMatcher.ContextLine> results = matcher.ScanWithContext(
    beforeContext: 3, afterContext: 3, "app.log");

foreach (var line in results)
{
    var sep = line.IsMatch ? ":" : "-";
    Console.WriteLine($"{line.LineNumber}{sep} {line.Line}");
}

File System Globbing

Glob matches file paths on disk with support for *, ?, [abc], ** (recursive directory matching), and {a,b,c} (brace expansion).

// Find all .cs files recursively
var files = Glob.Match("src/**/*.cs").ToList();

// Brace expansion — match multiple extensions in one pattern
var webFiles = Glob.Match("**/*.{razor,cs,css}").ToList();

// Single directory level
var logs = Glob.Match("/var/log/*.log").ToList();

// Respect .gitignore — skips bin/, obj/, node_modules/, .git/ etc.
var tracked = Glob.Match("**/*.cs", options: new GlobOptions { RespectGitignore = true }).ToList();

// Follow symbolic links (off by default, matching ripgrep behavior)
var withSymlinks = Glob.Match("**/*.cs", options: new GlobOptions { FollowSymlinks = true }).ToList();

// Pre-parsed glob for reuse
var glob = Glob.Parse("**/*.json");
foreach (var file in glob.EnumerateMatches("/my/project"))
    Console.WriteLine(file);

Find and Replace

FileReplacer performs find-and-replace across files with dry-run preview, atomic writes, and encoding preservation.

// Preview replacements (no files modified)
var results = FileReplacer.Preview(filePaths, "oldMethod", "newMethod");
foreach (var file in results)
    foreach (var r in file.Replacements)
        Console.WriteLine($"{file.FilePath}:{r.LineNumber}: {r.OriginalLine} → {r.ReplacedLine}");

// Apply replacements (atomic write per file)
FileReplacer.Apply(filePaths, "ERROR", "WARNING", ignoreCase: true);

// Capture-group replacement — wildcards in find, $1/$2 in replace
var results = FileReplacer.Preview(filePaths, "*console.log(*)*", "$1logger.info($2)$3");

Safety: skips binary files, read-only files, and files over 10MB. Preserves encoding (BOM) and line endings (\r\n/\n). Writes atomically via temp file + rename. If a file fails (permissions, locked), the error is reported and the remaining files continue processing.

CLI Tool — wcg

A command-line grep tool built on top of the library. Respects .gitignore by default, streams results as they're found.

Install

Option A — .NET tool (cross-platform, requires .NET 10 runtime):

dotnet tool install -g wcg
dotnet tool update -g wcg   # to update

Option B — Native binary (single file, no dependencies, ~4MB):

Download the latest binary for your platform from GitHub Releases:

# macOS / Linux
chmod +x wcg-osx-arm64
sudo mv wcg-osx-arm64 /usr/local/bin/wcg

Usage

wcg <glob> [<pattern>...] [options]

Arguments:
  <glob>      File glob pattern (e.g. "src/**/*.cs")
  <pattern>   Content search pattern(s) — multiple patterns are OR'd (e.g. ERROR WARN). Plain words match as substrings; use wildcards for prefix/suffix/full patterns (e.g. "ERROR*", "*.log").

Options:
  -x, --exclude <pattern>   Exclude lines matching pattern (repeatable)
  -X, --exclude-path <glob> Exclude files matching glob (repeatable)
  -i, --ignore-case         Case-insensitive content matching
  -l, --files-with-matches  Only print file paths that contain matches
  --no-ignore               Don't respect .gitignore files
  -L, --follow              Follow symbolic links
  -w, --watch               Watch for changes after initial scan
  -A, --after-context <N>   Show N lines after each match
  -B, --before-context <N>  Show N lines before each match
  -C, --context <N>         Show N lines before and after each match
  -c, --count               Show count of matching lines per file
  -r, --replace <text>      Replace matched content with this string (dry-run preview)
  --write                   Write replacements to files (requires --replace)

Examples:

wcg "src/**/*.cs"                         # List matching files
wcg "**/*.log" ERROR                      # Search for lines containing ERROR
wcg "**/*.log" ERROR WARN                 # OR mode — containing ERROR or WARN
wcg "**/*.cs" TODO -x DONE               # Search TODO, exclude DONE
wcg "**/*.cs" TODO FIXME -x DONE         # Search TODO or FIXME, exclude DONE
wcg "**/*.cs" TODO -i                    # Case-insensitive search
wcg "**/*.log" ERROR --watch             # Watch for new ERROR lines
wcg "**/*" class -X "*test*"             # Search, skip test paths
wcg "**/*.cs" --no-ignore               # Include .gitignore'd files
wcg "**/*.cs" -L                         # Follow symbolic links
wcg "**/*.cs" TODO -C 3                  # Show 3 lines of context around matches
wcg "**/*.log" ERROR -B 2 -A 5          # 2 lines before, 5 lines after each match

# Plain words are auto-wrapped as *word* (substring match).
# Use explicit wildcards for prefix/suffix/pattern matching:
wcg "**/*.cs" "using*"                   # Lines starting with "using"
wcg "**/*.log" "*.json"                  # Lines ending with ".json"
wcg "**/*.log" "*ERROR*timeout*"         # Multi-segment wildcard

# ? matches exactly one character:
wcg "**/*.log" "ERR?R"                   # Matches ERROR, ERRIR, ERR0R, …
wcg "**/*.log" "v?.?.?"                  # Matches v1.2.3, v2.0.1, …

# Character classes:
wcg "**/*.log" "HTTP [45]??"            # HTTP 4xx or 5xx — [45] + two ?? digits
wcg "**/*.log" "[EIWD]*"                # Lines starting with E, I, W or D (ERROR/INFO/WARN/DEBUG)
wcg "**/*.log" "[!D]*"                  # Lines not starting with D (excludes DEBUG)

# Brace alternation in content patterns:
wcg "**/*.log" "{ERROR,WARN}*"          # Lines starting with ERROR or WARN
wcg "**/*.cs" "{TODO,FIXME,HACK}*"      # Lines starting with any of those markers

# Count mode:
wcg "**/*.cs" TODO -c                   # Per-file match counts + summary
wcg "**/*.cs" TODO -c -l                # Summary only (total matches and files)
wcg "**/*.cs" -c                        # Count matching files (no content pattern)

# Find and replace (dry-run preview by default):
wcg "**/*.cs" oldMethod --replace newMethod          # Preview replacements
wcg "**/*.cs" oldMethod --replace newMethod --write  # Apply changes
wcg "**/*.cs" ERROR --replace WARNING -i             # Case-insensitive replace

# Capture-group replacement (wildcards in find, $1/$2 in replace):
wcg "**/*.cs" "*console.log(*)*" -r '$1logger.info($2)$3'  # Refactor method calls

Benchmarks

Measured on Apple M4 Pro, .NET 10.0, Arm64 RyuJIT AdvSIMD. Zero allocations for all single-match operations.

Pattern Matching — Wildcard vs Compiled Regex vs FileSystemName

Real-World Patterns — Wildcard vs Compiled Regex

Bulk Filtering — 10,000 Items

File Content Scanning — FilePathMatcher

Pattern *ERROR* across 4 log files (~12.5% matching lines). Compared against File.ReadAllLines + FilterLines baseline.

CLI — wcg vs find+grep, ripgrep

Real-world content search on ~/Code (~130k files across multiple git repos). Apple M4 Pro, .NET 10.0.

wcg is within 19% of ripgrep for content search. .gitignore filtering (on by default) prunes bin/, obj/, node_modules/ etc. during traversal. Work-stealing parallel glob overlaps directory enumeration with I/O-bound content scanning. The native AOT binary adds ~10% wall-clock improvement and 10ms cold startup.

How It Works

1. Pattern Compilation

PatternCompiler.Compile parses a pattern string into an array of Segment objects. Each segment is one of five types:

• Literal — a fixed string to match exactly (e.g. ".cs")
• Star — the * wildcard, matches any character sequence
• QuestionMark — the ? wildcard, matches exactly one character
• QuestionRun — consecutive ? characters collapsed into a single segment with a count
• CharClass — a character set like [a-z], optionally negated, using SearchValues<char> for SIMD-accelerated lookups

Consecutive * characters are collapsed into a single Star segment during compilation. Single-character, non-negated character classes (e.g. [[]) are promoted to Literal segments and merged with adjacent literals.

Brace expansion — patterns containing {a,b,c} are expanded by BraceExpander into multiple alternative patterns before compilation. For example, *.{cs,fs} becomes ["*.cs", "*.fs"]. Each alternative is compiled independently and stored as a WildcardPattern[]. Matching succeeds if any alternative matches. Patterns without braces skip this step entirely (zero overhead).

2. Pattern Shape Specialization

At compile time, common pattern shapes are detected and dispatched to optimized fast-paths that bypass the general matching engine entirely:

All other patterns fall through to the general backtracking engine.

3. Matching Engine

MatchCore walks the segment array and the input string simultaneously using a backtracking algorithm:

• Two pointers track the current position in the segments and the input.
• When a * segment is encountered, the engine records its position as a backtrack point and advances to the next segment.
• If a subsequent segment fails to match, the engine backtracks to the last * position and tries consuming one more character from the input.
• IndexOf acceleration — when a * is followed by a literal, the engine uses Span.IndexOf to jump directly to the next occurrence instead of scanning character-by-character.
• EndsWith fast-path — when a * is followed by the final literal segment, the engine checks EndsWith instead of scanning.

This approach avoids the exponential worst-case that naive recursive implementations can hit.

4. Performance Techniques

• Zero-copy matching — uses ReadOnlySpan<char> to avoid string allocations during matching.
• Aggressive inlining — hot-path methods like MatchLiteral and CharsEqual use [MethodImpl(MethodImplOptions.AggressiveInlining)].
• SIMD-accelerated character classes — SearchValues<char> provides hardware-accelerated membership testing. For case-insensitive patterns, both upper and lower case variants are expanded at compile time so the SIMD path works unconditionally.
• ref readonly struct access — segments are accessed by reference in the hot loop to avoid copying the struct on each iteration.
• Parallel bulk operations — WildcardSearch.FilterBulk processes arrays of 1024+ items in parallel using PLINQ with order preservation.

5. File Content Scanning

FilePathMatcher scans files on disk using memory-mapped I/O and parallel processing:

• Adaptive file I/O — small files (≤64KB) use pooled buffered reads; larger files use memory-mapped I/O. Files over 2GB are processed in 1GB overlapping sections.
• Byte-level pre-filtering — for ASCII, case-sensitive patterns over UTF-8 data, pattern matching runs directly on raw bytes using SIMD-accelerated span operations (IndexOf, StartsWith, EndsWith). Lines that don't match skip UTF-8 decoding entirely. When multiple include patterns are given, each pattern gets its own byte-level filter; a line is skipped only when all filters reject it.
• Minimum length gate — lines shorter than the pattern's minimum possible match length are rejected before any decoding or matching.
• Parallel multi-file scanning — multiple files are scanned concurrently via Parallel.For, with results merged preserving file order.
• Async streaming — ScanAsync uses a bounded channel to stream matches as they are found.

Attribution

This project was generated with the assistance of Claude Opus 4.6 by Anthropic.