宏
输入语法与输出语法一致
Input syntax is evocative of the output (C-EVOCATIVE)
Rust 宏系统允许你创造出你想要的输入语法。 尽量让输入的语法是让大多数人感到熟悉的， 仿照现存的 Rust 语法以便让使用者的代码风格统一。 注意对关键字和标点符号的选择与更改。
好的标准是：宏输入的语法与输出的结果不会相差太大，尤其在关键字和标点符号方面。
比如你写的宏要根据输入来声明一个具体的结构体，那么就以 struct 关键字开头，
后接结构体的名称。
// 这种方式更好
bitflags! {
struct S: u32 { /* ... */ }
}
// 这种方式就不太好
bitflags! {
S: u32 { /* ... */ }
}
// 这种方式也不太好
bitflags! {
flags S: u32 { /* ... */ }
}
另一个例子是分号和逗号之间如何做出选择。 Rust 的常量 (constants) 以分号作为结尾，所以如果你写的宏要定义一系列常量， 那么应该在输入语法里书写分号，即使语法看起来与 Rust 的语法有些不同。
// 原始的常量定义语法后面接的是分号
const A: u32 = 0b000001;
const B: u32 = 0b000010;
// 所以这种方式更好
bitflags! {
struct S: u32 {
const C = 0b000100;
const D = 0b001000;
}
}
// 这种方式不太好
bitflags! {
struct S: u32 {
const E = 0b010000,
const F = 0b100000,
}
}
宏是多样化的，以致于这里举的例子不会适合所有场景。 但是的确要仔细思考如何应用同一套规则。
宏与属性形成有机的整体
Item macros compose well with attributes (C-MACRO-ATTR)
生成超过一个条目 (item) 的宏，应该支持对每个条目添加属性。 一个常见的例子是，把单独的条目放在 cfg 后面：
bitflags! {
struct Flags: u8 {
#[cfg(windows)]
const ControlCenter = 0b001;
#[cfg(unix)]
const Terminal = 0b010;
}
}
生成结构体或枚举体的宏，应该支持添加宏属性， 方便让输出结果使用 derive 属性。
bitflags! {
#[derive(Default, Serialize)]
struct Flags: u8 {
const ControlCenter = 0b001;
const Terminal = 0b010;
}
}
生成条目的宏可以在条目被允许的地方使用
Item macros work anywhere that items are allowed (C-ANYWHERE)
Rust 允许条目 (item) 有模块级别那样的作用域或者出现在类似函数这样小的作用域里。 生成条目的宏应该和普通的条目一样，在这些地方可以正常使用。 测试这些宏的时，应该至少在模块和函数作用域里都调用宏。
#[cfg(test)]
mod tests {
test_your_macro_in_a!(module);
#[test]
fn anywhere() {
test_your_macro_in_a!(function);
}
}
下面这个例子展示了错误的宏： 这个宏能在模块作用域里运行，但不能在函数作用域里运行。
macro_rules! broken {
($m:ident :: $t:ident) => {
pub struct $t;
pub mod $m {
pub use super::$t;
}
}
}
broken!(m::T); // 运行通过，可以展开成 T 和 m::T
fn g() {
broken!(m::U); // 编译失败，super::U 指的是上级模块，而不是函数 g
}
生成条目的宏应支持可见性分类符
Item macros support visibility specifiers (C-MACRO-VIS)
宏应遵循 Rust 对条目可见性 (visibility) 的语法要求：
默认是私有的，如果使用 pub 则表明条目是公有的。
bitflags! {
struct PrivateFlags: u8 {
const A = 0b0001;
const B = 0b0010;
}
}
bitflags! {
pub struct PublicFlags: u8 {
const C = 0b0100;
const D = 0b1000;
}
}
类型分类符 $t:ty 是灵活的
Type fragments are flexible (C-MACRO-TY)
如果你写的宏接收 $t:ty 类型 分类符 作为输入，
那么输入的内容应该与以下代码一起使用：
- 原生类型：
u8,&str - 相对路径：
m::Data - 绝对路径：
::base::Data - 上级相对路径：
super::Data - 泛型：
Vec<String>
下面这个例子展示了错误的宏： 这个宏能在很好地与原生类型、绝对路径一起使用， 但不能和相对路径一起使用。