数据驱动：用一份 YAML 生成中英文简历

路径相对谁，能走多远#

loading.typ 开头那句注释“paths are relative to this file”值得拆开。相对路径是相对调用加载函数的那个 .typ 文件，不是相对你运行 typst 的目录。main.typ 里写 yaml("cv.yaml") 能成功，是因为 cv.yaml 和 main.typ 在同一个目录；lab/ch11/fig-cv.typ 要借同一份数据，就得写 yaml("../../examples/cv/cv.yaml")。

以斜杠开头的路径（/examples/cv/cv.yaml）相对项目根，根由 --root 决定，默认是入口文件所在目录。这就是为什么仓库的所有命令都带 --root .：fig-cv.typ 在 lab/ch11/ 下，要读到 examples/，根必须是仓库顶层。越出根目录的路径是被拒绝的，不是被忽略的，下面 eval 一节我会实测一次。

YAML 解析出来的类型#

写 cv.yaml 时我最担心的是 YAML 的隐式类型：2021-09 会不会变成日期，no 会不会变成 false。我试了一下（/tmp/p11/y/，不在仓库里）：

1
a: 2021-09
2
b: 2021-09-01
3
c: no
4
d: 1.0
5
e: "2021-09"
6
f: present
7
g: 0123
8
h: null

1
#let d = yaml("d.yaml")
2
#for (k, v) in d [
3
  #k: #repr(v) (#type(v)) \
4
]

1
a: "2021-09" (str)
2
b: "2021-09-01" (str)
3
c: "no" (str)
4
d: 1.0 (float)
5
e: "2021-09" (str)
6
f: "present" (str)
7
g: "0123" (str)
8
h: none (type(none))

在 Typst 0.15.1 里，不带引号的日期、no、0123 都是字符串，1.0 是 float，null 是 none。所以 cv.yaml 里 start: "2021-09" 的引号对 Typst 来说不是必须的。我还是留着：这份文件如果换成别的 YAML 工具读，规则可能不同（这一点我没有验证，只是不想让数据对解析器敏感）。

给 lang 加一道检查#

main.typ 把 sys.inputs 里的字符串原样交给 cv(lang:)，所以拼错的语言也会原样进来。cv 的第一行就是对它的检查：

1
  assert(lang in ("zh", "en"), message: "xuan: cv lang must be zh or en")

（它是 cv 函数体里的第一行，完整上下文在下面的 cv.typ 全文里。）我试了 --input lang=fr：

1
$ typst compile --root . --ignore-system-fonts --input lang=fr examples/cv/main.typ /tmp/p11/fr.pdf
2
error: assertion failed: xuan: cv lang must be zh or en
3
   ┌─ @local/xuan:0.1.0/src/cv.typ:61:2
4
   │
5
61 │   assert(lang in ("zh", "en"), message: "xuan: cv lang must be zh or en")
6
   │   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7

8
  while calling `cv` at examples/cv/main.typ:5:1
9
    cv(yaml("cv.yaml"), lang: lang)

错误直接说出了原因，并且指向调用 cv 的那一行。（这一行是后来加的：加之前，同一条命令报的是 cannot add dictionary and string，指到 set document 那一行，因为 tr 在字典里找不到键 fr 时把整个 {zh:, en:} 字典原样返回，后面再拿它做字符串加法才炸。）

它能看到哪些名字#

我最想弄清的是作用域：eval 里能引用我模板里的变量吗？能调用 cv 吗？下面是六个最小实验，放在 /tmp/p11/sc/（不在仓库里），每个文件一行 eval，用同一个脚本编译并打印第一行错误或输出：

1
#let secret = 1
2
#eval("#secret", mode: "markup")

1
#import "@local/xuan:0.1.0": cv
2
#eval("#cv", mode: "markup")

1
#eval("#emph[x] #calc.pow(2, 3) #sys.inputs.len()", mode: "markup")

1
#let secret = 1
2
#eval("#secret", mode: "markup", scope: (secret: secret))

