DumperSettings

Dumper settings cover all options related explicitly (only) to file dumping.

Creating a builder

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

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

Basic settings

Flow style

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 Parent method docs (v2.3): click Related YAML spec (v1.2.2): node styles

Scalar style

Builder#setScalarStyle(@NotNull ScalarStyle scalarStyle)

Sets the scalar style to use.

Default: ScalarStyle.PLAIN Parent method docs (v2.3): click Related YAML spec (v1.2.2): for BLOCK flow style, for FLOW flow style

String style

Builder#setStringStyle(@NotNull ScalarStyle stringStyle)

Sets the string style to use. This is the same as setScalarStyle(ScalarStyle), 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 Relevant parent method docs (v2.3): click Related YAML spec (v1.2.2): for BLOCK flow style, for FLOW flow style

Indentation

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 Related YAML spec (v1.2.2): indentation

Advanced settings

Anchor generator

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:

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

Default: supplier of NumberAnchorGenerator-s (default anchor generator defined by SnakeYAML Engine) Parent method docs (v2.3): click Related YAML spec (v1.2.2): anchors and aliases

Document start marker

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 Related YAML spec (v1.2.2): document markers

Document end marker

Builder#setEndMarker(boolean endMarker)

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

Default: false (disabled) Parent method docs (v2.3): click Related YAML spec (v1.2.2): document markers

Scalar resolver

Builder#setScalarResolver(@NotNull ScalarResolver resolver)

Sets custom scalar resolver, used to resolve tags for objects.

Default: defined by the parent method Parent method docs (v2.3): click Related YAML spec (v1.2.2): JSON schema tags, failsafe schema tags

Root tag

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 (represented by section) as the top-level object, the given tag must be referring to a class implementing Map 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 Related YAML spec (v1.2.2): JSON schema tags, failsafe schema tags

YAML version directive

Builder#setYamlDirective(@Nullable SpecVersion directive)

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

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 for more information. To avoid problems, update to 1.2 for full support, please.

Default: defined by the parent method Parent method docs (v2.3): click Related YAML spec (v1.2.2): YAML directives

Tag directives

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 Related YAML spec (v1.2.2): TAG directives

Canonical form

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:

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

Default: false (disabled) Parent method docs (v2.3): click Related YAML spec (v1.2.2): canonical form

Multiline style

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.

Default: true (enabled) Parent method docs (v2.3): click Related YAML spec (v1.2.2): -

Encoding

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 Related YAML spec (v1.2.2): character sets

Indicator indentation

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 Related YAML spec (v1.2.2): indentation, indicators

Line width

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).

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

Default: 0 (disabled) Parent method docs (v2.3): click Related YAML spec (v1.2.2): -

Max simple key length

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). If any value greater than 1018 is given, an IllegalArgumentException 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 Related YAML spec (v1.2.2): explicit keys

Line break

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 Related YAML spec (v1.2.2): -

Unprintable character style

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 equivalent Parent method docs (v2.3): click Related YAML spec (v1.2.2): character sets

PreviousLoaderSettingsNextUpdaterSettings

Last updated