YAML – 标量与标签

YAML - 标量和标签

标量（Scalars）是 YAML 的基本构建块，表示独立的数据单元，如字符串（strings）、数字（numbers）和布尔值（booleans）。标签（Tags）用于显式定义标量或任何其他 YAML 节点的类型。

标量（Scalars）

YAML 提供了几种编写标量内容的方式，大致分为块式标量（block scalars，用于多行内容）和流式标量（flow scalars，通常是内联的）。

块式标量（Block Scalars）

块式标量非常适合多行字符串。它们以字面量样式（|）或折叠样式（>）指示符开头。

字面量样式（|）：保留字符串中的所有换行符。块中的每一行都完全按照其显示的方式成为字符串内容的一部分。

ascii_art: |
  \_/
 (o.o)
 > ^ <

# 咬合指示符控制尾部换行符：
# | : 裁剪 (如果内容以换行符结尾，则保留一个尾部换行符；否则不保留)
# |- : 移除 (不保留任何尾部换行符)
# |+ : 保留 (保留所有尾部换行符)

clipped_script: |
  #!/bin/bash
  echo "Hello"

stripped_script: |-
  #!/bin/bash
  echo "Hello"

kept_script: |+
  #!/bin/bash
  echo "Hello"

折叠样式（>）：将段落内的换行符折叠成空格。空行表示段落中断（保留为一个换行符）。缩进比块本身更多的行也保留为换行符。

description: >
  This is a long description
  that will be folded into a
  single line, with newlines
  replaced by spaces.

  However, this new paragraph
  will start on a new line.
    And this line, being more indented,
    will also start on a new line.

# 咬合指示符 (>, >-, >+) 的工作方式与字面量样式类似。

流式标量（内联标量）

流式标量通常用于较短的单行值，但也可以遵循特定规则跨越多行。

普通样式（无引号）：不使用引号编写的字符串。它们不能以某些字符（例如 {}[]&*#?!|->%@、, grave accent）开头，并且必须注意后面跟有空格的冒号（: ）。示例：name: John Doe`
单引号样式（'）：用单引号括起来。允许大部分字符按字面意义表示。内部的单引号通过加倍来转义（''）。处理的转义序列较少。示例：message: 'It''s a beautiful day!'
双引号样式（"）：用双引号括起来。支持 C 风格的转义序列，如 \n（换行符）、\t（制表符）、\\（反斜杠）、\"（双引号）。示例：path: "C:\\Program Files\\My App"

plain_scalar: This is a simple string.
quoted_scalar: "This string can contain \"escaped quotes\" and newlines\nlike this."
single_quoted_scalar: 'This string handles most characters literally, like : { } [ ] - * & #.'
multiline_flow_plain: This unquoted scalar
  spans multiple lines;
  newlines are folded.
multiline_flow_quoted: "So does this\n  quoted scalar, with explicit \\n for newlines."

标签（Tags）

YAML 中的标签显式指定节点的数据类型。虽然 YAML 解析器通常会自动推断类型（例如，将 123 解析为整数，true 解析为布尔值），但标签提供了清晰性或可以覆盖默认行为。标签使用 ! 或 !! 表示。

特定标签：!!int（整数）、!!float（浮点数）、!!str（字符串）、!!bool（布尔值）、!!null（空值）、!!map（映射）、!!seq（序列）。
应用自定义标签：像 !mytype 这样的自定义标签可用于应用特定的数据结构。

YAML 的核心模式（Core Schema）自动解析常见类型：

常见隐式类型标量

以下示例展示了 YAML 通常会解析为标准类型的各种表示形式，无需显式标签。

# 整数
canonical_int: 12345
decimal_positive: +12345
hexadecimal: 0xC_A_F_E # 下划线用于提高可读性，解析为 0xCAFE
octal: 0o14 # 解析为十进制的 12

# 浮点数
canonical_float: 1.23015e+3
exponential_float: 12.3015e+02
fixed_float: 1230.15
negative_infinity: -.inf # 表示负无穷大
not_a_number: .nan # 表示 NaN (非数值)

# 布尔值
is_active: true
is_enabled: false

# 空值
no_value: null
alternate_null: ~

# 字符串（如果需要解决歧义，可显式标记）
# 例如，如果 '12345' 应该始终是字符串：
zip_code: !!str '12345'
version_number: !!str '2.0'

# 日期和时间戳（YAML 核心模式包含对 ISO 8601 的支持）
date: 2023-10-26
timestamp: 2023-10-26T10:20:30.5Z

六十进制（sexagesimal）格式（例如，用于时间或角度的 3:25:45）也是 YAML 扩展标签集的一部分，尽管在没有特定模式配置的情况下并非所有解析器都默认启用它。它常用于时间长度或地理坐标。

理解标量和标签对于准确表示数据并确保 YAML 处理器和应用程序正确解释数据至关重要。