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, StripPrefixError> {
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(StripPrefixError)
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
254#[derive(Debug)]
255pub struct StripPrefixError;
256
257impl ToOwned for RelPath {
258 type Owned = RelPathBuf;
259
260 fn to_owned(&self) -> Self::Owned {
261 self.to_rel_path_buf()
262 }
263}
264
265impl Borrow<RelPath> for RelPathBuf {
266 fn borrow(&self) -> &RelPath {
267 self.as_rel_path()
268 }
269}
270
271impl PartialOrd for RelPath {
272 fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
273 Some(self.cmp(other))
274 }
275}
276
277impl Ord for RelPath {
278 fn cmp(&self, other: &Self) -> std::cmp::Ordering {
279 self.components().cmp(other.components())
280 }
281}
282
283impl fmt::Debug for RelPath {
284 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
285 fmt::Debug::fmt(&self.0, f)
286 }
287}
288
289impl fmt::Debug for RelPathBuf {
290 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
291 fmt::Debug::fmt(&self.0, f)
292 }
293}
294
295impl RelPathBuf {
296 pub fn new() -> Self {
297 Self(String::new())
298 }
299
300 pub fn pop(&mut self) -> bool {
301 if let Some(ix) = self.0.rfind('/') {
302 self.0.truncate(ix);
303 true
304 } else if !self.is_empty() {
305 self.0.clear();
306 true
307 } else {
308 false
309 }
310 }
311
312 pub fn push(&mut self, path: &RelPath) {
313 if !self.is_empty() {
314 self.0.push('/');
315 }
316 self.0.push_str(&path.0);
317 }
318
319 pub fn as_rel_path(&self) -> &RelPath {
320 RelPath::new_unchecked(self.0.as_str())
321 }
322
323 pub fn set_extension(&mut self, extension: &str) -> bool {
324 if let Some(filename) = self.file_name() {
325 let mut filename = PathBuf::from(filename);
326 filename.set_extension(extension);
327 self.pop();
328 self.0.push_str(filename.to_str().unwrap());
329 true
330 } else {
331 false
332 }
333 }
334}
335
336impl Into<Arc<RelPath>> for RelPathBuf {
337 fn into(self) -> Arc<RelPath> {
338 Arc::from(self.as_rel_path())
339 }
340}
341
342impl AsRef<RelPath> for RelPathBuf {
343 fn as_ref(&self) -> &RelPath {
344 self.as_rel_path()
345 }
346}
347
348impl AsRef<RelPath> for RelPath {
349 fn as_ref(&self) -> &RelPath {
350 self
351 }
352}
353
354impl Deref for RelPathBuf {
355 type Target = RelPath;
356
357 fn deref(&self) -> &Self::Target {
358 self.as_ref()
359 }
360}
361
362impl<'a> From<&'a RelPath> for Cow<'a, RelPath> {
363 fn from(value: &'a RelPath) -> Self {
364 Self::Borrowed(value)
365 }
366}
367
368impl From<&RelPath> for Arc<RelPath> {
369 fn from(rel_path: &RelPath) -> Self {
370 let bytes: Arc<str> = Arc::from(&rel_path.0);
371 unsafe { Arc::from_raw(Arc::into_raw(bytes) as *const RelPath) }
372 }
373}
374
375#[cfg(any(test, feature = "test-support"))]
376#[track_caller]
377pub fn rel_path(path: &str) -> &RelPath {
378 RelPath::unix(path).unwrap()
379}
380
381impl PartialEq<str> for RelPath {
382 fn eq(&self, other: &str) -> bool {
383 self.0 == *other
384 }
385}
386
387#[derive(Default)]
388pub struct RelPathComponents<'a>(&'a str);
389
390pub struct RelPathAncestors<'a>(Option<&'a str>);
391
392const SEPARATOR: char = '/';
393
394impl<'a> RelPathComponents<'a> {
395 pub fn rest(&self) -> &'a RelPath {
396 RelPath::new_unchecked(self.0)
397 }
398}
399
400impl<'a> Iterator for RelPathComponents<'a> {
401 type Item = &'a str;
402
403 fn next(&mut self) -> Option<Self::Item> {
404 if let Some(sep_ix) = self.0.find(SEPARATOR) {
405 let (head, tail) = self.0.split_at(sep_ix);
406 self.0 = &tail[1..];
407 Some(head)
408 } else if self.0.is_empty() {
409 None
410 } else {
411 let result = self.0;
412 self.0 = "";
413 Some(result)
414 }
415 }
416}
417
418impl<'a> Iterator for RelPathAncestors<'a> {
419 type Item = &'a RelPath;
420
421 fn next(&mut self) -> Option<Self::Item> {
422 let result = self.0?;
423 if let Some(sep_ix) = result.rfind(SEPARATOR) {
424 self.0 = Some(&result[..sep_ix]);
425 } else if !result.is_empty() {
426 self.0 = Some("");
427 } else {
428 self.0 = None;
429 }
430 Some(RelPath::new_unchecked(result))
431 }
432}
433
434impl<'a> DoubleEndedIterator for RelPathComponents<'a> {
435 fn next_back(&mut self) -> Option<Self::Item> {
436 if let Some(sep_ix) = self.0.rfind(SEPARATOR) {
437 let (head, tail) = self.0.split_at(sep_ix);
438 self.0 = head;
439 Some(&tail[1..])
440 } else if self.0.is_empty() {
441 None
442 } else {
443 let result = self.0;
444 self.0 = "";
445 Some(result)
446 }
447 }
448}
449
450#[cfg(test)]
451mod tests {
452 use super::*;
453 use itertools::Itertools;
454 use pretty_assertions::assert_matches;
455
456 #[test]
457 fn test_rel_path_new() {
458 assert!(RelPath::new(Path::new("/"), PathStyle::local()).is_err());
459 assert!(RelPath::new(Path::new("//"), PathStyle::local()).is_err());
460 assert!(RelPath::new(Path::new("/foo/"), PathStyle::local()).is_err());
461
462 let path = RelPath::new("foo/".as_ref(), PathStyle::local()).unwrap();
463 assert_eq!(path, rel_path("foo").into());
464 assert_matches!(path, Cow::Borrowed(_));
465
466 let path = RelPath::new("foo\\".as_ref(), PathStyle::Windows).unwrap();
467 assert_eq!(path, rel_path("foo").into());
468 assert_matches!(path, Cow::Borrowed(_));
469
470 assert_eq!(
471 RelPath::new("foo/bar/../baz/./quux/".as_ref(), PathStyle::local())
472 .unwrap()
473 .as_ref(),
474 rel_path("foo/baz/quux")
475 );
476
477 let path = RelPath::new("./foo/bar".as_ref(), PathStyle::Posix).unwrap();
478 assert_eq!(path.as_ref(), rel_path("foo/bar"));
479 assert_matches!(path, Cow::Borrowed(_));
480
481 let path = RelPath::new(".\\foo".as_ref(), PathStyle::Windows).unwrap();
482 assert_eq!(path, rel_path("foo").into());
483 assert_matches!(path, Cow::Borrowed(_));
484
485 let path = RelPath::new("./.\\./foo/\\/".as_ref(), PathStyle::Windows).unwrap();
486 assert_eq!(path, rel_path("foo").into());
487 assert_matches!(path, Cow::Borrowed(_));
488
489 let path = RelPath::new("foo/./bar".as_ref(), PathStyle::Posix).unwrap();
490 assert_eq!(path.as_ref(), rel_path("foo/bar"));
491 assert_matches!(path, Cow::Owned(_));
492
493 let path = RelPath::new("./foo/bar".as_ref(), PathStyle::Windows).unwrap();
494 assert_eq!(path.as_ref(), rel_path("foo/bar"));
495 assert_matches!(path, Cow::Borrowed(_));
496
497 let path = RelPath::new(".\\foo\\bar".as_ref(), PathStyle::Windows).unwrap();
498 assert_eq!(path.as_ref(), rel_path("foo/bar"));
499 assert_matches!(path, Cow::Owned(_));
500 }
501
502 #[test]
503 fn test_rel_path_components() {
504 let path = rel_path("foo/bar/baz");
505 assert_eq!(
506 path.components().collect::<Vec<_>>(),
507 vec!["foo", "bar", "baz"]
508 );
509 assert_eq!(
510 path.components().rev().collect::<Vec<_>>(),
511 vec!["baz", "bar", "foo"]
512 );
513
514 let path = rel_path("");
515 let mut components = path.components();
516 assert_eq!(components.next(), None);
517 }
518
519 #[test]
520 fn test_rel_path_ancestors() {
521 let path = rel_path("foo/bar/baz");
522 let mut ancestors = path.ancestors();
523 assert_eq!(ancestors.next(), Some(rel_path("foo/bar/baz")));
524 assert_eq!(ancestors.next(), Some(rel_path("foo/bar")));
525 assert_eq!(ancestors.next(), Some(rel_path("foo")));
526 assert_eq!(ancestors.next(), Some(rel_path("")));
527 assert_eq!(ancestors.next(), None);
528
529 let path = rel_path("foo");
530 let mut ancestors = path.ancestors();
531 assert_eq!(ancestors.next(), Some(rel_path("foo")));
532 assert_eq!(ancestors.next(), Some(RelPath::empty()));
533 assert_eq!(ancestors.next(), None);
534
535 let path = RelPath::empty();
536 let mut ancestors = path.ancestors();
537 assert_eq!(ancestors.next(), Some(RelPath::empty()));
538 assert_eq!(ancestors.next(), None);
539 }
540
541 #[test]
542 fn test_rel_path_parent() {
543 assert_eq!(rel_path("foo/bar/baz").parent(), Some(rel_path("foo/bar")));
544 assert_eq!(rel_path("foo").parent(), Some(RelPath::empty()));
545 assert_eq!(rel_path("").parent(), None);
546 }
547
548 #[test]
549 fn test_rel_path_partial_ord_is_compatible_with_std() {
550 let test_cases = ["a/b/c", "relative/path/with/dot.", "relative/path/with.dot"];
551 for [lhs, rhs] in test_cases.iter().array_combinations::<2>() {
552 assert_eq!(
553 Path::new(lhs).cmp(Path::new(rhs)),
554 RelPath::unix(lhs)
555 .unwrap()
556 .cmp(&RelPath::unix(rhs).unwrap())
557 );
558 }
559 }
560
561 #[test]
562 fn test_strip_prefix() {
563 let parent = rel_path("");
564 let child = rel_path(".foo");
565
566 assert!(child.starts_with(parent));
567 assert_eq!(child.strip_prefix(parent).unwrap(), child);
568 }
569
570 #[test]
571 fn test_rel_path_constructors_absolute_path() {
572 assert!(RelPath::new(Path::new("/a/b"), PathStyle::Windows).is_err());
573 assert!(RelPath::new(Path::new("\\a\\b"), PathStyle::Windows).is_err());
574 assert!(RelPath::new(Path::new("/a/b"), PathStyle::Posix).is_err());
575 assert!(RelPath::new(Path::new("C:/a/b"), PathStyle::Windows).is_err());
576 assert!(RelPath::new(Path::new("C:\\a\\b"), PathStyle::Windows).is_err());
577 assert!(RelPath::new(Path::new("C:/a/b"), PathStyle::Posix).is_ok());
578 }
579
580 #[test]
581 fn test_pop() {
582 let mut path = rel_path("a/b").to_rel_path_buf();
583 path.pop();
584 assert_eq!(path.as_rel_path().as_unix_str(), "a");
585 path.pop();
586 assert_eq!(path.as_rel_path().as_unix_str(), "");
587 path.pop();
588 assert_eq!(path.as_rel_path().as_unix_str(), "");
589 }
590}