YAMLScript Advent 2023

by Ingy döt Net | | 4 min read

Seasons Greetings, my YAML friends!

What if I told you that you could write a program in YAML that would generate a Christmas tree?

Well, you can! Here's how:

#!/usr/bin/env ys-0

defn main(width=5):
tree: width

defn tree(width):
top =:
join "\n":
mapv \(line width, %1): width..1

trunk =: trunk(width) * 2

=>: "$top\n$trunk"

defn trunk(num):
spaces(num) + "*\n"

defn line(width, num):
# stars is a lexically defined function
stars =: \(inc(%1) * "*")

join "":
spaces: num
stars: (width - num) * 2

defn spaces(num): num * " "

Let's get a tree!

$ ys tree.ys

That's a pretty nice tree, but it's a little small. Let's make it bigger!

$ ys tree.ys 10

Welcome to the first day of YAMLScript Advent 2023! We're going to be writing a lot of YAMLScript this month, so let's get started…

Wait! What is YAMLScript?

YAMLScript is a new programming language that uses YAML as its syntax. You can do anything in YAMLScript that you can do in a language like Python or JavaScript such as:

  • Defining functions
  • Using variables
  • String manipulation and interpolation
  • Loops and conditionals
  • Importing modules
  • And more!

YAMLScript looks and feels like an imperative programming language, but it's actually a functional programming language. This means that YAMLScript programs are made up of expressions that are evaluated to produce a result.

But why would you even want to write a program in YAML?

YAMLScript is a full-featured, general purpose programming language, but it's also designed to be a great language for writing YAML configuration files. To that point, almost all YAML files are valid YAMLScript programs! And they evaluate to the same result that a YAML loader would produce.

For example, here's a YAML file that defines a list of fruits:

# fruits.yaml
- apple
- banana
- cherry

Let's run this file as a YAMLScript program:

$ ys fruits.yaml

Nothing happens!

But why would anything happen? The program doesn't do anything!

It's the same as running this Python program:

$ python -c '["apple", "banana", "cherry"]'

To evaluate a YAMLScript program, we need to use the --load option:

$ ys --load fruits.yaml
["apple", "banana", "cherry"]

We got some JSON back! That's because by default, --load evaluates the YAMLScript and prints the result as JSON.

What if we want to include these fruits in our YAML grocery list? Let's try it:

# grocery-list.yaml
- bread
- fruits: load("fruits.yaml")
- milk

Let's add the --yaml option to print the result as YAML:

$ ys --load grocery-list.yaml --yaml
- bread
- fruits: load("fruits.yaml")
- milk

That's not what we wanted! We wanted the contents of the fruits list to be included in the grocery list.

But if you think about it, this is exactly what we asked for. Since every YAML file is a valid YAMLScript program, it certainly should be loaded just like any other YAML loader would do it.

Let's fix this to do what we want:

# grocery-list.yaml
- bread
- fruits: ! load("fruits.yaml")
- milk

Now when we run it:

$ ys -l -Y grocery-list.yaml
- bread
- fruits:
- apple
- banana
- cherry
- milk

There we go! We got our fruits!

So what did we do here? We added 2 things:

  • A !yamlscript/v0/data tag at the top
  • A ! tag before the load function call

We won't get into the details of what these tags mean today, but you'll learn about them soon enough.

YAMLScript Advent 2023 Teasers

My name is Ingy döt Net. I'm one of the original creators of the YAML data language and I lead the YAML Language Development Team.

I've been working on YAMLScript for about a year now, and I'm excited to finally share it with you. I believe that YAMLScript is going to take YAML to exciting new places, while remedying many of its shortcomings, limitations and frustrations. I hope you'll come to agree as you join me on this holiday season unwrapping of the gift that is YAMLScript!

I also hope that you enjoyed this first day of the YAMLScript Advent 2023! I'll be posting a new blog article every day this month, so stay tuned! Well at least until December 25th, but I might keep going after that. :-)

Here's a sneak peek of some of the things to come:

  • Installing and using ys — the YAMLScript interpreter
  • The history of YAMLScript
  • How YAMLScript is compiled and evaluated
  • How YAMLScript can fix many of YAML's problems
  • How to use YAMLScript like a YAML loader in any programming language
  • Is YAMLScript actually a Lisp???
  • Refactoring complicated YAML configurations with YAMLScript
  • Writing polyglot libraries in YAMLScript
  • What makes a YAML file a valid (or invalid) YAMLScript program?
  • Compiling YAMLScript to native binaries and shared libraries

Hopefully you're as excited as I am to learn more about YAMLScript!

See you tomorrow!


Santa's little secrets...

In December 2023 YAMLScript is a work in progress.

This is not to say that it's a toy proof of concept. It has a working compiler, runtime and CLI. It has unit tests that must pass for every commit pushed to the main branch. It's well thought out and has a clear direction that I continually vet with a small group of talented and trusted people. It has regular releases.

But that in turn not to say that you should use it in production today. I encourage you to start playing with it, and I'm committed to backwards compatibility for stable releases. But we're not quite there yet. Caveat usor!

YAMLScript is evolving fast. While I'm writing these posts, I'm also writing the code for new features and fixing bugs as I go. I've had the Advent plan for over a month now, and I had planned to be further along before December 1st, but such are the time estimates of hackers.

I am attempting to make sure that the code examples in these posts are always using the implemented features, but sometimes I may fall a few hours behind. Often I need to write the examples using code patterns that actually work but are not the ones I preferred to best make a point.

As I fix bugs, implement features and tweak the language, I will update the posts accordingly. If you see something that bugs you, try taking another look after a few days. It probably bugged me too!

Be patient with me.

If I had to guess, I'd say that YAMLScript v0 will be have a stable release sometime before March 2024. I'll continue blogging the progress as I go, so it shouldn't be hard for you to decide when to start using YAMLScript for real.

Overall the whole thing is going extremely well, and I'm having a lot of fun. It's important to be transparent with you about where things are at.

Stick with me... This is going to be awesome!

— Ingy döt Net