[译]yaml快速教程

原文地址：https://learnxinyminutes.com/docs/yaml/

---

YAML是一种旨在直接可由人类编写和读取的数据序列化语言。

它是JSON的严格超集，语法上添加了类似Python的换行符和缩进。 但是与Python不同，YAML不允许使用TAB缩进。

---  # 文档开始

# 这是注释

##########
#  标量类型 #
#########

# 我们的根对象（包含整个文档）是一个map，
# 等价于其他语言中的dictionary, hash 或 object
key: value # 键值对
another_key: Another value goes here. # 另一个键值对
a_number_value: 100 # 数值
scientific_notation: 1e+12 # 科学计数法表示的数值
boolean: true # 布尔值
null_value: null # null值
key with spaces: value # 带空格的键
# 注意字符串不需要引号，但可以使用引号
however: 'A string, enclosed in quotes.' # 用引号括起来的字符串
'Keys can be quoted too.': "Useful if you want to put a ':' in your key." # 键也可以括起来
single quotes: 'have ''one'' escape pattern' # 使用单引号
double quotes: "have many: \", \0, \t, \u263A, \x0d\x0a == \r\n, and more." # 使用双引号

# 多行字符串可以采用“文本块” （使用 |）,
# 或“折叠块”（使用 >）
literal_block: |
    This entire block of text will be the value of the 'literal_block' key,
    with line breaks being preserved.

    The literal continues until de-dented, and the leading indentation is
    stripped.

        Any lines that are 'more-indented' keep the rest of their indentation -
        these lines will be indented by 4 spaces.

# 整个文本块将是'literal_block'键的值，保留换行符。
# 直到进一步缩进时，所有前导缩进将会被去除。
#     存在“更多缩进”的行将保留其缩进的剩余部分 - 这两行好将缩进4个空格。
# 
# 示例结果：
# This entire block of text will be the value of the 'literal_block' key,
# with line breaks being preserved.
# 
# The literal continues until de-dented, and the leading indentation is
# stripped.
# 
#     Any lines that are 'more-indented' keep the rest of their indentation -
#     these lines will be indented by 4 spaces.

folded_style: >
    This entire block of text will be the value of 'folded_style', but this
    time, all newlines will be replaced with a single space.

    Blank lines, like above, are converted to a newline character.

        'More-indented' lines keep their newlines, too -
        this text will appear over two lines.

# 折叠风格可以将（空格分割的）长行在空格处打断为多行，其特点是：
# - 折叠的换行符替换为空格
# - 更多缩进的行不折叠
# （译者注：这里，以及官方文档，都没能将其规则说清楚，为什么空行消失。但一般不会遇到这么复杂的字符串，所以不用深究。）
# 
#
# 示例结果：
# This entire block of text will be the value of 'folded_style', but this time, all newlines will be replaced with a single space.
# Blank lines, like above, are converted to a newline character.
# 
#     'More-indented' lines keep their newlines, too -
#     this text will appear over two lines.

##########
# 集合类型 #
##########

# 使用缩进嵌套，推荐2个空格（但非必须）
a_nested_map:
  key: value
  another_key: Another Value
  another_nested_map:
    hello: hello

# map不一定需要字符串的键
0.25: a float key

# 键可以很复杂，如多行对象。
# 使用 ? 及其后的一个空格，表明复杂键的开始
? |
  This is a key
  that has multiple lines
: and this is its value

# YAML同样允许序列之间映射，使用复杂键的语法。
# 一些实现不支持这样做，如jackson。
? - Manchester United
  - Real Madrid
: [2001-01-01, 2002-02-02]

# 序列（等价于列表或数组）如下所示
# （注意'-'记作一个缩进）:
a_sequence:
  - Item 1
  - Item 2
  - 0.5  # 序列支持不同类型
  - Item 4
  - key: value
    another_key: another_value
  -
    - This is a sequence
    - inside another sequence
  - - - Nested sequence indicators
      - can be collapsed

# 鉴于YAML是JSON的超集，可以使用JSON风格的map和序列：
json_map: {"key": "value"}
json_seq: [3, 2, 1, "takeoff"]
and quotes are optional: {key: [3, 2, 1, takeoff]}

###########
#额外的功能 #
##########

# YAML拥有称为“锚”的便捷功能，可以在文档中复用内容。下两个key拥有共同的值：
anchored_content: &anchor_name This string will appear as the value of two keys.
other_anchor: *anchor_name

# 锚可用于复制/继承属性
base: &base
  name: Everyone has same name

# The regexp << is called Merge Key Language-Independent Type. It is used to
# indicate that all the keys of one or more specified maps should be inserted
# into the current map.

foo: &foo
  <<: *base
  age: 10

bar: &bar
  <<: *base
  age: 20

# foo and bar would also have name: Everyone has same name

# YAML还有标记，您可以使用它来显式声明类型。
explicit_string: !!str 0.5
# Some parsers implement language specific tags, like this one for Python's
# complex number type.
python_complex_number: !!python/complex 1+2j

# We can also use yaml complex keys with language specific tags
? !!python/tuple [5, 7]
: Fifty Seven
# Would be {(5, 7): 'Fifty Seven'} in Python

################
# 额外的YAML类型 #
################

# 除了字符串和数字值，YAML还支持ISO格式的date和datetime字面量。
datetime: 2001-12-15T02:59:43.1Z
datetime_with_spaces: 2001-12-14 21:59:43.10 -5
date: 2002-12-14

# "!!binary"标签声明一个字符串是base64编码的，表示一个二进制blob
# （译者注：参考Python相关概念）
gif_file: !!binary |
  R0lGODlhDAAMAIQAAP//9/X17unp5WZmZgAAAOfn515eXvPz7Y6OjuDg4J+fn5
  OTk6enp56enmlpaWNjY6Ojo4SEhP/++f/++f/++f/++f/++f/++f/++f/++f/+
  +f/++f/++f/++f/++f/++SH+Dk1hZGUgd2l0aCBHSU1QACwAAAAADAAMAAAFLC
  AgjoEwnuNAFOhpEMTRiggcz4BNJHrv/zCFcLiwMWYNG84BwwEeECcgggoBADs=

# YAML拥有一个集合类型：
set:
  ? item1
  ? item2
  ? item3
or: {item1, item2, item3}

# 集合只是简单的映射为空值，以上等价于：
set2:
  item1: null
  item2: null
  item3: null

...  # 文档结束