Crate typed_path
source ·Expand description
Typed Path
Provides typed variants of Path
and PathBuf
for
Unix and Windows.
Install
[dependencies]
typed-path = "0.7"
Why?
Some applications need to manipulate Windows or UNIX paths on different platforms, for a variety of reasons: constructing portable file formats, parsing files from other platforms, handling archive formats, working with certain network protocols, and so on.
– Josh Triplett
Check out this issue of a discussion for this. The functionality actually exists within the standard library, but is not exposed!
This means that parsing a path like C:\path\to\file.txt
will be parsed
differently by std::path::Path
depending on which platform you are
on!
use std::path::Path;
fn main() {
// On Windows, this prints out:
//
// * Prefix(PrefixComponent { raw: "C:", parsed: Disk(67) })
// * RootDir
// * Normal("path")
// * Normal("to")
// * Normal("file.txt")]
//
// But on Unix, this prints out:
//
// * Normal("C:\\path\\to\\file.txt")
let path = Path::new(r"C:\path\to\file.txt");
for component in path.components() {
println!("* {:?}", component);
}
}
Usage
Byte paths
The library provides a generic Path<T>
and PathBuf<T>
that use [u8]
and Vec<u8>
underneath instead of OsStr
and OsString
. An
encoding generic type is provided to dictate how the underlying bytes are
parsed in order to support consistent path functionality no matter what
operating system you are compiling against!
use typed_path::WindowsPath;
fn main() {
// On all platforms, this prints out:
//
// * Prefix(PrefixComponent { raw: "C:", parsed: Disk(67) })
// * RootDir
// * Normal("path")
// * Normal("to")
// * Normal("file.txt")]
//
let path = WindowsPath::new(r"C:\path\to\file.txt");
for component in path.components() {
println!("* {:?}", component);
}
}
UTF8-enforced paths
Alongside the byte paths, this library also supports UTF8-enforced paths
through Utf8Path<T>
and Utf8PathBuf<T>
, which
internally use str
and String
. An encoding generic type is provided to
dictate how the underlying characters are parsed in order to support consistent
path functionality no matter what operating system you are compiling against!
use typed_path::Utf8WindowsPath;
fn main() {
// On all platforms, this prints out:
//
// * Prefix(Utf8WindowsPrefixComponent { raw: "C:", parsed: Disk(67) })
// * RootDir
// * Normal("path")
// * Normal("to")
// * Normal("file.txt")]
//
let path = Utf8WindowsPath::new(r"C:\path\to\file.txt");
for component in path.components() {
println!("* {:?}", component);
}
}
Converting between encodings
There may be times in which you need to convert between encodings such as when
you want to load a native path and convert it into another format. In that
case, you can use the with_encoding
method (or specific variants like
with_unix_encoding
and with_windows_encoding
) to convert a Path
or Utf8Path
into their respective PathBuf
and
Utf8PathBuf
with an explicit encoding:
use typed_path::{Utf8Path, Utf8UnixEncoding, Utf8WindowsEncoding};
fn main() {
// Convert from Unix to Windows
let unix_path = Utf8Path::<Utf8UnixEncoding>::new("/tmp/foo.txt");
let windows_path = unix_path.with_encoding::<Utf8WindowsEncoding>();
assert_eq!(windows_path, Utf8Path::<Utf8WindowsEncoding>::new(r"\tmp\foo.txt"));
// Converting from Windows to Unix will drop any prefix
let windows_path = Utf8Path::<Utf8WindowsEncoding>::new(r"C:\tmp\foo.txt");
let unix_path = windows_path.with_encoding::<Utf8UnixEncoding>();
assert_eq!(unix_path, Utf8Path::<Utf8UnixEncoding>::new(r"/tmp/foo.txt"));
// Converting to itself should retain everything
let path = Utf8Path::<Utf8WindowsEncoding>::new(r"C:\tmp\foo.txt");
assert_eq!(
path.with_encoding::<Utf8WindowsEncoding>(),
Utf8Path::<Utf8WindowsEncoding>::new(r"C:\tmp\foo.txt"),
);
}
Typed Paths
In the above examples, we were using paths where the encoding (Unix or Windows)
was known at compile time. There may be situations where we need runtime
support to decide and switch between encodings. For that, this crate provides
the TypedPath
and TypedPathBuf
enumerations
(and their Utf8TypedPath
and
Utf8TypedPathBuf
variations):
use typed_path::Utf8TypedPath;
// Derive the path by determining if it is Unix or Windows
let path = Utf8TypedPath::derive(r"C:\path\to\file.txt");
assert!(path.is_windows());
// Change the encoding to Unix
let path = path.with_unix_encoding();
assert_eq!(path, "/path/to/file.txt");
Normalization
Alongside implementing the standard methods associated with Path
and PathBuf
from the standard library, this crate also
implements several additional methods including the ability to normalize a path
by resolving .
and ..
without the need to have the path exist.
use typed_path::Utf8UnixPath;
assert_eq!(
Utf8UnixPath::new("foo/bar//baz/./asdf/quux/..").normalize(),
Utf8UnixPath::new("foo/bar/baz/asdf"),
);
In addition, you can leverage absolutize
to convert a path to an absolute
form by prepending the current working directory if the path is relative and
then normalizing it (requires std
feature):
use typed_path::{utils, Utf8UnixPath};
// With an absolute path, it is just normalized
// NOTE: This requires `std` feature, otherwise `absolutize` is missing!
let path = Utf8UnixPath::new("/a/b/../c/./d");
assert_eq!(path.absolutize().unwrap(), Utf8UnixPath::new("/a/c/d"));
// With a relative path, it is first joined with the current working directory
// and then normalized
// NOTE: This requires `std` feature, otherwise `utf8_current_dir` and
// `absolutize` are missing!
let cwd = utils::utf8_current_dir().unwrap().with_unix_encoding();
let path = cwd.join(Utf8UnixPath::new("a/b/../c/./d"));
assert_eq!(path.absolutize().unwrap(), cwd.join(Utf8UnixPath::new("a/c/d")));
Current directory
Helper functions are available in the utils
module (requires std
feature), and one of those provides an identical experience to
std::env::current_dir
:
// Retrieves the current directory as a NativePath:
//
// * For Unix family, this would be Path<UnixEncoding>
// * For Windows family, this would be Path<WindowsEncoding>
//
// NOTE: This requires `std` feature, otherwise `current_dir` is missing!
let _cwd = typed_path::utils::current_dir().unwrap();
// Retrieves the current directory as a Utf8NativePath:
//
// * For Unix family, this would be Utf8Path<Utf8UnixEncoding>
// * For Windows family, this would be Utf8Path<Utf8WindowsEncoding>
//
// NOTE: This requires `std` feature, otherwise `utf8_current_dir` is missing!
let _utf8_cwd = typed_path::utils::utf8_current_dir().unwrap();
License
This project is licensed under either of
Apache License, Version 2.0, (LICENSE-APACHE or apache-license) MIT license (LICENSE-MIT or mit-license) at your option.
Modules
- Contains constants associated with different path formats.
Structs
- An iterator over
Path
and its ancestors. - Helper struct for safely printing paths with
format!
and{}
. - A slice of a path (akin to
str
). - An owned, mutable path that mirrors
std::path::PathBuf
, but operatings using anEncoding
to determine how to parse the underlying bytes. - An error returned if the prefix was not found.
- Represents a Unix-specific
Encoding
- An iterator over
Utf8Path
and its ancestors. - A slice of a path (akin to
str
). - An owned, mutable path that mirrors
std::path::PathBuf
, but operatings using aUtf8Encoding
to determine how to parse the underlying str. - Represents a Unix-specific
Utf8Encoding
- Represents a Windows-specific
Components
- Represents a Windows-specific
Utf8Encoding
- A structure wrapping a Windows path prefix as well as its unparsed string representation.
str
version ofstd::path::PrefixComponent
. - Represents a Windows-specific
Components
- Represents a Windows-specific
Encoding
- A structure wrapping a Windows path prefix as well as its unparsed string representation. Byte slice version of
std::path::PrefixComponent
.
Enums
- Represents the type of the path.
- An iterator over
TypedPath
and its ancestors. - Byte slice version of
std::path::Component
that represents either a Unix or Windows path component. - Represents a path with a known type that can be one of:
- Represents a pathbuf with a known type that can be one of:
- Byte slice version of
std::path::Component
that represents a Unix-specific component - An iterator over
Utf8TypedPath
and its ancestors. - Str slice version of
std::path::Component
that represents either a Unix or Windows path component. - Represents a path with a known type that can be one of:
- Represents a pathbuf with a known type that can be one of:
str
slice version ofstd::path::Component
that represents a Unix-specific componentstr
slice version ofstd::path::Component
that represents a Windows-specific component- Windows path prefixes, e.g.,
C:
or\\server\share
. This is a byte slice version ofstd::path::Prefix
. - Byte slice version of
std::path::Component
that represents a Windows-specific component - Windows path prefixes, e.g.,
C:
or\\server\share
. This is a byte slice version ofstd::path::Prefix
.
Traits
- Interface representing a component in a
Path
- Interface of an iterator over a collection of
Component
s - Interface to provide meaning to a byte slice such that paths can be derived
- Interface to try to perform a cheap reference-to-reference conversion.
- Interface representing a component in a
Utf8Path
- Interface of an iterator over a collection of
Utf8Component
s - Interface to provide meaning to a byte slice such that paths can be derived
Type Aliases
Component
that is native to the platform during compilationEncoding
that is native to the platform during compilationPath
that is native to the platform during compilationPathBuf
that is native to the platform during compilation- Represents a Unix-specific
Path
- Represents a Unix-specific
PathBuf
Utf8Component
that is native to the platform during compilationUtf8Path
that is native to the platform during compilationUtf8Path
that is native to the platform during compilationUtf8PathBuf
that is native to the platform during compilation- Represents a Unix-specific
Utf8Path
- Represents a Unix-specific
Utf8PathBuf
- Represents a Windows-specific
Utf8Path
- Represents a Windows-specific
Utf8PathBuf
- Represents a Windows-specific
Path
- Represents a Windows-specific
PathBuf