ktsu.StrongPaths 1.3.2-pre.17

ktsu.StrongPaths

A library providing strong typing for common filesystem paths with compile-time feedback and runtime validation

Introduction

StrongPaths is a collection of classes derived from ktsu.StrongStrings with added functionality and helper methods for filesystem paths. It provides strong typing for common filesystem paths, giving you compile-time feedback and runtime validation to help catch path-related errors early in your development cycle.

Get familiar with the StrongStrings library to get the most out of StrongPaths.

Features

• Strong Typing for file system paths to prevent type confusion
• Path Combination using overloaded operators for intuitive path building
• Compile-time Safety to catch type mismatches early
• Runtime Validation for path format and structure
• Relative Path Calculations between different path types
• Hierarchical Type System for flexible parameter constraints

Installation

Package Manager Console

Install-Package ktsu.StrongPaths

.NET CLI

dotnet add package ktsu.StrongPaths

Package Reference

<PackageReference Include="ktsu.StrongPaths" Version="x.y.z" />

Usage Examples

Basic Example

using ktsu.StrongPaths;

// Create strongly-typed paths
AbsoluteDirectoryPath rootDir = (AbsoluteDirectoryPath)@"C:\Projects";
RelativeDirectoryPath subDir = (RelativeDirectoryPath)"MyProject";
FileName configFile = (FileName)"config.json";

// Combine paths with the / operator
AbsoluteFilePath fullPath = rootDir / subDir / configFile;

// Use with standard file operations
File.WriteAllText(fullPath, "{ \"setting\": \"value\" }");

Path Combining with Operators

using ktsu.StrongPaths;

public class MyDemoClass
{
    public AbsoluteDirectoryPath OutputDir { get; set; } = (AbsoluteDirectoryPath)@"c:\output";

    public void SaveData(RelativeDirectoryPath subDir, FileName fileName)
    {
        // You can use the / operator to combine paths
        AbsoluteFilePath filePath = OutputDir / subDir / fileName;
        File.WriteAllText(filePath, "Hello, world!");

        // An AbsoluteDirectoryPath combined with a RelativeDirectoryPath returns an AbsoluteDirectoryPath
        AbsoluteDirectoryPath newOutputDir = OutputDir / subDir;

        // An AbsoluteDirectoryPath combined with a FileName returns an AbsoluteFilePath
        AbsoluteFilePath newFilePath = newOutputDir / fileName;
    }
}

Calculating Relative Paths

using ktsu.StrongPaths;

AbsoluteDirectoryPath baseDir = (AbsoluteDirectoryPath)@"C:\Projects\MainProject";
AbsoluteDirectoryPath targetDir = (AbsoluteDirectoryPath)@"C:\Projects\MainProject\Submodule\Source";
AbsoluteFilePath targetFile = (AbsoluteFilePath)@"C:\Projects\MainProject\Submodule\Source\Program.cs";

// Get relative paths from one location to another
RelativeDirectoryPath relativeDir = targetDir.RelativeTo(baseDir);  // "Submodule\Source"
RelativeFilePath relativeFile = targetFile.RelativeTo(baseDir);     // "Submodule\Source\Program.cs"

Advanced Usage

Using Abstract Base Classes

You can use abstract base classes to accept a subset of path types in your method parameters:

using ktsu.StrongPaths;

public static class MyDemoClass
{
    public static void SaveData(AnyDirectoryPath outputDir, FileName fileName)
    {
        // You can't use the / operator with the abstract base classes because it has no way of knowing which type to return
        // You have to use the Path.Combine method when using the abstract base classes
        FilePath filePath = (FilePath)Path.Combine(outputDir, fileName);
        File.WriteAllText(filePath, "Hello, World!");
    }

    public static void Demo()
    {
        string storeLocation = "melbourne";
        RelativeDirectoryPath storeDir = (RelativeDirectoryPath)$"store_{storeLocation}";
        FileName fileName = (FileName)$"{DateTime.UtcNow}.json";
        SaveData(storeDir, fileName);
    }
}

Path Validation and Creation

using ktsu.StrongPaths;

// Validate paths at creation
try 
{
    // This will throw if the path is invalid
    AbsoluteFilePath invalidPath = (AbsoluteFilePath)"not:a:valid:path";
}
catch (FormatException ex)
{
    Console.WriteLine("Invalid path format: " + ex.Message);
}

// Create a directory if it doesn't exist
AbsoluteDirectoryPath projectDir = (AbsoluteDirectoryPath)@"C:\Projects\NewProject";
if (!Directory.Exists(projectDir))
{
    Directory.CreateDirectory(projectDir);
}

API Reference

Available Types

Concrete Types

Abstract Base Classes

Key Operations

Contributing

Contributions are welcome! Please feel free to submit a pull request.

License

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