YAML 语法
YAML 文件以 .yaml
或者 .yml
结尾,是一个可读性高,用来表达数据序列化的格式。
语法示例
--- # document start
# Comments in YAML look like this.
# YAML supports single-line comments.
################
# SCALAR TYPES
################
# Our root object (which continues for the entire document) will be a map,
# which is equivalent to a dictionary, hash or object in other languages.
key: value another_key: Another value goes here. a_number_value: 100 scientific_notation: 1e+12 hex_notation: 0x123 # evaluates to 291 octal_notation: 0123 # evaluates to 83
# The number 1 will be interpreted as a number, not a boolean.
# If you want it to be interpreted as a boolean, use true.
boolean: true null_value: null another_null_value: ~ key with spaces: value
# Yes and No (doesn't matter the case) will be evaluated to boolean
# true and false values respectively.
# To use the actual value use single or double quotes.
no: no # evaluates to "no": false yes: No # evaluates to "yes": false not_enclosed: yes # evaluates to "not_enclosed": true enclosed: 'yes' # evaluates to "enclosed": yes
# Notice that strings don't need to be quoted. However, they can be.
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."
# UTF-8/16/32 characters need to be encoded
Superscript two: \u00B2
# Special characters must be enclosed in single or double quotes
special_characters: '[ John ] & { Jane } - <Doe>'
# Multiple-line strings can be written either as a 'literal block' (using |),
# or a 'folded block' (using '>').
# Literal block turn every newline within the string into a literal newline (\n).
# Folded block removes newlines within the string.
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.
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.
# |- and >- removes the trailing blank lines (also called literal/block "strip")
literal_strip: |- This entire block of text will be the value of the 'literal_strip' key, with trailing blank line being stripped. block_strip: >- This entire block of text will be the value of 'block_strip', but this time, all newlines will be replaced with a single space and trailing blank line being stripped.
# |+ and >+ keeps trailing blank lines (also called literal/block "keep")
literal_keep: |+ This entire block of text will be the value of the 'literal_keep' key, with trailing blank line being kept.
block_keep: >+ This entire block of text will be the value of 'block_keep', but this time, all newlines will be replaced with a single space and trailing blank line being kept.
####################
# COLLECTION TYPES
####################
# Nesting uses indentation. 2 space indent is preferred (but not required).
a_nested_map: key: value another_key: Another Value another_nested_map: hello: hello
# Maps don't have to have string keys.
0.25: a float key
# Keys can also be complex, like multi-line objects
# We use ? followed by a space to indicate the start of a complex key.
? | This is a key that has multiple lines : and this is its value
# YAML also allows mapping between sequences with the complex key syntax
# Some language parsers might complain
# An example
? - Manchester United
- Real Madrid : [2001-01-01, 2002-02-02]
# Sequences (equivalent to lists or arrays) look like this
# (note that the '-' counts as indentation):
a_sequence:
- Item 1
- Item 2
- 0.5 # sequences can contain disparate types.
- Item 4
- key: value another_key: another_value
- - This is a sequence
- inside another sequence
- - - Nested sequence indicators
- can be collapsed
# Since YAML is a superset of JSON, you can also write JSON-style maps and
# sequences:
json_map: {'key': 'value'} json_seq: [3, 2, 1, 'takeoff'] and quotes are optional: {key: [3, 2, 1, takeoff]}
#######################
# EXTRA YAML FEATURES
#######################
# YAML also has a handy feature called 'anchors', which let you easily duplicate
# content across your document.
# Anchors identified by & character which define the value.
# Aliases identified by \* character which acts as "see above" command.
# Both of these keys will have the same value:
anchored_content: &anchor_name This string will appear as the value of two keys. other_anchor: \*anchor_name
# Anchors can be used to duplicate/inherit properties
base: &base name: Everyone has same name
# The expression << 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.
# NOTE: If key already exists alias will not be merged
foo: <<: *base # doesn't merge the anchor age: 10 name: John bar: <<: *base # base anchor will be merged age: 20
# foo name won't be changed and it will be: John. On the other hand, bar's name will be changed to the base one: Everyone has same name
# YAML also has tags, which you can use to explicitly declare types.
# Syntax: !![typeName] [value]
explicit_boolean: !!bool true explicit_integer: !!int 42 explicit_float: !!float -42.24 explicit_string: !!str 0.5 explicit_datetime: !!timestamp 2022-11-17 12:34:56.78 +9 explicit_null: !!null null
# 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
####################
# EXTRA YAML TYPES
####################
# Strings and numbers aren't the only scalars that YAML can understand.
# ISO-formatted date and datetime literals are also parsed.
datetime_canonical: 2001-12-15T02:59:43.1Z datetime_space_separated_with_time_zone: 2001-12-14 21:59:43.10 -5 date_implicit: 2002-12-14 date_explicit: !!timestamp 2002-12-14
# The !!binary tag indicates that a string is actually a base64-encoded
# representation of a binary blob.
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 also has a set type, which looks like this:
set: item1: item2: item3: or: {item1, item2, item3}
# Sets are just maps with null values; the above is equivalent to:
set2: item1: null item2: null item3: null ... # document end
设计目标
YAML 的设计目标是(优先级递减):
- YAML 应该很容易被人类阅读。
- YAML 数据应该在编程语言之间可移植。
- YAML 应该与动态语言的原生数据结构相匹配。
- YAML 应该有一个一致的模型来支持通用工具。
- YAML 应该支持一遍处理。
- YAML 应该具有表达性和可扩展性。
- YAML 应该易于实现和使用。
语法
YAML 实质上是一种通用的数据串行化格式。
它的基本语法规则如下。
- 大小写敏感
- 使用缩进表示层级关系
- 缩进时不允许使用 Tab 键,只允许使用空格
- 缩进的空格数目不重要,只要相同层级的元素左侧对齐即可
#
表示单行注释,从第一个#
字符一直到行尾,都会被忽略;不支持多行注释- (可选)以 --- 开头或以 ... 结尾,表示文档的开始和结束
YAML 支持的数据结构有三种。
- 标量:标量 (scalar),单个的、不可再分的值,如空值、布尔值、数字和字符串。
- 字典:键值对的集合,又称为映射(mapping)/ 键值对(key-value pair)。
- 数组:一组按次序排列的值,又称为序列(sequence) / 列表(list)
标量
类型 | 格式 | 说明 |
---|---|---|
空值 | null Null NULL ~ | 旧的 YAML 版本可以使用 null Null NULL ~ 或者留空。为了严格符合 YAML 规范,推荐优先使用 true 和 false,使用小写。 |
布尔值 | true True TRUE false False FALSE | 旧的 YAML 版本可以使用 yes no on off ,以及其首字母大写格式(首字母大写其余小写)、全大写模式。为了符合 JSON Schema,推荐优先使用小写 true 和 false 。 |
整数 | 全数字 | 为了符合 JSON Schema,非负数前面不要使用 + 。 |
整数(8 进制) | 0o 开头 | 为了符合 JSON Schema,不建议使用此项。 |
整数(16 进制) | 0x 开头 | 为了符合 JSON Schema,不建议使用此项。 |
浮点数 | 浮点数后面可以跟 e- e+ E- E+ 代表指数。 | 整数不能使用 exp 格式,如 1e-5 非法,需要使用 1.e-5 或者 1.0e-5 。为了符合 JSON Schema,非负数前面不要使用 + 。 |
浮点数(无穷值) | .inf .Inf .INF ,前面可以加正负号 | 为了符合 JSON Schema,不建议使用此项。 |
浮点数(无效值) | .nan .NaN .NAN | 为了符合 JSON Schema,不建议使用此项。 |
字符串 | * |
字典
虽然 YAML 解析器可能会接受重复的键。但是在实际使用中,建议键是唯一的,在同一个字典中,不应重复出现相同的键。
另外,字典用于表示键值对集合,其中每个键值对表示一个属性或字段。字典是无序的。
单行模式:
---
user: {id: 1, name: 'John Doe', age: 18}
多行模式:
---
user:
id: 1
name: 'John Doe'
age: 18
数组
单行模式:
---
items: [1, 2, 3]
names: ['one', 'two']
多行模式:
---
items:
- 1
- 2
- 3
names:
- 'one'
- 'two'
数组内嵌套多个字典
users:
- user1: 'John Doe'
age: 22
uid: 1
- age: 20
user2: 'Jane Doe'
uid: 2
- uid: 3
user3: 'Anonymous'
age: null
块指示符
块标量头包括三个部分组成:块格式指示符、块 Chomping 指示符 和 块缩进指示符。
比如 GitHub Actions 中常用的 |
,表示:保留换行,并去掉最后一行的尾随换行,缩进自动推测。
关于指示符的拼凑,YAML Multiline 内有详细的说明。
块格式指示符(Block Style Indicator)
- 字面样式指示符
|
:保留换行。 - 折叠样式指示符
>
:将新行替换为空格。但是如果在折叠指示内需要换行,可以换行两次,这样会被替换成单个换行。另外,具有额外缩进的行也不会被折叠。
块 Chomping 指示符(Block Chomping Indicator)
Chomping 控制如何解释最后的换行符和尾随空行。YAML 提供了三种 chomping 方法:
- Strip
-
:最后的换行符和任何尾随空行都将从标量的内容中排除。 - Clip:如果未指定明确的 chomping 指示符,则 Clipping 是默认行为。在这种情况下:最后的换行符将保留在标量的内容中。但是,任何尾随在最后一行的换行符都将从标量的内容中排除。
- Keep
+
:在这种情况下,最后的换行符和任何尾随空行都被视为标量内容的一部分。这些额外的行不受折叠的影响。
块缩进指示符
通常,缩进块的空格数将从其第一行自动推测。
如果块的第一行以额外的空格开头,您可能需要一个块缩进指示符。在这种情况下,只需在头部的末尾放置用于缩进的空格数(1 到 9 之间)。