Learn X in Y minutes 荷兰语 YAML 教程:从标量、集合到锚点与标签的完整语法精讲

原创2026-10-08 16:07:511,829 阅读
文章标签:文档教程

Learn X in Y minutes 荷兰语 YAML 教程:从标量、集合到锚点与标签的完整语法精讲

本篇围绕 nl/yaml.md 讲解 YAML 数据序列化语言的核心语法:标量类型、多行文本块、集合类型、锚点/别名、显式标签以及日期与二进制等扩展类型。该文档是 Learn X in Y minutes(learnxinyminutes-docs)仓库中的一篇荷兰语教程,全文以一份可直接运行的完整 YAML 示例为主体,配合中文注解逐段展开;读完后你能掌握 YAML 的完整书写范式,并了解本仓库如何使用 YAML frontmatter 与 lint 脚本管理全部文档。

教程定位与文档结构

nl/yaml.md 与英文版 yaml.md 属于同一篇教程的双语版本。英文版头部 frontmatter 声明了文章元数据:

name: YAML
filename: learnyaml.yaml
contributors:
  - [Leigh Brenecki, 'https://leigh.net.au']

而荷兰语版只保留了 contributors 与 translators 两个字段(译者为 Niels van Velzen 与 Sam van Kampen)。这一做法符合 CONTRIBUTING.md 中“非英文文章继承英文文章的 frontmatter 值,但可以覆盖”的约定。

教程的开头两句话概括了 YAML 的语言定位:

  • YAML 是一种为人类直接读写而设计的数据序列化语言;
  • 它是 JSON 的严格超集,像 Python 一样引入了语法上有意义的换行与缩进;
  • 与 Python 不同的是,YAML 不允许使用制表符(Tab)缩进。

教程主体是一个从标量到集合再到扩展功能的完整 YAML 文档,下面按文档脉络逐节展开。

标量类型(SCALAIRE TYPES)

文档说明注释以 # 开头,根对象是一张 map(等价于其他语言的 dictionary、hash 或 object):

# Commentaar in YAML ziet er zo uit
sleutel: waarde
nog_een_sleutel: Een andere waarde
nummer_waarde: 100
wetenschappelijke_waarde: 1e+12
boolean_waarde: true
null_waarde: null
sleutel met spaties: waarde

几个要点:

  • 数字可以写普通整数(100)或科学计数法(1e+12);
  • 布尔与空值直接写 true、false、null;
  • 字符串不必加引号,但也可以加;键(key)同样可以加引号,这在键中包含冒号等字符时非常有用:
quote_waarde: "Een string in quotes"
"Ook sleutels kunnen in quotes": "Dit is bijvoorbeeld handig als je een dubbelepunt wilt gebruiken in je key"

英文版 yaml.md 在标量部分还有若干荷兰语版未覆盖的细节,值得补充:

hex_notation: 0x123  # evaluates to 291
octal_notation: 0123 # evaluates to 83
another_null_value: ~
no: no            # evaluates to false
enclosed: "yes"   # evaluates to the string "yes"

即:YAML 还支持十六进制与八进制数字字面量;~ 是 null 的等价写法;yes/no(不分大小写)会被解析为布尔值,若想要字面字符串必须加引号。单引号内只有 '' 一种转义方式,双引号则支持 \t、\u263A、\r\n 等完整转义序列。

多行文本:字面块(|)与折叠块(>)

多行文本有两种写法:字面块用 |,换行原样保留;折叠块用 >,行内换行被替换为空格,空行转为一个换行符:

letterlijk_blok: |
    Dit hele blok met tekst is de waarde van de 'letterlijk_blok'-sleutel,
    met nieuwe lijnen behouden.

    Het blok blijft door gaan tot het geeindigd wordt door korter in te springen.

        Lijnen die groter zijn ingesprongen behouden dit.
gevouwen_stijl: >
    Dit blok met tekst zal de waarde zijn van 'gevouwen_stijl',
    maar deze keer zullen alle nieuwe lijnen worden vervangen met een spatie.

    Lege lijnen, zoals hierboven, zullen worden vertaald naar een nieuwe lijn.

规则总结:

  • 块文本一直延续到缩进变浅为止(de-dent);
  • 缩进更深的行会保留额外缩进,字面块中保留换行,折叠块中保留换行但其余行合并。

英文版还介绍了 chomping 指示符,控制块尾部空行的处理:|- / >- 去除尾部空行(strip),|+ / >+ 保留尾部空行(keep),默认行为(不加指示符)是保留最后一个换行。例如:

literal_strip: |-
  This entire block of text will be the value of the 'literal_strip' key,
  with trailing blank line being stripped.
