Macros déclaratives

macro_rules! bonjour {
    () => {
        println!("Bonjour !");
    };
}

bonjour!();

macro_rules! carre {
    ($x:expr) => {
        $x * $x
    };
}

let a = carre!(4);         // 16

$x:expr capture une expression et la nomme $x. Dans le développement, $x est remplacé par le code reçu.

macro_rules! declarer {
    ($vis:vis $nom:ident : $t:ty = $valeur:expr) => {
        $vis const $nom: $t = $valeur;
    };
}

declarer!(pub MAX: u32 = 100);
declarer!(MIN: u32 = 0);         // vis vide : privé

macro_rules! est {
    ($valeur:expr, $motif:pat) => {
        matches!($valeur, $motif)
    };
}

let ok = est!(Some(3), Some(1..=5));

macro_rules! mon_vec {
    ( $( $x:expr ),* ) => {{
        let mut v = Vec::new();
        $( v.push($x); )*          // une ligne générée par élément capturé
        v
    }};
}

let v = mon_vec![1, 2, 3];
let vide: Vec<i32> = mon_vec![];

Les doubles accolades {{ ... }} : les premières délimitent le développement, les secondes forment un bloc, pour que les variables (v) ne fuient pas et que le tout soit une seule expression.

macro_rules! liste {
    ( $( $x:expr ),* $(,)? ) => {
        vec![ $( $x ),* ]
    };
}

liste![1, 2, 3];
liste![1, 2, 3,];          // accepté grâce à $(,)?

macro_rules! table {
    ( $( $cle:expr => $valeur:expr ),* $(,)? ) => {{
        let mut m = ::std::collections::HashMap::new();
        $( m.insert($cle, $valeur); )*
        m
    }};
}

let t = table! {
    "un" => 1,
    "deux" => 2,
};

Les variables d'une même répétition avancent ensemble : $cle et $valeur doivent avoir été capturés le même nombre de fois.

macro_rules! matrice {
    ( $( [ $( $x:expr ),* ] ),* ) => {
        vec![ $( vec![ $( $x ),* ] ),* ]
    };
}

let m = matrice!([1, 2], [3, 4], [5, 6]);   // Vec<Vec<i32>>

macro_rules! champ {
    ($nom:ident : $t:ty $(= $defaut:expr)?) => {
        // $defaut n'est utilisable que dans une répétition $( ... )?
        let $nom: $t = champ!(@defaut $($defaut)?);
    };
    (@defaut $e:expr) => { $e };
    (@defaut) => { Default::default() };
}

macro_rules! log {
    ($msg:expr) => {
        println!("[INFO] {}", $msg)
    };
    ($niveau:ident, $msg:expr) => {
        println!("[{}] {}", stringify!($niveau), $msg)
    };
    ($niveau:ident, $fmt:literal, $($arg:tt)*) => {
        println!(concat!("[{}] ", $fmt), stringify!($niveau), $($arg)*)   // concat! exige un littéral
    };
}

log!("démarrage");
log!(WARN, "disque presque plein");
log!(ERREUR, "code {}", 500);

macro_rules! chrono {
    ($nom:expr, $bloc:block) => {{
        let debut = ::std::time::Instant::now();
        let r = $bloc;
        println!("{} : {:?}", $nom, debut.elapsed());
        r
    }};
}

let somme = chrono!("somme", { (1..1_000_000u64).sum::<u64>() });

macro_rules! exiger {
    ($cond:expr, $err:expr) => {
        if !$cond {
            return Err($err.into());
        }
    };
}

fn inscrire(age: u32, email: &str) -> Result<(), String> {
    exiger!(age >= 18, "il faut être majeur");
    exiger!(email.contains('@'), "email invalide");
    Ok(())
}

C'est le principe de anyhow::ensure!. Une macro peut faire return dans la fonction appelante, ce qu'une fonction ne peut pas.

macro_rules! voir {
    ($($e:expr),+ $(,)?) => {
        $( println!("{} = {:?}", stringify!($e), $e); )+
    };
}

voir!(1 + 2, "abc".len());
// 1 + 2 = 3
// "abc".len() = 3

stringify! transforme le code reçu en texte : c'est ainsi que assert! et dbg! affichent l'expression qui a échoué.

