Usage

(4min read) Basic file operations to get started.

🗃️ Structure

Every entry (key=value pair) in the document is represented as a block.

1. Blocks carry the comments and the actual value (Java object).

2. Sections are extensions of blocks representing Map values and provide plenty of methods for data accessing and modification. The document is also a section - the root section.

Migrating from Spigot/BungeeCord API?

Example plugin showing you everything described on this page is available at https://github.com/dejvokep/boosted-yaml-example -> look at the config.yml and onEnable() method.

Also, sections in BoostedYAML are similar to ConfigurationSection with a few differences, listed at the method translation table for sections. You may want to read it to get along with the API quicker. 😄

BoostedYAML uses "routes" (URI-like objects) to access and modify data (like paths in Spigot/BungeeCord API). Please read a short article about them - you'll need it: 👍

Routes

➕ Creating a document

You can create and initially load a document using any of the provided YamlDocument.create() methods (click HERE for JavaDoc):

// With defaults:
YamlDocument.create(File document, InputStream defaults, Settings... settings)
YamlDocument.create(InputStream document, InputStream defaults, Settings... settings)
// Without defaults:
YamlDocument.create(File document, Settings... settings)
YamlDocument.create(InputStream document, Settings... settings)

There are 4 types of settings you can provide: GeneralSettings, LoaderSettings, DumperSettings and UpdaterSettings. These modify the behaviour of the documents during runtime, loading, dumping and updating.

• Document: the actual content that will be loaded and made available to you.

• Defaults: the default version of the document, usually bundled under "resources". Optional, but are required if you'd like to obtain default values of missing/invalid mappings.

If you chose to use KeyFormat.OBJECT (article about routes) provide it here via GeneralSettings (KeyFormat.STRING is the default).

Building with boosted-yaml-spigot?

If you want to continue using ConfigurationSerialization, provide custom GeneralSettings with the Spigot-compatible serializer:

GeneralSettings.builder().setSerializer(SpigotSerializer.getInstance()).build()

This serializer is only a bridge between BoostedYAML and the Spigot's serialization system. To register classes for serialization, use ConfigurationSerialization just as you have been.

All the provided objects, including settings, are now said to be associated with the document. You will come across this term many times in the documentation.

👷‍♂️ BoostedYAML has insane File management capabilities!

If you give the document as an instance of File, it will be automatically created if it does not exist and saved after each update (yes, everything is customizable). It will be used as input/output, so you can use reload() and save() methods wihout providing any parameter. The file itself will be accessible using getFile().

These features are not available if the document is given as a Stream.

⚡ Choosing to provide defaults is also a huge boost.

Defaults are required by the updater and can also be used to substitute missing or invalid content in the document.

➕ Now, the benefits. By providing them, if a file is being created because it does not exist (see above), it's content and content of the loaded document will be the defaults (instead of an empty file and document). The updater will use the given defaults automatically, so you can not only use update() without any parameter, but also enable automatic updating, so you get up-to-date data each time you (re)load the document.

Selected section methods may reach out to the defaults to substitute deleted or malformed data, or collect all available data (bulk content getters which return a collection of blocks, values, keys...). We understand that this might not be a benefit. If you'd like to provide the defaults for updater and file creation purposes and consumption benefits, but don't want this behaviour, disable use of the defaults via GeneralSettings.

⁉️ What must I do if I don't provide the document as a File and/or the defaults at all?

You will lose access to all features listed above. But don't worry! That doesn't mean you can't load, save or update the file, you will just need to provide the input/output/defaults each time to the method you're using and you must do everything manually (talking about the settings, which will not be effective for you).

Examples

Java native

Uses the class loader to obtain the defaults and uses KeyFormat.OBJECT (Route objects):

YamlDocument.create(new File("file.yml"), getClassLoader().getResource("default_file.yml"), GeneralSettings.builder().setKeyFormat(KeyFormat.OBJECT).build());

Spigot/BungeeCord API users

Configuration compatible with current state of the Spigot/BungeeCord file API:

YamlDocument.create(new File(getDataFolder(), "config.yml"), getResource("config.yml"));

