SnakeYAML引擎 中文文档

安装

如果使用Maven,只需添加如下依赖描述:参考这里。

教程

加载YAML

使用构建者模式来创建org.snakeyaml.engine.v2.api.LoadSettings实例不可变对象:

LoadSettings settings = LoadSettings.builder().setLabel("自定义用户配置").build();

创建org.snakeyaml.engine.v2.api.Load实例:

Load load = new Load(settings);

org.snakeyaml.engine.v2.api.Load实例支持三种源加载:

• InputStream
• Reader
• 字符串

InputStream不包含编码信息,需要通过BOM(字节顺序标记)序列在流开始检测编码。如果没有BOM,默认使用UTF-8编码。

Reader和字符串定义了编码,BOM不应出现(会作为数据处理)。

这些方法可以将YAML文档转换为Java对象:

• loadFromInputStream
• loadFromReader
• loadFromString

Load load = new Load(settings);
String document = "\n- Hesperiidae\n- Papilionidae\n- Apatelodidae\n- Epiplemidae";
List<String> list = (List<String>) yaml.loadFromString(document);
System.out.println(list);

['Hesperiidae', 'Papilionidae', 'Apatelodidae', 'Epiplemidae']

详见例子

隐式类型

如果标记节点没有显式定义,SnakeYAML引擎会试图通过正则表达式匹配内容来检测类型,第一个匹配则解析为该类型。

1.0 -> Double
42 -> Integer
null -> null
false -> boolean 

仅支持JSON模式。

隐式标记会在获取到任何其他关于标量的信息后忽略。

您说得对,我确实忘记翻译Dumping相关内容,现在补充翻译如下:

输出YAML

使用构建者模式来创建可变的org.snakeyaml.engine.v2.api.DumpSettings实例:

DumpSettings settings = DumpSettings.builder()
  .setDefaultScalarStyle(ScalarStyle.DOUBLE_QUOTED)
  .build();

创建org.snakeyaml.engine.v2.api.Dump实例:

Dump dump = new Dump(settings);

方法Dump.dumpToString()接受一个实例并返回其YAML文档。方法Dump.dumpAllToString()接受一个java.util.Iterator并返回包含所有文档的YAML流。文档通过DumpSettings指定分隔。

为支持输出到流,Dump提供dump()和dumpAll()。它们采用继承java.io.Writer但不抛出IO异常的StreamDataWriter作为参数。这意味着用户需要创建接口的实现并处理捕获IO异常。

在测试中可以找到工作示例

生成自定义YAML文档

TODO

构造器、表示方法、解析器

TODO

枚举

SnakeYAML支持将枚举映射到YAML。

本地标签可以直接将枚举直接映射到相应语言的枚举类型,例如:

!java.lang.Enum ExampleEnum

也可以将枚举表示为map:

!map
  a: VALUE1 
  b: VALUE2

全局标签可以使用类似以下格式:

!!fully.qualified.name.of.Enum
  a: VALUE1
  b: VALUE2 

例子可以在这里找到。

线程安全性

实现不是线程安全的。不同线程不能调用同一个实例。线程必须有独立的Load或Dump实例。

底层API

可以对字符流进行解析或组装。解析示例在这里,组装示例在这里。

标签

显式标签可以是本地标签(开始于单个感叹号'!')和全局标签(开始于双感叹号'!!')。全局标签在单个编程语言内工作良好,因为可以在没有额外配置的情况下解析。本地标签需要额外上下文。由于每个解析器在运行时都必须提供更多信息来创建实例,所以本地标签有助于YAML文档在不同语言间交换(每个解析器都可以自行决定对!car作何处理)。

隐式标签会为每个标量自动分配。可以添加自定义隐式标签解析规则。在创建标量时会采用以下顺序:

1. 显式标签 - 存在时使用

2. 隐式标签 - 当运行时类不明时使用

如果上述都不匹配,则默认解析为tag:yaml.org,2002:str(作为字符串解析)。

例子可在这里找到。

YAML语法

YAML语法的很好入门介绍见规范章节2。

这里简要介绍最常见的YAML结构和对应的Java对象:

块序列

