Un derive macro paso a paso: generar un getter por campo

La teoría se asienta cuando construyes una macro completa. Vamos a escribir #[derive(Getters)]: un derive que, colocado sobre un struct de campos privados, genera automáticamente un método de acceso pub fn campo(&self) -> &Tipo por cada uno de ellos. Es el ejemplo canónico porque toca todas las piezas —parsear el DeriveInput, ramificar según la forma del dato, iterar sobre los campos, interpolar identificadores y tipos, respetar los genéricos— y sin embargo cabe en una pantalla. Al terminar tendrás una macro real y compilable, y habrás visto el patrón que se repite en derive_builder, en los getters de innumerables crates y en buena parte de los derives que usas a diario sin pensar en lo que generan.

El objetivo y la estructura del crate

Queremos que este uso funcione, sin que el autor del struct escriba un solo getter a mano:

#[derive(Getters)]
struct Usuario {
    nombre: String,
    edad: u32,
}

let u = Usuario { nombre: "Ada".into(), edad: 36 };
assert_eq!(u.nombre(), "Ada");   // metodo generado por la macro
assert_eq!(*u.edad(), 36);       // metodo generado por la macro

La macro vive en un crate aparte de tipo proc-macro, con syn y quote como dependencias:

[lib]
proc-macro = true

[dependencies]
syn = "2"
quote = "1"
proc-macro2 = "1"

Paso a paso: parsear, extraer, iterar, emitir

Este es el cuerpo completo de la macro. Léelo entero una vez y luego lo desmenuzamos.

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

#[proc_macro_derive(Getters)]
pub fn derivar_getters(input: TokenStream) -> TokenStream {
    // 1. PARSEAR: los tokens del struct anotado se elevan a un AST tipado.
    let ast = parse_macro_input!(input as DeriveInput);
    let nombre = &ast.ident;

    // 2. EXTRAER: solo soportamos structs con campos nombrados.
    let campos = match &ast.data {
        Data::Struct(datos) => match &datos.fields {
            Fields::Named(nombrados) => &nombrados.named,
            _ => panic!("Getters exige un struct con campos nombrados"),
        },
        _ => panic!("Getters solo se aplica a structs"),
    };

    // 3. ITERAR: un fragmento de codigo (un getter) por cada campo.
    let getters = campos.iter().map(|campo| {
        let ident = campo.ident.as_ref().unwrap(); // el nombre del campo
        let tipo = &campo.ty;                       // el tipo del campo
        quote! {
            pub fn #ident(&self) -> &#tipo {
                &self.#ident
            }
        }
    });

    // 4. RESPETAR GENERICOS: descomponer <T>, <T: Bound> y where.
    let (impl_generics, ty_generics, where_clause) = ast.generics.split_for_impl();

    // 5. EMITIR: envolver todos los getters en un solo impl.
    let expandido = quote! {
        impl #impl_generics #nombre #ty_generics #where_clause {
            #( #getters )*
        }
    };

    expandido.into()
}

Parsear. parse_macro_input!(input as DeriveInput) convierte los tokens en un DeriveInput, la estructura que syn reserva para lo que decora un derive. Si el usuario aplicara el derive a algo que no parsea como item derivable, syn emitiría el error por nosotros. De ahí sacamos ast.ident, el nombre del tipo.

Extraer. Un DeriveInput puede envolver un struct, un enum o una union: por eso ast.data es un enum Data de tres variantes. Descendemos hasta Data::Struct, y dentro, hasta Fields::Named, que es la lista de campos con nombre. Si nos dan un enum o un struct de tupla, fallamos con un mensaje claro —más adelante veremos cómo hacerlo con elegancia—.

Iterar. Aquí está el corazón. campos.iter().map(...) recorre cada campo y, para cada uno, invoca quote! para fabricar un fragmento de código: la definición de un método cuyo nombre es el del campo (#ident), que devuelve una referencia a su tipo (&#tipo) y cuyo cuerpo presta el campo (&self.#ident). El resultado es un iterador de TokenStream, uno por campo.

Emitir. El quote! final envuelve todo en un impl y despliega la colección de getters con la repetición #( #getters )*, que expande el iterador entero, un método tras otro. Convertimos con .into() y devolvemos.

Por qué split_for_impl no es opcional

Es tentador escribir impl #nombre { ... } a secas, y funcionará mientras el struct no tenga genéricos. En cuanto alguien escriba struct Caja<T> { valor: T }, esa versión ingenua generaría impl Caja { ... } —sin el <T>— y no compilaría. generics.split_for_impl() resuelve esto devolviendo las tres piezas que un impl genérico necesita, cada una en su sitio: impl_generics es el <T: Bound> que va tras impl, ty_generics es el <T> que va tras el nombre del tipo, y where_clause es la cláusula where si la hubiera. Colocadas en la plantilla, el impl generado es correcto para cualquier struct, tenga los genéricos que tenga.

#[derive(Getters)]
struct Caja<T> {
    valor: T,
}

// La macro genera, gracias a split_for_impl:
// impl<T> Caja<T> {
//     pub fn valor(&self) -> &T { &self.valor }
// }

flowchart TD
A[derive Getters sobre el struct] --> B[parse_macro_input a DeriveInput]
B --> C[Descender Data Struct y Fields Named]
C --> D[map sobre cada campo]
D --> E[quote genera un getter por campo]
E --> F[split_for_impl aporta los genericos]
F --> G[quote envuelve todo en un impl]
G --> H[El struct gana sus metodos de acceso]
style B fill:#89b4fa,color:#11111b
style E fill:#cba6f7,color:#11111b
style F fill:#f9e2af,color:#11111b
style H fill:#a6e3a1,color:#11111b