macro_rules! getters {
    ($type:ident { $( $champ:ident : $t:ty ),* $(,)? }) => {
        impl $type {
            $(
                pub fn $champ(&self) -> &$t {
                    &self.$champ
                }
            )*
        }
    };
}

struct Utilisateur { nom: String, age: u32 }
getters!(Utilisateur { nom: String, age: u32 });

macro_rules! identifiant {
    ($nom:ident) => {
        #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
        pub struct $nom(pub i64);

        impl ::std::fmt::Display for $nom {
            fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
                write!(f, "{}#{}", stringify!($nom), self.0)
            }
        }

        impl From<i64> for $nom {
            fn from(v: i64) -> Self { $nom(v) }
        }
    };
}

identifiant!(IdUtilisateur);
identifiant!(IdCommande);

Deux lignes génèrent deux types distincts avec six traits chacun : c'est le cas typique où une macro supprime une répétition qu'aucun générique ne peut supprimer (chaque type doit être nommé).

trait Nul { fn est_nul(&self) -> bool; }

macro_rules! impl_nul {
    ($($t:ty),*) => {
        $( impl Nul for $t { fn est_nul(&self) -> bool { *self == 0 as $t } } )*
    };
}

impl_nul!(i8, i16, i32, i64, u8, u16, u32, u64, f32, f64);

La bibliothèque standard implémente ainsi les traits numériques pour chaque type entier.

fn double(x: i32) -> i32 { x * 2 }

macro_rules! tests_double {
    ($($nom:ident : $entree:expr => $attendu:expr),* $(,)?) => {
        $(
            #[test]
            fn $nom() {
                assert_eq!(double($entree), $attendu);
            }
        )*
    };
}

tests_double! {
    zero: 0 => 0,
    positif: 3 => 6,
    negatif: -2 => -4,
}

macro_rules! maximum {
    ($x:expr) => { $x };
    ($x:expr, $($reste:expr),+) => {{
        let a = $x;
        let b = maximum!($($reste),+);
        if a > b { a } else { b }
    }};
}

let m = maximum!(3, 9, 2, 7);    // 9

Chaque appel traite le premier élément et rappelle la macro sur le reste, jusqu'au cas d'arrêt (un seul élément).

macro_rules! compter {
    () => { 0usize };
    ($tete:tt $($reste:tt)*) => { 1usize + compter!($($reste)*) };
}

const N: usize = compter!(a b c d);   // 4

macro_rules! remplacer { ($_t:tt $sub:expr) => { $sub }; }

macro_rules! compter_vite {
    ($($t:tt)*) => { <[()]>::len(&[$(remplacer!($t ())),*]) };
}

const M: usize = compter_vite!(a b c d e);   // 5

Chaque élément devient un () dans un tableau, dont on prend la longueur : aucune limite de récursion.

macro_rules! tableau_noms {
    ($($nom:ident),* $(,)?) => {
        [$(stringify!($nom)),*]
    };
}

const CHAMPS: [&str; 3] = tableau_noms!(nom, email, age);

macro_rules! carre_naif {
    ($x:expr) => { $x * $x };
}

let mut compteur = 0;
let mut suivant = || { compteur += 1; compteur };
let c = carre_naif!(suivant());   // suivant() est appelé DEUX fois : 1 * 2 = 2, pas 1

Le code reçu est recopié à chaque $x. Une expression avec effet de bord (ou coûteuse) est exécutée autant de fois. Correction : l'évaluer une fois dans une variable.

macro_rules! carre {
    ($x:expr) => {{
        let v = $x;
        v * v
    }};
}

macro_rules! nouvelle_map {
    () => { HashMap::new() };               // échoue si l'utilisateur n'a pas importé HashMap
}

macro_rules! nouvelle_map_ok {
    () => { ::std::collections::HashMap::new() };   // fonctionne partout
}

Dans le développement d'une macro, écris des chemins complets : ::std::... pour la bibliothèque standard, $crate::... pour ta propre crate (voir macros-export).

macro_rules! avec_temp {
    ($e:expr) => {{
        let temp = 10;
        $e + temp
    }};
}

let temp = 1;
let r = avec_temp!(temp);    // 11 : le `temp` de l'appelant n'est pas celui de la macro

Une variable déclarée dans une macro ne peut pas entrer en collision avec une variable de l'appelant, même de même nom : macro_rules! est hygiénique pour les variables locales.

