“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.)