Lightning.ExportUtils.Scalar (Lightning v2.19.0-pre)

Encodes single strings as YAML scalars for project export.

Lightning.ExportUtils builds the project spec by concatenating strings, so every name, label and identifier has to be quoted and escaped here.

Output has to stay byte-identical for anything already emitted correctly: customers keep their project spec in git, so a change in quoting style is a diff in every synced repo. That is why the bare and single-quoted shapes below are the historic ones rather than what a general purpose YAML writer would pick.

Summary

Functions

encode_block(value, indent)

Encodes a multi-line value as a literal block scalar, header and indented body together, ready to follow "key: ".

encode_key(key)

Encodes a string as a YAML mapping key.

encode_quoted_value(value)

Encodes a string as a YAML scalar that is always quoted, never left bare.

encode_value(value)

Encodes a string as a YAML scalar suitable for the right hand side of a mapping entry or for a sequence item.

Functions

encode_block(value, indent)

@spec encode_block(binary(), binary()) :: binary()

Encodes a multi-line value as a literal block scalar, header and indented body together, ready to follow "key: ".

The historic shape is kept byte for byte, including the trailing newline the reader adds to a body that did not have one. The cond below documents the three shapes that shape gets wrong.

encode_key(key)

@spec encode_key(binary()) :: binary()

Encodes a string as a YAML mapping key.

Keys use double quotes rather than single quotes, which is the style the export has always used for them.

encode_quoted_value(value)

@spec encode_quoted_value(binary()) :: binary()

Encodes a string as a YAML scalar that is always quoted, never left bare.

Used for adaptor and cron expression, which have always been quoted. A cron with no wildcard, such as 5 4 1 1 1, is bare-legal, and letting it come out bare would be a one-line diff in every synced repo that has one.

encode_value(value)

@spec encode_value(binary()) :: binary()

Encodes a string as a YAML scalar suitable for the right hand side of a mapping entry or for a sequence item.