Macros procédurales — Function-like

use proc_macro::TokenStream;

#[proc_macro]
pub fn ma_macro(entree: TokenStream) -> TokenStream {
    // entree : tout ce qui est entre les délimiteurs de ma_macro!( ... ) / [ ... ] / { ... }
    entree
}

ma_macro!(a + b);
ma_macro! { config { port: 8080 } }

// Exemple de syntaxe visée
config! {
    serveur {
        port: 8080,
        hote: "0.0.0.0",
    }
    base {
        url: "postgres://localhost/app",
        connexions: 10,
    }
}

use syn::parse::{Parse, ParseStream};
use syn::{Ident, LitInt, Token};

// port: 8080
struct Reglage {
    nom: Ident,
    valeur: LitInt,
}

impl Parse for Reglage {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let nom: Ident = input.parse()?;        // consomme un identifiant
        input.parse::<Token![:]>()?;            // consomme ':'
        let valeur: LitInt = input.parse()?;    // consomme un entier
        Ok(Reglage { nom, valeur })
    }
}

Chaque input.parse() consomme des jetons et renvoie une erreur positionnée si ce n'est pas ce qui est attendu.

mod kw {
    syn::custom_keyword!(table);
    syn::custom_keyword!(champs);
}

// table: "utilisateurs"
struct Table { nom: syn::LitStr }

impl Parse for Table {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        input.parse::<kw::table>()?;           // le mot `table`, et rien d'autre
        input.parse::<Token![:]>()?;
        Ok(Table { nom: input.parse()? })
    }
}

use syn::{LitBool, LitInt, LitStr};

enum Valeur {
    Texte(LitStr),
    Entier(LitInt),
    Booleen(LitBool),
}

impl Parse for Valeur {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let l = input.lookahead1();
        if l.peek(LitStr) {
            Ok(Valeur::Texte(input.parse()?))
        } else if l.peek(LitInt) {
            Ok(Valeur::Entier(input.parse()?))
        } else if l.peek(LitBool) {
            Ok(Valeur::Booleen(input.parse()?))
        } else {
            Err(l.error())                     // « expected string literal, integer literal or boolean literal »
        }
    }
}

lookahead1 mémorise tout ce qui a été testé et construit le message d'erreur automatiquement.

use syn::{braced, punctuated::Punctuated};

// serveur { port: 8080, hote: "0.0.0.0", }
struct Section {
    nom: Ident,
    reglages: Vec<(Ident, Valeur)>,
}

impl Parse for Section {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let nom: Ident = input.parse()?;
        let contenu;
        braced!(contenu in input);             // tout ce qui est entre { } devient un nouveau flux
        let liste = Punctuated::<Paire, Token![,]>::parse_terminated(&contenu)?;
        Ok(Section { nom, reglages: liste.into_iter().map(|p| (p.nom, p.valeur)).collect() })
    }
}

struct Paire { nom: Ident, valeur: Valeur }

impl Parse for Paire {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let nom = input.parse()?;
        input.parse::<Token![:]>()?;
        Ok(Paire { nom, valeur: input.parse()? })
    }
}

struct Config { sections: Vec<Section> }

impl Parse for Config {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let mut sections = Vec::new();
        while !input.is_empty() {
            sections.push(input.parse()?);
        }
        Ok(Config { sections })
    }
}

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

