Expand description
§Vacro Parser
Vacro 的声明式解析内核
§简介
Vacro Parser 是 Vacro 框架的核心声明式解析引擎。它提供了一种类似 macro_rules! 的 DSL，用于简化 Rust 过程宏中基于 syn 的解析逻辑。
它允许你声明式地定义 AST 结构和解析逻辑，消除了繁琐的 input.parse()? 调用。
§核心功能
§1. define!：定义解析结构体
使用 define! 定义一个结构体，它会自动实现 syn::parse::Parse。
// 定义一个名为 MyFn 的结构体，它会自动实现 Parse trait
vacro::define!(MyFn:
fn
#(?: <#(generic*[,]: GenericParam)>)
#(name: Ident)
( #(args*[,]: FnArg) )
#(?: -> #(ret: Type))
);
fn parse_my_fn(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
// 使用方式
let my_fn = parse_macro_input!(input as MyFn);
println!("Function name: {}", my_fn.name);
proc_macro::TokenStream::new()
}§2. bind!：即时流解析
在现有的命令式逻辑中，使用 bind! 快速消费一段 TokenStream。
// 即时解析函数签名模式
bind!(
let captured = (input ->
fn #(name: Ident) #(?: -> #(ret: Type))
)?;
);
// 直接访问捕获的字段
println!("Name: {}", captured.name);
if let Some(ret_type) = captured.ret {
// ...
}§语法参考
| 语法 | 描述 | 解析结果类型 | 示例 |
|---|---|---|---|
literal | 匹配并消费确切的 Token | ! | fn, ->, struct |
#(x: T) | 具名捕获: 捕获类型 T 到字段 x | T | #(name: Ident) |
#(x?: T) | 具名可选: 尝试解析，失败则跳过 | Option<T> | #(ret?: Type) |
#(x*[sep]: T) | 具名迭代: 按分隔符解析 | Punctuated<T, sep> | #(args*[,]: FnArg) |
#(T) | 匿名捕获: 验证 T 存在但不捕获 | ! | #(Ident) |
#(?: T) | 匿名可选: 仅作验证 | ! | #(?: Ident) |
#(*[sep]: T) | 匿名迭代: 仅作验证 | ! | #(*[,]: Ident) |
§多态捕获 (Enum Parsing)
Vacro 支持解析“多态”结构，即输入流中的某个位置可能是多种类型之一。
vacro::define!(MyPoly:
#(data: MyEnum {
Ident, // 1. 简写：匹配 Ident，生成 MyEnum::Ident(Ident)
syn::Type, // 2. 简写：匹配 Type，生成 MyEnum::Type(syn::Type)
Integer: syn::LitInt, // 3. 别名：匹配 LitInt，生成 MyEnum::Integer(LitInt)
Function: fn #(name: Ident), // 4. 模式：生成 MyEnum::Function { name: Ident }
Tuple: (#(@: Ident), #(@: Expr)), // 5. 模式：生成 MyEnum::Tuple(Ident, Expr)
})
);§Vacro Parser
The Declarative Parsing Kernel for Vacro
§Introduction
Vacro Parser is the core declarative parsing engine of the Vacro framework. It provides a macro_rules!-like DSL to simplify the writing of syn-based parsers for Rust Procedural Macros.
It allows you to define AST structures and parsing logic declaratively, eliminating the boilerplate of imperative input.parse()? calls.
§Core Features
§1. define!: Define Parsing Structs
Use define! to define a struct that automatically implements syn::parse::Parse.
// Define a struct named MyFn, it automatically implements the Parse trait
vacro::define!(MyFn:
fn
#(?: <#(generic*[,]: GenericParam)>)
#(name: Ident)
( #(args*[,]: FnArg) )
#(?: -> #(ret: Type))
);
fn parse_my_fn(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
// Usage
let my_fn = parse_macro_input!(input as MyFn);
println!("Function name: {}", my_fn.name);
proc_macro::TokenStream::new()
}§2. bind!: On-the-fly Parsing
Use bind! to consume a portion of a TokenStream within existing imperative logic.
// Parse a function signature pattern on the fly
bind!(
let captured = (input ->
fn #(name: Ident) #(?: -> #(ret: Type))
)?;
);
// Access captured fields directly
println!("Name: {}", captured.name);
if let Some(ret_type) = captured.ret {
// ...
}§Syntax Reference
| Syntax | Description | Result Type | Example |
|---|---|---|---|
literal | Matches and consumes exact tokens | ! | fn, ->, struct |
#(x: T) | Named Capture: Captures type T into field x | T | #(name: Ident) |
#(x?: T) | Named Optional: Attempts to parse; skips if failed | Option<T> | #(ret?: Type) |
#(x*[sep]: T) | Named Iter: Parses by separator | Punctuated<T, sep> | #(args*[,]: FnArg) |
#(T) | Anonymous Match: Validates T exists but doesn’t capture | ! | #(Ident) |
#(?: T) | Anonymous Optional: Validation only | ! | #(?: Ident) |
#(*[sep]: T) | Anonymous Iter: Validation only | ! | #(*[,]: Ident) |
§Polymorphic Capture (Enum Parsing)
Vacro supports parsing “polymorphic” structures, where a position in the input stream can be one of multiple types.
vacro::define!(MyPoly:
#(data: MyEnum {
Ident, // 1. Shorthand: Match Ident, produces MyEnum::Ident(Ident)
syn::Type, // 2. Shorthand: Match Type, produces MyEnum::Type(syn::Type)
Integer: syn::LitInt, // 3. Alias: Match LitInt, produces MyEnum::Integer(LitInt)
Function: fn #(name: Ident), // 4. Pattern: Produces MyEnum::Function { name: Ident }
Tuple: (#(@: Ident), #(@: Expr)), // 5. Pattern: Produces MyEnum::Tuple(Ident, Expr)
})
);