YAML – Block Styles

YAML - Block Scalar Styles

YAML provides powerful block scalar styles for representing multi-line strings. These styles offer fine-grained control over how newlines and indentation are handled, making YAML suitable for embedding text like scripts, poems, or long descriptions.

The two main block scalar styles are:

• Literal Style (|): Preserves all newlines within the block.
• Folded Style (>): Folds newlines into spaces, but preserves paragraph breaks (blank lines or more indented lines).

These styles are initiated by a header character (| or >) which can be followed by chomping indicators (to control trailing newlines) and, optionally, an indentation indicator (less common).

Literal Style (|)

The literal style preserves all newlines within the block. Each line break in the YAML source becomes a newline character in the resulting string. Leading whitespace on each line is also preserved.

literal_example: |
  This is the first line.
  This is the second line.
    This line is indented.

  This line is after a blank line.

The literal_example string would be (using \n to represent newline characters):

"This is the first line.\nThis is the second line.\n  This line is indented.\n\nThis line is after a blank line.\n"

Folded Style (>)

The folded style is designed for long blocks of text. It folds newlines within a paragraph into spaces. A new paragraph (resulting in a newline character in the string) is started by a blank line or a line that is more indented than the current paragraph.

folded_example: >
  This is a long sentence
  that has been written on multiple lines
  in the YAML source.

  This starts a new paragraph because of the blank line.
    This line starts another new paragraph
    because it's more indented.

The folded_example string would be:

"This is a long sentence that has been written on multiple lines in the YAML source.\n\nThis starts a new paragraph because of the blank line.\n  This line starts another new paragraph\n  because it's more indented.\n"

Controlling Trailing Newlines: Chomping Indicators

Chomping indicators control how final newlines at the end of a block scalar are handled. They are appended to the style indicator (e.g., |-, >+). There are three types:

Strip (-)

The strip chomping indicator (-) removes all trailing newlines from the end of the block. If the block ends with one or more newlines, they are all removed. If it doesn’t end with a newline, nothing changes.

strip_chomping: |-
  Line 1
  Line 2

# (Imagine the block ends here, after the blank line)

Resulting string for strip_chomping: "Line 1\nLine 2" (no trailing newline).

Clip (Default)

Clipping is the default behavior if no chomping indicator is specified (or | or > is used alone). If the scalar ends with one or more newlines, clipping results in a single trailing newline. If the scalar does not end with any newline characters (i.e., the very last character of content is not a newline), then no newline is added.

clip_chomping_default: |
  Line 1
  Line 2

# (Block ends after the blank line)

clip_chomping_no_final_char_newline: |
  Line 1
  Line 2 # (Imagine no newline char after '2' in this line within the block)

Resulting string for clip_chomping_default: "Line 1\nLine 2\n" (one trailing newline).

Resulting string for clip_chomping_no_final_char_newline (if the last content character isn’t a newline): "Line 1\nLine 2".

Keep (+)

The keep chomping indicator (+) preserves all trailing newlines. If the block scalar ends with one or more newlines, all of them are kept in the resulting string.

keep_chomping: |+
  Line 1
  Line 2


# (Block ends after two blank lines)

Resulting string for keep_chomping: "Line 1\nLine 2\n\n\n" (all three trailing newlines preserved).

Practical Applications

Block styles are invaluable for various scenarios:

• Embedding code snippets (e.g., shell scripts, JSON, SQL) within YAML: Literal style (|) is often preferred here to preserve exact formatting.
• Storing multi-line text such as poems, commit messages, or detailed descriptions.
• Configuration values that inherently span multiple lines, like SSH keys, SSL certificates, or multi-line log formats.
• Folded style (>) is excellent for long paragraphs of human-readable text, maintaining readability in the YAML source while collapsing it into a continuous string with appropriate paragraph breaks.

Common Pitfalls and Best Practices

• Indentation is Key: The content of a block scalar must be more indented than its parent key. Inconsistent indentation within the block itself (relative to its first line) is part of the content.
• Chomping Choices: Understand the effect of chomping indicators. Incorrect chomping can lead to unexpected newlines or missing newlines, which can be critical for scripts or formatted text.
• Folded Style Nuances: Remember that folded style (>) only introduces actual newlines in the output for blank lines or more-indented lines in the source. Other newlines are typically folded into spaces.
• Readability: Use block styles to enhance the readability of your YAML, especially for complex string values.

To experiment with block styles, chomping, and see their effects in real-time, consider using an online YAML parser or validator. Searching for ‘online YAML linter’ or ‘online YAML parser’ will provide several helpful tools.