#[proc_macro]
pub fn requete(entree: TokenStream) -> TokenStream {
    let texte = parse_macro_input!(entree as LitStr);
    let sql = texte.value();
    let majuscules = sql.trim_start().to_uppercase();

    if !majuscules.starts_with("SELECT") {
        return syn::Error::new(texte.span(), "requete! n'accepte que des SELECT")
            .to_compile_error()
            .into();
    }
    if sql.contains(';') {
        return syn::Error::new(texte.span(), "une seule instruction, sans `;`")
            .to_compile_error()
            .into();
    }

    quote!(#texte).into()                      // le texte, désormais vérifié
}

let q = requete!("SELECT id, email FROM utilisateurs WHERE id = $1");
// let r = requete!("DELETE FROM utilisateurs");   // ERREUR à la compilation, soulignée sur le texte

#[proc_macro]
pub fn config(entree: TokenStream) -> TokenStream {
    let cfg = parse_macro_input!(entree as Config);

    let structs = cfg.sections.iter().map(|s| {
        let nom_struct = quote::format_ident!("{}", majuscule(&s.nom.to_string()));
        let champs = s.reglages.iter().map(|(n, v)| {
            let ty = match v {
                Valeur::Texte(_) => quote!(&'static str),
                Valeur::Entier(_) => quote!(i64),
                Valeur::Booleen(_) => quote!(bool),
            };
            quote!(pub #n: #ty)
        });
        let valeurs = s.reglages.iter().map(|(n, v)| {
            let lit = match v {
                Valeur::Texte(l) => quote!(#l),
                Valeur::Entier(l) => quote!(#l),
                Valeur::Booleen(l) => quote!(#l),
            };
            quote!(#n: #lit)
        });
        quote! {
            #[derive(Debug, Clone)]
            pub struct #nom_struct { #(#champs),* }
            impl #nom_struct {
                pub const fn defaut() -> Self { Self { #(#valeurs),* } }
            }
        }
    });

    quote!(#(#structs)*).into()
}

fn majuscule(s: &str) -> String {
    let mut c = s.chars();
    c.next().map(|p| p.to_uppercase().collect::<String>() + c.as_str()).unwrap_or_default()
}

config! {
    serveur { port: 8080, hote: "0.0.0.0" }
    base { connexions: 10, ssl: true }
}

const SERVEUR: Serveur = Serveur::defaut();     // Serveur { port: 8080, hote: "0.0.0.0" }

// nom: type [option1, option2]     les crochets sont facultatifs
struct Champ {
    nom: Ident,
    ty: Ident,
    options: Vec<Ident>,
}

impl Parse for Champ {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let nom = input.parse()?;
        input.parse::<Token![:]>()?;
        let ty = input.parse()?;
        let options = if input.peek(syn::token::Bracket) {        // crochets présents ?
            let contenu;
            syn::bracketed!(contenu in input);
            Punctuated::<Ident, Token![,]>::parse_terminated(&contenu)?.into_iter().collect()
        } else {
            Vec::new()
        };
        Ok(Champ { nom, ty, options })
    }
}

struct Meta { table: Option<syn::LitStr>, ordre: Option<syn::LitStr> }

impl Parse for Meta {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let mut m = Meta { table: None, ordre: None };
        while !input.is_empty() {
            let cle: Ident = input.parse()?;
            input.parse::<Token![:]>()?;
            let valeur: syn::LitStr = input.parse()?;
            let emplacement = match cle.to_string().as_str() {
                "table" => &mut m.table,
                "ordre" => &mut m.ordre,
                _ => return Err(syn::Error::new(cle.span(), "clé inconnue : `table` ou `ordre`")),
            };
            if emplacement.replace(valeur).is_some() {
                return Err(syn::Error::new(cle.span(), format!("`{cle}` est déjà défini")));
            }
            if input.peek(Token![,]) {
                input.parse::<Token![,]>()?;
            }
        }
        Ok(m)
    }
}

Option::replace renvoie l'ancienne valeur : si elle existait, la clé est en double.

#[test]
fn refuse_une_cle_en_double() {
    let r: syn::Result<Meta> = syn::parse_str(r#"table: "a", table: "b""#);
    assert!(r.is_err());
}

syn::parse_str et syn::parse2 permettent de tester Parse comme du code ordinaire, si l'analyseur vit dans une crate normale (section 10).

let x = ma_macro!(...);       // doit produire une expression
ma_macro! { ... }             // en position d'élément : peut produire des déclarations

Une macro conçue pour les deux usages ne marche que dans l'un : décide lequel, et documente-le.

// demo-app/src/entities/chapitre.rs
model! {
    Chapitre,
    table: "chapitre",
    pk: id => Pk,
    {
        cour_id:    Pk [required],
        slug:       text [required],
        title:      text [required],
        lead:       text [nullable],
        sort_order: int [required],
    },
    relations: {
        belongs_to: Cour via cour_id [cascade],
    }
}

On y retrouve les techniques de ce cours : un mot-clé suivi de : (table:, pk:, relations:), un groupe { ... } de champs, des listes facultatives entre crochets ([required], [cascade]), des mots-clés personnels (via, belongs_to).

model! { ... }
   │  jetons
   ▼
runique_dsl      analyse le DSL → arbre (AST)          crate normale
   │
   ├──► derive_form   génère l'entité SeaORM, les colonnes, le formulaire   (proc-macro)
   │
   └──► runique (CLI) makemigrations : compare l'arbre au schéma et écrit les migrations

L'analyseur est dans runique_dsl, une crate ordinaire : une crate proc-macro ne peut rien exporter d'autre que des macros, et la commande runique makemigrations doit lire exactement les mêmes déclarations que la macro. Le même impl Parse sert donc à la compilation (génération du code) et à la CLI (génération des migrations SQL).

Autre avantage : l'analyseur se teste comme du code ordinaire (section 7.4). runique_dsl a des tests de propriétés (proptest) qui lui envoient des entrées générées : il doit répondre par un arbre ou une erreur, jamais paniquer.

// runique/derive_form/src/lib.rs (extrait)
#[proc_macro]
pub fn extend(input: TokenStream) -> TokenStream {
    const FRAMEWORK_TABLES: &[&str] = &["eihwaz_users", "eihwaz_groupes"];

    let dsl = match syn::parse::<extend_schema::ExtendDsl>(input) {
        Ok(d) => d,
        Err(e) => return e.to_compile_error().into(),
    };

    if !FRAMEWORK_TABLES.contains(&dsl.table.as_str()) {
        let tables_list = FRAMEWORK_TABLES.join(", ");
        let msg = format!(
            "extend!{{}}: \"{}\" is not a known framework table. Allowed: {}",
            dsl.table, tables_list
        );
        return quote::quote! { compile_error!(#msg); }.into();
    }
    // ...
}

extend!{} ajoute des colonnes aux tables du framework. Une table inconnue est refusée à la compilation, avec la liste des tables autorisées : la faute de frappe ne peut pas atteindre une migration.

// runique/derive_form/src/lib.rs (début)
#[cfg(all(not(doc), not(feature = "all-databases"), feature = "postgres", feature = "mysql"))]
compile_error!("features `postgres` and `mysql` are mutually exclusive");

La crate de macros reçoit les mêmes features que runique (transmises par runique/Cargo.toml : postgres = [..., "derive_form/postgres"]). Elle connaît ainsi le moteur de base à la compilation et applique les mêmes règles d'exclusion (voir cargo-dependances, section 9).

L'ancien mécanisme lisait le moteur dans .env (DB_ENGINE, DATABASE_URL) pendant la compilation, avec exactement les défauts de la section 9.1 : un .env modifié ne déclenchait pas de recompilation, et un fichier oublié pouvait désigner un autre moteur que celui réellement compilé. Il reste en repli, seulement pour les projets dont le Cargo.toml ne transmet pas encore la feature (runique/derive_form/src/model/utils/db_engine.rs) ; la feature, elle, ne peut pas diverger de ce qui est compilé.

#[proc_macro]
pub fn nom(entree: TokenStream) -> TokenStream {
    let dsl = parse_macro_input!(entree as MonDsl);   // impl Parse for MonDsl
    generer(&dsl).unwrap_or_else(|e| e.to_compile_error()).into()
}

input.parse::<Ident>()?        input.parse::<Token![:]>()?      input.parse::<LitStr>()?
syn::custom_keyword!(table);   input.parse::<kw::table>()?
input.peek(Token![,])          input.peek(syn::token::Bracket)  input.is_empty()
let l = input.lookahead1(); if l.peek(LitStr) { .. } else { Err(l.error()) }
let c; braced!(c in input);    bracketed!   parenthesized!
Punctuated::<T, Token![,]>::parse_terminated(&c)?
syn::Error::new(lit.span(), "..")   syn::parse_str::<T>("..")   format_ident!("{}", x)