Fluently building and using file and directory paths without binary dependencies

About • How To Use • Download • Contributors • Versioning • Credits • Related • License

About

What's this?

Pathy is a tiny source-only library that will allow you to build file and directory paths by chaining together strings like "c:", "dir1", "dir2" using

ChainablePath.New() / "c:" / "dir1" / "dir2";

Note how the / operator is used to chain multiple parts of a path together. This is the primary feature of Pathy. And it doesn't matter if you do that on Linux or Windows. Internally it'll use whatever path separator is suitable.

You can also use the + operator to add some phrase to the path without using a separator.

var path = ChainablePath.From("c:") / "my-path" / "to" / "a" / "directory";

path = path + "2"

// Returns "c:/my-path/to/a/directory2"
string result = path.ToString();

It was heavily inspired by the best build pipeline framework available in the .NET space, Nuke. Nuke has supported these concepts for many years, but I needed this capability outside build pipelines. Lots of kudos to Matthias Koch for what I see as a brilliant idea.

What's so special about that?

It makes those chained calls to Path.Combine a thing from the past and hides the ugliness of dealing with (trailing) slashes.

It ships as a source-only package, which means you can use it in your own libraries and projects, without incurring any dependency pain on your consuming projects. It runs on .NET 4.7, .NET 8, as well as frameworks supporting .NET Standard 2.0 and 2.1.

The core Pathy package does not have any dependencies, and I purposely moved the globbing functionality into a separate package as it depends on Microsoft.Extensions.FileSystemGlobbing.

Who created this?

My name is Dennis Doomen and I'm a Microsoft MVP and Principal Consultant at Aviva Solutions with 28 years of experience under my belt. As a software architect and/or lead developer, I specialize in designing full-stack enterprise solutions based on .NET as well as providing coaching on all aspects of designing, building, deploying and maintaining software systems. I'm the author of several open-source projects such as Fluent Assertions, Reflectify, Liquid Projections, and I've been maintaining coding guidelines for C# since 2001.

Contact me through Email, Bluesky, Twitter/X or Mastadon

Download

This library is available as a NuGet package on https://nuget.org. To install it, use the following command-line:

dotnet add package Pathy

How do I use it?

To ChainablePath and back to string

It all starts with the construction of a ChainablePath instance to represent a path to a file or directory.

There are several ways of doing that.

// Various ways for constructing a ChainablePath 
var path = ChainablePath.From("c:") / "my-path" / "to" / "a" /"directory");
var path = ChainablePath.New() / "c:" / "my-path" / "to" / "a" / "directory";
var path = "c:/mypath/to/a/directory".ToPath();
var path = (ChainablePath)"c:/mypath/to/a/directory";

// Find the first available file in the order of appearance and return a
// ChainablePath representing that file
var path = ChainablePath.FindFirst("build.yml", ".github\\build.yml");

Additionally, you can use ChainablePath.Current to get the current working directory as an instance of ChainablePath, and ChainablePath.Temp to get that for the user's temporary folder.

To convert an instance of ChainablePath back to a string, you can either call ToString() or cast the instance to a string.

string rawPath = path.ToString();
string rawPath = (string)path;

Working with paths

Know that ChainablePath overrides Equals and GetHashCode, so you can always compare two instances as you're used to.

Given an instance of ChainablePath, you can get a lot of useful information:

• Name returns the full name, but without the directory, whereas Extension gives you the extension including the dot.
• Directory, Parent or DirectoryName give you the (parent) directory of a file or directory.
• The range operator .. in newer versions of .NET serves a similar purpose, e.g. path / .. / "file.txt"
• To see if a path is absolute, use IsRooted
• Not sure if a path points to an actual file system entry? Use IsFile, IsDirectory or Exists
• Want to know the delta between two paths? Use AsRelativeTo.
• To determine if a file has a case-insensitive extension, use HasExtension(".txt") or HasExtension("txt").
• To check if a path has a specific file or directory name (case-insensitive), use HasName("MyFile.txt").
• Get the last write time in UTC using LastWriteTimeUtc for both files and directories.

And if the built-in functionality really isn't enough, you can always call ToDirectoryInfo or ToFileInfo to continue with an instance of DirectoryInfo and FileInfo.

Other features

