YAML 快速指南

---

---

YAML – 简介

YAML Ain't Markup Language 是一种数据序列化语言，符合用户对数据的期望。它旨在易于人类理解，并与其他编程语言完美配合。它可用于管理数据，并包含 Unicode 可打印字符。本章将为您介绍 YAML 并让您了解其功能。

格式

考虑以下文本：

Quick brown fox jumped over the lazy dog.

此文本的 YAML 表示形式如下：

yaml.load(Quick brown fox jumped over the lazy dog.)
>>'Quick brown fox jumped over the lazy dog.'

请注意，YAML 将值作为字符串格式处理，并如上所述表示输出。

示例

让我们借助以下示例了解 YAML 中的格式：

考虑以下圆周率“pi”的值为 3.1415926。在 YAML 中，它表示为如下所示的浮点数：

>>> yaml.load('3.1415926536')
3.1415926536

假设要将多个值加载到如下所示的特定数据结构中：

eggs
ham
spam
French basil salmon terrine

当您将其加载到 YAML 中时，这些值将以数组数据结构（一种列表形式）的形式处理。输出如下所示：

>>> yaml.load('''
   - eggs
   - ham
   - spam
   - French basil salmon terrine
   ''')
['eggs', 'ham', 'spam', 'French basil salmon terrine']

功能

YAML 包含一种标记语言，具有重要的结构，用于区分面向数据语言和文档标记。YAML 的设计目标和功能如下：

• 匹配敏捷方法及其语言（如 Perl、Python、PHP、Ruby 和 JavaScript）的原生数据结构

• YAML 数据可在编程语言之间移植

• 包含一致的数据模型

• 易于人工阅读

• 支持单向处理

• 易于实现和使用

YAML – 基础

现在您已经了解了 YAML 及其功能，让我们学习其语法和其他操作的基础知识。请记住，YAML 包含一种易于阅读的结构化格式。

创建 YAML 文件的规则

创建 YAML 文件时，应记住以下基本规则：

• YAML 区分大小写

• 文件应以 .yaml 为扩展名

• 创建 YAML 文件时，YAML 不允许使用制表符；允许使用空格

YAML 文件的基本组件

YAML 的基本组件如下所述：

常规块格式

此块格式使用 连字符+空格 在指定的列表中开始新项目。请观察以下示例：

--- # Favorite movies
 - Casablanca
 - North by Northwest
 - The Man Who Wasn't There

内联格式

内联格式用 逗号和空格 分隔，项目用 JSON 括起来。请观察以下示例：

--- # Shopping list
   [milk, groceries, eggs, juice, fruits]

折叠文本

折叠文本将换行符转换为空格，并删除前导空格。请观察以下示例：

- {name: John Smith, age: 33}
- name: Mary Smith
  age: 27

遵循 YAML 所有基本约定的结构如下所示：

men: [John Smith, Bill Jones]
women:
  - Mary Smith
  - Susan Williams

YAML 基本元素概要

