java.lang.Object

cloud.opencode.base.yml.OpenYml

public final class OpenYml extends Object

OpenYml - Main entry point for YAML operations OpenYml - YAML 操作的主入口点

This class provides a simple API for parsing, writing, and manipulating YAML.

此类提供解析、写入和操作 YAML 的简单 API。

Features | 主要功能:

Parse YAML from strings, files, and streams - 从字符串、文件和流解析 YAML
Write/dump YAML to strings, files, and writers - 将 YAML 写入字符串、文件和写入器
Object binding (YAML to Java objects and back) - 对象绑定（YAML 到 Java 对象的双向转换）
Document merging with configurable strategies - 可配置策略的文档合并
Placeholder resolution (${key:default}) - 占位符解析
Multi-document YAML support - 多文档 YAML 支持

Usage Examples | 使用示例:

// Parse YAML
Map<String, Object> data = OpenYml.load("server:\n  port: 8080");
YmlDocument doc = OpenYml.parse("server:\n  port: 8080");

// Load from file
YmlDocument doc = OpenYml.loadFile(Path.of("config.yml"));

// Write YAML
String yaml = OpenYml.dump(data);

// Bind to object
ServerConfig config = OpenYml.bind(doc, ServerConfig.class);

// Merge documents
Map<String, Object> merged = OpenYml.merge(base, overlay);

Security | 安全性:

Thread-safe: Yes (stateless utility class) - 线程安全: 是（无状态工具类）
Null-safe: No (null input may throw exceptions) - 空值安全: 否（空输入可能抛出异常）
Uses SafeConstructor to prevent arbitrary type deserialization - 使用 SafeConstructor 防止任意类型反序列化

Since:

JDK 25, opencode-base-yml V1.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

Method Summary

Modifier and Type

Method

Description

static <T> T

bind(YmlDocument document, Class<T> type)

Binds document to a Java object.

static <T> T

bind(YmlDocument document, String path, Class<T> type)

Binds document at path to a Java object.

static <T> T

bind(String yaml, Class<T> type)

Binds YAML string to a Java object.

static List<DiffEntry>

diff(YmlDocument base, YmlDocument other)

Compares two YAML documents and returns a list of differences.

static List<DiffEntry>

diff(Map<String,Object> base, Map<String,Object> other)

Compares two YAML maps and returns a list of differences.

static String

dump(YmlDocument document)

Dumps document to YAML string.

static String

dump(Object data)

Dumps data to YAML string.

static String

dump(Object data, YmlConfig config)

Dumps data to YAML string with config.

static String

dumpAll(Iterable<?> documents)

Dumps multiple documents.

static String

dumpObject(Object object)

Dumps object to YAML string.

static boolean

isValid(String yaml)

Checks if YAML string is valid.

static Map<String,Object>

load(String yaml)

Parses YAML string to a Map.

static List<YmlDocument>

loadAll(String yaml)

Loads multi-document YAML.

static YmlDocument

loadDefaultProfile(Path directory, String... profiles)

Loads configuration with profile overlays using default name "application".

static YmlDocument

loadFile(Path path)

Loads YAML from a file.

static YmlDocument

loadFile(Path path, Charset charset)

Loads YAML from a file with charset.

static YmlDocument

loadProfile(Path basePath, String name, String... profiles)

Loads configuration with profile overlays.

static YmlDocument

loadStream(InputStream input)

Loads YAML from an input stream.

static Map<String,Object>

loadWithIncludes(Path file)

Loads a YAML file with !include directive resolution.

static YmlDocument

merge(YmlDocument base, YmlDocument overlay)

Merges two documents.

static Map<String,Object>

merge(Map<String,Object> base, Map<String,Object> overlay)

Merges two YAML maps.

static Map<String,Object>

merge(Map<String,Object> base, Map<String,Object> overlay, MergeStrategy strategy)

Merges two YAML maps with strategy.

static Map<String,Object>

mergeAll(Map<String,Object>... maps)

Merges multiple YAML maps.

static YmlDocument

parse(String yaml)

Parses YAML to a document.

static YmlNode

parseTree(String yaml)

Parses YAML to a node tree.

static YmlDocument

parseWithPlaceholders(String yaml)

Parses YAML with placeholder resolution.

