#path

relative-path

Portable, relative paths for Rust

30 releases (8 stable)

1.3.2 Jul 12, 2020
1.2.1 Jun 16, 2020
1.0.0 Oct 11, 2019
0.4.0 Sep 7, 2018
0.1.5 Nov 5, 2017

#7 in Filesystem

Download history 2627/week @ 2020-04-18 2301/week @ 2020-04-25 3363/week @ 2020-05-02 2697/week @ 2020-05-09 2452/week @ 2020-05-16 2402/week @ 2020-05-23 2569/week @ 2020-05-30 2495/week @ 2020-06-06 2575/week @ 2020-06-13 2998/week @ 2020-06-20 2406/week @ 2020-06-27 3775/week @ 2020-07-04 3632/week @ 2020-07-11 2053/week @ 2020-07-18 1608/week @ 2020-07-25 1395/week @ 2020-08-01

11,661 downloads per month
Used in 43 crates (14 directly)

MIT/Apache

78KB
1.5K SLoC

Build Status crates.io docs.rs discord

relative-path

Portable relative UTF-8 paths for Rust.

This provide a module analogous to std::path, with the following characteristics:

  • The path separator is set to a fixed character (/), regardless of platform.
  • Relative paths cannot represent a path in the filesystem without first specifying what they are relative to through to_path.
  • Relative paths are always guaranteed to be a UTF-8 string.

On top of this we support many path-like operations that guarantee portable behavior.

Serde Support

This library includes serde support that can be enabled with the serde feature.

Why is std::path a portability hazard?

Path representations differ across platforms.

  • Windows permits using drive volumes (multiple roots) as a prefix (e.g. "c:\") and backslash (\) as a separator.
  • Unix references absolute paths from a single root and uses slash (/) as a separator.

If we use PathBuf, Storing paths like this in a manifest would happily allow our applications to build and run on one platform, but potentially not others.

Consider the following manifest:

use std::path::PathBuf;
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
struct Manifest {
    source: PathBuf,
}

Which represents this TOML file:

# Uh oh, trouble.
source = "C:\\path\\to\\source"

Assuming "C:\\path\\to\\source" is a legal path on Windows, this will happily run for one platform when checked into source control but not others.

Since RelativePath strictly uses / as a separator it avoids this issue. Anything non-slash will simply be considered part of a distinct component.

Conversion to Path may only happen if it is known which path it is relative to through the to_path function. This is where the relative part of the name comes from.

use relative_path::RelativePath;
use std::path::Path;

let relative_path = RelativePath::new("foo/bar");
let path = Path::new("C:\\");
let full_path = relative_path.to_path(path);

This would permit relative paths to portably be used in project manifests or configurations. Where files are referenced from some specific, well-known point in the filesystem.

source = "path/to/source"

The fixed manifest would look like this:

use relative_path::RelativePathBuf;
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
pub struct Manifest {
    source: RelativePathBuf,
}

Overview

When two relative paths are compared to each other, their exact component makeup determines equality.

use relative_path::RelativePath;

assert_ne!(
    RelativePath::new("foo/bar/../baz"),
    RelativePath::new("foo/baz")
);

Using platform-specific path separators to construct relative paths is not supported.

Path separators from other platforms are simply treated as part of a component:

use relative_path::RelativePath;

assert_ne!(
    RelativePath::new("foo/bar"),
    RelativePath::new("foo\\bar")
);

assert_eq!(1, RelativePath::new("foo\\bar").components().count());
assert_eq!(2, RelativePath::new("foo/bar").components().count());

To see if two relative paths are equivalent you can use normalize:

use relative_path::RelativePath;

assert_eq!(
    RelativePath::new("foo/bar/../baz").normalize(),
    RelativePath::new("foo/baz").normalize(),
);

Additional portability notes

While relative paths avoid the most egregious portability issues, namely that absolute paths will work equally unwell on all platforms. We do not avoid all.

This section tries to document additional portability issues that we know about.

RelativePath, similarly to Path, makes no guarantees that the components represented in them makes up legal file names. While components are strictly separated by slashes, we can still store things in path components which may not be used as legal paths on all platforms.

  • NUL is not permitted on unix platforms - this is a terminator in C-based filesystem APIs. Slash (/) is also used as a path separator.
  • Windows has a number of reserved characters and names.

As a relative path that actually contains a platform-specific absolute path will result in a nonsensical path being generated.

use relative_path::RelativePath;
use std::path::Path;

if cfg!(windows) {
    assert_eq!(
        Path::new("foo\\c:\\bar\\baz"),
        RelativePath::new("c:\\bar\\baz").to_path("foo")
    );
}

if cfg!(unix) {
    assert_eq!(
        Path::new("foo/bar/baz"),
        RelativePath::new("/bar/baz").to_path("foo")
    );
}

This is intentional in order to cause an early breakage when a platform encounters paths like "foo/c:\\bar\\baz" to signal that it is a portability hazard. On Unix it's a bit more subtle with ""foo/bar/baz"", since the leading slash (/) will simply be ignored. The hope is that it will be more probable to cause an early error unless a compatible relative path also exists.

Dependencies

~72KB