vacro-report 0.1.3

Diagnostic reporting enhancements for Rust procedural macros, improving error messages.
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

# Vacro Report

**Better Panic Reporting for Procedural Macros**

[![crates.io](https://img.shields.io/crates/v/vacro-report.svg?style=for-the-badge&color=fc8d62&logo=rust)](https://crates.io/crates/vacro-report)
[![docs.rs](https://img.shields.io/badge/docs.rs-vacro--report-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs)](https://docs.rs/vacro-report)

## Introduction

`vacro-report` is a diagnostic enhancement tool designed to improve the debugging experience for Rust Procedural Macros.

It currently focuses on solving the opaque panic messages generated by `syn::parse_quote!` or `parse_quote_spanned`. When `parse_quote!` or `parse_quote_spanned` fails, it usually just says "failed to parse". `vacro-report` intercepts these calls and prints the actual generated token stream formatted as code, highlighting the syntax error.

## Installation

```toml
[dependencies]
vacro-report = "0.1.3"
```

## Usage

Simply decorate your function with `#[vacro_report::scope]`.

Inside the scope, any usage of `parse_quote!` and `parse_quote_spanned` will be automatically instrumented. No other code changes are required.

```rust
use syn::{parse_quote, Expr, Token};
use vacro_report::scope;

#[scope]
fn generate_code() {
    // If this fails, vacro-report will print the exact tokens that caused the error.
    let _expr: Expr = parse_quote! {
        1 + 2 + // Missing operand, would normally panic silently or vaguely
    };
}
```

## Features

- **Automatic Interception**: Rewrites `parse_quote!` and `parse_quote_spanned!` calls within the `#[scope]` function.
- **Detailed Diagnostics**: When a parsing error occurs, it displays the generated code (formatted) and the error location.
- **Zero Overhead (Success)**: Adds minimal overhead only when an error actually occurs (panic path).
  > ⚠️ Warning
  >
  > We use `debug_assertions` to make this judgment, which means that if you have enabled certain optimizations, the effect may not trigger.

## Macro `help!` (v0.1.3)

Creates a wrapper type with enhanced error reporting and smart hints.

This macro defines a new struct (wrapper type) that proxies the behavior of the underlying parsing type (such as `syn::Ident` or `syn::Expr`) and allows you to attach context-aware error messages, help text, and code examples.

## Syntax

```rust,ignore
help!(NewTypeName: BaseType {
    error: "Short error message",
    help: "More detailed help text/suggestions",
});

```

## Basic Usage

```rust
# use vacro_report::help;
use syn::Ident;

help!(MyIdent: Ident {
    error: "expected a valid identifier",
    help: "identifiers must start with a letter or underscore"
});

```

## Support for [vacro-parser](https://www.google.com/url?sa=E&source=gmail&q=https://docs.rs/vacro-parser/latest/vacro_parser)

When both the `parser` and `report` features of `vacro` are enabled, or when `vacro-report` is installed independently with the `parser` feature enabled, you can use the `example` field to provide additional support for `vacro-parser`, enabling it to generate more detailed help information.

```rust
# use vacro_report::help;
use syn::Expr;

help!(Arithmetic: Expr {
    error: "expected an arithmetic expression",
    help: "try using explicit values like 1, 2 or operations like 1 + 2",
    // The example here will be used to assist vacro-parser
    example: "1 + 2"
});

```