vacro 0.2.5

A progressive DevX framework for building Rust procedural macros. Painless parsing, visual debugging, and robust tooling.
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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

# 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:

1. **Parsing**: Write parsing logic in a declarative way.
2. **Debugging**: Visualize the parsing path to see exactly what happens inside the macro.
3. **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:

```rust
# #[cfg(feature = "parser")]
# mod parser_example {
use vacro::prelude::*;

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

See more: [vacro-parser](https://docs.rs/vacro-parser)

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

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

```rust
# #[cfg(feature = "trace")]
# mod trace_example {
use vacro::prelude::*;

# fn main() {
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](https://docs.rs/vacro-trace)

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

Provides superior error reporting capabilities.

```rust
# #[cfg(feature = "report")]
# mod report_example {
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](https://docs.rs/vacro-report)

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

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

```bash
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:

```rust
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);
}

```

<div align="center">
<img src="https://github.com/FeVeR-Store/vacro/blob/master/assets/vacro-cli.gif?raw=true" width="100%" alt="Vacro CLI Demo">
</div>

See more: [vacro-cli](https://crates.io/crates/vacro-cli)