Macros procédurales — Derive

#[derive(Debug, Clone)]
struct Point { x: i32, y: i32 }

cargo new decrire_macros --lib

# decrire_macros/Cargo.toml
[package]
name = "decrire_macros"
version = "0.1.0"
edition = "2024"

[lib]
proc-macro = true            # indispensable : fait de la crate une crate de macros

[dependencies]
syn = { version = "2", features = ["full"] }   # analyse du code Rust
quote = "1"                                    # génération de code
proc-macro2 = "1"                              # TokenStream utilisable hors de la macro (tests)

# mon_app/Cargo.toml
[dependencies]
decrire_macros = { path = "../decrire_macros" }

use decrire_macros::Decrire;

#[derive(Decrire)]
struct Utilisateur { nom: String, age: u32 }

code source ──► TokenStream ──syn──► arbre (DeriveInput) ──vous──► quote! ──► TokenStream ──► compilateur

use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, DeriveInput};

#[proc_macro_derive(Decrire)]
pub fn derive_decrire(entree: TokenStream) -> TokenStream {
    let ast = parse_macro_input!(entree as DeriveInput);   // erreur de syntaxe -> erreur de compilation
    let nom = &ast.ident;

    let code = quote! {
        impl #nom {
            pub fn decrire() -> &'static str {
                stringify!(#nom)
            }
        }
    };

    code.into()                                            // proc_macro2::TokenStream -> proc_macro::TokenStream
}

pub struct DeriveInput {
    pub attrs: Vec<Attribute>,     // #[...] posés sur le type
    pub vis: Visibility,           // pub, pub(crate)...
    pub ident: Ident,              // le nom du type
    pub generics: Generics,        // <T, 'a, const N: usize> et where
    pub data: Data,                // Struct, Enum ou Union, avec les champs
}

// decrire_macros/src/lib.rs
use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, Data, DeriveInput, Fields};

