Macro traceback

macro_rules! traceback {
    () => { ... };
    ($msg:expr) => { ... };
    (err $e:expr) => { ... };
    (err $e:expr, $msg:expr) => { ... };
}

A macro for creating instances of the TracebackError struct with various options.

The traceback! macro simplifies the creation of TracebackError instances by providing convenient syntax for specifying error messages and handling different error types.

Examples

Creating a new TracebackError with a custom message:

let error = traceback_error::traceback!("Custom error message");
println!("{:?}", error);

Creating a new TracebackError from a generic error:

fn custom_function() -> Result<(), traceback_error::TracebackError> {
    // ...
    // Some error occurred
    let generic_error: Box<dyn std::error::Error> = Box::new(std::io::Error::new(std::io::ErrorKind::Other, "Generic error"));
    Err(traceback_error::traceback!(err generic_error))
}

Creating a new TracebackError from a generic error with a custom message:

fn custom_function() -> Result<(), traceback_error::TracebackError> {
    // ...
    // Some error occurred
    let generic_error: Box<dyn std::error::Error> = Box::new(std::io::Error::new(std::io::ErrorKind::Other, "Generic error"));
    Err(traceback_error::traceback!(err generic_error, "Custom error message"))
}

Tracing an error:

fn main() {
    match caller_of_tasks() {
        Ok(_) => {}
        Err(e) => {
            traceback_error::traceback!(err e, "One of the tasks failed");
        }
    }
}

fn task_that_may_fail() -> Result<(), traceback_error::TracebackError> {
    return Err(traceback_error::traceback!("task_that_may_fail failed"));
}

fn other_task_that_may_fail() -> Result<(), traceback_error::TracebackError> {
    return Err(traceback_error::traceback!("other_task_that_may_fail failed"));
}

fn caller_of_tasks() -> Result<(), traceback_error::TracebackError> {
    match task_that_may_fail() {
        Ok(_) => {}
        Err(e) => {
            return Err(traceback_error::traceback!(err e));
        }
    };
    match other_task_that_may_fail() {
        Ok(_) => {}
        Err(e) => {
            return Err(traceback_error::traceback!(err e));
        }
    };
    Ok(())
}

When the error is dropped at the end of main() in the above example, the default callback function generates the following JSON error file:

{
  "message": "One of the tasks failed",
  "file": "src\\main.rs",
  "line": 7,
  "parent": {
    "message": "task_that_may_fail failed",
    "file": "src\\main.rs",
    "line": 24,
    "parent": {
      "message": "task_that_may_fail failed",
      "file": "src\\main.rs",
      "line": 13,
      "parent": null,
      "time_created": "2023-09-11T10:27:25.195697400Z",
      "extra_data": null,
      "project": null,
      "computer": null,
      "user": null,
      "is_parent": true,
      "is_handled": true,
      "is_default": false
    },
    "time_created": "2023-09-11T10:27:25.195789100Z",
    "extra_data": null,
    "project": null,
    "computer": null,
    "user": null,
    "is_parent": true,
    "is_handled": true,
    "is_default": false
  },
  "time_created": "2023-09-11T10:27:25.195836Z",
  "extra_data": null,
  "project": "traceback_test",
  "computer": "tommypc",
  "user": "tommy",
  "is_parent": false,
  "is_handled": true,
  "is_default": false
}

Syntax

The traceback! macro supports the following syntax variations:

• traceback!(): Creates a TracebackError with an empty message, using the current file and line number.

• traceback!($msg:expr): Creates a TracebackError with the specified error message, using the current file and line number.

• traceback!(err $e:expr): Attempts to downcast the provided error ($e) to a TracebackError. If successful, it marks the error as handled and creates a new TracebackError instance based on the downcasted error. If the downcast fails, it creates a TracebackError with an empty message and includes the original error’s description in the extra data field.

• traceback!(err $e:expr, $msg:expr): Similar to the previous variation but allows specifying a custom error message for the new TracebackError instance.

Error Handling

When using the traceback! macro to create TracebackError instances from other error types, it automatically sets the is_handled flag to true for the original error to indicate that it has been handled. This prevents the TRACEBACK_ERROR_CALLBACK function to be called on it.

Environment Variables

Environment variables such as CARGO_PKG_NAME, COMPUTERNAME, and USERNAME are automatically added to the project, computer, and user fields when the error is being handled.