YAML – 字符流

YAML - 流与文档

YAML 将数据处理为字符流（stream of characters），这些字符流可以组织成一个或多个文档（document）。理解这些概念是有效使用 YAML 的关键。主要组成部分包括：

指令（Directives）：给 YAML 解析器的指示。
文档边界标记（Document Boundary Markers）：文档开始和结束的指示符。
文档（Documents）：单一原生数据结构的表示。
完整流（Complete Stream）：代表 YAML 内容的完整字符序列。

本章将详细探讨这些组成部分。

指令

指令（Directives）是给 YAML 解析器的指示。它们不是数据模型本身的一部分，但可以影响 YAML 内容如何被解释。指令以百分号（%）开头，通常位于流或文档的开头。

最常见的指令是 %YAML，它指定文档遵循的 YAML 规范版本。例如：

%YAML 1.2
---
# 本文档符合 YAML 1.2 版本规范
message: "Hello, YAML 1.2!"

如果省略 %YAML 指令，解析器通常会默认使用一个常见版本（例如 YAML 1.2）。虽然存在其他指令，如 %TAG（用于自定义标签缩写），但它们属于更高级的用法，通常在日常 YAML 任务中不需要。

文档边界标记

YAML 允许在单个文件或流中包含多个文档。文档之间通过文档边界标记分隔。文档的开始由三个连字符（---）指示。文档的结束可以可选地由三个点（...）指示。

这是一个包含多个文档的流示例：

%YAML 1.2
---
document_id: 1
content: "First document in the stream."
...
---
# 后续文档如果符合相同版本，则不需要 %YAML 指令。
document_id: 2
content: "Second document."
...
---
document_id: 3
content: "Third document. # 对于最后一个文档，'...' 结束标记是可选的。"

--- 标记对于分隔文档至关重要。... 结束标记在流式传输文档或您想在文件末尾潜在的注释或其他非 YAML 内容之前显式地发出文档结束信号时特别有用。

文档

一个 YAML 文档代表一个单一的原生数据结构，例如一个映射（字典/对象）、一个序列（列表/数组）或一个标量（字符串、数字、布尔值）。表示细节，如注释、缩进样式和指令，不属于反序列化数据本身的一部分，但会指导解析器。

显式文档

显式文档（explicit document）明确地以文档开始标记（---）开头。它也可以可选地以文档结束标记（...）结束。这在流中存在多个文档时很常见。

---
# 这是一个显式文档
project_name: "YAML Revamp Project"
version: 2.0
settings:
  darkMode: true
  notifications: enabled
...

解析后，这段 YAML 通常会生成与以下 JSON 等效的数据结构：

{
  "project_name": "YAML Revamp Project",
  "version": 2.0,
  "settings": {
    "darkMode": true,
    "notifications": "enabled"
  }
}

隐式文档

隐式文档（implicit document）不以 --- 标记开头。这对于单文档 YAML 文件（例如配置文件）非常常见，文件开头就意味着文档的开始。

# 这是一个隐式文档，常用于配置文件
user_preferences:
  theme: dark
  language: en
  notifications:
    email: true
    sms: false

这将解析成一个等效于以下内容的数据结构：

{
  "user_preferences": {
    "theme": "dark",
    "language": "en",
    "notifications": {
      "email": true,
      "sms": false
    }
  }
}

完整流

YAML 流（stream）是被处理的全部 YAML 内容，从头到尾。它可以选择以字节顺序标记（Byte Order Mark, BOM）开头，用于指示字符编码（强烈推荐并广泛支持 UTF-8）。流随后可能包含指令，后跟一个或多个文档。注释几乎可以出现在任何地方，并被解析器忽略，不影响最终的数据结构。

一个完整流的示例：

# 可选：字节顺序标记（通常在文本编辑器中不可见）
# 流开头的注释
%YAML 1.2
---
message: "Hello from the YAML stream!"
# 第一个文档结束
...
---
# 同一流中第二个文档开始
data_points:
  - 10
  - 20
  - 30
# 注释也可以出现在这里

处理 YAML 文件时，您通常是在处理一个可能包含一个或多个文档的单一流。理解这些结构元素有助于调试问题和创建结构良好、易于维护的 YAML。为了全面理解，官方 YAML 规范（例如 1.2 版）是一个极好的资源。您通常可以通过搜索“YAML 1.2 specification”找到它。