DumperSettings

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

PreviousLoaderSettings NextUpdaterSettings

Last updated 11 months ago

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

Scalar style

Builder#setScalarStyle(@NotNull ScalarStyle scalarStyle)

Sets the scalar style to use.

Default: Parent method docs (v2.3): Related YAML spec (v1.2.2): ,

String style

Builder#setStringStyle(@NotNull ScalarStyle stringStyle)

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

Scalar formatter

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

Sets the scalar formatter to use when formatting scalar nodes.

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

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.

Mapping formatter

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

Sets the mapping formatter to use when formatting mapping nodes.

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.

Indentation

Builder#setIndentation(int spaces)

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

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

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.

Document end marker

Builder#setEndMarker(boolean endMarker)

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

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.

Root tag

Builder#setRootTag(@Nullable Tag rootTag)

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

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

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.

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.

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.

Multiline style

Builder#setMultilineStyle(boolean multilineStyle)

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.

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.

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.

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

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

Line break

Builder#setLineBreak(@NotNull String lineBreak)

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

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.

PreviousLoaderSettings NextUpdaterSettings

Last updated 11 months ago