Macros — Visibilité et export

// avant!();                    // ERREUR : la macro n'est pas encore déclarée

macro_rules! avant {
    () => { 1 };
}

fn f() -> i32 { avant!() }      // OK : après la déclaration

mod enfant {
    pub fn g() -> i32 { avant!() }   // OK : module déclaré après la macro
}

// src/lib.rs
#[macro_use]
mod macros;        // définit les macros (voir section 2.1)
mod formulaires;   // peut les utiliser
mod vues;          // aussi

// src/lib.rs
#[macro_use]
mod macros;                     // les macros de ce module restent visibles après lui
mod utilisateurs;

// src/macros.rs
macro_rules! verifier {
    ($c:expr) => { assert!($c) };
}

// src/utilisateurs.rs
pub fn creer() {
    verifier!(true);            // visible grâce au #[macro_use] et à l'ordre des mod
}

// src/macros.rs
macro_rules! verifier {
    ($c:expr) => { assert!($c) };
}
pub(crate) use verifier;        // la macro devient un élément ordinaire du module

// src/utilisateurs.rs
use crate::macros::verifier;    // import explicite, comme une fonction

pub fn creer() {
    verifier!(true);
}

pub(crate) use nom_de_macro; juste après la définition transforme la macro en élément importable par son chemin. L'ordre des mod n'a alors plus d'importance, et l'éditeur sait d'où vient la macro.

// Dans la crate `ma_lib`, n'importe quel fichier
#[macro_export]
macro_rules! dire {
    ($msg:expr) => { println!("ma_lib : {}", $msg) };
}

// Dans une crate qui dépend de ma_lib
use ma_lib::dire;              // depuis la racine, jamais ma_lib::module::dire

fn main() {
    dire!("bonjour");
    ma_lib::dire!("aussi possible sans use");
}

// Dans ma_lib
pub fn journal(msg: &str) { println!("{msg}"); }

#[macro_export]
macro_rules! log_mauvais {
    ($m:expr) => { journal($m) };     // résolu à l'endroit de l'APPEL, chez l'utilisateur
}

Chez l'utilisateur, journal n'existe pas (ou désigne autre chose) : la macro casse. Écrire ma_lib::journal ne suffit pas non plus : l'utilisateur peut avoir renommé la dépendance (ma_lib2 = { package = "ma_lib" }), et dans ma_lib elle-même, ma_lib:: ne désigne rien.

#[macro_export]
macro_rules! log {
    ($m:expr) => { $crate::journal($m) };
}

$crate est remplacé par le chemin de la crate qui définit la macro, quel que soit l'endroit d'où elle est appelée et le nom sous lequel elle est importée. C'est la seule façon fiable de désigner les éléments de sa propre crate dans une macro exportée.

#[macro_export]
macro_rules! nouvelle_table {
    ($($k:expr => $v:expr),*) => {{
        let mut m = ::std::collections::HashMap::new();   // std : chemin absolu ::std
        $( m.insert($k, $v); )*
        $crate::Table::from(m)                             // propre crate : $crate
    }};
}

Le dernier point est un piège fréquent : x.methode() dans le développement ne marche que si l'utilisateur a importé le trait. $crate::MonTrait::methode(&x) marche toujours.

// Dans ma_lib (qui dépend de serde_json)
#[doc(hidden)]
pub use serde_json as __serde_json;      // réexport caché

#[macro_export]
macro_rules! json_de {
    ($v:expr) => { $crate::__serde_json::to_string(&$v) };
}

pub struct Routes { /* ... */ }

impl Routes {
    #[doc(hidden)]
    pub fn new() -> Self { Routes { /* ... */ } }         // appelée par la macro

    #[doc(hidden)]
    pub fn ajouter(&mut self, chemin: &str) { /* ... */ }  // appelée par la macro
}

#[macro_export]
macro_rules! routes {
    ($($chemin:literal),* $(,)?) => {{
        let mut r = $crate::Routes::new();
        $( r.ajouter($chemin); )*
        r
    }};
}

// src/macros/mod.rs
#[macro_export]
macro_rules! ma_macro { () => {} }

// src/lib.rs
pub mod macros;
// pub use macros::ma_macro;      // inutile : #[macro_export] la met déjà à la racine

