Expand description
An error reporter that prints an error and its sources.
Report also exposes configuration options for formatting the error chain, either entirely on a single line, or in multi-line format with each cause in the error chain on a new line.
Report
only requires that the wrapped error implement Error
. It doesn’t require that the
wrapped error be Send
, Sync
, or 'static
.
Examples
#![feature(error_reporter)]
use std::error::{Error, Report};
use std::fmt;
#[derive(Debug)]
struct SuperError {
source: SuperErrorSideKick,
}
impl fmt::Display for SuperError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "SuperError is here!")
}
}
impl Error for SuperError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
Some(&self.source)
}
}
#[derive(Debug)]
struct SuperErrorSideKick;
impl fmt::Display for SuperErrorSideKick {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "SuperErrorSideKick is here!")
}
}
impl Error for SuperErrorSideKick {}
fn get_super_error() -> Result<(), SuperError> {
Err(SuperError { source: SuperErrorSideKick })
}
fn main() {
match get_super_error() {
Err(e) => println!("Error: {}", Report::new(e)),
_ => println!("No error"),
}
}
RunThis example produces the following output:
Error: SuperError is here!: SuperErrorSideKick is here!
Output consistency
Report prints the same output via Display
and Debug
, so it works well with
Result::unwrap
/Result::expect
which print their Err
variant via Debug
:
#![feature(error_reporter)]
use std::error::Report;
get_super_error().map_err(Report::new).unwrap();
RunThis example produces the following output:
thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: SuperError is here!: SuperErrorSideKick is here!', src/error.rs:34:40
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
Return from main
Report
also implements From
for all types that implement Error
; this when combined with
the Debug
output means Report
is an ideal starting place for formatting errors returned
from main
.
#![feature(error_reporter)]
use std::error::Report;
fn main() -> Result<(), Report> {
get_super_error()?;
Ok(())
}
RunThis example produces the following output:
Error: SuperError is here!: SuperErrorSideKick is here!
Note: Report
s constructed via ?
and From
will be configured to use the single line
output format. If you want to make sure your Report
s are pretty printed and include backtrace
you will need to manually convert and enable those flags.
#![feature(error_reporter)]
use std::error::Report;
fn main() -> Result<(), Report> {
get_super_error()
.map_err(Report::from)
.map_err(|r| r.pretty(true).show_backtrace(true))?;
Ok(())
}
RunThis example produces the following output:
Error: SuperError is here!
Caused by:
SuperErrorSideKick is here!
Implementations
sourceimpl<E> Report<E>
impl<E> Report<E>
sourcepub fn pretty(self, pretty: bool) -> Self
pub fn pretty(self, pretty: bool) -> Self
Enable pretty-printing the report across multiple lines.
Examples
#![feature(error_reporter)]
use std::error::Report;
let error = SuperError { source: SuperErrorSideKick };
let report = Report::new(error).pretty(true);
eprintln!("Error: {report:?}");
RunThis example produces the following output:
Error: SuperError is here!
Caused by:
SuperErrorSideKick is here!
When there are multiple source errors the causes will be numbered in order of iteration starting from the outermost error.
#![feature(error_reporter)]
use std::error::Report;
let source = SuperErrorSideKickSideKick;
let source = SuperErrorSideKick { source };
let error = SuperError { source };
let report = Report::new(error).pretty(true);
eprintln!("Error: {report:?}");
RunThis example produces the following output:
Error: SuperError is here!
Caused by:
0: SuperErrorSideKick is here!
1: SuperErrorSideKickSideKick is here!
sourcepub fn show_backtrace(self, show_backtrace: bool) -> Self
pub fn show_backtrace(self, show_backtrace: bool) -> Self
Display backtrace if available when using pretty output format.
Examples
Note: Report will search for the first Backtrace
it can find starting from the
outermost error. In this example it will display the backtrace from the second error in the
chain, SuperErrorSideKick
.
#![feature(error_reporter)]
#![feature(backtrace)]
use std::error::Report;
use std::backtrace::Backtrace;
#[derive(Debug)]
struct SuperErrorSideKick {
backtrace: Backtrace,
}
impl SuperErrorSideKick {
fn new() -> SuperErrorSideKick {
SuperErrorSideKick { backtrace: Backtrace::force_capture() }
}
}
impl Error for SuperErrorSideKick {
fn backtrace(&self) -> Option<&Backtrace> {
Some(&self.backtrace)
}
}
// The rest of the example is unchanged ...
let source = SuperErrorSideKick::new();
let error = SuperError { source };
let report = Report::new(error).pretty(true).show_backtrace(true);
eprintln!("Error: {report:?}");
RunThis example produces something similar to the following output:
Error: SuperError is here!
Caused by:
SuperErrorSideKick is here!
Stack backtrace:
0: rust_out::main::_doctest_main_src_error_rs_1158_0::SuperErrorSideKick::new
1: rust_out::main::_doctest_main_src_error_rs_1158_0
2: rust_out::main
3: core::ops::function::FnOnce::call_once
4: std::sys_common::backtrace::__rust_begin_short_backtrace
5: std::rt::lang_start::{{closure}}
6: std::panicking::try
7: std::rt::lang_start_internal
8: std::rt::lang_start
9: main
10: __libc_start_main
11: _start
Trait Implementations
Auto Trait Implementations
impl<E> RefUnwindSafe for Report<E> where
E: RefUnwindSafe,
impl<E> Send for Report<E> where
E: Send,
impl<E> Sync for Report<E> where
E: Sync,
impl<E> Unpin for Report<E> where
E: Unpin,
impl<E> UnwindSafe for Report<E> where
E: UnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more