Crate vacro

Expand description

§Vacro

The Progressive DevX Framework for Rust Procedural Macros

§The Philosophy

Writing procedural macros in Rust shouldn’t be a nightmare filled with boilerplate code and black-box debugging.

Vacro has evolved from a simple parsing library into a complete toolchain designed to improve the Developer Experience (DevX) across the entire macro lifecycle:

Parsing: Write parsing logic in a declarative way.
Debugging: Visualize the parsing path to see exactly what happens inside the macro.
Reporting: Easily generate elegant and precise compiler error messages.

§The Ecosystem

Vacro is designed as a modular framework. You can use the fully-featured vacro entry point or pick specific underlying components as needed.

Feature	Crate	Description
Parsing	`vacro-parser`	Declarative Parsing. A DSL similar to `macro_rules!` that automatically implements `syn::Parse`.
Debugging	`vacro-trace`	Visual Tracing. Captures snapshots and logs to solve complex grammar debugging issues.
Visualization	`vacro-cli`	TUI Tool. A terminal interface to inspect traces and diff snapshots captured by `vacro-trace`.
Diagnostics	`vacro-report`	Error Reporting. Simplifies the construction and emission of diagnostic messages in proc-macros.

§Quick Start

§1. Declarative Parsing (`vacro-parser`)

Define your macro’s input grammar like writing regex:

use vacro::prelude::*;