1
#eval("#read(\"s1.typ\")", mode: "markup")

1
#eval("#read(\"../../../../etc/passwd\")", mode: "markup")

脚本是这样的：

1
for f in s1 s2 s3 s4 s5 s6; do
2
  echo "== $f"
3
  if typst compile --root . --ignore-system-fonts $f.typ $f.pdf 2> $f.err; then
4
    echo "ok: $(pdftotext $f.pdf - | head -c 60 | tr '\n' ' ')"
5
  else
6
    head -1 $f.err
7
  fi
8
done

1
== s1
2
error: unknown variable: secret
3
== s2
4
error: unknown variable: cv
5
== s3
6
ok: x80
7
== s4
8
ok: 1
9
== s5
10
ok: #let secret = 1 #eval("#secret", mode: "markup")
11
== s6
12
error: path `"../../../../etc/passwd"` would escape the project root

结论：

• eval 里是一张干净的作用域，只有标准库。 你文件里 #let 的变量（s1）和 #import 进来的名字（s2）都不可见；emph、calc.pow、sys.inputs 这些标准库的东西可见（s3，输出 x、8、0：没传 --input，sys.inputs.len() 是 0）。
• 要让数据看到你的东西，用 scope: 显式递过去。 s4 里 secret 通过 scope: (secret: secret) 才可见。这也解释了为什么 cv.typ 里的 rich 只用 eval(v, mode: "markup") 就够了：简历字符串里只会出现标准库函数（emph、link、数学式），不需要引用模板里的任何名字。
• eval 里的文件读取仍然可用。 s5 里 read("s1.typ") 读到了文件内容。路径相对调用 eval 的那个文件，这一点我也验证了：把 eval 放在 sub/m.typ 里的函数中，主文件调用它去读 h.txt，读到的是 sub/h.txt（内容 in-sub），不是根目录那份 h.txt（内容 in-root）。
• 越出项目根的路径被拒绝。 s6 明确报 would escape the project root，和 --root 的行为是同一套。

风险：别 eval 不是你写的字符串#

由此产生的结论很直接：eval 的字符串等同于你文档里的源码，权限也等同。s5 说明它能读项目根下的任何文件，读出来的内容可以直接排进 PDF；#import、#read、yaml(...) 都是可用的。如果 YAML 来自别人（比如网页表单收集的简历数据，再由服务端调 typst compile），不要对它 eval，要么把字段当纯文本直接 [#field]，要么限制成一个小的、自己写的标记子集。我实测的只有上面几条（读根内文件、不能越根）；至于它能不能被拿来拖死编译，我没有试。顺带一个实测的小保护：eval("#while true {}", mode: "markup") 会被编译器在静态阶段拒绝（error: condition is always true），但这只拦得住最明显的写法，不要把它当防线。

我在 cv.typ 里仍然用了 eval，是因为 cv.yaml 是我自己写的、放在自己的仓库里，信任边界和 .typ 文件一样。

还有一个很实际的体验：YAML 里的标记写错了，错误指向的是 eval 的那一行而不是 YAML 里的那一行。我把 bullet: "提升 *3 倍。"（星号没闭合）放进 bad.yaml 再 eval(d.bullet, mode: "markup")：

1
error: unclosed delimiter
2
  ┌─ bad.typ:2:6
3
  │
4
2 │ #eval(d.bullet, mode: "markup")
5
  │       ^^^^^^^^

所以 cv.yaml 变长以后，出错时要靠 unclosed delimiter 这类描述自己去 YAML 里找。不 eval 的话（只是 #d.bullet 原样显示）同一个字符串编译完全没事。

两个字段解析函数#

1
// One-page CV generated from a dictionary (see examples/cv/cv.yaml).
2
#import "cjk.typ": xuan-cjk
3
#import "fonts.typ": fonts
4

