Source code
Revision control
Copy as Markdown
Other Tools
<!--↩
↩
Edit `src/lib.rs` and use `cargo readme > README.md` to update it.↩
-->↩
↩
# fs-err↩
↩
[](https://github.com/andrewhickman/fs-err/actions?query=workflow%3ACI)↩
↩
fs-err is a drop-in replacement for [`std::fs`][std::fs] that provides more↩
helpful messages on errors. Extra information includes which operations was↩
attempted and any involved paths.↩
↩
## Error Messages↩
↩
Using [`std::fs`][std::fs], if this code fails:↩
↩
```rust↩
let file = File::open("does not exist.txt")?;↩
```↩
↩
The error message that Rust gives you isn't very useful:↩
↩
```txt↩
The system cannot find the file specified. (os error 2)↩
```↩
↩
...but if we use fs-err instead, our error contains more actionable information:↩
↩
```txt↩
failed to open file `does not exist.txt`↩
caused by: The system cannot find the file specified. (os error 2)↩
```↩
↩
## Usage↩
↩
fs-err's API is the same as [`std::fs`][std::fs], so migrating code to use it is easy.↩
↩
```rust↩
// use std::fs;↩
use fs_err as fs;↩
↩
let contents = fs::read_to_string("foo.txt")?;↩
↩
println!("Read foo.txt: {}", contents);↩
↩
```↩
↩
fs-err uses [`std::io::Error`][std::io::Error] for all errors. This helps fs-err↩
compose well with traits from the standard library like↩
[`std::io::Read`][std::io::Read] and crates that use them like↩
[`serde_json`][serde_json]:↩
↩
```rust↩
use fs_err::File;↩
↩
let file = File::open("my-config.json")?;↩
↩
// If an I/O error occurs inside serde_json, the error will include a file path↩
// as well as what operation was being performed.↩
let decoded: Vec<String> = serde_json::from_reader(file)?;↩
↩
println!("Program config: {:?}", decoded);↩
↩
```↩
↩
↩
## License↩
↩
Licensed under either of↩
↩
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)↩
↩
at your option.↩
↩
### Contribution↩
↩
Unless you explicitly state otherwise, any contribution intentionally↩
submitted for inclusion in the work by you, as defined in the Apache-2.0↩
license, shall be dual licensed as above, without any additional terms or↩
conditions.↩