docs/modules/yaml/pages/yaml-primer.adoc

   1 = YAML primer
   2
   3 https://yaml.org/[YAML] is a human-readable data serialization format,
   4 like https://www.json.org/json-en.html[JSON].
   5
   6 In fact, YAML is a superset of JSON: you can also write a barectf
   7 configuration in JSON.
   8
   9 YAML has many features which are outside the scope of the barectf
  10 documentation. This page is a simple introduction to the
  11 https://yaml.org/spec/1.2/spec.html[YAML{nbsp}1.2] language.
  12
  13 YAML uses indentation for scoping, much like Python.
  14
  15 The root of a YAML document is a <<mapping,mapping>>.
  16
  17 [[mapping]]
  18 == Mapping
  19
  20 A YAML mapping is an unordered list of key-value pairs.
  21
  22 Within a mapping, `:` delimits the value from the key.
  23
  24 .A YAML mapping with four entries.
  25 ====
  26 [source,yaml]
  27 ----
  28 Castonguay: Huguette Delisle
  29 Létourneau: Gaétan Delisle
  30 Robitaille: Serge Paquette
  31 Gonthier-Hyndman: Micheline Paquette
  32 ----
  33 ====
  34
  35 .A YAML mapping with a nested mapping.
  36 ====
  37 [source,yaml]
  38 ----
  39 title: C'est comme ça que je t'aime
  40 country: Canada
  41 language: French
  42 release-date: 6 March 2020
  43 cast:
  44   Castonguay: Huguette Delisle
  45   Létourneau: Gaétan Delisle
  46   Robitaille: Serge Paquette
  47   Gonthier-Hyndman: Micheline Paquette
  48 ----
  49 ====
  50
  51 You can also write a mapping on a single line, delimiting key-value
  52 pairs with `,`, beginning with `{` and ending with `}`:
  53
  54 .A single-line YAML mapping with four entries.
  55 ====
  56 [source,yaml]
  57 ----
  58 {Marilyn: Huguette, François: Gaétan, Karine: Micheline, Patrice: Serge}
  59 ----
  60 ====
  61
  62 .A YAML mapping with a nested single-line mapping.
  63 ====
  64 [source,yaml]
  65 ----
  66 title: C'est comme ça que je t'aime
  67 country: Canada
  68 language: French
  69 release-date: 6 March 2020
  70 cast: {Marilyn: Huguette, François: Gaétan, Karine: Micheline, Patrice: Serge}
  71 ----
  72 ====
  73
  74 Although the keys of a mapping can be any value, barectf only uses
  75 strings.
  76
  77 Each key of a given mapping must be unique.
  78
  79 [[sequence]]
  80 == Sequence
  81
  82 A YAML sequence is an ordered list of values.
  83
  84 Each item begins with `-`.
  85
  86 .A YAML sequence with four items.
  87 ====
  88 [source,yaml]
  89 ----
  90 - Corvette Express
  91 - Québec Deli
  92 - Boulangerie Fanfare
  93 - Marché Méli-Mélo
  94 ----
  95 ====
  96
  97 .A YAML sequence. The third item is a <<mapping,mapping>>.
  98 ====
  99 [source,yaml]
 100 ----
 101 - Le poète des temps gris
 102 - Aidez-moi
 103 - name: Granby
 104   album: Toutte est temporaire
 105   year: 2014
 106 - La patente
 107 ----
 108 ====
 109
 110 You can also write a sequence on a single line, delimiting items
 111 with a comma (`,`), beginning with `[` and ending with `]`:
 112
 113 .A single-line YAML sequence with four items.
 114 ====
 115 [source,yaml]
 116 ----
 117 [Corvette Express, Québec Deli, Boulangerie Fanfare, Marché Méli-Mélo]
 118 ----
 119 ====
 120
 121 .A single-line YAML sequence. The third item is a single-line <<mapping,mapping>>.
 122 ====
 123 [source,yaml]
 124 ----
 125 [Le poète des temps gris, Aidez-moi, {name: Granby, year: 2014}, La patente]
 126 ----
 127 ====
 128
 129 [[scalar]]
 130 == Null, boolean, integer, and string values
 131
 132 The basic YAML scalar values which are of interest to write a barectf
 133 configuration are:
 134
 135 Null::
 136     `null`, `Null`, `NULL`, `+~+`, or nothing.
 137 +
 138 In a barectf YAML configuration, a null value always means to use the
 139 default value.
 140
 141 Boolean::
 142     `true`, `True`, `TRUE`, `false`, `False`, or `FALSE`.
 143
 144 Integer::
 145     Anything matching:
 146 +
 147 ** `+[-+]?[0-9]++` (decimal)
 148 ** `+0o[0-7]++` (octal)
 149 ** `+0x[0-9a-fA-F]++` (hexadecimal)
 150
 151 +
 152 Examples: `23`, `0x45fc1`, `-17`, `0o644`.
 153
 154 String::
 155     Double-quoted or single-quoted sequence of characters, or unquoted
 156     sequence of characters when it doesn't match the form of another
 157     value.
 158 +
 159 Examples:
 160 +
 161 ** `+"Whoever is happy will make others happy too."+`
 162 ** `+'Life is either a daring adventure or nothing at all.'+`
 163 ** `+Only a life lived for others is a life worthwhile.+`
 164
 165 .A YAML mapping with null, boolean, integer, and string values.
 166 ====
 167 [source,yaml]
 168 ----
 169 'null': null
 170 booleans: [true, false]
 171 integers: [23, 0x45fc1, -17, 0o644]
 172 strings:
 173   - "Whoever is happy will make others happy too."
 174   - 'Life is either a daring adventure or nothing at all.'
 175   - Only a life lived for others is a life worthwhile
 176 ----
 177 ====
 178
 179 == Comment
 180
 181 A YAML comment starts with `+#+` and ends at the end of the line.
 182
 183 .A YAML mapping with comments.
 184 ====
 185 [source,yaml]
 186 ----
 187 title: C'est comme ça que je t'aime
 188
 189 # This is actually a Québec production.
 190 country: Canada
 191
 192 language: French
 193 release-date: 6 March 2020
 194 cast:
 195   Castonguay: Huguette Delisle
 196   Létourneau: Gaétan Delisle # also cowrote Série noire
 197   Robitaille: Serge Paquette
 198   Gonthier-Hyndman: Micheline Paquette
 199 ----
 200 ====
 201
 202 [[tag]]
 203 == Tags
 204
 205 Any YAML value has a tag to indicate its meaning.
 206
 207 If you don't write any tag, it's implicit from the value's form.
 208
 209 .A YAML value with a tag.
 210 ====
 211 The second `true` value below is actually a string instead of a boolean
 212 because it has an explicit YAML string tag:
 213
 214 [source,yaml]
 215 ----
 216 a boolean: true
 217 actually a string: !<tag:yaml.org,2002:str> true
 218 ----
 219 ====
 220
 221 In the example above, `tag:yaml.org,2002:str` is the standard YAML tag
 222 for string values.
 223
 224 barectf requires that the configuration file's root <<mapping,mapping>>
 225 be tagged with `tag:barectf.org,2020/3/config` to identify the whole
 226 mapping as a barectf configuration object.
 227
 228 You can tag the root mapping by tagging the YAML document itself:
 229
 230 .A tagged YAML document.
 231 ====
 232 [source,yaml]
 233 ----
 234 --- !<tag:barectf.org,2020/3/config>
 235 trace:
 236   type:
 237     # ...
 238 ----
 239 ====