5
// Resolve a field: plain value, or (zh: ..., en: ...) by language.
6
#let tr(field, lang) = {
7
  if type(field) == dictionary and (lang in field) { field.at(lang) } else {
8
    field
9
  }
10
}
11

12
// Strings may carry markup, e.g. "*bold* and #link(...)".
13
#let rich(field, lang) = {
14
  let v = tr(field, lang)
15
  if type(v) == str { eval(v, mode: "markup") } else { v }
16
}

tr 做的是“按语言取值”：如果字段是字典并且含有当前语言这个键，取出来；否则原样返回。lang in field 对字典是测试键。这两个条件合在一起，让纯字符串（如 email）和 {zh:, en:} 都走同一个调用。字典里没有当前语言时它会原样返回整个字典，所以 cv 才需要在入口先 assert 语言合法。

rich 在 tr 之后再判一次类型：只有字符串才 eval，已经是 content 的（比如 link(...)）就不动。这条类型判断保证 rich 对任何字段都安全。模块里的 tr 和第 8 篇 math.typ 导出的 tr（矩阵迹）重名，但 lib.typ 只导出 cv，所以不冲突。

日期与版式小函数#

1
// "2023-09" -> datetime; "present" -> none.
2
#let parse-month(s) = {
3
  if s == "present" { return none }
4
  let (y, m) = s.split("-").map(int)
5
  datetime(year: y, month: m, day: 1)
6
}
7

8
#let fmt-month(s, lang) = {
9
  let d = parse-month(s)
10
  if d == none {
11
    if lang == "zh" { "至今" } else { "Present" }
12
  } else {
13
    d.display("[year].[month]")
14
  }
15
}
16

17
#let date-range(item, lang) = {
18
  fmt-month(item.start, lang) + "–" + fmt-month(item.end, lang)
19
}
20

21
#let section(title) = {
22
  v(0.6em)
23
  text(weight: "bold", size: 1.1em, title)
24
  v(-0.5em)
25
  line(length: 100%, stroke: 0.5pt)
26
  v(-0.2em)
27
}
28

29
// Left: title and role; right: dates.
30
#let entry(left, right, body: none) = {
31
  grid(
32
    columns: (1fr, auto),
33
    left, right,
34
  )
35
  if body != none { body }
36
}

parse-month 是这一篇最典型的“把字符串提升成类型”：s.split("-").map(int) 得到 (2021, 9)，let (y, m) = ... 解构（第 2 篇），day: 1 是因为 datetime 需要一个完整的日期，简历只关心年月。"present" 直接返回 none，fmt-month 再据此显示 至今 / Present。把 "present" 约定成一个关键字而不是写 至今，让 YAML 里的这个字段也不必分语言。

section 里两个负的 v(...) 是把标题和横线收紧，具体数值是仓库里现成的取值，我没有逐个调整来验证它们各自的效果。entry 是两栏 grid，1fr 给标题，auto 给日期，日期因此总是贴右；body: none 的默认值加上 if body != none { body } 让没有正文的条目不多出空白。

bullets 与 set 的作用域#

1
#let bullets(items, lang) = {
2
  set par(first-line-indent: 0pt, justify: false)
3
  list(..items.map(b => rich(b, lang)))
4
}

bullets 里的 set par(...) 只在这个函数体内有效（第 4 篇：作用域是代码块的边界）。xuan-cjk 给中文段落设了两字缩进和两端对齐，对列表项都不合适，所以在这里局部关掉。list(..items.map(...)) 把数组展开成 list 的位置参数，每个元素就是一条列表项，这是第 3 篇 ..args 的反向用法（调用端展开）。

cv 本体#

1
#let cv(data, lang: "zh") = {
2
  assert(lang in ("zh", "en"), message: "xuan: cv lang must be zh or en")
3
  let t(field) = tr(field, lang)
4
  let zh = lang == "zh"
5
  set document(title: t(data.name) + " CV", author: t(data.name))
6
  set page(paper: "a4", margin: (x: 1.8cm, y: 1.5cm))
