示例宏

^语法
MacroRulesDefinition :
   macro_rules ! 标识符 MacroRulesDef

MacroRulesDef :
      ( MacroRules ) ;
   | [ MacroRules ] ;
   | { MacroRules }

MacroRules :
   MacroRule ( ; MacroRule )^* ;^?

MacroRule :
   MacroMatcher => MacroTranscriber

MacroMatcher :
      ( MacroMatch^* )
   | [ MacroMatch^* ]
   | { MacroMatch^* }

MacroMatch :
      Token_{除了 $ 和 分隔符 之外}
   | MacroMatcher
   | $ ( IDENTIFIER_OR_KEYWORD _{除了 crate 之外} | RAW_IDENTIFIER | _ ) : MacroFragSpec
   | $ ( MacroMatch⁺ ) MacroRepSep^? MacroRepOp

MacroFragSpec :
      block | expr | expr_2021 | ident | item | lifetime | literal
   | meta | pat | pat_param | path | stmt | tt | ty | vis

MacroRepSep :
   Token_{除了 分隔符 和 MacroRepOp 之外}

MacroRepOp :
   * | + | ?

MacroTranscriber :
   DelimTokenTree

macro_rules 允许用户以声明式方式定义语法扩展。我们将此类扩展称为“示例宏”或简称为“宏”。

每个示例宏都有一个名称以及一个或多个规则。每个规则包含两个部分：一个匹配器，描述它匹配的语法；以及一个转录器，描述将替换成功匹配的调用的语法。匹配器和转录器都必须用分隔符括起来。宏可以扩展为表达式、语句、条目（包括 trait、impl 和外部条目）、类型或模式。

转录

当宏被调用时，宏展开器按名称查找宏调用，并依次尝试每个宏规则。它转录第一个成功匹配的规则；如果这导致错误，则不会尝试后续的匹配。

匹配时，不执行前瞻；如果编译器无法明确地一次一个 token 地确定如何解析宏调用，则会发生错误。在以下示例中，编译器不会前瞻标识符之后的 token 以查看后续 token 是否为 )，即使这样做可以使其明确地解析调用

#![allow(unused)]
fn main() {
macro_rules! ambiguity {
    ($($i:ident)* $j:ident) => { };
}

ambiguity!(error); // Error: local ambiguity
}

在匹配器和转录器中，$ token 都用于调用宏引擎的特殊行为（如下面的 元变量 和 重复 中所述）。不属于此类调用的 token 将按字面意义匹配和转录，但有一个例外。例外情况是，匹配器的外部分隔符将匹配任何一对分隔符。因此，例如，匹配器 (()) 将匹配 {()}，但不匹配 {{}}。字符 $ 不能按字面意义匹配或转录。

转发匹配的片段

当将匹配的片段转发到另一个示例宏时，第二个宏中的匹配器将看到片段类型的不透明 AST。第二个宏不能使用字面 token 来匹配匹配器中的片段，只能使用相同类型的片段指定符。ident、lifetime 和 tt 片段类型是例外，可以 通过字面 token 进行匹配。以下示例说明了此限制

#![allow(unused)]
fn main() {
macro_rules! foo {
    ($l:expr) => { bar!($l); }
// ERROR:               ^^ no rules expected this token in macro call
}

macro_rules! bar {
    (3) => {}
}

foo!(3);
}

以下示例说明了在匹配 tt 片段后如何直接匹配 token

#![allow(unused)]
fn main() {
// compiles OK
macro_rules! foo {
    ($l:tt) => { bar!($l); }
}

macro_rules! bar {
    (3) => {}
}

foo!(3);
}

元变量

在匹配器中，$ name : 片段指定符 匹配指定类型的 Rust 语法片段，并将其绑定到元变量 $name。

有效的片段指定符包括

• block：BlockExpression
• expr：Expression
• expr_2021：Expression，但 UnderscoreExpression 和 ConstBlockExpression 除外（请参阅 macro.decl.meta.edition2024）
• ident：IDENTIFIER_OR_KEYWORD 或 RAW_IDENTIFIER
• item：Item
• lifetime：LIFETIME_TOKEN
• literal：匹配 -^?LiteralExpression
• meta：Attr，属性的内容
• pat：Pattern（请参阅 macro.decl.meta.edition2021）
• pat_param：PatternNoTopAlt
• path：TypePath 样式的路径
• stmt：Statement，不带尾部分号（条目语句需要分号的情况除外）
• tt：TokenTree （单个 token 或匹配分隔符 ()、[] 或 {} 中的 token）
• ty：Type
• vis：可能为空的 Visibility 限定符