static YmlDocument

parseWithPlaceholders(String yaml, Map<String,String> properties)

Parses YAML with placeholder resolution using custom properties.

static String

resolvePlaceholders(String yaml)

Resolves placeholders in YAML string.

static String

resolvePlaceholders(String yaml, PlaceholderResolver resolver)

Resolves placeholders in YAML string with resolver.

static Map<String,Object>

resolvePlaceholders(Map<String,Object> data)

Resolves placeholders in map values.

static Map<String,Object>

toMap(Object object)

Converts object to a Map.

static void

write(Object data, Writer writer)

Writes YAML to a writer.

static void

writeFile(Object data, Path path)

Writes YAML to a file.

static void

writeFile(Object data, Path path, Charset charset)

Writes YAML to a file with charset.

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- load
  
  public static Map<String,Object> load(String yaml)
  
  Parses YAML string to a Map. 将 YAML 字符串解析为 Map。
  
  Parameters:
  
  yaml - the YAML string | YAML 字符串
  
  Returns:
  
  the parsed map | 解析后的映射
- parse
  
  public static YmlDocument parse(String yaml)
  
  Parses YAML to a document. 将 YAML 解析为文档。
  
  Parameters:
  
  yaml - the YAML string | YAML 字符串
  
  Returns:
  
  the document | 文档
- loadFile
  
  public static YmlDocument loadFile(Path path)
  
  Loads YAML from a file. 从文件加载 YAML。
  
  Parameters:
  
  path - the file path | 文件路径
  
  Returns:
  
  the document | 文档
- loadFile
  
  public static YmlDocument loadFile(Path path, Charset charset)
  
  Loads YAML from a file with charset. 使用字符集从文件加载 YAML。
  
  Parameters:
  
  path - the file path | 文件路径
  
  charset - the charset | 字符集
  
  Returns:
  
  the document | 文档
- loadStream
  
  public static YmlDocument loadStream(InputStream input)
  
  Loads YAML from an input stream. 从输入流加载 YAML。
  
  Parameters:
  
  input - the input stream | 输入流
  
  Returns:
  
  the document | 文档
- loadAll
  
  public static List<YmlDocument> loadAll(String yaml)
  
  Loads multi-document YAML. 加载多文档 YAML。
  
  Parameters:
  
  yaml - the YAML string | YAML 字符串
  
  Returns:
  
  list of documents | 文档列表
- dump
  
  public static String dump(Object data)
  
  Dumps data to YAML string. 将数据转储为 YAML 字符串。
  
  Parameters:
  
  data - the data | 数据
  
  Returns:
  
  the YAML string | YAML 字符串
- dump
  
  public static String dump(Object data, YmlConfig config)
  
  Dumps data to YAML string with config. 使用配置将数据转储为 YAML 字符串。
  
  Parameters:
  
  data - the data | 数据
  
  config - the configuration | 配置
  
  Returns:
  
  the YAML string | YAML 字符串
- dump
  
  public static String dump(YmlDocument document)
  
  Dumps document to YAML string. 将文档转储为 YAML 字符串。
  
  Parameters:
  
  document - the document | 文档
  
  Returns:
  
  the YAML string | YAML 字符串
- dumpObject
  
  public static String dumpObject(Object object)
  
  Dumps object to YAML string. 将对象转储为 YAML 字符串。
  
  Parameters:
  
  object - the object | 对象
  
  Returns:
  
  the YAML string | YAML 字符串
- writeFile
  
  public static void writeFile(Object data, Path path)
  
  Writes YAML to a file. 将 YAML 写入文件。
  
  Parameters:
  
  data - the data | 数据
  
  path - the file path | 文件路径
- writeFile
  
  public static void writeFile(Object data, Path path, Charset charset)
  
  Writes YAML to a file with charset. 使用字符集将 YAML 写入文件。
  
  Parameters:
  
  data - the data | 数据
  
  path - the file path | 文件路径
  
  charset - the charset | 字符集
- write
  
  public static void write(Object data, Writer writer)
  
  Writes YAML to a writer. 将 YAML 写入写入器。
  
  Parameters:
  
  data - the data | 数据
  
  writer - the writer | 写入器
