errors 0.1.0

std::error::Error utilities
Documentation 
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
56
57
58
59
60
61

# errors

`std::error::Error` extensions

[![crates.io](https://img.shields.io/crates/v/errors.svg)](https://crates.io/crates/errors)
[![Documentation](https://docs.rs/errors/badge.svg)](https://docs.rs/errors)

This crate encourages usage of the `std::error::Error` trait for
describing errors, providing the following utilities:

- **Error creation**: The `errors::new`, `errors::wrap`,
  and `errors::opaque` functions ease the creation of simple
  error values.
- **Error inspection**: Error source chains can be easily iterated with
  `errors::iter` iterators to find the error you're looking for.
- **Error formatting**: The error values created with this crate provide
  simple yet powerful control over the formatting of errors and their
  source chains, and the `errors::fmt` adapter allows
  foreign error values to follow along.

## Configuring Error Formatting

An `Error` likely has a message, it might have a cause, and someday, it may
have a backtrace. How can a user decide how they should be formatted?

### Output options:

- Top message only

  ```
  ship exploded
  ```
- Top message + message of source chain
  
  ```
  ship exploded: cat hair in generator
  ```
- Top message + message of source chain + trace/frame

  ```
  ship exploded
      at main.rs:55
      at ship.rs:89
  Caused by: cat hair in generator
      at ship::parts::generator.rs:33
      at ship::parts::engine.rs:789
      at ship.rs:89
      at main.rs:55
  ```

### Format flags

- **Default (`{}`)**: Print only the top-level message. This is inline with the recommendation for `Error`
  - *Example*: `println!("top only = {}", err)` outputs `top only = ship exploded`.
  - *Alternative*: This could also be achieved and possibly clearer by setting the "precision" flag to 0, such as `println!("top only: {:.0}", err)`.
- **Message chain (`{:+}`)**: Prints the message, and the message of each source, joined by `": "`.
  - *Example*: `println!("chain = {:+}", err)` outputs `chain = ship exploded: cat hair in generator`.
- **With trace/frame (`{:#}`)**: Prints the message and stack trace/frame
  - *Example*: `println!("top trace = {:#}", err)` outputs `top trace = ship exploded\n    at ship.rs:89`.
- **Message chain with trace/frame (`{:+#}`)**: Prints the message and stack trace/frame, and message and trace for each source, joined by `\nCaused by:`.
- **Message chain maximum (`{:+.2}`)**: Sets the maximum messages that should be printed down the source chain.