Expand description
⚠️ WARNING
This is work in progress and is not ready for use
Use cases
Config files
The paths below are valid on any platform. They will be cleaned and have environment variables resolved at load.
dir1 = "~/mydir/${SOME_ENV}/../"
dir2 = "c:\\anotherdir\\%ANOTHER_ENV%"
Clear expectations
Use one of the below to communicate what your function or API expects.
Any | Dir | File | |
---|---|---|---|
Any | AnyPath | DirPath | FilePath |
Rel | RelPath | RelDirPath | RelFilePath |
Abs | AbsPath | AbsDirPath | AbsFilePath |
fn mirror(file: RelFilePath, from: AbsDirPath, to: AbsDirPath) {}
Testable
#[test]
fn test() -> anyhow::Result<()> {
// imagine that the path string is read from a conf.toml file:
let dir = AbsDirPath::new(r"~/dir1//..\dir2");
// when using the alternative debug specifier, if the path starts
// with current working directory or user home, then they are replaced
// with '.' or '~' respectively. The path separator used is always '/'.
assert_eq!(format!("{:#?}", dir), "AbsDirPath(~/dir2)");
// standard debug output uses the internal representation of the path
// which uses the full path with platform specific path separators.
// linux:
assert_eq!(format!("{:?}", dir), "AbsDirPath(/home/me/code/dir2)");
// windows:
assert_eq!(format!("{:?}", dir), r"AbsDirPath(c:\Users\me\code\dir2)");
}
Cross-platform
Both Windows-style and Unix-style paths can be used on all platforms. They are all resolved and converted into a unified format that is comparable.
The typical file system restrictions are enforced when read.
On Windows, the NTFS, VFAT and exFAT restrictions are applied which are
much more stringent than the Unix ones. Enable the feature strict
if
you want the same restrictions applied when running on Unix.
Convenient
Access the paths as &str
, all paths implement:
- Display for easy display.
AsRef<Path>
for interoperability with all the std::fs operations.- Iterate through all the path segments as
&str
ings withpath.segments()
. - Many convenient functions: see the doc for each path type.
Design goals
- Make rust’s typical “if it compiles it works” experience work for cross-platform path handling as well.
- Make Paths comparable, i.e. they are resolved to a common format in memory, and converted to a platform-specific format when used.
- Write config files using paths that work across platforms (as far as possible).
- AnyPath for general use and specific ones when you need to assure that
- Provide types distinguishing between Absolute or Relative and Directory or File:
- FilePath, FileAbsPath, FileRelPath
- DirPath, DirAbsPath, DirAbsPath
- Support for the major operating systems and file systems:
- Linux & Unix: most file systems.
- macOS: HFS+, APFS.
- Windows: exFAT, NTFS. With feature
strict
enabled.
- Comparable paths (because they are resolved, see Path Comparison below).
Non-goals:
- Maximum performance.
- Crazy filenames. I.e. only UTF-8 filenames are supported.
Other:
- Displays resolved paths or use
.native_string()
orformat("{path:#}")
for outputting OS native string. - Error:
- handling with anyhow aims to produce comprehensive human-readable messages instead of machine-parsable ones.
- the message always includes the path in question.
- the message includes the current working directory for relative paths.
Limits
The limits are verified when creating and manipulating a path. By default, on Unix-based platforms, only a few limits are applied. On Windows, there are automatically more restrictions.
If you want to ensure that the paths work seamlessly (as far as possible)
on all platforms (i.e. paths authored on Linux work on Windows) then turn on the strict
Cargo feature.
Characters
Reserved characters:
- Slash (
/
and\
): are used as path separators on all platforms. $
and%
: when at the start of a path or immediately after a slash it will be interpreted as an environment variable see section Environment variables.
and~
when at the start of a path followed by either a slash or nothing are interpreted as the current working dir and user home dir respectively.
Always forbidden:
Forbidden in strict
mode or when running on Windows:
- Ascii control characters: 0x00-0x1F, 0x7F
"
,*
,/
,<
,>
,?
,\
,|
- Filenames: CON, PRN, AUX, NUL, COM0 - COM9 and LPT0 - LPT9. Also any of these filenames followed by an extension (ex: .txt).
Path separators (slash) and drives
The path separators are kept in memory and displayed in a platform-native representation,
i.e. using the platform where the binary is running. For Windows, it’s \
and for the others /
.
On Windows, any drive letters are kept lower-cased, and on the others, it is discarded.
This means that a string written as either c:\my\path
or /my/path
is converted and stored in memory and displayed as:
- Windows:
c:\my\path
when the current directory’s drive letter isc
- Others:
/my/path
Path components
Path components are limited to a maximum of 255 characters.
Filenames
Forbidden in strict
mode or when running on Windows: CON, PRN, AUX, NUL, COM0 - COM9 and LPT0 - LPT9.
Also any of these filenames followed by an extension (ex: .txt).
Path resolution
Path resolution is done without file-system access so that paths don’t need to exist.
Path* | Becomes | When | Is | Comment |
---|---|---|---|---|
. , ./ | nix: /tmp win: c:\tmp | current_dir() | nix: /tmp win: c:\tmp | |
~ , ~/ | nix: /Users/tom win: c:\Users\tom | home_dir() | nix: /Users/tom win: c:\Users\tom | |
/ | nix: / win: c:\ | - current_dir() | - win: c:/somedir | - win: Same drive as the current dir |
c:/ , C:/ | nix: / win: c:\ | nix: Drive letter removed win: Drive letters always in lower case | ||
c:dir | nix: /tmp/dir win: c:\tmp\dir | current_dir() | nix: /tmp win: c:\tmp | |
dir//dir | nix: dir/dir win: dir\dir | Multiple slashes are joined | ||
dir/./dir | nix: dir/dir win: dir\dir | Dots inside of a path are ignored | ||
dir/.. | Empty path | |||
dir1/dir2/.. | dir1 | |||
${MYDIR} ,%MYDIR% | dir | var(“MYDIR”) | dir | See Environment variables |
Legend:
- * - Any
/
can also be\
. - nix - Unix-based platforms: Linux, Unix, macOS.
- win - Windows
- current_dir() - refers to rust’s std::env::current_dir()
- var() - refers to rust’s std::env::var(key)
- home_dir() - refers to the dirs_sys::home_dir()
Environment variables
There is restricted support for environment variables where only a path segment that
in Unix style: starts with ${
and ends with }
or in Windows style starts and ends with %
is interpreted as an environment variable and expanded when read. The stricter-than-usual
requirements reduce interference with normal paths.
Interpreted as environment variables:
/dir/${MYVAR}/
,${MYVAR}
,${MYVAR}/dir
,/dir/${MYVAR}
/dir/%MYVAR%/
,%MYVAR%
,%MYVAR%/dir
,/dir/%MYVAR%
Not interpreted as environment vars:
$MYVAR
- missing curly braceshi${MYVAR}
,${MYVAR}hi
,hi%MYVAR%
,%MYVAR%hi
- any character before or after that is not a slash.${MYVAR
,%MYVAR
- not closed.${MY-VAR}
,%MY-VAR%
: use of character not permitted in environment variables.
Returns an error:
${}
,\${}
,\${}\
- empty keys are invalid%MYVAR
when the environment variable MYVAR is not defined.
Path comparison
While paths preserve casing when kept in memory comparing is done in a case-insensitive manner.