Building with boosted-yaml-spigot

Configuration compatible with current state of the Spigot/BungeeCord file and serialization API (as stated above, continue using ConfigurationSerialization to register your classes):

YamlDocument.create(new File(getDataFolder(), "config.yml"), getResource("config.yml"), GeneralSettings.builder().setSerializer(SpigotSerializer.getInstance()).build();

♻️ Reloading

From the associated File

YamlDocument#reload() throws IOException

Reloads from the associated File (it will fail if there is not any).

The behaviour is the same as loading initially and if the file does not exist, the document will be reloaded from a copy of the defaults (or empty if there are not any). It will also automatically be created and saved to the file (enabled by default).

From another File

YamlDocument#reload(File file) throws IOException

Reloads from the provided File.

If the file does not exist, the document will be reloaded from a copy of the defaults (or empty if there are not any). It will also automatically be created and saved to the file (enabled by default).

From an InputStream

YamlDocument#reload(InputStream inputStream) throws IOException

Reloads from the provided InputStream.

The document will now contain YAML from the stream.

TIP: No matter the method you use, if there are any defaults, you can enable automatic updating (disabled by default), which will ensure your document is always up to date.

📂 Saving (dumping)

To the associated File

YamlDocument#save() throws IOException

Saves to the associated File (it will fail if there is not any) with UTF-8 charset.

To another File

YamlDocument#save(File file) throws IOException

Saves to the provided File with UTF-8 charset.

To an OutputStream

YamlDocument#save(OutputStream stream, Charset charset) throws IOException

Saves to the provided output with the given charset.

To an OutputStreamWriter

YamlDocument#save(OutputStreamWriter writer) throws IOException

Saves to the provided output.

To string

YamlDocument#dump()

Method returns the dumped contents as a string.

TIP: You're welcome to use other methods as well, if you'd like to save using custom (non-associated settings).

🔝 Updating

What is the updater?

Updater is used to update content of YAML documents, to contain at least the content defined by the defaults - while simutaneously doing everything automatically and keeping all comments.

This is a perfect solution for "reset your config" headache, with just one line of code.

Use DVS (document versioning system) to index documents by their versions (revisions). This tells the updater if the document is already up to date (ensuring the best performance) and allows you to use cool and useful features the updater offers. We'll get back to that in a second.

Against the associated defaults

YamlDocument#update() throws IOException

Updates against the associated defaults (it will fail if there are not any).

To ensure you have always up to date document, it is recommended to call this method after creation and each reload. Or, let BoostedYAML all of this for you automatically by enabling automatic updating. ⚡

Against other defaults

YamlDocument#update(InputStream defaults) throws IOException

Loads and updates against the provided defaults.

To ensure you have always up to date document, it is recommended to call this method after creation and each reload.

If there's any associated File, the document will be saved afterwards (enabled by default).

TIP: Use the DVS (document versioning system) to index documents using versions (revisions).

If the document is already up to date, it does not need an update. Document versions tell the updater if this is case and also allows you to use plenty of cool and useful features it offers. Read quick setup here (~2 min).

The cool features you can use:

• relocations: if you moved some content from one place in the document to another,

• ignored routes: for sections which users can freely extend (whose content is not strictly defined),

• mappers: if you changed the datatype of the value, for example for settings which were true/false but are represented by an enum now,

• custom logic: apply custom logic to the document - access, delete, change data your way.

Changing the settings

You can associate new settings at any time using the following method:

YamlDocument#setSettings(@NotNull Settings... settings)

The given settings will be now associated with the document.

This method has replaced the 4 association methods listed below since v1.3.2. These are now deprecated and subject for removal:

YamlDocument#setLoaderSettings(@NotNull LoaderSettings loaderSettings)
YamlDocument#setDumperSettings(@NotNull DumperSettings dumperSettings)
YamlDocument#setGeneralSettings(@NotNull GeneralSettings generalSettings)
YamlDocument#setUpdaterSettings(@NotNull UpdaterSettings updaterSettings)

WARNING!

Always refer to the method documentation, as there are a few limitations to mind and be aware of when re-associating settings.