示例文宏

^语法
MacroRulesDefinition :
   macro_rules ! 标识符 MacroRulesDef

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

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

MacroRule :
   MacroMatcher => MacroTranscriber

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

MacroMatch :
      标记_{除了 $ 和 分隔符 之外}
   | MacroMatcher
   | $ ( 标识符或关键字 _{除了 crate} | 原始标识符 | _ ) : MacroFragSpec
   | $ ( MacroMatch⁺ ) MacroRepSep^? MacroRepOp

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

MacroRepSep :
   标记_{除了 分隔符 和 MacroRepOp 之外}

MacroRepOp :
   * | + | ?

MacroTranscriber :
   DelimTokenTree

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

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

转录

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

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

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

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

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

转发匹配的片段

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

#![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 片段后如何直接匹配标记

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

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

foo!(3);
}

元变量

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

有效的片段说明符包括

• block: 一个 块表达式
• expr: 一个 表达式
• expr_2021: 一个 表达式，除了 下划线表达式 和 const 块表达式（参见 macro.decl.meta.edition2024）
• ident: 一个 标识符或关键字 或 原始标识符
• item: 一个 项
• lifetime: 一个 生命周期标记
• literal: 匹配 -^?字面量表达式
• meta: 一个 Attr，属性的内容
• pat: 一个 模式（参见 macro.decl.meta.edition2021）
• pat_param: 一个 PatternNoTopAlt
• path: 一个 TypePath 风格的路径
• stmt: 一个 语句，不带尾随的分号（除了需要分号的项语句）
• tt: 一个 标记树 （一个单独的 标记 或匹配分隔符 (), [], 或 {} 中的标记）
• ty: 一个 类型
• vis: 一个可能为空的 可见性 限定符

在转录器中，元变量只需通过 $名称 来引用，因为片段类型已在匹配器中指定。元变量将被替换为与其匹配的语法元素。

关键字元变量 $crate 可用于引用当前 crate；参见下文 卫生性。元变量可以被转录多次或不被转录。

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

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

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

版本差异：在 2024 版本之前，expr 片段说明符不匹配顶层的 下划线表达式 或 const 块表达式。它们允许出现在子表达式中。

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

重复

在匹配器和转录器中，通过将要重复的标记放在 $(…) 内部来指示重复，后跟一个重复操作符，可选地在它们之间有一个分隔标记。

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

重复操作符包括

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

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

重复的片段既匹配又转录为指定数量的片段，它们由分隔标记分开。元变量匹配其对应片段的每次重复。例如，上面的 $( $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 根模块中的 extern crate 声明上，它可以用于从另一个 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（如下）。它们与基于路径的宏导入（如上所述）一起添加，以确保宏导出 crate 的用户不需要手动导入辅助宏。为早期 Rust 版本编写的使用辅助宏的 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 {
    () => { () }
}
}

后继集歧义限制

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

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

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

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

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

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

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

• vis 后面只能跟随以下之一：,，一个非原始 priv 之外的标识符，任何可以开始一个类型的标记，或者一个具有 ident、ty 或 path 片段说明符的元变量。

• 所有其他片段说明符没有限制。

版本差异：在 2021 版本之前，pat 后面也可以跟随 |。

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

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

有关更多详情，请参阅 正式规范。