在块上下文,序列项用“-”(破折号后跟一个空格)表示:

# YAML
- Mark McGwire
- Sammy Sosa
- Ken Griffey


["Mark McGwire", "Sammy Sosa", "Ken Griffey"]

块序列可以嵌套:

# YAML
-
  - HTML
  - LaTeX
  - SGML
  - VRML
  - XML
  - YAML
-
  - BSD
  - GNU Hurd
  - Linux


[['HTML', 'LaTeX', 'SGML', 'VRML', 'XML', 'YAML'], ['BSD', 'GNU Hurd', 'Linux']]

嵌套序列项不必另起一行:

# YAML
- 1.1
- - 2.1
  - 2.2
- - - 3.1
    - 3.2
    - 3.3


[1.1, [2.1, 2.2], [[3.1, 3.2, 3.3]]]

块映射

在块上下文,映射项用“:”(冒号后跟一个空格)表示键值对:

# YAML 
hr: 65
avg: 0.278


{"hr": 65, "avg": 0.278}

可支持复杂键:

# YAML
? !!python/tuple [0,0]
: The Hero
? !!python/tuple [0,1] 
: Treasure


{(0, 0): 'The Hero', (0, 1): 'Treasure'}

块映射也支持嵌套:

# YAML
hero:
  hp: 34
  sp: 8
  level: 4
orc:
  hp: 12
  sp: 0
  level: 2


{"hero": {"hp": 34, "sp": 8, "level": 4}, "orc": {"hp": 12, "sp": 0, "level": 2}} 

流集合

流序列用“[”和“]”包围,项间用“,”分隔:

# YAML
[ one, two, ]

["one", "two"]

流映射用“{”和“}”包围,键值对间用“,”分隔:

# YAML
{ key: value }

{"key": "value"}

标量样式

YAML提供5种标量样式:

• 纯样式
• 单引号样式
• 双引号样式
• 字面样式
• 漫展样式

每个样式各有优点,主要区别在于是否支持换行和转义。

标签

标签以“!”表示,可以是显式标签或者使用缩写:

# 显式 
!!null null

# 缩写
!!bool true

缺失标签会被解析为特定类型。

YAML语法与Java类型映射

下表描述不同标签节点在Java中的表现:

| YAML标签       | Java类型                  |
| -------------- | ------------------------- |
| 标准YAML标签   |                           |
| !!null         | null                      |
| !!bool         | Boolean                   |
| !!int          | Integer, Long, BigInteger |
| !!float        | Double                    |
| !!binary       | byte[], String            |
| !!omap,!!pairs | List ofObject[]           |
| !!set          | Set                       |
| !!str          | String                    |
| !!seq          | List                      |
| !!map          | Map                       |

默认集合实现:

• List: ArrayList
• Map: LinkedHashMap

可以定义其他默认实现。

YAML与Java类型相对应

以下贴出一些常见映射:

# YAML
- Mark McGwire
- Sammy Sosa 

# Java
["Mark McGwire", "Sammy Sosa"]


# YAML 
hr: 65
avg: 0.278

# Java
{"hr": 65, "avg": 0.278}


# YAML
true
false 

# Java 
true
false


# YAML
0
3
-1

# Java
0
3 
-1


# YAML
0. 
1.2e3

# Java
0.0
1200.0

详见例子

YAML语法与特定语言绑定

YAML处理器往往提供特定语言的本地标签,比如:

!ruby/object Ruby::Set

这类标签直接绑定到语言原生类型上。

同时也支持全局标签,比如:

!!tag:yaml.org,2002:set 

这类标签在不同语言间互操作。

值得注意的是,通过本地标签也可以实现跨语言互操作。例如:

%TAG !ruby/object !!

会把本地标签映射到全局域名定义的类型上。

合并

YAML定义了“合并”语义,详见http://yaml.org/type/merge.html。

但是SnakeYAML已经移除了对该语义的支持,因为它在YAML 1.2中不再推荐使用。

---

译者：Claude

校对：devzhi

原文：https://bitbucket.org/snakeyaml/snakeyaml-engine/wiki/Documentation#markdown-header-constructors-representers-resolvers