Macro toplevel 

macro_rules! toplevel {
    (($($args:tt)*), $err:expr) => { ... };
}

Available on crate feature macros only.

Creates a one-time ErrorTrace-compatible type from the given string, then calls trace() on it.

Arguments

The macro has the following signature:

(`$($args:tt)*), $err:expr

• $($args:tt)*: A message to use for the toplevel error. This can be given the arguments to a format!-call.
• $err:expr: The error to embed in the newly built type.

Returns

An ErrorTraceFormatter that can be displayed immediately.

Example

use error_trace::toplevel;

// Do something that fails
let err = std::str::from_utf8(&[0xFF]).unwrap_err();

// Format it with a one-time parent error
assert_eq!(
    toplevel!(("Oh no, everything went wrong!"), err).to_string(),
    r#"Oh no, everything went wrong!

Caused by:
 o invalid utf-8 sequence of 1 bytes from index 0

"#
);

One can use full format strings for the message:

use error_trace::toplevel;

// Do something that fails
let bytes: [u8; 1] = [0xFF];
let err = std::str::from_utf8(&bytes).unwrap_err();

// Format it with a one-time parent error
assert_eq!(
    toplevel!(("Failed to parse '{:?}'", bytes.as_slice()), err).to_string(),
    r#"Failed to parse '[255]'

Caused by:
 o invalid utf-8 sequence of 1 bytes from index 0

"#
);


// Equivalent to above (but using a neater format syntax!)
assert_eq!(
    toplevel!(("Failed to parse '{bytes:?}'"), err).to_string(),
    r#"Failed to parse '[255]'

Caused by:
 o invalid utf-8 sequence of 1 bytes from index 0

"#
);