pathx 0.1.0

A collection of utilities for working with paths.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

# pathx


[![Crates.io](https://img.shields.io/crates/v/pathx.svg)](https://crates.io/crates/pathx)
[![Docs.rs](https://img.shields.io/badge/docs.rs-pathx-blue)](https://docs.rs/pathx)
[![License](https://img.shields.io/crates/l/pathx)](https://github.com/Pjdur/pathx/blob/main/LICENSE)
[![CI](https://github.com/Pjdur/pathx/actions/workflows/ci.yml/badge.svg)](https://github.com/Pjdur/pathx/actions)


**A collection of ergonomic, cross-platform utilities for working with paths in Rust.**

From lexical normalization to templated path generation, `pathx` helps you compose, analyze, and manipulate paths with clarity and precision.

---

## ✨ Features


- `join()` — Join and normalize paths lexically
- `normalize()` — Resolve `.` and `..` without touching the filesystem
- `relative_to()` — Compute relative paths between two locations
- `template!()` — Rust-style macro for path templating
- `is_subpath()` — Check if one path is lexically nested under another
- `strip_root()` — Remove root or prefix from a path
- Platform-aware separator via `separator()`

All utilities are **pure**, **lexical**, and **cross-platform safe**.

---

## 🚀 Quick Start


Add to your `Cargo.toml`:

```toml
[dependencies]
pathx = "0.1.0"
```

---

## 🛠️ Usage Examples


### Join and Normalize


```rust
use pathx::join;
use std::path::Path;

let base = Path::new("/foo/bar");
let segment = Path::new("../baz");
let path = join(base, segment).unwrap();
// → "/foo/baz"
```

### Path Templating


```rust
use pathx::template;

let path = template!("src/{module}/{file}.rs", {
    module: "utils",
    file: "normalize"
});
// → "src/utils/normalize.rs"
```

### Relative Path


```rust
use pathx::relative_to;
use std::path::Path;

let base = Path::new("/a/b/c");
let target = Path::new("/a/b/d/e.txt");
let rel = relative_to(base, target);
// → "../d/e.txt"
```

---

## 📚 API Reference


| Function / Macro            | Description                                    |
| --------------------------- | ---------------------------------------------- |
| `join(base, segment)`       | Joins and normalizes two paths                 |
| `join_lossy(...)`           | Same as `join`, but falls back on error        |
| `normalize(path)`           | Lexically resolves `.` and `..`                |
| `normalize_lossy(...)`      | Returns original path if normalization fails   |
| `relative_to(base, target)` | Computes relative path from base to target     |
| `is_subpath(base, child)`   | Checks if `child` is nested under `base`       |
| `strip_root(path)`          | Removes root or prefix from a path             |
| `template!(...)`            | Macro for path templating using `{key}` syntax |
| `render_template(...)`      | Function version of `template!()`              |
| `separator()`               | Returns platform-specific path separator       |

---

## 📦 Platform Support


- ✅ Windows
- ✅ macOS
- ✅ Linux

All path operations are **lexical only** — no filesystem access or symlink resolution.

---

## 🤝 Contributing


Contributions, bug reports, and feature requests are welcome!

1. Fork the repo
2. Create a feature branch
3. Write tests for your changes
4. Submit a pull request

Please follow Rust’s formatting and documentation conventions.

---

## 📄 License


Licensed under the [MIT License](LICENSE).  
You’re free to use, modify, and distribute this crate with attribution.

---

## 💬 Author


Created by [Pjdur](https://github.com/Pjdur).  
Feel free to reach out or open an issue if you have ideas or feedback!