在转录器中，元变量仅通过 $name 引用，因为片段类型在匹配器中指定。元变量将替换为与它们匹配的语法元素。

关键字元变量 $crate 可用于引用当前 crate；请参阅下面的 卫生性。元变量可以转录多次或根本不转录。

版本和 Edition 差异：从 2021 Edition 开始，pat 片段指定符匹配顶层或模式（即，它们接受 Pattern）。

在 2021 Edition 之前，它们匹配的片段与 pat_param 完全相同（即，它们接受 PatternNoTopAlt）。

相关的 Edition 是 macro_rules! 定义生效的版本。

版本和 Edition 差异：在 2024 Edition 之前，expr 片段指定符在顶层不匹配 UnderscoreExpression 或 ConstBlockExpression。它们在子表达式中是允许的。

expr_2021 片段指定符的存在是为了保持与 2024 之前版本的向后兼容性。

重复

在匹配器和转录器中，重复都通过将要重复的 token 放在 $(…) 内来指示，后跟一个重复运算符，可以选择在两者之间使用分隔符 token。

分隔符 token 可以是除了分隔符或重复运算符之外的任何 token，但 ; 和 , 是最常见的。例如，$( $i:ident ),* 表示任意数量的以逗号分隔的标识符。允许嵌套重复。

重复运算符包括

• * — 表示任意次数的重复。
• + — 表示任意次数，但至少一次。
• ? — 表示一个可选片段，出现零次或一次。

由于 ? 最多表示一次出现，因此不能与分隔符一起使用。

重复的片段既匹配又转录为指定数量的片段，并由分隔符 token 分隔。元变量与它们对应的片段的每次重复匹配。例如，上面的 $( $i:ident ),* 示例将 $i 匹配到列表中的所有标识符。

在转录期间，重复会应用其他限制，以便编译器知道如何正确展开它们

1. 元变量在转录器中出现的重复次数、种类和嵌套顺序必须与在匹配器中完全相同。因此，对于匹配器 $( $i:ident ),*，转录器 => { $i }、=> { $( $( $i)* )* } 和 => { $( $i )+ } 都是非法的，但 => { $( $i );* } 是正确的，并将逗号分隔的标识符列表替换为分号分隔的列表。
2. 转录器中的每个重复都必须包含至少一个元变量，以确定要展开多少次。如果多个元变量出现在同一个重复中，则它们必须绑定到相同数量的片段。例如，( $( $i:ident ),* ; $( $j:ident ),* ) => (( $( ($i,$j) ),* )) 必须绑定与 $j 片段相同数量的 $i 片段。这意味着使用 (a, b, c; d, e, f) 调用宏是合法的，并将展开为 ((a,d), (b,e), (c,f))，但 (a, b, c; d, e) 是非法的，因为它没有相同的数量。此要求适用于每一层嵌套重复。

作用域、导出和导入

由于历史原因，示例宏的作用域不像条目那样完全起作用。宏具有两种形式的作用域：文本作用域和基于路径的作用域。文本作用域基于事物在源文件中出现的顺序，甚至跨多个文件，并且是默认作用域。下面将进一步解释。基于路径的作用域的工作方式与条目作用域完全相同。宏的作用域、导出和导入主要由属性控制。

当通过非限定标识符（不是多部分路径的一部分）调用宏时，首先在文本作用域中查找它。如果这没有产生任何结果，则在基于路径的作用域中查找它。如果宏的名称使用路径限定，则仅在基于路径的作用域中查找它。

use lazy_static::lazy_static; // Path-based import.

macro_rules! lazy_static { // Textual definition.
    (lazy) => {};
}

lazy_static!{lazy} // Textual lookup finds our macro first.
self::lazy_static!{} // Path-based lookup ignores our macro, finds imported one.

文本作用域