#[proc_macro_derive(Decrire)]
pub fn derive_decrire(entree: TokenStream) -> TokenStream {
    let ast = parse_macro_input!(entree as DeriveInput);
    let nom = &ast.ident;

    let Data::Struct(donnees) = &ast.data else {
        return syn::Error::new_spanned(&ast.ident, "Decrire ne s'applique qu'aux structs")
            .to_compile_error()
            .into();
    };

    let Fields::Named(champs) = &donnees.fields else {
        return syn::Error::new_spanned(&ast.ident, "Decrire demande des champs nommés")
            .to_compile_error()
            .into();
    };

    let noms: Vec<_> = champs.named.iter().map(|c| c.ident.as_ref().unwrap()).collect();

    quote! {
        impl #nom {
            pub fn decrire(&self) -> String {
                let mut parties = Vec::new();
                #(
                    parties.push(format!("{} = {:?}", stringify!(#noms), self.#noms));
                )*
                format!("{} {{ {} }}", stringify!(#nom), parties.join(", "))
            }
        }
    }
    .into()
}

// mon_app
#[derive(Decrire)]
struct Utilisateur { nom: String, age: u32 }

fn main() {
    let u = Utilisateur { nom: "Ada".into(), age: 36 };
    println!("{}", u.decrire());     // Utilisateur { nom = "Ada", age = 36 }
}

impl Utilisateur {
    pub fn decrire(&self) -> String {
        let mut parties = Vec::new();
        parties.push(format!("{} = {:?}", "nom", self.nom));
        parties.push(format!("{} = {:?}", "age", self.age));
        format!("{} {{ {} }}", "Utilisateur", parties.join(", "))
    }
}

use syn::{Data, Fields};

fn decrire_forme(data: &Data) -> &'static str {
    match data {
        Data::Struct(s) => match &s.fields {
            Fields::Named(_) => "struct à champs nommés",      // struct S { a: i32 }
            Fields::Unnamed(_) => "tuple struct",              // struct S(i32, String);
            Fields::Unit => "unit struct",                     // struct S;
        },
        Data::Enum(_) => "enum",
        Data::Union(_) => "union",
    }
}

pub struct Field {
    pub attrs: Vec<Attribute>,     // #[...] sur le champ
    pub vis: Visibility,
    pub ident: Option<Ident>,      // None pour un champ de tuple
    pub ty: Type,                  // le type du champ
    // ...
}

use syn::Index;

let indices: Vec<Index> = (0..champs.unnamed.len()).map(Index::from).collect();
// quote! { #( self.#indices ),* }     ->   self.0, self.1, self.2

Un usize interpolé donnerait 0usize ; syn::Index donne 0, la forme correcte après un point.

use syn::{Type, TypePath};

fn est_option(ty: &Type) -> bool {
    matches!(ty, Type::Path(TypePath { path, .. })
        if path.segments.last().is_some_and(|s| s.ident == "Option"))
}

Une macro ne voit que la syntaxe : elle sait qu'un champ s'écrit Option<String>, pas ce que ce type est réellement. Un alias (type MaybeName = Option<String>) ou un chemin complet (std::option::Option) ne sont reconnus que si on les gère explicitement.

let nom = &ast.ident;            // Ident
let ty: syn::Type = syn::parse_quote!(u32);
let n = 42usize;
let texte = "bonjour";

let code = quote! {
    const N: usize = #n;         // 42usize
    fn f() -> #ty { 0 }          // fn f() -> u32
    fn g() -> &'static str { #texte }    // "bonjour" (un littéral de chaîne)
    impl #nom {}
};

Tout type qui implémente ToTokens s'interpole : Ident, Type, Expr, TokenStream, entiers, &str, bool...

let noms = vec![quote!(a), quote!(b), quote!(c)];
let types = vec![quote!(i32), quote!(String), quote!(bool)];

quote! {
    struct S { #( #noms: #types ),* }        // a: i32, b: String, c: bool
};

quote! {
    #( println!("{}", stringify!(#noms)); )*   // une ligne par élément, sans séparateur
};

#( ... ),* répète avec un séparateur, #( ... )* sans. Toutes les variables d'une même répétition doivent avoir la même longueur.

use quote::format_ident;

let champ = format_ident!("email");
let getter = format_ident!("get_{}", champ);        // get_email
let setter = format_ident!("set_{}", champ);        // set_email

quote! {
    pub fn #getter(&self) -> &str { &self.#champ }
    pub fn #setter(&mut self, v: String) { self.#champ = v; }
};

C'est ce que macro_rules! ne sait pas faire.

let mut methodes = proc_macro2::TokenStream::new();
for c in champs.named.iter() {
    let nom = c.ident.as_ref().unwrap();
    let ty = &c.ty;
    methodes.extend(quote! {
        pub fn #nom(&self) -> &#ty { &self.#nom }
    });
}

quote! {
    impl #nom_type { #methodes }
};

#[derive(Decrire)]
struct Boite<T> { valeur: T }

// Un impl écrit comme `impl #nom { ... }` donne `impl Boite { ... }` : ERREUR, Boite attend un T

let (impl_generics, ty_generics, where_clause) = ast.generics.split_for_impl();

quote! {
    impl #impl_generics #nom #ty_generics #where_clause {
        // ...
    }
}
// impl<T> Boite<T> { ... }
// impl<'a, T: Clone, const N: usize> S<'a, T, N> where T: Debug { ... }

split_for_impl sépare correctement durées de vie, paramètres de type, const generics et clause where.

use syn::{Data, Fields};

#[proc_macro_derive(NomVariante)]
pub fn derive_nom_variante(entree: TokenStream) -> TokenStream {
    let ast = parse_macro_input!(entree as DeriveInput);
    let nom = &ast.ident;

    let Data::Enum(e) = &ast.data else {
        return syn::Error::new_spanned(nom, "NomVariante ne s'applique qu'aux enums")
            .to_compile_error()
            .into();
    };

    let bras = e.variants.iter().map(|v| {
        let variante = &v.ident;
        let texte = variante.to_string();
        let motif = match &v.fields {
            Fields::Unit => quote!(Self::#variante),
            Fields::Unnamed(_) => quote!(Self::#variante(..)),
            Fields::Named(_) => quote!(Self::#variante { .. }),
        };
        quote!(#motif => #texte)
    });

    let (ig, tg, wc) = ast.generics.split_for_impl();
    quote! {
        impl #ig #nom #tg #wc {
            pub fn nom_variante(&self) -> &'static str {
                match self { #(#bras),* }
            }
        }
    }
    .into()
}

#[derive(NomVariante)]
enum Message { Quitter, Ecrire(String), Deplacer { x: i32, y: i32 } }

Message::Ecrire("a".into()).nom_variante();    // "Ecrire"

#[proc_macro_derive(Decrire, attributes(decrire))]
pub fn derive_decrire(entree: TokenStream) -> TokenStream { /* ... */ }

attributes(decrire) autorise l'utilisateur à écrire #[decrire(...)] sur le type et sur ses champs. Sans cette déclaration, le compilateur refuserait l'attribut inconnu.

#[derive(Decrire)]
#[decrire(nom = "Compte")]
struct Utilisateur {
    nom: String,
    #[decrire(cache)]
    mot_de_passe: String,
    #[decrire(renommer = "âge")]
    age: u32,
}

struct OptionsChamp {
    cache: bool,
    renommer: Option<String>,
}

fn lire_options(champ: &syn::Field) -> syn::Result<OptionsChamp> {
    let mut opts = OptionsChamp { cache: false, renommer: None };
    for attr in &champ.attrs {
        if !attr.path().is_ident("decrire") {
            continue;                                  // un autre attribut (serde, doc...) : ignoré
        }
        attr.parse_nested_meta(|meta| {
            if meta.path.is_ident("cache") {
                opts.cache = true;                     // #[decrire(cache)]
                Ok(())
            } else if meta.path.is_ident("renommer") {
                let valeur: syn::LitStr = meta.value()?.parse()?;   // #[decrire(renommer = "...")]
                opts.renommer = Some(valeur.value());
                Ok(())
            } else {
                Err(meta.error("option inconnue : attendu `cache` ou `renommer = \"...\"`"))
            }
        })?;
    }
    Ok(opts)
}

let mut lignes = Vec::new();
for c in champs.named.iter() {
    let opts = match lire_options(c) {
        Ok(o) => o,
        Err(e) => return e.to_compile_error().into(),
    };
    if opts.cache {
        continue;                                      // le mot de passe n'apparaît jamais
    }
    let ident = c.ident.as_ref().unwrap();
    let libelle = opts.renommer.unwrap_or_else(|| ident.to_string());
    lignes.push(quote! {
        parties.push(format!("{} = {:?}", #libelle, self.#ident));
    });
}

Un attribut cache qui retire un champ secret de l'affichage est un bon exemple d'usage : c'est le genre d'erreur qu'un #[derive(Debug)] ordinaire ne sait pas éviter.

// Mauvais : l'utilisateur voit « proc-macro derive panicked » sans position
let champs = match &ast.data { Data::Struct(s) => &s.fields, _ => panic!("struct attendue") };

// Bon : une erreur de compilation, soulignée au bon endroit
let Data::Struct(s) = &ast.data else {
    return syn::Error::new_spanned(&ast.ident, "struct attendue").to_compile_error().into();
};

let mut erreurs: Option<syn::Error> = None;
for c in champs.named.iter() {
    if let Err(e) = lire_options(c) {
        match &mut erreurs {
            Some(tout) => tout.combine(e),            // accumuler
            None => erreurs = Some(e),
        }
    }
}
if let Some(e) = erreurs {
    return e.to_compile_error().into();               // toutes les erreurs en une compilation
}

#[proc_macro_derive(Decrire, attributes(decrire))]
pub fn derive_decrire(entree: TokenStream) -> TokenStream {
    let ast = parse_macro_input!(entree as DeriveInput);
    generer(&ast).unwrap_or_else(|e| e.to_compile_error()).into()
}

fn generer(ast: &DeriveInput) -> syn::Result<proc_macro2::TokenStream> {
    // ... ? partout ...
    Ok(quote! {})
}

Le point d'entrée ne fait que convertir ; tout le travail est dans une fonction qui utilise ?.

// Mauvais : dépend des imports de l'utilisateur
quote! { impl Display for #nom { fn fmt(&self, f: &mut Formatter) -> Result { .. } } };

// Bon : chemins absolus
quote! {
    impl ::std::fmt::Display for #nom {
        fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result { /* .. */ Ok(()) }
    }
};

// mon_app/tests/decrire.rs (ou dans la crate qui réexporte la macro)
use decrire_macros::Decrire;

#[derive(Decrire)]
struct Point { x: i32, y: i32 }

#[test]
fn decrit_les_champs() {
    assert_eq!(Point { x: 1, y: 2 }.decrire(), "Point { x = 1, y = 2 }");
}

Une crate proc-macro ne peut pas utiliser ses propres macros dans ses tests unitaires : on les teste depuis une autre crate (tests d'intégration de la bibliothèque qui la réexporte, ou un dossier d'exemples).

// tests/erreurs.rs
#[test]
fn erreurs_de_compilation() {
    let t = trybuild::TestCases::new();
    t.compile_fail("tests/ui/*.rs");      // chaque fichier doit échouer avec le message du .stderr voisin
    t.pass("tests/ok/*.rs");
}

trybuild compile des petits fichiers et compare le message d'erreur obtenu à un fichier .stderr attendu : on vérifie ainsi que l'utilisateur reçoit le bon message, au bon endroit.

ma_lib/            ← la bibliothèque : types, traits, fonctions ; réexporte les macros
ma_lib_macros/     ← proc-macro = true : seulement les macros
ma_lib_dsl/        ← (facultatif) l'analyseur, dans une crate normale, réutilisable ailleurs

// ma_lib/src/lib.rs
pub trait Decrire { fn decrire(&self) -> String; }   // le trait vit ici
pub use ma_lib_macros::Decrire;                      // la macro derive de même nom aussi

runique/runique_dsl/   ← analyseur du DSL model!{} / extend!{} -> arbre (crate normale)
runique/derive_form/   ← proc-macro = true : model!{}, extend!{}, #[form]
runique/               ← le framework ; réexporte les macros (use runique::prelude::*)

# runique/derive_form/Cargo.toml (extrait)
[lib]
proc-macro = true

[dependencies]
runique_dsl.workspace = true
syn = { workspace = true, features = ["extra-traits"] }
quote = "1"
proc-macro2 = "1"

// 1. À la main : rien à apprendre, mais répétitif
struct A { nom: String, age: u32 }
impl A {
    fn nom(&self) -> &String { &self.nom }
    fn age(&self) -> &u32 { &self.age }
}

// 2. macro_rules! : il faut répéter la liste des champs à l'appel
macro_rules! getters {
    ($t:ident { $($c:ident : $ty:ty),* }) => {
        impl $t { $( fn $c(&self) -> &$ty { &self.$c } )* }
    };
}
struct B { nom: String, age: u32 }
getters!(B { nom: String, age: u32 });

// 3. Derive : la macro lit les champs elle-même
// #[derive(Getters)]
// struct C { nom: String, age: u32 }

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

#[proc_macro_derive(Nom, attributes(nom))]
pub fn f(input: TokenStream) -> TokenStream {
    let ast = parse_macro_input!(input as DeriveInput);
    let nom = &ast.ident;
    let (ig, tg, wc) = ast.generics.split_for_impl();
    quote! { impl #ig ::ma_lib::Trait for #nom #tg #wc { .. } }.into()
}

Data::Struct(s) / Data::Enum(e)       Fields::Named / Unnamed / Unit
#var   #( #a: #b ),*   #( .. )*        format_ident!("get_{}", x)   syn::Index::from(i)
attr.path().is_ident("nom")           attr.parse_nested_meta(|meta| ..)
syn::Error::new_spanned(&noeud, "..").to_compile_error()      e.combine(autre)