“Fun” learning YAML properly?

Okay. So. I have to learn ANSI-Bell for $ork. Meh. But okay.

Pre-existing “fun”

Playbooks are written in YAML. I hate YAML and have always used yaml2jsn to convert it to JSON (if possible) when I had to touch it in the past, as somehow a subset¹² of JSON is a valid subset of YAML accepted² by YAML parsers.

① you’ll have to make sure you don’t emit some codepoints literally, and to format numbers in scientific notation a specific way, but that’s generally a good advice for JSON emitters
② except JSON strings have codepoints outside the Basic Multilingual Plane encoded as two UTF-16 surrogates in \u#### notation whereas YAML parsers require it to be unescaped four-octet UTF-8, which breaks many JSON parsers; I ran into that just this week, in fact, for my RSS to Fediverse gateways…

I personally find YAML unwritable, due to things like GitHub Actions’ example of…

on:
  push:
    branches:
      - main

… does not convert to…

{
  "on": {
    "push": {
      "branches": [
        "main"
      ]
    }
  }
}

… but to:

{
  "1": {
    "push": {
      "branches": [
        "main"
      ]
    }
  }
}

(GitHub accepts both syntacēs in workflow files in JSON.)

But let’s go back to the “self-explaining, obvious” YAML:

on:
  push:
    branches:
      - main

So, we’ve already established that “on” is 1 and that something like country: no isn’t Norway but 0 (and real existing people have fallen into this, yet there are strong recommendations to not quote strings in YAML documents like ANSI-Bell playbooks, and somehow nobody even documents how strings are to be escaped and when they need to be escaped).

But, riddle me this:

push:
<2 spaces>branches:

But:

branches:
<2 spaces><hyphen-minus and space>main

But:

options:
<no space><hyphen-minus and space>Ubuntu
<no space><hyphen-minus and space>macOS

(All examples from here.)

I find this totally obvious and self-explanatory and consistent, and I totally know when to use two spaces, or dash-plus-space, or both.</sarcasm>

But there is training material!

One of the books I’ve been provided (actual published training material with an ISBN each) just hand-waves it away, the other says:

The target section looks like the following code snippet:

  - hosts: webservers
    user: root

[…] As per the YAML syntax, the line must start with a dash. […]

So, basically, the hosts: line must start with a dashhyphen-minus? I think not.

The “Hands-on interactive lab and helpful resources” in the Red Hat “YAML essentials for Ansible” “learning path” is similarly deficient in even fundamentally basic explanation. 0/10, won’t recommend.

Fun with training material, continued

The hand-waving book links to http://www.yaml.org/start.html, so let’s read…

a getting started guide for YAML

… in my favourite webbrowser lynx:

                                                   Page not found · GitHub Pages
 
 
   File not found
 
   The  site  configured  at  this  address does not contain the requested
   file.
 
   If  this is your site, make sure that the filename case matches the URL
   as well as any file permissions.
   For root URLs (like http://example.com/) you must provide an index.html
   file.
 
   [1]Read  the full documentation for more information about using GitHub
   Pages.
   [2]GitHub Status — [3]@githubstatus
 
 
 
 
 
 
 
Edit this document's URL: https://yaml.org/start.html

… oooookay?

But surely yaml.org has more material? *looks* … well, it has links to the specs and implementations. All very useful, but not right now for a hopefully structured introduction that explains the hows and ideally also the whys.

Let’s follow the *New* link in which they announce the 1.2.2 spec… a blogpost. Okay. It has a title bar (brown background in Firefox) with a promising link:

   Y
 
     *
     * [2]Blog
     * [3]Docs

Let’s follow #3 to “Docs”!

←←←                                                                      Twitter
   [1]Skip to main content
 
   Y
 
     *
     * [2]Blog
     * [3]Docs
 
     *
     *
 
   [4]YAML Glossary
 
   [5]YAML Cheat Sheet
 
   (BUTTON) Menu
 
YAML Documentation
     __________________________________________________________________
 
   YAML documentation is on the way!
 
#content

This 80×24 screenshot is literally the entirety of the official #YAML documentation.

Well, colour me impressed.

Wait, no.

Fuck that shit.

Wait. This is for $dayjob. $customer also edits playbooks. I’m sure they’ll be delighted if I run things through yaml2jsn and commit the result as #JSON.

Also, see footnote 2 above.

Fuuuuck I’m SOL.

So. Do I honestly have to wade through the spec to learn this?

(Not that this is new. When I first learnt Python in 2008, I had to look at the C-language source code of the #Python interpreter to figure out things missing from the documentation. Which brings us back full circle to #ansible, the culprit of bringing this entire shitshow to my attention. I’m a programmer, not a DevCloudOp or something.)