Skip to content

Extend Your YAML

If you want to use YS to get more out of your YAML files, this page is a good place to start.

We'll cover the most common ways to use YS in YAML files without diving into all the YS details first.

Turn On the YS!🔗

It's an extremely good chance that your YAML files are already valid YAML.

To find out, run a command like this:

$ ys -J your-file.yaml

If the output is your data converted to JSON, then you're good to go!

To turn on YS functional capabilities, just add a !YS v0: line to the top of your YAML file.

Try running that command again. The output should be exactly the same as before.

You've turned on YS but you haven't used it yet!

String Interpolation🔗

YS supports the interpolation (expansion) of variables and expressions in double-quoted and literal YAML scalars (strings).

First we need some variables to interpolate. We'll show how to define variables shortly, but for now we'll just use some of the global variables that are built into YS.

The ENV variable is a great place to start, because it contains a map of your current environment variables. For instance you can access your USER variable with ENV.USER. Also let's use the VERSION variable, which contains the current YS version.

Here's an example of string interpolation: 

!YS v0:
foo: bar   # Normal YAML data
greeting: |
  My name is $(ENV.USER).
  I'm using YS $VERSION!
bar: baz

Lets see load this file to YAML with the ys command: 

$ ys -Y file.yaml
foo: bar
greeting: |
  My name is $(ENV.USER).
  I'm using YS $VERSION!
bar: baz

Well that's not what we expected. No interpolation happened!

In order for the YS YAML loader to see a particular YAML node as YS code, we need to flip that node to code mode. YS makes this easy. Just change the : before that particuar node to ::.

!YS v0:
foo: bar   # Normal YAML data
greeting:: |
  My name is $(ENV.USER).
  I'm using YS $VERSION!
bar: baz

And now we get the expected output: 

$ ys -Y file.yaml
foo: bar
greeting: |
  My name is ingy.
  I'm using YS 0.1.91!
bar: baz

YS has 3 different ways to interpolate in strings:

  • Expand variables: "I am $name."
    • Put a $ in front of a variable name.
  • Expand expressions: "In reverse I'm $(name:reverse)."
    • Put a $() around an expression.
  • Separate variable from text: "${name}ami!"
    • Put a ${} around a variable name when it is followed by alphanumeric characters.