Skip to content

YAML Variables

YAML itself isn't a functional programming language, but advanced users are probably aware of YAML's anchors, aliases and the merge key.

The merge key is YAML's one functional thing, and it's actually not even part of the YAML 1.2 spec External link . However, people find it useful and many YAML implementations (including YS) support it.

The merge key (<<) is a special key that allows you to merge the contents of one mapping into another.

Today we'll explore the merge key a bit and show how variables can make it nicer to use.

The Merge Key🔗

Consider the following YAML file:

# shoes.yaml
- &defaults
  size: 10
  color: blue

- name: sneaker
  <<: *defaults
  color: red

- name: boot
  <<: *defaults
  color: black

- name: sandal
  size: 8
  <<: *defaults

We can convert it to JSON with YS:

$ ys -J shoes.yaml
[{"size":10, "color":"blue"},
 {"name":"sneaker", "color":"red", "size":10},
 {"name":"boot", "color":"black", "size":10},
 {"name":"sandal", "size":8, "color":"blue"}]

Here we define a mapping of default values with an anchor name of &defaults, and then we merge it into each of the other mappings using the merge key << and a value alias of *defaults.

This works out ok but it has a problem. Can you see it?

We've defined a sequence of 3 shoe mappings, but we have 4 things in the sequence. The defaults mapping itself is a (probably unwanted) part of the sequence.

The problem with this common scenario is that there is no way in YAML itself to declare the thing that is to be merged, but not have it be part of the result.

YS Variables to the Rescue🔗

There are so many things I could show you about YS using this example, but today I'll just use it to introduce you to YS variables. (Remember, I have at least 90 more posts to write this summer!)

Let's change the YAML file to use a variable to store the default values. Here's one way to do that:

!YS-v0

defaults =::
  size: 10
  color: blue

=>::
- name: sneaker
  <<:: defaults
  color: red

- name: boot
  <<:: defaults
  color: black

- name: sandal
  size: 8
  <<:: defaults

Let's load that and see what we get:

$ ys -J shoes2.yaml
[{"name":"sneaker", "color":"red", "size":10},
 {"name":"boot", "color":"black", "size":10},
 {"name":"sandal", "size":8, "color":"blue"}]

That's more like it!

YS Syntax Review🔗

Let's take a moment to review the YS syntax we used here.

Note

I'll probably say it a lot this summer, but I'll say it now:

YAML with YS is always 100% valid YAML. It literally has to be. That topic should be an interesting post.

Maybe mid-July...

  1. We start with !YS-v0 to indicate that we want this file to be able to use code features like variables.
  2. We define a variable called defaults with a value of our default values.
  3. We use :: instead of : when we need to switch from code mode to data mode (or vice versa). More on that in a future post.
  4. The :: after the merge key means that the value word defaults is a variable (not the string "defaults").
  5. We use the dummy key => to evaluate everything as a sequence rather than a mapping (because the YAML document was already a mapping due to the variable assignment).

See You Tomorrow!🔗

There is sooo much more that I could tell you about YAML and YS just in the context of this little example. But I'm going to pace myself and take it slow.

After all, it's Summertime. 😎

See ya tomorrow!

Comments