batch-impl 0.2.1

A proc-macro library for batch generating trait impls with a powerful DSL
Documentation

batch-impl

为 Rust trait 批量生成 impl 块的过程宏库。

设计目标

batch-impl 的核心设计目标是批量生成（bulk generation）——把"为 N 个类型写 N 个 impl"压缩成一行声明式 DSL。

功能特性

特性 说明
批量生成 为任意类型批量生成 impl 块
泛型控制 手动精确指定 impl 泛型和 trait 泛型
自定义 body 每个类型可有独立的实现体
元组生成 ()^N + 笛卡尔积 + 范围语法
^ 运算符 右结合，泛型应用和类型组合
- 运算符 左结合，同 ^ 语义
unsafe impl 支持 unsafe impl 生成
关联类型 简洁语法绑定关联类型
fn 类型 批量生成函数类型实现
属性支持 为 impl 块添加属性

安装

[dependencies]

batch-impl = "0.2.1"

需要 Rust 2021 edition 及以上。

两个入口

宏 用途
#[batch_impl] 属性宏，在 trait 定义上标注
batch_trait! 函数式宏，对已声明的 trait 批量生成 impl

两者接受相同的 DSL 参数。

快速开始

use batch_impl::batch_impl;

#[batch_impl(usize, isize)]
trait Numeric {}
// → impl Numeric for usize {}
// → impl Numeric for isize {}

语法概览

#[batch_impl( impl-spec [, impl-spec]* [ { body }]? )]
impl-spec = [ <impl-泛型> ] [ Trait名<trait-泛型> ] 目标 [ { body } ]

结构分解

部分 示例 何时需要
<impl-泛型> <T>, <T: Clone>, <const N: usize> impl 块需要泛型参数时
Trait名<trait-泛型> MyTrait<T>, MyTrait<Vec<T>> trait 定义有泛型参数时
目标类型 usize, Vec<T>, &str 必需
[...] 列表 [A, B, C] 为多个类型同时实现
{ body } { fn m(&self) -> usize { 0 } } 需要自定义实现体时

^ 运算符（右结合）

A^B^C = A^(B^C)。左侧是"修饰符"，右侧是"目标类型"。修饰符可以是：

修饰符 含义
& 引用
&mut 可变引用
*const 裸指针（不可变）
*mut 裸指针（可变）
self 恒等（不改变类型）
unsafe 标记 impl 为 unsafe impl
fn 函数类型前缀
#[attr] 属性前缀
Ident 容器（如 Box, Vec）
Ident<...> 带预填泛型的容器（如 HashMap<K>），^ 追加参数
(A,)/(A,B) 元组前缀
() 空元组前缀
(<bound>) 带 trait bound 的泛型元组前缀
[A, B] 多修饰符（笛卡尔积展开）
写法 展开
&^T &T
&mut^T &mut T
*const^T *const T
*mut^T *mut T
self^T T
Box^T Box<T>
Box^<X,Y> Box<X, Y>（多参容器）
[Box, Vec]^T Box<T>, Vec<T>
Box^[T1, T2] Box<T1>, Box<T2>
[Box, Vec]^[T1, T2] 笛卡尔积共 4 项
Box^Box^T Box<Box<T>>
HashMap<K>^V HashMap<K, V>（预填泛型追加）
[HashMap<K>, Vec<K>]^V HashMap<K, V>, Vec<K, V>
&^Box^T &Box<T>（引用类修饰符链式应用）
*const^Vec^T *const Vec<T>
fn^(A,B) fn(A,B)（函数类型）
#[attr]^T 在 impl 块前添加属性

- 运算符（左结合）

- 与 ^ 语义完全相同，仅结合方向不同：A-B = A^B，A-B-C = (A-B)-C。

写法 展开
Vec-u32 Vec<u32>
HashMap-u32-String HashMap<u32, String>（左结合，预填泛型追加）
()-[A, B] (A,), (B,)
()-[A, B]-[C, D] (A, C), (A, D), (B, C), (B, D)

元组生成

