匹配规则设计
核心概念
声明宏的匹配规则由两部分组成:匹配器(matcher)和转写器(transcriber)。匹配器定义了宏接受的输入格式,转写器定义了匹配成功后展开的代码。当宏被调用时,编译器按照定义顺序逐条尝试规则,第一个匹配成功的规则会被使用,如果所有规则都不匹配则编译报错。
好的匹配规则设计需要考虑:模式的唯一性(避免歧义)、模式的顺序(具体的放前面,通用的放后面)、以及后续 token 的限制(follow-set ambiguity restrictions)。Rust 编译器会强制要求某些片段说明符后面只能跟特定的 token,以避免解析歧义。
// 多规则匹配:编译器按顺序尝试
macro_rules! describe {
// 规则1:空参数
() => {
println!("无参数");
};
// 规则2:单个表达式
($e:expr) => {
println!("表达式: {}", $e);
};
// 规则3:两个表达式
($a:expr, $b:expr) => {
println!("两个: {} 和 {}", $a, $b);
};
}
fn main() {
describe!(); // 匹配规则1
describe!(42); // 匹配规则2
describe!(1, 2); // 匹配规则3
}字面量 token 匹配
// 匹配器中可以包含字面量 token,必须精确匹配
macro_rules! command {
// 字面量关键字 + 表达式
(create $name:ident) => {
println!("创建: {}", stringify!($name));
};
(delete $name:ident) => {
println!("删除: {}", stringify!($name));
};
(rename $old:ident to $new:ident) => {
println!("重命名: {} → {}", stringify!($old), stringify!($new));
};
}
// 用标点符号作为分隔
macro_rules! pair {
($a:expr => $b:expr) => {
($a, $b)
};
($a:expr : $b:expr) => {
($a, $b)
};
}
// 用特殊符号构建 DSL 语法
macro_rules! css_like {
($selector:expr { $($prop:ident : $val:expr);* $(;)? }) => {
println!("选择器: {}", $selector);
$(
println!(" {}: {}", stringify!($prop), $val);
)*
};
}
fn main() {
command!(create user);
command!(delete file);
command!(rename old to new);
let p1 = pair!(1 => "one");
let p2 = pair!(2 : "two");
println!("{:?}, {:?}", p1, p2);
css_like!("div.header" {
color: "red";
width: "100px";
height: "50px"
});
}规则顺序的重要性
// 规则按定义顺序匹配,第一个成功的被使用
// 所以要把更具体的规则放在前面
macro_rules! check {
// 具体模式放前面
(0) => { println!("零") };
(1) => { println!("一") };
// 通用模式放后面
($e:expr) => { println!("其他: {}", $e) };
}
fn main() {
check!(0); // "零"(匹配第一条)
check!(1); // "一"(匹配第二条)
check!(42); // "其他: 42"(匹配第三条)
}// 错误示例:通用规则放前面会导致具体规则永远不被匹配
macro_rules! bad_order {
($e:expr) => { println!("通用: {}", $e) };
// 下面这条永远不会被匹配到,因为上面已经能匹配所有表达式
(0) => { println!("零") };
}
fn main() {
bad_order!(0); // "通用: 0",而不是"零"
}后续 token 限制(Follow-set)
// Rust 对某些片段说明符后面能跟的 token 有严格限制
// 这是为了避免解析歧义
// :expr 和 :stmt 后面只能跟 => , ;
// :pat 后面只能跟 => , = | if in
// :path 和 :ty 后面只能跟 => , = | ; : > >> [ { as where
// :vis 后面只能跟 , 或标识符(非原始标识符)
// :tt, :ident, :literal, :meta, :lifetime, :block 没有限制
// 合法
macro_rules! valid {
($e:expr, $t:ty) => {}; // expr 后跟 ,
($e:expr => $x:ident) => {}; // expr 后跟 =>
($p:pat => $e:expr) => {}; // pat 后跟 =>
}
// 不合法(编译错误)
// macro_rules! invalid {
// ($e:expr $t:ty) => {}; // expr 后直接跟 ty,不合法
// ($e:expr + $x:ident) => {}; // expr 后跟 +,不合法
// }
fn main() {
println!("后续 token 限制确保宏的解析不会产生歧义");
}| 片段说明符 | 允许的后续 token |
|---|---|
expr, stmt | => , ; |
pat, pat_param | => , = | if in |
path, ty | => , = | ; : > >> [ { as where |
vis | , 或任意标识符 |
tt, ident, literal | 任意 token |
meta, lifetime, block | 任意 token |
嵌套匹配器
// 匹配器可以嵌套使用分组
macro_rules! nested {
// 匹配 (a, b) => result 的形式
( ($a:expr, $b:expr) => $result:ident ) => {
let $result = $a + $b;
};
// 匹配 [items] 的形式
( [$($item:expr),*] ) => {
vec![$($item),*]
};
// 匹配 {key: value} 的形式
( { $key:ident : $value:expr } ) => {
println!("{} = {}", stringify!($key), $value);
};
}
// 复杂的嵌套结构
macro_rules! define_tests {
(
$(
test $name:ident {
input: $input:expr,
expected: $expected:expr
}
)*
) => {
$(
#[test]
fn $name() {
assert_eq!($input, $expected);
}
)*
};
}
define_tests! {
test add_works {
input: 2 + 3,
expected: 5
}
test mul_works {
input: 3 * 4,
expected: 12
}
}
fn main() {
nested!((10, 20) => sum);
println!("sum = {}", sum);
let v = nested!([1, 2, 3, 4]);
println!("vec = {:?}", v);
nested!({ name: "Rust" });
}基本示例
// 综合示例:设计一个迷你路由宏
macro_rules! router {
// 匹配多个路由定义
(
$(
$method:ident $path:literal => $handler:expr
);*
$(;)?
) => {
fn route(method: &str, path: &str) -> String {
match (method, path) {
$(
(stringify!($method), $path) => {
let handler: fn() -> String = $handler;
handler()
}
),*
_ => "404 Not Found".to_string(),
}
}
};
}
// 用宏定义路由
router! {
GET "/" => || "首页".to_string();
GET "/about" => || "关于".to_string();
POST "/login" => || "登录处理".to_string()
}
// 建造者模式宏
macro_rules! builder {
(
$name:ident {
$( $field:ident : $ty:ty ),* $(,)?
}
) => {
#[derive(Debug, Default)]
struct $name {
$( $field: Option<$ty>, )*
}
impl $name {
fn new() -> Self {
Self::default()
}
$(
fn $field(mut self, value: $ty) -> Self {
self.$field = Some(value);
self
}
)*
}
};
}
builder! {
Config {
host: String,
port: u16,
debug: bool,
}
}
fn main() {
// 路由
println!("{}", route("GET", "/"));
println!("{}", route("GET", "/about"));
println!("{}", route("POST", "/login"));
println!("{}", route("DELETE", "/unknown"));
// 建造者
let config = Config::new()
.host("localhost".to_string())
.port(8080)
.debug(true);
println!("{:?}", config);
}常见问题
问题一:规则匹配失败时错误信息不清晰怎么办?
可以在最后添加一条"兜底"规则,用 compile_error! 给出明确的提示信息。例如 ($($t:tt)*) => { compile_error!("用法: my_macro!(expr)"); };
问题二:多个规则之间会有歧义吗?
不会,因为 Rust 严格按定义顺序匹配,第一个匹配成功的规则就会被使用。但 Rust 编译器会通过 follow-set 限制确保单个规则内部不会产生解析歧义。
问题三:怎么匹配任意内容?
使用 $($t:tt)* 可以匹配任意的 token 序列,tt(token tree)是最通用的片段说明符,可以匹配任何单个 token 或被定界符包裹的 token 组。
适用场景
- DSL 设计:用字面量 token 构建特定语法
- 多态宏:用多条规则处理不同参数形式
- 代码生成:用嵌套匹配器处理复杂的结构化输入
注意事项
- 具体的规则放前面,通用的放后面
- 注意 follow-set 限制,某些片段说明符后面能跟的 token 有限
- 匹配器中的字面量 token 必须精确匹配
- 嵌套的匹配器可以使用不同的定界符
- 使用
compile_error!提供友好的错误提示
总结
匹配规则设计是声明宏的核心。每条规则由匹配器和转写器组成,编译器按定义顺序逐条尝试匹配。匹配器可以包含字面量 token(精确匹配)、片段说明符(捕获语法片段)和重复模式。设计规则时要注意顺序——具体的放前面、通用的放后面。Rust 的 follow-set 限制确保解析不会出现歧义,某些片段说明符(如 expr、pat、ty)后面能跟的 token 类型是固定的。嵌套匹配器可以用不同的定界符来构造复杂的 DSL 语法。