匹配规则设计 ​

核心概念 ​

声明宏的匹配规则由两部分组成:匹配器(matcher)和转写器(transcriber)。匹配器定义了宏接受的输入格式,转写器定义了匹配成功后展开的代码。当宏被调用时,编译器按照定义顺序逐条尝试规则,第一个匹配成功的规则会被使用,如果所有规则都不匹配则编译报错。

好的匹配规则设计需要考虑:模式的唯一性(避免歧义)、模式的顺序(具体的放前面,通用的放后面)、以及后续 token 的限制(follow-set ambiguity restrictions)。Rust 编译器会强制要求某些片段说明符后面只能跟特定的 token,以避免解析歧义。

rust
// 多规则匹配:编译器按顺序尝试
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 匹配 ​

rust
// 匹配器中可以包含字面量 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"
    });
}

规则顺序的重要性 ​

rust
// 规则按定义顺序匹配,第一个成功的被使用
// 所以要把更具体的规则放在前面

macro_rules! check {
    // 具体模式放前面
    (0) => { println!("零") };
    (1) => { println!("一") };
    // 通用模式放后面
    ($e:expr) => { println!("其他: {}", $e) };
}

fn main() {
    check!(0);     // "零"(匹配第一条)
    check!(1);     // "一"(匹配第二条)
    check!(42);    // "其他: 42"(匹配第三条)
}
rust
// 错误示例:通用规则放前面会导致具体规则永远不被匹配
macro_rules! bad_order {
    ($e:expr) => { println!("通用: {}", $e) };
    // 下面这条永远不会被匹配到,因为上面已经能匹配所有表达式
    (0) => { println!("零") };
}

fn main() {
    bad_order!(0);  // "通用: 0",而不是"零"
}

后续 token 限制(Follow-set) ​

rust
// 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

嵌套匹配器 ​

rust
// 匹配器可以嵌套使用分组
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" });
}

基本示例 ​

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 语法。