1<!--
2	This readme is created with https://github.com/livioribeiro/cargo-readme
3
4	Edit `src/lib.rs` and use `cargo readme > README.md` to update it.
5-->
6
7# fs-err
8
9[![Crates.io](https://img.shields.io/crates/v/fs-err.svg)](https://crates.io/crates/fs-err)
10[![GitHub Actions](https://github.com/andrewhickman/fs-err/workflows/CI/badge.svg)](https://github.com/andrewhickman/fs-err/actions?query=workflow%3ACI)
11
12fs-err is a drop-in replacement for [`std::fs`][std::fs] that provides more
13helpful messages on errors. Extra information includes which operations was
14attempted and any involved paths.
15
16## Error Messages
17
18Using [`std::fs`][std::fs], if this code fails:
19
20```rust
21let file = File::open("does not exist.txt")?;
22```
23
24The error message that Rust gives you isn't very useful:
25
26```txt
27The system cannot find the file specified. (os error 2)
28```
29
30...but if we use fs-err instead, our error contains more actionable information:
31
32```txt
33failed to open file `does not exist.txt`
34    caused by: The system cannot find the file specified. (os error 2)
35```
36
37## Usage
38
39fs-err's API is the same as [`std::fs`][std::fs], so migrating code to use it is easy.
40
41```rust
42// use std::fs;
43use fs_err as fs;
44
45let contents = fs::read_to_string("foo.txt")?;
46
47println!("Read foo.txt: {}", contents);
48
49```
50
51fs-err uses [`std::io::Error`][std::io::Error] for all errors. This helps fs-err
52compose well with traits from the standard library like
53[`std::io::Read`][std::io::Read] and crates that use them like
54[`serde_json`][serde_json]:
55
56```rust
57use fs_err::File;
58
59let file = File::open("my-config.json")?;
60
61// If an I/O error occurs inside serde_json, the error will include a file path
62// as well as what operation was being performed.
63let decoded: Vec<String> = serde_json::from_reader(file)?;
64
65println!("Program config: {:?}", decoded);
66
67```
68
69[std::fs]: https://doc.rust-lang.org/stable/std/fs/
70[std::io::Error]: https://doc.rust-lang.org/stable/std/io/struct.Error.html
71[std::io::Read]: https://doc.rust-lang.org/stable/std/io/trait.Read.html
72[serde_json]: https://crates.io/crates/serde_json
73
74## Minimum Supported Rust Version
75
76The oldest rust version this crate is tested on is **1.40**.
77
78This crate will generally be conservative with rust version updates. It uses the [`autocfg`](https://crates.io/crates/autocfg) crate to allow wrapping new APIs without incrementing the MSRV.
79
80If the `tokio` feature is enabled, this crate will inherit the MSRV of the selected [`tokio`](https://crates.io/crates/tokio) version.
81
82## License
83
84Licensed under either of
85
86* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
87* MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)
88
89at your option.
90
91### Contribution
92
93Unless you explicitly state otherwise, any contribution intentionally
94submitted for inclusion in the work by you, as defined in the Apache-2.0
95license, shall be dual licensed as above, without any additional terms or
96conditions.
97