Package space.arim.dazzleconf.backend.yaml

Class YamlBackend

java.lang.Object
space.arim.dazzleconf.backend.yaml.YamlBackend
All Implemented Interfaces:
Backend
public final class YamlBackend extends Object implements Backend
A backend for YAML.

The implementation uses a shaded copy of SnakeYAML Engine, which is not exposed, with 'block' flow style enabled.

Environment variables

This backend supports environment variable substitution as described on the SnakeYAML-Engine wiki. For example, a string value can be set to ${DEBUG} (provided it is unquoted) and the "DEBUG" environment variable will be substituted at load time.

Null values

Following the recommended practice of Backend, null values are substituted with the literal string "null".

Comment data

Comments are fully supported, provided they are added through library mechanisms. Note that some comments in YAML files, if not added by this backend (e.g., added by the user), might not be easily recognized as belonging to a certain entry. This backend uses line breaks and indentation to sleuth out where comments belong, and comments are discarded where not supported by the library model (e.g., inline comments on keys instead of values).

Because the backend writes the same line breaks and comments in the locations it expects, it can guarantee round trips for its own comment data. A good way to comply with this backend's expectations is to add an extra line after comments below an entry, to differentiate them from comments above, e.g.: 

     
         # A header for the document always has a blank line separating it from the first entry

         # Comment on 'first-entry'
         first-entry: "hi"
         # Comment on 'option'
         option: "some comments here"
         # Another comment on 'option'
         # Notice the empty space below

         # Comment on 'rest-here'
         rest-here: "hooray!" # Inline comment on 'rest-here'

         # Finally, a footer

  • Constructor Details

    • YamlBackend

      @API(status=EXPERIMENTAL) public YamlBackend(@NonNull ReadableRoot dataRoot, @NonNull URL syntaxLinter)
      Creates from a readable data root, and a URL pointing to a syntax linter.

      The URL, when supplied by this constructor, may be provided to users in the form of error messages. It should point to a live website where end users can paste and validate their configuration file's syntax.

      Parameters:
      dataRoot - the data root from which to read and write
      syntaxLinter - a link to an online syntax linter

    • YamlBackend

      public YamlBackend(@NonNull ReadableRoot dataRoot)
      Creates from a readable data root. For example, to load from a file: 
           
         Backend yamlBackend = new YamlBackend(new PathRoot(Path.of("config.yml")));
         Configuration<MyConfig> configuration = Configuration.defaultBuilder(MyConfig.class).build();
         LoadResult<MyConfig> loaded = configuration.configureWith(yamlBackend);
      Parameters:
      dataRoot - the data root from which to read and write

  • Method Details