« Hugo’s intersect Function ⛅
  
Hugo’s data Directory »

YAML's Folded Block Scalars: A Way to Avoid Quoting Most Strings
Updated  2022-September-16

Page contents

News

2022-May-19  Published this evolving⁠[1] article.

Prerequisites

This article assumes you know the basics about YAML, including the following.

  • In a YAML serialization, whitespace matters and tabs are not allowed.[2]

  • The elementary particles of YAML are called scalars. A YAML scalar is also known as an atom and is usually a boolean, a number, or a string.

For an overview of YAML, see Infinite Ink’s YAML Includes Atoms, Maps, and Lists.

 

Notation

In this article, a leading or trailing space in a YAML line is represented with a teal BULLET character. For example:

this line begins with 0 spaces
this line begins with 1 space
••this line begins with 2 spaces
•••this line begins with 3 spaces

this line ends with 0 spaces
this line ends with 1 space
this line ends with 2 spaces••
this line ends with 3 spaces•••

this line both begins and ends with 1 space

Flow scalars

The front matter of the source of this article includes this line:

title: "YAML's Folded Block Scalars: A Way to Avoid Quoting Most Strings"

The value of this YAML key-⁠value pair is this:

"YAML's Folded Block Scalars: A Way to Avoid Quoting Most Strings"

This is a double-⁠quoted single-⁠line flow scalar.

 

The value of this title key must be quoted because it contains a colon followed by a space (:), which is a character sequence that can have a special meaning in YAML.⁠[3]

 

To learn about YAML flow scalars, see yaml.org/spec/1.2.2/#73-flow-scalar-styles.

 

Block scalars

The following three lines are an equivalent way to specify this article’s title.

title: >-
••YAML's Folded Block Scalars:
••A Way to Avoid Quoting Most Strings

 

The value of this YAML key-⁠value pair is the following folded block scalar.

>-
••YAML's Folded Block Scalars:
••A Way to Avoid Quoting Most Strings

 

The second and third lines contain the scalar’s content. The first line is the block scalar header and contains the following indicators.

IndicatorMeaning

>

block scalar style is folded

-

chomping method is strip

 

💡
If a block scalar’s content contains an ASCII quotation mark (' or "),⁠[4] it will not have any special meaning and will be interpreted as a literal quotation mark.

 

To learn about block scalars, see yaml.org/spec/1.2.2/#81-block-scalar-styles.

 

Switching from flow to block scalars on Infinite Ink

One of the things I like about YAML is that most strings do not need to be quoted. But, if a string is a flow scalar and it…

  1. looks like a number or a boolean,

  2. or contains a special character⁠[3] or a special character sequence (for example : or #),

…it must be quoted. You can avoid quoting a string by specifying it using a block scalar. Because of this, I’m in the midst of converting most of Infinite Ink’s quoted flow scalars to block scalars. For example, in Infinite Ink’s config.yaml, I changed this:

cacheDir: 'C:\Hugo_cache_infiniteink'

to this:

cacheDir: >-
••C:\Hugo_cache_infiniteink

This is one of the YAML examples discussed on Infinite Ink’s YAML Includes Atoms, Maps, and Lists (featuring the string ¯\_(ツ)_/¯).⁠

 

References

Endnotes


1. Many Infinite Ink articles, including this one, are evergreen and regularly updated.
2. Tabs are allowed in some parts of a YAML serialization, but it’s safest to not use tabs at all.
3. The following characters can have a special meaning in YAML: : - { } [ ] ! # | > & % @ \ ' "
4. The ASCII quotation marks ' and " are also known as a dumb, neutral, vertical, straight, or typewriter quotation marks.

Comments 📝 🤔 👎 👍

Your comment might immediately improve this page or help me to (eventually) improve this page.

To post or view comments, click this sentence.