Crate chainerror

chainerror provides an error backtrace without doing a real backtrace, so even after you strip your binaries, you still have the error backtrace.

chainerror has no dependencies!

chainerror uses .source() of std::error::Error along with line()! and file()! to provide a nice debug error backtrace. It encapsulates all types, which have Display + Debug and can store the error cause internally.

Along with the ChainError<T> struct, chainerror comes with some useful helper macros to save a lot of typing.

Features

no-fileline : completely turn off storing filename and line

display-cause : turn on printing a backtrace of the errors in Display

no-debug-cause : turn off printing a backtrace of the errors in Debug

Tutorial

Read the Tutorial

Examples

use chainerror::*;
use std::error::Error;
use std::io;
use std::result::Result;

fn do_some_io() -> Result<(), Box<Error>> {
    Err(io::Error::from(io::ErrorKind::NotFound))?;
    Ok(())
}

fn func2() -> Result<(), Box<Error>> {
    let filename = "foo.txt";
    do_some_io().map_err(mstrerr!("Error reading '{}'", filename))?;
    Ok(())
}

fn func1() -> Result<(), Box<Error>> {
    func2().map_err(mstrerr!("func1 error"))?;
    Ok(())
}

fn main() {
    if let Err(e) = func1() {
        #[cfg(not(windows))]
        assert_eq!(
            format!("\n{:?}\n", e), r#"
src/lib.rs:20: func1 error
Caused by:
src/lib.rs:15: Error reading 'foo.txt'
Caused by:
Kind(NotFound)
"#
        );
    }
}

use chainerror::*;
use std::error::Error;
use std::io;
use std::result::Result;

fn do_some_io() -> Result<(), Box<Error>> {
    Err(io::Error::from(io::ErrorKind::NotFound))?;
    Ok(())
}

fn func3() -> Result<(), Box<Error>> {
    let filename = "foo.txt";
    do_some_io().map_err(mstrerr!("Error reading '{}'", filename))?;
    Ok(())
}

derive_str_cherr!(Func2Error);

fn func2() -> ChainResult<(), Func2Error> {
    func3().map_err(mstrerr!(Func2Error, "func2 error: calling func3"))?;
    Ok(())
}

enum Func1Error {
    Func2,
    IO(String),
}

impl ::std::fmt::Display for Func1Error {
    fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result {
        match self {
            Func1Error::Func2 => write!(f, "func1 error calling func2"),
            Func1Error::IO(filename) => write!(f, "Error reading '{}'", filename),
        }
    }
}

impl ::std::fmt::Debug for Func1Error {
    fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result {
        write!(f, "{}", self)
    }
}

fn func1() -> ChainResult<(), Func1Error> {
    func2().map_err(|e| cherr!(e, Func1Error::Func2))?;
    let filename = String::from("bar.txt");
    do_some_io().map_err(|e| cherr!(e, Func1Error::IO(filename)))?;
    Ok(())
}

fn main() {
    if let Err(e) = func1() {
        assert!(
            match e.kind() {
                Func1Error::Func2 => {
                    eprintln!("Main Error Report: func1 error calling func2");
                    true
                }
                Func1Error::IO(filename) => {
                    eprintln!("Main Error Report: func1 error reading '{}'", filename);
                    false
                }
            }
        );

        assert!(e.find_chain_cause::<Func2Error>().is_some());

        if let Some(e) = e.find_chain_cause::<Func2Error>() {
            eprintln!("\nError reported by Func2Error: {}", e)
        }


        assert!(e.root_cause().is_some());

        if let Some(e) = e.root_cause() {
            let ioerror = e.downcast_ref::<io::Error>().unwrap();
            eprintln!("\nThe root cause was: std::io::Error: {:#?}", ioerror);
        }

        #[cfg(not(windows))]
        assert_eq!(
            format!("\n{:?}\n", e), r#"
src/lib.rs:47: func1 error calling func2
Caused by:
src/lib.rs:22: Func2Error(func2 error: calling func3)
Caused by:
src/lib.rs:15: Error reading 'foo.txt'
Caused by:
Kind(NotFound)
"#
        );
    }
}

Macros

cherr	Creates a new ChainError<T>
derive_str_cherr	Convenience macro to create a "new type" T(String) and implement Display + Debug for T
into_cherr
minto_cherr
mstrerr	Convenience macro for |e| cherr!(e, format!(…))
strerr	Convenience macro for cherr!(T(format!(…))) where T(String)

Structs

ChainError

chains an inner error kind T with a causing error

Traits

ChainErrorDown	Convenience trait to hide the ChainError<T> implementation internals
ChainErrorFrom
IntoChainError

Type Definitions

ChainResult

convenience type alias