^ 运算符右侧是数字或范围时，生成指定长度的元组。

写法 展开
()^3 (A, B, C)（带3个泛型参数）
(T,)^3 (T, T, T)
(<Clone>)^3 (A:Clone, B:Clone, C:Clone)
(T1, T2)^2 笛卡尔积 (T1,T1), (T1,T2), (T2,T1), (T2,T2)
()^1..3 (A,), (A, B)（长度1到2）
()^1..=3 (A,), (A, B), (A, B, C)（长度1到3）
(T,)^2..4 (T, T), (T, T, T)（长度2到3）

注意：(T) 是分组（非元组），(T,) 才是单元素元组。

使用示例

基础

use batch_impl::batch_impl;

#[batch_impl(usize, isize)]
trait Numeric {}

#[batch_impl(<T> Vec<T>)]
trait Collection {}

Trait 带泛型参数

#[batch_impl(<T> FromValue<T> i32 {
    fn wrap(_val: T) -> Self { 0 }
})]
trait FromValue<T> { fn wrap(val: T) -> Self; }

并列列表 + 共享 body

#[batch_impl([usize, isize, f32] {
    fn tag(&self) -> &'static str { "number" }
})]
trait Tagged { fn tag(&self) -> &'static str; }

嵌套泛型合并

use std::collections::HashMap;

#[batch_impl(<T> Describe<T> [Vec<T>, <U> HashMap<T, U>] {
    fn describe(&self) -> String { format!("len={}", self.len()) }
})]
trait Describe<T> { fn describe(&self) -> String; }
// → impl<T>    Describe<T> for Vec<T>
// → impl<T, U> Describe<T> for HashMap<T, U>

关联类型简洁写法

在 trait 泛型参数中使用 Name=value 语法绑定关联类型：

#[batch_impl(<T> Iter<Item=T> Vec<T> {
    fn count(&self) -> usize { self.len() }
})]
trait Iter {
    type Item;
    fn count(&self) -> usize;
}
// → impl<T> Iter for Vec<T> { type Item = T; fn count(&self) -> usize { self.len() } }

支持多关联类型：

#[batch_impl(<T, U> Pair<First=T, Second=U> (T, U))]
trait Pair {
    type First;
    type Second;
}

支持泛型约束：

#[batch_impl(<T: Clone> CloneIter<Item=T> Vec<T> {
    fn first(&self) -> T { self[0].clone() }
})]
trait CloneIter {
    type Item;
    fn first(&self) -> Self::Item;
}

独立/共享 body 合并

列表项可有独立 body，与共享 body 合并：

#[batch_impl(
    [usize { fn name() -> &'static str { "usize" } },
     isize { fn name() -> &'static str { "isize" } }]
    { fn zero() -> Self { 0 } }
)]
trait Zero {
    fn zero() -> Self;
    fn name() -> &'static str;
}
// → impl Zero for usize { fn zero() -> Self { 0 } fn name() -> &'static str { "usize" } }
// → impl Zero for isize { fn zero() -> Self { 0 } fn name() -> &'static str { "isize" } }

纯独立 body（无共享）：

#[batch_impl(
    usize { fn describe(&self) -> String { format!("usize: {}", self) } },
    String { fn describe(&self) -> String { format!("string: {}", self) } }
)]
trait Describe {
    fn describe(&self) -> String;
}

^ 运算符

#[batch_impl([&, Box, Rc]^u32)]
trait RefOrOwned {}

#[batch_impl(HashMap^<u32, String>)]
trait MapMarker {}

元组生成

#[batch_impl(()^4)]
trait TupleTrait {}

#[batch_impl((<Clone>)^6)]
trait CloneTuple {}

// 范围语法
#[batch_impl(()^1..3)]
trait RangeTuple {}

#[batch_impl(()^1..=3)]
trait RangeIncTuple {}

fn 类型

// fn 类型创建
#[batch_impl(fn^(i32, u32))]
trait FnSimple {}

// fn 类型追加返回类型
#[batch_impl(fn(i32, u32)-String)]
trait FnWithReturn {}