- dumpAll
  
  public static String dumpAll(Iterable<?> documents)
  
  Dumps multiple documents. 转储多个文档。
  
  Parameters:
  
  documents - the documents | 文档列表
  
  Returns:
  
  the YAML string | YAML 字符串
- bind
  
  public static <T> T bind(YmlDocument document, Class<T> type)
  
  Binds document to a Java object. 将文档绑定到 Java 对象。
  
  Type Parameters:
  
  T - the type parameter | 类型参数
  
  Parameters:
  
  document - the document | 文档
  
  type - the target type | 目标类型
  
  Returns:
  
  the bound object | 绑定的对象
- bind
  
  public static <T> T bind(YmlDocument document, String path, Class<T> type)
  
  Binds document at path to a Java object. 将指定路径的文档绑定到 Java 对象。
  
  Type Parameters:
  
  T - the type parameter | 类型参数
  
  Parameters:
  
  document - the document | 文档
  
  path - the path prefix | 路径前缀
  
  type - the target type | 目标类型
  
  Returns:
  
  the bound object | 绑定的对象
- bind
  
  public static <T> T bind(String yaml, Class<T> type)
  
  Binds YAML string to a Java object. 将 YAML 字符串绑定到 Java 对象。
  
  Type Parameters:
  
  T - the type parameter | 类型参数
  
  Parameters:
  
  yaml - the YAML string | YAML 字符串
  
  type - the target type | 目标类型
  
  Returns:
  
  the bound object | 绑定的对象
- toMap
  
  public static Map<String,Object> toMap(Object object)
  
  Converts object to a Map. 将对象转换为 Map。
  
  Parameters:
  
  object - the object | 对象
  
  Returns:
  
  the map | 映射
- merge
  
  public static Map<String,Object> merge(Map<String,Object> base, Map<String,Object> overlay)
  
  Merges two YAML maps. 合并两个 YAML 映射。
  
  Parameters:
  
  base - the base map | 基础映射
  
  overlay - the overlay map | 覆盖映射
  
  Returns:
  
  the merged map | 合并后的映射
- merge
  
  public static Map<String,Object> merge(Map<String,Object> base, Map<String,Object> overlay, MergeStrategy strategy)
  
  Merges two YAML maps with strategy. 使用策略合并两个 YAML 映射。
  
  Parameters:
  
  base - the base map | 基础映射
  
  overlay - the overlay map | 覆盖映射
  
  strategy - the merge strategy | 合并策略
  
  Returns:
  
  the merged map | 合并后的映射
- mergeAll
  
  @SafeVarargs public static Map<String,Object> mergeAll(Map<String,Object>... maps)
  
  Merges multiple YAML maps. 合并多个 YAML 映射。
  
  Parameters:
  
  maps - the maps to merge | 要合并的映射
  
  Returns:
  
  the merged map | 合并后的映射
- merge
  
  public static YmlDocument merge(YmlDocument base, YmlDocument overlay)
  
  Merges two documents. 合并两个文档。
  
  Parameters:
  
  base - the base document | 基础文档
  
  overlay - the overlay document | 覆盖文档
  
  Returns:
  
  the merged document | 合并后的文档
- resolvePlaceholders
  
  public static String resolvePlaceholders(String yaml)
  
  Resolves placeholders in YAML string. 解析 YAML 字符串中的占位符。
  
  Parameters:
  
  yaml - the YAML string | YAML 字符串
  
  Returns:
  
  the resolved YAML | 解析后的 YAML
- resolvePlaceholders
  
  public static String resolvePlaceholders(String yaml, PlaceholderResolver resolver)
  
  Resolves placeholders in YAML string with resolver. 使用解析器解析 YAML 字符串中的占位符。
  
  Parameters:
  
  yaml - the YAML string | YAML 字符串
  
  resolver - the placeholder resolver | 占位符解析器
  
  Returns:
  
  the resolved YAML | 解析后的 YAML
- resolvePlaceholders
  
  public static Map<String,Object> resolvePlaceholders(Map<String,Object> data)
  
  Resolves placeholders in map values. 解析映射值中的占位符。
  
  Parameters:
  
  data - the data map | 数据映射
  
  Returns:
  
  the resolved map | 解析后的映射
