diff options
Diffstat (limited to 'vendor/fs-err/README.md')
| -rw-r--r-- | vendor/fs-err/README.md | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/vendor/fs-err/README.md b/vendor/fs-err/README.md new file mode 100644 index 000000000..70bf1fa44 --- /dev/null +++ b/vendor/fs-err/README.md @@ -0,0 +1,88 @@ +<!--
+ This readme is created with https://github.com/livioribeiro/cargo-readme
+
+ Edit `src/lib.rs` and use `cargo readme > README.md` to update it.
+-->
+
+# fs-err
+
+[](https://crates.io/crates/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
+attmpted 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);
+
+```
+
+[std::fs]: https://doc.rust-lang.org/stable/std/fs/
+[std::io::Error]: https://doc.rust-lang.org/stable/std/io/struct.Error.html
+[std::io::Read]: https://doc.rust-lang.org/stable/std/io/trait.Read.html
+[serde_json]: https://crates.io/crates/serde_json
+
+## License
+
+Licensed under either of
+
+* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
+* MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)
+
+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.
|