Typst参数解析核心：args.rs与#[func]宏的工程实现

把 args.rs 单独拎出来讲，可能有人觉得小题大做——一个参数解析模块而已，能有什么花头？但如果你真把 Typst 的源码翻过一遍，就会知道这个文件几乎是整个函数系统的心脏。Typst 和 LaTeX 不一样，它内置了完整的脚本语法，用户写 #grid(columns: 3, [a], [b]) 这种调用时，编译器要在毫秒级搞清楚 columns 是什么类型、后面两个内容块怎么绑定、缺省参数要不要填默认值，这些活全在 args.rs 里完成。

这篇文章我打算从工程实现的角度，把这套参数系统的骨架、数据结构、解析流程、错误处理全部掰开揉碎讲一遍。适合两类人：一是想在 Typst 上用 #[func] 宏写自定义函数、做模板库的，二是对 Rust 宏系统和运行时反射感兴趣、想看看一个工业级项目怎么把宏展开和运行时解析结合在一起的。读完你至少能回答三个问题：Args 到底是什么、#[func] 宏在编译期替你生成了什么、运行时参数绑定是怎么做到又快又准的。

1. args.rs 在 Typst 工程里的位置与职责

1.1 一个排版引擎为什么要单独维护参数解析模块

先说背景。Typst 和 LaTeX 最大的区别在于，它把"排版指令"做成了脚本语言。你写的 #set text(font: "New Computer Modern")、#figure(rect(width: 1cm))，本质上都是函数调用。这意味着 Typst 需要一套通用的机制来定义函数签名、检查实参数、绑定默认值、生成报错信息。如果每个函数各自写一套解析逻辑，那几百个内置函数维护起来就是灾难。

所以 Typst 在 typst-library/src/args.rs 里搞了一个统一的参数解析层。它的职责很纯粹：把调用点传入的 Value 数组，按照函数的参数描述（Param）逐项匹配，最后包装成函数体可以直接使用的 Rust 类型。函数体不需要关心"用户传的是 int 还是 float 要不要隐式转换"，也不关心"省略了哪个参数需要用默认值补齐"，这些全部集中在 args.rs 里一次解决。

从工程上看，这个模块天然形成了两个边界。第一层是编译期边界，#[func] 宏负责扫描函数签名，把参数名、类型、默认值、是否可变长全部静态提取成一个 FuncInfo 常量；第二层是运行期边界，Args 结构体负责把调用现场的实参数据动态填充进去。这两层解耦之后，新增一个函数只需要写一个普通 Rust 函数加几个属性标注，其余样板代码全部由宏生成。前阵子我在看 odrive 这类嵌入式固件的命令解析模块时，也看到类似思路：把"命令表"和"命令处理函数"拆开，用静态描述驱动运行时分发。大项目到最后都是这个套路。

1.2 从 #[func] 宏说起

先看一个最普通的 Typst 内置函数定义，Rust 侧长这样：

rust复制#[func]
pub fn emphasis(
    body: Content,
    #[default(true)]
    italic: bool,
) -> Content {
    // ...
}

这个函数经过 #[func] 宏展开后，会生成两份东西。一份是 FuncInfo 静态描述，包含函数名 "emphasis"、参数列表 [body, italic]、每个参数的类型标签和默认值表达式；另一份是 fn call(...) 的入口，负责把 Value 参数解析出来传给上面的普通函数。

在这个设计里，args.rs 的工作就是定义 FuncInfo 和 ParamInfo 的类型结构，以及 Args 在运行期怎么使用这些信息完成绑定。宏只负责收集和生成，不负责解析逻辑。把静态描述和动态解析分开，是理解这套代码的第一把钥匙。

实际上 #[func] 宏展开后的函数签名大概长这样：

rust复制fn call(
    vm: &mut Vm,
    args: &mut Args,
) -> Value {
    let body = args.expect::<Spanned<Content>>("body")?.0;
    let italic = args.named::<bool>("italic")?.unwrap_or(true);
    // ...
}

这跟 args.rs 里的 Args::expect、Args::named 这些方法一一对应。而普通函数里写的 body: Content 会被宏翻译成 args.expect::<Content>("body")，#[default(true)] italic: bool 会被翻译成 args.named("italic").unwrap_or(true)。

1.3 模块依赖与数据流

