Crate vacro_report 

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.

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.

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

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

Future Plans

• Support for more syn macros and custom parsing logic.

Vacro Report

为过程宏提供更优质的 Panic 错误报告

简介

vacro-report 是一个专为 Rust 过程宏（Procedural Macros）设计的诊断增强工具。

目前它主要用于解决 syn::parse_quote! 或 parse_quote_spanned 产生的 Panic 信息晦涩难懂的问题。当 parse_quote! 或 parse_quote_spanned 解析失败时，通常只会抛出一个简单的 “failed to parse”。vacro-report 能够拦截这些调用，并在失败时打印出实际生成的已格式化的 Token 流，并高亮显示语法错误的位置。

使用方法

只需在你的函数上添加 #[vacro_report::scope] 属性宏。

在该作用域内，所有的 parse_quote! 和 parse_quote_spanned 调用都会被自动增强。无需修改内部代码。

#[scope]
fn generate_code() {
    // 如果此处失败，vacro-report 会打印出导致错误的具体 Token 代码
    let _expr: Expr = parse_quote! {
        1 + 2 + // 缺少操作数，通常会产生难以调试的 Panic
    };
}

特性

• 自动拦截：自动重写 #[scope] 函数内部的 parse_quote! 与 parse_quote_spanned! 的调用。
• 详细诊断：发生解析错误时，展示格式化后的生成代码及错误位置。
• 零开销（成功路径）：仅在发生错误（Panic 路径）时才会有额外开销，在生产环境时，只有您写的源代码会被包含。

我们通过 `debug_assertions` 进行判断，意味着，如果您启用了某些优化，可能会导致效果无法触发。

help! 宏（v0.1.3）

此宏定义一个新的结构体（包装类型），它代理了底层解析类型（如 syn::Ident 或 syn::Expr）的行为，并允许你附加上下文相关的错误信息、帮助文本以及示例代码。

语法

help!(NewTypeName: BaseType {
    error: "简短的错误消息",
    help: "更详细的帮助文本/建议",
});

基础用法

use syn::Ident;

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

为 vacro-parser 提供支持

当同时启用 vacro 的 parser 与 report 特性，或独立安装两个 crate 且启用 vacro-report 的 parser feature 时，你可以使用 example 字段为 vacro-parser 提供更多支持，以辅助其提供更详尽的帮助信息。

use syn::Expr;

help!(Arithmetic: Expr {
    error: "expected an arithmetic expression",
    help: "try using explicit values like 1, 2 or operations like 1 + 2",
    // 这里的 example 会用于辅助 vacro-parser
    example: "1 + 2"
});

未来计划

• 支持更多的 syn 宏以及自定义解析逻辑的诊断增强。

Macros

help

创建带有增强错误报告和智能提示的包装类型。 Creates a wrapper type with enhanced error reporting and smart hints.

Attribute Macros

scope

作用域标记宏。 Scope marker macro.