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.
357 lines
11 KiB
Plaintext
357 lines
11 KiB
Plaintext
---
|
||
source: tests/output.rs
|
||
expression: "get_stdout(path, &[\"anyhow::Error\"])"
|
||
---
|
||
anyhow Struct anyhow::Error rusty-man
|
||
|
||
SYNOPSIS
|
||
pub struct Error { /* fields omitted */ }
|
||
|
||
DESCRIPTION
|
||
The `Error` type, a wrapper around a dynamic error type.
|
||
|
||
`Error` works a lot like `Box<dyn std::error::Error>`, but with these differences:
|
||
|
||
* `Error` requires that the error is `Send`, `Sync`, and `'static`.
|
||
* `Error` guarantees that a backtrace is available, even if the underlying error type does not
|
||
provide one.
|
||
* `Error` is represented as a narrow pointer — exactly one word in size instead of two.
|
||
|
||
|
||
|
||
# Display representations
|
||
|
||
When you print an error object using "{}" or to_string(), only the outermost underlying error
|
||
or context is printed, not any of the lower level causes. This is exactly as if you had called
|
||
the Display impl of the error from which you constructed your anyhow::Error.
|
||
|
||
`Failed to read instrs from ./path/to/instrs.json
|
||
`
|
||
|
||
To print causes as well using anyhow's default formatting of causes, use the alternate
|
||
selector "{:#}".
|
||
|
||
`Failed to read instrs from ./path/to/instrs.json: No such file or directory (os error 2)
|
||
`
|
||
|
||
The Debug format "{:?}" includes your backtrace if one was captured. Note that this is the
|
||
representation you get by default if you return an error from `fn main` instead of printing it
|
||
explicitly yourself.
|
||
|
||
`Error: Failed to read instrs from ./path/to/instrs.json
|
||
Caused by:
|
||
No such file or directory (os error 2)
|
||
`
|
||
|
||
and if there is a backtrace available:
|
||
|
||
`Error: Failed to read instrs from ./path/to/instrs.json
|
||
Caused by:
|
||
No such file or directory (os error 2)
|
||
Stack backtrace:
|
||
0: <E as anyhow::context::ext::StdError>::ext_context
|
||
at /git/anyhow/src/backtrace.rs:26
|
||
1: core::result::Result<T,E>::map_err
|
||
at /git/rustc/src/libcore/result.rs:596
|
||
2: anyhow::context::<impl anyhow::Context<T,E> for core::result::Result<T,E>>::with_context
|
||
at /git/anyhow/src/context.rs:58
|
||
3: testing::main
|
||
at src/main.rs:5
|
||
4: std::rt::lang_start
|
||
at /git/rustc/src/libstd/rt.rs:61
|
||
5: main
|
||
6: __libc_start_main
|
||
7: _start
|
||
`
|
||
|
||
To see a conventional struct-style Debug representation, use "{:#?}".
|
||
|
||
`Error {
|
||
context: "Failed to read instrs from ./path/to/instrs.json",
|
||
source: Os {
|
||
code: 2,
|
||
kind: NotFound,
|
||
message: "No such file or directory",
|
||
},
|
||
}
|
||
`
|
||
|
||
If none of the built-in representations are appropriate and you would prefer to render the
|
||
error and its cause chain yourself, it can be done something like this:
|
||
|
||
use anyhow::{Context, Result};
|
||
fn main() {
|
||
if let Err(err) = try_main() {
|
||
eprintln!("ERROR: {}", err);
|
||
err.chain().skip(1).for_each(|cause| eprintln!("because: {}", cause));
|
||
std::process::exit(1);
|
||
}
|
||
}
|
||
fn try_main() -> Result<()> {
|
||
...
|
||
}
|
||
|
||
METHODS
|
||
impl Error
|
||
new
|
||
pub fn new<E>(error: E) -> Self
|
||
where
|
||
E: StdError + Send + Sync + 'static,
|
||
|
||
Create a new error object from any error type.
|
||
|
||
The error type must be threadsafe and `'static`, so that the `Error` will be as well.
|
||
|
||
If the error type does not provide a backtrace, a backtrace will be created here to
|
||
ensure that a backtrace exists.
|
||
|
||
msg
|
||
pub fn msg<M>(message: M) -> Self
|
||
where
|
||
M: Display + Debug + Send + Sync + 'static,
|
||
|
||
Create a new error object from a printable error message.
|
||
|
||
If the argument implements std::error::Error, prefer `Error::new` instead which
|
||
preserves the underlying error's cause chain and backtrace. If the argument may or may
|
||
not implement std::error::Error now or in the future, use `anyhow!(err)` which handles
|
||
either way correctly.
|
||
|
||
`Error::msg("...")` is equivalent to `anyhow!("...")` but occasionally convenient in
|
||
places where a function is preferable over a macro, such as iterator or stream
|
||
combinators:
|
||
|
||
use anyhow::{Error, Result};
|
||
use futures::stream::{Stream, StreamExt, TryStreamExt};
|
||
async fn demo<S>(stream: S) -> Result<Vec<Output>>
|
||
where
|
||
S: Stream<Item = Input>,
|
||
{
|
||
stream
|
||
.then(ffi::do_some_work) // returns Result<Output, &str>
|
||
.map_err(Error::msg)
|
||
.try_collect()
|
||
.await
|
||
}
|
||
|
||
context
|
||
pub fn context<C>(self, context: C) -> Self
|
||
where
|
||
C: Display + Send + Sync + 'static,
|
||
|
||
Wrap the error value with additional context.
|
||
|
||
For attaching context to a `Result` as it is propagated, the [`Context`][crate::Context]
|
||
extension trait may be more convenient than this function.
|
||
|
||
The primary reason to use `error.context(...)` instead of `result.context(...)` via the
|
||
`Context` trait would be if the context needs to depend on some data held by the
|
||
underlying error:
|
||
|
||
use anyhow::Result;
|
||
use std::fs::File;
|
||
use std::path::Path;
|
||
struct ParseError {
|
||
line: usize,
|
||
column: usize,
|
||
}
|
||
fn parse_impl(file: File) -> Result<T, ParseError> {
|
||
...
|
||
}
|
||
pub fn parse(path: impl AsRef<Path>) -> Result<T> {
|
||
let file = File::open(&path)?;
|
||
parse_impl(file).map_err(|error| {
|
||
let context = format!(
|
||
"only the first {} lines of {} are valid",
|
||
error.line, path.as_ref().display(),
|
||
);
|
||
anyhow::Error::new(error).context(context)
|
||
})
|
||
}
|
||
|
||
chain
|
||
pub fn chain(&self) -> Chain
|
||
|
||
An iterator of the chain of source errors contained by this Error.
|
||
|
||
This iterator will visit every error in the cause chain of this error object, beginning
|
||
with the error that this error object was created from.
|
||
|
||
# Example
|
||
|
||
use anyhow::Error;
|
||
use std::io;
|
||
pub fn underlying_io_error_kind(error: &Error) -> Option<io::ErrorKind> {
|
||
for cause in error.chain() {
|
||
if let Some(io_error) = cause.downcast_ref::<io::Error>() {
|
||
return Some(io_error.kind());
|
||
}
|
||
}
|
||
None
|
||
}
|
||
|
||
root_cause
|
||
pub fn root_cause(&self) -> &(dyn StdError + 'static)
|
||
|
||
The lowest level cause of this error — this error's cause's cause's cause etc.
|
||
|
||
The root cause is the last error in the iterator produced by [`chain()`][Error::chain].
|
||
|
||
is
|
||
pub fn is<E>(&self) -> bool
|
||
where
|
||
E: Display + Debug + Send + Sync + 'static,
|
||
|
||
Returns true if `E` is the type held by this error object.
|
||
|
||
For errors with context, this method returns true if `E` matches the type of the context
|
||
`C` **or** the type of the error on which the context has been attached. For details
|
||
about the interaction between context and downcasting, see here.
|
||
|
||
downcast
|
||
pub fn downcast<E>(self) -> Result<E, Self>
|
||
where
|
||
E: Display + Debug + Send + Sync + 'static,
|
||
|
||
Attempt to downcast the error object to a concrete type.
|
||
|
||
downcast_ref
|
||
pub fn downcast_ref<E>(&self) -> Option<&E>
|
||
where
|
||
E: Display + Debug + Send + Sync + 'static,
|
||
|
||
Downcast this error object by reference.
|
||
|
||
# Example
|
||
|
||
// 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),
|
||
}
|
||
|
||
downcast_mut
|
||
pub fn downcast_mut<E>(&mut self) -> Option<&mut E>
|
||
where
|
||
E: Display + Debug + Send + Sync + 'static,
|
||
|
||
Downcast this error object by mutable reference.
|
||
|
||
Methods from Deref<Target = dyn StdError + Send + Sync + 'static>
|
||
is
|
||
pub fn is<T>(&self) -> bool
|
||
where
|
||
T: 'static + Error,
|
||
|
||
Returns `true` if the boxed type is the same as `T`
|
||
|
||
downcast_ref
|
||
pub fn downcast_ref<T>(&self) -> Option<&T>
|
||
where
|
||
T: 'static + Error,
|
||
|
||
Returns some reference to the boxed value if it is of type `T`, or `None` if it isn't.
|
||
|
||
downcast_mut
|
||
pub fn downcast_mut<T>(&mut self) -> Option<&mut T>
|
||
where
|
||
T: 'static + Error,
|
||
|
||
Returns some mutable reference to the boxed value if it is of type `T`, or `None` if it
|
||
isn't.
|
||
|
||
IMPLEMENTATIONS
|
||
Trait Implementations
|
||
AsRef
|
||
impl AsRef<dyn Error + 'static + Sync + Send> for Error
|
||
|
||
AsRef
|
||
impl AsRef<dyn Error + 'static> for Error
|
||
|
||
Debug
|
||
impl Debug for Error
|
||
|
||
Deref
|
||
impl Deref for Error
|
||
|
||
DerefMut
|
||
impl DerefMut for Error
|
||
|
||
Display
|
||
impl Display for Error
|
||
|
||
Drop
|
||
impl Drop for Error
|
||
|
||
From
|
||
impl From<Error> for Box<dyn StdError + 'static>
|
||
|
||
From
|
||
impl From<Error> for Box<dyn StdError + Send + Sync + 'static>
|
||
|
||
From
|
||
impl<E> From<E> for Error
|
||
where
|
||
E: StdError + Send + Sync + 'static,
|
||
|
||
Auto Trait Implementations
|
||
RefUnwindSafe
|
||
impl RefUnwindSafe for Error
|
||
|
||
Send
|
||
impl Send for Error
|
||
|
||
Sync
|
||
impl Sync for Error
|
||
|
||
Unpin
|
||
impl Unpin for Error
|
||
|
||
UnwindSafe
|
||
impl UnwindSafe for Error
|
||
|
||
Blanket Implementations
|
||
Any
|
||
impl<T> Any for T
|
||
where
|
||
T: 'static + ?Sized,
|
||
|
||
Borrow
|
||
impl<T> Borrow<T> for T
|
||
where
|
||
T: ?Sized,
|
||
|
||
BorrowMut
|
||
impl<T> BorrowMut<T> for T
|
||
where
|
||
T: ?Sized,
|
||
|
||
From
|
||
impl<T> From<!> for T
|
||
|
||
From
|
||
impl<T> From<T> for T
|
||
|
||
Into
|
||
impl<T, U> Into<U> for T
|
||
where
|
||
U: From<T>,
|
||
|
||
ToString
|
||
impl<T> ToString for T
|
||
where
|
||
T: Display + ?Sized,
|
||
|
||
TryFrom
|
||
impl<T, U> TryFrom<U> for T
|
||
where
|
||
U: Into<T>,
|
||
|
||
TryInto
|
||
impl<T, U> TryInto<U> for T
|
||
where
|
||
U: TryFrom<T>,
|
||
|
||
|