Breaking YAML Strings Over Multiple Lines

1. Overview

In this article, we'll learn about breaking YAML strings over multiple lines.

In order to parse and test our YAML files, we'll make use of the SnakeYAML library.

2. Multi-Line Strings

Before we begin, let's create a method to simply read a YAML key from a file into a String:

String parseYamlKey(String fileName, String key) {
    InputStream inputStream = this.getClass()
      .getClassLoader()
      .getResourceAsStream(fileName);
    Map<String, String> parsed = yaml.load(inputStream);
    return parsed.get(key);
}

In the next subsections, we'll look over a few strategies for splitting strings over multiple lines.

We'll also learn how YAML handles leading and ending line breaks represented by empty lines at the beginning and end of a block.

3. Literal Style

The literal operator is represented by the pipe (“|”) symbol. It keeps our line breaks but reduces empty lines at the end of the string down to a single line break.

Let's take a look at the YAML file literal.yaml:

key: |
  Line1
  Line2
  Line3

We can see that our line breaks are preserved:

String key = parseYamlKey("literal.yaml", "key");
assertEquals("Line1\nLine2\nLine3", key);

Next, let's take a look at literal2.yaml, which has some leading and ending line breaks:

key: |


  Line1

  Line2

  Line3


...

We can see that every line break is present except for ending line breaks, which are reduced to one:

String key = parseYamlKey("literal2.yaml", "key");
assertEquals("\n\nLine1\n\nLine2\n\nLine3\n", key);

Next, we'll talk about block chomping and how it gives us more control over starting and ending line breaks.

We can change the default behavior by using two chomping methods: keep and strip.

3.1. Keep

Keep is represented by “+” as we can see in literal_keep.yaml:

key: |+
  Line1
  Line2
  Line3


...

By overriding the default behavior, we can see that every ending empty line is kept:

String key = parseYamlKey("literal_keep.yaml", "key");
assertEquals("Line1\nLine2\nLine3\n\n", key);

3.2. Strip

The strip is represented by “-” as we can see in literal_strip.yaml:

key: |-
  Line1
  Line2
  Line3

...

As we might've expected, this results in removing every ending empty line:

String key = parseYamlKey("literal_strip.yaml", "key");
assertEquals("Line1\nLine2\nLine3", key);

4. Folded Style

The folded operator is represented by “>” as we can see in folded.yaml:

key: >
  Line1
  Line2
  Line3

By default, line breaks are replaced by space characters for consecutive non-empty lines:

String key = parseYamlKey("folded.yaml", "key");
assertEquals("Line1 Line2 Line3", key);

Let's look at a similar file, folded2.yaml, which has a few ending empty lines:

key: >
  Line1
  Line2


  Line3


...

We can see that empty lines are preserved, but ending line breaks are also reduced to one:

String key = parseYamlKey("folded2.yaml", "key");
assertEquals("Line1 Line2\n\nLine3\n", key);

We should keep in mind that block chomping affects the folding style in the same way it affects the literal style.

5. Quoting

Let's have a quick look at splitting strings with the help of double and single quotes.

5.1. Double Quotes

With double quotes, we can easily create multi-line strings by using “\n“:

key: "Line1\nLine2\nLine3"

String key = parseYamlKey("plain_double_quotes.yaml", "key");
assertEquals("Line1\nLine2\nLine3", key);

5.2. Single Quotes

On the other hand, single-quoting treats “\n” as part of the string, so the only way to insert a line break is by using an empty line:

key: 'Line1\nLine2

  Line3'

String key = parseYamlKey("plain_single_quotes.yaml", "key");
assertEquals("Line1\\nLine2\nLine3", key);

6. Conclusion

In this quick tutorial, we've looked over multiple ways of breaking YAML strings over multiple lines through quick and practical examples.

As always, the code is available over on GitHub.