可选模式 $( )?
核心概念
可选模式 $( ... )? 是 Rust 1.32 稳定引入的重复操作符,表示"匹配零次或一次"。它是 *(零或多次)和 +(一或多次)的补充,专门用于处理"有或没有"的可选参数场景。在此之前,处理可选参数只能通过定义多条规则来实现。
$( ... )? 内部可以包含任意 token 组合,包括片段说明符、字面量 token 等。匹配到的内容在转写器中用同样的 $( ... )? 展开。? 操作符不能有分隔符(因为最多只匹配一次,不需要分隔符)。
// 可选的返回类型
macro_rules! make_fn {
// $( -> $ret:ty )? 匹配可选的返回类型
(fn $name:ident() $(-> $ret:ty)? { $($body:tt)* }) => {
fn $name() $(-> $ret)? {
$($body)*
}
};
}
// 没有返回类型
make_fn!(fn greet() {
println!("Hello!");
});
// 有返回类型
make_fn!(fn answer() -> i32 {
42
});
fn main() {
greet();
println!("answer = {}", answer());
}与多规则方式的对比
// === 旧方式:多条规则处理可选参数 ===
macro_rules! old_style {
// 无可选参数
($name:expr) => {
println!("名称: {}", $name);
};
// 有可选参数
($name:expr, $desc:expr) => {
println!("名称: {}, 描述: {}", $name, $desc);
};
}
// === 新方式:$( )? 处理可选参数 ===
macro_rules! new_style {
($name:expr $(, $desc:expr)?) => {
print!("名称: {}", $name);
$(
print!(", 描述: {}", $desc);
)?
println!();
};
}
fn main() {
old_style!("Alice");
old_style!("Bob", "开发者");
new_style!("Alice");
new_style!("Bob", "开发者");
}| 方式 | 代码量 | 可维护性 | 适用场景 |
|---|---|---|---|
| 多条规则 | 规则数随可选参数组合增长 | 参数多时难维护 | 不同参数形式的逻辑完全不同 |
$( )? | 一条规则 | 简洁 | 可选参数只是"有或没有"的差别 |
常见用法
// 1. 可选的尾随逗号
macro_rules! list {
($($item:expr),* $(,)?) => {
vec![$($item),*]
};
}
// 2. 可选的可见性修饰符(vis 自带可选语义,但有时需要额外语法)
macro_rules! define_fn {
($(pub)? fn $name:ident() $body:block) => {
// 这里用字面量 pub 匹配
// 注意:这不如用 $vis:vis 灵活
};
}
// 3. 可选的泛型约束
macro_rules! make_wrapper {
($name:ident($inner:ty) $(where $bound:tt)*) => {
struct $name {
inner: $inner,
}
};
}
// 4. 可选的初始值
macro_rules! declare {
($name:ident : $ty:ty $(= $init:expr)?) => {
// 用 Option 来处理有或没有初始值
let $name: $ty;
$(
$name = $init;
)?
// 如果没有初始值,变量未初始化,后续赋值前不能使用
};
}
// 5. 可选的文档注释
macro_rules! documented_const {
($(#[doc = $doc:literal])? const $name:ident : $ty:ty = $val:expr) => {
$(#[doc = $doc])?
const $name: $ty = $val;
};
}
documented_const!(
#[doc = "最大重试次数"]
const MAX_RETRIES: u32 = 3
);
documented_const!(
const MIN_SIZE: usize = 1
);
fn main() {
// 尾随逗号
let v1 = list![1, 2, 3]; // 无尾随逗号
let v2 = list![1, 2, 3,]; // 有尾随逗号
println!("{:?} {:?}", v1, v2);
// 可选初始值
declare!(x: i32 = 42);
println!("x = {}", x);
println!("MAX_RETRIES = {}", MAX_RETRIES);
println!("MIN_SIZE = {}", MIN_SIZE);
}$( )? 与 $( )* 的区别
// ? 最多匹配一次,* 可以匹配多次
// 用 ? 的场景:可选的单个参数
macro_rules! greet {
($name:expr $(, $title:expr)?) => {
$(
print!("{} ", $title);
)?
println!("{}", $name);
};
}
// 用 * 的场景:可变数量的参数
macro_rules! greet_many {
($($name:expr),*) => {
$(
println!("你好, {}", $name);
)*
};
}
// ? 不能有分隔符
// macro_rules! bad {
// ($($e:expr),?) => {}; // 编译错误:? 不能有分隔符
// }
// * 可以有分隔符
macro_rules! good {
($($e:expr),*) => {}; // 合法
}
fn main() {
greet!("Alice");
greet!("Alice", "Dr.");
greet_many!();
greet_many!("Alice", "Bob", "Carol");
}| 特性 | ? | * | + |
|---|---|---|---|
| 最少次数 | 0 | 0 | 1 |
| 最多次数 | 1 | 无限 | 无限 |
| 分隔符 | 不允许 | 允许 | 允许 |
| 典型场景 | 可选单参数 | 可变参数列表 | 至少一个参数 |
基本示例
// 综合实战:用可选模式构建灵活的结构体定义宏
macro_rules! entity {
(
$(#[doc = $doc:literal])?
$vis:vis struct $name:ident {
$(
$(#[doc = $fdoc:literal])?
$fvis:vis $fname:ident : $fty:ty $(= $fdefault:expr)?
),*
$(,)?
}
) => {
$(#[doc = $doc])?
#[derive(Debug)]
$vis struct $name {
$(
$(#[doc = $fdoc])?
$fvis $fname: $fty,
)*
}
impl $name {
$vis fn new(
$( $fname: $fty, )*
) -> Self {
Self {
$( $fname, )*
}
}
}
// 如果有默认值,生成 default 构造函数
impl Default for $name {
fn default() -> Self {
Self {
$(
$fname: entity!(@default $fty $(, $fdefault)?),
)*
}
}
}
};
// 内部辅助规则:处理可选的默认值
(@default $ty:ty, $val:expr) => { $val };
(@default $ty:ty) => { <$ty as Default>::default() };
}
entity! {
#[doc = "用户配置"]
pub struct UserConfig {
#[doc = "用户名"]
pub name: String = String::from("guest"),
pub age: u32 = 0,
pub email: String,
pub active: bool = true,
}
}
// 可选模式在错误处理宏中的应用
macro_rules! try_or {
($expr:expr $(, $fallback:expr)?) => {{
match $expr {
Ok(val) => val,
Err(_e) => {
$(return $fallback;)?
// 如果没有 fallback,继续执行(这行不会到达如果有 fallback)
#[allow(unreachable_code)]
{
panic!("操作失败");
}
}
}
}};
}
fn parse_number(s: &str) -> Result<i32, String> {
s.parse::<i32>().map_err(|e| e.to_string())
}
fn process(input: &str) -> i32 {
let num = try_or!(parse_number(input), -1);
num * 2
}
fn main() {
// 使用默认值
let default_config = UserConfig::default();
println!("默认: {:?}", default_config);
// 使用自定义值
let custom_config = UserConfig::new(
"Alice".to_string(),
30,
"alice@example.com".to_string(),
true,
);
println!("自定义: {:?}", custom_config);
// try_or
println!("parse '42': {}", process("42"));
println!("parse 'abc': {}", process("abc"));
}常见问题
问题一:$( )? 是什么时候稳定的?
Rust 1.32.0(2019年1月发布)。在此之前只能用多条规则或 $( )* 配合额外逻辑来模拟可选参数。
问题二:$( )? 内部可以有多个 token 吗?
可以。$( ... )? 内部可以是任意 token 组合,包括多个片段说明符、字面量 token 等。整个组要么全部匹配,要么全部不匹配。
问题三:$( )? 和直接用 $( ) 有什么实际差别?*
语义上更精确——? 明确表示"最多一次",* 表示"任意次"。使用 ? 可以避免意外匹配多次。另外 ? 不允许分隔符,而 * 允许。
问题四:可选模式中的变量如果没匹配到怎么办?
转写器中对应的 $( ... )? 块不会展开,相当于没有这段代码。这不会报错,也不会产生任何输出。
适用场景
- 尾随逗号:
$(,)?允许列表最后有可选逗号 - 可选返回类型:
$(-> $ret:ty)? - 可选属性/文档:
$(#[doc = $doc:literal])? - 可选默认值:
$(= $default:expr)? - 可选泛型约束:
$(where $bounds:tt)*
注意事项
?不能有分隔符,与*和+不同?最多匹配一次,不能用于列表- 转写器中的
$( ... )?会在没匹配时被完全省略 - 对于
vis片段说明符,它本身就隐含可选语义 - 如果不同参数组合的处理逻辑差异很大,多条规则比
?更清晰
总结
$( )? 是声明宏中的可选模式操作符,匹配零次或一次。它让宏能优雅地处理"有或没有"的参数,替代了之前需要多条规则的写法。? 不能有分隔符,内部可以包含任意 token 组合。最常见的用法是 $(,)? 处理尾随逗号、$(-> $ret:ty)? 处理可选返回类型、$(= $default:expr)? 处理可选默认值。转写器中对应的 $( ... )? 在未匹配时会被完全省略。当不同参数组合需要完全不同的处理逻辑时,多条规则依然比 ? 更合适。