FerrousPath

Nivel 3 · Sistemas· Lección 6 de 11 · 30 min

Macros procedurales

Macros derive, de atributo y de tipo función — programas de Rust que se ejecutan dentro del compilador y escriben Rust.

Tres clases

Clase Aspecto Entrada Salida
Derive #[derive(Serialize)] el struct/enum se añade junto a él
Atributo #[tokio::main], #[test] los argumentos del atributo + el elemento sustituye al elemento
Tipo función sqlx::query!("…") tokens arbitrarios sustituye a la invocación

Cada una es una función de Rust TokenStream -> TokenStream a la que el compilador llama durante la expansión. Puede ejecutar cualquier código: analizar la entrada, leer archivos, incluso hablar con una base de datos (como hace sqlx para comprobar los tipos del SQL). Ese poder es la razón por la que hay que usarlas con mesura: cuestan tiempo de compilación y pueden ocultar muchas cosas.

Estructura del proyecto

builder/
├── Cargo.toml             # workspace
├── builder-derive/        # el crate proc-macro
│   ├── Cargo.toml
│   └── src/lib.rs
└── app/                   # un crate que lo usa
# builder-derive/Cargo.toml
[lib]
proc-macro = true

[dependencies]
syn = { version = "2", features = ["full"] }
quote = "1"
proc-macro2 = "1"

Una macro derive, paso a paso

Objetivo: #[derive(Builder)] sobre un struct genera un FooBuilder con un método de asignación por campo y un build() que informa del primer campo que falta.

// builder-derive/src/lib.rs
use proc_macro::TokenStream;
use quote::{format_ident, quote};
use syn::{parse_macro_input, Data, DeriveInput, Fields};

#[proc_macro_derive(Builder)]
pub fn derive_builder(input: TokenStream) -> TokenStream {
    // 1. Analiza los tokens y construye un árbol sintáctico.
    let input = parse_macro_input!(input as DeriveInput);
    let name = &input.ident;
    let builder = format_ident!("{}Builder", name);

    // 2. Extrae lo que necesitamos, y rechaza con un buen error lo que no admitimos.
    let Data::Struct(data) = &input.data else {
        return syn::Error::new_spanned(name, "Builder can only be derived for structs")
            .to_compile_error()
            .into();
    };
    let Fields::Named(fields) = &data.fields else {
        return syn::Error::new_spanned(name, "Builder requires named fields")
            .to_compile_error()
            .into();
    };

    let idents: Vec<_> = fields.named.iter().map(|f| f.ident.as_ref().unwrap()).collect();
    let types: Vec<_> = fields.named.iter().map(|f| &f.ty).collect();
    let missing: Vec<_> = idents.iter().map(|i| format!("missing field `{i}`")).collect();

    // 3. Genera el código. `#var` interpola; `#( … )*` repite.
    let expanded = quote! {
        #[derive(Default)]
        pub struct #builder {
            #( #idents: ::core::option::Option<#types>, )*
        }

        impl #builder {
            #(
                pub fn #idents(mut self, value: #types) -> Self {
                    self.#idents = ::core::option::Option::Some(value);
                    self
                }
            )*

            pub fn build(self) -> ::core::result::Result<#name, &'static str> {
                ::core::result::Result::Ok(#name {
                    #( #idents: self.#idents.ok_or(#missing)?, )*
                })
            }
        }

        impl #name {
            pub fn builder() -> #builder {
                #builder::default()
            }
        }
    };
    expanded.into()
}

Para usarla:

// app/src/main.rs
use builder_derive::Builder;

#[derive(Debug, Builder)]
struct Request {
    url: String,
    retries: u32,
}

fn main() {
    let ok = Request::builder().url("https://example.com".into()).retries(3).build();
    let bad = Request::builder().retries(3).build();
    println!("{ok:?}\n{bad:?}"); // Ok(Request { … }) / Err("missing field `url`")
}

Cosas que importan en la práctica

Spans y errores. Cada token lleva un span: su ubicación en el código fuente. Informa de los problemas con syn::Error::new_spanned(tokens, msg) para que el error subraye el código del usuario, no la macro. Nunca uses panic! ante los errores del usuario.

Higiene. Las macros procedurales no son higiénicas por defecto: los identificadores generados se resuelven en el lugar de la llamada. Usa rutas absolutas (::core::option::Option), porque el usuario puede haber sombreado Option o Result, y prefiere ::core a ::std para que la macro funcione en crates no_std.

Genéricos. Un derive de verdad debe arrastrar los genéricos del struct:

// dentro de un derive, con `input: DeriveInput` y `name = &input.ident`
let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();
let expanded = quote! {
    impl #impl_generics MyTrait for #name #ty_generics #where_clause {
        // …
    }
};

Atributos auxiliares. #[proc_macro_derive(Builder, attributes(builder))] permite #[builder(default)] en los campos; se leen desde field.attrs.

Pruebas. Pon la lógica en una función sobre proc_macro2::TokenStream para poder probarla con pruebas unitarias. Usa cargo expand para leer la salida y el crate trybuild para comprobar los errores de compilación.

Tiempo de compilación. syn con todas sus características es una dependencia pesada, y cada invocación ejecuta tu código. Una macro macro_rules! o una función genérica, cuando bastan, son más baratas para todos los que dependen de ti.

Macros de atributo

// en el crate proc-macro
use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, ItemFn};

/// Envuelve una función para que imprima cuánto tardó cada llamada.
#[proc_macro_attribute]
pub fn timed(_args: TokenStream, item: TokenStream) -> TokenStream {
    let ItemFn { attrs, vis, sig, block } = parse_macro_input!(item as ItemFn);
    let name = sig.ident.to_string();
    quote! {
        #(#attrs)* #vis #sig {
            let __start = ::std::time::Instant::now();
            let __result = (move || #block)();
            eprintln!("{} took {:?}", #name, __start.elapsed());
            __result
        }
    }
    .into()
}

Esta es la forma de #[tokio::main], de #[test] y de los atributos de ruta de los frameworks web: recibir un elemento y emitir un elemento transformado.

Ejercicios

  1. Construye el derive Builder en un workspace y ejecútalo. Usa cargo expand para leer lo que genera.
  2. Haz que los campos Option<T> sean opcionales en el builder (por defecto valen None y el método de asignación recibe T). Tendrás que inspeccionar syn::Type::Path.
  3. Admite structs genéricos con split_for_impl.
  4. Añade un atributo de campo #[builder(default = "expr")].
  5. Escribe una prueba con trybuild que compruebe que derivar Builder en un enum produce tu mensaje de error.

Comprueba lo que has entendido

Elige una respuesta para ver la explicación.

  1. 1.¿Por qué las macros procedurales deben vivir en su propio crate con proc-macro = true?

  2. 2.¿Qué puede hacer una macro derive con el elemento al que se aplica?

  3. 3.¿Qué crates forman el conjunto de herramientas estándar para escribir macros procedurales?

Términos clave de esta lección

¿Has terminado la lección y los ejercicios?