X-Path

• X-Path
• Use cases
  • Config files
  • Clear expectations
  • Testable
  • Cross-platform
  • Convenient
• Design goals
• Limits
  • Characters
  • Path separators (slash) and drives
  • Path components
  • Filenames
• Path resolution
• Environment variables
• Path comparison
• References

⚠️ 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.

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 &strings with path.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() or format("{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:

• Non UTF-8 characters (i.e. don't use OsStr or OsString)
• NULL, :

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 is c
• 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.

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 braces
• hi${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.

References

• File path formats on Windows systems
• Naming Files, Paths, and Namespaces
• Wikipedia: Filenames - Comparison of filename limitations