Macros procédurales — Attribute

use proc_macro::TokenStream;

#[proc_macro_attribute]
pub fn mon_attribut(attr: TokenStream, item: TokenStream) -> TokenStream {
    // attr : ce qui est entre les parenthèses de #[mon_attribut(...)]
    // item : l'élément annoté, complet
    item                // renvoyer item tel quel = l'attribut ne change rien
}

#[mon_attribut(niveau = "debug", repetitions = 3)]
fn calcul() {}
// attr = niveau = "debug", repetitions = 3
// item = fn calcul() {}

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

#[proc_macro_attribute]
pub fn chrono(_attr: TokenStream, item: TokenStream) -> TokenStream {
    let fonction = parse_macro_input!(item as ItemFn);

    let attrs = &fonction.attrs;          // #[inline], ///doc... : à conserver
    let vis = &fonction.vis;
    let sig = &fonction.sig;              // nom, paramètres, retour, async, génériques
    let corps = &fonction.block;
    let nom = sig.ident.to_string();

    quote! {
        #(#attrs)*
        #vis #sig {
            let __debut = ::std::time::Instant::now();
            let __resultat = (|| #corps)();
            ::std::eprintln!("{} : {:?}", #nom, __debut.elapsed());
            __resultat
        }
    }
    .into()
}

#[chrono]
fn calcul(n: u64) -> u64 {
    (0..n).sum()
}

fn main() {
    calcul(1_000_000);        // calcul : 1.2ms
}

#[proc_macro_attribute]
pub fn sans_argument(attr: TokenStream, item: TokenStream) -> TokenStream {
    if !attr.is_empty() {
        return syn::Error::new(proc_macro2::Span::call_site(), "#[sans_argument] ne prend pas d'argument")
            .to_compile_error()
            .into();
    }
    item
}

use syn::{parse::Parser, punctuated::Punctuated, Expr, Lit, Meta, Token};

struct Options { niveau: String, repetitions: u32, silencieux: bool }

fn lire_options(attr: TokenStream) -> syn::Result<Options> {
    let mut o = Options { niveau: "info".into(), repetitions: 1, silencieux: false };
    let liste = Punctuated::<Meta, Token![,]>::parse_terminated.parse(attr)?;
    for meta in liste {
        match meta {
            Meta::NameValue(nv) if nv.path.is_ident("niveau") => {
                let Expr::Lit(e) = &nv.value else {
                    return Err(syn::Error::new_spanned(&nv.value, "texte attendu"));
                };
                let Lit::Str(s) = &e.lit else {
                    return Err(syn::Error::new_spanned(&e.lit, "texte attendu"));
                };
                o.niveau = s.value();
            }
            Meta::NameValue(nv) if nv.path.is_ident("repetitions") => {
                let Expr::Lit(syn::ExprLit { lit: Lit::Int(n), .. }) = &nv.value else {
                    return Err(syn::Error::new_spanned(&nv.value, "entier attendu"));
                };
                o.repetitions = n.base10_parse()?;
            }
            Meta::Path(p) if p.is_ident("silencieux") => o.silencieux = true,
            autre => return Err(syn::Error::new_spanned(autre, "option inconnue")),
        }
    }
    Ok(o)
}

Meta couvre les trois formes : chemin (drapeau), chemin = valeur, chemin(...) (liste imbriquée).

use syn::meta;

fn lire_options_v2(attr: TokenStream) -> syn::Result<Options> {
    let mut o = Options { niveau: "info".into(), repetitions: 1, silencieux: false };
    let lecteur = meta::parser(|m| {
        if m.path.is_ident("niveau") {
            o.niveau = m.value()?.parse::<syn::LitStr>()?.value();
        } else if m.path.is_ident("repetitions") {
            o.repetitions = m.value()?.parse::<syn::LitInt>()?.base10_parse()?;
        } else if m.path.is_ident("silencieux") {
            o.silencieux = true;
        } else {
            return Err(m.error("option inconnue"));
        }
        Ok(())
    });
    syn::parse::Parser::parse(lecteur, attr)?;
    Ok(o)
}

Plus court et avec des messages d'erreur bien placés. C'est la forme recommandée par syn 2.

pub struct ItemFn {
    pub attrs: Vec<Attribute>,     // attributs restants (dont la doc)
    pub vis: Visibility,
    pub sig: Signature,            // const, async, unsafe, fn, nom, génériques, paramètres, retour
    pub block: Box<Block>,         // le corps
}

let sig = &fonction.sig;
sig.ident;                 // nom
sig.asyncness.is_some();   // async ?
sig.inputs;                // paramètres : FnArg::Receiver (self) ou FnArg::Typed (nom: Type)
sig.output;                // ReturnType::Default (()) ou ReturnType::Type(_, ty)
sig.generics;

#[proc_macro_attribute]
pub fn tracer(_attr: TokenStream, item: TokenStream) -> TokenStream {
    let mut f = parse_macro_input!(item as ItemFn);
    let nom = f.sig.ident.to_string();
    let corps = &f.block;

    // On remplace le corps par un nouveau bloc qui contient l'ancien
    let nouveau: syn::Block = syn::parse_quote!({
        ::std::eprintln!("entrée dans {}", #nom);
        #corps
    });
    f.block = Box::new(nouveau);

    quote!(#f).into()          // ItemFn s'interpole tel quel
}

Modifier l'arbre (f.block = ...) puis l'interpoler en entier garde automatiquement attributs, visibilité et signature.

#[proc_macro_attribute]
pub fn chrono_async(_attr: TokenStream, item: TokenStream) -> TokenStream {
    let mut f = parse_macro_input!(item as ItemFn);
    let nom = f.sig.ident.to_string();
    let corps = &f.block;

    let nouveau: syn::Block = if f.sig.asyncness.is_some() {
        syn::parse_quote!({
            let __debut = ::std::time::Instant::now();
            let __r = async move #corps.await;         // un bloc async garde .await et ?
            ::std::eprintln!("{} : {:?}", #nom, __debut.elapsed());
            __r
        })
    } else {
        syn::parse_quote!({
            let __debut = ::std::time::Instant::now();
            let __r = (|| #corps)();
            ::std::eprintln!("{} : {:?}", #nom, __debut.elapsed());
            __r
        })
    };
    f.block = Box::new(nouveau);
    quote!(#f).into()
}

use syn::{FnArg, Pat};

let noms: Vec<_> = f.sig.inputs.iter().filter_map(|a| match a {
    FnArg::Typed(pt) => match &*pt.pat {
        Pat::Ident(i) => Some(i.ident.clone()),
        _ => None,                                 // motif déstructuré : pas de nom simple
    },
    FnArg::Receiver(_) => None,                    // self
}).collect();

// quote! { ::std::eprintln!(concat!(#(stringify!(#noms), " = {:?} "),*), #(#noms),*); }

let f = match syn::parse::<ItemFn>(item.clone()) {
    Ok(f) => f,
    Err(_) => {
        return syn::Error::new(proc_macro2::Span::call_site(), "#[chrono] s'applique à une fonction")
            .to_compile_error()
            .into();
    }
};

use syn::{parse_macro_input, parse_quote, Fields, ItemStruct};

#[proc_macro_attribute]
pub fn horodate(_attr: TokenStream, item: TokenStream) -> TokenStream {
    let mut s = parse_macro_input!(item as ItemStruct);

    if let Fields::Named(champs) = &mut s.fields {
        champs.named.push(parse_quote! { pub cree_le: ::std::time::SystemTime });
        champs.named.push(parse_quote! { pub modifie_le: ::std::time::SystemTime });
    } else {
        return syn::Error::new_spanned(&s.ident, "#[horodate] demande des champs nommés")
            .to_compile_error()
            .into();
    }

    let nom = &s.ident;
    quote! {
        #s
        impl #nom {
            pub fn toucher(&mut self) { self.modifie_le = ::std::time::SystemTime::now(); }
        }
    }
    .into()
}

#[horodate]
struct Article { titre: String }

// devient :
// struct Article { titre: String, pub cree_le: SystemTime, pub modifie_le: SystemTime }
// impl Article { pub fn toucher(&mut self) { .. } }

Une derive ne pourrait pas ajouter de champ : c'est le cas où l'attribut est nécessaire. Le prix : l'utilisateur voit struct Article { titre } mais doit construire Article { titre, cree_le, modifie_le }. Une macro qui ajoute des champs doit donc fournir un constructeur et le documenter.

#[proc_macro_attribute]
pub fn formulaire(_attr: TokenStream, item: TokenStream) -> TokenStream {
    let s = parse_macro_input!(item as ItemStruct);
    let vis = &s.vis;
    let nom = &s.ident;
    let attrs = &s.attrs;

    if !matches!(s.fields, Fields::Unit) {
        return syn::Error::new_spanned(&s.fields, "écris `struct Nom;` : les champs sont générés")
            .to_compile_error()
            .into();
    }

    quote! {
        #(#attrs)*
        #vis struct #nom {
            pub donnees: ::std::collections::HashMap<String, String>,
            pub erreurs: Vec<String>,
        }
    }
    .into()
}

L'utilisateur écrit #[formulaire] pub struct Contact; et obtient une struct complète. C'est le modèle de #[form] dans Runique (section 10).

let messages = colonnes.iter().map(|c| {
    let texte = c.to_string();
    let msg = format!("`{texte}` est la clé primaire : elle ne peut pas être un champ de formulaire");
    quote_spanned! { c.span()=>
        assert!(!::ma_lib::meme_nom(#schema::CLE_PRIMAIRE, #texte), #msg);
    }
});

Dans un bloc const, un assert! qui échoue est une erreur de compilation avec ce message. La fonction appelée doit être une const fn.

#[a]          // s'exécute en premier, et reçoit l'élément AVEC #[b] et #[derive] dans ses attributs
#[b]          // s'exécute ensuite, sur ce que #[a] a produit
#[derive(Debug)]
struct S;

// Ce que fait #[tokio::main], en simplifié
#[tokio::main]
async fn main() { /* ... */ }

// devient
fn main() {
    tokio::runtime::Builder::new_multi_thread()
        .enable_all()
        .build()
        .unwrap()
        .block_on(async { /* ... */ })
}

#[form(schema = crate::entities::contact, fields = [email, message])]
pub struct ContactForm;

// runique/derive_form/src/schema_form.rs (extrait)
enum Columns {
    Only(Vec<Ident>),     // fields = [a, b]
    All,                  // fields = All
    Except(Vec<Ident>),   // exclude = [a, b]
}

struct FormAttrs {
    schema: Path,
    columns: Columns,
}

impl Parse for FormAttrs {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        // boucle clé = valeur : schema, fields, exclude
        // fields et exclude ensemble -> erreur ; schema absent -> erreur ;
        // ni fields ni exclude -> erreur « incomplete declaration »
        // ...
    }
}

C'est la technique de la section 4.4. Le choix de conception : fields ou exclude est obligatoire. Un formulaire qui prendrait toutes les colonnes sans le dire prendrait aussi toute colonne ajoutée plus tard au modèle (un champ is_admin, par exemple), une faille classique d'affectation de masse. fields = All reste possible, mais il faut l'écrire.

// runique/derive_form/src/schema_form.rs (extrait)
// Each name a column of the entity, checked by the compiler: the error
// lands on the name, not on a panic the first time the form is used.
let checks = fields.iter().chain(exclude.iter()).flatten().map(|field| {
    let mut variant = crate::model::utils::ident_pascal(field);
    variant.set_span(field.span());
    quote_spanned! { field.span()=> let _ = #schema_path::Column::#variant; }
});

// The key is the database's to set: listed in `fields`, refused here.
let key_checks = fields.iter().flatten().map(|field| {
    let name = field.to_string();
    let message = format!(
        "#[form]: `{name}` is the primary key; the database sets it, it is never a form field"
    );
    quote_spanned! { field.span()=>
        assert!(!::runique::forms::__same_name(#schema_path::PRIMARY_KEY, #name), #message);
    }
});

let column_check = quote! { const _: () = { #(#checks)* #(#key_checks)* }; };

On y retrouve exactement la section 7 :

• chaque nom de champ devient Column::NomEnPascal : une faute de frappe (emial) est une erreur de compilation soulignée sur emial ;
• lister la clé primaire dans fields est refusé à la compilation par une assertion const, avec un message qui explique pourquoi ;
• tout est dans un const _: () = { ... }; : rien n'est exécuté au démarrage.

// 1. À la main : explicite, mais à répéter dans chaque fonction
fn a() { eprintln!("entrée dans a"); /* ... */ }

// 2. macro_rules! : il faut envelopper toute la fonction
macro_rules! tracee {
    (fn $nom:ident() $corps:block) => {
        fn $nom() { eprintln!("entrée dans {}", stringify!($nom)); $corps }
    };
}
tracee!(fn b() { /* ... */ });

// 3. Attribut : une ligne au-dessus d'une fonction ordinaire
// #[tracer]
// fn c() { /* ... */ }

#[proc_macro_attribute]
pub fn nom(attr: TokenStream, item: TokenStream) -> TokenStream {
    let args = parse_macro_input!(attr as MesArgs);       // impl Parse for MesArgs
    let mut f = parse_macro_input!(item as ItemFn);       // ou ItemStruct, Item...
    f.block = Box::new(parse_quote!({ /* avant */ #corps }));
    quote!(#f).into()
}

Punctuated::<Meta, Token![,]>::parse_terminated.parse(attr)
syn::meta::parser(|m| { m.path.is_ident("x"); m.value()?.parse::<LitStr>()?; Ok(()) })
bracketed!(contenu in input)   contenu.parse_terminated(Ident::parse, Token![,])
quote_spanned! { ident.span()=> let _ = #chemin::#ident; }
const _: () = { /* vérifications */ };