ktsu.Semantics.Paths 3.2.0

ktsu.Semantics.Paths

Polymorphic, strongly-typed file system path types that keep files, directories, absolute, and relative paths distinct at compile time.

ktsu.Semantics.Paths is one package in the ktsu.Semantics family. It builds on ktsu.Semantics.Strings, which supplies the underlying SemanticString<T> machinery.

Introduction

ktsu.Semantics.Paths models a file system path as a type, not a bare string. The type encodes two independent facts: whether the path names a file or a directory, and whether it is absolute or relative. That gives concrete types like AbsoluteFilePath, RelativeDirectoryPath, and orientation-agnostic FilePath / DirectoryPath, all implementing a shared IPath interface hierarchy. You can hold mixed paths in a List<IPath> and filter by capability with OfType<IFilePath>().

Paths are canonicalized on creation (separators normalized, trailing separators trimmed), convert implicitly to string so they drop into any System.IO API, and compose with a / operator that returns the correctly-typed result.

Features

• Interface hierarchy: IPath with IFilePath, IDirectoryPath, IAbsolutePath, IRelativePath, and the four combinations (IAbsoluteFilePath, IAbsoluteDirectoryPath, IRelativeFilePath, IRelativeDirectoryPath).
• Eight concrete path types: AbsolutePath, RelativePath, FilePath, DirectoryPath, AbsoluteFilePath, AbsoluteDirectoryPath, RelativeFilePath, RelativeDirectoryPath.
• Path decomposition: FileName, FileExtension, FullFileExtension (for .tar.gz), DirectoryPath, FileNameWithoutExtension, plus the FileName / FileExtension / DirectoryName primitive value types.
• Composition with /: directory / relativePath, directory / FileName, and similar, each returning the right result type.
• Absolute/relative conversions: AsAbsolute(), AsAbsolute(baseDirectory), and AsRelative(baseDirectory).
• Directory navigation: Parent, Depth, IsRoot, GetAncestors(), IsChildOf, IsParentOf, and strongly-typed GetContents() enumeration.
• Filesystem checks: Exists, IsFile, IsDirectory.
• Validation and canonicalization inherited from the semantic string framework, driven by path attributes such as [IsAbsolutePath], [IsFileName], and [IsFileExtension].

Installation

Package Manager Console

Install-Package ktsu.Semantics.Paths

.NET CLI

dotnet add package ktsu.Semantics.Paths

Package Reference

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

Usage Examples

Basic Example

using ktsu.Semantics.Paths;

// Build paths with the typed factory, then compose with the '/' operator
AbsoluteDirectoryPath projectDir = AbsoluteDirectoryPath.Create(@"C:\repos\app");
RelativeFilePath rel = RelativeFilePath.Create(@"src\Program.cs");

AbsoluteFilePath source = projectDir / rel;   // C:\repos\app\src\Program.cs
FileName name = source.FileName;              // Program.cs
FileExtension ext = source.FileExtension;     // .cs
AbsoluteDirectoryPath dir = source.AbsoluteDirectoryPath;

if (source.Exists)
{
    // implicit conversion to string drops straight into System.IO
    string text = System.IO.File.ReadAllText(source);
}

Absolute and relative conversions

using ktsu.Semantics.Paths;

AbsoluteDirectoryPath root = AbsoluteDirectoryPath.Create(@"C:\data");
AbsoluteFilePath file = AbsoluteFilePath.Create(@"C:\data\logs\app.log");

RelativeFilePath relative = file.AsRelative(root);        // logs\app.log
AbsoluteFilePath backAgain = relative.AsAbsolute(root);   // C:\data\logs\app.log

AbsoluteFilePath renamed = file.ChangeExtension(FileExtension.Create(".bak"));
bool nested = file.IsChildOf(root);                       // true

AsAbsolute() with no argument resolves a relative path against the current working directory. The baseDirectory overload of AsAbsolute exists on the relative path types only.

Polymorphic collections and typed enumeration

using ktsu.Semantics.Paths;

List<IPath> all =
[
    AbsoluteFilePath.Create(@"C:\data.txt"),
    RelativeDirectoryPath.Create(@"logs\app"),
    FilePath.Create(@"document.pdf"),
];

List<IFilePath> files = all.OfType<IFilePath>().ToList();
List<IAbsolutePath> absolutes = all.OfType<IAbsolutePath>().ToList();

// GetContents() yields correctly-typed children
AbsoluteDirectoryPath project = AbsoluteDirectoryPath.Create(@"C:\project");
foreach (IPath entry in project.GetContents())
{
    switch (entry)
    {
        case AbsoluteFilePath f:
            Console.WriteLine($"file: {f.FileName} ({f.FileExtension})");
            break;
        case AbsoluteDirectoryPath d:
            Console.WriteLine($"dir:  {d.Name} at depth {d.Depth}");
            break;
    }
}

GetContents() returns an empty sequence rather than throwing when the directory is missing or access is denied.

API Reference

Interface hierarchy

Concrete types and creation

All concrete types are sealed records created through the inherited static factory Create(...) (accepting string, char[], or ReadOnlySpan<char>). Create throws ArgumentException on invalid input and ArgumentNullException on null.

The primitive component types FileName, FileExtension, and DirectoryName are semantic strings in their own right.

Common members

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

License

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