https://github.com/ievangelist/pathological.globbing
.NET globbing library—built atop Microsoft.Extensions.FileSystemGlobbing.
https://github.com/ievangelist/pathological.globbing
csharp dotnet file-system-globbing glob globber globbing globbing-library
Last synced: 5 months ago
JSON representation
.NET globbing library—built atop Microsoft.Extensions.FileSystemGlobbing.
- Host: GitHub
- URL: https://github.com/ievangelist/pathological.globbing
- Owner: IEvangelist
- License: mit
- Created: 2023-09-25T00:37:32.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-03T19:51:06.000Z (7 months ago)
- Last Synced: 2025-04-08T19:56:10.621Z (6 months ago)
- Topics: csharp, dotnet, file-system-globbing, glob, globber, globbing, globbing-library
- Language: C#
- Homepage:
- Size: 973 KB
- Stars: 7
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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.
```csharp
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` returning extension methods.
```csharp
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.
```csharp
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
```
## 🔥 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/'. |
For more information, see [File globbing in .NET: Pattern formats](https://learn.microsoft.com/dotnet/core/extensions/file-globbing#pattern-formats).