6dc75f0c5d
This patch adds tests for Rust 1.54.0, 1.55.0 and 1.56.0. To make the tests pass, we have to take care of some changes like more details elements and changed heading levels. To make it easier to generate the tests for new Rust versions, we also add two bash scripts that take care of that.
121 lines
4.2 KiB
Plaintext
121 lines
4.2 KiB
Plaintext
---
|
||
source: tests/output.rs
|
||
expression: "get_stdout(path, &[\"anyhow::Context\"])"
|
||
|
||
---
|
||
anyhow Trait anyhow::Context rusty-man
|
||
|
||
SYNOPSIS
|
||
pub trait Context<T, E>: Sealed {
|
||
fn context<C>(self, context: C) -> Result<T, Error>
|
||
where
|
||
C: Display + Send + Sync + 'static;
|
||
fn with_context<C, F>(self, f: F) -> Result<T, Error>
|
||
where
|
||
C: Display + Send + Sync + 'static,
|
||
F: FnOnce() -> C;
|
||
}
|
||
|
||
DESCRIPTION
|
||
Provides the `context` method for `Result`.
|
||
|
||
This trait is sealed and cannot be implemented for types outside of `anyhow`.
|
||
|
||
|
||
# Example
|
||
|
||
`use anyhow::{Context, Result};
|
||
use std::fs;
|
||
use std::path::PathBuf;
|
||
pub struct ImportantThing {
|
||
path: PathBuf,
|
||
}
|
||
impl ImportantThing {
|
||
pub fn detach(&mut self) -> Result<()> {...}
|
||
}
|
||
pub fn do_it(mut it: ImportantThing) -> Result<Vec<u8>> {
|
||
it.detach().context("Failed to detach the important thing")?;
|
||
let path = &it.path;
|
||
let content = fs::read(path)
|
||
.with_context(|| format!("Failed to read instrs from {}", path.display()))?;
|
||
Ok(content)
|
||
}`
|
||
|
||
When printed, the outermost context would be printed first and the lower level underlying
|
||
causes would be enumerated below.
|
||
|
||
`Error: Failed to read instrs from ./path/to/instrs.json
|
||
Caused by:
|
||
No such file or directory (os error 2)`
|
||
|
||
|
||
|
||
# Effect on downcasting
|
||
|
||
After attaching context of type `C` onto an error of type `E`, the resulting `anyhow::Error`
|
||
may be downcast to `C` **or** to `E`.
|
||
|
||
That is, in codebases that rely on downcasting, Anyhow’s context supports both of the
|
||
following use cases:
|
||
|
||
* **Attaching context whose type is insignificant onto errors whose type is used in
|
||
downcasts.**
|
||
|
||
In other error libraries whose context is not designed this way, it can be risky to
|
||
introduce context to existing code because new context might break existing working
|
||
downcasts. In Anyhow, any downcast that worked before adding context will continue to work
|
||
after you add a context, so you should freely add human-readable context to errors wherever
|
||
it would be helpful.
|
||
|
||
`use anyhow::{Context, Result};
|
||
fn do_it() -> Result<()> {
|
||
helper().context("Failed to complete the work")?;
|
||
...
|
||
}
|
||
fn main() {
|
||
let err = do_it().unwrap_err();
|
||
if let Some(e) = err.downcast_ref::<SuspiciousError>() {
|
||
// If helper() returned SuspiciousError, this downcast will
|
||
// correctly succeed even with the context in between.
|
||
}
|
||
}`
|
||
* **Attaching context whose type is used in downcasts onto errors whose type is
|
||
insignificant.**
|
||
|
||
Some codebases prefer to use machine-readable context to categorize lower level errors in a
|
||
way that will be actionable to higher levels of the application.
|
||
|
||
`use anyhow::{Context, Result};
|
||
fn do_it() -> Result<()> {
|
||
helper().context(HelperFailed)?;
|
||
...
|
||
}
|
||
fn main() {
|
||
let err = do_it().unwrap_err();
|
||
if let Some(e) = err.downcast_ref::<HelperFailed>() {
|
||
// If helper failed, this downcast will succeed because
|
||
// HelperFailed is the context that has been attached to
|
||
// that error.
|
||
}
|
||
}`
|
||
|
||
METHODS
|
||
Required Methods
|
||
context
|
||
fn context<C>(self, context: C) -> Result<T, Error>
|
||
where
|
||
C: Display + Send + Sync + 'static,
|
||
|
||
Wrap the error value with additional context.
|
||
|
||
with_context
|
||
fn with_context<C, F>(self, f: F) -> Result<T, Error>
|
||
where
|
||
C: Display + Send + Sync + 'static,
|
||
F: FnOnce() -> C,
|
||
|
||
Wrap the error value with additional context that is evaluated lazily only once an error
|
||
does occur.
|
||
|
||
|