• Build an absolute path from a relative path using ToAbsolute to use the current directory as the base or ToAbsolute(parentPath) to use something else as the base.
• Finding the closest parent directory containing a file matching one or more wildcards. For example, given you have a ChainablePath pointing to a .csproj file, you can then use FindParentWithFileMatching("*.sln", "*.slnx") to find the directory containing the .sln or .slnx file.

Resolving files

If you have a ChainablePath that could represent either a file or a directory, and you want to resolve a specific file name, you can use the ResolveFile extension method:

// When the path is a directory containing the file
var directory = ChainablePath.From("c:/projects/myapp");
var configFile = directory.ResolveFile("appsettings.json");
// Returns: c:/projects/myapp/appsettings.json (if it exists)

// When the path is already the file itself
var filePath = ChainablePath.From("c:/projects/myapp/appsettings.json");
var resolved = filePath.ResolveFile("appsettings.json");
// Returns: c:/projects/myapp/appsettings.json (if it exists)

// When the file doesn't exist
var missing = directory.ResolveFile("missing.txt");
// Returns: ChainablePath.Empty

The method performs case-insensitive file name matching, so ResolveFile("CONFIG.JSON") will match config.json.

Globbing

If you add the Pathy.Globbing NuGet source-only package as well, you'll get access to the GlobFiles method. With that, you can fetch a collection of files like this:

// Match files with a single pattern
ChainablePath[] files = (ChainablePath.Current / "Artifacts").GlobFiles("**/*.json");

// Match files with multiple patterns
ChainablePath[] files = (ChainablePath.Current / "Artifacts").GlobFiles("**/*.txt", "**/*.md", "**/*.json");

File system operations

Next to that, Pathy also provides a bunch of extension methods to operate on the file-system:

• CreateDirectoryRecursively
• DeleteFileOrDirectory
• MoveFileOrDirectory

These methods also support operating on collections of ChainablePath objects:

// Delete multiple files or directories at once
var files = new[] { 
    ChainablePath.Temp / "file1.txt", 
    ChainablePath.Temp / "file2.txt",
    ChainablePath.Temp / "dir1" 
};
files.DeleteFileOrDirectory();

// Move multiple files to a destination directory
var filesToMove = (ChainablePath.Current / "source").GlobFiles("*.txt");
filesToMove.MoveFileOrDirectory(ChainablePath.Current / "destination");

Building

To build this repository locally so you can contribute to it, you need the following:

• The .NET SDKs for .NET 4.7, 8.0.
• Visual Studio, JetBrains Rider or Visual Studio Code with the C# DevKit

You can also build, run the unit tests and package the code using the following command-line:

build.ps1

Or, if you have, the Nuke tool installed:

nuke

Also try using --help to see all the available options or --plan to see what the scripts does.

Contributing

Your contributions are always welcome! Please have a look at the contribution guidelines first.

Previous contributors include:

(Made with contrib.rocks)

Versioning

This library uses Semantic Versioning to give meaning to the version numbers. For the versions available, see the tags on this repository.

Credits

This library wouldn't have been possible without the following tools, packages and companies:

• Nuke - Smart automation for DevOps teams and CI/CD pipelines by Matthias Koch
• xUnit - Community-focused unit testing tool for .NET by Brad Wilson
• Coverlet - Cross platform code coverage for .NET by Toni Solarin-Sodara
• GitVersion - From git log to SemVer in no time
• ReportGenerator - Converts coverage reports by Daniel Palme
• StyleCopyAnalyzer - StyleCop rules for .NET
• Roslynator - A set of code analysis tools for C# by Josef Pihrt
• CSharpCodingGuidelines - Roslyn analyzers by Bart Koelman to go with the C# Coding Guidelines
• Meziantou - Another set of awesome Roslyn analyzers by Gérald Barré
• Verify - Snapshot testing by Simon Cropp

Support the project

• Github Sponsors
• Tip Me
• Buy me a Coffee
• Patreon

You may also like

• My Blog
• PackageGuard - Get a grip on your open-source packages
• Reflectify - Reflection extensions without causing dependency pains
• .NET Library Package Templates - "dotnet new" templates for building NuGet-published multi-targeting libraries with all the bells and whistles
• FluentAssertions - Extension methods to fluently assert the outcome of .NET tests
• C# Coding Guidelines - Forkable coding guidelines for all C# versions

License

This project is licensed under the MIT License - see the LICENSE file for details.