Macros Procedurales Simples
Introducción a la Derivación Básica
En el vasto ecosistema de Rust, las macros procedurales representan una extensión poderosa del sistema de macros declarativas, permitiendo manipulaciones más complejas del código en tiempo de compilación. Este capítulo se centra en los fundamentos de las macros procedurales simples, explorando su integración mediante el crate proc-macro y su aplicación en derivaciones básicas. Al dominar estos conceptos, se facilita la creación de código reutilizable y extensible, preparando el terreno para extensiones más avanzadas en metaprogramación.
El Crate proc-macro
Las macros procedurales en Rust operan a un nivel más profundo que las macros declarativas, procesando el código fuente como un flujo de tokens y generando código Rust válido en respuesta. El crate proc-macro, parte integral de la biblioteca estándar de Rust, proporciona las herramientas esenciales para definir tales macros. Este crate se habilita mediante la característica proc_macro en el archivo Cargo.toml, y su uso requiere que el crate que define la macro se compile como una biblioteca de tipo proc-macro.
En esencia, una macro procedural se define como una función Rust que toma un TokenStream como entrada y devuelve otro TokenStream. El tipo TokenStream representa una secuencia de tokens del código fuente, similar a un flujo de lexemas en un analizador léxico. Por ejemplo, una macro procedural simple podría inspeccionar los tokens de entrada y generar una expansión basada en ellos. Es crucial destacar que las macros procedurales se ejecutan en tiempo de compilación, lo que implica que cualquier error en su lógica se manifiesta como errores de compilación, no en tiempo de ejecución.
Comparado con lenguajes como C++, donde las macros de preprocesador son meras sustituciones textuales, las macros procedurales de Rust ofrecen seguridad y estructuración, ya que operan sobre un árbol de sintaxis abstracta (AST) implícito a través de los tokens. Sin embargo, el crate proc-macro no proporciona parsing directo; para ello, se recurre a crates externos como syn, que se explorarán más adelante. Un detalle sutil radica en la higiene: a diferencia de las macros declarativas, las procedurales no heredan automáticamente la higiene, por lo que el desarrollador debe gestionar explícitamente la unicidad de identificadores para evitar colisiones.
Para ilustrar la sintaxis básica, considere la definición de una macro procedural mínima:
use proc_macro::TokenStream;
#[proc_macro]
pub fn mi_macro_simple(input: TokenStream) -> TokenStream {
// Lógica simple: devolver el input sin cambios
input
}
Esta función, anotada con #[proc_macro], se invoca como una macro function-like, pero el enfoque de este capítulo se limita a derivaciones, no a formas más complejas.
Derivación Básica
Las macros de derivación constituyen una de las aplicaciones más comunes de las macros procedurales, permitiendo la generación automática de implementaciones para traits en tipos de datos. Mediante el atributo #[proc_macro_derive], se define una macro que se aplica a structs, enums o unions mediante #[derive(NombreDeMacro)]. Esta aproximación simplifica la boilerplate, como en el caso de traits estándar como Debug o Clone, pero aquí se explora su creación personalizada.
El proceso inicia con la anotación de la función de macro con #[proc_macro_derive(NombreTrait)], donde NombreTrait es el nombre del trait que se derivará. La función recibe un TokenStream que representa la definición del tipo anotado con #[derive]. La salida debe ser un TokenStream que contenga la implementación del trait para ese tipo. Un caso borde importante surge cuando el tipo tiene campos genéricos o lifetimes, requiriendo que la macro preserve estos parámetros en la implementación generada para mantener la corrección semántica.
En comparación con lenguajes como Haskell, donde las derivaciones son parte del lenguaje base para instancias de clases de tipos, Rust delega esta funcionalidad a macros procedurales, ofreciendo flexibilidad pero demandando precisión en el parsing. Por instancia, una derivación básica para un trait Saludo podría generar un método que imprime un mensaje fijo. Detalles sutiles incluyen la necesidad de manejar visibilidades: si el tipo es pub, la implementación derivada debe respetar esa visibilidad, aunque típicamente se genera como un impl block sin modificadores adicionales.
Un ejemplo aislado de una derivación simple:
use proc_macro::TokenStream;
#[proc_macro_derive(Saludo)]
pub fn saludo_derive(input: TokenStream) -> TokenStream {
// Parsing y generación simulados; en la práctica, usar syn/quote
let output = quote::quote! {
impl Saludo for #nombre_tipo {
fn saludo(&self) {
println!("Hola desde {}", stringify!(#nombre_tipo));
}
}
};
output.into()
}
Aquí, se asume el uso de quote para generar tokens, lo que se detalla en la siguiente sección. Nótese que esta derivación no maneja campos del tipo, limitándose a una implementación estática.
Introducción Mínima a syn y quote
Para manipular efectivamente el TokenStream en macros procedurales, los crates syn y quote emergen como herramientas indispensables. syn facilita el parsing de tokens en estructuras de datos que representan el AST de Rust, mientras que quote permite la generación de tokens a partir de plantillas cuasi-citadas. Estos crates se incluyen como dependencias en el Cargo.toml del crate de macro, con syn configurado para características como derive si es necesario.
El crate syn ofrece tipos como DeriveInput para parsing de definiciones de tipos en derivaciones. Por ejemplo, syn::parse_macro_input!(input as DeriveInput) convierte el TokenStream en una estructura con campos como ident (el nombre del tipo) y data (la variante: struct, enum o union). Una regla formal clave es que el parsing debe manejar todos los atributos y visibilidades, ignorando aquellos no relevantes para evitar errores inesperados. En casos borde, como tipos con atributos personalizados, syn proporciona métodos para filtrarlos.
Por su parte, quote utiliza una sintaxis de cuasi-citación similar a las macros declarativas, interpolando variables con # y repitiendo patrones con #(...)*. Esto contrasta con lenguajes como Lisp, donde las macros operan directamente sobre listas S, pero en Rust, quote abstrae la complejidad de construir TokenStream manualmente. Un detalle sutil reside en la spans: quote preserva las posiciones de origen para mejores diagnósticos de errores.
Un fragmento mínimo ilustrativo:
use syn::{parse_macro_input, DeriveInput};
use quote::quote;
#[proc_macro_derive(Ejemplo)]
pub fn ejemplo_derive(input: TokenStream) -> TokenStream {
let input = parse_macro_input!(input as DeriveInput);
let name = &input.ident;
let expanded = quote! {
impl Ejemplo for #name {
fn metodo() {
// Lógica generada
}
}
};
expanded.into()
}
Esta introducción se mantiene mínima, enfocándose en lo esencial para derivaciones básicas sin explorar parsing avanzado o errores personalizados.
Implementación de #[derive(DebugPersonalizado)]
Para ejemplificar los conceptos previos, se considera la creación de una macro de derivación personalizada: #[derive(DebugPersonalizado)], que genera una implementación de un trait DebugPersonalizado con formato configurable. Este trait extiende la funcionalidad de Debug estándar, permitiendo opciones como prefijos o formatos alternativos mediante atributos auxiliares. La macro utiliza proc-macro, syn y quote para parsear el tipo y generar el código correspondiente.
Primero, se define el trait DebugPersonalizado en un crate separado, con un método que acepta una configuración, como un string para el formato. La macro parsea la estructura del tipo, extrayendo campos y generando una implementación que formatea cada campo según la configuración proporcionada. En casos borde, como structs con campos no nombrados (tuples), la macro debe generar índices en lugar de nombres, asegurando compatibilidad. Otro detalle sutil es el manejo de genéricos: la macro debe copiar los parámetros genéricos al bloque impl para preservar la tipificación.
Un ejemplo de código aislado para la macro:
use proc_macro::TokenStream;
use syn::{parse_macro_input, DeriveInput, Data, Fields};
use quote::quote;
#[proc_macro_derive(DebugPersonalizado, attributes(debug_config))]
pub fn debug_personalizado_derive(input: TokenStream) -> TokenStream {
let input = parse_macro_input!(input as DeriveInput);
let name = &input.ident;
let generics = &input.generics;
// Extracción simple de configuración (asumiendo un atributo básico)
let config = "personalizado";
// En la práctica, parsear atributos
let debug_impl = match &input.data {
Data::Struct(data_struct) => {
match &data_struct.fields {
Fields::Named(fields_named) => {
let field_debugs = fields_named.named.iter().map(|field| {
let field_name = &field.ident;
quote! { format!("{}: {:?}", stringify!(#field_name), &self.#field_name) }
});
quote! { format!("{} {{ {} }}", stringify!(#name), vec![#(#field_debugs),*].join(", ")) }
}
_ => quote! { format!("{} (config: {})", stringify!(#name), #config) },
}
}
_ => quote! { format!("{} (no soportado)", stringify!(#name)) },
};
let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();
let expanded = quote! {
impl #impl_generics DebugPersonalizado for #name #ty_generics #where_clause {
fn debug_personalizado(&self, config: &str) -> String {
#debug_impl
}
}
};
expanded.into()
}
Esta implementación genera un formato configurable, por ejemplo, adaptando el output basado en un atributo como #[debug_config(formato = "detallado")], aunque aquí se simplifica para ilustrar la sintaxis. La configuración se asume estática, pero podría extenderse a runtime mediante el parámetro config.
Habiendo explorado los fundamentos de las macros procedurales simples a través de derivaciones básicas, el siguiente capítulo profundizará en extensiones más avanzadas, como macros de atributo, para manejar transformaciones de código a mayor escala.