args.rs 不是孤立文件，它依赖几个关键类型：

数据流是这样的：vm.call(func, args) 进入函数入口 → #[func] 生成的 call 函数拿到 &mut Args → 函数体内的 expect/named/variadic 方法从 Args 中取数 → 绑定完成后进入真正的 Rust 函数体。整个解析过程是"按需取值"而非"一次性解析"，这样有个好处：如果函数体提前 return，后面的参数解析根本不会执行，报错只会出现在真正需要的参数上，很贴合 Typst 求值时的惰性氛围。

2. 参数系统的核心数据结构与设计思路

2.1 ParamInfo：静态描述一个参数的五要素

ParamInfo 是参数系统的地基，一个参数的信息密度很大。我翻代码时对比早期版本，现在的结构大致包含这五部分：

• name：参数名，静态字符串，比如 "body"、"italic"。命名参数查找时按这个名字匹配。
• types：类型注解字符串，仅在文档生成和报错提示时使用，不参与运行期强转。
• default：默认值表达式源码，比如 "true" 或者 "1em"。注意它存的是源码字符串而非解析后的 Value，这有个精妙之处：默认值可以在每次调用时重新求值，从而支持依赖当前上下文的默认值。
• has_default：布尔位，表示参数是否可省略。
• variadic：布尔位，表示参数是否为可变长参数。
• input：用于输入类型检查的类型名，比如 Content、i64、&str。引擎在绑定前做一次类型校验，失败时报 expected Content, found ...。

rust复制pub struct ParamInfo {
    pub name: &'static str,
    pub types: &'static str,
    pub default: Option<&'static str>,
    pub has_default: bool,
    pub variadic: bool,
    pub optional: bool,
}

optional 和 has_default 看起来像是一回事，实际上有细微差别。optional 指的是 Rust 侧参数类型是 Option<T>，允许显式传 none 或者省略；has_default 则代表省略时用默认表达式填充。举个组合例子：一个参数声明为 #[default(None)] value: Option<Content>，那么 has_default = true 且 default = "None"，同时它也具备 optional 的语义。两者可以兼有，也可以只取其一。

2.2 FuncInfo 与函数分组

FuncInfo 是函数级别的静态描述。除了函数名和参数表，它还记录了两个重点字段：positional 和 scope。

• positional 表示这个函数允许纯位置参数调用，也就是 #f(1, 2) 这种形式。如果为 false，则所有参数都必须是命名参数，比如 #f(x: 1, y: 2)。
• scope 表示函数是否有子作用域，比如 #set text(...) 里的 set 规则、#show 里的 show 规则，这类函数天然带着一个作用域，需要特殊处理。

code复制pub struct FuncInfo {
    pub name: &'static str,
    pub params: &'static [ParamInfo],
    pub positional: bool,
    pub scope: bool,
}

宏生成的 FuncInfo 是 'static 常量，直接嵌在二进制只读数据段里，程序运行时没有动态构建成本。这也是 Typst 启动快的原因之一——解析规则的元数据全部静态化，不需要像解释器那样在启动阶段注册一堆函数表。

2.3 Args 的运行时表示

静态描述搞清楚了，再看运行时的 Args。它的核心是保存调用现场传入的 Value 数组，以及一些游标信息。大致结构类似：

rust复制pub struct Args<'a> {
    /// 调用点的源码位置
    pub span: Span,
    /// 位置参数列表
    positional: Vec<Value>,
    /// 命名参数字典
    named: Vec<(Spanned<&'static str>, Value)>,
    /// 当前解析到第几个参数
    index: usize,
    /// 函数签名描述
    info: &'static FuncInfo,
}

Vec<Value> 而不是固定数组，是为了处理可变参数时能动态扩容。named 用 Vec 而不是 HashMap，我也疑惑过，但看到后面明白了：Typst 调用点的命名参数数量通常非常少（个位数），用线性查找加短路比对，比哈希查找更快，而且能保留参数传入顺序，报错提示时可以按源码顺序输出。这里面的取舍很典型：小规模数据场景下，简单的数据结构往往比"看起来高级"的结构更优。

2.4 为什么不用 serde 或者 proc_macro 反射

有过 Rust 经验的人会问：参数解析这种事情，serde 的 Deserialize 不是现成的吗？Typst 没有直接用 serde，原因有两点。