文本作用域主要基于事物在源文件中出现的顺序，其工作方式类似于使用 let 声明的局部变量的作用域，但它也适用于模块级别。当 macro_rules! 用于定义宏时，宏在定义后（请注意，它仍然可以递归使用，因为名称是从调用站点查找的）直到其周围的作用域（通常是模块）关闭时才进入作用域。这可以进入子模块，甚至跨越多个文件

//// src/lib.rs
mod has_macro {
    // m!{} // Error: m is not in scope.

    macro_rules! m {
        () => {};
    }
    m!{} // OK: appears after declaration of m.

    mod uses_macro;
}

// m!{} // Error: m is not in scope.

//// src/has_macro/uses_macro.rs

m!{} // OK: appears after declaration of m in src/lib.rs

多次定义宏不是错误；最新的声明将覆盖之前的声明，除非它已超出作用域。

#![allow(unused)]
fn main() {
macro_rules! m {
    (1) => {};
}

m!(1);

mod inner {
    m!(1);

    macro_rules! m {
        (2) => {};
    }
    // m!(1); // Error: no rule matches '1'
    m!(2);

    macro_rules! m {
        (3) => {};
    }
    m!(3);
}

m!(1);
}

宏也可以在函数内部局部声明和使用，并且工作方式类似

#![allow(unused)]
fn main() {
fn foo() {
    // m!(); // Error: m is not in scope.
    macro_rules! m {
        () => {};
    }
    m!();
}

// m!(); // Error: m is not in scope.
}

macro_use 属性

macro_use 属性有两个用途。首先，它可以用于使模块的宏作用域在模块关闭时不会结束，方法是将其应用于模块

#![allow(unused)]
fn main() {
#[macro_use]
mod inner {
    macro_rules! m {
        () => {};
    }
}

m!();
}

其次，它可以用于从另一个 crate 导入宏，方法是将其附加到 crate 根模块中出现的 extern crate 声明。以这种方式导入的宏将导入到 macro_use prelude 中，而不是文本上，这意味着它们可以被任何其他名称覆盖。虽然 #[macro_use] 导入的宏可以在 import 语句之前使用，但在发生冲突时，最后导入的宏获胜。可选地，可以使用 MetaListIdents 语法指定要导入的宏列表；当 #[macro_use] 应用于模块时，不支持此功能。

#[macro_use(lazy_static)] // Or #[macro_use] to import all macros.
extern crate lazy_static;

lazy_static!{}
// self::lazy_static!{} // Error: lazy_static is not defined in `self`

要使用 #[macro_use] 导入的宏必须使用 #[macro_export] 导出，这将在下面介绍。

基于路径的作用域

默认情况下，宏没有基于路径的作用域。但是，如果它具有 #[macro_export] 属性，则会在 crate 根作用域中声明它，并且可以像这样正常引用它

#![allow(unused)]
fn main() {
self::m!();
m!(); // OK: Path-based lookup finds m in the current module.

mod inner {
    super::m!();
    crate::m!();
}

mod mac {
    #[macro_export]
    macro_rules! m {
        () => {};
    }
}
}

使用 #[macro_export] 标记的宏始终是 pub 的，并且可以被其他 crate 通过路径或如上所述的 #[macro_use] 引用。

卫生性

示例宏具有混合站点卫生性。这意味着 循环标签、块标签 和局部变量在宏定义站点查找，而其他符号在宏调用站点查找。例如

#![allow(unused)]
fn main() {
let x = 1;
fn func() {
    unreachable!("this is never called")
}

macro_rules! check {
    () => {
        assert_eq!(x, 1); // Uses `x` from the definition site.
        func();           // Uses `func` from the invocation site.
    };
}

{
    let x = 2;
    fn func() { /* does not panic */ }
    check!();
}
}

在宏展开中定义的标签和局部变量不会在调用之间共享，因此此代码无法编译

#![allow(unused)]
fn main() {
macro_rules! m {
    (define) => {
        let x = 1;
    };
    (refer) => {
        dbg!(x);
    };
}

m!(define);
m!(refer);
}

一个特殊情况是 $crate 元变量。它引用定义宏的 crate，并且可以在路径的开头使用，以查找调用站点中不在作用域内的条目或宏。

