# DumperSettings

## Creating a builder

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

```java
DumperSettings.builder() /*configure*/ .build()
```

## Basic settings

### Flow style

```java
Builder#setFlowStyle(@NotNull FlowStyle flowStyle)
```

Sets the flow style to use. Flow styles determine the style of the dumped document. Block style represents an expanded document; flow is somewhat similar to JSON format.

**Default:** [`FlowStyle.BLOCK`](https://javadoc.io/doc/org.snakeyaml/snakeyaml-engine/latest/org/snakeyaml/engine/v2/common/FlowStyle.html#BLOCK)\
**Parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setDefaultFlowStyle\(org.snakeyaml.engine.v2.common.FlowStyle\))\
**Related YAML spec (v1.2.2):** [node styles](https://yaml.org/spec/1.2.2/#3231-node-styles)

### Scalar style

```java
Builder#setScalarStyle(@NotNull ScalarStyle scalarStyle)
```

Sets the scalar style to use.

**Default:** [`ScalarStyle.PLAIN`](https://javadoc.io/doc/org.snakeyaml/snakeyaml-engine/latest/org/snakeyaml/engine/v2/common/ScalarStyle.html#PLAIN)\
**Parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setDefaultScalarStyle\(org.snakeyaml.engine.v2.common.ScalarStyle\))\
**Related YAML spec (v1.2.2):** [for `BLOCK` flow style](https://yaml.org/spec/1.2.2/#81-block-scalar-styles), [for `FLOW` flow style](https://yaml.org/spec/1.2.2/#73-flow-scalar-styles)

### ~~String style~~

```java
Builder#setStringStyle(@NotNull ScalarStyle stringStyle)
```

{% hint style="danger" %}
This method is deprecated and subject for removal. Use the [scalar formatter](#scalar-formatter) instead.
{% endhint %}

~~Sets the string style to use. This is the same as~~ [~~`setScalarStyle(ScalarStyle)`~~](#scalar-style)~~, but used exclusively for String instances.~~

~~You can define whether strings in the dumped (saved) document should always be quoted, double quoted or plain (without quoting) via this setting. You can also choose folded or literal style (used mostly with multiline strings).~~

~~**Default:**~~ [~~`ScalarStyle.PLAIN`~~](https://javadoc.io/doc/org.snakeyaml/snakeyaml-engine/latest/org/snakeyaml/engine/v2/common/ScalarStyle.html#PLAIN)\
~~**Relevant parent method docs (v2.3):**~~ [~~click~~](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setDefaultScalarStyle\(org.snakeyaml.engine.v2.common.ScalarStyle\))\
~~**Related YAML spec (v1.2.2):**~~ [~~for `BLOCK` flow style~~](https://yaml.org/spec/1.2.2/#81-block-scalar-styles)~~,~~ [~~for `FLOW` flow style~~](https://yaml.org/spec/1.2.2/#73-flow-scalar-styles)

### Scalar formatter

```java
Builder#setScalarFormatter(@NotNull Formatter<ScalarStyle, String> formatter)
```

Sets the scalar formatter to use when formatting scalar nodes.

Scalar nodes are nodes representing a [`String`](https://docs.oracle.com/javase/8/docs/api/java/lang/String.html?is-external=true), or any other **primitive** (for sequences and mappings, use the other formatters) datatype like integers, floats and booleans. The value given to the formatter will always be the string representation of the actual scalar (e.g. `"abc"`, `"2.45"`, `"true"` respectively for strings, numbers and booleans). To find out about the datatype the node is representing, use the provided `tag`.

{% hint style="warning" %}
**Always make sure to check the provided tag (datatype of the node)!**

For example, the following formatter:

```java
builder.setScalarFormatter((tag, value, role, def) -> role == NodeRole.KEY ? ScalarStyle.PLAIN : ScalarStyle.DOUBLE_QUOTED)
```

Would also produce not only strings, but also integers, floats... double-quoted:

```yaml
key: !!int "1"
```

**To avoid this,** always make sure to validate that the node you are setting the double-quoted style for is a string (if `tag == Tag.STR`).
{% endhint %}

Formatters are used to alter the resulting YAML style of any given scalar node in the outputted document. They provide you with the default style as the last parameter, which you can return if you do not want to specifically alter the node format.

Please note that the style returned by the formatter for `Tag.STR` might be overridden in order to produce output compliant with the YAML specification. For example, returning style `ScalarStyle.PLAIN` for strings which start with a reserved YAML indicator (like `#` or `-`) will use a quoted style.

<details>

<summary>Example: leave all string keys plain (unquoted) and quote all string values</summary>

```java
builder.setScalarFormatter((tag, value, role, def) -> {
    if (tag != Tag.STR) // if not a string, return the default (otherwise it would also quote numbers..., see the note above)
        return def;
    
    // if this is the key node, dump as a plain string, quote otherwise
    return role == NodeRole.KEY ? ScalarStyle.PLAIN : ScalarStyle.DOUBLE_QUOTED;
})
```

</details>

**Default:** an identity formatter (which always returns the [default scalar style](#scalar-style) for all nodes)\
**Related parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setDefaultScalarStyle\(org.snakeyaml.engine.v2.common.ScalarStyle\))\
**Related YAML spec (v1.2.2):** [for `BLOCK` flow style](https://yaml.org/spec/1.2.2/#81-block-scalar-styles), [for `FLOW` flow style](https://yaml.org/spec/1.2.2/#73-flow-scalar-styles)

### Sequence formatter

```java
Builder#setSequenceFormatter(@NotNull Formatter<FlowStyle, Iterable<?>> formatter)
```

Sets the sequence formatter to use when formatting sequence nodes.

Sequence nodes are nodes which contain a collection of sub-nodes, also called elements, like an array or a list. The provided `tag` will always be `Tag.SEQ` or `Tag.SET`.

Formatters are used to alter the resulting YAML style of any given sequence node in the outputted document. They provide you with the default style as the last parameter, which you can return if you do not want to specifically alter the node format.

Please note that the style returned by the formatter might be overridden in order to produce output compliant with the YAML specification. This only applies to cases when a parent node (map/sequence this sequence is an element of) is `FlowStyle.FLOW`, but the formatter returned `FlowStyle.BLOCK` for this node.

**Default:** an identity formatter (which always returns the [default flow style](#flow-style) for all nodes)\
**Related parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setDefaultFlowStyle\(org.snakeyaml.engine.v2.common.FlowStyle\))\
**Related YAML spec (v1.2.2):** [node styles](https://yaml.org/spec/1.2.2/#3231-node-styles)

### Mapping formatter

```java
Builder#setMappingFormatter(@NotNull Formatter<FlowStyle, Map<?, ?>> formatter)
```

Sets the mapping formatter to use when formatting mapping nodes.

Mapping nodes are nodes which contain a collection of `key=value` pairs, also called a [`map`](https://docs.oracle.com/javase/8/docs/api/java/util/Map.html?is-external=true). The provided `tag` will always be `Tag.MAP`.

Formatters are used to alter the resulting YAML style of any given mapping node in the outputted document. They provide you with the default style as the last parameter, which you can return if you do not want to specifically alter the node format.

Please note that the style returned by the formatter might be overridden in order to produce output compliant with the YAML specification. This only applies to cases when a parent node (map/sequence this mapping is an element of) is `FlowStyle.FLOW`, but the formatter returned `FlowStyle.BLOCK` for this node.

**Default:** an identity formatter (which always returns the [default flow style](#flow-style) for all nodes)\
**Relevant parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setDefaultFlowStyle\(org.snakeyaml.engine.v2.common.FlowStyle\))\
**Related YAML spec (v1.2.2):** [node styles](https://yaml.org/spec/1.2.2/#3231-node-styles)

### Indentation

```java
Builder#setIndentation(int spaces)
```

Sets how many spaces to use per one indent = one level in YAML indentation hierarchy.

**Default:** `2`\
**Parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setIndent\(int\))\
**Related YAML spec (v1.2.2):** [indentation](https://yaml.org/spec/1.2.2/#61-indentation-spaces)

## Advanced settings

### Anchor generator

```java
Builder#setAnchorGenerator(@NotNull Supplier<AnchorGenerator> generator)
```

Sets custom anchor generator supplier used to supply generators when dumping. Anchor generators are used to generate anchor IDs for duplicate nodes.

Supplier ensures that a brand new, yet unused generator, is used on every file dump.

If you do not want to generate any anchors (dump duplicate nodes), supply a generator which will return `null` anchors:

```java
Builder#setAnchorGenerator(() -> node -> null);
```

**Default:** supplier of [NumberAnchorGenerator](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/serializer/NumberAnchorGenerator.html)-s (default anchor generator defined by SnakeYAML Engine)\
**Parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setAnchorGenerator\(org.snakeyaml.engine.v2.serializer.AnchorGenerator\))\
**Related YAML spec (v1.2.2):** [anchors and aliases](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases)

### Document start marker

```java
Builder#setStartMarker(boolean startMarker)
```

Sets if to forcefully add document start marker (`---`). If there are any directives to be dumped, it is added automatically.

**Default:** `false` (disabled)\
**Parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setExplicitStart\(boolean\))\
**Related YAML spec (v1.2.2):** [document markers](https://yaml.org/spec/1.2.2/#document-markers)

### Document end marker

```java
Builder#setEndMarker(boolean endMarker)
```

Sets if to forcefully add document end marker (`...`).

**Default:** `false` (disabled)\
**Parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setExplicitEnd\(boolean\))\
**Related YAML spec (v1.2.2):** [document markers](https://yaml.org/spec/1.2.2/#document-markers)

### Schema

```java
Builder#setSchema(@NotNull Schema schema)
```

Sets custom schema to use. Schemas are used to resolve and determine object tags contained within a document. This setting replaces `setScalarResolver` available until the 1.3.6 release.

**Default:** defined by the parent method\
**Parent method docs (v2.7):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.7/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setSchema\(org.snakeyaml.engine.v2.schema.Schema\))\
**Related YAML spec (v1.2.2):** [JSON schema tags](https://yaml.org/spec/1.2.2/#1021-tags), [failsafe schema tags](https://yaml.org/spec/1.2.2/#failsafe-schema)

### Root tag

```java
Builder#setRootTag(@Nullable Tag rootTag)
```

Sets (explicit) tag of the root document element (top-level element in the document).

As this library does not support anything other than [Map](https://docs.oracle.com/javase/8/docs/api/java/util/Map.html) (represented by section) as the top-level object, the given tag must be referring to a class implementing [Map](https://docs.oracle.com/javase/8/docs/api/java/util/Map.html) interface, serious issues will occur otherwise (the given tag is **not** validated).

If `null`, does not dump any tag for the root section (which will make the resolver resolve it automatically when the document's loaded next time).

**Default:** `null` (none)\
**Parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setExplicitRootTag\(java.util.Optional\))\
**Related YAML spec (v1.2.2):** [JSON schema tags](https://yaml.org/spec/1.2.2/#1021-tags), [failsafe schema tags](https://yaml.org/spec/1.2.2/#failsafe-schema)

### YAML version directive

```java
Builder#setYamlDirective(@Nullable SpecVersion directive)
```

Sets the version (`%YAML`) directive. If `null`, does not dump any explicit version directive.

{% hint style="danger" %}
**For users of YAML 1.1 and older.**

SnakeYAML Engine (upon which BoostedYAML is built) supports YAML 1.2 only, however, per the Engine specification, most of the older YAML can be processed.

Always refer to the [Engine's documentation](https://bitbucket.org/asomov/snakeyaml-engine/wiki/Documentation) for more information. To avoid problems, update to 1.2 for full support, please.
{% endhint %}

**Default:** defined by the parent method\
**Parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setYamlDirective\(java.util.Optional\))\
**Related YAML spec (v1.2.2):** [YAML directives](https://yaml.org/spec/1.2.2/#681-yaml-directives)

### Tag directives

```java
Builder#setTagDirectives(@NotNull Map<String, String> directives)
```

Sets the given tag (`%TAG`) directives in form of a map, where key is the *!handle!* (including the exclamation marks) and value the *prefix* (per the YAML spec).

If there were any tag directives set previously, they are **all** overwritten.

**Default:** defined by the parent method\
**Parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setTagDirective\(java.util.Map\))\
**Related YAML spec (v1.2.2):** [TAG directives](https://yaml.org/spec/1.2.2/#682-tag-directives)

### Canonical form

```java
Builder#setCanonicalForm(boolean canonical)
```

Sets if to dump in canonical form.

Though there is no information and/or specification regarding "canonical form", if enabled (according to experiment shown below), the dumped file looks as if:

* [`#setFlowStyle(FlowStyle)`](#flow-style) is set to [`FlowStyle#FLOW`](https://javadoc.io/doc/org.snakeyaml/snakeyaml-engine/latest/org/snakeyaml/engine/v2/common/FlowStyle.html#FLOW),
* [`#setScalarStyle(ScalarStyle)`](#scalar-style) is set to [`ScalarStyle#DOUBLE_QUOTED`](https://javadoc.io/doc/org.snakeyaml/snakeyaml-engine/latest/org/snakeyaml/engine/v2/common/ScalarStyle.html#DOUBLE_QUOTED),
* [`#setMultilineStyle(boolean)`](#multiline-style) is enabled,
* [`#setMaxSimpleKeyLength(int)`](#maximal-simple-key-length) is set to `1`,
* [`#setStartMarker(boolean)`](#document-start-marker) is enabled.

Enabling this option might overwrite those settings as well, detailed behaviour is not documented.

**Default:** `false` (disabled)\
**Parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setCanonical\(boolean\))\
**Related YAML spec (v1.2.2):** [canonical form](https://yaml.org/spec/1.2.2/#canonical-form)

### Multiline style

```java
Builder#setMultilineStyle(boolean multilineStyle)
```

Sets if to separate content of the document using newlines to make the dumped file somewhat readable; has effect if and only if the flow style is set to [FlowStyle#FLOW](https://javadoc.io/doc/org.snakeyaml/snakeyaml-engine/latest/org/snakeyaml/engine/v2/common/FlowStyle.html#FLOW).

**Default:** `true` (enabled)\
**Parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setMultiLineFlow\(boolean\))\
**Related YAML spec (v1.2.2):** -

### Encoding

```java
Builder#setEncoding(@NotNull Encoding encoding)
```

Sets the encoding to use.

For additional information regarding this option and charsets, please refer to documentation of the parent method listed below.

**Default:** Encoding#UNICODE\
**Parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setUseUnicodeEncoding\(boolean\))\
**Related YAML spec (v1.2.2):** [character sets](https://yaml.org/spec/1.2.2/#51-character-set)

### Indicator indentation

```java
Builder#setIndicatorIndentation(int spaces)
```

Sets how many spaces to use per one indentation level for indicators. If the given value is less than or equal to `0`, disables indicator indentation.

**Default:** `0` (disabled)\
**Parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setIndicatorIndent\(int\))\
**Related YAML spec (v1.2.2):** [indentation](https://yaml.org/spec/1.2.2/#61-indentation-spaces), [indicators](https://yaml.org/spec/1.2.2/#indicator-characters)

### Line width

```java
Builder#setLineWidth(int width)
```

Sets the preferred line width. If any scalar makes the line longer than the given width, the dumper attempts to break the line at the nearest (next) applicable whitespace, if any.

If the given value is less than or equal to `0`, disables the limit and therefore, allows for theoretically unlimited line lengths (up to [Integer.MAX\_VALUE](https://docs.oracle.com/javase/7/docs/api/java/lang/Integer.html#MAX_VALUE)).

For additional information, please refer to documentation of the parent method listed below.

**Default:** `0` (disabled)\
**Parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setWidth\(int\))\
**Related YAML spec (v1.2.2):** -

### Max simple key length

```java
Builder#setMaxSimpleKeyLength(int length)
```

Sets the maximum length a key can (in serialized form, also applies to flow sequence and map keys) have to be printed in simple format (without the explicit key indicator `?`).

If the given value is less than or equal to `0`, disables the limit and therefore, allows for keys of length up to `1024` (limit enforced by the [YAML spec](https://yaml.org/spec/1.2.2/#822-block-mappings)). If any value greater than `1018` is given, an [IllegalArgumentException](https://docs.oracle.com/javase/7/docs/api/java/lang/IllegalArgumentException.html) will be thrown (not a typo - the limit here is lower as there is some "processing").

**Default:** `0` (disabled)\
**Parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setMaxSimpleKeyLength\(int\))\
**Related YAML spec (v1.2.2):** [explicit keys](https://yaml.org/spec/1.2.2/#example-explicit-block-mapping-entries)

### Line break

```java
Builder#setLineBreak(@NotNull String lineBreak)
```

Sets the line break appended at the end of each line.

**Default:** defined by the parent method\
**Parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setBestLineBreak\(java.lang.String\))\
**Related YAML spec (v1.2.2):** -

### Unprintable character style

```java
Builder#setEscapeUnprintable(boolean escape)
Builder#setUnprintableStyle(@NotNull NonPrintableStyle style)
```

Sets if strings containing unprintable characters should have those characters escaped, or the whole string dumped as binary data.

**Default:** `true` (enabled), [NonPrintableStyle.ESCAPE](https://javadoc.io/doc/org.snakeyaml/snakeyaml-engine/latest/org/snakeyaml/engine/v2/common/NonPrintableStyle.html#ESCAPE) equivalent\
**Parent method docs (v2.3):** [click](https://javadoc.io/static/org.snakeyaml/snakeyaml-engine/2.3/org/snakeyaml/engine/v2/api/DumpSettingsBuilder.html#setNonPrintableStyle\(org.snakeyaml.engine.v2.common.NonPrintableStyle\))\
**Related YAML spec (v1.2.2):** [character sets](https://yaml.org/spec/1.2.2/#51-character-set)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dejvokep.gitbook.io/boostedyaml/settings/dumpersettings.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.