# Usage

## :card\_box: Structure

Every entry (key=value pair) in the document is represented as a [**block**](https://javadoc.io/doc/dev.dejvokep/boosted-yaml/latest/dev/dejvokep/boostedyaml/block/Block.html).

1. [Blocks](https://javadoc.io/doc/dev.dejvokep/boosted-yaml/latest/dev/dejvokep/boostedyaml/block/Block.html) carry the comments and the actual value (Java object).
2. [Sections](https://javadoc.io/doc/dev.dejvokep/boosted-yaml/latest/dev/dejvokep/boostedyaml/block/implementation/Section.html) are extensions of blocks representing [Map](https://docs.oracle.com/javase/8/docs/api/java/util/Map.html) values and provide plenty of methods for data accessing and modification. The [document](https://javadoc.io/doc/dev.dejvokep/boosted-yaml/latest/dev/dejvokep/boostedyaml/YamlDocument.html) is also a section - the **root** section.

<details>

<summary><strong>Migrating from Spigot/BungeeCord API?</strong></summary>

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](https://dejvokep.gitbook.io/boostedyaml/content-manipulation#method-translation-table). You may want to read it to get along with the API quicker. :smile:

</details>

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: :thumbsup:

{% content-ref url="../routing/routes" %}
[routes](https://dejvokep.gitbook.io/boostedyaml/routing/routes)
{% endcontent-ref %}

## :heavy\_plus\_sign: Creating a document

You can create and initially [**load**](#reloading) a document using any of the provided `YamlDocument.create()` methods (click [HERE](https://javadoc.io/static/dev.dejvokep/boosted-yaml/1.3/dev/dejvokep/boostedyaml/YamlDocument.html) for JavaDoc):

```java
// 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](https://dejvokep.gitbook.io/boostedyaml/settings/generalsettings), [LoaderSettings](https://dejvokep.gitbook.io/boostedyaml/settings/loadersettings), [DumperSettings](https://dejvokep.gitbook.io/boostedyaml/settings/dumpersettings) and [UpdaterSettings](https://dejvokep.gitbook.io/boostedyaml/settings/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](https://dejvokep.gitbook.io/boostedyaml/routing/routes)) provide it here via [GeneralSettings](https://dejvokep.gitbook.io/boostedyaml/settings/generalsettings) (`KeyFormat.STRING` is the default).

<details>

<summary><strong>Building with</strong> <code>boosted-yaml-spigot</code><strong>?</strong></summary>

If you want to continue using [ConfigurationSerialization](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/configuration/serialization/ConfigurationSerialization.html), provide custom [GeneralSettings](https://dejvokep.gitbook.io/boostedyaml/settings/generalsettings) with the Spigot-compatible serializer:

```java
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](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/configuration/serialization/ConfigurationSerialization.html) just as you have been.

</details>

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.

### :man\_construction\_worker: **BoostedYAML has insane** [**File**](https://docs.oracle.com/javase/7/docs/api/java/io/File.html) **management capabilities!**

If you give the document as an instance of [File](https://docs.oracle.com/javase/7/docs/api/java/io/File.html), it will be automatically [created if it does not exist](https://dejvokep.gitbook.io/boostedyaml/settings/loadersettings#create-file-if-absent) and [saved after each update](https://dejvokep.gitbook.io/boostedyaml/settings/updatersettings#save-automatically) (yes, everything is customizable). It will be used as input/output, so you can use [`reload()`](https://javadoc.io/static/dev.dejvokep/boosted-yaml/1.0/dev/dejvokep/boostedyaml/YamlDocument.html#reload--) and [`save()`](https://javadoc.io/static/dev.dejvokep/boosted-yaml/1.0/dev/dejvokep/boostedyaml/YamlDocument.html#save--) methods wihout providing any parameter. The file itself will be accessible using [`getFile()`](https://javadoc.io/static/dev.dejvokep/boosted-yaml/1.0/dev/dejvokep/boostedyaml/YamlDocument.html#getFile--).

These features are not available if the document is given as a [Stream](https://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html).

### :zap: **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.

:heavy\_plus\_sign: 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()`](https://javadoc.io/static/dev.dejvokep/boosted-yaml/1.0/dev/dejvokep/boostedyaml/YamlDocument.html#update--) without any parameter, but also enable [automatic updating](https://dejvokep.gitbook.io/boostedyaml/settings/loadersettings#update-automatically), 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](https://dejvokep.gitbook.io/boostedyaml/settings/generalsettings#use-defaults).

### :interrobang: **What must I do if I don't provide the document as a** [**File**](https://docs.oracle.com/javase/7/docs/api/java/io/File.html) **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

{% tabs %}
{% tab title="Java native" %}
Uses the class loader to obtain the defaults and uses `KeyFormat.OBJECT` (Route objects):

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

{% endtab %}

{% tab title="Spigot/BungeeCord API users" %}
Configuration compatible with current state of the Spigot/BungeeCord file API:

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

{% endtab %}

{% tab title="Building with boosted-yaml-spigot" %}
Configuration compatible with current state of the Spigot/BungeeCord file and serialization API (as stated above, continue using [ConfigurationSerialization](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/configuration/serialization/ConfigurationSerialization.html) to register your classes):

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

{% endtab %}
{% endtabs %}

## :recycle: Reloading

{% tabs %}
{% tab title="From the associated File" %}

```java
YamlDocument#reload() throws IOException
```

Reloads from the **associated** [**File**](https://docs.oracle.com/javase/7/docs/api/java/io/File.html) (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](https://dejvokep.gitbook.io/boostedyaml/settings/loadersettings#create-file-if-absent) to the file (enabled by default).
{% endtab %}

{% tab title="From another File" %}

```java
YamlDocument#reload(File file) throws IOException
```

Reloads from the provided [File](https://docs.oracle.com/javase/7/docs/api/java/io/File.html).

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](https://dejvokep.gitbook.io/boostedyaml/settings/loadersettings#create-file-if-absent) to the file (enabled by default).
{% endtab %}

{% tab title="From an InputStream" %}

```java
YamlDocument#reload(InputStream inputStream) throws IOException
```

Reloads from the provided [InputStream](https://docs.oracle.com/javase/8/docs/api/java/io/InputStream.html).

The document will now contain YAML from the stream.
{% endtab %}
{% endtabs %}

{% hint style="success" %}
**TIP:** No matter the method you use, if there are any defaults, you can enable [automatic updating](https://dejvokep.gitbook.io/boostedyaml/settings/loadersettings#update-automatically) (disabled by default), which will ensure your document is always up to date.
{% endhint %}

## :open\_file\_folder: Saving (dumping)

{% tabs %}
{% tab title="To the associated File" %}

```java
YamlDocument#save() throws IOException
```

Saves to the **associated** [**File**](https://docs.oracle.com/javase/7/docs/api/java/io/File.html) (it will **fail** if there is not any) with UTF-8 charset.
{% endtab %}

{% tab title="To another File" %}

```java
YamlDocument#save(File file) throws IOException
```

Saves to the provided [File](https://docs.oracle.com/javase/7/docs/api/java/io/File.html) with UTF-8 charset.
{% endtab %}

{% tab title="To an OutputStream" %}

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

Saves to the provided output with the given charset.
{% endtab %}

{% tab title="To an OutputStreamWriter" %}

```java
YamlDocument#save(OutputStreamWriter writer) throws IOException
```

Saves to the provided output.
{% endtab %}

{% tab title="To string" %}

```java
YamlDocument#dump()
```

Method returns the dumped contents as a string.
{% endtab %}
{% endtabs %}

{% hint style="success" %}
**TIP:** You're welcome to use other methods as well, if you'd like to save using custom (non-associated settings).
{% endhint %}

## :top: Updating

{% hint style="info" %}
**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.**
{% endhint %}

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.

{% tabs %}
{% tab title="Against the associated defaults" %}

```java
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](#update-automatically). :zap:
{% endtab %}

{% tab title="Against other defaults" %}

```java
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.
{% endtab %}
{% endtabs %}

If there's any **associated** [**File**](https://docs.oracle.com/javase/7/docs/api/java/io/File.html), the document will be [saved afterwards](https://dejvokep.gitbook.io/boostedyaml/settings/updatersettings#save-automatically) (enabled by default).

{% hint style="success" %}
**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](https://dejvokep.gitbook.io/boostedyaml/updater/file-versioning-system) (\~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.
  {% endhint %}

## Changing the settings

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

```java
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:*

<pre class="language-java"><code class="lang-java"><strong>YamlDocument#setLoaderSettings(@NotNull LoaderSettings loaderSettings)
</strong>YamlDocument#setDumperSettings(@NotNull DumperSettings dumperSettings)
YamlDocument#setGeneralSettings(@NotNull GeneralSettings generalSettings)
YamlDocument#setUpdaterSettings(@NotNull UpdaterSettings updaterSettings)
</code></pre>

{% hint style="danger" %}
**WARNING!**

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