manyhow 0.11.4

proc macro error handling à la anyhow x proc-macro-error
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
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

# manyhow
## anyhow for proc macros
[![CI Status](https://github.com/ModProg/manyhow/actions/workflows/test.yaml/badge.svg)](https://github.com/ModProg/manyhow/actions/workflows/test.yaml)
[![Crates.io](https://img.shields.io/crates/v/manyhow)](https://crates.io/crates/manyhow)
[![Docs.rs](https://img.shields.io/crates/v/template?color=informational&label=docs.rs)](https://docs.rs/manyhow)
[![Documentation for `main`](https://img.shields.io/badge/docs-main-informational)](https://modprog.github.io/manyhow/manyhow/)

Proc **m**acro **anyhow**, a combination of ideas from
[`anyhow`](https://docs.rs/anyhow) and
[`proc-macro-error`](https://docs.rs/proc-macro-error) to improve proc macro
development, especially focused on the error handling.

## Motivation
Error handling in proc-macros is unideal, as the top level functions of proc
macros can only return `TokenStreams` both in success and failure case. This
means that I often write code like this, moving the actual implementation in
a separate function to be able to use the ergonomic rust error handling with
e.g., `?`.
```rust
use proc_macro2::TokenStream as TokenStream2;
                                                                                           
#[proc_macro]
pub fn my_macro(input: TokenStream) -> TokenStream {
    match actual_implementation(input.into()) {
        Ok(output) => output,
        Err(error) => error.into_compile_error(),
    }
    .into()
}
                                                                                           
fn actual_implementation(input: TokenStream2) -> syn::Result<TokenStream2> {
    // ..
}
```

## Using the `#[manyhow]` macro
To activate the error handling, just add `#[manyhow]` above any
proc macro implementation, reducing the above example to:

```rust
use manyhow::manyhow;
use proc_macro2::TokenStream as TokenStream2;
                                                                                           
#[manyhow]
#[proc_macro]
fn my_macro(input: TokenStream2) -> syn::Result<TokenStream2> {
    // ..
}
```

See [Without macros](#without-macros) to see what this expands to under the
hood.

A proc macro function marked as `#[manyhow]` can take and return any
`TokenStream` and can also return `Result<TokenStream,
E>` where `E` implements `ToTokensError`. As additional parameters a
[dummy](#dummy-mut-tokenstream) and/or [emitter](#emitter-mut-emitter) can
be specified.

The `manyhow` attribute takes one optional flag when used for `proc_macro`
and `proc_macro_attribute`. `#[manyhow(input_as_dummy)]` will take the input
of a function like `proc_macro` to initialize the [dummy `&mut
TokenStream`](#dummy-mut-tokenstream) while `#[manyhow(item_as_dummy)]` on
`proc_macro_attribute` will initialize the dummy with the annotated item.

## Without macros
`manyhow` can be used without proc macros, and they can be disabled by
adding `manyhow` with `default-features=false`.

The usage is more or less the same, though with some added boilerplate from
needing to invoke one of `function`, `attribute` or `derive`
directly.

While the examples use closures, functions can be passed in as well. The
above example would then change to:
```rust
use proc_macro2::TokenStream as TokenStream2;
                                                                                           
#[proc_macro]
pub fn my_macro(input: TokenStream) -> TokenStream {
    manyhow::function(
        input,
        false,
        |input: TokenStream2| -> syn::Result<TokenStream2> {
            // ..
        },
    )
}
```
[`Emitter`](#emitter-mut-emitter) and [dummy
`TokenStream`](#dummy-mut-tokenstream) can also be used. `function` and
`attribute` take an additional boolean parameter controlling whether the
input/item will be used as initial dummy.

## `emitter: &mut Emitter`
`MacroHandler`s (the trait defining what closures/functions can be used
with `manyhow`) can take a mutable reference to an `Emitter`. This
allows to collect errors, but not fail immediately.

`Emitter::into_result` can be used to return if an `Emitter` contains
any values.

```rust
use manyhow::{manyhow, Emitter, ErrorMessage};
use proc_macro2::TokenStream as TokenStream2;
                                                                                           
#[manyhow]
#[proc_macro]
fn my_macro(input: TokenStream2, emitter: &mut Emitter) -> manyhow::Result<TokenStream2> {
    // ..
    emitter.emit(ErrorMessage::call_site("A fun error!"));
    emitter.into_result()?;
    // ..
}
```

## `dummy: &mut TokenStream`
`MacroHandler`s also take a mutable reference to a `TokenStream`, to
enable emitting some dummy code to be used in case the macro errors.

This allows either appending tokens e.g., with `ToTokens::to_tokens` or
directly setting the dummy code e.g., `*dummy = quote!{some tokens}`.