文档中心MogDBMogDB StackUqbar
v2.0

文档:v2.0

支持的版本:

附录:YAML语法

PTK 采用 YAML 格式的配置文件,主要是因为语法简洁直观,数据结构方面的表达能力强,并且便于搭配注释进行描述。

注意:YAML 特点是使用空格来表达层次结构,所以在编写配置时需要注意缩进层次

本文就主要介绍 YAML 的语法,来帮助用户可以更好的理解 PTK 的配置文件格式。

标量和集合

根据 YAML 规范,有两种集合类型和很多标量类型。

两种集合类型是 map (字典)和 sequence (列表):

map:
  one: 1
  two: 2
  three: 3

sequence:
  - one
  - two
  - three

标量值是单个值,(与集合相反)

YAML中的标量类型

如果整型或浮点型数字没有引号,通常被视为数字类型:

count: 1
size: 2.34

但是如果被引号引起来,会被当做字符串:

count: "1" # <-- string, not int
size: '2.34' # <-- string, not float

布尔函数也是如此:

isGood: true   # bool
answer: "true" # string

空字符串是 null (不是 nil)。

注意 port: "80"是合法的YAML,可以通过模板引擎和YAML解释器传值,但是如果PTK希望port是整型,就会失败。

在一些场景中,可以使用YAML节点标签强制推断特定类型:

coffee: "yes, please"
age: !!str 21
port: !!int "80"

如上所示,!!str告诉解释器age是一个字符串,即使它看起来像是整型。即使port被引号括起来,也会被视为int。

YAML中的字符串

YAML中的大多数数据都是字符串。YAML有多种表示字符串的方法。本节解释这些方法并演示如何使用其中一些方法。

有三种单行方式声明一个字符串:

way1: bare words
way2: "double-quoted strings"
way3: 'single-quoted strings'

单行样式必须在一行:

  • 裸字没有引号,也没有转义,因此,必须小心使用字符。
  • 双引号字符串可以使用\转义指定字符。比如,"\"Hello\", she said"。可以使用\n转义换行。
  • 单引号字符串是字面意义的字符串,不用\转义,只有单引号''需要转义,转成单个'

除了单行字符串,可以声明多行字符串:

coffee: |
  Latte
  Cappuccino
  Espresso

上述会被当作coffee的字符串值,等同于Latte\nCappuccino\nEspresso\n

注意在第一行|后面必须正确缩进。可以这样破坏上述示例:

coffee: |
         Latte
  Cappuccino
  Espresso

由于Latte没有正确缩进,会遇到这样的错误:

Error parsing file: error converting YAML to JSON: yaml: line 7: did not find expected key

模板中,有时候为了避免上述错误,在多行文本中添加一个假的“第一行”会更加安全:

coffee: |
  # Commented first line
         Latte
  Cappuccino
  Espresso

注意无论第一行是什么,都会保存在字符串的输出中。比如你要这样把文件内容注入到配置映射中,注释应该是读取该条目需要的类型。

控制多行字符串中的空格

在上述示例中,使用了 | 来表示多行字符串。但是注意字符串后面有一个尾随的\n。如果需要YAML处理器去掉末尾的换行符,在| 后面添加-

coffee: |-
  Latte
  Cappuccino
  Espresso

现在 coffee的值变成了: Latte\nCappuccino\nEspresso (没有末尾的\n)。

其他时候,可能希望保留尾随空格。可以使用 |+符号:

coffee: |+
  Latte
  Cappuccino
  Espresso


another: value

现在coffee的值是 Latte\nCappuccino\nEspresso\n\n\n

文本块中的缩进会被保留,也会保留换行符:

coffee: |-
  Latte
    12 oz
    16 oz
  Cappuccino
  Espresso

上述示例中,coffee会变成 Latte\n 12 oz\n 16 oz\nCappuccino\nEspresso

折叠多行字符串

有时您想在 YAML 中用多行表示一个字符串,但希望在解释时将其视为一个长行。这被称为"折叠"。要声明一个折叠块,使用 > 代替 |

coffee: >
  Latte
  Cappuccino
  Espresso

上面coffee的值是: Latte Cappuccino Espresso\n。 注意,除了最后一个换行符之外,所有的换行符都将转换成空格。 可以组合空格控制符和折叠字符标记 >- 来替换或取消所有的新行。

注意在折叠语法中,缩进文本将导致保留行。

coffee: >-
  Latte
    12 oz
    16 oz
  Cappuccino
  Espresso

上述结果为:Latte\n 12 oz\n 16 oz\nCappuccino Espresso。注意空格和换行都保存下来了。

YAML是JSON的超集

由于YAML是一个JSON的超集,任何合法的JSON文档 都应该 是合法的YAML。

{
  "coffee": "yes, please",
  "coffees": [
    "Latte", "Cappuccino", "Espresso"
  ]
}

上述json的另一种表述方式是:

coffee: yes, please
coffees:
- Latte
- Cappuccino
- Espresso

而且两种可以混合(要小心):

coffee: "yes, please"
coffees: [ "Latte", "Cappuccino", "Espresso"]

所有这三个都应该解析为相同的内部表示形式。

Copyright © 2011-2024 www.enmotech.com All rights reserved.