In YAML, I have a string that's very long. I want to keep this within the 80-column (or so) view of my editor, so I'd like to break the string. What's the syntax for this?
In other words, I have this:
Key: 'this is my very very very very very very long string'
and I'd like to have this (or something to this effect):
Key: 'this is my very very very ' +
'long string'
I'd like to use quotes as above, so I don't need to escape anything within the string.
Best Answer
There are
56NINE (or 63*, depending how you count) different ways to write multi-line strings in YAML.TL;DR
Use
>
most of the time: interior line breaks are stripped out, although you get one at the end:Use
|
if you want those linebreaks to be preserved as\n
(for instance, embedded markdown with paragraphs).Use
>-
or|-
instead if you don't want a linebreak appended at the end.Use
"..."
if you need to split lines in the middle of words or want to literally type linebreaks as\n
:YAML is crazy.
Block scalar styles (
>
,|
)These allow characters such as
\
and"
without escaping, and add a new line (\n
) to the end of your string.>
Folded style removes single newlines within the string (but adds one at the end, and converts double newlines to singles):→
this is my very very very long string\n
Extra leading space is retained and causes extra newlines. See note below.
Advice: Use this. Usually this is what you want.
|
Literal style turns every newline within the string into a literal newline, and adds one at the end:→
this is my very very very\nlong string\n
Here's the official definition from the YAML Spec 1.2
Advice: Use this for inserting formatted text (especially Markdown) as a value.
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:>
,|
: "clip": keep the line feed, remove the trailing blank lines.>-
,|-
: "strip": remove the line feed, remove the trailing blank lines.>+
,|+
: "keep": keep the line feed, keep trailing blank lines."Flow" scalar styles (
,
"
,'
)These have limited escaping, and construct a single-line string with no new line characters. They can begin on the same line as the key, or with additional newlines first, which are stripped. Doubled newline characters become one newline.
plain style (no escaping, no
#
or:
combinations, first character can't be"
,'
or many other punctuation characters ):Advice: Avoid. May look convenient, but you're liable to shoot yourself in the foot by accidentally using forbidden punctuation and triggering a syntax error.
double-quoted style (
\
and"
must be escaped by\
, newlines can be inserted with a literal\n
sequence, lines can be concatenated without spaces with trailing\
):→
"this is my very very \"very\" loooong string.\n\nLove, YAML."
Advice: Use in very specific situations. This is the only way you can break a very long token (like a URL) across lines without adding spaces. And maybe adding newlines mid-line is conceivably useful.
single-quoted style (literal
'
must be doubled, no special characters, possibly useful for expressing strings starting with double quotes):→
"this is my very very \"very\" long string, isn't it."
Advice: Avoid. Very few benefits, mostly inconvenience.
Block styles with indentation indicators
Just in case the above isn't enough for you, you can add a "block indentation indicator" (after your block chomping indicator, if you have one):
Note: Leading spaces in Folded style (
>
)If you insert extra spaces at the start of not-the-first lines in Folded style, they will be kept, with a bonus newline. (This doesn't happen with flow styles.) Section 6.5:
→
["my long\n string\n \nmany spaces above\n","my long string\nmany spaces above"]
Summary
In this table,
_
meansspace character
.\n
means "newline character" (\n
in JavaScript) except under "Other features". "Leading space" applies after the first line (which establishes the indent)>
|
"
'
>-
>+
|-
|+
\n
\
#
or:
in valueline as key
Examples
Note the trailing spaces on the line before "spaces."
*
2 block styles, each with 2 possible block chomping indicators (or none), and with 9 possible indentation indicators (or none), 1 plain style and 2 quoted styles: 2 x (2 + 1) x (9 + 1) + 1 + 2 = 63Some of this information has also been summarised here.