//// Definitions in the `helper_macro` crate.
#[macro_export]
macro_rules! helped {
    // () => { helper!() } // This might lead to an error due to 'helper' not being in scope.
    () => { $crate::helper!() }
}

#[macro_export]
macro_rules! helper {
    () => { () }
}

//// Usage in another crate.
// Note that `helper_macro::helper` is not imported!
use helper_macro::helped;

fn unit() {
    helped!();
}

请注意，由于 $crate 引用当前 crate，因此在引用非宏条目时，必须将其与完全限定的模块路径一起使用

#![allow(unused)]
fn main() {
pub mod inner {
    #[macro_export]
    macro_rules! call_foo {
        () => { $crate::inner::foo() };
    }

    pub fn foo() {}
}
}

此外，即使 $crate 允许宏在展开时引用其自身 crate 中的条目，但其使用对可见性没有影响。引用的条目或宏仍必须从调用站点可见。在以下示例中，从其 crate 外部调用 call_foo!() 的任何尝试都将失败，因为 foo() 不是 public 的。

#![allow(unused)]
fn main() {
#[macro_export]
macro_rules! call_foo {
    () => { $crate::foo() };
}

fn foo() {}
}

版本和 Edition 差异：在 Rust 1.30 之前，不支持 $crate 和 local_inner_macros（如下所述）。它们与宏的基于路径的导入（如上所述）一起添加，以确保 helper 宏不需要由宏导出 crate 的用户手动导入。为早期版本的 Rust 编写的使用 helper 宏的 crate 需要进行修改以使用 $crate 或 local_inner_macros，以便与基于路径的导入良好地工作。

当导出宏时，#[macro_export] 属性可以添加 local_inner_macros 关键字，以自动为所有包含的宏调用添加 $crate:: 前缀。这主要旨在作为一种工具，用于迁移在添加 $crate 之前编写的代码，以便与 Rust 2018 的宏的基于路径的导入一起工作。不鼓励在新代码中使用它。

#![allow(unused)]
fn main() {
#[macro_export(local_inner_macros)]
macro_rules! helped {
    () => { helper!() } // Automatically converted to $crate::helper!().
}

#[macro_export]
macro_rules! helper {
    () => { () }
}
}

Follow-set 歧义限制

宏系统使用的解析器功能相当强大，但为了防止当前或未来语言版本中出现歧义，它受到限制。

特别是，除了关于歧义展开的规则之外，由元变量匹配的非终结符必须后跟一个 token，该 token 已被确定可以安全地在该类匹配之后使用。

例如，像 $i:expr [ , ] 这样的宏匹配器在今天的 Rust 中理论上是可以接受的，因为 [,] 不可能是合法表达式的一部分，因此解析始终是明确的。但是，由于 [ 可以启动尾随表达式，因此 [ 不是可以安全排除在表达式之后出现的字符。如果 [,] 在更高版本的 Rust 中被接受，则此匹配器将变得模棱两可或会错误解析，从而破坏工作的代码。然而，像 $i:expr, 或 $i:expr; 这样的匹配器是合法的，因为 , 和 ; 是合法的表达式分隔符。具体规则如下

• expr 和 stmt 只能后跟以下之一：=>、, 或 ;。

• pat_param 只能后跟以下之一：=>、,、=、|、if 或 in。

• pat 只能后跟以下之一：=>、,、=、if 或 in。

• path 和 ty 只能后跟以下之一：=>、,、=、|、;、:、>、>>、[、{、as、where 或 block 片段指定符的宏变量。

• vis 只能后跟以下之一：,、非原始 priv 之外的标识符、可以开始类型的任何 token 或具有 ident、ty 或 path 片段指定符的元变量。

• 所有其他片段指定符都没有限制。

Edition 差异：在 2021 Edition 之前，pat 也可以后跟 |。

当涉及重复时，规则适用于每种可能的展开次数，并考虑分隔符。这意味着

• 如果重复包含分隔符，则分隔符必须能够后跟重复的内容。
• 如果重复可以多次重复（* 或 +），则内容必须能够后跟自身。
• 重复的内容必须能够后跟在它之前的内容，并且在它之后的内容必须能够后跟重复的内容。
• 如果重复可以匹配零次（* 或 ?），则在它之后的内容必须能够后跟在它之前的内容。

有关更多详细信息，请参阅 正式规范。