Nivel 3 · Sistemas· Lección 5 de 11 · 25 min
Macros declarativas
macro_rules! — coincidencia de patrones sobre la sintaxis, repetición, higiene, y cuándo una macro es la herramienta adecuada.
Para qué sirven las macros
Las funciones abstraen sobre valores. Los genéricos abstraen sobre tipos. Las macros abstraen sobre la sintaxis: reciben tokens y producen código, antes de la comprobación de tipos. Úsalas para lo que los otros dos no pueden hacer —argumentos variádicos, sintaxis nueva, generar elementos repetitivos— y prefiere una función o un genérico siempre que sirvan.
macro_rules!
Una macro declarativa es una lista de reglas, (patrón) => { expansión }, que se prueban en orden.
macro_rules! square {
($x:expr) => {
$x * $x
};
}
macro_rules! maximum {
($x:expr) => { $x };
($x:expr, $($rest:expr),+) => {{
let a = $x;
let b = maximum!($($rest),+); // recursión
if a > b { a } else { b }
}};
}
fn main() {
println!("{}", square!(7));
println!("{}", square!(2 + 3)); // 25, no 11: un fragmento `expr` se mantiene como una unidad
println!("{}", maximum!(3, 9, 4, 1));
}
$x:expr captura una expresión. A diferencia de una macro de C, lo capturado es un árbol sintáctico ya analizado, no texto, así que square!(2 + 3) es (2 + 3) * (2 + 3). (Aun así evalúa el argumento dos veces: enlázalo a una variable local si eso importa, como hace maximum!.)
Especificadores de fragmento
| Especificador | Coincide con |
|---|---|
expr |
una expresión |
ident |
un identificador |
ty |
un tipo |
pat |
un patrón |
stmt |
una sentencia |
block |
un bloque { … } |
item |
un elemento: fn, struct, impl… |
path |
una ruta como std::fmt::Debug |
literal |
un literal |
lifetime |
un lifetime |
vis |
un calificador de visibilidad, posiblemente vacío |
meta |
el interior de un atributo |
tt |
un único árbol de tokens: el más flexible |
Repetición
use std::collections::HashMap;
macro_rules! hashmap {
() => { HashMap::new() };
( $( $key:expr => $value:expr ),+ $(,)? ) => {{
let mut map = HashMap::new();
$( map.insert($key, $value); )+
map
}};
}
fn main() {
let ages = hashmap! {
"Ada" => 36,
"Grace" => 85, // la coma final se acepta gracias a $(,)?
};
let empty: HashMap<u8, u8> = hashmap!();
println!("{:?} {}", ages.get("Ada"), empty.len());
}
$( … ),+ coincide con el patrón interior una o más veces, separadas por comas. En la expansión, $( … )+ repite su cuerpo una vez por cada coincidencia. Las llaves dobles {{ … }} hacen que la expansión sea una única expresión de bloque.
Generar elementos
Las macros brillan cuando se trata de eliminar impls repetitivos:
trait Zero {
fn zero() -> Self;
fn is_zero(&self) -> bool;
}
macro_rules! impl_zero {
($($t:ty => $z:expr),* $(,)?) => {
$(
impl Zero for $t {
fn zero() -> Self { $z }
fn is_zero(&self) -> bool { *self == $z }
}
)*
};
}
impl_zero!(u8 => 0, i32 => 0, u64 => 0, f64 => 0.0);
macro_rules! newtype {
($(#[$meta:meta])* $vis:vis struct $name:ident($inner:ty);) => {
$(#[$meta])*
$vis struct $name($inner);
impl From<$inner> for $name {
fn from(v: $inner) -> Self { $name(v) }
}
impl std::ops::Deref for $name {
type Target = $inner;
fn deref(&self) -> &$inner { &self.0 }
}
};
}
newtype! {
/// A user identifier.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct UserId(u64);
}
fn main() {
println!("{} {}", i32::zero().is_zero(), 2.5f64.is_zero());
let id: UserId = 42.into();
println!("{id:?} {}", *id + 1);
}
Así implementa la biblioteca estándar los traits para todos los tipos enteros.
Higiene
macro_rules! swap {
($a:expr, $b:expr) => {
let tmp = $a;
$a = $b;
$b = tmp;
};
}
fn main() {
let mut tmp = 1; // el mismo nombre que la variable interna de la macro
let mut other = 2;
swap!(tmp, other);
println!("{tmp} {other}"); // 2 1 — sin colisión
}
El tmp de dentro de la macro y el tmp de quien la llama son identificadores distintos: macro_rules! es higiénica para las variables locales y las etiquetas. No es higiénica para los elementos ni las rutas, que se resuelven en el lugar de la llamada. Por eso, en una biblioteca, refiérete a tus propios elementos como $crate::path::Item y a los de std con una ruta absoluta (::std::vec::Vec).
Ámbito y exportación
Dentro de un crate, una macro es visible textualmente después de su definición. #[macro_export] la coloca en la raíz del crate para que la usen otros crates. En código moderno también puedes reexportarla por su ruta con pub(crate) use my_macro;.
Depuración
cargo expand(un subcomando de cargo que se instala aparte) imprime tu código con todas las macros expandidas.- Los errores del compilador señalan dentro de la expansión y nombran la macro.
- Para entradas complejas, el patrón tt-muncher procesa recursivamente un árbol de tokens cada vez, y las reglas internas (
(@step …) => …) mantienen privados los brazos auxiliares. The Little Book of Rust Macros cataloga estas técnicas.
Límites
macro_rules! no puede inspeccionar tipos, calcular con valores ni crear identificadores nuevos por concatenación. Cuando necesitas analizar la definición entera de un struct y generar código a partir de sus campos, necesitas una macro procedural: la próxima lección.
Ejercicios
- Escribe
my_vec!de modo que admitamy_vec![],my_vec![1, 2, 3]ymy_vec![0; 5]. - Escribe
count!(a, b, c)que se expanda al número de argumentos como una expresión constanteusize. - Escribe una macro
enum_str!que defina un enum y un métodoas_str(&self) -> &'static strque devuelva el nombre de cada variante (pista:stringify!).
Solución del 3
macro_rules! enum_str {
($vis:vis enum $name:ident { $($variant:ident),+ $(,)? }) => {
#[derive(Debug, Clone, Copy, PartialEq)]
$vis enum $name { $($variant),+ }
impl $name {
$vis fn as_str(&self) -> &'static str {
match self {
$( $name::$variant => stringify!($variant), )+
}
}
}
};
}
enum_str! { pub enum Level { Debug, Info, Warn } }
fn main() {
println!("{} {}", Level::Info.as_str(), Level::Warn.as_str());
}
Comprueba lo que has entendido
Elige una respuesta para ver la explicación.
1.¿Con qué coincide
$( $x:expr ),*?2.¿Qué garantiza la higiene de las macros en
macro_rules!?3.¿Por qué
vec!es una macro y no una función?