捕获指定类型 ident/expr/ty ​

核心概念 ​

片段说明符(fragment specifier)是声明宏中用来描述要捕获的语法片段类型的关键字。当你在匹配器中写 $name:expr 时,expr 就是片段说明符,告诉编译器"这里要匹配一个表达式"。Rust 目前共有 16 种片段说明符,每种对应不同的语法结构。

最常用的三种是 ident(标识符)、expr(表达式)和 ty(类型)。ident 匹配变量名、函数名等标识符;expr 匹配任何 Rust 表达式;ty 匹配类型表达式。编译器会利用 Rust 解析器来匹配这些语法片段,确保捕获的内容在语法上是正确的。

捕获后的片段变成了不透明的 AST 节点——除了 ident、lifetime 和 tt 之外,其他片段在后续的宏规则中无法再被进一步匹配拆分。

rust
// ident:匹配标识符(变量名、函数名、类型名等)
macro_rules! make_var {
    ($name:ident, $value:expr) => {
        let $name = $value;
    };
}

// expr:匹配任何表达式
macro_rules! double {
    ($e:expr) => {
        $e + $e
    };
}

// ty:匹配类型
macro_rules! make_vec {
    ($t:ty) => {
        Vec::<$t>::new()
    };
}

fn main() {
    make_var!(x, 42);
    println!("x = {}", x);

    println!("double(5) = {}", double!(5));
    println!("double(2+3) = {}", double!(2 + 3));

    let v = make_vec!(String);
    println!("Vec<String>: {:?}", v);
}

所有片段说明符详解 ​

rust
// === ident:标识符 ===
// 匹配变量名、函数名、关键字等
macro_rules! show_ident {
    ($i:ident) => {
        println!("标识符: {}", stringify!($i));
    };
}

// === expr:表达式 ===
// 匹配任何表达式:字面量、函数调用、运算、块等
macro_rules! show_expr {
    ($e:expr) => {
        println!("表达式值: {}", $e);
    };
}

// === ty:类型 ===
// 匹配类型表达式:i32, Vec<String>, &str, impl Trait 等
macro_rules! type_name {
    ($t:ty) => {
        println!("类型: {}", stringify!($t));
    };
}

// === pat:模式 ===
// 匹配 match 分支的模式(2021 edition 支持 | 模式)
macro_rules! match_it {
    ($val:expr, $p:pat => $body:expr) => {
        match $val {
            $p => $body,
            _ => println!("不匹配"),
        }
    };
}

// === stmt:语句 ===
// 匹配语句(不含尾部分号,除非是需要分号的 item)
macro_rules! wrap_stmt {
    ($s:stmt) => {
        println!("执行语句前");
        $s;
        println!("执行语句后");
    };
}

// === block:代码块 ===
// 匹配花括号包裹的代码块
macro_rules! run_block {
    ($b:block) => {
        println!("块开始");
        $b
        println!("块结束");
    };
}

// === item:项 ===
// 匹配函数定义、结构体定义、impl 块等
macro_rules! emit_item {
    ($i:item) => { $i };
}

// === literal:字面量 ===
// 匹配数字、字符串、字符、布尔等字面量
macro_rules! show_literal {
    ($l:literal) => {
        println!("字面量: {}", $l);
    };
}

// === lifetime:生命周期 ===
macro_rules! show_lifetime {
    ($lt:lifetime) => {
        println!("生命周期: {}", stringify!($lt));
    };
}

// === path:路径 ===
// 匹配类型路径:std::collections::HashMap, Vec 等
macro_rules! show_path {
    ($p:path) => {
        println!("路径: {}", stringify!($p));
    };
}

// === meta:属性内容 ===
// 匹配 #[...] 属性中的内容
macro_rules! apply_attr {
    (#[$m:meta] $i:item) => {
        #[$m]
        $i
    };
}

// === tt:token tree ===
// 匹配任何单个 token 或定界符包裹的 token 组
macro_rules! show_tt {
    ($t:tt) => {
        println!("tt: {}", stringify!($t));
    };
}

