Home
Welcome to the BetterYaml wiki!
Easily add/remove config options or contents without overriding the server's settings. This tool is written specifically for Spigot plugins but may be adapted to work in any environment, feel free to fork this repo. We advise using a Maven project for easy dependency management.
You can easily navigate this wiki using the overview on the right.
Our javadocs can be viewed on GitHub pages
-
BetterYaml Usage (use OptionalBetterYaml when possible)
-
BetterLang Setup (included in the BetterYaml dependency!)
BetterYaml uses a template file to handle your config files, this allows you to change comments or config contents very easily (adding or removing options) between plugin updates.
A very important detail in this process is that all server settings will remain intact!
The best part of this that this is all handled automatically! You only need to provide the correct files and make an instance of BetterYaml. After this, you can retrieve a YamlConfiguration and do your regular config reading.
It will make sure that the server's config file is always up to date.
Let's say an earlier version of your software has the following YAML config:
Your current default file
# Your plugin name
# Link to Spigot page
# Some explanation
# This option decides whether or not to give free hot dogs
free_pizza: true
custom_name: "Steve"
Imagine a user has changed free_pizza to false on their server and they removed the first few lines of comments.
User's changed config
# This option decides whether or not to give free hot dogs
free_pizza: false
custom_name: "Steve"
However, after release you notice a mistake in your comments (you mentioned 'free hot dogs' instead of pizza), you want to remove the custom_name option as it is no longer supported and you want to introduce a new option max_free_pizzas. Usually this would be a hassle, but with BetterYaml you can easily change your template without altering the server's settings. Simply update the template and default values and you're good to go. After changing the right files and releasing a new update, your users will get the correct config file right away. This is the new default file you have in mind:
Your new default file
# Your plugin name
# Link to Spigot page
# Some explanation
max_free_pizzas: 3
# This option decides whether or not to give free pizza
free_pizza: true
After installing your update, the user's config will look as follows:
User's config after your update
# Your plugin name
# Link to Spigot page
# Some explanation
max_free_pizzas: 3
# This option decides whether or not to give free pizza
free_pizza: false
Using BetterYaml is very simple once our project is set up.
BetterYaml can be utilised in two different ways, through BetterYaml or OptionalBetterYaml. The former is our legacy approach and is left in to prevent breaking code when upgrading. And the latter is a new addition, which does not require catching Exceptions.
There is no guaranteed support for lists or multi-line values, but nested keys are considered valid.