Ramstack.Globbing 2.1.0-preview.3

Ramstack.Globbing

Fast and zero-allocation .NET globbing library for matching file paths using glob patterns. No external dependencies.

Getting Started

To install the Ramstack.Globbing NuGet package to your project, run the following command:

dotnet add package Ramstack.Globbing

Usage

bool result = Matcher.IsMatch("wiki/section-1/start.md", "wiki/**/*.md");

The IsMatch method attempts to match the specified path against the provided wildcard pattern.

By default, the system's default path separators are used. You can override this behavior by specifying one of the following flags:

Example with a specific flag:

bool result = Matcher.IsMatch("wiki/section-1/start.md", @"wiki\**\*.md", MatchFlags.Windows);

Patterns

From Wikipedia

Pattern specific for directories

Brace patterns

Brace patterns allow for matching multiple alternatives in a single pattern. Here are some key features:

• Empty alternatives are valid, e.g., {src,test,} will also match paths without the listed prefixes.
• Brace patterns can be nested, allowing for complex matching scenarios.
• Full glob patterns can be used within braces, providing powerful and flexible matching capabilities.

Escaping characters

The meta characters ?, *, [, \ can be escaped by using the [], which means match one character listed in the bracket.

• [[] matches the literal [
• [*] matches the literal *

This works when using any MatchFlags (Windows or Unix). When using MatchFlags.Unix, an additional escape character (\) is available:

• \[ matches the literal [
• \* matches the literal *

Notes

• Leading and trailing path separators are ignored.
• Consecutive path separators are counted as one separator.

Special cases

• At the root level, an empty path segment is valid, which can be represented by patterns like "*".
• At any deeper level, an empty segment indicates that a required directory or file is missing, making the path invalid for patterns expecting something at that level.

💡 This means that the patterns */{} and */{,} cannot match any path due to the rule: an empty segment is not allowed beyond the root level.

Optimizations

We use optimizations that prevent quadratic behavior in scenarios like the pattern a*a*a*a*a*a*a*a*a*c matching against the text aaaaaaaaaaaaaaa...aaaa...aaa. Similarly, for the a/**/a/**/a/**/.../a/**/a/**/a/**/b pattern matching against a/a/a/a/.../a/.../a.

File traversal

The Files class provides functionality for traversing the file system and retrieving lists of files and directories based on specified glob patterns. This allows for flexible and efficient file and directory enumeration.

using Ramstack.Globbing.Traversal;

// List all *.cs files
var files = Files.EnumerateFiles(@"/path/to/directory", "**/*.cs");
foreach (var file in files)
    Console.WriteLine(file);

// List all *.cs files except in tests directory
var files = Files.EnumerateFiles(@"/path/to/directory", "**/*.cs", "tests");
foreach (var file in files)
    Console.WriteLine(file);

Support for multiple patterns is also included:

using Ramstack.Globbing.Traversal;

// List all *.cs files
var files = Files.EnumerateFiles(@"/path/to/directory", ["src/**/*.cs", "lib/**/*.cs"], ["**/tests"]);
foreach (var file in files)
    Console.WriteLine(file);

Changelog

2.0.0

• Added the ability to retrieve a list of files and directories based on a specified glob pattern.

BREAKING CHANGE

To improve code readability and adherence to .NET conventions, the order of parameters in the IsMatch method has been changed. The path parameter is now first, followed by the pattern parameter.

New signature

public static bool IsMatch(string path, string pattern, MatchFlags flags = MatchFlags.Auto)

Reasons for the change:

• Consistency with .NET methods: The primary object of an action is typically the first parameter. Here, path is the primary object, and pattern is the secondary.
• Alignment with common APIs: This order matches other .NET methods like Regex.IsMatch(string input, string pattern).
• Flexibility for future expansions: Having the most commonly varied parameter (pattern) second makes it easier to create intuitive method overloads in the future.
• Early stage of development: Since the library is newly released, we've made this change to ensure consistency from the start.

1.1.0

• Change target framework from multi-targeting (net6.0;net8.0) to single target net6.0
• Replace conditional compilation for .NET 8 with a universal approach

Supported versions

Contributions

Bug reports and contributions are welcome.

License

This package is released as open source under the MIT License. See the LICENSE file for more details.