common_failures: User-friendly io::Error wrappers, quick_main! and more

We provide support for:

• User-friendly io::Error wrappers with pathnames,
• Formatting errors for display to the user (with the entire cause chain!), and
• Handy helper utilities like quick_main!.

Basically, the goal is to make failure as ergonomic as possible, so that everybody can stop re-inventing common bits of supporting code.

User-friendly io::Error wrappers

By default, Rust's I/O errors do not include any information about the operation that failed. This means that you'll often see errors like:

txt No such file or directory (os error 2)

But it's much nicer for users if we print something like:

Error: error reading the file no-such-file.txt caused by: No such file or directory (os error 2)

To do this, we can use io_read_context and related functions:

```rust use common_failures::prelude::*; use std::fs::File; use std::path::Path;

fn openexample(path: &Path) -> Result { Ok(File::open(path).ioread_context(path)?) } ```

Formatting errors for display to the user

We also provide a support for formatting errors as strings, including the entire chain of "causes" of the error:

rust format!("{}", err.display_causes_and_backtrace());

The quick_main! macro

This is a replacement for quick_main! from the error-chain crate. It generates a main function that calls a second function returning Result<()>, and prints out any errors.

```rust

[macro_use]

extern crate common_failures;

[macro_use]

extern crate failure;

// This imports Result, Error, failure::ResultExt, and possibly // other useful extension traits, to get you a minimal useful API. use common_failures::prelude::*;

// Uncomment this to define a main function that calls run, and prints // any errors that it returns to standard error. quick_main!(run);

fn run() -> Result<()> { if true { Ok(()) } else { Err(format_err!("an error occurred")) } } ```