ii.com: YAML Includes Atoms, Maps, and Lists (featuring the string ¯\_(ツ)

YAML is a configuration language and data-serialization format that can include atoms, maps and lists.^[2]

Atoms

Atoms are the elementary particles of a YAML serialization. An atom is usually⁠^[3] either…

a boolean (e.g. true or false),
a number (e.g. 6 or 6.283185307),
or a string (e.g. hello world or ¯∖_(ツ)_/¯).

Maps

A map is a key-value pair. Here are a couple example YAML maps:

key1: value1
key2: value2

Lists

Here is an example of a YAML list:

- item1
- item2
- item3

Data objects

These data structures can have names, also known as keys. For example:

name1:
  key1: value1
  key2: value2

name2:
  - item1
  - item2
  - item3

Note that name1 is a key whose value is a couple maps and name2 is a key whose value is a three-item list. Naming a collection is a way to turn it into a block or object (with sub-objects) that can be referenced.

More terminology

An atom is also known as a scalar.

A list is also known as an array, a sequence, a slice, or a vector.

A collection of maps, for example name1, is also known as an associative array, a data object, a dictionary, a dict, a hash table, a hash, a keyed list, a map, a mapping, a named map, a nested map, a record, a struct, or a table.

YAML examples

This article’s YAML front matter

The following is the YAML front matter that is at the top of the source of this article.

---
draft: false

title: 'YAML Includes Atoms, Maps, and Lists (featuring the string ¯\_(ツ)_/¯)'
linkTitle: YAML Includes Atoms, Maps, and Lists

publishDate: 2019-11-10
lastmod: 2022-06-01

tags:
  - content
  - emoji
  - gohugo
  - iusethis
  - n2s
  - tech
---

‼	The value of the `title` key must be surrounded by single ASCII quotation marks⁠^[4] because it is a string that contains a backslash (`\`), which is a character that has a special meaning in YAML. To learn about quoting in YAML, see www.yaml.info/learn/quote.html.

ℹ	To learn about the shruggie emoticon (¯\_(ツ)_/¯), see emojipedia.org/person-shrugging/.

Excerpt 1 of a Hugo config.yaml

Here is an excerpt of the config.yaml that Hugo uses to generate this Infinite Ink website.

cacheDir: 'C:\Hugo_cache_infiniteink'

‼	The above value of the `cacheDir` key must be within single ASCII quotes⁠^[4] because it contains a backslash (`\`).

ℹ	The Hugo default is to put `cacheDir` below `$TMPDIR` but since I can never remember that, I put it in the root of my `C:` drive (which I can remember).

Excerpt 2 of a Hugo config.yaml

Here is another excerpt of Infinite Ink’s config.yaml.

markup:
 asciidocExt:
  preserveTOC: true
  workingFolderCurrent: false  # default is false
  attributes:
   toc: macro
   hide-uri-scheme: true@  # trailing @ means ok to override
   sectlinks: true
   octothorpe: &#35;  # hash
   colon: &#58;
   rsolidus: &#92;  # backslash
   underscore: &#95;

To learn about this config.yaml excerpt, see section 2 of Infinite Ink’s Intertwingling AsciiDoc and Hugo⁠.

YAML syntax tips

In general, you do not need to use quotation marks around YAML strings, but quoting a string might be needed if it…

includes any of the following 14 characters, each of which can have a special meaning in YAML: : - { } [ ] ! # | > & % @ \

Quoting a string is needed if it…

looks like a number (decimal, hexadecimal, exponential E or e notation, etc.)
or is one of YAML’s reserved boolean words (true, false, yes, no, on, off).⁠^[5]

For more about quoting in YAML, see www.yaml.info/learn/quote.html and www.ii.com/yaml-block-scalars/.

‼	In YAML: Indentation matters. Tabs are not allowed.^[6] A line or fragment of a line that begins with an unquoted hash (`#`) is a comment and is ignored.

1. Many Infinite Ink articles, including this one, are evergreen and regularly updated.

2. I like to think that the AML part of YAML stands for Atoms, Maps, and Lists, but this is not what the YAML acronym really stands for.

3. In addition to boolean, numeric, and string atoms, YAML supports the null atom, which means undefined. All these types of atoms are also known as scalars.

4. ASCII quotation marks are also known as a dumb, neutral, vertical, straight, or typewriter quotation marks.

5. I learned about the off problem the hard way. Here is a story about someone who learned about the no problem the hard way: The Norway Problem.

6. Tabs are allowed in some parts of a YAML serialization, but it’s safest to not use tabs at all.

YAML Includes Atoms, Maps, and Lists (featuring the string ¯\_(ツ)_/¯)
Updated 2022-June-1

News

What is YAML?