Skip to content
A library for conveniently displaying well-formatted, and good looking errors to users of CLI applications. Useful for bubbling up unrecoverable errors to inform the user what they can do to fix them.
Rust
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows
src
tests
.gitignore
.gitlab-ci.yml
CHANGELOG.md Added in a CHANGELOG, updated the README and the Cargo.toml to reflec… Jul 6, 2019
Cargo.toml
LICENSE.txt
README.md

README.md

UserFacingError

UserError is an error type that helps you format and print good looking error messages for users of your CLI application. These errors are intended for consumption by a human, not your program. They are divided into 3 parts: summary, reasons and help text.

Summary: A String representing a one-line description of your error. A summary is mandatory and is printed boldly in red.

Reasons: A vector of Strings explaining in more detail why this error occured. Reasons are optional and if the terminal supports color, the bullet point ('-') will be colored yellow. Each reason will be printed on its own line.

Help Text: A String explaining additional information, including what the user can do about the error, or where to file a bug. Help text is optional and if the terminal supports color it will be printed dimly.

Docs

The docs are really good for this crate. In addition to reading this README you can find tons of examples in the documentation generated by Cargo.

Quickstart

Add the following to your Cargo.toml:

[dependencies]
user-error = "1.1.0"

Add the following to your main.rs/lib.rs:

use user_error::UserFacingError;

fn main() {
    let e = UserFacingError::new("Failed to build project") 
                            .reason("Database could not be parsed")
                            .reason("File \"main.db\" not found") 
                            .helptext("Try: touch main.db"); 
    eprintln!("{}", e);
}

This prints:

Error: Failed to build project
- Database could not be parsed
- File "main.db" not found
Try: touch main.db

If the user has colors enabled on their terminal, it may look something like this: Quickstart example of user-error library for Rust

Print

If for some reason you don't want to follow the format!() convention, you can call print() on a UserError and it will pretty print itself to stderr

use user_error::UserError;

fn main() {
    let e = UserFacingError::new("Critical Failure!");
    e.print();
}

This prints:

Error: Critical Failure!

Print and Exit

Since this error is likely the last thing your program will run you can use this shortcut to print the error and exit the process in an immediate, albeit ungraceful manner. Returns error code 1 to the OS.

use user_error::UserError;

fn main() {
    let e = UserFacingError::new("Critical Failure!");
    e.print_and_exit();
    eprintln("I am never printed!");
}

This prints:

Error: Critical Failure!
You can’t perform that action at this time.