giveup/
lib.rs

1//! # Giveup
2//!
3//! `giveup` is a tiny abstraction for wrapping and nicely displaying
4//! `Result`s to end-users.
5//!
6//! It is meant to be used as a replacement for `expect` or `unwrap_or_else`,
7//! if an error occured which terminates the program. 
8//!
9//! ## Example
10//!
11//! ```rust
12//! // Here reading the config at the start of the cli app
13//! // fails because the user has not yet created a config file.
14//! let config = Config::read(/*config-path*/)
15//!     .hint("Create a configuration file")
16//!     .example("touch config-filename")
17//!     .giveup("Missing configuration file")
18//! ```
19//!
20//! ## Motivation
21//! In the above scenario `expect` is misplaced because we do not want
22//! the user of the cli to be confronted with a `panic`.
23//! 
24//! To goal is to display an easily readable error messag and offer
25//! as much help as possible, so the user can get back to what
26//! they originally intended to do (which never is fixing some issues
27//! of the tool one is using).
28//! My usual solution would look somewhat like this:
29//!  
30//! ```rust
31//! let config = Config::read(/*config-path*/).unwrap_or_else(|err| {
32//!     eprintln!("Missing configuration file: {}\n \
33//!         Create a new configuration file: `touch config-filename`",
34//!         err);
35//!     std::process::exit(1);
36//! });
37//! ```
38//!
39//! In this case the difference is not world-chaning but using
40//! `unwrap_or_else` can get pretty verbose with lot's of
41//! boilerplate repeating over and over again.
42//! Also `giveup` is more friendly to dynamic error messages
43//! using variables.
44//!
45//! ## Feedback
46//!
47//! I primarily wrote `giveup` for my personal use so I would love
48//! to get your [feedback](https://github.com/d4ckard/giveup/issues).
49//!
50//!
51
52mod giveup;
53mod hint;
54pub use giveup::Giveup;
55pub use hint::Example;