628377c83b
This patch refactors the test suite: - Instead of always generating the documentation with the available rustdoc version, we now store generated documentation for all supported rustdoc versions in the test/html directory. - Instead of using one snapshot per test case, we now use one snapshot per test case and rustdoc version.
121 lines
4.2 KiB
Plaintext
121 lines
4.2 KiB
Plaintext
---
|
||
source: tests/output.rs
|
||
expression: "get_stdout(&[item])"
|
||
---
|
||
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.
|
||
|
||
|