Skip to content

Commit db3a255

Browse files
CroaBeastCroaBeast
committed
Initial commit
0 parents  commit db3a255

17 files changed

Lines changed: 2825 additions & 0 deletions

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# Project exclude paths
2+
/target/

‎README‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# YAML API
2+
3+
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.
4+
5+
---
6+
7+
## Overview
8+
9+
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.
10+
11+
Key components include:
12+
13+
- **YAMLFile**: A class to load, save, and update YAML configuration files.
14+
- **ResourceUtils**: Utility methods for handling resources and file operations.
15+
- **Configurable & ConfigurableFile**: Interfaces and classes that provide easy access to the underlying `FileConfiguration`.
16+
- **ConfigurableUnit**: An interface representing a configuration unit, useful for handling permissions or groups in the configuration.
17+
- **Mappable, SectionMappable, UnitMappable & HashMappable**: A set of interfaces and classes for mapping configuration sections and units into Java collections.
18+
- **YAMLUpdater**: A class that updates YAML files by merging default values and preserving comments.
19+
20+
---
21+
22+
## Key Features
23+
24+
- **Unified Configuration Management**:
25+
Provides a consistent API for reading, writing, and updating YAML configuration files.
26+
27+
- **Dynamic Mapping and Conversion**:
28+
Supports mapping configuration sections to custom units and collections, making it easier to work with complex configuration structures.
29+
30+
- **Resource and File Utilities**:
31+
Includes helper classes to simplify file loading, resource saving, and directory management.
32+
33+
- **Comment Preservation and Updates**:
34+
YAMLUpdater handles merging of default configuration values while preserving existing comments.
35+
36+
- **Reflection-Based Parsing**:
37+
Uses reflection to dynamically access configuration sections and values, ensuring compatibility across server versions.
38+
39+
---
40+
41+
## Usage Example
42+
43+
Below is an example demonstrating how to use the YAML API to load, update, and work with configuration files.
44+
45+
### Example: Using ConfigurableFile and YAMLFile
46+
47+
```java
48+
package com.example.myplugin;
49+
50+
import me.croabeast.file.ConfigurableFile;
51+
import me.croabeast.file.YAMLFile;
52+
import org.bukkit.configuration.file.FileConfiguration;
53+
import org.bukkit.plugin.java.JavaPlugin;
54+
55+
import java.io.IOException;
56+
57+
public class MyPlugin extends JavaPlugin {
58+
59+
private ConfigurableFile config;
60+
61+
@Override
62+
public void onEnable() {
63+
try {
64+
// Create a new configuration file located in the "config" folder
65+
config = new ConfigurableFile(this, "config", "settings")
66+
// Optionally, override methods to control updatability or other behaviors
67+
{
68+
@Override
69+
public boolean isUpdatable() {
70+
// Retrieve the "update" key from the configuration to decide if updates are allowed
71+
return get("update", false);
72+
}
73+
};
74+
// Save the default configuration if not present
75+
saveDefaultConfig();
76+
// Update the configuration file (merges defaults and preserves comments)
77+
config.update();
78+
} catch (IOException e) {
79+
e.printStackTrace();
80+
}
81+
82+
// Access configuration values
83+
FileConfiguration conf = config.getConfiguration();
84+
String prefix = conf.getString("lang-prefix", "&e MyPlugin »&7");
85+
getLogger().info("Language prefix: " + prefix);
86+
}
87+
}
88+
```
89+
90+
### Example: Working with Mappable and SectionMappable
91+
92+
```java
93+
package com.example.myplugin;
94+
95+
import me.croabeast.file.SectionMappable;
96+
import me.croabeast.file.ConfigurableFile;
97+
import org.bukkit.configuration.ConfigurationSection;
98+
import org.bukkit.plugin.java.JavaPlugin;
99+
100+
public class MyPlugin extends JavaPlugin {
101+
102+
private ConfigurableFile config;
103+
104+
@Override
105+
public void onEnable() {
106+
try {
107+
config = new ConfigurableFile(this, "config", "settings");
108+
config.saveDefaults();
109+
config.update();
110+
} catch (Exception e) {
111+
e.printStackTrace();
112+
}
113+
114+
// Assume we have a configuration section "advancements"
115+
ConfigurationSection section = config.getConfiguration().getConfigurationSection("advancements");
116+
if (section != null) {
117+
// Create a SectionMappable from the configuration section
118+
SectionMappable.Set sectionMap = SectionMappable.asSet(section.getValues(false));
119+
// Process the mapped configuration as needed
120+
getLogger().info("Loaded advancements: " + sectionMap);
121+
}
122+
}
123+
}
124+
```
125+
126+
---
127+
128+
## Conclusion
129+
130+
**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.
131+
132+
Happy coding!
133+
— *CroaBeast*

