dennisdoomen / dennisdoomen/pathy

[API Proposal]: File content helpers so build scripts stay in one vocabulary

Open
#136 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
C#
Stars
27
Forks
5
Avg merge
21h 29m
Merged PRs (30d)
10

Description

### Background and motivation

Pathy covers building and inspecting paths and a few file system operations, but the moment you want to read or write the file you have just located, you switch to `File.ReadAllText(path.ToString())`. In a build script or a test that mixes both styles, this is a constant, jarring context switch, and it means the path has to be converted back to a string over and over. Thin wrappers would let a script speak one vocabulary from start to finish.

### API Proposal

```C#
namespace Pathy
{
public static class ChainablePathExtensions
{
public static string ReadAllText(this ChainablePath path);
public static string ReadAllText(this ChainablePath path, Encoding encoding);
public static string[] ReadAllLines(this ChainablePath path);
public static IEnumerable ReadLines(this ChainablePath path);
public static byte[] ReadAllBytes(this ChainablePath path);

public static void WriteAllText(this ChainablePath path, string contents);
public static void WriteAllText(this ChainablePath path, string contents, Encoding encoding);
public static void WriteAllLines(this ChainablePath path, IEnumerable contents);
public static void WriteAllBytes(this ChainablePath path, byte[] bytes);
public static void AppendAllText(this ChainablePath path, string contents);

public static FileStream OpenRead(this ChainablePath path);
public static FileStream OpenWrite(this ChainablePath path);
}
}
```

### API Usage

```C#
var version = (ChainablePath.Current / "version.txt").ReadAllText().Trim();

(artifacts / "manifest.json").WriteAllText(JsonSerializer.Serialize(manifest));

foreach (var line in (logs / "build.log").ReadLines())
{
...
}
```

### Alternative Designs

* Do nothing and let callers use `File.*` with an implicit conversion to `string`. This already works, so the proposal is purely about ergonomics and consistency.
* Ship these in a separate `Pathy.IO` package to keep the core surface small. Worth considering, although unlike globbing these wrappers need no extra dependency.

### Risks

This grows the API surface noticeably for what is mostly convenience, and it invites scope creep toward wrapping all of `System.IO`. A clear boundary is needed. There is also a question of whether the write methods should create missing parent directories; doing so silently would differ from `File.WriteAllText` and could surprise people.

Contributor guide

Open the contributing guide

Research direction

Start with ChainablePath and ChainablePathExtensions, then inspect how existing path operations are exposed. Resolve whether these System.IO-style wrappers belong in the core or a Pathy.IO package and define write behavior for missing parent directories. Done means the API boundary and behavior of the proposed helpers are settled and covered by project tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.