#io-error #path #failure #wrapper #helper #user-friendly #display

deprecated common_failures

DEPRECATED: Helpers for failure, including io::Error wrappers with paths, quick_main!, display_causes_and_backtrace. Deprecated, because failure is long-deprecated.

3 unstable releases

0.2.0 Mar 4, 2024
0.1.1 May 15, 2018
0.1.0 Dec 24, 2017

#50 in #user-friendly

Download history 11/week @ 2023-11-27 3/week @ 2023-12-04 8/week @ 2023-12-11 14/week @ 2023-12-18 7/week @ 2023-12-25 12/week @ 2024-01-08 13/week @ 2024-01-15 3/week @ 2024-01-22 8/week @ 2024-02-05 15/week @ 2024-02-12 27/week @ 2024-02-19 37/week @ 2024-02-26 183/week @ 2024-03-04 29/week @ 2024-03-11

278 downloads per month
Used in 5 crates

CC0 license

19KB
230 lines

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

Latest version License Build Status Build status (AppVeyor)

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:

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:

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

fn open_example(path: &Path) -> Result<File> {
    Ok(File::open(path).io_read_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:

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.

#[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"))
    }
}

Dependencies

~64KB