GeneralSettings

General settings cover all options related to documents in general.

Creating a builder

Settings introduced by BoostedYAML follow builder design pattern, e.g. you may build your own settings using:

GeneralSettings.builder() /*configure*/ .build()

Settings

Key format

Builder#setKeyFormat(@NotNull KeyFormat keyFormat)

Sets the key format to use; specifies how the loaded/supplied keys should be formatted.

Please read about routing, if you did not do so.

Key format should be chosen based on which routing you'd like to use. You'll also find a bunch of useful notes and examples there.

• KeyFormat.STRING - allows only strings as keys.

  • All keys loaded are converted to strings via Object#toString() (e.g. 5 -> "5"), except null keys, which are considered illegal and will throw an NPE. Please note that such conversion is irrevocable upon saving.

  • This key format ensures compatibility with Spigot/BungeeCord API.

• KeyFormat.OBJECT - allows anything as the key per the YAML specification (that is, integers, strings, doubles...).

  • Preserves keys as they were loaded by SnakeYAML Engine (YAML processor), or supplied.

Default: KeyFormat.STRING

Route separator

Builder#setRouteSeparator(char separator)

Sets route separator used to separate individual keys inside a string route and vice-versa.

Default: '.' (compatible with Spigot/BungeeCord API)

Serializer

Builder#setSerializer(@NotNull YamlSerializer serializer)

Sets serializer used for custom object serialization/deserialization. You can read more about serializers here:

Implementation

Default: StandardSerializer with == set as the serialized type key

Coming from Spigot API and using serialization system of those libraries?

Make sure to implement the correct artifact and setSpigotSerializer.getInstance() for compatiblity. You can then continue registering your custom classes to ConfigurationSerialization.

Use defaults

Builder#setUseDefaults(boolean useDefaults)

Sets if to enable use of the defaults by section methods (if any are present).

Not effective if there are no defaults associated with the document.

If enabled, bulk getter methods (which return a set/map of all keys, routes, values, blocks) will not only include content from the file, but also from the equivalent section in the defaults. Value getters with signature getX(route) will search the defaults as documented.

If disabled, none of the section methods will interact with the defaults. This is recommended if you would like to handle all value absences (present in the defaults, but not in the file) and invalid values manually - e.g. notifying the user and then using the default value defined within final fields, or obtained via Section#getDefaults().

Default values

Runtime defaults

Builder#setDefaultObject(@Nullable Object defaultObject)
Builder#setDefaultNumber(@NotNull Number defaultNumber)
Builder#setDefaultString(@Nullable String defaultString)
Builder#setDefaultChar(@Nullable Character defaultChar)
Builder#setDefaultBoolean(@Nullable Boolean defaultBoolean)
Builder#setDefaultList(@NotNull ListSupplier defaultList)
Builder#setDefaultSet(@NotNull SetSupplier defaultSet)
Builder#setDefaultMap(@NotNull MapSupplier defaultMap)

Defaults used by section methods which don't provide default parameter and have general syntax of Section#getX(Route).

For exact specification regarding which method returns which of these defaults, please visit corresponding method docs.

Default: object: null, number: 0, string: null, char: ' ', boolean: false, list: supplier of ArrayList, set: supplier of LinkedHashSet, map: supplier of LinkedHashMap.

Defaults that are also present in Spigot/BungeeCord API are the same by default.

Load defaults

Builder#setDefaultList(@NotNull ListSupplier defaultList)
Builder#setDefaultSet(@NotNull SetSupplier defaultSet)
Builder#setDefaultMap(@NotNull MapSupplier defaultMap)

Defaults used also during document loading.

For example, if there is a list in the document (unless it has a YAML tag explicitly specified which determines the exact type), it's contents are loaded into a list supplied by the default list supplier.

Default: list: supplier of ArrayList, set: supplier of LinkedHashSet, map: supplier of LinkedHashMap.