block_keep: >+
  This entire block of text will be the value of the 'block_keep' key,
  with trailing blank line being kept.

集合类型(COLLECTIETYPES)

嵌套 map 与非字符串键

嵌套完全靠缩进表达(推荐 2 空格缩进,但非强制):

geneste_map:
    sleutel: waarde
    andere_sleutel: andere waarde
    andere_geneste_map:
        hallo: wereld

# In een map hoeft de sleutel geen string te zijn.
0.25: een float als sleutel

map 的键不必是字符串——0.25 就是一个浮点键。

复杂键:? 显式键语法

键本身也可以是多行复合对象,用 ? 表示键的开始,: 后跟值:

? |
    Dit is een sleutel
    met meerdere lijnen
: en dit is de waarde

荷兰语版在此提醒:YAML 甚至允许用集合做键,但“许多编程语言的解析器会对此抱怨”。英文版给了一个用序列做键的例子(键是 [Manchester United, Real Madrid],值是两个日期的序列),并注明部分语言解析器不支持。

序列(sequence)

序列等价于列表/数组,- 本身计入缩进:

een_sequence:
    - Item 1
    - Item 2
    - 0.5 # sequences kunnen meerdere typen waardes bevatten.
    - Item 4
    - sleutel: waarde
      andere_sleutel: andere waarde
    -
        - Dit is een sequence
        - in een andere sequence

要点:

  • 序列元素可以是任意混合类型(字符串、数字、map);
  • 列表项可以直接嵌套列表;
  • 英文版的补充写法是嵌套序列指示符可以折叠为一行:- - - Nested sequence indicators。

JSON 风格的行内写法

因为 YAML 是 JSON 的超集,map 和序列可以直接按 JSON 风格行内书写:

json_map: {"sleutel": "waarde"}
json_seq: [3, 2, 1, "takeoff"]

额外 YAML 功能:锚点、别名与合并键

Anchors(锚点)与别名

锚点让你把文档某处的值复制到别处,& 定义锚点,* 引用:

geankert_content: &anker_naam Deze string zal verschijnen als waarde voor de twee sleutels
andere_anker: *anker_naam

两个键将拥有同一份值。

英文版进一步演示了用锚点实现属性继承,并引入了 << 合并键(Merge Key):

base: &base
  name: Everyone has same name

foo:
  <<: *base # doesn't merge the anchor
  age: 10
  name: John
bar:
  <<: *base # base anchor will be merged
  age: 20

<<: *base 表示把 base map 的所有键插入当前 map;若当前 map 已存在同名键,则别名不会被合并覆盖——因此 foo 的 name 保持 John,而 bar 的 name 被合并为 Everyone has same name。

显式标签(Tags)

标签用于显式声明值类型,语法为 !![typeName] [value]:

expliciete_string: !!str 0.5
# Sommige parsers gebruiken taalspecifieke tags, zoals deze voor Python's
# complexe nummertype:
python_complex_nummer: !!python/complex 1+2j

!!str 0.5 强制把 0.5 解释为字符串。语言特定标签(如 !!python/complex)由具体解析器实现。英文版列出了完整的标准标签集:!!bool、!!int、!!float、!!str、!!timestamp、!!null,并演示了用语言特定标签构造复合键(? !!python/tuple [ 5, 7 ],在 Python 中等价于字典键 (5, 7))。

额外 YAML 类型:日期、二进制与集合

ISO 日期与日期时间

字符串和数字之外,YAML 直接解析 ISO 格式的日期/时间字面量:

datumtijd: 2001-12-15T02:59:43.1Z
datumtijd_met_spaties: 2001-12-14 21:59:43.10 -5
datum: 2002-12-14

支持 T 分隔的规范格式、空格分隔格式(可带时区偏移 -5),以及纯日期。英文版补充了显式写法 date_explicit: !!timestamp 2002-12-14。

二进制数据:!!binary

!!binary 标签声明字符串是 base64 编码的二进制 blob——教程用一个 GIF 文件作为例子(base64 内容解码后以 GIF 头 R0lGOD 开头,即以 GIF8 起始的图像数据):

gif_bestand: !!binary |
    R0lGODlhDAAMAIQAAP//9/X17unp5WZmZgAAAOfn515eXvPz7Y6OjuDg4J+fn5
    ...

集合(set)

YAML 的 set 类型用 ? 列出元素:

set:
    ? item1
    ? item2
    ? item3

本质上就是值为 null 的 map,等价于:

set2:
    item1: null
    item2: null
    item3: null

英文版还给出了集合的行内写法 or: { item1, item2, item3 }。

仓库如何消费 YAML:frontmatter 与 lint 管线