7
  show: xuan-cjk.with(lang: lang)
8
  set text(size: 10pt)
9
  set par(first-line-indent: 0pt, leading: 0.6em, spacing: 0.7em)
10
  set list(indent: 0.5em, spacing: 0.5em)
11

12
  align(center)[
13
    #text(size: 22pt, weight: "bold", font: fonts.sans, t(data.name))
14
    #v(-0.2em)
15
    #(
16
      link("mailto:" + data.email, data.email),
17
      data.phone,
18
      link("https://" + data.github, data.github),
19
      link("https://" + data.site, data.site),
20
    ).join(h(1em) + "|" + h(1em))
21
  ]
22

23
  section(if zh { "教育经历" } else { "Education" })
24
  for e in data.education {
25
    entry(
26
      [*#t(e.school)*, #t(e.degree)],
27
      date-range(e, lang),
28
      body: if "detail" in e { rich(e.detail, lang) },
29
    )
30
  }
31

32
  section(if zh { "实习经历" } else { "Experience" })
33
  for e in data.experience {
34
    entry(
35
      [*#t(e.org)*, #emph(t(e.role))],
36
      date-range(e, lang),
37
      body: bullets(e.bullets.map(t), lang),
38
    )
39
  }
40

41
  section(if zh { "项目经历" } else { "Projects" })
42
  for e in data.projects {
43
    entry(
44
      [*#t(e.name)*, #emph(t(e.role))],
45
      date-range(e, lang),
46
      body: bullets(e.bullets.map(t), lang),
47
    )
48
  }
49

50
  section(if zh { "技能" } else { "Skills" })
51
  for s in data.skills {
52
    [*#t(s.label)*#if zh [：] else [: ]#rich(s.items, lang) \ ]
53
  }
54
}

几个值得说的设计选择：

cv 是一个普通函数调用，不是 show: 模板。 第 4 篇的 note 接收一个 body 并用 #show: note.with(...) 套在整篇文档上，因为正文是你写的。简历没有正文，输入是一份字典，所以 #cv(yaml("cv.yaml"), lang: lang) 直接生成整页内容。它仍然用 set page、show: xuan-cjk.with(lang: lang)，这些规则落在 cv 的函数体作用域里，调用一次页面就配好一次。

let t(field) = tr(field, lang) 是闭包。 t 捕获了外层的 lang，后面一百多处调用不用再传。这是第 3 篇讲过的闭包捕获；e.bullets.map(t) 里直接把 t 当参数传给 map，也是同一个原因。bullets(...) 之前先把每条 {zh:, en:} 变成字符串，rich 之后再 eval，顺序不能反。

联系方式只拼字符串，不 eval。 email、phone、github、site 都是普通字符串，直接放进 link(...)。邮箱、电话这类字段没有需要格式化的内容，不让它们过 eval 就少一处可能被标记语法误读的地方（这一点是设计上的保守，我没有构造出具体的误读例子）。.join(h(1em) + "|" + h(1em)) 把四个内容用竖线隔开，竖线两侧各 1em 的水平空白。

set document 写入 PDF 元数据。 我用 pdfinfo out/examples/cv.pdf 看了：

1
Title:           张三 CV
2
Author:          张三

英文版则是 Zhang San CV 和 Zhang San。第 16 篇再展开 document 的更多字段。

可选字段用 "detail" in e 判断。 教育条目有 detail，实习条目没有。字典的 in 测试键，body: if "detail" in e { rich(...) } 在条件不成立时整个 if 得到 none（没有 else 的 if 就是这样），正好是 entry 参数 body 的默认值。

技能一节的 \。 [*#t(s.label)*#if zh [：] else [: ]#rich(s.items, lang) \ ] 是一行内容块：粗体标签，中文用全角冒号、英文用半角冒号加空格，然后是 rich 出来的条目，最后用 \ 强制换行。中英文冒号不同，所以用 if zh 在内容里分叉。