Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/andrewhickman/fs-err
A simple wrapper around filesystem operations to provide more helpful error messages.
https://github.com/andrewhickman/fs-err
Last synced: about 8 hours ago
JSON representation
A simple wrapper around filesystem operations to provide more helpful error messages.
- Host: GitHub
- URL: https://github.com/andrewhickman/fs-err
- Owner: andrewhickman
- License: apache-2.0
- Created: 2020-02-02T22:11:23.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2024-01-11T22:24:22.000Z (10 months ago)
- Last Synced: 2024-04-25T00:03:04.132Z (7 months ago)
- Language: Rust
- Size: 95.7 KB
- Stars: 122
- Watchers: 7
- Forks: 13
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# 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
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`: 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 = serde_json::from_reader(file)?;
println!("Program config: {:?}", decoded);
```
## Feature flags
* `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,
this also suppresses printing its message in their `Display` implementation, so make sure that you are printing the full error chain.
## Minimum Supported Rust Version
The oldest rust version this crate is tested on is **1.40**.
This 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.
If the `tokio` feature is enabled, this crate will inherit the MSRV of the selected [`tokio`](https://crates.io/crates/tokio) version.
[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.