601ec251f8
This patch adds support for multiple rustdoc output formats to the test suite. This is a preparation for adding support for rustdoc’s JSON output.
135 lines
5.1 KiB
Plaintext
135 lines
5.1 KiB
Plaintext
---
|
||
source: tests/output.rs
|
||
expression: "get_stdout(path, &[\"anyhow\"])"
|
||
---
|
||
anyhow Module anyhow rusty-man
|
||
|
||
DESCRIPTION
|
||
[[github]][1] [[crates-io]][2] [[docs-rs]][3]
|
||
|
||
This library provides `anyhow::Error`, a trait object based error type for easy idiomatic
|
||
error handling in Rust applications.
|
||
|
||
|
||
# Details
|
||
|
||
* Use `Result<T, anyhow::Error>`, or equivalently `anyhow::Result<T>`, as the return type of
|
||
any fallible function.
|
||
|
||
Within the function, use `?` to easily propagate any error that implements the
|
||
`std::error::Error` trait.
|
||
|
||
use anyhow::Result;
|
||
fn get_cluster_info() -> Result<ClusterMap> {
|
||
let config = std::fs::read_to_string("cluster.json")?;
|
||
let map: ClusterMap = serde_json::from_str(&config)?;
|
||
Ok(map)
|
||
}
|
||
* Attach context to help the person troubleshooting the error understand where things went
|
||
wrong. A low-level error like “No such file or directory” can be annoying to debug without
|
||
more context about what higher level step the application was in the middle of.
|
||
|
||
use anyhow::{Context, Result};
|
||
fn main() -> Result<()> {
|
||
...
|
||
it.detach().context("Failed to detach the important thing")?;
|
||
let content = std::fs::read(path)
|
||
.with_context(|| format!("Failed to read instrs from {}", path))?;
|
||
...
|
||
}
|
||
`Error: Failed to read instrs from ./path/to/instrs.json
|
||
Caused by:
|
||
No such file or directory (os error 2)
|
||
`
|
||
* Downcasting is supported and can be by value, by shared reference, or by mutable reference
|
||
as needed.
|
||
|
||
// If the error was caused by redaction, then return a
|
||
// tombstone instead of the content.
|
||
match root_cause.downcast_ref::<DataStoreError>() {
|
||
Some(DataStoreError::Censored(_)) => Ok(Poll::Ready(REDACTED_CONTENT)),
|
||
None => Err(error),
|
||
}
|
||
* If using the nightly channel, a backtrace is captured and printed with the error if the
|
||
underlying error type does not already provide its own. In order to see backtraces, they
|
||
must be enabled through the environment variables described in [`std::backtrace`][1]:
|
||
|
||
* If you want panics and errors to both have backtraces, set `RUST_BACKTRACE=1`;
|
||
* If you want only errors to have backtraces, set `RUST_LIB_BACKTRACE=1`;
|
||
* If you want only panics to have backtraces, set `RUST_BACKTRACE=1` and
|
||
`RUST_LIB_BACKTRACE=0`.
|
||
|
||
The tracking issue for this feature is [rust-lang/rust#53487][2].
|
||
|
||
[1] https://doc.rust-lang.org/std/backtrace/index.html#environment-variables
|
||
[2] https://github.com/rust-lang/rust/issues/53487
|
||
* Anyhow works with any error type that has an impl of `std::error::Error`, including ones
|
||
defined in your crate. We do not bundle a `derive(Error)` macro but you can write the impls
|
||
yourself or use a standalone macro like [thiserror][1].
|
||
|
||
use thiserror::Error;
|
||
#[derive(Error, Debug)]
|
||
pub enum FormatError {
|
||
#[error("Invalid header (expected {expected:?}, got {found:?})")]
|
||
InvalidHeader {
|
||
expected: String,
|
||
found: String,
|
||
},
|
||
#[error("Missing attribute: {0}")]
|
||
MissingAttribute(String),
|
||
}
|
||
|
||
[1] https://github.com/dtolnay/thiserror
|
||
* One-off error messages can be constructed using the `anyhow!` macro, which supports string
|
||
interpolation and produces an `anyhow::Error`.
|
||
|
||
return Err(anyhow!("Missing attribute: {}", missing));
|
||
|
||
|
||
|
||
# No-std support
|
||
|
||
In no_std mode, the same API is almost all available and works the same way. To depend on
|
||
Anyhow in no_std mode, disable our default enabled “std” feature in Cargo.toml. A global
|
||
allocator is required.
|
||
|
||
`[dependencies]
|
||
anyhow = { version = "1.0", default-features = false }
|
||
`
|
||
|
||
Since the `?`-based error conversions would normally rely on the `std::error::Error` trait
|
||
which is only available through std, no_std mode will require an explicit
|
||
`.map_err(Error::msg)` when working with a non-Anyhow error type inside a function that
|
||
returns Anyhow’s error type.
|
||
|
||
[1] https://github.com/dtolnay/anyhow
|
||
[2] https://crates.io/crates/anyhow
|
||
[3] https://docs.rs/anyhow
|
||
|
||
MACROS
|
||
anyhow
|
||
Construct an ad-hoc error from a string.
|
||
|
||
bail
|
||
Return early with an error.
|
||
|
||
ensure
|
||
Return early with an error if a condition is not satisfied.
|
||
|
||
STRUCTS
|
||
Chain
|
||
Iterator of a chain of source errors.
|
||
|
||
Error
|
||
The `Error` type, a wrapper around a dynamic error type.
|
||
|
||
TRAITS
|
||
Context
|
||
Provides the `context` method for `Result`.
|
||
|
||
TYPEDEFS
|
||
Result
|
||
`Result<T, Error>`
|
||
|
||
|