YAML – Block Scalar Header

YAML - Block Scalars (Multi-line Strings)

YAML provides powerful mechanisms for representing multi-line strings, known as block scalars. These are particularly useful for embedding text blocks, code snippets, or any string data that spans multiple lines. There are two main types of block scalars: literal style and folded style.

Comments may precede or follow block scalar content but should not be interleaved within the scalar’s lines, as they would become part of the string content.

Literal Style (|)

The literal style, indicated by a pipe character (|), preserves all newlines within the block. Each line break in the YAML source translates to a newline character in the resulting string. The indentation of the block scalar content (relative to the initial | line) is stripped.

poem: |
  Roses are red,
  Violets are blue,
  Sugar is sweet,
  And so are you.

The parsed string value for poem would be: "Roses are red,\nViolets are blue,\nSugar is sweet,\nAnd so are you.\n" (note the trailing newline is also preserved if present from the last line of content, and one is added by default if not chomped).

Folded Style (>)

The folded style, indicated by a greater-than sign (>), generally converts newlines within the block into spaces. However, it preserves newlines that are followed by a more indented line or newlines that appear as blank lines (paragraph breaks).

description: >
  This is a long description
  that spans multiple lines.
  It will be folded into a
  single line, with newlines
  replaced by spaces.

  Paragraph breaks, however,
  like this one, are preserved
  as newlines.

The parsed string value for description would be: "This is a long description that spans multiple lines. It will be folded into a single line, with newlines replaced by spaces.\nParagraph breaks, however, like this one, are preserved as newlines.\n"

Chomping Modifiers

Both literal and folded styles can have chomping modifiers that control how final newlines are handled:

• - (strip): Removes all trailing newlines. For example, |- or >-.
• + (keep): Keeps all trailing newlines, including the very last one if the block ends with multiple blank lines. For example, |+ or >+.
• Default (clip): If no modifier is specified (| or >), a single trailing newline is kept; additional trailing blank lines are removed.

strip_example: |-
  Line 1
  Line 2

# Result: "Line 1\nLine 2"

keep_example: |+
  Line A
  Line B


# Result: "Line A\nLine B\n\n\n"

clip_example: |
  Line X
  Line Y

# Result: "Line X\nLine Y\n" (assuming Line Y has a newline after it)

Indentation

The indentation of the block scalar’s content determines how much leading whitespace is stripped from each line. The parser detects the minimum indentation level of the content lines and removes that amount of leading space. If a line is less indented than the first content line, it signals the end of the scalar (unless it’s an empty line which might be preserved depending on the style).

Block scalars are essential for cleanly embedding larger pieces of text within YAML documents, making them highly readable and maintainable.