unwrap 1.1.0

An unwrap! macro
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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

# An `unwrap!` macro for Rust.

The crate provides a macro, `unwrap!` which can be used to unwrap values of
type `Result` or `Option` (or any type that implements `VerboseUnwrap`). The
advantage of using this macro over the `.unwrap()`/`.expect()` methods is that,
on a panic, it will print the file name, line number, column number, and
function name of where the macro was called from.

## Example

This code:

```
let x: Result<(), u32> = Err(123);
let y = unwrap!(x);
```

Panics with the following message:

```

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!   unwrap! called on Result::Err                                              !
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
example.rs:2,9 in example_module::example_function

Err(
    123
)

```

`unwrap!` can also be called with an optional error message. This is supplied
as a format string and arguments.

```
let x: Option<()> = None;
let y = unwrap!(x, "Oh no! {}", 123);
```

Prints:

```

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!   unwrap! called on Option::None                                             !
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
example.rs:2,9 in example_module::example_function
Oh no! 123

```

## Implementation

The unwrap crate provides a trait for types which can be unwrapped.

```
trait VerboseUnwrap {
    type Wrapped;
    fn verbose_unwrap(self, message: Option<std::fmt::Arguments>,
                            module_path: &str,
                            file: &str,
                            line_number: u32,
                            column: u32) -> Self::Wrapped;
}
```

This is implemented by both `Result` and `Option`. The `unwrap!` macro simply
calls this trait method:

```
macro_rules! unwrap(
    ($e:expr) => (
        $crate::VerboseUnwrap::verbose_unwrap($e, None, module_path!(), file!(), line!(), column!())
    );
    ($e:expr, $($arg:tt)*) => (
        $crate::VerboseUnwrap::verbose_unwrap($e, Some(format_args!($($arg)*)), module_path!(), file!(), line!(), column!())
    );
);
```

## Usage

Add this to your dependencies in `Cargo.toml`

```
unwrap = "~0.2.0"
```

Then import it using `#[macro_use]`

```
#[macro_use]
extern crate unwrap;
```