normal-path 0.2.0

Ensure paths are normalized without I/O
Documentation
  • Coverage
  • 100%
    11 out of 11 items documented1 out of 1 items with examples
  • Size
  • Source code size: 125.7 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 9.92 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 27s Average build duration of successful builds.
  • all releases: 27s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • auckas/normal-path
    1 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • auckas

normal-path

Crates.io Documentation License

A Rust library to ensure paths are normalized without touching the filesystem.

This library provides two types, NormpathBuf and Normpath (akin to PathBuf and Path), for working with normalized paths abstractly. Similar to the standard library, these types are thin wrappers around OsString and OsStr that represent normalized paths according to the local platform's path syntax.

Features

  • No I/O: Normalizes paths purely on the string level, without touching the filesystem.
  • Cross-platform: Handles Unix and Windows path semantics correctly.
  • Type-checked: Ensures paths are absolute, canonical, and free of parent directory components (..).
  • Normalization: Can normalize non-canonical patterns (like //, ./, trailing slashes, and on Windows, forward slashes and lowercase drive letters) into their canonical forms.
  • Serde support: Optional serde feature for serialization and deserialization.

Example

use normal_path::{Normpath, NormpathBuf};

// Validate an already normalized path
let path = Normpath::validate("/foo/bar").unwrap();

// Normalize a path with non-canonical patterns
let normalized = NormpathBuf::normalize("/foo/./bar//".into()).unwrap();
assert_eq!(&normalized, "/foo/bar");

Normalization Rules

In general, a path is considered normalized if and only if:

  1. It is absolute, i.e., independent of the current directory.
  2. It is canonical, meaning it does not contain any pattern that is considered non-canonical and has a corresponding canonical form depending on the platform.
  3. It does not contain any parent directory component (..).

A normalized path is not necessarily the "real" path to the filesystem object it denotes, which may not even exist. Instead, it defines a path unambiguously on the string level, unaffected by the state of the filesystem.

Canonicality

These patterns are considered non-canonical on both Unix and Windows:

  1. Multiple consecutive slashes (foo//bar).
  2. Trailing slashes (foo/bar/).
  3. Current directory components (foo/. or ./foo).

Specifically on Windows, the following patterns are also considered non-canonical:

  1. Forward slashes (D:\foo/bar or //./COM11).
  2. Lowercase drive letters (d:\).
  3. Parent directory components (that can be normalized).

Handling Parent Directories

On Unix, any parent component is an error, since it is impossible to eliminate them without filesystem access.

Windows, on the other hand, collapses parent components lexically before walking the filesystem (unless the path starts with \\?\). Therefore, it is only a hard error if a parent component points outside of the base directory, like C:\...

License

Licensed under either of

at your option.