syntax - How do I break a string in YAML over multiple lines?

ID : 440

viewed : 100

Tags : stringsyntaxyamlnewlinestring

Top 5 Answer for syntax - How do I break a string in YAML over multiple lines?

vote vote

94

There are 5 6 NINE (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:

      key: >     Your long     string here. 
  • Use | if you want those linebreaks to be preserved as \n (for instance, embedded markdown with paragraphs).

      key: |     ### Heading      * Bullet     * Points 
  • 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:

      key: "Antidisestab\    lishmentarianism.\n\nGet on it." 
  • 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):

Key: >   this is my very very very   long string 

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:

Key: |   this is my very very very    long string 

this is my very very very\nlong string\n

Here's the official definition from the YAML Spec 1.2

Scalar content can be written in block notation, using a literal style (indicated by “|”) where all line breaks are significant. Alternatively, they can be written with the folded style (denoted by “>”) where each line break is folded to a space unless it ends an empty or a more-indented line.

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 ):

Key: this is my very very very    long string 

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 \):

Key: "this is my very very \"very\" loooo\   ng string.\n\nLove, YAML." 

"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):

Key: 'this is my very very "very"   long string, isn''t it.' 

"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):

- >8         My long string         starts over here - |+1  This one  starts here 

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:

In addition, folding does not apply to line breaks surrounding text lines that contain leading white space. Note that such a more-indented line may consist only of such leading white space.

- >     my long       string                          many spaces above - my long       string                          many spaces above      

["my long\n string\n \nmany spaces above\n","my long string\nmany spaces above"]

Summary

In this table, _ means space character. \n means "newline character" (\n in JavaScript) except under "Other features". "Leading space" applies after the first line (which establishes the indent)

> | " ' >- >+ |- |+
Spaces/newlines converted as:
Trailing space → _ _ _ _ _ _
Leading space → \n_ \n_ \n_ \n_ \n_ \n_
Single newline → _ \n _ _ _ _ _ \n \n
Double newline → \n \n\n \n \n \n \n \n \n\n \n\n
Final newline → \n \n \n \n
Final double newline → \n\n \n\n
How to create a literal:
Single quote ' ' ' ' '' ' ' ' '
Double quote " " " \" " " " " "
Backslash \ \ \ \\ \ \ \ \ \
Other features
In-line newlines with \n 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Spaceless newlines with \ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
# or : in value 🚫
Can start on same
line as key
🚫 🚫 🚫 🚫 🚫 🚫

Examples

Note the trailing spaces on the line before "spaces."

- >   very "long"   'string' with    paragraph gap, \n and           spaces. - |    very "long"   'string' with    paragraph gap, \n and           spaces. - very "long"   'string' with    paragraph gap, \n and           spaces. - "very \"long\"   'string' with    paragraph gap, \n and           s\   p\   a\   c\   e\   s." - 'very "long"   ''string'' with    paragraph gap, \n and           spaces.' - >-    very "long"   'string' with    paragraph gap, \n and           spaces.  [   "very \"long\" 'string' with\nparagraph gap, \\n and         spaces.\n",    "very \"long\"\n'string' with\n\nparagraph gap, \\n and        \nspaces.\n",    "very \"long\" 'string' with\nparagraph gap, \\n and spaces.",    "very \"long\" 'string' with\nparagraph gap, \n and spaces.",    "very \"long\" 'string' with\nparagraph gap, \\n and spaces.",    "very \"long\" 'string' with\nparagraph gap, \\n and         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 = 63

Some of this information has also been summarised here.

vote vote

85

Using yaml folded style. The indention in each line will be ignored. A line break will be inserted at the end.

Key: >   This is a very long sentence   that spans several lines in the YAML   but which will be rendered as a string   with only a single carriage return appended to the end. 

http://symfony.com/doc/current/components/yaml/yaml_format.html

You can use the "block chomping indicator" to eliminate the trailing line break, as follows:

Key: >-   This is a very long sentence   that spans several lines in the YAML   but which will be rendered as a string   with NO carriage returns. 

In either case, each line break is replaced by a space.

There are other control tools available as well (for controlling indentation for example).

See https://yaml-multiline.info/

vote vote

78

To preserve newlines use |, for example:

|   This is a very long sentence   that spans several lines in the YAML   but which will be rendered as a string   with newlines preserved. 

is translated to "This is a very long sentence‌\n that spans several lines in the YAML‌\n but which will be rendered as a string‌\n with newlines preserved.\n"

vote vote

69

1. Block Notation(plain, flow-style, scalar): Newlines become spaces and extra newlines after the block are removed

--- # Note: It has 1 new line after the string content:     Arbitrary free text     over multiple lines stopping     after indentation changes...  ... 

Equivalent JSON

{  "content": "Arbitrary free text over multiple lines stopping after indentation changes..." } 

2. Literal Block Scalar: A Literal Block Scalar | will include the newlines and any trailing spaces. but removes extra

newlines after the block.

--- # After string we have 2 spaces and 2 new lines content1: |  Arbitrary free text  over "multiple lines" stopping  after indentation changes...     ... 

Equivalent JSON

{  "content1": "Arbitrary free text\nover \"multiple lines\" stopping\nafter indentation changes...  \n" } 

3. + indicator with Literal Block Scalar: keep extra newlines after block

--- # After string we have 2 new lines plain: |+  This unquoted scalar  spans many lines.   ... 

Equivalent JSON

{  "plain": "This unquoted scalar\nspans many lines.\n\n\n" } 

4. – indicator with Literal Block Scalar: means that the newline at the end of the string is removed.

--- # After string we have 2 new lines plain: |-  This unquoted scalar  spans many lines.   ... 

Equivalent JSON

{  "plain": "This unquoted scalar\nspans many lines." } 

5. Folded Block Scalar(>):

will fold newlines to spaces and but removes extra newlines after the block.

--- folded_newlines: >  this is really a  single line of text  despite appearances   ... 

Equivalent JSON

{  "fold_newlines": "this is really a single line of text despite appearances\n" } 

for more you can visit my Blog

vote vote

57

To concatenate long lines without whitespace, use double quotes and escape the newlines with backslashes:

key: "Loremipsumdolorsitamet,consecteturadipiscingelit,seddoeiusmodtemp\   orincididuntutlaboreetdoloremagnaaliqua." 

(Thanks @Tobia)

Top 3 video Explaining syntax - How do I break a string in YAML over multiple lines?

Related QUESTION?