1use crate::paths::{PathStyle, is_absolute};
2use anyhow::{Context as _, Result, anyhow};
3use serde::{Deserialize, Serialize};
4use std::{
5 borrow::{Borrow, Cow},
6 fmt,
7 ops::Deref,
8 path::{Path, PathBuf},
9 sync::Arc,
10};
11
12/// A file system path that is guaranteed to be relative and normalized.
13///
14/// This type can be used to represent paths in a uniform way, regardless of
15/// whether they refer to Windows or POSIX file systems, and regardless of
16/// the host platform.
17///
18/// Internally, paths are stored in POSIX ('/'-delimited) format, but they can
19/// be displayed in either POSIX or Windows format.
20///
21/// Relative paths are also guaranteed to be valid unicode.
22#[repr(transparent)]
23#[derive(PartialEq, Eq, Hash, Serialize)]
24pub struct RelPath(str);
25
26/// An owned representation of a file system path that is guaranteed to be
27/// relative and normalized.
28///
29/// This type is to [`RelPath`] as [`std::path::PathBuf`] is to [`std::path::Path`]
30#[derive(PartialEq, Eq, Clone, Serialize, Deserialize)]
31pub struct RelPathBuf(String);
32
33impl RelPath {
34 /// Creates an empty [`RelPath`].
35 pub fn empty() -> &'static Self {
36 Self::new_unchecked("")
37 }
38
39 /// Converts a path with a given style into a [`RelPath`].
40 ///
41 /// Returns an error if the path is absolute, or is not valid unicode.
42 ///
43 /// This method will normalize the path by removing `.` components,
44 /// processing `..` components, and removing trailing separators. It does
45 /// not allocate unless it's necessary to reformat the path.
46 #[track_caller]
47 pub fn new<'a>(path: &'a Path, path_style: PathStyle) -> Result<Cow<'a, Self>> {
48 let mut path = path.to_str().context("non utf-8 path")?;
49
50 let (prefixes, suffixes): (&[_], &[_]) = match path_style {
51 PathStyle::Posix => (&["./"], &['/']),
52 PathStyle::Windows => (&["./", ".\\"], &['/', '\\']),
53 };
54
55 while prefixes.iter().any(|prefix| path.starts_with(prefix)) {
56 path = &path[prefixes[0].len()..];
57 }
58 while let Some(prefix) = path.strip_suffix(suffixes)
59 && !prefix.is_empty()
60 {
61 path = prefix;
62 }
63
64 if is_absolute(&path, path_style) {
65 return Err(anyhow!("absolute path not allowed: {path:?}"));
66 }
67
68 let mut string = Cow::Borrowed(path);
69 if path_style == PathStyle::Windows && path.contains('\\') {
70 string = Cow::Owned(string.as_ref().replace('\\', "/"))
71 }
72
73 let mut result = match string {
74 Cow::Borrowed(string) => Cow::Borrowed(Self::new_unchecked(string)),
75 Cow::Owned(string) => Cow::Owned(RelPathBuf(string)),
76 };
77
78 if result
79 .components()
80 .any(|component| component == "" || component == "." || component == "..")
81 {
82 let mut normalized = RelPathBuf::new();
83 for component in result.components() {
84 match component {
85 "" => {}
86 "." => {}
87 ".." => {
88 if !normalized.pop() {
89 return Err(anyhow!("path is not relative: {result:?}"));
90 }
91 }
92 other => normalized.push(RelPath::new_unchecked(other)),
93 }
94 }
95 result = Cow::Owned(normalized)
96 }
97
98 Ok(result)
99 }
100
101 /// Converts a path that is already normalized and uses '/' separators
102 /// into a [`RelPath`] .
103 ///
104 /// Returns an error if the path is not already in the correct format.
105 #[track_caller]
106 pub fn unix<S: AsRef<Path> + ?Sized>(path: &S) -> anyhow::Result<&Self> {
107 let path = path.as_ref();
108 match Self::new(path, PathStyle::Posix)? {
109 Cow::Borrowed(path) => Ok(path),
110 Cow::Owned(_) => Err(anyhow!("invalid relative path {path:?}")),
111 }
112 }
113
114 fn new_unchecked(s: &str) -> &Self {
115 // Safety: `RelPath` is a transparent wrapper around `str`.
116 unsafe { &*(s as *const str as *const Self) }
117 }
118
119 pub fn is_empty(&self) -> bool {
120 self.0.is_empty()
121 }
122
123 pub fn components(&self) -> RelPathComponents<'_> {
124 RelPathComponents(&self.0)
125 }
126
127 pub fn ancestors(&self) -> RelPathAncestors<'_> {
128 RelPathAncestors(Some(&self.0))
129 }
130
131 pub fn file_name(&self) -> Option<&str> {
132 self.components().next_back()
133 }
134
135 pub fn file_stem(&self) -> Option<&str> {
136 Some(self.as_std_path().file_stem()?.to_str().unwrap())
137 }
138
139 pub fn extension(&self) -> Option<&str> {
140 Some(self.as_std_path().extension()?.to_str().unwrap())
141 }
142
143 pub fn parent(&self) -> Option<&Self> {
144 let mut components = self.components();
145 components.next_back()?;
146 Some(components.rest())
147 }
148
149 pub fn starts_with(&self, other: &Self) -> bool {
150 self.strip_prefix(other).is_ok()
151 }
152
153 pub fn ends_with(&self, other: &Self) -> bool {
154 if let Some(suffix) = self.0.strip_suffix(&other.0) {
155 if suffix.ends_with('/') {
156 return true;
157 } else if suffix.is_empty() {
158 return true;
159 }
160 }
161 false
162 }
163
164 pub fn strip_prefix<'a>(&'a self, other: &Self) -> Result<&'a Self> {
165 if other.is_empty() {
166 return Ok(self);
167 }
168 if let Some(suffix) = self.0.strip_prefix(&other.0) {
169 if let Some(suffix) = suffix.strip_prefix('/') {
170 return Ok(Self::new_unchecked(suffix));
171 } else if suffix.is_empty() {
172 return Ok(Self::empty());
173 }
174 }
175 Err(anyhow!("failed to strip prefix: {other:?} from {self:?}"))
176 }
177
178 pub fn len(&self) -> usize {
179 self.0.matches('/').count() + 1
180 }
181
182 pub fn last_n_components(&self, count: usize) -> Option<&Self> {
183 let len = self.len();
184 if len >= count {
185 let mut components = self.components();
186 for _ in 0..(len - count) {
187 components.next()?;
188 }
189 Some(components.rest())
190 } else {
191 None
192 }
193 }
194
195 pub fn join(&self, other: &Self) -> Arc<Self> {
196 let result = if self.0.is_empty() {
197 Cow::Borrowed(&other.0)
198 } else if other.0.is_empty() {
199 Cow::Borrowed(&self.0)
200 } else {
201 Cow::Owned(format!("{}/{}", &self.0, &other.0))
202 };
203 Arc::from(Self::new_unchecked(result.as_ref()))
204 }
205
206 pub fn to_rel_path_buf(&self) -> RelPathBuf {
207 RelPathBuf(self.0.to_string())
208 }
209
210 pub fn into_arc(&self) -> Arc<Self> {
211 Arc::from(self)
212 }
213
214 /// Convert the path into the wire representation.
215 pub fn to_proto(&self) -> String {
216 self.as_unix_str().to_owned()
217 }
218
219 /// Load the path from its wire representation.
220 pub fn from_proto(path: &str) -> Result<Arc<Self>> {
221 Ok(Arc::from(Self::unix(path)?))
222 }
223
224 /// Convert the path into a string with the given path style.
225 ///
226 /// Whenever a path is presented to the user, it should be converted to
227 /// a string via this method.
228 pub fn display(&self, style: PathStyle) -> Cow<'_, str> {
229 match style {
230 PathStyle::Posix => Cow::Borrowed(&self.0),
231 PathStyle::Windows if self.0.contains('/') => Cow::Owned(self.0.replace('/', "\\")),
232 PathStyle::Windows => Cow::Borrowed(&self.0),
233 }
234 }
235
236 /// Get the internal unix-style representation of the path.
237 ///
238 /// This should not be shown to the user.
239 pub fn as_unix_str(&self) -> &str {
240 &self.0
241 }
242
243 /// Interprets the path as a [`std::path::Path`], suitable for file system calls.
244 ///
245 /// This is guaranteed to be a valid path regardless of the host platform, because
246 /// the `/` is accepted as a path separator on windows.
247 ///
248 /// This should not be shown to the user.
249 pub fn as_std_path(&self) -> &Path {
250 Path::new(&self.0)
251 }
252}
253
254impl ToOwned for RelPath {
255 type Owned = RelPathBuf;
256
257 fn to_owned(&self) -> Self::Owned {
258 self.to_rel_path_buf()
259 }
260}
261
262impl Borrow<RelPath> for RelPathBuf {
263 fn borrow(&self) -> &RelPath {
264 self.as_rel_path()
265 }
266}
267
268impl PartialOrd for RelPath {
269 fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
270 Some(self.cmp(other))
271 }
272}
273
274impl Ord for RelPath {
275 fn cmp(&self, other: &Self) -> std::cmp::Ordering {
276 self.components().cmp(other.components())
277 }
278}
279
280impl fmt::Debug for RelPath {
281 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
282 fmt::Debug::fmt(&self.0, f)
283 }
284}
285
286impl fmt::Debug for RelPathBuf {
287 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
288 fmt::Debug::fmt(&self.0, f)
289 }
290}
291
292impl RelPathBuf {
293 pub fn new() -> Self {
294 Self(String::new())
295 }
296
297 pub fn pop(&mut self) -> bool {
298 if let Some(ix) = self.0.rfind('/') {
299 self.0.truncate(ix);
300 true
301 } else if !self.is_empty() {
302 self.0.clear();
303 true
304 } else {
305 false
306 }
307 }
308
309 pub fn push(&mut self, path: &RelPath) {
310 if !self.is_empty() {
311 self.0.push('/');
312 }
313 self.0.push_str(&path.0);
314 }
315
316 pub fn as_rel_path(&self) -> &RelPath {
317 RelPath::new_unchecked(self.0.as_str())
318 }
319
320 pub fn set_extension(&mut self, extension: &str) -> bool {
321 if let Some(filename) = self.file_name() {
322 let mut filename = PathBuf::from(filename);
323 filename.set_extension(extension);
324 self.pop();
325 self.0.push_str(filename.to_str().unwrap());
326 true
327 } else {
328 false
329 }
330 }
331}
332
333impl Into<Arc<RelPath>> for RelPathBuf {
334 fn into(self) -> Arc<RelPath> {
335 Arc::from(self.as_rel_path())
336 }
337}
338
339impl AsRef<RelPath> for RelPathBuf {
340 fn as_ref(&self) -> &RelPath {
341 self.as_rel_path()
342 }
343}
344
345impl AsRef<RelPath> for RelPath {
346 fn as_ref(&self) -> &RelPath {
347 self
348 }
349}
350
351impl Deref for RelPathBuf {
352 type Target = RelPath;
353
354 fn deref(&self) -> &Self::Target {
355 self.as_ref()
356 }
357}
358
359impl<'a> From<&'a RelPath> for Cow<'a, RelPath> {
360 fn from(value: &'a RelPath) -> Self {
361 Self::Borrowed(value)
362 }
363}
364
365impl From<&RelPath> for Arc<RelPath> {
366 fn from(rel_path: &RelPath) -> Self {
367 let bytes: Arc<str> = Arc::from(&rel_path.0);
368 unsafe { Arc::from_raw(Arc::into_raw(bytes) as *const RelPath) }
369 }
370}
371
372#[cfg(any(test, feature = "test-support"))]
373#[track_caller]
374pub fn rel_path(path: &str) -> &RelPath {
375 RelPath::unix(path).unwrap()
376}
377
378impl PartialEq<str> for RelPath {
379 fn eq(&self, other: &str) -> bool {
380 self.0 == *other
381 }
382}
383
384#[derive(Default)]
385pub struct RelPathComponents<'a>(&'a str);
386
387pub struct RelPathAncestors<'a>(Option<&'a str>);
388
389const SEPARATOR: char = '/';
390
391impl<'a> RelPathComponents<'a> {
392 pub fn rest(&self) -> &'a RelPath {
393 RelPath::new_unchecked(self.0)
394 }
395}
396
397impl<'a> Iterator for RelPathComponents<'a> {
398 type Item = &'a str;
399
400 fn next(&mut self) -> Option<Self::Item> {
401 if let Some(sep_ix) = self.0.find(SEPARATOR) {
402 let (head, tail) = self.0.split_at(sep_ix);
403 self.0 = &tail[1..];
404 Some(head)
405 } else if self.0.is_empty() {
406 None
407 } else {
408 let result = self.0;
409 self.0 = "";
410 Some(result)
411 }
412 }
413}
414
415impl<'a> Iterator for RelPathAncestors<'a> {
416 type Item = &'a RelPath;
417
418 fn next(&mut self) -> Option<Self::Item> {
419 let result = self.0?;
420 if let Some(sep_ix) = result.rfind(SEPARATOR) {
421 self.0 = Some(&result[..sep_ix]);
422 } else if !result.is_empty() {
423 self.0 = Some("");
424 } else {
425 self.0 = None;
426 }
427 Some(RelPath::new_unchecked(result))
428 }
429}
430
431impl<'a> DoubleEndedIterator for RelPathComponents<'a> {
432 fn next_back(&mut self) -> Option<Self::Item> {
433 if let Some(sep_ix) = self.0.rfind(SEPARATOR) {
434 let (head, tail) = self.0.split_at(sep_ix);
435 self.0 = head;
436 Some(&tail[1..])
437 } else if self.0.is_empty() {
438 None
439 } else {
440 let result = self.0;
441 self.0 = "";
442 Some(result)
443 }
444 }
445}
446
447#[cfg(test)]
448mod tests {
449 use super::*;
450 use itertools::Itertools;
451 use pretty_assertions::assert_matches;
452
453 #[test]
454 fn test_rel_path_new() {
455 assert!(RelPath::new(Path::new("/"), PathStyle::local()).is_err());
456 assert!(RelPath::new(Path::new("//"), PathStyle::local()).is_err());
457 assert!(RelPath::new(Path::new("/foo/"), PathStyle::local()).is_err());
458
459 let path = RelPath::new("foo/".as_ref(), PathStyle::local()).unwrap();
460 assert_eq!(path, rel_path("foo").into());
461 assert_matches!(path, Cow::Borrowed(_));
462
463 let path = RelPath::new("foo\\".as_ref(), PathStyle::Windows).unwrap();
464 assert_eq!(path, rel_path("foo").into());
465 assert_matches!(path, Cow::Borrowed(_));
466
467 assert_eq!(
468 RelPath::new("foo/bar/../baz/./quux/".as_ref(), PathStyle::local())
469 .unwrap()
470 .as_ref(),
471 rel_path("foo/baz/quux")
472 );
473
474 let path = RelPath::new("./foo/bar".as_ref(), PathStyle::Posix).unwrap();
475 assert_eq!(path.as_ref(), rel_path("foo/bar"));
476 assert_matches!(path, Cow::Borrowed(_));
477
478 let path = RelPath::new(".\\foo".as_ref(), PathStyle::Windows).unwrap();
479 assert_eq!(path, rel_path("foo").into());
480 assert_matches!(path, Cow::Borrowed(_));
481
482 let path = RelPath::new("./.\\./foo/\\/".as_ref(), PathStyle::Windows).unwrap();
483 assert_eq!(path, rel_path("foo").into());
484 assert_matches!(path, Cow::Borrowed(_));
485
486 let path = RelPath::new("foo/./bar".as_ref(), PathStyle::Posix).unwrap();
487 assert_eq!(path.as_ref(), rel_path("foo/bar"));
488 assert_matches!(path, Cow::Owned(_));
489
490 let path = RelPath::new("./foo/bar".as_ref(), PathStyle::Windows).unwrap();
491 assert_eq!(path.as_ref(), rel_path("foo/bar"));
492 assert_matches!(path, Cow::Borrowed(_));
493
494 let path = RelPath::new(".\\foo\\bar".as_ref(), PathStyle::Windows).unwrap();
495 assert_eq!(path.as_ref(), rel_path("foo/bar"));
496 assert_matches!(path, Cow::Owned(_));
497 }
498
499 #[test]
500 fn test_rel_path_components() {
501 let path = rel_path("foo/bar/baz");
502 assert_eq!(
503 path.components().collect::<Vec<_>>(),
504 vec!["foo", "bar", "baz"]
505 );
506 assert_eq!(
507 path.components().rev().collect::<Vec<_>>(),
508 vec!["baz", "bar", "foo"]
509 );
510
511 let path = rel_path("");
512 let mut components = path.components();
513 assert_eq!(components.next(), None);
514 }
515
516 #[test]
517 fn test_rel_path_ancestors() {
518 let path = rel_path("foo/bar/baz");
519 let mut ancestors = path.ancestors();
520 assert_eq!(ancestors.next(), Some(rel_path("foo/bar/baz")));
521 assert_eq!(ancestors.next(), Some(rel_path("foo/bar")));
522 assert_eq!(ancestors.next(), Some(rel_path("foo")));
523 assert_eq!(ancestors.next(), Some(rel_path("")));
524 assert_eq!(ancestors.next(), None);
525
526 let path = rel_path("foo");
527 let mut ancestors = path.ancestors();
528 assert_eq!(ancestors.next(), Some(rel_path("foo")));
529 assert_eq!(ancestors.next(), Some(RelPath::empty()));
530 assert_eq!(ancestors.next(), None);
531
532 let path = RelPath::empty();
533 let mut ancestors = path.ancestors();
534 assert_eq!(ancestors.next(), Some(RelPath::empty()));
535 assert_eq!(ancestors.next(), None);
536 }
537
538 #[test]
539 fn test_rel_path_parent() {
540 assert_eq!(rel_path("foo/bar/baz").parent(), Some(rel_path("foo/bar")));
541 assert_eq!(rel_path("foo").parent(), Some(RelPath::empty()));
542 assert_eq!(rel_path("").parent(), None);
543 }
544
545 #[test]
546 fn test_rel_path_partial_ord_is_compatible_with_std() {
547 let test_cases = ["a/b/c", "relative/path/with/dot.", "relative/path/with.dot"];
548 for [lhs, rhs] in test_cases.iter().array_combinations::<2>() {
549 assert_eq!(
550 Path::new(lhs).cmp(Path::new(rhs)),
551 RelPath::unix(lhs)
552 .unwrap()
553 .cmp(&RelPath::unix(rhs).unwrap())
554 );
555 }
556 }
557
558 #[test]
559 fn test_strip_prefix() {
560 let parent = rel_path("");
561 let child = rel_path(".foo");
562
563 assert!(child.starts_with(parent));
564 assert_eq!(child.strip_prefix(parent).unwrap(), child);
565 }
566
567 #[test]
568 fn test_rel_path_constructors_absolute_path() {
569 assert!(RelPath::new(Path::new("/a/b"), PathStyle::Windows).is_err());
570 assert!(RelPath::new(Path::new("\\a\\b"), PathStyle::Windows).is_err());
571 assert!(RelPath::new(Path::new("/a/b"), PathStyle::Posix).is_err());
572 assert!(RelPath::new(Path::new("C:/a/b"), PathStyle::Windows).is_err());
573 assert!(RelPath::new(Path::new("C:\\a\\b"), PathStyle::Windows).is_err());
574 assert!(RelPath::new(Path::new("C:/a/b"), PathStyle::Posix).is_ok());
575 }
576
577 #[test]
578 fn test_pop() {
579 let mut path = rel_path("a/b").to_rel_path_buf();
580 path.pop();
581 assert_eq!(path.as_rel_path().as_unix_str(), "a");
582 path.pop();
583 assert_eq!(path.as_rel_path().as_unix_str(), "");
584 path.pop();
585 assert_eq!(path.as_rel_path().as_unix_str(), "");
586 }
587}