// === vis:可见性 ===
// 匹配可见性修饰符(pub、pub(crate) 等,也可以为空)
macro_rules! make_field_struct {
    ($vis:vis $name:ident { $($fvis:vis $fname:ident : $fty:ty),* $(,)? }) => {
        $vis struct $name {
            $($fvis $fname: $fty,)*
        }
    };
}

fn main() {
    show_ident!(hello);
    show_ident!(my_var);

    show_expr!(1 + 2);
    show_expr!("hello".to_string());

    type_name!(i32);
    type_name!(Vec<String>);
    type_name!(&'static str);

    match_it!(42, 42 => println!("匹配到 42"));
    match_it!(42, 1 | 2 | 3 => println!("小数字"));

    wrap_stmt!(let x = 10);

    run_block!({
        let a = 1;
        let b = 2;
        println!("a + b = {}", a + b);
    });

    emit_item!(fn generated() { println!("生成的函数"); });
    generated();

    show_literal!(42);
    show_literal!("hello");
    show_literal!(true);

    show_lifetime!('static);

    show_path!(std::collections::HashMap);

    apply_attr!(#[derive(Debug)] struct Foo { x: i32 });
    println!("{:?}", Foo { x: 1 });

    show_tt!(hello);
    show_tt!((1 + 2));
    show_tt!({ a: b });
}
片段说明符匹配内容示例可再匹配
ident标识符/关键字foo, async是
expr表达式1+2, f()否
ty类型i32, Vec<T>否
pat模式_, Some(x), 1|2否
stmt语句let x = 1否
block代码块{ ... }否
item项定义fn f(){}, struct S{}否
literal字面量42, "hi", true否
lifetime生命周期'a, 'static是
path路径std::io::Read否
meta属性内容derive(Debug)否
tttoken tree任意单 token 或组是
vis可见性pub, pub(crate), 空否
pat_param模式(不含顶层|)Some(x)否

ident 的特殊用法 ​

rust
// ident 可以用来生成新的标识符名称

// 生成 getter/setter
macro_rules! accessor {
    ($field:ident, $ty:ty) => {
        // 用 ident 作为函数名和字段名
        fn $field(&self) -> &$ty {
            &self.$field
        }
    };
}

// 批量生成枚举变体
macro_rules! make_enum {
    ($name:ident => $($variant:ident),* $(,)?) => {
        #[derive(Debug, PartialEq)]
        enum $name {
            $($variant,)*
        }
    };
}

make_enum!(Color => Red, Green, Blue, Yellow);

struct Person {
    name: String,
    age: u32,
}

impl Person {
    accessor!(name, String);
    accessor!(age, u32);
}

fn main() {
    let p = Person { name: "Alice".into(), age: 30 };
    println!("{}, {}", p.name(), p.age());
    println!("{:?}", Color::Red);
}

expr 的注意事项 ​

rust
// expr 捕获的内容是不透明的 AST 节点
// 不能在后续宏中拆分

macro_rules! safe_div {
    ($a:expr, $b:expr) => {{
        let divisor = $b;
        if divisor == 0 {
            None
        } else {
            // $a 会被计算两次如果直接使用两次
            // 所以绑定到局部变量
            let dividend = $a;
            Some(dividend / divisor)
        }
    }};
}

// expr 可能的副作用:表达式被多次求值
macro_rules! bad_double {
    ($e:expr) => {
        $e + $e  // 如果 $e 有副作用,会执行两次!
    };
}

macro_rules! good_double {
    ($e:expr) => {{
        let val = $e;  // 只求值一次
        val + val
    }};
}

fn side_effect() -> i32 {
    println!("  副作用!");
    5
}

fn main() {
    println!("safe_div(10, 3) = {:?}", safe_div!(10, 3));
    println!("safe_div(10, 0) = {:?}", safe_div!(10, 0));

    println!("\nbad_double:");
    println!("结果: {}", bad_double!(side_effect()));
    // 打印两次"副作用!"

    println!("\ngood_double:");
    println!("结果: {}", good_double!(side_effect()));
    // 只打印一次"副作用!"
}

基本示例 ​

rust
// 综合运用多种片段说明符

// 用 ident + ty + expr 生成结构体和构造函数
macro_rules! define_struct {
    (
        $vis:vis struct $name:ident {
            $($fvis:vis $field:ident : $ty:ty = $default:expr),*
            $(,)?
        }
    ) => {
        #[derive(Debug)]
        $vis struct $name {
            $($fvis $field: $ty,)*
        }

        impl $name {
            $vis fn new() -> Self {
                Self {
                    $($field: $default,)*
                }
            }
        }

        impl std::fmt::Display for $name {
            fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
                write!(f, "{} {{ ", stringify!($name))?;
                $(
                    write!(f, "{}: {:?}, ", stringify!($field), self.$field)?;
                )*
                write!(f, "}}")
            }
        }
    };
}

define_struct! {
    pub struct AppConfig {
        pub host: String = String::from("localhost"),
        pub port: u16 = 8080,
        pub debug: bool = false,
        pub max_connections: usize = 100
    }
}

// 用 pat + expr 构建 match 包装
macro_rules! match_map {
    ($val:expr; $($pat:pat => $result:expr),+ $(,)?) => {
        match $val {
            $($pat => $result,)+
        }
    };
}

fn main() {
    let config = AppConfig::new();
    println!("{}", config);
    println!("{:?}", config);

    let status = 404;
    let msg = match_map!(status;
        200 => "OK",
        404 => "Not Found",
        500 => "Internal Server Error",
        _ => "Unknown"
    );
    println!("HTTP {}: {}", status, msg);
}

常见问题 ​

问题一:为什么 expr 捕获后不能再匹配?

因为 expr 捕获后变成了不透明的 AST 节点,编译器不会再"拆开"它。只有 ident、lifetime 和 tt 捕获的内容可以在后续宏调用中再次被匹配。如果需要对捕获内容做进一步处理,用 tt 代替。

问题二:pat 和 pat_param 有什么区别?

在 Rust 2021 Edition 中,pat 匹配包含顶层 | 的模式(如 1 | 2 | 3),而 pat_param 不匹配顶层 |。在 2021 之前,pat 的行为与 pat_param 相同。如果你的宏需要在 $p:pat 后面跟 |,应该用 pat_param。

问题三:vis 可以匹配空内容吗?

可以。vis 隐含了 ? 的语义,它可以匹配 pub、pub(crate)、pub(super) 等可见性修饰符,也可以匹配空(即没有修饰符,表示私有)。但 vis 不能单独重复使用,必须后跟其他 token。

问题四:expr 与 literal 有什么区别?

literal 只匹配字面量值(如 42、"hello"、true),不匹配变量、函数调用或运算表达式。expr 匹配所有表达式,包括字面量。当你确定只需要字面量时,用 literal 更精确。

适用场景 ​

  • ident:生成函数名、变量名、类型名
  • expr:接受任意运算表达式作为参数
  • ty:泛型类型参数、类型别名生成
  • tt:需要灵活匹配的场景
  • pat:match 分支的模式构建

注意事项 ​

  • expr 捕获的内容如果有副作用要绑定到局部变量
  • 除 ident/lifetime/tt 外的捕获不能再被其他片段说明符匹配
  • 不同片段说明符有不同的 follow-set 限制
  • Rust 2021 Edition 改变了 pat 的行为
  • vis 可以匹配空内容,但不能单独重复

总结 ​

片段说明符是声明宏捕获语法片段的方式。Rust 提供了 16 种说明符,覆盖了所有语法结构。最常用的 ident 匹配标识符、expr 匹配表达式、ty 匹配类型。捕获后的片段(除 ident/lifetime/tt)变成不透明的 AST 节点,不能在后续宏中再拆分匹配。使用 expr 时要注意多次求值的副作用问题,应将表达式绑定到局部变量。tt 是最灵活的说明符,可以匹配任意 token。不同说明符有不同的 follow-set 限制,决定了它后面可以跟什么 token。