simple-unc 0.2.2

Simplify Windows UNC path for `fs::canonicalize`
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

[![CI-badge]][CI]
[![crate-badge]][crate]
[![docs-badge]][docs]

[CI-badge]: https://github.com/kojiishi/simple-unc/actions/workflows/rust-ci.yml/badge.svg
[CI]: https://github.com/kojiishi/simple-unc/actions/workflows/rust-ci.yml
[crate-badge]: https://img.shields.io/crates/v/simple-unc.svg
[crate]: https://crates.io/crates/simple-unc
[docs-badge]: https://docs.rs/simple-unc/badge.svg
[docs]: https://docs.rs/simple-unc/

# SimpleUnc

On Windows,
[`fs::canonicalize`] returns a path prefixed by "`\\?\`".
such as:
```
\\?\UNC\server\share\dir
```
The "`\\?\`" prefix is called the [Win32 File Namespaces].
It has advantages such as long paths,
and is fine for most modern APIs,
but some programs can't handle them.
PowerShell and `cmd.exe` are examples of such programs.

The `SimpleUnc` simplifies network share UNC paths
so that these programs can handle.

Since the simplification may not always be safe,
it does so if they are currently mapped to drives.

Let's say your PC has a network share on the `Z:` drive:
```
net use Z: \\server\share
```
If you run the following code on this PC:
```rust
let path = r"Z:\dir\file";
let canonicalized = fs::canonicalize(path)?;
println!("{}", canonicalized.display());
```
prints:
```
\\?\UNC\server\share\dir\file
```
Neither PowerShell nor `cmd.exe` can handle this path.

With the `SimpleUnc`:
```rust
let path = r"Z:\dir\file";
let simplified = SimpleUnc::default().canonicalize(path)?;
println!("{}", simplified.display());
```
prints:
```
\\server\share\dir\file
```
This path works fine for PowerShell and `cmd.exe`.

## Drive

If you prefer to use the network drive in the path:
```rust
let path = r"Z:\dir\file";
let unc = SimpleUnc { map_to_drive: true, ..Default::default() };
let simplified = unc.canonicalize(path)?;
println!("{}", simplified.display());
```
prints:
```
Z:\dir\file
```

## Dunce

The `SimpleUnc` calls the [`dunce`] crate
to normalize some other cases, such as:
```
\\?\C:\foo
```
to:
```
C:\foo
```
You can skip the [`dunce`] simplification if you prefer:
```rust
let unc = SimpleUnc { skip_dunce: true, ..Default::default() };
```

[`dunce`]: https://crates.io/crates/dunce
[`fs::canonicalize`]: https://doc.rust-lang.org/std/fs/fn.canonicalize.html
[Win32 File Namespaces]: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#win32-file-namespaces