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