relative_path/
path_ext.rs

Help
1// Copyright 2012-2015 The Rust Project Developers. See the COPYRIGHT
2// file at the top-level directory of this distribution and at
3// http://rust-lang.org/COPYRIGHT.
4//
5// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8// option. This file may not be copied, modified, or distributed
9// except according to those terms.
10
11// Ported from the pathdiff crate, which adapted the original rustc's
12// path_relative_from
13// https://github.com/Manishearth/pathdiff/blob/master/src/lib.rs
14// https://github.com/rust-lang/rust/blob/e1d0de82cc40b666b88d4a6d2c9dcbc81d7ed27f/src/librustc_back/rpath.rs#L116-L158
15
16use std::error;
17use std::fmt;
18use std::path::{Path, PathBuf};
19
20use crate::{Component, RelativePathBuf};
21
22// Prevent downstream implementations, so methods may be added without backwards
23// breaking changes.
24mod sealed {
25    use std::path::{Path, PathBuf};
26
27    pub trait Sealed {}
28
29    impl Sealed for Path {}
30    impl Sealed for PathBuf {}
31}
32
33/// An error raised when attempting to convert a path using
34/// [`PathExt::relative_to`].
35#[derive(Debug, Clone, PartialEq, Eq)]
36pub struct RelativeToError {
37    kind: RelativeToErrorKind,
38}
39
40/// Error kind for [`RelativeToError`].
41#[derive(Debug, Clone, Copy, PartialEq, Eq)]
42#[non_exhaustive]
43enum RelativeToErrorKind {
44    /// Non-utf8 component in path.
45    NonUtf8,
46    /// Mismatching path prefixes.
47    PrefixMismatch,
48    /// A provided path is ambiguous, in that there is no way to determine which
49    /// components should be added from one path to the other to traverse it.
50    ///
51    /// For example, `.` is ambiguous relative to `../..` because we don't know
52    /// the names of the components being traversed.
53    AmbiguousTraversal,
54    /// This is a catch-all error since we don't control the `std::path` API a
55    /// Components iterator might decide (intentionally or not) to produce
56    /// components which violates its own contract.
57    ///
58    /// In particular we rely on only relative components being produced after
59    /// the absolute prefix has been consumed.
60    IllegalComponent,
61}
62
63impl fmt::Display for RelativeToError {
64    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
65        match self.kind {
66            RelativeToErrorKind::NonUtf8 => "path contains non-utf8 component".fmt(fmt),
67            RelativeToErrorKind::PrefixMismatch => {
68                "paths contain different absolute prefixes".fmt(fmt)
69            }
70            RelativeToErrorKind::AmbiguousTraversal => {
71                "path traversal cannot be determined".fmt(fmt)
72            }
73            RelativeToErrorKind::IllegalComponent => "path contains illegal components".fmt(fmt),
74        }
75    }
76}
77
78impl error::Error for RelativeToError {}
79
80impl From<RelativeToErrorKind> for RelativeToError {
81    #[inline]
82    fn from(kind: RelativeToErrorKind) -> Self {
83        Self { kind }
84    }
85}
86
87/// Extension methods for [`Path`] and [`PathBuf`] to for building and
88/// interacting with [`RelativePath`].
89///
90/// [`RelativePath`]: crate::RelativePath
91pub trait PathExt: sealed::Sealed {
92    /// Build a relative path from the provided directory to `self`.
93    ///
94    /// Producing a relative path like this is a logical operation and does not
95    /// guarantee that the constructed path corresponds to what the filesystem
96    /// would do. On Linux for example symbolic links could mean that the
97    /// logical path doesn't correspond to the filesystem path.
98    ///
99    /// # Examples
100    ///
101    /// ```
102    /// use std::path::Path;
103    /// use relative_path::{RelativePath, PathExt};
104    ///
105    /// let baz = Path::new("/foo/bar/baz");
106    /// let bar = Path::new("/foo/bar");
107    /// let qux = Path::new("/foo/bar/qux");
108    ///
109    /// assert_eq!(bar.relative_to(baz)?, RelativePath::new("../"));
110    /// assert_eq!(baz.relative_to(bar)?, RelativePath::new("baz"));
111    /// assert_eq!(qux.relative_to(baz)?, RelativePath::new("../qux"));
112    /// assert_eq!(baz.relative_to(qux)?, RelativePath::new("../baz"));
113    /// assert_eq!(bar.relative_to(qux)?, RelativePath::new("../"));
114    /// # Ok::<_, relative_path::RelativeToError>(())
115    /// ```
116    ///
117    /// # Errors
118    ///
119    /// Errors in case the provided path contains components which cannot be
120    /// converted into a relative path as needed, such as non-utf8 data.
121    fn relative_to<P>(&self, root: P) -> Result<RelativePathBuf, RelativeToError>
122    where
123        P: AsRef<Path>;
124}
125
126impl PathExt for Path {
127    fn relative_to<P>(&self, root: P) -> Result<RelativePathBuf, RelativeToError>
128    where
129        P: AsRef<Path>,
130    {
131        use std::path::Component::{CurDir, Normal, ParentDir, Prefix, RootDir};
132
133        // Helper function to convert from a std::path::Component to a
134        // relative_path::Component.
135        fn std_to_c(c: std::path::Component<'_>) -> Result<Component<'_>, RelativeToError> {
136            Ok(match c {
137                CurDir => Component::CurDir,
138                ParentDir => Component::ParentDir,
139                Normal(n) => Component::Normal(n.to_str().ok_or(RelativeToErrorKind::NonUtf8)?),
140                _ => return Err(RelativeToErrorKind::IllegalComponent.into()),
141            })
142        }
143
144        let root = root.as_ref();
145        let mut a_it = self.components();
146        let mut b_it = root.components();
147
148        // Ensure that the two paths are both either relative, or have the same
149        // prefix. Strips any common prefix the two paths do have. Prefixes are
150        // platform dependent, but different prefixes would for example indicate
151        // paths for different drives on Windows.
152        let (a_head, b_head) = loop {
153            match (a_it.next(), b_it.next()) {
154                (Some(RootDir), Some(RootDir)) => (),
155                (Some(Prefix(a)), Some(Prefix(b))) if a == b => (),
156                (Some(Prefix(_) | RootDir), _) | (_, Some(Prefix(_) | RootDir)) => {
157                    return Err(RelativeToErrorKind::PrefixMismatch.into());
158                }
159                (None, None) => break (None, None),
160                (a, b) if a != b => break (a, b),
161                _ => (),
162            }
163        };
164
165        let mut a_it = a_head.into_iter().chain(a_it);
166        let mut b_it = b_head.into_iter().chain(b_it);
167        let mut buf = RelativePathBuf::new();
168
169        loop {
170            let a = if let Some(a) = a_it.next() {
171                a
172            } else {
173                for _ in b_it {
174                    buf.push(Component::ParentDir);
175                }
176
177                break;
178            };
179
180            match b_it.next() {
181                Some(CurDir) => buf.push(std_to_c(a)?),
182                Some(ParentDir) => {
183                    return Err(RelativeToErrorKind::AmbiguousTraversal.into());
184                }
185                root => {
186                    if root.is_some() {
187                        buf.push(Component::ParentDir);
188                    }
189
190                    for comp in b_it {
191                        match comp {
192                            ParentDir => {
193                                if !buf.pop() {
194                                    return Err(RelativeToErrorKind::AmbiguousTraversal.into());
195                                }
196                            }
197                            CurDir => (),
198                            _ => buf.push(Component::ParentDir),
199                        }
200                    }
201
202                    buf.push(std_to_c(a)?);
203
204                    for c in a_it {
205                        buf.push(std_to_c(c)?);
206                    }
207
208                    break;
209                }
210            }
211        }
212
213        Ok(buf)
214    }
215}
216
217impl PathExt for PathBuf {
218    #[inline]
219    fn relative_to<P>(&self, root: P) -> Result<RelativePathBuf, RelativeToError>
220    where
221        P: AsRef<Path>,
222    {
223        self.as_path().relative_to(root)
224    }
225}
226
227#[cfg(test)]
228mod tests {
229    use std::path::Path;
230
231    use super::{PathExt, RelativeToErrorKind};
232    use crate::{RelativePathBuf, RelativeToError};
233
234    macro_rules! assert_relative_to {
235        ($path:expr, $base:expr, Ok($expected:expr) $(,)?) => {
236            assert_eq!(
237                Path::new($path).relative_to($base),
238                Ok(RelativePathBuf::from($expected))
239            );
240        };
241
242        ($path:expr, $base:expr, Err($expected:ident) $(,)?) => {
243            assert_eq!(
244                Path::new($path).relative_to($base),
245                Err(RelativeToError::from(RelativeToErrorKind::$expected))
246            );
247        };
248    }
249
250    #[cfg(windows)]
251    macro_rules! abs {
252        ($path:expr) => {
253            Path::new(concat!("C:\\", $path))
254        };
255    }
256
257    #[cfg(not(windows))]
258    macro_rules! abs {
259        ($path:expr) => {
260            Path::new(concat!("/", $path))
261        };
262    }
263
264    #[test]
265    #[cfg(windows)]
266    fn test_different_prefixes() {
267        assert_relative_to!("C:\\repo", "D:\\repo", Err(PrefixMismatch),);
268        assert_relative_to!("C:\\repo", "C:\\repo", Ok(""));
269        assert_relative_to!(
270            "\\\\server\\share\\repo",
271            "\\\\server2\\share\\repo",
272            Err(PrefixMismatch),
273        );
274    }
275
276    #[test]
277    fn test_absolute() {
278        assert_relative_to!(abs!("foo"), abs!("bar"), Ok("../foo"));
279        assert_relative_to!("foo", "bar", Ok("../foo"));
280        assert_relative_to!(abs!("foo"), "bar", Err(PrefixMismatch));
281        assert_relative_to!("foo", abs!("bar"), Err(PrefixMismatch));
282    }
283
284    #[test]
285    fn test_identity() {
286        assert_relative_to!(".", ".", Ok(""));
287        assert_relative_to!("../foo", "../foo", Ok(""));
288        assert_relative_to!("./foo", "./foo", Ok(""));
289        assert_relative_to!("/foo", "/foo", Ok(""));
290        assert_relative_to!("foo", "foo", Ok(""));
291
292        assert_relative_to!("../foo/bar/baz", "../foo/bar/baz", Ok(""));
293        assert_relative_to!("foo/bar/baz", "foo/bar/baz", Ok(""));
294    }
295
296    #[test]
297    fn test_subset() {
298        assert_relative_to!("foo", "fo", Ok("../foo"));
299        assert_relative_to!("fo", "foo", Ok("../fo"));
300    }
301
302    #[test]
303    fn test_empty() {
304        assert_relative_to!("", "", Ok(""));
305        assert_relative_to!("foo", "", Ok("foo"));
306        assert_relative_to!("", "foo", Ok(".."));
307    }
308
309    #[test]
310    fn test_relative() {
311        assert_relative_to!("../foo", "../bar", Ok("../foo"));
312        assert_relative_to!("../foo", "../foo/bar/baz", Ok("../.."));
313        assert_relative_to!("../foo/bar/baz", "../foo", Ok("bar/baz"));
314
315        assert_relative_to!("foo/bar/baz", "foo", Ok("bar/baz"));
316        assert_relative_to!("foo/bar/baz", "foo/bar", Ok("baz"));
317        assert_relative_to!("foo/bar/baz", "foo/bar/baz", Ok(""));
318        assert_relative_to!("foo/bar/baz", "foo/bar/baz/", Ok(""));
319
320        assert_relative_to!("foo/bar/baz/", "foo", Ok("bar/baz"));
321        assert_relative_to!("foo/bar/baz/", "foo/bar", Ok("baz"));
322        assert_relative_to!("foo/bar/baz/", "foo/bar/baz", Ok(""));
323        assert_relative_to!("foo/bar/baz/", "foo/bar/baz/", Ok(""));
324
325        assert_relative_to!("foo/bar/baz", "foo/", Ok("bar/baz"));
326        assert_relative_to!("foo/bar/baz", "foo/bar/", Ok("baz"));
327        assert_relative_to!("foo/bar/baz", "foo/bar/baz", Ok(""));
328    }
329
330    #[test]
331    fn test_current_directory() {
332        assert_relative_to!(".", "foo", Ok("../."));
333        assert_relative_to!("foo", ".", Ok("foo"));
334        assert_relative_to!("/foo", "/.", Ok("foo"));
335    }
336
337    #[test]
338    fn assert_does_not_skip_parents() {
339        assert_relative_to!("some/path", "some/foo/baz/path", Ok("../../../path"));
340        assert_relative_to!("some/path", "some/foo/bar/../baz/path", Ok("../../../path"));
341    }
342
343    #[test]
344    fn test_ambiguous_paths() {
345        // Parent directory name is unknown, so trying to make current directory
346        // relative to it is impossible.
347        assert_relative_to!(".", "../..", Err(AmbiguousTraversal));
348        assert_relative_to!(".", "a/../..", Err(AmbiguousTraversal));
349        // Common prefixes are ok.
350        assert_relative_to!("../a/..", "../a/../b", Ok(".."));
351        assert_relative_to!("../a/../b", "../a/..", Ok("b"));
352    }
353}
relative_path/path_ext.rs

relative_path/
path_ext.rs
