Two Types of Formats for Strings
There are two types of formats that YAML supports for scalar strings. (Scalars are what YAML calls basic values like numbers or strings, as opposed to complex types like arrays or objects.)
- Flow scalar formats are designed for robust simplicity but do have a limited escaping and line-break support. They are designed to ignore indentations.
- Block scalar formats provide more control over how they are interpreted by increasing sensitivity rules regarding indentations and escaping. These are designed to answer for cases whenever scalar flow formats become cumbersome or insufficient.
Although they are parsed by different rules, they all express strings, allowing authors to choose the option that expresses best what they need the string to be.
Flow Scalars
Single-quoted
example: 'A simple string.'
A simple string.
example: 'Several lines of text,\n ··containing ''single quotes'' and "double quotes". ··Escapes (like \n) don''t do anything.\n ··\n ··Newlines can be added by leaving a blank line.\n ····Leading whitespace on lines is ignored.'\n
Several lines of text, containing 'single quotes' and "double quotes". Escapes (like \n) don't do anything.\n
Newlines can be added by leaving a blank line. Leading whitespace on lines is ignored.Double-quoted
example: "A simple string."
A simple string.
example: "Several lines of text,\n ··containing \"double quotes\" and 'single quotes'. ··Escapes (like \\n) work.\nIn addition,\n ··newlines can be esc\\n ··aped to prevent them from being converted to a space.\n ··\n ··Newlines can also be added by leaving a blank line.\n ····Leading whitespace on lines is ignored."\n
Several lines of text, containing "double quotes" and 'single quotes'. Escapes (like \n) work.\n In addition, newlines can be escaped to prevent them from being converted to a space.\n Newlines can also be added by leaving a blank line. Leading whitespace on lines is ignored.\n
Plain
example: A simple string.A simple string.
example: Several lines of text,\n ··with some "quotes" of various 'types'.\n ··Escapes (like \n) don't do anything.\n ··\n ··Newlines can be added by leaving a blank line.\n ····Additional leading whitespace is ignored.\n
Several lines of text, with some "quotes" of various 'types'. Escapes (like \n) don't do anything.\n
Newlines can be added by leaving a blank line. Additional leading whitespace is ignored.⚠️ Plain flow scalars (unquoted strings) have several pitfalls:
- Plain flow scalars are picky about the
:and#characters. They can be in the string, but:cannot appear before a space or newline, and#cannot appear after a space or newline; doing this will cause a syntax error. - Parsers which support YAML 1.1 may interpret the strings `y`, `n`, `yes`, `no`, `on`, and `off` (case-insensitive) as boolean values rather than strings.
- Leading and trailing whitespace will be removed.
If your strings are affected by any of these caveats you should use one of the quoted styles instead.
Block Scalars
A block scalar header has three parts:
Block Style Indicator: The block style indicates
how newlines inside the block should behave.
If you would like them to be kept as newlines, use the literal
style, indicated by a pipe (|).
If instead you want them to be replaced by spaces, use the folded
style, indicated by a right angle bracket (>).
(To get a newline using the folded style, leave a blank line by putting two newlines in.
Lines with extra indentation are also not folded.)
Block Chomping Indicator:
The chomping indicator controls what should happen with newlines
at the end of the string.
The default, clip, puts a single newline at the end of the string.
To remove all newlines, strip them by putting a minus sign (-)
after the style indicator.
Both clip and strip ignore how many newlines are actually at the end of the block;
to keep them all put a plus sign (+) after the style indicator.
Indentation Indicator: Ordinarily, the number of spaces you're using to indent a block will be automatically guessed from its first line. You may need a block indentation indicator if the first line of the block starts with extra spaces. In this case, simply put the number of spaces used for indentation (between 1 and 9) at the end of the header.
Demo
example: |>-+\n ··Several lines of text,\n ··with some "quotes" of various 'types',\n ··and also a blank line:\n ··\n ··and some text with\n ··extra indentation\n ··on the next line,\n ··plus another line at the end.\n ··\n ··\n
Several lines of text,\n with some "quotes" of various 'types',\n and also a blank line:\n \n and some text with\n extra indentation\n on the next line,\n plus another line at the end.\n \n \n