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