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[](https://crates.io/crates/fs-err) 10[](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`: The system cannot find the file specified. (os error 2) 34``` 35 36## Usage 37 38fs-err's API is the same as [`std::fs`][std::fs], so migrating code to use it is easy. 39 40```rust 41// use std::fs; 42use fs_err as fs; 43 44let contents = fs::read_to_string("foo.txt")?; 45 46println!("Read foo.txt: {}", contents); 47 48``` 49 50fs-err uses [`std::io::Error`][std::io::Error] for all errors. This helps fs-err 51compose well with traits from the standard library like 52[`std::io::Read`][std::io::Read] and crates that use them like 53[`serde_json`][serde_json]: 54 55```rust 56use fs_err::File; 57 58let file = File::open("my-config.json")?; 59 60// If an I/O error occurs inside serde_json, the error will include a file path 61// as well as what operation was being performed. 62let decoded: Vec<String> = serde_json::from_reader(file)?; 63 64println!("Program config: {:?}", decoded); 65 66``` 67 68## Feature flags 69 70* `expose_original_error`: when enabled, the [`Error::source()`](https://doc.rust-lang.org/stable/std/error/trait.Error.html#method.source) method of errors returned by this crate return the original `io::Error`. To avoid duplication in error messages, 71 this also suppresses printing its message in their `Display` implementation, so make sure that you are printing the full error chain. 72 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[std::fs]: https://doc.rust-lang.org/stable/std/fs/ 83[std::io::Error]: https://doc.rust-lang.org/stable/std/io/struct.Error.html 84[std::io::Read]: https://doc.rust-lang.org/stable/std/io/trait.Read.html 85[serde_json]: https://crates.io/crates/serde_json 86 87## License 88 89Licensed under either of 90 91* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0) 92* MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT) 93 94at your option. 95 96### Contribution 97 98Unless you explicitly state otherwise, any contribution intentionally 99submitted for inclusion in the work by you, as defined in the Apache-2.0 100license, shall be dual licensed as above, without any additional terms or 101conditions. 102
){kind=link}
){kind=link}