捕获指定类型 ident/expr/ty
核心概念
片段说明符(fragment specifier)是声明宏中用来描述要捕获的语法片段类型的关键字。当你在匹配器中写 $name:expr 时,expr 就是片段说明符,告诉编译器"这里要匹配一个表达式"。Rust 目前共有 16 种片段说明符,每种对应不同的语法结构。
最常用的三种是 ident(标识符)、expr(表达式)和 ty(类型)。ident 匹配变量名、函数名等标识符;expr 匹配任何 Rust 表达式;ty 匹配类型表达式。编译器会利用 Rust 解析器来匹配这些语法片段,确保捕获的内容在语法上是正确的。
捕获后的片段变成了不透明的 AST 节点——除了 ident、lifetime 和 tt 之外,其他片段在后续的宏规则中无法再被进一步匹配拆分。
// 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);
}所有片段说明符详解
// === 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) | 否 |
tt | token tree | 任意单 token 或组 | 是 |
vis | 可见性 | pub, pub(crate), 空 | 否 |
pat_param | 模式(不含顶层|) | Some(x) | 否 |
ident 的特殊用法
// 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 的注意事项
// 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()));
// 只打印一次"副作用!"
}基本示例
// 综合运用多种片段说明符
// 用 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。