• YAML 基本元素的概要如下：YAML 中的注释以 (#) 字符开头。

• 注释必须用空格与其他标记分隔。

• 空格缩进用于表示结构。

• 制表符不包含在 YAML 文件的缩进中。

• 列表成员以一个前导连字符 (-) 表示。

• 列表成员用方括号括起来，并用逗号分隔。

• 关联数组使用冒号 ( : ) 以键值对的形式表示。它们用花括号 {} 括起来。

• 具有单个流的多个文档用 3 个连字符 (---) 分隔。

• 每个文件中重复的节点最初用一个与号 (&) 表示，以后用星号 (*) 标记。

• YAML 始终需要冒号和逗号作为列表分隔符，后跟空格和标量值。

• 节点应使用感叹号 (!) 或双感叹号 (!!) 标记，后跟可以扩展为 URI 或 URL 的字符串。

YAML – 缩进和分隔

学习任何编程语言时，缩进和分隔是两个主要概念。本章将详细介绍与 YAML 相关的这两个概念。

YAML 的缩进

YAML 不包含任何强制空格。此外，无需保持一致。有效的 YAML 缩进如下所示：

a:
   b:
      - c
      -  d
      - e
f:
      "ghi"

• 使用 YAML 中的缩进时，应记住以下规则：流块必须至少使用一些空格与周围的当前块级别缩进。

• YAML 的流内容跨越多行。流内容的开头以 { 或 [ 开头。

• 块列表项与周围的块级别具有相同的缩进，因为 - 被视为缩进的一部分。

缩进块的示例

观察以下显示带示例的缩进的代码：

--- !clarkevans.com/^invoice
invoice: 34843
date   : 2001-01-23
bill-to: &id001
   given  : Chris
   family : Dumars
   address:
      lines: |
            458 Walkman Dr.
            Suite #292
      city    : Royal Oak
      state   : MI
      postal  : 48046
ship-to: *id001
product:
    - sku         : BL394D
      quantity    : 4
      description : Basketball
      price       : 450.00
   - sku         : BL4438H
      quantity    : 1
      description : Super Hoop
      price       : 2392.00
tax  : 251.42
total: 4443.52
comments: >
    Late afternoon is best.
    Backup contact is Nancy
    Billsmer @ 338-4338.

字符串分隔

使用双引号字符串分隔字符串。如果转义给定字符串中的换行符，则将其完全删除并转换为空格值。

示例

在此示例中，我们重点介绍了作为数组结构列出的动物列表，其数据类型为字符串。每个新元素都以连字符作为前缀列出。

-
 - Cat
 - Dog
 - Goldfish
-
 - Python
 - Lion
 - Tiger

另一个解释 YAML 中字符串表示的示例如下所示。

 errors:
      messages:
         already_confirmed: "was already confirmed, please try signing in"
         confirmation_period_expired: "needs to be confirmed within %{period}, please request a new one"
         expired: "has expired, please request a new one"
         not_found: "not found"
         not_locked: "was not locked"
         not_saved:
            one: "1 error prohibited this %{resource} from being saved:"
            other: "%{count} errors prohibited this %{resource} from being saved:"

此示例指的是用户只需提及关键方面即可使用的错误消息集，并相应地获取值。此 YAML 模式遵循 JSON 的结构，对于 YAML 新手来说很容易理解。

YAML – 注释

既然您已经熟悉了 YAML 的语法和基础知识，让我们进一步深入了解其细节。在本章中，我们将了解如何在 YAML 中使用注释。

YAML 支持单行注释。其结构将通过以下示例进行解释：

# this is single line comment.

YAML 不支持多行注释。如果要为多行提供注释，您可以按照以下示例所示进行操作：

# this
# is a multiple
# line comment

注释的功能

YAML 中注释的功能如下：

• 在执行过程中会跳过注释块。

• 注释有助于为指定的代码块添加说明。

• 注释不能出现在标量内。

• YAML 没有办法转义井号 (#)，因此在多行字符串中，无法将注释与原始字符串值分开。

集合中的注释如下所示：

key: #comment 1
   - value line 1
   #comment 2
   - value line 2
   #comment 3
   - value line 3

YAML 块注释的快捷键组合是 Ctrl+Q。

如果您使用的是 Sublime Text 编辑器，则注释块的步骤如下：

选择块。在 Linux 和 Windows 上使用“CTRL + /”，在 Mac 操作系统上使用“CMD+/”。执行块。

请注意，如果您使用的是 Visual Studio Code 编辑器，则相同的步骤也适用。始终建议使用 Sublime Text 编辑器 创建 YAML 文件，因为它受大多数操作系统支持，并包含对开发人员友好的快捷键。

YAML – 集合和结构

YAML 包含使用缩进表示作用域的块集合。在此，每个条目都以新行开头。集合中的块序列用 连字符和空格 (-) 表示每个条目。在 YAML 中，块集合样式不用任何特定指示符表示。YAML 中的块集合可以通过识别其中包含的键值对将其与其他标量量区分开来。

映射表示 JSON 结构中包含的键值。它经常用于多语言支持系统和移动应用程序中 API 的创建。映射使用键值对表示法，使用 冒号和空格 (:)。

示例

考虑一个标量序列的示例，例如如下所示的棒球运动员列表：

- Mark Joseph
- James Stephen
- Ken Griffey

以下示例显示将标量映射到标量：

hr: 87
avg: 0.298
rbi: 149

以下示例显示将标量映射到序列：

European:
- Boston Red Sox
- Detroit Tigers
- New York Yankees

national:
- New York Mets
- Chicago Cubs
- Atlanta Braves

集合可用于序列映射，如下所示：

-
   name: Mark Joseph
   hr: 87
   avg: 0.278
-
   name: James Stephen
   hr: 63
   avg: 0.288

对于集合，YAML 包含使用显式指示符而不是使用缩进来表示空间的流样式。集合中的流序列被写成用方括号括起来的逗号分隔列表。最适合在 PHP 框架（如 symphony）中包含的集合的说明。

[PHP, Perl, Python]

这些集合存储在文档中。YAML 中文档的分隔用三个连字符或短划线 (---) 表示。文档的结尾用三个点 (...) 标记。

YAML 中文档的分隔用三个短划线 (---) 表示。文档的结尾用三个点 (...) 表示。

文档表示称为结构格式，如下所示：

# Ranking of 1998 home runs
---
- Mark Joseph
- James Stephen
- Ken Griffey 

# Team ranking
---
- Chicago Cubs
- St Louis Cardinals

问号与空格的组合表示结构中的复杂映射。在一个块集合中，用户可以使用连字符、冒号和问号包含结构。以下示例显示序列之间的映射：

- 2001-07-23
? [ New York Yankees,Atlanta Braves ]
: [ 2001-07-02, 2001-08-12, 2001-08-14]

YAML – 标量和标签

YAML 中的标量使用文字类型（表示为 (|)）的块格式编写。它表示换行符计数。在 YAML 中，标量以折叠样式 (>) 编写，其中每一行都表示一个折叠空格，该空格以空行或缩进更多的行结尾。

文字中保留换行符，如下所示：

ASCII Art
--- |
\//||\/||
// || ||__

对于缩进更多的行和空行，折叠的换行符将保留，如下所示：

>
Sammy Sosa completed another
fine season with great stats.
63 Home Runs
0.288 Batting Average
What a year!

YAML 流标量包括纯样式和引号样式。双引号样式包含各种转义序列。流标量可以包含多行；换行符在此结构中始终被折叠。

plain:
This unquoted scalar
spans many lines.
quoted: "So does this
quoted scalar.\n"

在 YAML 中，未标记的节点使用特定类型的应用程序指定。标签规范的示例通常使用seq、map和str类型表示 YAML 标签存储库。标签表示为如下所示的示例：

整数标签

这些标签包含整数数值。它们也称为数字标签。

canonical: 12345
decimal: +12,345
sexagecimal: 3:25:45
octal: 014
hexadecimal: 0xC

浮点数

这些标签包含十进制和指数值。它们也称为指数标签。

canonical: 1.23015e+3
exponential: 12.3015e+02
sexagecimal: 20:30.15
fixed: 1,230.15
negative infinity: -.inf
not a number: .NaN

其他标签

它包含各种嵌入其中的整数、浮点数和字符串值。因此，它被称为其他标签。

null: ~
true: y
false: n
string: '12345'

YAML –完整示例

下面的完整示例指定了YAML的结构，其中包括符号和各种表示形式，这在将YAML转换为JSON格式或处理JSON格式时将非常有用。这些属性在JSON文档中也称为键名。这些表示法是为了安全目的而创建的。

上述YAML格式表示defaults、adapter和host的各种属性以及其他属性。YAML还会记录生成的每个文件，跟踪生成的错误消息。将指定的YAML文件转换为JSON格式后，我们将得到如下所示的所需输出：

defaults: &defaults
   adapter:  postgres
   host:     localhost

development:
   database: myapp_development
   <<: *defaults

test:
   database: myapp_test
   <<: *defaults

让我们将YAML转换为JSON格式并检查输出。

{
   "defaults": {
      "adapter": "postgres",
      "host": "localhost"
   },
   "development": {
      "database": "myapp_development",
      "adapter": "postgres",
      "host": "localhost"
   },
   "test": {
      "database": "myapp_test",
      "adapter": "postgres",
      "host": "localhost"
   }
}

带有“<<: *”前缀的defaults键根据需要包含，无需重复编写相同的代码片段。

YAML - 处理过程

YAML遵循标准的流程处理程序。YAML中的原生数据结构包括简单的表示形式，例如节点。它也称为表示节点图。

它包括映射、序列和标量量，这些量被序列化以创建一个序列化树。通过序列化，对象将转换为字节流。

序列化事件树有助于创建字符流的表示，如下图所示。

反向过程将字节流解析为序列化事件树。之后，节点将转换为节点图。这些值随后转换为YAML原生数据结构。下图对此进行了说明：

YAML中的信息以两种方式使用：**机器处理**和**人工阅读**。YAML中的处理器用作在上面所示图表中转换互补视图之间信息的工具。本章描述了YAML处理器必须在给定应用程序中提供的信​​息结构。

YAML包含一个序列化过程，用于以串行格式表示数据对象。YAML信息的处理包括三个阶段：**表示、序列化、呈现和解析**。让我们详细讨论每个阶段。

表示

YAML使用三种节点来表示数据结构：**序列、映射**和**标量**。

序列

序列指的是有序的条目数，它映射键值对的无序关联。它对应于Perl或Python的数组列表。

下面显示的代码是序列表示的示例：

product:
   - sku         : BL394D
     quantity    : 4
     description : Football
     price       : 450.00
   - sku         : BL4438H
     quantity    : 1
     description : Super Hoop
     price       : 2392.00

映射

另一方面，映射表示字典数据结构或哈希表。下面提到了一个相同的例子：

batchLimit: 1000
threadCountLimit: 2
key: value
keyMapping: <What goes here?>

标量

标量表示字符串、整数、日期和原子数据类型的标准值。请注意，YAML还包含指定数据类型结构的节点。有关标量的更多信息，请参阅本教程的第6章。

序列化

YAML需要序列化过程，这简化了对人友好的键顺序和锚点名称。序列化的结果是YAML序列化树。可以遍历它以产生一系列YAML数据的事件调用。

下面给出了一个序列化示例：

consumer:
   class: 'AppBundle\Entity\consumer'
   attributes:
      filters: ['customer.search', 'customer.order', 'customer.boolean']
   collectionOperations:
      get:
         method: 'GET'
         normalization_context:
       groups: ['customer_list']
   itemOperations:
      get:
         method: 'GET'
         normalization_context:
            groups: ['customer_get']

呈现

YAML序列化的最终输出称为呈现。它以对人友好的方式表示字符流。YAML处理器包含各种呈现细节，用于创建流、处理缩进和格式化内容。这个完整的过程由用户的偏好引导。

YAML呈现过程的一个示例是创建的JSON值的输出结果。观察下面给出的代码以更好地理解：

{
   "consumer": {
      "class": "AppBundle\\Entity\\consumer",
      "attributes": {
         "filters": [
            "customer.search",
            "customer.order",
            "customer.boolean"
         ]
      },
      "collectionOperations": {
         "get": {
            "method": "GET",
            "normalization_context": {
               "groups": [
                  "customer_list"
               ]
            }
         }
      },
      "itemOperations": {
         "get": {
            "method": "GET",
            "normalization_context": {
               "groups": [
                  "customer_get"
               ]
            }
         }
      }
   }
}

解析

解析是呈现的逆过程；它包含一系列字符并创建一系列事件。它丢弃了呈现过程中引入的细节，这些细节导致序列化事件。由于输入格式错误，解析过程可能会失败。它基本上是一个检查YAML是否格式良好的过程。

考虑下面提到的YAML示例：

---
   environment: production
   classes:
      nfs::server:
         exports:
            - /srv/share1
            - /srv/share3
   parameters:
      paramter1

三个连字符表示文档的开始，后面定义了各种属性。

YAML lint是YAML的在线解析器，有助于解析YAML结构以检查其是否有效。YAML lint的官方链接如下：http://www.yamllint.com/

您可以看到如下所示的解析输出：

YAML - 信息模型

本章将详细解释我们在上一章中讨论的过程和步骤。YAML中的信息模型将使用特定的图表以系统化的格式指定序列化和呈现过程的特性。

对于信息模型，重要的是要表示可以在编程环境之间移植的应用程序信息。

上图表示以图形格式表示的普通信息模型。在YAML中，原生数据的表示是根植的、连接的，并且是标记节点的有向图。如果我们提到有向图，它包括一组具有有向图的节点。如信息模型中提到的，YAML支持三种类型的节点，即：

• 序列
• 标量
• 映射

这些表示节点的基本定义已在上一章中讨论过。在本章中，我们将重点关注这些术语的示意图。下面的序列图表示带有各种类型标签和映射节点的图例的工作流程。

共有三种类型的节点：**序列节点、标量节点**和**映射节点**。

序列

序列节点遵循顺序架构，并包含零个或多个节点的有序序列。YAML序列可以重复包含相同的节点或单个节点。

标量

YAML中标量的内容包括Unicode字符，可以用一系列零的格式表示。一般来说，标量节点包含标量量。

映射

映射节点包括键值对表示。映射节点的内容包括键值对的组合，其中必须维护键名唯一。序列和映射共同构成一个集合。

请注意，如上图所示，标量、序列和映射以系统化的格式表示。

YAML - 语法字符

各种类型的字符用于各种功能。本章详细介绍了YAML中使用的语法，并重点介绍字符操作。

指示符字符

指示符字符包括用于描述YAML文档内容的特殊语义。下表对此进行了详细说明。

下面的示例显示了语法中使用的字符：

%YAML 1.1
---
!!map {
   ? !!str "sequence"
   : !!seq [
      !!str "one", !!str "two"
   ],
   ? !!str "mapping"
   : !!map {
      ? !!str "sky" : !!str "blue",
      ? !!str "sea" : !!str "green",
   }
}

# This represents
# only comments.
---
!!map1 {
   ? !!str "anchored"
   : !local &A1 "value",
   ? !!str "alias"
   : *A1,
}
!!str "text"

YAML - 语法基元

在本章中，您将学习YAML中语法基元的以下方面：

• 生产参数
• 缩进空格
• 分隔空格
• 忽略的行前缀
• 折行

让我们详细了解每个方面。

生产参数

生产参数包括一组参数和允许值的范围，这些值用于特定生产。YAML中使用以下生产参数列表：

缩进

它由字符**n**或**m**表示。字符流取决于其中包含的块的缩进级别。许多产品都对这些特性进行了参数化。

上下文

它由**c**表示。YAML支持两组上下文：**块样式**和**流样式**。

样式

它由s表示。标量内容可以以五种样式之一呈现：**普通、带双引号和带单引号的流、文字和折叠块。**

截断

它由**t**表示。块标量提供许多机制，有助于修剪块：**去除、剪辑**和**保留**。截断有助于格式化换行符字符串。它用于块样式表示。截断过程借助指示符进行。指示符控制应使用字符串的换行符产生什么输出。换行符使用**(-)**运算符删除，并使用**(+)**运算符添加换行符。

下面显示了一个截断过程的示例：

strip: |-
   text↓
clip: |
   text↓
keep: |+
   text↓

解析指定的YAML示例后的输出如下：

缩进空格

在YAML字符流中，缩进定义为由零个或多个字符组成的换行符。最重要的是要注意，缩进不能包含任何制表符。缩进中的字符绝不能被视为节点内容信息的一部分。观察以下代码以更好地理解：

%YAML 1.1
---
!!map {
   ? !!str "Not indented"
   : !!map {
      ? !!str "By one space"
      : !!str "By four\n spaces\n",
      ? !!str "Flow style"
      : !!seq [
         !!str "By two",
         !!str "Still by two",
         !!str "Again by two",
      ]
   }
}

缩进后可以看到的输出如下：

{
   "Not indented": {
      "By one space": "By four\n spaces\n", 
      "Flow style": [
         "By two", 
         "Still by two", 
         "Again by two"
      ]
   }
}

分隔空格

YAML使用空格字符分隔标记。最重要的是要注意，YAML中的分隔符不应包含制表符。

以下代码行显示了分隔空格的使用：

{ · first: · Sammy, · last: · Sosa · }

上面显示的语法会给出以下输出

{
   "\u00b7 last": "\u00b7 Sosa \u00b7", 
   "\u00b7 first": "\u00b7 Sammy"
}

忽略的行前缀

空前缀始终包含取决于标量类型的缩进，其中还包括前导空格。普通标量不应包含任何制表符。另一方面，带引号的标量可能包含制表符。块标量完全取决于缩进。

以下示例以系统化的方式显示了忽略行前缀的工作原理：

%YAML 1.1
---
!!map {
   ? !!str "plain"
   : !!str "text lines",
   ? !!str "quoted"
   : !!str "text lines",
   ? !!str "block"
   : !!str "text·®lines\n"
}

块流实现的输出如下：

{
   "plain": "text lines", 
   "quoted": "text lines", 
   "block": "text\u00b7\u00aelines\n"
}

折行

折行允许换行长行以提高可读性。较多的短行意味着更好的可读性。通过注意长行的原始语义来实现折行。以下示例演示了折行：

%YAML 1.1
--- !!str
"specific\L\
trimmed\n\n\n\
as space"

您可以看到以JSON格式进行折行的输出如下：

"specific\u2028trimmed\n\n\nas space"

YAML - 字符流

在YAML中，您会遇到以下各种字符流：

• 指令
• 文档边界标记
• 文档
• 完整流

在本章中，我们将详细讨论它们。

指令

指令是在YAML处理器中使用的基本指令。指令是表示细节（如注释），这些细节不会反映在序列化树中。在YAML中，无法定义私有指令。本节讨论各种类型的指令以及相关的示例：

保留指令

保留指令以三个连字符（---）开头，如下面的示例所示。保留指令将转换为JSON的特定值。

%YAML 1.1
--- !!str
"foo"

YAML指令

YAML指令是默认指令。如果转换为JSON，则获取的值在其前导字符和终止字符中包含正斜杠字符。

%YAML 1.1
---
!!str "foo"

文档边界标记

YAML 使用这些标记允许在一个流中包含多个文档。这些标记特别用于传达 YAML 文档的结构。请注意，以“---”开头的行用于开始一个新的文档。

以下代码通过示例对此进行了说明：

%YAML 1.1
---
!!str "foo"
%YAML 1.1
---
!!str "bar"
%YAML 1.1
---
!!str "baz"

文档

YAML 文档被认为是呈现为单个根节点的单个原生数据结构。YAML 文档中的表示细节，例如指令、注释、缩进和样式，不被视为其中包含的内容。

YAML 中使用两种类型的文档。本节将对它们进行解释：

显式文档

它以文档开始标记开头，然后是根节点的表示。YAML 显式声明的示例如下所示：

---

some: yaml

...

它包含显式的开始和结束标记，在本例中为“---”和“...” 。将指定的 YAML 转换为 JSON 格式后，我们将得到如下所示的输出：

{
   "some": "yaml"
}

隐式文档

这些文档不以文档开始标记开头。请观察以下代码：

fruits:
   - Apple
   - Orange
   - Pineapple
   - Mango

将这些值转换为 JSON 格式，我们将得到如下所示的简单 JSON 对象：

{
   "fruits": [
      "Apple",
      "Orange",
      "Pineapple",
      "Mango"
   ]
}

完整流

YAML 包含一个称为字符流的字节序列。流以包含字节顺序的 (表示字符编码) 前缀开头。完整的流以包含字符编码的前缀开头，后跟注释。

完整流 (字符流) 的示例如下所示：

%YAML 1.1
---
!!str "Text content\n"

YAML - 节点属性

每个表示节点包含两个主要特征，称为锚点和标签。节点属性可以与节点内容一起指定，也可以从字符流中省略。

节点表示的基本示例如下：

%YAML 1.1
---
!!map {
   ? &A1 !!str "foo"
   : !!str "bar",
   ? !!str &A2 "baz"
   : *a1
}

节点锚点

锚点属性表示一个节点以供将来参考。YAML 表示中节点的字符流用＆号 (&)指示符表示。YAML 处理器不需要保留与其中组合的表示细节一起的锚点名称。以下代码对此进行了说明：

%YAML 1.1
---
!!map {
   ? !!str "First occurence"
   : &A !!str "Value",
   ? !!str "Second occurence"
   : *A
}

使用锚点节点生成的 YAML 输出如下所示：

---
!!map {
   ? !!str "First occurence"
   : !!str "Value",
   ? !!str "Second occurence"
   : !!str "Value",
}

节点标签

标签属性表示原生数据结构的类型，该类型完整地定义了一个节点。标签用 (!) 指示符表示。标签被认为是表示图的固有部分。以下示例详细解释了节点标签：

%YAML 1.1
---
!!map {
   ? !<tag:yaml.org,2002:str> "foo"
   : !<!bar> "baz"
}

节点内容

节点内容可以用流内容或块格式表示。块内容扩展到行尾，并使用缩进表示结构。每种集合类型都可以以特定的单流集合样式表示，或者可以视为单个块。以下代码详细解释了这一点：

%YAML 1.1
---
!!map {
   ? !!str "foo"
   : !!str "bar baz"
}

%YAML 1.1
---
!!str "foo bar"

%YAML 1.1
---
!!str "foo bar"

%YAML 1.1
---
!!str "foo bar\n"

YAML - 块标量头

在本章中，我们将重点介绍用于表示内容的各种标量类型。在 YAML 中，注释可以位于标量内容之前或之后。重要的是要注意，注释不应包含在标量内容中。

请注意，所有流标量样式都可以包含多行，但不能在多个键中使用。

标量的表示如下所示：

%YAML 1.1
---
!!map {
   ? !!str "simple key"
   : !!map {
      ? !!str "also simple"
      : !!str "value",
      ? !!str "not a simple key"
      : !!str "any value"
   }
}

块标量头的生成输出如下所示：

{
   "simple key": {
      "not a simple key": "any value", 
      "also simple": "value"
   }
}

文档标记标量内容

本例中的所有字符都被视为内容，包括内部空格字符。

%YAML 1.1
---
!!map {
   ? !!str "---"
   : !!str "foo",
   ? !!str "...",
   : !!str "bar"
}

%YAML 1.1
---
!!seq [
   !!str "---",
   !!str "...",
   !!map {
      ? !!str "---"
      : !!str "..."
   }
]

普通换行符用以下示例表示：

%YAML 1.1
---
!!str "as space \
trimmed\n\
specific\L\n\
none"

相同的 JSON 输出如下所示：

"as space trimmed\nspecific\u2028\nnone"

YAML - 流样式

YAML 中的流样式可以被认为是 JSON 的自然扩展，用于涵盖折叠内容行以获得更好的可读性功能，该功能使用锚点和别名来创建对象实例。在本章中，我们将重点介绍以下概念的流表示：

• 别名节点
• 空节点
• 流标量样式
• 流集合样式
• 流节点

别名节点的示例如下所示：

%YAML 1.2
---
!!map {
   ? !!str "First occurrence"
   : &A !!str "Foo",
   ? !!str "Override anchor"
   : &B !!str "Bar",
   ? !!str "Second occurrence"
   : *A,
   ? !!str "Reuse anchor"
   : *B,
}

上面代码的 JSON 输出如下所示：

{
   "First occurrence": "Foo", 
   "Second occurrence": "Foo", 
   "Override anchor": "Bar", 
   "Reuse anchor": "Bar"
}

内容为空的节点被认为是空节点。以下示例显示了这一点：

%YAML 1.2
---
!!map {
   ? !!str "foo" : !!str "",
   ? !!str "" : !!str "bar",
}

JSON 中空节点的输出表示如下：

{
   "": "bar", 
   "foo": ""
}

流标量样式包括双引号、单引号和平面类型。相同的基本示例如下所示：

%YAML 1.2
---
!!map {
   ? !!str "implicit block key"
   : !!seq [
      !!map {
         ? !!str "implicit flow key"
         : !!str "value",
      }
   ]  
}

上面示例的 JSON 格式输出如下所示：

{
   "implicit block key": [
      {
         "implicit flow key": "value"
      }
   ] 
}

YAML 中的流集合在一个流集合中嵌套了一个块集合。流集合条目以逗号 (,) 指示符结尾。以下示例详细解释了流集合块：

%YAML 1.2
---
!!seq [
   !!seq [
      !!str "one",
      !!str "two",
   ],
   
   !!seq [
      !!str "three",
      !!str "four",
   ],
]

JSON 中流集合的输出如下所示：

[
   [
      "one", 
      "two"
   ], 
   [
      "three", 
      "four"
   ]
]

像 JSON 这样的流样式包含开始和结束指示符。唯一没有任何属性的流样式是纯标量。

%YAML 1.2
---
!!seq [
!!seq [ !!str "a", !!str "b" ],
!!map { ? !!str "a" : !!str "b" },
!!str "a",
!!str "b",
!!str "c",]

以上代码的 JSON 格式输出如下所示：

[
   [
      "a", 
      "b"
   ], 
   
   {
      "a": "b"
   }, 
   
   "a", 
   "b", 
   "c"
]

YAML - 块样式

YAML 包含两种块标量样式：文字和折叠。块标量由一些指示符控制，这些指示符在内容本身之前有一个标题。块标量头的示例如下所示：

%YAML 1.2
---
!!seq [
   !!str "literal\n",
   !!str "·folded\n",
   !!str "keep\n\n",
   !!str "·strip",
]

具有默认行为的 JSON 格式输出如下所示：

[
   "literal\n", 
   "\u00b7folded\n", 
   "keep\n\n", 
   "\u00b7strip"
]

块样式的类型

有四种类型的块样式：文字、折叠、保留和去除样式。这些块样式是在块切除场景的帮助下定义的。块切除场景的示例如下所示：

%YAML 1.2
---
!!map {
   ? !!str "strip"
   : !!str "# text",
   ? !!str "clip"
   : !!str "# text\n",
   ? !!str "keep"
   : !!str "# text\n",
}

您可以看到使用三种格式生成的 JSON 输出，如下所示：

{
   "strip": "# text", 
   "clip": "# text\n", 
   "keep": "# text\n"
}

YAML 中的切除控制最终换行符和尾随空行，这些换行符和空行以各种形式解释。

去除

在这种情况下，最终换行符和空行将从标量内容中排除。它由切除指示符“-”指定。

裁剪

如果没有指定显式切除指示符，则裁剪被认为是默认行为。最终换行符将保留在标量的内容中。上面示例中演示了裁剪的最佳示例。它以换行符“\n”字符结尾。

保留

保留是指添加“+”切除指示符的表示。创建的附加行不受折叠的影响。附加行不受折叠的影响。

YAML - 序列样式

要理解序列样式，重要的是要理解集合。集合和序列样式的概念并行工作。YAML 中的集合用正确的序列样式表示。如果要引用标签的正确顺序，请始终参考集合。YAML 中的集合由从零开始的连续整数索引，如数组中所示。序列样式的重点从集合开始。

示例

让我们考虑宇宙中行星的数量作为一个序列，可以将其创建为一个集合。以下代码显示了如何表示宇宙中行星的序列样式：

# Ordered sequence of nodes in YAML STRUCTURE
Block style: !!seq
- Mercury   # Rotates - no light/dark sides.
- Venus     # Deadliest. Aptly named.
- Earth     # Mostly dirt.
- Mars      # Seems empty.
- Jupiter   # The king.
- Saturn    # Pretty.
- Uranus    # Where the sun hardly shines.
- Neptune   # Boring. No rings.
- Pluto     # You call this a planet?
Flow style: !!seq [ Mercury, Venus, Earth, Mars,      # Rocks
                    Jupiter, Saturn, Uranus, Neptune, # Gas
                    Pluto ]                           # Overrated

然后，您可以看到 JSON 格式的有序序列的以下输出：

{
   "Flow style": [
      "Mercury", 
      "Venus", 
      "Earth", 
      "Mars", 
      "Jupiter", 
      "Saturn", 
      "Uranus", 
      "Neptune", 
      "Pluto"
   ], 
   
   "Block style": [
      "Mercury", 
      "Venus", 
      "Earth", 
      "Mars", 
      "Jupiter", 
      "Saturn", 
      "Uranus", 
      "Neptune", 
      "Pluto"
   ]
}

YAML - 流映射

YAML 中的流映射表示键值对的无序集合。它们也称为映射节点。请注意，应保持键的唯一性。如果流映射结构中键重复，则会生成错误。键顺序在序列化树中生成。

示例

流映射结构的示例如下所示：

%YAML 1.1
paper:
   uuid: 8a8cbf60-e067-11e3-8b68-0800200c9a66
   name: On formally undecidable propositions of  Principia Mathematica and related systems I.
   author: Kurt Gödel.
tags:
   - tag:
      uuid: 98fb0d90-e067-11e3-8b68-0800200c9a66
      name: Mathematics
   - tag:
      uuid: 3f25f680-e068-11e3-8b68-0800200c9a66
      name: Logic

JSON 格式中映射序列（无序列表）的输出如下所示：

{
   "paper": {
      "uuid": "8a8cbf60-e067-11e3-8b68-0800200c9a66",
      "name": "On formally undecidable propositions of Principia Mathematica and related systems I.",
      "author": "Kurt Gödel."
   },
   "tags": [
      {
         "tag": {
            "uuid": "98fb0d90-e067-11e3-8b68-0800200c9a66",
            "name": "Mathematics"
         }
      },
      {
         "tag": {
            "uuid": "3f25f680-e068-11e3-8b68-0800200c9a66",
            "name": "Logic"
         }
      }
   ]
}

如果您观察到如上所示的输出，您会发现键名在 YAML 映射结构中保持唯一。

YAML - 块序列

YAML 的块序列表示一系列节点。每个项目都用前导“-”指示符表示。请注意，YAML 中的“-”指示符应与节点用空格分隔。

块序列的基本表示如下所示：

block sequence:
··- one↓
  - two : three↓

示例

观察以下示例，以便更好地理解块序列。

示例 1

port: &ports
  adapter:  postgres
  host:     localhost

development:
  database: myapp_development
  <<: *ports

块序列的 JSON 格式输出如下所示：

{
   "port": {
      "adapter": "postgres",
      "host": "localhost"
   },
   "development": {
      "database": "myapp_development",
      "adapter": "postgres",
      "host": "localhost"
   }
}

YAML - 安全模式模式

YAML 模式定义为一组标签的组合，并包含一种解析非特定标签的机制。YAML 中的安全模式模式以这样一种方式创建，即它可以与任何 YAML 文档一起使用。它也被认为是通用 YAML 文档的推荐模式。

类型

安全模式模式有两种类型：通用映射和通用序列

通用映射

它表示一个关联容器。在这里，每个键在关联中都是唯一的，并且恰好映射到一个值。YAML 对键定义没有任何限制。

表示通用映射的示例如下所示：

Clark : Evans
Ingy : döt Net
Oren : Ben-Kiki
Flow style: !!map { Clark: Evans, Ingy: döt Net, Oren: Ben-Kiki }

JSON 格式中通用映射结构的输出如下所示：

{
   "Oren": "Ben-Kiki", 
   "Ingy": "d\u00f6t Net", 
   "Clark": "Evans", 
   "Flow style": {
      "Oren": "Ben-Kiki", 
      "Ingy": "d\u00f6t Net", 
      "Clark": "Evans"
   }
}

通用序列

它表示一种序列类型。它包含一个由从零开始的连续整数索引的集合。它用!!seq标签表示。

Clark : Evans
Ingy : döt Net
Oren : Ben-Kiki
Flow style: !!seq { Clark: Evans, Ingy: döt Net, Oren: Ben-Kiki }

安全模式模式此通用序列的输出

schema is shown below:
{
   "Oren": "Ben-Kiki", 
   "Ingy": "d\u00f6t Net", 
   "Clark": "Evans", 
   "Flow style": {
      "Oren": "Ben-Kiki", 
      "Ingy": "d\u00f6t Net", 
      "Clark": "Evans"
   }
}

YAML - JSON 模式

YAML 中的 JSON 模式被认为是大多数现代计算机语言的共同点。它允许解析 JSON 文件。YAML 强烈建议在 JSON 模式上考虑其他模式。其主要原因是它包含用户友好的键值组合。消息可以编码为键，并可以在需要时使用。

JSON 模式是标量，缺少值。JSON 模式中的映射条目以某种键值对的格式表示，其中 null 被视为有效。

示例

空 JSON 模式表示如下所示：

!!null null: value for null key
key with null value: !!null null

JSON 表示的输出如下所示：

{
   "null": "value for null key", 
   "key with null value": null
}

示例

以下示例表示布尔 JSON 模式：

YAML is a superset of JSON: !!bool true
Pluto is a planet: !!bool false

以下是 JSON 格式的相同输出：

{
   "YAML is a superset of JSON": true, 
   "Pluto is a planet": false
}

示例

以下示例表示整数 JSON 模式：

negative: !!int -12
zero: !!int 0
positive: !!int 34

生成的整数 JSON 模式的输出如下所示

{
   "positive": 34, 
   "zero": 0, 
   "negative": -12
}

示例

JSON 模式中的标签用以下示例表示：

A null: null
Booleans: [ true, false ]
Integers: [ 0, -0, 3, -19 ]
Floats: [ 0., -0.0, 12e03, -2E+05 ]
Invalid: [ True, Null, 0o7, 0x3A, +12.3 ]

您可以找到如下所示的 JSON 输出：

{
   "Integers": [
      0, 
      0, 
      3, 
      -19
   ], 
   
   "Booleans": [
      true, 
      false
   ], 
   "A null": null, 

   "Invalid": [
         true, 
         null, 
         "0o7", 
         58, 
         12.300000000000001
   ], 
   
   "Floats": [
      0.0, 
      -0.0, 
      "12e03", 
      "-2E+05"
   ]
}