- parseWithPlaceholders
  
  public static YmlDocument parseWithPlaceholders(String yaml)
  
  Parses YAML with placeholder resolution. 解析 YAML 并解析占位符。
  
  Parameters:
  
  yaml - the YAML string | YAML 字符串
  
  Returns:
  
  the document with resolved placeholders | 解析了占位符的文档
- parseWithPlaceholders
  
  public static YmlDocument parseWithPlaceholders(String yaml, Map<String,String> properties)
  
  Parses YAML with placeholder resolution using custom properties. 使用自定义属性解析 YAML 并解析占位符。
  
  Parameters:
  
  yaml - the YAML string | YAML 字符串
  
  properties - the properties for placeholder resolution | 用于占位符解析的属性
  
  Returns:
  
  the document with resolved placeholders | 解析了占位符的文档
- isValid
  
  public static boolean isValid(String yaml)
  
  Checks if YAML string is valid. 检查 YAML 字符串是否有效。
  
  Parameters:
  
  yaml - the YAML string | YAML 字符串
  
  Returns:
  
  true if valid | 如果有效则返回 true
- parseTree
  
  public static YmlNode parseTree(String yaml)
  
  Parses YAML to a node tree. 将 YAML 解析为节点树。
  
  Parameters:
  
  yaml - the YAML string | YAML 字符串
  
  Returns:
  
  the root node | 根节点
- diff
  
  public static List<DiffEntry> diff(Map<String,Object> base, Map<String,Object> other)
  
  Compares two YAML maps and returns a list of differences. 比较两个 YAML 映射并返回差异列表。
  
  Parameters:
  
  base - the base map | 基础映射
  
  other - the other map | 另一个映射
  
  Returns:
  
  list of diff entries | 差异条目列表
- diff
  
  public static List<DiffEntry> diff(YmlDocument base, YmlDocument other)
  
  Compares two YAML documents and returns a list of differences. 比较两个 YAML 文档并返回差异列表。
  
  Parameters:
  
  base - the base document | 基础文档
  
  other - the other document | 另一个文档
  
  Returns:
  
  list of diff entries | 差异条目列表
- loadProfile
  
  public static YmlDocument loadProfile(Path basePath, String name, String... profiles)
  
  Loads configuration with profile overlays. 加载带有 Profile 覆盖的配置。
  Loads {basePath}/{name}.yml as the base, then overlays {basePath}/{name}-{profile}.yml for each profile.
  
  加载 {basePath}/{name}.yml 作为基础，然后为每个 Profile 覆盖 {basePath}/{name}-{profile}.yml。
  
  Parameters:
  
  basePath - the directory containing config files | 包含配置文件的目录
  
  name - the base config file name (without extension) | 基础配置文件名（无扩展名）
  
  profiles - the profile names to overlay | 要覆盖的 Profile 名称
  
  Returns:
  
  the merged document | 合并后的文档
- loadDefaultProfile
  
  public static YmlDocument loadDefaultProfile(Path directory, String... profiles)
  
  Loads configuration with profile overlays using default name "application". 使用默认名称 "application" 加载带有 Profile 覆盖的配置。
  
  Parameters:
  
  directory - the directory containing config files | 包含配置文件的目录
  
  profiles - the profile names to overlay | 要覆盖的 Profile 名称
  
  Returns:
  
  the merged document | 合并后的文档
- loadWithIncludes
  
  public static Map<String,Object> loadWithIncludes(Path file)
  
  Loads a YAML file with !include directive resolution. 加载带有 !include 指令解析的 YAML 文件。
  
  Parameters:
  
  file - the YAML file to load | 要加载的 YAML 文件
  
  Returns:
  
  the resolved YAML data as a map | 解析后的 YAML 数据映射

Class OpenYml

Method Summary

Methods inherited from class Object

Method Details

load

parse

loadFile

loadFile

loadStream

loadAll

dump

dump

dump

dumpObject

writeFile

writeFile

write

dumpAll

bind

bind

bind

toMap

merge

merge

mergeAll

merge

resolvePlaceholders

resolvePlaceholders

resolvePlaceholders

parseWithPlaceholders

parseWithPlaceholders

isValid

parseTree

diff

diff

loadProfile

loadDefaultProfile

loadWithIncludes