Macro format_err

macro_rules! format_err {
    (code = $c:expr, raw = $arg:expr, context = $arg2:expr) => { ... };
    (code = $c:expr, raw = $arg:expr) => { ... };
    (code = $c:expr, raw = ($($arg:tt)*), context = ($($arg2:tt)*) $(,)?) => { ... };
    (code = $c:expr, context = $($arg2:tt)*) => { ... };
    (code = $c:expr, raw = $arg:literal, context = $($arg2:tt)*) => { ... };
    (code = $c:expr, raw = $arg:ident, context = $($arg2:tt)*) => { ... };
    (code = $c:expr) => { ... };
    (code = $c:expr, raw = $($arg:tt)*) => { ... };
    (code = $c:expr, $($arg:tt)*) => { ... };
    (any = $($arg:tt)*) => { ... };
    (raw = $($arg:tt)*) => { ... };
    ($c:expr, raw = $arg:expr) => { ... };
    ($c:expr, raw = $arg:expr, context = $arg2:expr) => { ... };
    ($c:expr, raw = ($($arg:tt)*), context = ($($arg2:tt)*) $(,)?) => { ... };
    ($c:expr, context = $arg:expr) => { ... };
    ($c:expr, context = $($arg2:tt)*) => { ... };
    ($c:expr, raw = $($arg:tt)*) => { ... };
    ($c:expr) => { ... };
    ($($arg:tt)*) => { ... };
}

Format error with code, raw, and context messages.

• code is come from native C API for from websocket API.
• raw is the error message which is treated as internal error.
• context is some context message which is helpful to users.

We suggest to use all the three fields to construct a more human-readable and meaningful error. Suck as:

let err = format_err!(
    code = 0x0618,
    raw = "Message error from native API",
    context = "Query with sql: `select server_status()`"
);
let err_str = err.to_string();
assert_eq!(err_str, "[0x0618] Query with sql: `select server_status()`: Internal error: `Message error from native API`");

It will give the error:

[0x0618] Query with sql: `select server_status()`: Internal error: `Message error from native API`

For more complex error expressions, use a format! like API as this:

let _ = format_err!(
    code = 0x0618,
    raw = ("Message error from native API while calling {}", "some_c_api"),
    context = ("Query with sql {:?} in {}", sql, context),
);

In this kind of usage, code = is optional, so you can use a shorter line:

let _ = format_err!(0x0618, raw = "Some error", context = "Query error");

The raw or context is optional too:

let _ = format_err!(0x0618, raw = "Some error");
let _ = format_err!(0x0618, context = "Some error");

For non-internal errors, eg. if you prefer construct an anyhow-like error manually, you can use the same arguments like anyhow::format_err with this pattern:

let err = format_err!(any = "Error here: {}", message);
let err = format_err!("Error here: {}", message);

It’s equivalent to:

let err = Error::from(anyhow::format_err!("Error here: {}", message));