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