macro_rules! declarer_fonction {
    () => { fn aide() -> u32 { 42 } };
}

declarer_fonction!();
let x = aide();              // la fonction est visible : les éléments (fn, struct, impl) ne sont pas hygiéniques

Les noms de fonctions, de types, de modules et de traits générés par une macro sont visibles normalement. Les chemins dans le développement sont résolus à l'endroit de l'appel, d'où la règle des chemins absolus (section 10.3).

macro_rules! couleur {
    (rouge) => { (255, 0, 0) };
    (vert) => { (0, 255, 0) };
    ($autre:tt) => {
        compile_error!(concat!("couleur inconnue : ", stringify!($autre)))
    };
}

let c = couleur!(rouge);
// let d = couleur!(bleu);   // ERREUR : couleur inconnue : bleu

Sans le dernier bras, l'erreur serait « no rules expected the token bleu », moins parlante.

cargo install cargo-expand
cargo expand                  # toute la crate développée
cargo expand module::chemin   # un seul module

C'est l'outil indispensable pour comprendre une erreur dans une macro : on lit le code produit, et on compile la partie fautive à la main.

const VERSION: &str = env!("CARGO_PKG_VERSION");          // version du Cargo.toml, figée à la compilation
const README: &str = include_str!("../README.md");        // le fichier est intégré au binaire

// runique/src/macros/routeur/router.rs (début)
macro_rules! urlpatterns {
    (@parse $routes:ident;) => {};

    (@parse $routes:ident;
        admin $path:expr => $handler:expr,
        name = $name:expr,
        for_model = $model:ty,
        overrides = $view:expr,
        $($rest:tt)*
    ) => {
        $routes.add_admin_route::<$model>($path, $name, $handler, $view);
        $crate::urlpatterns!(@parse $routes; $($rest)*);
    };
    // ... d'autres bras pour les autres formes de route ...
}

On y retrouve toutes les techniques de ce cours : des règles internes @parse, un cas d'arrêt ((@parse $routes:ident;) => {}), la capture de la suite avec $($rest:tt)*, l'appel récursif, des bras spécifiques (qui commencent par le mot admin) placés avant les bras généraux, et $crate:: pour que l'appel récursif fonctionne depuis la crate de l'utilisateur.

// runique/src/macros/context/impl_error.rs
#[macro_export]
macro_rules! impl_from_error {
    ($($err:ty => $method:ident),*) => {
        $(
            impl From<$err> for AppError {
                fn from(err: $err) -> Self { Self { context: ErrorContext::$method(&err) } }
            }
            impl From<$err> for Box<AppError> {
                fn from(err: $err) -> Self { Box::new(AppError::from(err)) }
            }
        )*
    };
}

impl_from_error!(
    anyhow::Error => from_anyhow,
    DbErr => database,
    tower_sessions::session::Error => database
);

Une répétition avec deux variables ($err et $method), qui génère deux impl par entrée : trois lignes d'appel remplacent six blocs impl.

use std::collections::HashMap;
use std::hash::Hash;

// 1. Fonction générique : lisible, autocomplétée, déboguable
fn map_de<K: Hash + Eq, V, const N: usize>(paires: [(K, V); N]) -> HashMap<K, V> {
    HashMap::from(paires)
}

// 2. Bibliothèque standard : rien à écrire
let a = HashMap::from([("un", 1), ("deux", 2)]);

// 3. Macro : syntaxe plus légère, rien de plus
macro_rules! map {
    ($($k:expr => $v:expr),* $(,)?) => {
        ::std::collections::HashMap::from([$(($k, $v)),*])
    };
}
let b = map! { "un" => 1, "deux" => 2 };
let c = map_de([("un", 1)]);

macro_rules! nom {
    () => { .. };                                   // sans argument
    ($x:expr) => { .. };                            // une expression
    ($a:ident, $t:ty) => { .. };                    // identifiant, type
    ($($x:expr),* $(,)?) => { $( f($x); )* };       // répétition, virgule finale facultative
    ($($k:expr => $v:expr),*) => { .. };            // paires
    (@interne $acc:expr; $($reste:tt)*) => { .. };  // règle interne + tt muncher
    ($x:tt) => { compile_error!("..") };            // dernier recours : erreur claire
}