Skip to content

1.8
Compare
Choose a tag to compare
@Carleslc Carleslc released this 18 Mar 12:08
· 11 commits to master since this release
1.8
510904f

The examples have been improved with the new features:

Comment Fixes

  • #42 Fixes issues with # character inside values or side comments

Comment Formatting

  • #53 Header behaviour has changed to be more intuitive. Now the header is considered to be the first block comment until a blank line (i.e. with no direct key below), instead of everything above the first key like before. The comment on the first key does not overlap anymore with the header. The header and the first key comment are separated by a blank line.
  • Footer methods have been added for the last comment of the file without any key below.
  • You can customize the header format using yamlFile.options().headerFormatter(YamlHeaderFormatter).
  • #53 #54 Comments now can be formatted, either by default or per comment.

Now it is possible to format comments using prefixes and suffixes, globally or per comment, taking into account blank lines as comments, with some configurations available for reading comments (for instance stripping the # prefix and stripping trailing or leading blank lines), using an instance of YamlCommentFormatter or a custom format implementing CommentFormatter.

Some formatters are available with the YamlCommentFormat enum. For instance, the following will add blank lines above of the comments you add on keys with indent 0:

yamlFile.setCommentFormat(YamlCommentFormat.PRETTY);

The default prefix is "# " for block comments and " # " for side comments. You can change them to add blank lines above or below the comments, or to add more spaces, # characters or section dividers.

Examples:

Changing Quote Style

yamlFile.set("quote", "This is double quote style", QuoteStyle.DOUBLE);

More information here.

List indexing

You can use list indexing to select list values with array notation. This is especially useful if you want to get a single element, set a comment on a specific index or set different comments on list values that are not unique.

Negative indexing is allowed (list[-1] is the last element).

See the example with values and example with comments.

Other features

  • An alternative API has been added using the path(String) method to set comments along with values without repeating the path.
yamlFile.path("test.hello")
         .set("Hello")
         .comment("Block comment")
         .commentSide("Side comment");
  • Path separator can be escaped with \ character prefix, for instance getString("a\.b.c") selects a\.b -> c. In previous versions that would have been a\ -> b -> c. This is for specific scenarios, but if you usually have dots in keys consider changing the path separator to something else like /, in that case getString("a.b/c") selects a.b -> c.

Implementation abstraction

Now the snakeyaml implementation is decoupled from YamlConfiguration class.

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) if you don't want to use snakeyaml.

More information here.

@Deprecated

If you were loading a file with loadConfiguration(Reader) or loadConfiguration(InputStream) those methods have been deprecated. Use loadConfiguration(SupplierIO.Reader) or loadConfiguration(SupplierIO.InputStream) instead:
Change YamlFile.loadConfiguration(new BufferedReader(...)) to YamlFile.loadConfiguration(() -> new BufferedReader(...)) or YamlFile.loadConfiguration(new FileInputStream(file)) to YamlFile.loadConfiguration(() -> new FileInputStream(file)).

Previously while loading or saving a file the whole file was stored in a String in memory before parsing or dumping the yaml file. This is acceptable for small to medium configuration files, but now writing the yaml in memory to a StringBuilder is not required, so this is an improvement in memory usage.

Loading a YamlFile with load or loadWithComments and saving with save have this improvement automatically so you don't have to change anything in that case.

Assets 4
Loading