本仓库的每篇文档(包括 nl/yaml.md 自身)都以 YAML frontmatter 开头,仓库提供了一套专门的校验工具链来保证这些 YAML 片段的合法性——这恰好是“YAML 作为配置文件格式”的实战印证。

frontmatter 的字段契约

CONTRIBUTING.md 定义了 frontmatter 的字段约定:

  • 必需(英文文章):name(语言名)、contributors([作者, URL] 列表,URL 可选);
  • 可选:category(默认为 language)、filename(用于把文中代码打包为可下载文件);
  • 翻译文章还需包含 translators。

从 lint/frontmatter.py 的 allowed_keys 字典(lint/frontmatter.py#L80-L87)可以看到完整的合法键集合:

allowed_keys = {
    "name": str,
    "where_x_eq_name": str,
    "category": str,
    "filename": str,
    "contributors": list,
    "translators": list,
}

CONTRIBUTING.md 中的 Ruby 示例头部即按此格式书写:

---
name: Ruby
filename: learnruby.rb
contributors:
    - ["Doktor Esperanto", "http://example.com/"]
    - ["Someone else", "http://someoneelseswebsite.com/"]
---

解析、lint 与键校验的实现

lint/frontmatter.py 的工作流程分三步:

  1. 提取:extract_yaml_frontmatter 用正则 ^(---\s*\n.*?\n)---\n(DOTALL 模式)从 Markdown 文件头部匹配出 frontmatter 块(lint/frontmatter.py#L10-L17);
  2. lint:把提取出的 YAML 交给 yamllint,使用 extends: default 但禁用 commas、trailing-spaces、indentation、line-length、empty-lines 五条规则——因为文档 frontmatter 的行长和缩进风格由人工维护,不适合一刀切(lint/frontmatter.py#L20-L31);
  3. 键校验:validate_yaml_keys 调用 yaml.safe_load 解析,检查是否存在未声明的键、各键类型是否匹配,并对 contributors/translators 这类列表做逐元素校验——每个元素必须是长度 1 或 2 的列表,item<a href="https://link.gitcode.com/i/9ce692439724146115845ef8d2d1f44e" target="_blank">0] 必须是字符串,item[1](若存在)也必须是字符串([lint/frontmatter.py#L42-L69)。

依赖仅两个库,见 lint/requirements.txt:yamllint 与 pyyaml。

值得注意的印证点:nl/yaml.md 的 frontmatter 里 contributors 使用了 ["Leigh Brenecki", "https://github.com/adambrenecki"] 这种两元素列表、translators 是嵌套列表——正是上述逐元素校验所期望的结构;而它省略了 name/filename,因为继承自英文版 yaml.md 的 name: YAML、filename: learnyaml.yaml。

编码约束

lint/encoding.sh 则负责编码层面:用 file -b --mime-encoding 检查所有 *.md 文件必须是 UTF-8 或 US-ASCII,并且 UTF-8 文件不得带 BOM(通过 head -c 3 比对 \xEF\xBB\xBF 字节序列判定)。这与 CONTRIBUTING.md 风格指南中“Use UTF-8”的要求一一对应。这也解释了为什么教程中的荷兰语字符(如 kopieëren)都能安全出现在文档中。

荷兰语版与英文版的差异速查

对比 nl/yaml.md 与 yaml.md,翻译版保留了全部核心章节骨架(标量 → 集合 → 额外功能 → 额外类型),但精简了以下细节,深入学习时建议对照英文版:

主题 荷兰语版 英文版补充
数字字面量 整数、科学计数法 十六进制 0x123、八进制 0123
布尔/空值 true / null yes/no 解析为布尔、~ 表示 null、引号转义规则
块标量 | 与 > `
锚点 基本锚点与别名 << 合并键与覆盖语义
标签 !!str、!!python/complex 完整标准标签集、复合键标签
集合 ? item 写法 行内集合 { item1, item2 }
文档边界 无 --- 文档开始、... 文档结束标记

小结与延伸阅读

nl/yaml.md 用一份 130 余行的自包含 YAML 示例,串起了 YAML 的完整语法面:缩进驱动的嵌套结构、|/> 块标量、混合类型序列、锚点/别名复用、显式类型标签、日期时间字面量、base64 二进制与集合。它的写法——“以有效代码为教程正文”——正是 README.md 中对本仓库的定位:Whirlwind tours ... presented as valid, commented code and explained as they go。

可进一步深入的路径:

按 CONTRIBUTING.md 的说明,本地构建站点需要克隆网站仓库并将本仓库嵌套到 source/docs/ 下,pip install -r requirements.txt 后运行 python build.py,再用 python -m http.server 查看生成结果。

登录后查看全文
learnxinyminutes-docs