YAML

Table of Contents

1. YAML 简介

YAML is a human friendly data serialization standard for all programming languages. YAML stands for YAML Ain't Markup Language. 即 YAML 全称为“YAML 不是一种标记语言”。注:YAML 之前的全称为“Yet Another Markup Language”。

YAML 的语法比 XML 要简单得多,YAML 的可读性很好,非常适合用作配置文件。

参考:
YAML reference card: http://www.yaml.org/refcard.html
YAML Ain’t Markup Language (YAML™) Version 1.2: http://www.yaml.org/spec/1.2/spec.html

1.1. 简单例子

下面是 YAML 的一个例子:

name: John Smith
age: 37
spouse:
  name: Jane Smith
  age: 25
children:
  - name: Jimmy Smith
    age: 5
  - name: Jenny Smith
    age: 2

一看就知道上面文件表达的是:John 今年 37 岁,其妻子 Jane 今年 25 岁,两个孩子 Jimmy 和 Jenny 分别为 5 和 2 岁。

2. 基本语法

YAML 的基本语法如下:

  • 使用空格(不能使用 Tab)缩进表示分层,同层元素左对齐。
  • # 开始处到行尾是注释内容。
  • - 表示序列(Sequence)。
  • : 表示 key-value 键值对(Mapping)。

2.1. Sequence 和 Mapping

下面是 Sequence 的例子:

- Mark McGwire
- Sammy Sosa
- Ken Griffey

下面是 Mapping 的例子:

hr:  65    # Home runs
avg: 0.278 # Batting average
rbi: 147   # Runs Batted In

下面是 Mapping(Scalars to Sequences)例子:

american:
  - Boston Red Sox
  - Detroit Tigers
  - New York Yankees
national:
  - New York Mets
  - Chicago Cubs
  - Atlanta Braves

Scalars to Sequences 例子中的 Sequences 前面的空格缩进也可以省略(参考:https://stackoverflow.com/questions/5953338/indenting-a-yaml-sequence-inside-a-mapping ),即写为下面形式也合法:

# 合法,其含义同上面例子,但不推荐省略缩进
american:
- Boston Red Sox
- Detroit Tigers
- New York Yankees
national:
- New York Mets
- Chicago Cubs
- Atlanta Braves

下面是 Sequence of Mappings 例子:

-
  name: Mark McGwire
  hr:   65
  avg:  0.278
-
  name: Sammy Sosa
  hr:   63
  avg:  0.288

2.1.1. JSON 风格的 Sequence 和 Mapping

YAML 也支持 JSON 风格的 Sequence(方括号表示)和 Mapping(大括号表示)。

下面是 Sequence of Sequences 的例子:

- [name        , hr, avg  ]
- [Mark McGwire, 65, 0.278]
- [Sammy Sosa  , 63, 0.288]

下面是 Mapping of Mappings 的例子:

Mark McGwire: {hr: 65, avg: 0.278}
Sammy Sosa: {
    hr: 63,
    avg: 0.288
  }

2.2. 文档开头和结束(3个连字符和 3 个点)

--- 表示文档的开头(前面可以有注释或指令), ... 表示文档结束。

下面是“Two Documents in a Stream(each with a leading comment)”的例子:

# Ranking of 1998 home runs
---
- Mark McGwire
- Sammy Sosa
- Ken Griffey
...
# Team ranking
---
- Chicago Cubs
- St Louis Cardinals
...

2.3. 重复和引用(&和*)

如果 YAML 中有重复的内容,可以先用 & 标记一个 anchor,然后可以使用 * 引用它。

如下面 YAML 文件(“Sammy Sosa”是重复内容,它出现了两次):

---
hr: # 1998 hr ranking
  - Mark McGwire
  - Sammy Sosa
rbi:
  # 1998 rbi ranking
  - Sammy Sosa
  - Ken Griffey

也可以写为:

---
hr:
  - Mark McGwire
  # Following node labeled SS
  - &SS Sammy Sosa
rbi:
  - *SS # Subsequent occurrence
  - Ken Griffey

2.4. 多行文本中忽略和保留换行符

使用尖括号(>),换行符会被替换为空格,直到出现空行或者缩进不同的行表示结束。

如下面 YAML 文件:

name: Mark McGwire
accomplishment: >
  Mark set a major league
  home run record in 1998.

相当于:

name: Mark McGwire
accomplishment: Mark set a major league home run record in 1998.

要保留换行符,可以使用竖线(|)。 如:

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

2.5. 指令(以百分号打头)

Directives are instructions to the YAML processor. 指令以 % 打头,如 %YAML 1.2 用于说明当前 YAML 的版本为 1.2。

%YAML 1.2
--- text

参考:
http://www.yaml.org/spec/1.2/spec.html#directive/YAML/

Author: cig01

Created: <2017-02-08 Wed>

Last updated: <2020-04-28 Tue>

Creator: Emacs 27.1 (Org mode 9.4)