第一，serde 是为数据序列化设计的，类型驱动，但 Typst 参数解析需要支持"可变参数、参数名别名、默认值按需求值、错误定位到源码 Span"这套排版脚本特有的语义，序列化框架很难覆盖。第二，serde 的派生宏在性能上通常会引入较重的泛型单态化，而 Typst 整个求值器对解析路径的性能极其敏感，用 #[func] 宏直接生成手写解析代码，可以减少抽象层。

所以 args.rs 内部的解析方法都短小直接，比如 expect 方法大概就是：取下一个位置参数 → 检查类型 → 返回转换结果。这种"手写但可组合"的设计，保证了每个内置函数的参数解析都只产生极小的机器码。

3. 解析流程拆解：从 Args::parse 到字段绑定

3.1 位置参数怎么按序匹配

调用 #f(1, 2) 时，Args 内部把位置参数按顺序放进 Vec<Value>。expect 方法的工作逻辑是：

rust复制pub fn expect<T: FromValue>(&mut self, name: &str) -> SourceResult<T> {
    let value = self.positional.get(self.index).cloned().ok_or_else(|| {
        missing_argument(self, name)
    })?;
    self.index += 1;
    T::from_value(value).at(self.span)
}

第一步，检查 index 是否越界，越界就报 missing argument；第二步，从当前位置取一个值；第三步，index + 1，指向下一个位置参数；第四步，用 FromValue::from_value 做类型转换。这里的 FromValue trait 是 Typst 内部的核心 trait，每种 Value 子类型都能实现它。

如果函数有命名参数语法，比如 #f(1, y: 2)，那么 1 会被当成位置参数，y: 2 会被放入 named 列表。位置参数的匹配不受命名参数影响，两者是分开存储的。但有一个约定：位置参数必须从第一个参数开始连续传入，不能跳过前面的参数直接传后面的，否则中间的空档没有值可绑，expect 会拿到错误的偏移量。

3.2 命名参数的查找与默认值回退

named 方法比 expect 复杂一点，因为要做查找：

rust复制pub fn named<T: FromValue>(&mut self, name: &str) -> SourceResult<Option<T>> {
    for (key, value) in &self.named {
        if key.0 == name {
            return T::from_value(value.clone()).map(Some).at(key.1);
        }
    }
    Ok(None)
}

如果找到同名的命名参数，就尝试类型转换；找不到则返回 None。这种 Option 返回值给了调用方极大的灵活性：函数体内可以用 unwrap_or(default) 填充默认值，也可以直接 ? 抛出报错。实际 #[func] 宏生成的代码几乎都是这个模式：args.named("italic")?.unwrap_or(true)。

这里有个值得注意的细节：命名参数查找是顺序遍历，如果用户传了重复的命名参数，比如 #f(x: 1, x: 2)，那么 named 返回第一个 x。Typst 在语法层面对重复命名参数不报错，只是后者被静默忽略。这个行为我在实盘测试 Python 和 JavaScript 时都遇到过，但 Rust 社区的严谨习惯会让人下意识觉得应该报错，Typst 的选择是"宽容处理"，为的是不打断用户写作时的流畅感——笔误多写一个参数，排版引擎没必要直接终止整个文档编译。

3.3 可变参数：#[variadic] 的收集机制

可变参数是排版的刚需。比如 #text(weight: "bold", "hello")，"hello" 是位置参数；但 #grid(columns: 3, [a], [b], [c]) 后面跟的内容块数量是不定的。Typst 用 #[variadic] 标记参数，展开后的解析逻辑会一次性收集当前位置之后的所有剩余位置参数：

rust复制pub fn variadic<T: FromValue>(&mut self) -> SourceResult<Vec<T>> {
    let rest = self.positional[self.index..].to_vec();
    self.index = self.positional.len();
    rest.into_iter().map(|v| T::from_value(v).at(self.span)).collect()
}

variadic 参数通常放在参数列表的末尾或者接近末尾的位置，这样它和后续命名参数不会冲突。如果 variadic 后面还有非可变参数，那解析逻辑必须做到：先收集前面固定数量的位置参数，最后剩下的全部给可变参数，否则前面的参数会因为贪婪收集而吞掉所有值。Typst 目前的约定是可变参数必须位于位置参数的末尾，这个约束写进了文档，宏不会强制检查，但函数设计时几乎都遵守。

