# Typed Path

[![Crates.io][crates_img]][crates_lnk] [![Docs.rs][doc_img]][doc_lnk] [![CI][ci_img]][ci_lnk] [![RustC 1.58.1+][rustc_img]][rustc_lnk] 

[crates_img]: https://img.shields.io/crates/v/typed-path.svg
[crates_lnk]: https://crates.io/crates/typed-path
[doc_img]: https://docs.rs/typed-path/badge.svg
[doc_lnk]: https://docs.rs/typed-path
[ci_img]: https://github.com/chipsenkbeil/typed-path/actions/workflows/ci.yml/badge.svg
[ci_lnk]: https://github.com/chipsenkbeil/typed-path/actions/workflows/ci.yml
[rustc_img]: https://img.shields.io/badge/rustc_1.58.1+-lightgray.svg
[rustc_lnk]: https://blog.rust-lang.org/2022/01/20/Rust-1.58.1.html

Provides typed variants of [`Path`][StdPath] and [`PathBuf`][StdPathBuf] for
Unix and Windows.

## Install

```toml
[dependencies]
typed-path = "0.7"
```

As of version `0.7`, this library also supports `no_std` environments that
depend on `alloc`. To build in this manner, remove the default `std` feature:

```toml
[dependencies]
typed-path = { version = "...", default-features = false }
```

## 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](https://github.com/rust-lang/rust/issues/66621) 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`][StdPath] depending on which platform you are
on!

```rust
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>`][Path] and [`PathBuf<T>`][PathBuf]
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!

```rust
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>`][Utf8Path] and [`Utf8PathBuf<T>`][Utf8PathBuf], 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!

```rust
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`][Path]
or [`Utf8Path`][Utf8Path] into their respective [`PathBuf`][PathBuf] and
[`Utf8PathBuf`][Utf8PathBuf] with an explicit encoding:

```rust
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`][TypedPath] and [`TypedPathBuf`][TypedPathBuf] enumerations
(and their [`Utf8TypedPath`][Utf8TypedPath] and
[`Utf8TypedPathBuf`][Utf8TypedPathBuf] variations):

```rust
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`][StdPath]
and [`PathBuf`][StdPathBuf] 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.


```rust
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):

```rust
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`][utils] module (requires `std`
feature), and one of those provides an identical experience to
[`std::env::current_dir`](https://doc.rust-lang.org/std/env/fn.current_dir.html):

```rust
// 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][apache-license]) MIT license (LICENSE-MIT or
[mit-license][mit-license]) at your option.

[apache-license]: http://www.apache.org/licenses/LICENSE-2.0
[mit-license]: http://opensource.org/licenses/MIT

[StdPath]: https://doc.rust-lang.org/std/path/struct.Path.html
[StdPathBuf]: https://doc.rust-lang.org/std/path/struct.PathBuf.html
[Path]: https://docs.rs/typed-path/latest/typed_path/struct.Path.html
[PathBuf]: https://docs.rs/typed-path/latest/typed_path/struct.PathBuf.html
[Utf8Path]: https://docs.rs/typed-path/latest/typed_path/struct.Utf8Path.html
[Utf8PathBuf]: https://docs.rs/typed-path/latest/typed_path/struct.Utf8PathBuf.html
[UnixPath]: https://docs.rs/typed-path/latest/typed_path/type.UnixPath.html
[UnixPathBuf]: https://docs.rs/typed-path/latest/typed_path/type.UnixPathBuf.html
[Utf8UnixPath]: https://docs.rs/typed-path/latest/typed_path/type.Utf8UnixPath.html
[Utf8UnixPathBuf]: https://docs.rs/typed-path/latest/typed_path/type.Utf8UnixPathBuf.html
[WindowsPath]: https://docs.rs/typed-path/latest/typed_path/type.WindowsPath.html
[WindowsPathBuf]: https://docs.rs/typed-path/latest/typed_path/type.WindowsPathBuf.html
[Utf8WindowsPath]: https://docs.rs/typed-path/latest/typed_path/type.Utf8WindowsPath.html
[Utf8WindowsPathBuf]: https://docs.rs/typed-path/latest/typed_path/type.Utf8WindowsPathBuf.html
[TypedPath]: https://docs.rs/typed-path/latest/typed_path/enum.TypedPath.html
[TypedPathBuf]: https://docs.rs/typed-path/latest/typed_path/enum.TypedPathBuf.html
[Utf8TypedPath]: https://docs.rs/typed-path/latest/typed_path/enum.Utf8TypedPath.html
[Utf8TypedPathBuf]: https://docs.rs/typed-path/latest/typed_path/enum.Utf8TypedPathBuf.html
[utils]: https://docs.rs/typed-path/latest/typed_path/utils/index.html
