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

packagecom.example.myplugin;
importme.croabeast.file.ConfigurableFile;
importme.croabeast.file.YAMLFile;
importorg.bukkit.configuration.file.FileConfiguration;
importorg.bukkit.plugin.java.JavaPlugin;
importjava.io.IOException;
publicclassMyPluginextendsJavaPlugin {
privateConfigurableFileconfig;
@OverridepublicvoidonEnable() {
try {
// Create a new configuration file located in the "config" folderconfig = newConfigurableFile(this, "config", "settings")
// Optionally, override methods to control updatability or other behaviors
{
@OverridepublicbooleanisUpdatable() {
// Retrieve the "update" key from the configuration to decide if updates are allowedreturnget("update", false);
}
};
// Save the default configuration if not presentconfig.saveDefaults();
// Update the configuration file (merges defaults and preserves comments)config.update();
} catch (IOExceptione) {
e.printStackTrace();
}
// Access configuration valuesStringprefix = config.get("lang-prefix", "&e MyPlugin »&7");
getLogger().info("Language prefix: " + prefix);
}
}

Example: Working with Mappable and SectionMappable

packagecom.example.myplugin;
importme.croabeast.file.SectionMappable;
importme.croabeast.file.ConfigurableFile;
importorg.bukkit.configuration.ConfigurationSection;
importorg.bukkit.plugin.java.JavaPlugin;
publicclassMyPluginextendsJavaPlugin {
privateConfigurableFileconfig;
@OverridepublicvoidonEnable() {
try {
config = newConfigurableFile(this, "config", "settings");
config.saveDefaults();
config.update();
} catch (Exceptione) {
e.printStackTrace();
}
// Assume we have a configuration section "advancements"ConfigurationSectionsection = config.getConfiguration().getConfigurationSection("advancements");
if (section != null) {
// Create a SectionMappable from the configuration sectionSectionMappable.SetsectionMap = SectionMappable.asSet(section.getValues(false));
// Process the mapped configuration as neededgetLogger().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