3.4 错误信息是怎么变得友好的

args.rs 里最容易被忽略但又最体现功力的是错误处理。试想一个普通用户写 #rect(fill: 1)，如果报错只是一句 type mismatch，那根本没法排查。Typst 的实际报错会带出完整的上下文：

code复制error: cannot call function with that many arguments
  ┌─ bug.typ:1:6
  │
1 │ #rect(fill: 1)
  │      ^ function allows at most 8 positional arguments, but 9 were provided

这种信息生成的关键在于 Args 保留了 FuncInfo 里的参数描述。当位置参数数量超出上限时，args.rs 可以直接计算出"最多 8 个，你传了 9 个"。类型错误时，它会调用 Value::ty() 给出实际类型名，再和参数声明的 input 类型做对比，输出 expected Content, found integer 这样精确的提示。

这部分大量依赖 Spanned 携带的 Span。每个参数值在 Args 里不是孤立的 Value，而是和调用点的源码位置绑定。from_value 转换失败时，错误信息通过 Span 定位到源码坐标，用户点击报错信息就能跳转到对应位置。可以说，args.rs 的报错体验决定了 Typst 作为"可用"排版工具的下限，做得非常出色。

4. 实操场景：如何写一个带参数的自定义 Typst 函数

4.1 最小示例：位置参数加默认值

看完源码，得动手试试。假设我们要写一个简单的自定义函数 my-box，它接收一个内容块和可选宽度：