‎pom.xml‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<modelVersion>4.0.0</modelVersion>
6+
7+
<groupId>me.croabeast</groupId>
8+
<artifactId>file</artifactId>
9+
<version>0.1.0</version>
10+
<packaging>jar</packaging>
11+
12+
<properties>
13+
<java.version>1.8</java.version>
14+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
15+
</properties>
16+
17+
<build>
18+
<plugins>
19+
<plugin>
20+
<groupId>org.apache.maven.plugins</groupId>
21+
<artifactId>maven-compiler-plugin</artifactId>
22+
<version>3.8.1</version>
23+
<configuration>
24+
<source>${java.version}</source>
25+
<target>${java.version}</target>
26+
</configuration>
27+
</plugin>
28+
<plugin>
29+
<groupId>org.apache.maven.plugins</groupId>
30+
<artifactId>maven-shade-plugin</artifactId>
31+
<version>3.2.4</version>
32+
<executions>
33+
<execution>
34+
<phase>package</phase>
35+
<goals>
36+
<goal>shade</goal>
37+
</goals>
38+
<configuration>
39+
<createDependencyReducedPom>false</createDependencyReducedPom>
40+
</configuration>
41+
</execution>
42+
</executions>
43+
</plugin>
44+
</plugins>
45+
<resources>
46+
<resource>
47+
<directory>src/main/resources</directory>
48+
<filtering>true</filtering>
49+
</resource>
50+
</resources>
51+
</build>
52+
53+
<repositories>
54+
<repository>
55+
<id>spigotmc-repo</id>
56+
<url>https://hub.spigotmc.org/nexus/content/repositories/snapshots/</url>
57+
</repository>
58+
<repository>
59+
<id>sonatype</id>
60+
<url>https://oss.sonatype.org/content/groups/public/</url>
61+
</repository>
62+
</repositories>
63+
64+
<dependencies>
65+
<dependency>
66+
<groupId>org.jetbrains</groupId>
67+
<artifactId>annotations</artifactId>
68+
<version>24.0.1</version>
69+
<scope>provided</scope>
70+
</dependency>
71+
<dependency>
72+
<groupId>org.projectlombok</groupId>
73+
<artifactId>lombok</artifactId>
74+
<version>1.18.26</version>
75+
<scope>provided</scope>
76+
</dependency>
77+
<dependency>
78+
<groupId>org.spigotmc</groupId>
79+
<artifactId>spigot-api</artifactId>
80+
<version>1.16.5-R0.1-SNAPSHOT</version>
81+
<scope>provided</scope>
82+
</dependency>
83+
</dependencies>
84+
</project>

‎src/main/java/me/croabeast/file/Builder.java‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
package me.croabeast.file;
2+
3+
import org.jetbrains.annotations.NotNull;
4+
5+
/**
6+
* A foundational interface for builder patterns, ensuring a self-referential type.
7+
*
8+
* @param <B> the specific builder type extending this interface
9+
*/
10+
public interface Builder<B extends Builder<B>> {
11+
12+
/**
13+
* Provides an instance of the builder, ensuring fluent-style method chaining.
14+
*
15+
* @return the builder instance
16+
*/
17+
@NotNull
18+
B instance();
19+
}

0 commit comments

Comments
 (0)