Quote Style + Implementation abstraction

[Carleslc]

Changing Quote Style

Closes #50

// By default strings are written without quotes if they are not needed so the configuration file remains clean
yamlFile.set("quotes.plain", "This is plain style");

// If a string contains special characters like # then it will be wrapped within single quotes
yamlFile.set("quotes.wrap", "# this is wrapped automatically with single quote style"); // this is a value, not a comment

// If you need it, you can enforce a quote style
yamlFile.set("quotes.custom", "This is double quote style", QuoteStyle.DOUBLE);

// You can change the quote style for all values with specific type
yamlFile.options().quoteStyleDefaults().setQuoteStyle(String.class, QuoteStyle.DOUBLE);
yamlFile.set("quotes.customDefault", "This is double quote style too");

quotes:
  plain: This is plain style
  wrap: '# this is wrapped automatically with single quote style'
  custom: "This is double quote style"
  customDefault: "This is double quote style too"

YamlExample is updated with these changes.

---

Implementation abstraction

This Simple-YAML API was created to decouple the Bukkit dependency so the configuration wrapper can be used in other projects not related to Bukkit/Spigot. Comments is also a concern with YAML libraries so this API was also designed to provide the feature of comment parsing and dumping. Since years ago this API has diverged somewhat from the original Bukkit configuration.

Now the implementation is decoupled from YamlConfiguration class. We are currently using snakeyaml library as the implementation for parsing and dumping yml.

You can access to the implementation if needed with getImplementation():

SnakeYamlImplementation implementation = (SnakeYamlImplementation) yamlFile.getImplementation();
org.yaml.snakeyaml.Yaml yaml = implementation.getYaml();

You can also provide a custom implementation using yamlFile.setImplementation(YamlImplementation), either inheriting an available implementation or providing your own implementing YamlImplementation interface. Currently, there are two available implementations, both based on snakeyaml.

Default implementation is SimpleYamlImplementation which uses the high-level snakeyaml API and a custom comment parser. An alternative is SnakeYamlImplementation which uses the low-level snakeyaml API and snakeyaml comment parser. There are some constructors you can use with both implementations to set a custom snakeyaml Yaml for instance with a custom representer.

For instance, have a look at this example of how to change the default implementation to use a custom representer.

With SnakeYaml it was not possible to parse or save comments in yaml files until recently (version 1.29). Similarly, with the original Spigot YamlConfiguration preserving comments on save was not possible until recently (late 2021), because when saving the file from code then all previous comments in the file were removed. Spigot now provides comments for the ConfigurationSection using the SnakeYaml new comment processor. Simple-YAML also adds the possibility to use a comment formatter to configure spaces or blank lines and other custom prefixes and suffixes to get and set comments.

With SnakeYamlImplementation comment processor there are still some limitations like 100 comments per key. Spigot implementation has some workaround. This limitation does not exist in SimpleYamlImplementation because the comment processor is decoupled from SnakeYaml, but other limitations may arise. If you need it, there is an example of how to access the SnakeYaml implementation from Simple-YAML and use the SnakeYamlImplementation comment processor here, though some presentation details are different from SimpleYamlImplementation, some of them noted here.