YAML API
YAML API 是一个专用库,旨在简化在 Bukkit/Spigot/Paper 插件中处理 YAML 配置文件的工作。它提供了一个强大且一致的接口,用于加载、保存、更新和管理基于 YAML 的配置,并提供了针对配置节和可配置单元的高级映射功能。
概述
YAML API 包提供了一套工具,旨在高效处理 YAML 配置文件。它抽象了文件 I/O 和基于反射的配置解析的复杂性,让你能够专注于在插件中使用配置数据。
关键组件包括:
- YAMLFile:一个用于加载、保存和更新 YAML 配置文件的类。
- ResourceUtils:用于处理资源和文件操作的实用方法。
- Configurable & ConfigurableFile:提供对底层
FileConfiguration 轻松访问的接口和类。
- ConfigurableUnit:表示配置单元的接口,在处理配置中的权限或组时非常有用。
- Mappable, SectionMappable, UnitMappable & HashMappable:一组用于将配置节和单元映射到 Java 集合的接口和类。
- YAMLUpdater:通过合并默认值并保留注释来更新 YAML 文件的类。
主要特性
-
统一的配置管理:
提供了一致的 API 用于读取、写入和更新 YAML 配置文件。
-
动态映射与转换:
支持将配置节映射到自定义单元和集合,使得处理复杂的配置结构变得更加容易。
-
资源与文件工具:
包含辅助类,简化文件加载、资源保存和目录管理。
-
注释保留与更新:
YAMLUpdater 在处理默认配置值的合并时,会保留现有的注释。
-
基于反射的解析:
使用反射动态访问配置节和值,确保跨服务器版本的兼容性。
使用示例
以下示例演示了如何使用 YAML API 加载、更新和处理配置文件。
示例:使用 ConfigurableFile 和 YAMLFile
package com.example.myplugin;
import me.croabeast.file.ConfigurableFile;
import me.croabeast.file.YAMLFile;
import org.bukkit.configuration.file.FileConfiguration;
import org.bukkit.plugin.java.JavaPlugin;
import java.io.IOException;
public class MyPlugin extends JavaPlugin {
private ConfigurableFile config;
@Override
public void onEnable() {
try {
// 在 "config" 文件夹中创建一个新配置文件
config = new ConfigurableFile(this, "config", "settings")
// 可选:重写方法以控制可更新性或其他行为
{
@Override
public boolean isUpdatable() {
// 从配置中获取 "update" 键,以决定是否允许更新
return get("update", false);
}
};
// 如果不存在则保存默认配置
config.saveDefaults();
// 更新配置文件(合并默认值并保留注释)
config.update();
} catch (IOException e) {
e.printStackTrace();
}
// 访问配置值
String prefix = config.get("lang-prefix", "&e MyPlugin »&7");
getLogger().info("Language prefix: " + prefix);
}
}
示例:处理 Mappable 和 SectionMappable
package com.example.myplugin;
import me.croabeast.file.SectionMappable;
import me.croabeast.file.ConfigurableFile;
import org.bukkit.configuration.ConfigurationSection;
import org.bukkit.plugin.java.JavaPlugin;
public class MyPlugin extends JavaPlugin {
private ConfigurableFile config;
@Override
public void onEnable() {
try {
config = new ConfigurableFile(this, "config", "settings");
config.saveDefaults();
config.update();
} catch (Exception e) {
e.printStackTrace();
}
// 假设我们有一个名为 "advancements" 的配置节
ConfigurationSection section = config.getConfiguration().getConfigurationSection("advancements");
if (section != null) {
// 从配置节创建 SectionMappable
SectionMappable.Set sectionMap = SectionMappable.asSet(section.getValues(false));
// 根据需要处理映射后的配置
getLogger().info("Loaded advancements: " + sectionMap);
}
}
}
Maven / Gradle 安装
要将 YAML API 包含到项目中,请将以下仓库和依赖项添加到你的构建配置中。将 ${version} 替换为所需的版本标签。
Maven
将仓库和依赖项添加到你的 pom.xml 中:
<repositories>
<repository>
<id>croabeast-repo</id>
<url>https://croabeast.github.io/repo/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>me.croabeast</groupId>
<artifactId>YAML-API</artifactId>
<version>${version}</version>
<scope>compile</scope>
</dependency>
</dependencies>
Gradle
将仓库和依赖项添加到你的 build.gradle 中:
repositories {
maven {
url "https://croabeast.github.io/repo/"
}
}
dependencies {
implementation "me.croabeast:YAML-API:${version}"
}
将 ${version} 替换为相应的模块版本。
结语
YAML API 是一个强大的库,用于在您的 Bukkit/Spigot/Paper 插件中管理 YAML 配置。它简化了文件操作、映射和更新过程,同时保留注释并确保跨服务器版本的兼容性。无论您是在构建简单的配置系统,还是处理复杂的嵌套设置,YAML API 都能提供高效管理插件配置所需的工具。
祝您编码愉快!
— CroaBeast
YAML API
YAML API is a specialized library that simplifies working with YAML configuration files in Bukkit/Spigot/Paper plugins. It provides a robust and consistent interface for loading, saving, updating, and managing YAML-based configurations, along with advanced mapping capabilities for configuration sections and configurable units.
Overview
The YAML API package offers a set of tools designed to handle YAML configuration files efficiently. It abstracts the complexity of file I/O and reflection-based configuration parsing, allowing you to focus on using configuration data in your plugin.
Key components include:
- YAMLFile: A class to load, save, and update YAML configuration files.
- ResourceUtils: Utility methods for handling resources and file operations.
- Configurable & ConfigurableFile: Interfaces and classes that provide easy access to the underlying
FileConfiguration.
- ConfigurableUnit: An interface representing a configuration unit, useful for handling permissions or groups in the configuration.
- Mappable, SectionMappable, UnitMappable & HashMappable: A set of interfaces and classes for mapping configuration sections and units into Java collections.
- YAMLUpdater: A class that updates YAML files by merging default values and preserving comments.
Key Features
-
Unified Configuration Management:
Provides a consistent API for reading, writing, and updating YAML configuration files.
-
Dynamic Mapping and Conversion:
Supports mapping configuration sections to custom units and collections, making it easier to work with complex configuration structures.
-
Resource and File Utilities:
Includes helper classes to simplify file loading, resource saving, and directory management.
-
Comment Preservation and Updates:
YAMLUpdater handles merging of default configuration values while preserving existing comments.
-
Reflection-Based Parsing:
Uses reflection to dynamically access configuration sections and values, ensuring compatibility across server versions.
Usage Example
Below is an example demonstrating how to use the YAML API to load, update, and work with configuration files.
Example: Using ConfigurableFile and YAMLFile
package com.example.myplugin;
import me.croabeast.file.ConfigurableFile;
import me.croabeast.file.YAMLFile;
import org.bukkit.configuration.file.FileConfiguration;
import org.bukkit.plugin.java.JavaPlugin;
import java.io.IOException;
public class MyPlugin extends JavaPlugin {
private ConfigurableFile config;
@Override
public void onEnable() {
try {
// Create a new configuration file located in the "config" folder
config = new ConfigurableFile(this, "config", "settings")
// Optionally, override methods to control updatability or other behaviors
{
@Override
public boolean isUpdatable() {
// Retrieve the "update" key from the configuration to decide if updates are allowed
return get("update", false);
}
};
// Save the default configuration if not present
config.saveDefaults();
// Update the configuration file (merges defaults and preserves comments)
config.update();
} catch (IOException e) {
e.printStackTrace();
}
// Access configuration values
String prefix = config.get("lang-prefix", "&e MyPlugin »&7");
getLogger().info("Language prefix: " + prefix);
}
}
Example: Working with Mappable and SectionMappable
package com.example.myplugin;
import me.croabeast.file.SectionMappable;
import me.croabeast.file.ConfigurableFile;
import org.bukkit.configuration.ConfigurationSection;
import org.bukkit.plugin.java.JavaPlugin;
public class MyPlugin extends JavaPlugin {
private ConfigurableFile config;
@Override
public void onEnable() {
try {
config = new ConfigurableFile(this, "config", "settings");
config.saveDefaults();
config.update();
} catch (Exception e) {
e.printStackTrace();
}
// Assume we have a configuration section "advancements"
ConfigurationSection section = config.getConfiguration().getConfigurationSection("advancements");
if (section != null) {
// Create a SectionMappable from the configuration section
SectionMappable.Set sectionMap = SectionMappable.asSet(section.getValues(false));
// Process the mapped configuration as needed
getLogger().info("Loaded advancements: " + sectionMap);
}
}
}
Maven / Gradle Installation
To include YAML API to the project, add the following repository and dependency to your build configuration. Replace ${version} with the desired version tag.
Maven
Add the repository and dependency to your pom.xml:
<repositories>
<repository>
<id>croabeast-repo</id>
<url>https://croabeast.github.io/repo/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>me.croabeast</groupId>
<artifactId>YAML-API</artifactId>
<version>${version}</version>
<scope>compile</scope>
</dependency>
</dependencies>
Gradle
Add the repository and dependency to your build.gradle:
repositories {
maven {
url "https://croabeast.github.io/repo/"
}
}
dependencies {
implementation "me.croabeast:YAML-API:${version}"
}
Replace ${version} with the appropriate module version.
Conclusion
YAML API is a powerful library for managing YAML configurations in your Bukkit/Spigot/Paper plugins. It streamlines file operations, mapping, and updates while preserving comments and ensuring compatibility across server versions. Whether you are building simple configuration systems or working with complex, nested settings, YAML API provides the tools you need to efficiently manage your plugin’s configuration.
Happy coding!
— CroaBeast
评论 0
登录后参与评分
还没有评论,来抢沙发吧