vacro-parser 0.1.4

A declarative parsing library for Rust procedural macros, simplifying input handling.
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

# Vacro Parser

**The Declarative Parsing Kernel for Vacro**

[![crates.io](https://img.shields.io/crates/v/vacro-parser.svg?style=for-the-badge&color=fc8d62&logo=rust)](https://crates.io/crates/vacro-parser)
[![docs.rs](https://img.shields.io/badge/docs.rs-vacro--parser-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs)](https://docs.rs/vacro-parser)

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

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
vacro-parser = "0.1.4"
```

## Core Features

### 1. `define!`: Define Parsing Structs

Use `define!` to define a struct that automatically implements `syn::parse::Parse`.

```rust
use syn::{Ident, Type, GenericParam, FnArg, parse_macro_input};

// Define a struct named MyFn, it automatically implements the Parse trait
vacro::define!(MyFn:
    fn
    #(?: <#(generic*[,]: GenericParam)>)
    #(name: Ident)
    ( #(args*[,]: FnArg) )
    #(?: -> #(ret: Type))
);

// Usage in a proc-macro
// 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!`: On-the-fly Parsing

Use `bind!` to consume a portion of a `TokenStream` within existing imperative logic.

```rust
use syn::{Ident, Type, Token};
use vacro::bind;

fn parser(input: syn::parse::ParseStream) -> syn::Result<()> {
    // 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 {
        // ...
    }
    Ok(())
}
```

## Syntax Reference

| Syntax | Description | Example |
| :--- | :--- | :--- |
| `literal` | Matches exact tokens | `fn`, `->`, `struct` |
| `#(x: T)` | **Named Capture**: Captures type `T` into field `x` | `#(name: Ident)` |
| `#(x?: T)` | **Optional Capture**: `Option<T>` | `#(ret?: Type)` |
| `#(x*[sep]: T)` | **Iterative Capture**: `Punctuated<T, sep>` | `#(args*[,]: FnArg)` |
| `#(T)` | **Anonymous Match**: Validates `T` exists but doesn't capture | `#(Ident)` |

## License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.