Vacro Report

Better Panic Reporting for Procedural Macros

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

[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.

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

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

Basic Usage

# 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

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.

# 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"
});

vacro-report 0.1.3