color-eyre

color-eyre is a Rust library designed to provide enhanced, colorful, and pretty-printed error reporting for applications. It works in conjunction with the `eyre` (or `anyhow`) error handling crates, significantly improving the developer experience by making error messages more readable, informative, and visually appealing.

Key features and benefits of `color-eyre` include:

* Pretty-printed Errors: It formats error messages with colors, clear structure, and often adds helpful context, making them much easier to parse at a glance than standard Rust error outputs.
* Detailed Backtraces: By default, in debug builds, it prints comprehensive backtraces that show the execution path leading to the error. This is highly configurable, allowing developers to control when and how backtraces are displayed (e.g., always, never, on specific conditions).
* Platform-Specific Context: `color-eyre` can automatically inject useful platform-specific information into error reports, such as OS error codes for I/O errors, aiding in faster diagnosis.
* `tracing` Spans Integration: When integrated with the `tracing` crate, it can include active `tracing` spans in the error report, providing even deeper context about the program's flow at the time of the error.
* Compact Mode: For scenarios where verbose output is not desired, a compact mode can be enabled to reduce the amount of information printed, offering a balance between detail and conciseness.
* Easy Setup: Setting up `color-eyre` typically involves a single call to `color_eyre::install()` at the very beginning of your `main` function. This hook integrates it into the global panic and error reporting mechanisms.

`color-eyre` is particularly useful in applications where errors can be complex or occur deep within the call stack. By presenting errors in a well-structured and digestible format, it reduces the time spent deciphering cryptic messages and greatly boosts debugging efficiency.

Example Code

[Cargo.toml]
```toml
[package]
name = "color_eyre_example"
version = "0.1.0"
edition = "2021"

[dependencies]
color-eyre = "0.6" # Or a newer compatible version
eyre = "0.6"        # Or a newer compatible version
```

[src/main.rs]
```rust
use color_eyre::{eyre::Report, Result};
use std::{fs, io::ErrorKind, path::Path};

fn main() -> Result<()> {
    // 1. Install the color-eyre hook. This must be called only once at the start
    // of your application. It sets up the panic and error reporting hooks.
    color_eyre::install()?;

    println!("--- color-eyre Example ---");

    // Simulate an error by trying to read a non-existent file
    println!("\nAttempting to read a non-existent file...");
    if let Err(e) = read_file("non_existent_file.txt") {
        eprintln!("Caught expected error: {:?}", e);
        // We explicitly print it here for demonstration, usually main() returning Result handles this.
    }

    // Simulate another error by trying to parse an invalid number string
    println!("\nAttempting to parse an invalid number string...");
    parse_invalid_number("abc")?;

    // This part will not be reached if parse_invalid_number errors out.
    println!("\nThis message indicates success (if previous operations didn't fail). However, the example is designed to show errors.");

    Ok(())
}

/// A function that attempts to read a file, which might fail.
/// It wraps errors with additional context using `eyre`.
fn read_file(path_str: &str) -> Result<String> {
    let path = Path::new(path_str);
    fs::read_to_string(path).map_err(|e| {
        // Add context to the error using eyre's .wrap_err()
        match e.kind() {
            ErrorKind::NotFound => Report::new(e).wrap_err(format!("File not found: {}", path.display())),
            _ => Report::new(e).wrap_err(format!("Failed to read file: {}", path.display())),
        }
    })
}

/// A function that attempts to parse a string into an integer, which might fail.
/// It wraps parsing errors with additional context.
fn parse_invalid_number(s: &str) -> Result<i32> {
    s.parse::<i32>().map_err(|e| {
        Report::new(e).wrap_err(format!("Failed to parse '{}' as an integer", s))
    })
}
```

To run this example:
1.  Create a new Rust project: `cargo new color_eyre_example`
2.  Navigate into the project directory: `cd color_eyre_example`
3.  Update `Cargo.toml` with the `dependencies` section as shown above.
4.  Replace the content of `src/main.rs` with the provided code.
5.  Run the application: `cargo run`

You will observe colorful, detailed error messages printed to the console when `parse_invalid_number("abc")` fails, complete with backtraces (in debug mode) and the context added by `wrap_err`.

Example Code

Related Topics