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)

This method is deprecated and subject for removal. Use the scalar formatter instead.

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

Scalar formatter

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

Sets the scalar formatter to use when formatting scalar nodes.

Scalar nodes are nodes representing a String, 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.

Always make sure to check the provided tag (datatype of the node)!

For example, the following formatter:

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:

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

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.

Example: leave all string keys plain (unquoted) and quote all string values

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;
})

Default: an identity formatter (which always returns the default scalar style for all nodes) Related parent method docs (v2.3): click Related YAML spec (v1.2.2): for BLOCK flow style, for FLOW flow style

Sequence formatter

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

Mapping formatter

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

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

Schema

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

• #setFlowStyle(FlowStyle) is set to FlowStyle#FLOW,

• #setScalarStyle(ScalarStyle) is set to ScalarStyle#DOUBLE_QUOTED,

• #setMultilineStyle(boolean) is enabled,

• #setMaxSimpleKeyLength(int) is set to 1,

• #setStartMarker(boolean) 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 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