Une macro #[macro_export] est déjà à la racine. On peut l'ajouter à un prélude :

// src/prelude.rs
pub use crate::ma_macro;

#[macro_use]
extern crate serde_derive;

// Ancien
#[macro_use]
extern crate ma_lib;
fn main() { dire!("x"); }

// Moderne : un use explicite
use ma_lib::dire;
fn main() { dire!("x"); }

/// Crée une `HashMap` à partir de paires `clé => valeur`.
///
/// # Exemple
///
/// ```
/// let m = ma_lib::table! { "a" => 1, "b" => 2 };
/// assert_eq!(m["a"], 1);
/// ```
#[macro_export]
macro_rules! table {
    ($($k:expr => $v:expr),* $(,)?) => {
        ::std::collections::HashMap::from([$(($k, $v)),*])
    };
}

Le commentaire /// se place au-dessus de #[macro_export]. L'exemple est exécuté par cargo test comme un test de documentation, depuis une crate externe : il vérifie exactement ce que verra l'utilisateur (chemins par $crate, imports nécessaires).

/// ```compile_fail
/// let x = ma_lib::table!(1, 2);     // syntaxe sans => : doit être refusée
/// ```

// runique/src/macros/routeur/router.rs
#[macro_export]
macro_rules! urlpatterns {
    // ...
    (@parse $routes:ident; admin $path:expr => $handler:expr, /* ... */ $($rest:tt)*) => {
        $routes.add_admin_route::<$model>($path, $name, $handler, $view);
        $crate::urlpatterns!(@parse $routes; $($rest)*);      // récursion par $crate
    };
}

// runique/src/macros/routeur/routes.rs
impl Routes {
    /// Used by `urlpatterns!`; construct route sets through the macro.
    #[doc(hidden)]
    pub fn new() -> Self { /* ... */ }

    /// Used by `urlpatterns!` to add an ordinary route.
    #[doc(hidden)]
    pub fn add_route(&mut self, path: impl AsRef<str>, handler: MethodRouter) { /* ... */ }
}

La macro est exportée à la racine (runique::urlpatterns!), s'appelle elle-même par $crate::, et utilise des méthodes publiques mais cachées de la documentation, que l'utilisateur n'est pas censé appeler directement.

// runique/src/macros/bdd/filter.rs
#[macro_export]
#[doc(hidden)]
macro_rules! search_apply_op { /* eq, icontains, gte... */ }

search! traduit des opérateurs (eq, icontains, gte...) en conditions SeaORM par l'intermédiaire de cette macro d'aide, exportée (pour être appelable depuis le code développé chez l'utilisateur) mais cachée.

// runique/src/lib.rs
pub use derive_form::{extend, model};

pub mod prelude {
    pub use derive_form::{extend, form, model};
    // ...
}

model!{}, extend!{} et #[form] vivent dans la crate derive_form (une crate proc-macro). L'utilisateur ne déclare que runique et les reçoit par use runique::prelude::*.

// runique/src/lib.rs
// In the crate's own tests, `::runique::…` (what `model!{}` and `extend!{}`
// generate) names the crate itself.
#[cfg(test)]
extern crate self as runique;

Le code généré par model!{} contient des chemins ::runique::.... Chez l'utilisateur, runique est une dépendance : tout va bien. Dans les tests du framework lui-même, cette ligne donne à la crate le nom runique, pour que le même code généré compile (section 7.3).

macro_rules! m { .. }                // visible après sa déclaration, dans le module et les suivants
#[macro_use] mod macros;             // garder les macros visibles après le module
pub(crate) use m;                    // importer par chemin dans la crate : use crate::macros::m;
#[macro_export] macro_rules! m { .. } // racine de la crate, pour tout le monde : use ma_lib::m;
$crate::Element                      // chemin vers sa propre crate dans le développement
::std::collections::HashMap          // std en chemin absolu
$crate::Trait::methode(&x)           // méthode de trait sans import chez l'utilisateur
#[doc(hidden)] pub use dep as __dep; // dépendance utilisée par la macro
#[doc(hidden)] pub fn aide() {}      // aide publique, cachée de la doc
pub use ma_lib_macros::MonDerive;    // réexporter une macro procédurale
#[cfg(test)] extern crate self as ma_lib;   // ::ma_lib:: dans ses propres tests