Portable, relative paths for Rust.
This library provides two types: RelativePath
and RelativePathBuf
.
These are analogous to the Path
and PathBuf
structures provided through standard Rust.
While Path
provides an API that adapts to a given platform, RelativePath
does not.
Instead RelativePath
uses a fixed, slash-separated representation regardless of platform.
Windows permits using drive volumes as a prefix (e.g. "c:\"
) and backslash (\
) as a separator.
Storing paths like this would build and run on one platform, but not others.
Another hairy issue is that data serialized for one platform through serde might not be
usable on another:
#[derive(Serialize, Deserialize)]
struct Message {
path: PathBuf,
}
Since RelativePath
only uses /
as a separator it avoids this issue.
Anything non-slash else will be considered part of a distinc 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.
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.
The following is an example configuration for a made up project:
lib = "src/lib.rs"
bin = "src/bin/hello.rs"
The corresponding Rust struct to deserialize it would look like this:
#[derive(Deserialize)]
pub struct Manifest {
lib: RelativePathBuf,
bin: RelativePathBuf,
}
RelativePath
, similarly to Path
, makes no guarantees that the components represented in them
makes up legal file names.
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.
- Verify that relative paths are - indeed - portable.
- Better function documentation with examples.
- Support more
Path
-like functions.