Portable relative UTF-8 paths for Rust.
This crate provides a module analogous to
std::path, with the following
- 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 using functions such as
- Relative paths are always guaranteed to be valid UTF-8 strings.
On top of this we support many operations that guarantee the same behavior across platforms.
relative-path to your
Start using relative paths:
use ; use RelativePath;
This library includes serde support that can be enabled with the
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 forward slash
/) as a separator.
If we use
PathBuf, Storing paths in a manifest would allow our application
to build and run on one platform but potentially not others.
Consider the following data model and corresponding toml for a manifest:
use PathBuf; use ;
This will run for you (assuming
source exists). So you go ahead and check
the manifest into git. The next day your Linux colleague calls you and
wonders what they have ever done to wrong you?
So what went wrong? Well two things. You forgot to make the
relative, so anyone at the company which has a different username than you
won't be able to use it. So you go ahead and fix that:
But there is still one problem! A backslash (
\) is only a legal path
separator on Windows. Luckily you learn that forward slashes are supported
both on Windows and Linux. So you opt for:
Things are working now. So all is well... Right? Sure, but we can do better.
This crate provides types that work with portable relative paths (hence
the name). So by using
RelativePath we can systematically help avoid
portability issues like the one above. Avoiding issues at the source is
preferably over spending 5 minutes of onboarding time on a theoretical
problem, hoping that your new hires will remember what to do if they ever
RelativePathBuf we can fix our data model like this:
use RelativePathBuf; use ;
And where it's used:
use fs; use current_dir; let manifest: Manifest = todo!; let root = current_dir?; let source = manifest.source.to_path; let content = read?;
Conversion to a platform-specific
Path happens through the
to_logical_path functions. Where you are required to specify the
path that prefixes the relative path. This can come from a function such as
use current_dir; use Path; use RelativePath; let root = current_dir?; // to_path unconditionally concatenates a relative path with its base: let relative_path = new; let full_path = relative_path.to_path; assert_eq!; // to_logical_path tries to apply the logical operations that the relative // path corresponds to: let relative_path = new; let full_path = relative_path.to_logical_path; // Replicate the operation performed by `to_logical_path`. let mut parent = root.clone; parent.pop; assert_eq!;
When two relative paths are compared to each other, their exact component makeup determines equality.
use RelativePath; assert_ne!;
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 RelativePath; assert_ne!; assert_eq!; assert_eq!;
To see if two relative paths are equivalent you can use
use RelativePath; assert_eq!;
Additional portability notes
While relative paths avoid the most egregious portability issue, that absolute paths will work equally unwell on all platforms. We cannot avoid all. This section tries to document additional portability hazards that we are aware of.
RelativePath, similarly to
Path, makes no guarantees that its
constituent components make up legal file names. While components are
strictly separated by slashes, we can still store things in them which may
not be used as legal paths on all platforms.
NULcharacter 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
AUX) which cannot legally be part of a filesystem component.
- Windows paths are case-insensitive by default. So,
foo.txtare the same files on windows. But they are considered different paths on most unix systems.
A relative path that accidentally contains a platform-specific components will largely result in a nonsensical paths being generated in the hope that they will fail fast during development and testing.
use ; use Path; if cfg! if cfg! assert_eq!;