FerrousPath

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

  1. Escribe my_vec! de modo que admita my_vec![], my_vec![1, 2, 3] y my_vec![0; 5].
  2. Escribe count!(a, b, c) que se expanda al número de argumentos como una expresión constante usize.
  3. Escribe una macro enum_str! que defina un enum y un método as_str(&self) -> &'static str que 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. 1.¿Con qué coincide $( $x:expr ),*?

  2. 2.¿Qué garantiza la higiene de las macros en macro_rules!?

  3. 3.¿Por qué vec! es una macro y no una función?

Términos clave de esta lección

¿Has terminado la lección y los ejercicios?