YAML – 语法原语

YAML - 核心语法概念

理解 YAML 的语法原语有助于编写有效且实用的 YAML 文档。本章节深入探讨控制 YAML 如何解析和解释的关键结构和格式规则。

基本结构概念

1. 缩进

缩进是 YAML 定义嵌套和结构的方式。必须使用空格进行缩进，而不是制表符。一个缩进级别所需的空格数在给定块内必须一致，尽管不同的块可以有不同的缩进级别（例如，父级使用 2 个空格，子级可以使用 4 个，但同一级别的所有同级元素必须使用相同的缩进量）。更多缩进意味着更深层次的嵌套。

2. 上下文：块式 vs. 流式风格

YAML 内容可以用两种主要上下文编写：

块式风格：使用缩进来表示结构。对于复杂数据（例如，多行字符串、嵌套映射/序列），通常首选这种风格以提高可读性。
流式风格：使用显式指示符，如用于映射的 {} 和用于序列的 []，类似于 JSON。流式风格更紧凑，常用于简单数据或嵌入小型集合时。

3. 标量风格

标量内容（字符串、数字、布尔值）可以呈现为几种风格：普通（无引号）、单引号、双引号、字面量块（|）和折叠块（>）。每种风格对于处理空白、换行符和特殊字符有不同的规则（详见“标量和标签”章节）。

4. 咬合处理：控制块式标量中的换行符

咬合（Chomping）控制块式标量（字面量 | 和折叠 >）中结尾换行符的处理方式。通过在风格字符后添加指示符（- 或 +）来指定：

裁剪（默认，无指示符或只有 | 或 >）：如果内容中存在一个结尾换行符，则保留一个；否则，不添加换行符。多个结尾换行符会被减少到只剩一个。
移除（|- 或 >-）：移除所有结尾换行符。标量值末尾不会有换行符。
保留（|+ 或 >+）：保留块中所有结尾换行符在标量值中。

咬合处理效果示例：

# Input YAML
clip_example: |
  Line 1
  Line 2

strip_example: |-
  Line 1
  Line 2

keep_example: |+
  Line 1
  Line 2

解析后的字符串值（使用 \n 表示换行符）：

// 对于 clip_example (假设内容以一个换行符结尾)：
// "Line 1\nLine 2\n"

// 对于 strip_example：
// "Line 1\nLine 2"

// 对于 keep_example (假设内容以两个换行符结尾)：
// "Line 1\nLine 2\n\n"

缩进空格

正如强调的，缩进使用空格来定义结构。前导空白的数量决定了项目相对于其父级的嵌套级别。禁止使用制表符进行缩进。

# YAML 文档
level1_key:
  level2_key: # 相对于 level1_key 缩进
    level3_value: "Nested deep"
  another_level2_key: "Sibling to level2_key"
another_level1_key: "Sibling to level1_key"

等效的 JSON 结构：

{
  "level1_key": {
    "level2_key": {
      "level3_value": "Nested deep"
    },
    "another_level2_key": "Sibling to level2_key"
  },
  "another_level1_key": "Sibling to level1_key"
}

分隔空格

YAML 使用空格来分隔 token，例如，在键与其值之间（key: value），或在序列指示符之后（- item）。虽然可以使用多个空格，但通常一个就足够了。与定义结构的缩进空格不同，这些分隔空格通常不属于内容的一部分。

# 正确的分隔
key1: value1
- item1

# 也有效，但不常用
key2   :    value2
-    item2

普通标量中的行折叠

普通（无引号）标量可以跨越多行。YAML 的行折叠规则通常会将普通标量内的单个换行符转换为一个空格。空行（两个换行符）通常会保留为一个单独的换行符，从而有效地创建一个段落中断。这允许编写可读的长字符串，而无需显式的换行符，如 \n。

folded_plain_scalar:
  This is a long sentence
  that continues on the next line.
  It will be parsed as a single line of text.

  This new paragraph, started after a blank line,
  will also be parsed with a newline character preceding it.

folded_plain_scalar 的解析后字符串值：

"This is a long sentence that continues on the next line. It will be parsed as a single line of text.\nThis new paragraph, started after a blank line, will also be parsed with a newline character preceding it."

此行为与字面量块式标量（|）不同，后者保留所有换行符；也与折叠块式标量（>）不同，后者提供对折叠和段落中断更显式的控制。

提示：在编辑器中集成 YAML linter 或验证器可以帮助捕获常见的语法错误，例如与缩进、空格和特殊字符相关的错误，确保您的 YAML 格式良好。