Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/yoshuawuyts/context-attribute
Set the error context using doc comments
https://github.com/yoshuawuyts/context-attribute
Last synced: 7 days ago
JSON representation
Set the error context using doc comments
- Host: GitHub
- URL: https://github.com/yoshuawuyts/context-attribute
- Owner: yoshuawuyts
- License: apache-2.0
- Created: 2019-03-23T23:49:38.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2019-12-14T11:24:35.000Z (almost 5 years ago)
- Last Synced: 2024-10-10T14:59:41.769Z (about 1 month ago)
- Language: Rust
- Homepage: https://docs.rs/context-attribute
- Size: 19.5 KB
- Stars: 53
- Watchers: 5
- Forks: 4
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE-APACHE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# context-attribute
[![crates.io version][1]][2] [![build status][3]][4]
[![downloads][5]][6] [![docs.rs docs][7]][8]
Set the error [`context`] using doc comments.
This is useful because instead of writing manual error messages to provide context to an error, it
automatically derives it from doc comments. This works especially well for async contexts, where
stack traces may not be persisted past yield points and thread boundaries. But contexts do.
[`context`]: https://docs.rs/failure/0.1.5/failure/trait.ResultExt.html#tymethod.context
- [Documentation][8]
- [Crates.io][2]
- [Releases][releases]
## Examples
```rust
use context_attribute::context;
use failure::{ensure, ResultExt};
/// Square a number if it's less than 10.
#[context]
fn square(num: usize) -> Result {
ensure!(num < 10, "Number was too large");
Ok(num * num)
}
fn main() -> Result<(), failure::Error> {
let args = std::env::args();
ensure!(args.len() == 2, "usage: square ");
let input = args.skip(1).next().unwrap().parse()?;
println!("result is {}", square(input)?);
Ok(())
}
```
```txt
$ cargo run --example square 12
Error: ErrorMessage { msg: "Number was too large" }
Square a number if it's less than 10.
```
## Installation
```sh
$ cargo add context-attribute
```
## FAQ
### What does the code expand to?
Take this piece of code:
```rust
/// Read address.txt from disk
#[context]
pub fn read_file_2() -> Result {
Ok(std::fs::read_to_string("address.txt")?.trim().to_string())
}
```
Any error that comes from it is tagged with the message `"Read address.txt from disk"`. To write it
by hand we'd have to do:
```rust
/// Read address.txt from disk
pub fn read_file_1() -> Result {
let res = std::fs::read_to_string("address.txt")
.context("Read address.txt from disk")?
.trim()
.to_string();
Ok(res)
}
```
## Safety
This crate uses ``#![deny(unsafe_code)]`` to ensure everything is implemented in
100% Safe Rust.
## Contributing
Want to join us? Check out our ["Contributing" guide][contributing] and take a
look at some of these issues:
- [Issues labeled "good first issue"][good-first-issue]
- [Issues labeled "help wanted"][help-wanted]
## License
[MIT](./LICENSE-MIT) OR [Apache-2.0](./LICENSE-APACHE)
[1]: https://img.shields.io/crates/v/context-attribute.svg?style=flat-square
[2]: https://crates.io/crates/context-attribute
[3]: https://img.shields.io/travis/yoshuawuyts/context-attribute/master.svg?style=flat-square
[4]: https://travis-ci.org/yoshuawuyts/context-attribute
[5]: https://img.shields.io/crates/d/context-attribute.svg?style=flat-square
[6]: https://crates.io/crates/context-attribute
[7]: https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square
[8]: https://docs.rs/context-attribute
[releases]: https://github.com/yoshuawuyts/context-attribute/releases
[contributing]: https://github.com/yoshuawuyts/context-attribute/blob/master.github/CONTRIBUTING.md
[good-first-issue]: https://github.com/yoshuawuyts/context-attribute/labels/good%20first%20issue
[help-wanted]: https://github.com/yoshuawuyts/context-attribute/labels/help%20wanted