syn y quote: parsear los tokens, generar el código

Un TokenStream es la moneda que cruza la frontera con el compilador, pero es una moneda incómoda de contar: recorrer tokens a mano —distinguir un identificador de una llave de apertura, emparejar delimitadores, reconstruir la forma de un struct— es tan tedioso como escribir un parser desde cero cada vez. La comunidad resolvió el problema con dos crates que hoy son casi parte del lenguaje: syn, que parsea el TokenStream de entrada a un árbol sintáctico tipado y navegable, y quote, cuya macro quote! genera un TokenStream de salida a partir de una plantilla de código con huecos interpolables. La una lee, la otra escribe. Entre ambas queda tu lógica: la transformación. Ese triple movimiento —parsear, transformar, emitir— es el esqueleto de toda macro procedural, desde el derive de tres líneas hasta el framework más elaborado.

syn: del token crudo al árbol tipado

syn es un parser completo de la gramática de Rust escrito como biblioteca. Le das tokens y te devuelve estructuras de datos con nombres reconocibles: un DeriveInput para lo que decora un derive, un ItemFn para una función, una Expr para una expresión. Cada nodo es un tipo Rust normal que puedes desestructurar con match, recorrer y consultar. La puerta de entrada habitual en una proc-macro es la macro parse_macro_input!, que parsea o, si la sintaxis es inválida, emite por ti un error de compilación bien situado.

use proc_macro::TokenStream;
use syn::{parse_macro_input, DeriveInput};

#[proc_macro_derive(Resumen)]
pub fn derivar_resumen(input: TokenStream) -> TokenStream {
    // Parseo: los tokens del struct/enum anotado se elevan a un AST tipado.
    let ast: DeriveInput = parse_macro_input!(input as DeriveInput);

    let nombre = &ast.ident;      // el identificador del tipo, p. ej. Usuario
    let generics = &ast.generics; // sus parametros genericos, si los hay
    let datos = &ast.data;        // Data::Struct, Data::Enum o Data::Union

    // ... aqui iria la transformacion y la emision ...
    let _ = (nombre, generics, datos);
    TokenStream::new()
}

Con el AST en la mano, interrogar la estructura del tipo es cuestión de navegar campos. ast.ident te da el nombre; ast.data distingue struct de enum; dentro de un struct, Fields::Named te entrega la lista de campos con su identificador y su tipo. Esa introspección es justo lo que macro_rules! no puede hacer: una macro declarativa empareja patrones sintácticos, pero no puede preguntar “¿cuántos campos tiene este struct y de qué tipo es cada uno?”. syn sí.

quote: de las variables al token nuevo

Del lado de la salida, escribir tokens a mano sería aún peor. quote! te deja redactar el código generado como si lo teclearas, con dos operaciones de plantilla. La interpolación #variable inserta el valor de una variable Rust —normalmente un fragmento de AST o un identificador— en ese punto del código. La repetición #( ... )* recorre un iterable y repite el fragmento interior una vez por elemento, como un for dentro de la plantilla.

use quote::quote;
use proc_macro2::TokenStream as TokenStream2;

fn generar(nombre: &syn::Ident, campos: &[syn::Ident]) -> TokenStream2 {
    quote! {
        impl #nombre {
            fn describir(&self) -> String {
                let mut partes: Vec<String> = Vec::new();
                #(
                    partes.push(format!("{}={:?}", stringify!(#campos), self.#campos));
                )*
                partes.join(", ")
            }
        }
    }
}

Fíjate en la mezcla de niveles. #nombre se sustituye una vez por el identificador del tipo. El bloque #( ... )* se repite tantas veces como identificadores haya en campos, y dentro de él #campos toma en cada vuelta el valor correspondiente. Lo que quote! devuelve no es texto ni un String: es un proc_macro2::TokenStream, ya tokenizado, listo para volver al compilador. La plantilla se lee como el código que produce, y esa transparencia es la mitad del valor de la herramienta.

Los dos TokenStream y el flujo completo

Aquí aparece una sutileza que confunde a todo principiante: hay dos tipos TokenStream. El de la biblioteca proc_macro lo provee el compilador y solo existe dentro de una proc-macro —no puedes usarlo en tests ni en código normal—. El de proc_macro2 es un espejo independiente del compilador, y es el que usan syn y quote. La regla práctica: recibes y devuelves proc_macro::TokenStream en la firma pública, pero por dentro trabajas con proc_macro2, convirtiendo en las fronteras con .into().

use proc_macro::TokenStream;
use syn::{parse_macro_input, DeriveInput};
use quote::quote;

#[proc_macro_derive(Resumen)]
pub fn derivar_resumen(input: TokenStream) -> TokenStream {
    let ast = parse_macro_input!(input as DeriveInput); // 1. PARSEAR (syn)
    let nombre = &ast.ident;

    let salida = quote! {                                // 2. TRANSFORMAR + 3. EMITIR (quote)
        impl #nombre {
            fn resumen() -> &'static str {
                stringify!(#nombre)
            }
        }
    };

    salida.into() // proc_macro2::TokenStream -> proc_macro::TokenStream
}

Este esqueleto —parse_macro_input! para entrar, tu lógica en medio, quote! seguido de .into() para salir— es el patrón que reconocerás en el noventa por ciento de las proc-macros del ecosistema. Cambia el AST que parseas y el código que generas; el andamiaje es idéntico.

flowchart LR
A[proc_macro TokenStream de entrada] --> B[syn parsea a un AST tipado]
B --> C[Tu logica recorre y transforma el AST]
C --> D[quote genera un proc_macro2 TokenStream]
D --> E[into vuelve a proc_macro TokenStream]
E --> F[El compilador recibe el codigo generado]
style B fill:#89b4fa,color:#11111b
style C fill:#f9e2af,color:#11111b
style D fill:#cba6f7,color:#11111b
style F fill:#a6e3a1,color:#11111b