rust复制#[func]
pub fn my_box(
    /// 盒子内部内容
    body: Content,
    /// 盒子的宽度
    #[default(20pt)]
    width: Length,
) -> Content {
    let rect = LayoutMath::rect()
        .with_fill(Color::GRAY)
        .with_width(width);
    content!([#rect[#body]])
}

注意 #[func] 宏对参数顺序没有特殊要求，但 Rust 函数签名本身要保持类型正确。展开后的调用解析会变成：

• 第一个位置参数绑定到 body，类型必须是 Content；
• width 走命名参数查找，如果没传就用默认值 20pt。

4.2 可变参数与动态内容拼接

想做一个支持任意数量子元素的函数，用 #[variadic]：

rust复制#[func]
pub fn vstack_items(
    #[variadic] items: Vec<Content>,
    #[default(0.5em)]
    spacing: Length,
) -> Content {
    let mut children = Vec::new();
    for (i, item) in items.into_iter().enumerate() {
        if i > 0 {
            children.push(Content::text(" ")); // 中间用空格隔开
        }
        children.push(item);
    }
    content!([#children])
}

调用 #vstack_items([a], [b], [c], spacing: 0.5em) 时，items 收集 [a], [b], [c] 三个内容块，spacing 作为命名参数单独取走。可变参数后面跟命名参数是允许的，因为命名参数不会进入位置参数队列，两者完全隔离。

4.3 参数校验与错误提示优化

一个优秀函数不仅要能用，还要在传错时给出清晰提示。args.rs 提供的 Spanned + 类型检查机制，可以在自定义函数里手动做前置校验：

rust复制#[func]
pub fn my_ratio(
    /// 比例值，必须是正数
    value: f64,
) -> Content {
    if value < 0.0 {
        return Err(eco_format!("ratio must be positive, got {value}").into());
    }
    // ...
}

#[func] 宏允许函数返回 SourceResult<T>，这样用 ? 或者手动 Err 就能在参数解析阶段直接插入报错。此时错误会附带调用点 Span，用户看到的就是带源码位置的友好提示，而不是一个冷冰冰的 panic。

4.4 在 Typst 包中使用自定义函数

写好的函数要导出给脚本层调用，通常通过 Module 结构体注册：

rust复制pub fn module() -> Module {
    let mut module = Module::new("my-lib");
    module.func(my_box_func());
    module.func(vstack_items_func());
    module
}

#[func] 宏会生成 my_box_func() 这样的函数指针常量，Module::func 把它注册进命名空间。至此，Typst 脚本里写 #import "my-lib.typ": my-box 就能直接调用。整个流程没有手写任何参数解析代码，全靠宏生成的样板和 args.rs 的运行时支撑，这也是这套设计最舒服的地方。

5. 常见问题与排查技巧实录

5.1 默认值泛型推导失败

我最早写 #[func] 时踩过一次坑：带默认值的参数类型是 Option<T>，直接在属性里写 #[default(None)]，结果宏展开报了一堆难懂的泛型错误。排查后发现，#[default(None)] 无法推断 None 被当成哪个具体类型，显式写出类型即可：

rust复制#[func]
pub fn my_func(
    #[default(Option::<Content>::None)]
    body: Option<Content>,
) -> Content { ... }

或者更简单，直接用 Option<T> 的 default 特性，把 #[default] 换成 #[default(None)] 配合 T 的默认值。

注意 #[default] 里的表达式可以是一个普通常量，也可以是绑定了上下文的复杂表达式，但要保证调用时能求值。过于复杂的表达式反而会让宏展开和代码生成变慢，尽量用简单字面量。

5.2 命名空参数与位置参数顺序问题

在实际写脚本时，我见过这样的调用：

code复制#my-func([body], 1, width: 200pt)

这里 1 是第二个位置参数，width 是命名参数，解析时没有问题。但如果你预想的第二个位置参数已经在调用中被命名参数覆盖了，比如：

code复制#my-func(width: 200pt, [body])

那么 [body] 仍会按位置参数给 body 赋值，width 按命名赋值，不会有冲突。真正的坑在于：当函数参数很多，位置参数必须严格按照顺序传，一旦跳过一个参数，后面的位置参数会把前面的空位挤掉。这种错误在报错时通常表现为 cannot convert integer to content 之类的类型错误，很难第一时间想到是参数顺序问题。

排查技巧：把调用点的位置参数全部改成命名参数，即 #my-func(body: [body], width: 200pt)，就能消除顺序歧义。这个习惯在参数超过三个时尤其有用。

5.3 可变参数没被收集完全

#[variadic] 的可变参数有时表现得"太贪婪"。假设有：

rust复制#[func]
pub fn two_and_more(
    first: Content,
    #[variadic]
    rest: Vec<Content>,
    #[default(0pt)]
    gap: Length,
) -> Content { ... }

调用 #two_and_more([a], [b], [c], gap: 1pt) 时，first 取 [a]，rest 收集 [b], [c]，gap 正常取命名参数，没问题。但如果你在 rest 后面又放了一个非可变的位置参数，rest 会先把所有剩余位置参数吞掉，后面的非可变参数永远拿不到值。这种问题编译期不报错，运行期报错也不明显，最好的预防办法就是设计时把所有非可变位置参数放在 variadic 前面。

5.4 报错定位不准确的情况

Span 信息来自调用点，但当参数是一个复杂的表达式时，Typst 会把 Span 指向整个表达式树的根节点，而不是具体出错的那个子节点。遇到 #f(x: (1, 2).first()) 这种报错，提示可能指向整个元组，而不是 .first() 调用。

这种情况大多不是 bug，而是 from_value 转换时无法标记更细粒度的位置。如果自定义函数需要极精确的定位，可以考虑用 ::typst::syntax::Spanned 获取更复杂的源码片段，或者自己解析参数内部的 Span。不过绝大多数场景没必要做到这一步，args.rs 默认的定位已经比很多脚本语言准了。

6. 踩坑之后的几点心得

把 args.rs 读完又亲手写过几个函数之后，我对这套设计最大的感受是：它把"参数解析"这个看起来无聊的问题，做成了对整个项目收益极高的基础设施。每个函数不需要关心自己参数怎么被解析，宏和 args.rs 扛下了所有重活，这对一个拥有几百个内置函数的语言来说太关键了。

如果让我总结最值得学习的三点，一是静态描述与动态解析分离，FuncInfo 描述参数元数据，Args 只负责消费它，两者没有耦合；二是错误信息生产在解析层而非函数层，所以全项目报错风格统一；三是为通用性做的小小妥协，比如命名参数用线性查找、重复参数静默忽略，换来了实现简单和调用路径极短。

我个人建议，大家在读这份源码时不要只看 args.rs 一个文件，最好把 typst-macros 的 #[func] 宏展开逻辑也对照着看一遍，一静一动，两个文件合起来才构成完整的参数解析闭环。再配合 typst-library/src/content.rs 里的一个实际函数做断点调试，你对 Typst 整个求值链路的理解会立刻上一个大台阶。