Pathological: Globbing

Welcome to the Pathological Globbing library. This library is a wrapper around the Microsoft.Extensions.FileSystemGlobbing NuGet package, which provides a fast, efficient, and cross-platform globbing functionality for .NET.

This library strives to simplify globbing by exposing a Glob type, which provides an approachable API for matching file paths against globbing patterns.

📦 Install

To install the Pathological.Globbing NuGet package, run the following command:

dotnet add package Pathological.Globbing

Alternatively, you can install the Pathological.Globbing NuGet package from the package manager in Visual Studio.

*️⃣ Usage

To use the Pathological.Globbing library, you must first create a Glob instance. The Glob instance is the entry point to the library, and provides a number of methods for matching file paths against globbing patterns.

using Pathological.Globbing;

var glob = new Glob();

// All js files, but don't look in node_modules
var files = glob.GetMatches("**/*.js", "node_modules/**");

foreach (var filePath in files)
{
    // Use file...
}

Note

There are various extensions methods that expose, in addition to a string representing the fully qualified file path of the matched file, a GlobMatch instance. The GlobMatch instance provides additional information about the matched file, it can also be used to easily convert to a FileInfo type as well.

📂 Streaming API

To use the streaming API, call any of the available IAsyncEnumerable<T> returning extension methods.

using Pathological.Globbing;

var glob = new Glob(basePath: "../");

// All js files, but don't look in node_modules
var files = glob.GetMatchesAsync("**/*.js", "node_modules/**");

await foreach (var file in files)
{
    // Use file...
}

Important

All streaming APIs support CancellationToken for signaling a manual cancellation, or TimeSpan for signaling cancellation after a certain amount of time.

☑️ Builder-pattern fluent API

To use the builder-pattern fluent API, create a new GlobOptionsBuilder instance, and chain any available With* method. When you're done, call Build which validates the options, and returns a GlobOptions instance. The GlobOptions instance can be used to execute the globbing operation.

using Pathological.Globbing;
using Pathological.Globbing.Options;

// Build glob options.
var builder = new GlobOptionsBuilder()
    .WithBasePath("../../")
    .WithCaseInsensitive(isCaseInsensitive: true)
    .WithPattern("**/*.cs")
    .WithIgnorePatterns(["**/bin/**", "**/obj/**"]);

// Build the globbing options.
var options = builder.Build();

// Get matching file infos.
var files = glob.GetMatchingFileInfos();

foreach (var fileInfo in files)
{
    // Use fileInfo...
}

// Alternatively, execute the globbing operation, evaluating results.
var result = options.ExecuteEvaluation();

_ = result.HasMatches;  // true
_ = result.Matches;     // IEnumerable<GlobMatch>

🔥 File-system globbing

This library relies on the Microsoft.Extensions.FileSystemGlobbing NuGet package for file-system globbing.

All of the following patterns are supported:

Exact directory or file name
- some-file.txt
- path/to/file.txt

Wildcards * in file and directory names that represent zero to many characters not including separator characters.

Value	Description
`*.txt`	All files with .txt file extension.
`.`	All files with an extension.
`*`	All files in top-level directory.
`.*`	File names beginning with '.'.
`word`	All files with 'word' in the filename.
`readme.*`	All files named 'readme' with any file extension.
`styles/*.css`	All files with extension '.css' in the directory 'styles/'.
`scripts//`	All files in 'scripts/' or one level of subdirectory under 'scripts/'.
`images/`	All files in a folder with name that is or begins with 'images'.

Arbitrary directory depth (/**/).

Value Description

**/* All files in any subdirectory.

dir/ All files in any subdirectory under 'dir/'.

dir/**/* All files in any subdirectory under 'dir/'.

Value	Description
`*/`	All files in any subdirectory.
`dir/`	All files in any subdirectory under 'dir/'.
`dir/*/`	All files in any subdirectory under 'dir/'.

For more information, see File globbing in .NET: Pattern formats.

ievangelist / pathological.globbing Goto Github PK