YAML Files – Formatting Long Strings

oussamaComments are off for this post.

Keep the Yaml files in your project tidy is useful. Not only it improves code readability but also helps avoiding misunderstanding and bugs. Luckily there are many tools available that helps with “linting” and formatting yaml file, I introduced two of those tools in an earlier blog post titled: YAML Files – Linting and Formatting. In this blog post I will cover the issue of handling long strings thoroughly. So let us start

Formatting Long String

Generally speaking, YAML linters, and other scripts linters suggest a maximum of 80 characters per line. that means linters will report a warning or an error in case our strings were longer than 80 characters strings, and they often are.

Let’s say we have the following line in the yaml file:

Key: 'this is my very very very very very very long string'

How do we break it into several lines. Would something line the following works?

Key: 'this is my very very very ' +
     'long string'

The answer is: no that will not work.

Actually, there is a very nice Stackoverflow.com Q/A article that covers this topic. In this blog post I am using parts of the best answer by Steve Bennett in that article, for my safe-keeping more than anything.
There are several ways to write a string over multiple lines, here are methods I care about:

Folded style >:

This style removes single newlines within the string (but adds one at the end, and converts double newlines to singles). It allow characters such as \ and " without escaping, and add a new line (\n) to the end of the string. Extra leading space is retained and causes extra newlines. Example:

Key: >
  this is my very very very
  long string

and the result will be:

this is my very very very long string\n

Literal Style |:

This style turns every newline within the string into a literal newline and adds one at the end. Example:

Key: |
  this is my very very very 
  long string

the result will be:

this is my very very very\nlong string\n

More on this topic in the Literal style in the yaml documentation.

Folded and Literal Block styles with block chomping indicator (>-, |-, >+, |+)

You can control the handling of the final new line in the string, and any trailing blank lines (\n\n) by adding a block chomping indicator character:

use >- or |- to “strip” the line feed and remove the trailing blank lines.

use >+ or |+ to “keep” the line feed and the trailing blank lines.

Example:

Key: >-
  this is my very very very
  long string

The result will be:

this is my very very very long string

Note the missing newline at the end.

Flow styles ( , ", ')

Is another way to spread a string over several lines but it will not be covered here. Please refer to the stackoverflow answer referenced earlier, or to the original yaml documentation for details about this method. However for the sake of completion and because I often find myself needed this special case, I am going to describe it here.

If you want to pass a long string, such as a cryptographic token or a a certificate that is basically a very long string without spaces, line feeds or newlines, all of the options mentioned thus far won’t help. the flow styles will:

Key: 
"W3R7sftuza5ucgWOGfAZZMfZ5HQ7!\
XVURgdFyPRi8UKgYeWsgXDZgIYSTPH\
HPYN24wvznZeymfXrw41gHUx32d2eB\
=!H63kQZ=avAwb/GXU3pJ8IYbkCC8c\
KEkEy7uZs4yuLzcWB1mq3aaYxXM!mW\
Y5pwyLydtRdAqCqbrThUKz=2KVZjBB\
ahmg3ZXe6FwVHLTKkE29p!BCw2cpEk\
B-i6A2twYf8DH4cnZQYeYuzK2YPwD3\
JBZDR6fG6JTjZ"

The result will be:

Key: W3R7sftuza5ucgWOGfAZZMfZ5HQ7!XVURgdFyPRi8UKgYeWsgXDZgIYSTPHHPYN24wvznZeymfXrw41gHUx32d2eB=!H63kQZ=avAwb/GXU3pJ8IYbkCC8cKEkEy7uZs4yuLzcWB1mq3aaYxXM!mWY5pwyLydtRdAqCqbrThUKz=2KVZjBBahmg3ZXe6FwVHLTKkE29p!BCw2cpEkB-i6A2twYf8DH4cnZQYeYuzK2YPwD3JBZDR6fG6JTjZ

What about Linting?

In this article I discussed several ways for formatting strings in yaml files for the purposes of keeping files in the repository clean of long strings. But to deal with other formatting issues and to avoid introducing accidental mistakes that might waste precious development time, it is recommended to use a linter. I discuss two tools for linting YAML files in my other blog post: YAML Files – Linting and Formatting.