// fn 类型批量生成（笛卡尔积）
#[batch_impl(fn-(i32, u32)^2)]
trait FnTupleGen {}
// → impl FnTupleGen for fn(i32, i32) {}
// → impl FnTupleGen for fn(i32, u32) {}
// → impl FnTupleGen for fn(u32, i32) {}
// → impl FnTupleGen for fn(u32, u32) {}

unsafe

// 单个 spec 标记为 unsafe
#[batch_impl(unsafe^usize, isize)]
unsafe trait UnsafePartial {}

// unsafe trait 所有 impl 自动 unsafe
#[batch_impl(usize, Box<u32>)]
unsafe trait UnsafeAll {}

复杂类型透传

#[batch_impl(
    (i32, String),
    &str,
    Box<dyn std::fmt::Display>,
    dyn Fn() + Send + Sync
)]
trait ComplexMarker {}

batch_trait! 宏

对已声明的 trait 批量生成 impl。

use batch_impl::batch_trait;

trait A {}
trait B<T> {}
mod foo { pub trait C {} }

batch_trait!(
    A: usize, isize;
    B: <T> B<T> Vec<T>;
    foo::C: u32;
    unsafe UnsafeTrait: usize
);

语法：Trait路径: impl-specs，; 分隔多个 trait。: 前可加 unsafe 关键字。

设计决策

有意识不支持

  • where 子句：不在 DSL 内。复杂 bound 写在 trait 定义本身
  • 高阶 trait bound（for<'a>）：where 子句式范畴；类型内部 token 透传，无需特殊处理
  • TraitName<>（空尖括号）：视为"trait 无泛型"；无需指定时直接写 TraitName

歧义处理

  • []：有逗号是并列列表，无逗号是切片类型
  • ()：() = 空元组，(A,) = 单元素元组，(A) = 分组
  • [<：Rust 的词法限制，[<Trait>] 中 [< 会被 token 化；拆成独立表达式使用

错误提示

宏对常见错误给出中文提示并指向源码位置：

错误输入 错误信息
#[batch_impl()] batch_impl 至少需要一个类型参数
#[batch_impl(<T> MyTrait<T>)] `MyTrait<...>` 被解析为 trait 泛型参数，但缺少目标类型
#[batch_impl([])] `` 空的 `[]```
#[batch_impl(<T> Vec<T)] 未闭合的 <（有 1 层尖括号未关闭）
#[batch_impl((T)^3)] `(T)` 是分组而非元组，若需单元素元组请写 `(T,)`

优先级

运算符优先级从高到低：

  1. ^（右结合）- 最高优先级
  2. -（左结合）- 中等优先级
  3. ,（分隔符）- 最低优先级

示例：

  • A^B-C,D = (A^B)-C,D = (A<B>)-C,D = A<B,C>,D
  • [A,B]^[C,D]-E = ([A,B]^[C,D])-E = [A<C>,A<D>,B<C>,B<D>]-E
  • HashMap^K-V = (HashMap^K)-V = HashMap<K>-V = HashMap<K, V>
  • fn^(A,B)-C = (fn^(A,B))-C = fn(A,B)->C

注意：Box^Vec-u32 是错误写法（- 会被当作外层 dash），应写为 Box^Vec^u32。

内部原理

解析基于 proc-macro2 的 token tree 迭代器：

  • 逗号切割：仅按顶层 <> 深度判断；()、[]、{} 在 proc-macro2 中是 Group 令牌，内部逗号天然不暴露
  • 泛型参数解析：parse_balanced 做 < > 深度跟踪，支持任意嵌套类型、类型标注、const 泛型
  • 目标类型：原样透传为 TokenStream，不做解析——天然兼容一切合法 Rust 类型
  • span 传播：错误信息和生成代码均保留原始输入位置
  • 递归深度限制：128 层上限防栈溢出
  • 泛型名唯一化：基于 Span 哈希后缀，多个 ()^N 表达式不冲突

许可证

MIT OR Apache-2.0