// Define syntax: "fn" <name> "(" <args> ")"
vacro::define!(MyMacroInput:
    fn
    #(name: syn::Ident)
    ( #(args*[,]: syn::Type) )
);

See more: vacro-parser

§2. Visual Debugging (`vacro-trace`)

Take snapshots of your TokenStream to see how it evolves. View the diffs in vacro-cli.

use vacro::prelude::*;

let tokens = quote::quote! { struct A; };
// Capture a snapshot with a tag.
// If called multiple times with the same tag, vacro-cli will show the diff.
vacro::snapshot!("expand", tokens);

See more: vacro-trace

§3. Diagnostic Reporting (`vacro-report`)

Provides superior error reporting capabilities.

use vacro::prelude::*;

#[vacro::report::scope]
fn my_macro_impl(input: proc_macro2::TokenStream) -> proc_macro2::TokenStream {
    // If this fails (e.g., invalid syntax constructed),
    // Vacro will catch it and emit a precise error pointing to the code.
    // let f: syn::ItemFn = parse_quote!( fn foo () { >>invalid<< } );
    quote::quote!()
}

See more: vacro-report

§4. Visualization Tool (`vacro-cli`)

Install and run the TUI tool to view trace data and snapshot diffs.

cargo install vacro-cli
# 1. Run tests to generate trace data
cargo test
# 2. Launch the visualizer
cargo vacro

Run the following test, then open the CLI to inspect the captured logs and snapshot evolution:

use vacro::trace::{debug, error, info, instrument, snapshot, warn};

#[test]
#[instrument]
fn test_function() {
    // 1. Log
    info!("Function started");
    warn!("This is a warning");
    error!("This is an error");

    // 2. Snapshot
    // Initial state
    let code_snippet = quote! { x: i32 };
    snapshot!("Field", code_snippet);

    // State change: Wrap in a struct
    // vacro-cli will automatically diff multiple snapshots with the "Struct" tag
    let code_snippet = quote! { struct A { #code_snippet }};
    snapshot!("Struct", code_snippet);

    // State change: Add derive
    let code_snippet = quote! {
        #[derive(Debug)]
        #code_snippet
    };
    snapshot!("Struct", code_snippet);

    let x = 1 + 1;
    debug!("Calculation result: {}", x);
}

See more: vacro-cli

§Vacro

Rust 过程宏的渐进式 DevX 框架

§设计理念

在 Rust 中编写过程宏不应该是一场充满样板代码和黑盒调试的噩梦。

Vacro 已经从一个简单的解析库演进为一个完整的工具链，旨在提升过程宏开发全生命周期的 开发者体验 (DevX)：

解析 (Parsing)：以声明式的方式编写解析逻辑。
调试 (Debugging)：可视化解析路径，精准洞察宏内部发生了什么。
报告 (Reporting)：轻松生成优雅且精确的编译器错误信息。

§生态系统

Vacro 被设计为一个模块化框架。你可以使用功能齐全的 vacro 入口，也可以根据需要挑选特定的底层组件。

功能	Crate	描述
Parsing	`vacro-parser`	声明式解析。类似 `macro_rules!` 的 DSL，自动实现 `syn::Parse`。
Debugging	`vacro-trace`	可视化追踪。捕获快照和日志，以解决复杂的语法调试问题。
Visualization	`vacro-cli`	终端工具。一个 TUI 界面，用于检查由 `vacro-trace` 捕获的追踪和快照 Diff。
Diagnostics	`vacro-report`	错误报告。简化过程宏中诊断信息的构建和发射。

§快速开始

§1. 声明式解析 (`vacro-parser`)

像写正则一样定义你的宏输入语法：

use vacro::prelude::*;

// 定义语法: "fn" <name> "(" <args> ")"
vacro::define!(MyMacroInput:
    fn
    #(name: syn::Ident)
    ( #(args*[,]: syn::Type) )
);

更多内容参见：vacro-parser

§2. 可视化调试 (`vacro-trace`)

对你的 TokenStream 进行快照，观察它如何演变。在 vacro-cli 中查看 Diff。

use vacro::prelude::*;

let tokens = quote::quote! { struct A; };
// 使用 tag 捕获快照。
// 如果使用相同的 tag 调用多次，vacro-cli 将展示它们之间的 Diff。
vacro::snapshot!("expand", tokens);

更多内容参见：vacro-trace

§3. 诊断报告 (`vacro-report`)

提供卓越的错误报告能力，告别通用的 unexpected identifier 错误。

use vacro::prelude::*;

#[vacro::report::scope]
fn my_macro_impl(input: proc_macro2::TokenStream) -> proc_macro2::TokenStream {
    // 如果这里失败（例如构造了无效语法），
    // Vacro 会捕获它并发出指向代码的精确错误。
    // let f: syn::ItemFn = parse_quote!( fn foo () { >>invalid<< } );
    quote::quote!()
}

更多内容参见：vacro-report

§4. 可视化工具 (`vacro-cli`)

安装并运行 TUI 工具来查看追踪数据和快照对比。

cargo install vacro-cli
# 1. 运行测试生成追踪数据
cargo test
# 2. 启动可视化界面
cargo vacro

编写如下测试代码，运行测试后即可在 CLI 中查看捕获的日志和快照演变：

use vacro::trace::{debug, error, info, instrument, snapshot, warn};

#[test]
#[instrument]
fn test_function() {
    // 1. Log
    info!("Function started");
    warn!("This is a warning");
    error!("This is an error");

    // 2. Snapshot
    // Initial state
    let code_snippet = quote! { x: i32 };
    snapshot!("Field", code_snippet);

    // State change: Wrap in a struct
    // vacro-cli will automatically diff multiple snapshots with the "Struct" tag
    let code_snippet = quote! { struct A { #code_snippet }};
    snapshot!("Struct", code_snippet);

    // State change: Add derive
    let code_snippet = quote! {
        #[derive(Debug)]
        #code_snippet
    };
    snapshot!("Struct", code_snippet);

    let x = 1 + 1;
    debug!("Calculation result: {}", x);
}

更多内容参见：vacro-cli

Modules§

parser: Declarative parsing tools. 声明式解析工具。
prelude: Vacro 常用功能的预导入模块。 A prelude for convenient access to commonly used Vacro features.
report: Diagnostic reporting tools. 诊断报告工具。
trace: Observability and tracing tools. 可观测性追踪工具

Macros§

bind: 即时解析宏：在现有的解析逻辑中快速消费 TokenStream On-the-fly parsing macro: Quickly consume a TokenStream within existing parsing logic
define: 结构体定义宏：定义一个新的 AST 节点并自动实现 syn::parse::Parse Struct definition macro: Define a new AST node and implement syn::parse::Parse automatically
help: 创建带有增强错误报告和智能提示的包装类型。 Creates a wrapper type with enhanced error reporting and smart hints.
snapshot: 捕获 TokenStream 快照。

Capture a TokenStream snapshot.

将当前的 Token 状态记录下来，以便在 `vacro-cli` 中查看。如果使用相同的 tag 调用多次，会自动展示 Diff。用法：`snapshot!("tag", tokens)`

Records the current token state for inspection in `vacro-cli`. If called multiple times with the same tag, it will automatically show a Diff. Usage: `snapshot!("tag", tokens)`

Crate vacro

Crate vacro Copy item path

§Vacro

§The Philosophy

§The Ecosystem

§Quick Start

§1. Declarative Parsing (vacro-parser)

§2. Visual Debugging (vacro-trace)

§3. Diagnostic Reporting (vacro-report)

§4. Visualization Tool (vacro-cli)

§Vacro

§设计理念

§生态系统

§快速开始

§1. 声明式解析 (vacro-parser)

§2. 可视化调试 (vacro-trace)

§3. 诊断报告 (vacro-report)

§4. 可视化工具 (vacro-cli)

Modules§

Macros§

Crate vacro

§1. Declarative Parsing (`vacro-parser`)

§2. Visual Debugging (`vacro-trace`)

§3. Diagnostic Reporting (`vacro-report`)

§4. Visualization Tool (`vacro-cli`)

§1. 声明式解析 (`vacro-parser`)

§2. 可视化调试 (`vacro-trace`)

§3. 诊断报告 (`vacro-report`)

§4. 可视化工具 (`vacro-cli`)